Repo review: python-conventions except sweep, MLX import gate, agent tool fix, honest size gate

[konjoinfinity]

Summary

Full-repo review hardening pass. Two parts:

1. Targeted correctness/constraint fixes (verified bugs + violations).
2. Repo-wide except Exception sweep — eliminates every non-boundary broad catch, which the project's own .claude/rules/python-conventions.md forbids ("No bare except: or except Exception: — catch specific exceptions; log and re-raise").

Final state: 2691 passed, 109 skipped (MLX/platform-gated), ruff check clean across squish/, zero non-boundary except Exception remaining.

Part 1 — correctness / constraint fixes

• MLX import gating — quant/int3_linear.py imported mlx.core/mlx.nn at module top level (violates "MLX must be gated, never imported on Linux paths"). Added the darwin/arm64 guard mirroring sqint2_linear.py; clear ImportError on Linux instead of a crash.
• Agent tool-dispatch bug — agent/tool_name_map.py mapped VSCode tool names to backend tools that were never registered (squish_list_directory/run_terminal/rename_file/create_directory), so those client calls silently failed. Remapped to the real tools, added a genuine squish_create_directory builtin, dropped the dead get_workspace_info entry, and added a regression test asserting every mapping resolves to a registered tool.
• Latent bugs surfaced by narrowing — _configure_blazing_mode called ChipDetector.detect() on the class (it's an instance method) → fixed to ChipDetector().detect().
• Perf quick win — serving/scheduler.py caches the 64-token prefix hash on _Request instead of recomputing it every batch-formation pass.
• Docs / CI-gate honesty — the 500-line file-size gate was continue-on-error (never blocked despite the docs). Now blocking for new files, with the 39 current oversized files grandfathered in .konjo/oversized-allowlist.txt. Fixed stale MODULES.md version (v9.34.1 → v9.34.2) and a dangling CLAUDE.md reference.

Part 2 — except Exception sweep (~278 sites, 37 files)

Each broad catch was narrowed to an explicit exception tuple matching what the guarded block can raise, bound as exc, and logged (_LOG.debug for expected/optional/probe/cleanup failures, _LOG.warning when functionality degrades). Control flow was preserved everywhere — same fallbacks, returns, re-raises.

12 genuine top-level boundaries were intentionally kept as logged catch-alls marked # noqa: BLE001, where narrowing would risk crashing a server/daemon/worker or breaking a must-degrade-gracefully contract: FastAPI/SSE stream consumers, the token-generation worker thread, the background preload thread, the daemon connection handler, two GPU worker run-loops, the memory-governor callback dispatch, the layer-overlap background worker, tool-registry tool execution, the python_repl sandbox exec(), the startup warm-up, the sparse-ffn mask loader, and the squishd chat-template fallback (arbitrary Jinja).

Module loggers were added where missing and existing ones reused (no duplicates). _fast_imports.py uses a lazy in-handler logger to avoid cold-start import overhead.

Deferred (planned, not in this PR)

• Perf: server.py hot-path string-join deferral, KV old-tier buffer pre-allocation, vectorized KITTY eviction, tokenizer-decode LUT — darwin-only MLX paths needing benchmarking on Apple Silicon.
• Architectural: system-prompt KV prefix caching, greedy speculative decoding, continuous batching / paged KV.
• Follow-ups: enable ruff BLE001 now that the tree is clean; MLC backend decision; catalog fetch retry/backoff.

🤖 Generated with Claude Code