fix: OpenCode config safety (#1585,#1586), policy-aware drift (#1596,#1598,#1599), verbatim turn budget (#1582), config/CLI/dispatch honesty (#1605,#1604,#1602)

[yvgude]

Six field-reported defects, each with regression tests. Branch is cut from github/main (5a90893092), so the diff is 16 files — not the whole lineage.

What was wrong

#1586 — an OpenCode config could be silently replaced by a lean-ctx-only scaffold.
Both writers (install_opencode_hook_with_mode and register_opencode_instructions) started from an empty object whenever parse_jsonc failed, wiping providers, models, plugins and foreign MCP entries — and the command still reported success. They now fail closed: an existing config that will not parse is left untouched and the reason is printed. parse_jsonc also tolerates a single leading UTF-8 BOM, which Windows editors emit routinely and serde_json rejects — that rejection was one of the ways a healthy config got read as "corrupt".

#1585 — OpenCode accepts both opencode.json and opencode.jsonc.
lean-ctx hardcoded one name per call site, so install, doctor, setup and uninstall could each target a different file than the user actually has. New core::opencode_config resolver (exactly one exists → that file; both → .json, flagged ambiguous; neither → .json for creation) is now the single source of truth for all of them. Uninstall visits both names so a lean-ctx entry is never orphaned in the file we did not install to.

#1596 — intentionally absent rules files were reported as drift.
A missing global rules file counted as unhealthy even when rules_injection = "off" or rules_scope = "project" made its absence deliberate. Claude Code's dedicated check already reasoned this way; check_rules_file_for_policy gives Cline, Cline CLI, Roo, Windsurf and the rest the same rule.

#1598 — Windows setup --fix loop.
The generated bash wrappers hold an MSYS path (/c/Users/Max/.cargo/bin/lean-ctx.exe) because that is what bash needs, while the expected binary is native (C:\Users\Max\…). Byte comparison called a correct wrapper stale and sent Windows users into a setup --fix loop that rewrote the file to a byte-identical result. same_windows_path compares the two spellings; anything not drive-qualified in one of those two forms returns false, so ordinary Unix paths are never conflated.

#1599 — rules_injection = "off" was only half honoured.
That setting is an opt-out from lean-ctx steering the agent. The initialize instructions field is the same steering block delivered over a different channel, so honouring the setting in the files while still shipping ~780 tokens of "ALWAYS use ctx_*, NEVER use native Read/Grep" on every session start made the setting look broken. Off is now off on every channel. The existing #1447 carve-out for Antigravity/Gemini CLI is unchanged.

#1582 — the documented recovery path out of compression did not work.
The turn budget (#1306) capped every response at 4096 tokens, including a read the caller explicitly asked to be verbatim. raw=true is exactly what the compression annotations and the server instructions name as the way back to the original bytes, so that path was silently unreachable for any file above ~16 KB.

Explicit verbatim requests (raw=true or mode="raw", on ctx_read and ctx_shell) now use a separate turn_fresh_limit_verbatim — default 32768, env LEAN_CTX_TURN_FRESH_LIMIT_VERBATIM, 0 = unlimited, and never below the ordinary limit so raising turn_fresh_limit can't make a raw read deliver less than a compressed one. Everyday modes keep the 4096-token backstop: exempting full, lines:, anchored and friends would switch the backstop off for most traffic, and their truncation banner already points at a working lines= recovery.

Measured, not asserted

235 KB / 6000-line markdown file, driven through the stdio server:

request	before	after
{mode:"raw", raw:true}	4052 tokens / 462 lines	32740 tokens / 3722 lines
{mode:"raw"}	4052 tokens	32740 tokens
{mode:"full"}	4052 tokens	4052 tokens (unchanged, banner intact)

Side note for the original report: a truncation banner is emitted on this build ([… truncated at ~N of M tokens — use ctx_read with lines= …]). The defect was the ceiling ignoring an explicit verbatim request, not a missing banner.

Verification

• cargo test --lib → 10508 passed, 0 failed, 22 ignored
• cargo clippy --lib --all-features → clean
• scripts/preflight.sh fast → 7/8. The one failure is git diff --check evaluated over the divergent merge-base (437132fa, 3466 pre-existing files from the other lineage); git diff --check on this branch's own changes is empty.

New tests: 6 in hooks::agents::opencode::config_preservation_tests, 9 in doctor::integrations::wiring::tests, 5 in core::opencode_config, 3 in core::config::logic::verbatim_budget_tests, 3 in server::call_tool::pipeline::savings_tests, 2 in core::jsonc::tests.

#1605 — config set llm.api_key reported a save it discarded

The [llm] schema block was hand-written with literal defaults instead of being derived from cfg.llm, and had drifted three ways: an api_key key no struct field backs (so set_by_key wrote it into the TOML table and the Config round-trip silently dropped it — after the CLI printed "Updated"), a model default of llama3.2 against the struct's qwen2.5-coder:1.5b, and a missing base_url. Defaults now come from cfg.llm.* like the neighbouring [decision_loop] block, api_key is gone (config set llm.api_key … fails with Unknown config key; the section description names OPENROUTER_API_KEY / ANTHROPIC_API_KEY), and llm_schema_keys_match_the_llm_config_struct guards the class so the next drift fails in CI instead of eating a secret. config-keys.md regenerated.

#1604 — ctx_call answered "path is required" about a parameter the caller supplied

The envelope parser accepted the inner arguments only under arguments (plus the #658 guard that turns an args/params/parameters/arg wrapper into a "did you mean arguments" hint). Agents also flatten the call — ctx_call(name="ctx_edit", path=…, old_string=…) — and that reached the inner tool with no arguments at all, so the inner tool complained about its own first required parameter. Probing a shipped 3.9.20 binary shows the signature: flattened ctx_glob → "pattern is required", flattened ctx_edit → "path is required" — the message follows whichever tool you name, which is what an argument-less forward looks like, not the registry-ordering bug the report suspected. name is the only key ctx_call reserves, so a flattened call is unambiguous and the rest is now forwarded; nested calls and the #658 hint are unchanged. With arguments arriving, an inner tool that genuinely isn't registered now reaches the existing Unknown tool: … + nearest-match path (#712), which is what the reporter asked for. ctx_call_forwards_flattened_inner_arguments pins all four shapes; it drives ctx_read deliberately, because that tool is on every built-in role's allowlist and so a sibling test leaving a non-default role in the global slot can't turn the assertions into [ROLE DENIED].

#1602 — lean-ctx watch was still advertised after its removal

The TUI went with the dead-module cleanup in 3.9.20 (de96cc5), but --help, the completion spec and watch --help all still described it as a working command, while bare watch exited 1 with "The live TUI dashboard has been removed." and named no replacement. All four surfaces now carry the same notice and point at lean-ctx dashboard (web UI, same event stream), lean-ctx cep (metrics as text) and lean-ctx index watch (the index watcher). watch --help → stdout, exit 0; bare watch → stderr, exit 1. The completion entry is hidden rather than deleted, with a "Removed — see lean-ctx dashboard" description. Guarded by full_help_does_not_advertise_the_removed_tui_dashboard and removed_watch_command_is_not_advertised.

Fixes #1582
Fixes #1585
Fixes #1586
Fixes #1596
Fixes #1598
Fixes #1599
Fixes #1602
Fixes #1604
Fixes #1605

🤖 Generated with Claude Code