(feat) hot-reload engine settings via settings.yaml + /acp config (phase 1; supersedes #76)

[ranxianglei]

What this PR does

Makes the engine's runtime configuration hot-editable, no restart required. The six scalar knobs — modelContextLimit, autoModelContextLimit, nudgeMinContextLimitPct, nudgeMaxContextLimitPct, nudgeEmergencyThresholdPct, autoNudge — can now be changed through the host's ~/.dsh/settings.yaml (namespace compaction-acp) and take effect on a running session. Adds a /acp config command (list / set / reset) and a settingsEnabled kill switch that reverts to the current composition-layer-only behavior. Full design: docs/settings-integration-design.md.

Why a new PR (supersedes #76)

PR #76 carried this exact feature work, but it was branched from an older commit. Since then, main shipped three changes that touch the very files this feature rewrites — #106 (output reservation), #103 (shadow-price meter heuristic), #124 (tool-pairing mirror) — which left #76 with conflicts that can no longer be auto-resolved. This branch is the same feature work with main merged in and every conflict resolved, so it is cleanly mergeable.

Merge notes (what was kept from each side)

• src/index.ts: keeps BOTH the settings seam and the output-reservation logic (fields, windowFor cap + live gate, and all three methods).
• src/window.ts: keeps the output-reservation probe.
• Shadow-price claim keeps the meter fixed-heuristic basis (issue [bug] 图片区间的压缩影子价误用路由重定价 node.tokens 而非 heuristicTokens → 宿主 token-meter 投影扣负（#54 残留通道） #103).
• The tool-pairing local mirror is preserved (issue [bug] dsh-compaction@0.1.2-rc.1 tool-pairing 缓存读取已删除的 session.events → 0.1.2 宿主上所有压缩必炸 (Cannot read properties of undefined (reading 'N')) #124).
• Docs (config tables, module map, doc index), package-lock.json, and the built dist/ are regenerated from the merged source.

Verification (all run on the merged branch)

• npm run typecheck: clean (tsc --noEmit, zero errors).
• npm test: 228/228 pass, 0 fail.
• dist/ rebuilt from merged source.

Supersedes #76.

[Tyan66666]

Merged main (through #93 + the dist-bot refresh) into this branch and adapted the settings seam to dsh-settings 0.1.5 — pushed as 9af0cab4 (a merge commit; its first parent is 95fca89, so this is a plain fast-forward).

1. Why the merge was needed, and what the seam adaptation touched

The branch was written against dsh-settings 0.1.0-rc.6, where the seam was two free functions: installSettingsSection(...) and settingsNamespace(). On the host line this PR targets, both are gone — installSection is now a SettingsProvider method that must be called inside a ctx.inject(['settings'], …) callback, and the namespace is a plain string literal ('compaction-acp'), not a branded runtime helper. Without the adaptation the plugin does not compile against the installed seam at all (error TS2305: Module '"@deepseek-ai/dsh-settings"' has no exported member 'installSettingsSection').

Adapted in this push: src/settings.ts (type-only import, plain-literal namespace, the String(descriptor.ns) === ACP_SETTINGS_NAMESPACE comparison), src/index.ts (one inject callback that captures the service and registers the section), package.json (peer >=0.1.5-alpha.1 <0.1.6-0 + devDep 0.1.5-rc.2), and tests/peer-range.test.ts (dsh-settings folded into the shared five-seam peer assertion). dist/ carries no changes — it is reset to origin/main, since the repo now rebuilds it after merge via .github/workflows/dist-bot.yml.

2. Four findings from a merge review, all fixed

• (blocker) The window projection gate read the composition snapshot, not the live value. windowFor tested this.config.autoModelContextLimit while the probe branch below it already used the live settings snapshot. Consequence: /acp config set autoModelContextLimit false cleared the window cache and printed success, but the very next windowFor still returned { source: 'projection' } — the knob's documented semantics were violated in both directions. Both gates now read the live source.
• The registered base layer was the resolved snapshot instead of the filtered composition subset. The seam registers entry verbatim (verified against the real 0.1.5 provider: descriptor.base === entry, no validation on register), so passing resolveAcpSettings(filterSettingsEntry(config)) made every untouched key look composed: /acp config list printed source: base for keys the operator never wrote, and reset named a composition value that does not exist. The filtered subset is now what gets registered; the resolved snapshot is used for reads only.
• Nothing restored state when the settings provider detached. The inject callback left this.settingsService and the source thunk pointing at the disposed provider, so /acp config kept reporting available: true and calling describe/update on a dead service while the engine silently froze at the last value. The callback now returns a disposer that clears both.
• Both reset paths called replaceSection unguarded and rewrote the whole section. A SettingsConflictError (or a schema rejection) escaped as a raw rejection instead of the friendly "run /acp config again" copy that set uses; and because the settings layer does not whitelist keys (publish of an unknown key reaches descriptor.user and update({ bogus: 1 }) is accepted — both verified), rebuilding the section from SETTING_KEYS would silently delete a hand-written entry. Both paths now share the set error mapping, and a single-key reset deletes only the target key while carrying the rest through verbatim. The write-back data always comes from the YAML file, never from this.config, so no object/function value can reach the layer.

3. Verification

• npm run typecheck — clean.
• npm test — 275/275 (was 270; +5 regression locks in tests/settings.test.ts, each asserting both the pre-fix and post-fix value, so every one of them goes red against the old code): the filtered base entry plus /acp config list sources, the seam→window gate, the kernelConfigFor output, provider-detach fallback through the inject disposer, and reset preserving hand-written keys.
• Docs in the same push (per the repo's "docs stay in sync" rule): AGENTS.md gains hard-won rule 17 (the three traps above), docs/settings-integration-design.md §4.6 documents the single-key-reset semantics and §6 lists the added locks.
• git diff origin/main -- dist is empty, so no dist conflict with the dist-bot.

This PR supersedes #76 (it carries the same feature plus /acp config); #76 can be closed once this lands.

[Tyan66666]

Merged origin/main into the branch so the PR is mergeable again (7237eac), then pushed.

Why it had gone stale — main moved on while this PR was open: c527104 (#118) added paging to /acp decompress, followed by the dist-bot commit baa8834.

Conflict resolution — one file, one hunk: src/commands.ts, inside the /acp usage string. Both sides had appended a clause to it, so both are kept:

/acp status | /acp compress <startSeq> <endSeq> <summary> | /acp decompress <blockId> [offset] [limit] | /acp config [list|set <key> <value>|reset <key>|all]

Everything else auto-merged: AGENTS.md, README.md, README.en.md, docs/INSTALL.md, src/tools.ts, tests/commands.test.ts. Both features survive the merge — the paged path still calls sliceDecompressPage(expanded, offset, limit, DEFAULT_DECOMPRESS_PAGE_CHARS, …) and rejects a bad offset with offset must be a non-negative integer, while this PR's /acp config path still runs configText(env, …) and maps SettingsConflictError through settingsWriteFailure in all three write paths.

dist — reset to origin/main's state. Under the current policy (AGENTS.md) a PR branch does not carry dist/; dist-bot rebuilds it after the merge.

Verification — npm run typecheck clean; npm test 280/280, i.e. main's pagination tests and this PR's settings tests passing together. Net diff vs main: 17 files, +1596/−57 (src/settings.ts 253 lines, tests/settings.test.ts 396, docs/settings-integration-design.md 539).

This PR supersedes #76, so #76 can be closed once it lands.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

Independently re-verified against the current head 7237eac (isolated worktree checked out at that sha, deps installed fresh from its lockfile). Everything checks out — no blockers found.

Build & tests (independent run)

• npm run typecheck → clean (exit 0)
• npm test → 280/280 pass, 0 fail (main's pagination tests + this PR's settings tests together, as you noted)
• npm ci → exit 0, so the newly added @deepseek-ai/dsh-settings + @deepseek-ai/schemastery peer/devDep closure resolves with no ERESOLVE cascade

Diff & dist (vs true current origin/main = baa8834)

• Net diff: 17 files, +1596/−57 — matches your number exactly (src/settings.ts 253, tests/settings.test.ts 396, docs/settings-integration-design.md 539)
• git diff origin/main -- dist → empty ✓ (dist correctly reset to main; dist-bot rebuilds post-merge)

The conflict you flagged — src/commands.ts:208 usage string keeps both clauses: /acp decompress <blockId> [offset] [limit] (main #118) and /acp config [list|set <key> <value>|reset <key>|all] (this PR). Both features survive the merge.

Seam adaptation (spot-checked in code)

• src/settings.ts: type-only import from @deepseek-ai/dsh-settings, plain-literal ACP_SETTINGS_NAMESPACE = 'compaction-acp', String(descriptor.ns) === ACP_SETTINGS_NAMESPACE — matches the 0.1.5 SettingsProvider.installSection shape.
• All three traps from rule 17 are handled: base layer registers the filtered compositionEntry (src/index.ts:289, src/index.ts:318); both window gates read the live readSettingsSource() (src/index.ts:509, :523, :538); the inject callback returns a disposer clearing settingsService + thunk (src/index.ts:337-338). Single-key reset deletes only the target key and carries the rest verbatim (src/commands.ts:295-309), with SettingsConflictError mapped through the shared handler in all three write paths (src/commands.ts:205).

Docs — synced: AGENTS.md rule 17 present; README zh/en gained the runtime-settings section + config-table rows (+ settingsEnabled); docs/settings-integration-design.md covers §4.6 (/acp config) and §6 (test plan).

One minor nit (non-blocking): docs/e2e-harness-design.md §「依赖钉」still describes the pinned closure as 0.1.0-rc.6 ("18 新增") and does not list the new dsh-settings seam. AGENTS.md §4 asks to re-derive/document the closure whenever a host package is added, so that section should be refreshed (add dsh-settings, correct the version line to the 0.1.5 line). Doesn't gate the merge — happy to sweep it in a small follow-up commit if you want.

Verdict: ready to merge. (Merges stay human-only, so I won't merge it myself.) Once it lands, #76 can be closed as superseded.

一句话中文：独立复验通过——typecheck 干净、280/280、git diff origin/main -- dist 为空、净 diff 17 文件与你所述完全吻合，seam 适配与四处修复都在代码里确认到位；唯一小瑕疵是 docs/e2e-harness-design.md 的依赖钉一节需补 dsh-settings/更到 0.1.5 线（非阻塞），可以合并。