@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.21

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright 2026 Fractal Synapse Labs
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# dsh-chapters
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Long memory for local AI: a [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+plugin that archives agent conversations as verbatim chapters, continues sessions from a Table of
+Contents at zero inference-token cost, and turns that archive into a shared, searchable knowledge
+pool.** Published on npm as [`@fractalsynapse/dsh-chapters`](https://www.npmjs.com/package/@fractalsynapse/dsh-chapters);
+source at [fractalsynapse/dsh-chapters](https://github.com/fractalsynapse/dsh-chapters).
+
+> **All documentation lives on the documentation site — this README is a doorway, not a duplicate.**
+> ### 📖 https://fractalsynapse.github.io/dsh-chapters/
+
+## Install (the whole setup)
+
+```bash
+dsh plugin --profile web add @fractalsynapse/dsh-chapters      # install into your harness profile
+dsh plugin --profile web update @fractalsynapse/dsh-chapters   # keep current — restart `dsh web` after
+```
+
+`--profile <name>` is required on every `dsh plugin` command (`web` = the browser harness profile).
+After restart you have the fork button, seven agent tools, twelve `/chapters-*` commands (through
+`0.2.17`, including `/chapters-remove`) — and the optional `chapters` preset that routes `/compact`
+through the zero-token engine.
+
+## Find the right page for your question
+
+| You want to… | Go to |
+|---|---|
+| understand what this is / why (the ten benefits) | [Home → “What it gives you”](https://fractalsynapse.github.io/dsh-chapters/) |
+| install, upgrade, uninstall, verify provenance | [§23 Install, upgrade, provenance](https://fractalsynapse.github.io/dsh-chapters/operations/install/) |
+| run your first compaction/continuation | [§1 Quickstart](https://fractalsynapse.github.io/dsh-chapters/start/quickstart/) → [§2 Your first continuation](https://fractalsynapse.github.io/dsh-chapters/start/first-continuation/) |
+| link a shared knowledge pool (git or TreeDX) | [§3 Link a knowledge pool](https://fractalsynapse.github.io/dsh-chapters/start/link-pool/) · [§10 The pool](https://fractalsynapse.github.io/dsh-chapters/knowledge/pool/) |
+| run any command — exact syntax, scope, outputs | [§15 Commands](https://fractalsynapse.github.io/dsh-chapters/reference/commands/) |
+| delete a bad chapter (the wrong-project prompt) | [§15 Commands → `/chapters-remove`](https://fractalsynapse.github.io/dsh-chapters/reference/commands/#chapters-remove--delete-a-bad-chapter-for-real) |
+| know what the agent-facing tools do | [§16 Agent tools](https://fractalsynapse.github.io/dsh-chapters/reference/tools/) |
+| tune a threshold, budget, or trigger | [§17 Configuration](https://fractalsynapse.github.io/dsh-chapters/reference/configuration/) |
+| understand *why not summaries* / the economics | [§5 Why not summaries?](https://fractalsynapse.github.io/dsh-chapters/concepts/why-not-summaries/) |
+| read the design rules the system won't break | [§6 The four invariants](https://fractalsynapse.github.io/dsh-chapters/concepts/invariants/) |
+| the theory behind retrieval-over-compression (RLM) | [§8 Recursive context theory](https://fractalsynapse.github.io/dsh-chapters/concepts/recursive-context/) |
+| propose/approve rules for agents | [§13 Rules & governance](https://fractalsynapse.github.io/dsh-chapters/knowledge/rules/) |
+| let a second model propose your next prompt | [§28 Prompt recommendations](https://fractalsynapse.github.io/dsh-chapters/concepts/prompt-recommendations/) |
+| debug something (“seems broken, is it?”) | [§4 FAQ & troubleshooting](https://fractalsynapse.github.io/dsh-chapters/start/faq/) |
+| prompt-cache / llama.cpp behavior | [§21 Cache behavior on llama.cpp](https://fractalsynapse.github.io/dsh-chapters/evidence/llamacpp-cache/) |
+| see measured results (production run + benchmarks) | [§19 Benchmarks](https://fractalsynapse.github.io/dsh-chapters/evidence/benchmarks/) · [§20 Field study](https://fractalsynapse.github.io/dsh-chapters/evidence/field-study/) |
+| compare with other memory approaches | [§22 The alternatives, compared](https://fractalsynapse.github.io/dsh-chapters/evidence/comparison/) |
+| check security/privacy boundaries | [§27 Security & privacy](https://fractalsynapse.github.io/dsh-chapters/operations/security/) |
+| release history & known-fixed incidents | [§26 Changelog](https://fractalsynapse.github.io/dsh-chapters/operations/changelog/) |
+| **develop the plugin itself** | [§24 Developing](https://fractalsynapse.github.io/dsh-chapters/operations/development/) → the engineering specs below |
+
+## Developing / contributing
+
+Three ways to set up a development environment — pick whichever fits your workflow:
+
+| Mode | Best for | Command |
+|------|----------|---------|
+| **Centralized** (your live profile) | Day-to-day development on your main machine | `./dev/install/install.sh && dsh web` |
+| **Compartmentalized** (isolated DSH_HOME) | Testing changes without touching your live sessions | `DSH_HOME=/tmp/dsh-dev ./dev/install/install.sh` |
+| **Containerized** (full stack) | Isolated platform with vLLM + Playwright + Chromium | `cd dev/install && docker compose up -d` |
+
+All three install the same plugin set: dsh-chapters, [dsh-codegraph](https://github.com/jiangzhenguo/dsh-codegraph)
+(structural code search via pre-indexed AST graph), and dsh-tinyfish-search. Full details in
+[`dev/install/README.md`](dev/install/README.md). The containerized stack additionally ships its own
+vLLM model server (Qwen3-4B-AWQ with inference + systemone endpoints), a DSH Web UI service, and a
+CI-capable test runner — everything runs locally with no external API keys required.
+
+The site's Part VI covers the daily loop; the repository itself holds the engineering truth for agents:
+
+- **[`AGENTS.md`](AGENTS.md)** — working spec for AI agents developing this repo (invariants, budget, hard rules)
+- **[`docs/`](docs/)** — deep specs: `contract.md` (host API facts), `architecture.md` (mechanics), `development.md` (build/test loop + tape system), `verify.md` (every claim's procedure), `knowledge-repo.md` (design record), `host-compaction-seam.md`, `provider.md`
+- **[`dev/install/`](dev/install/)** — installer, containerized platform, and local-llm skill
+- **benchmarks**: `npm run bench` — three arms, local model, never CI ([protocol](benchmarks/README.md))
+
+Feature requests and bugs: [open an issue](https://github.com/fractalsynapse/dsh-chapters/issues) —
+measured reports get measured answers.
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE). Your conversations, chapters, and knowledge pools stay yours.

package/cordis.patch.yml

@@ -0,0 +1,363 @@
+# dsh-chapters bundle patch — ACTIVE: package.json declares this file as the
+# plugin's composition patch, applied when a profile adds the plugin. The YAML
+# below the comment block is functional; everything in this comment is the
+# complete configuration reference (kept in sync with src/index.ts and
+# src/engine.ts — verified 2026-10-01 against both schemas, including the
+# 2026-09-21 transport keys). The site's §17 (Configuration) is the readable
+# authority; this header mirrors it.
+# Scratch-profile install: DSH_HOME=$PWD/.dshdev dsh plugin --profile web add "link:$(pwd)"
+#
+# Two planes, two surfaces:
+#   HOST PLANE  — the `config:` block below (defaults shown commented; set any
+#                 under your profile's plugin entry).
+#   REALM PLANE — the compaction ENGINE row inside the preset's composition (the
+#                 `preset-chapters` row at the foot of this file); shared names behave per
+#                 plane. Design record: docs/knowledge-repo.md §12.
+#
+# PRESET DELIVERY — the preset is a DECLARATION ROW, exactly like the host's own presets.
+#   `preset-chapters` (the id is the host convention `preset-<id>`) is inserted by this
+#   file, its `config` IS the preset definition (`id/name/description/order/plugins`), and
+#   because it is an ordinary Loader entry you can see it in the plugin list and the config
+#   editor, override it from your profile patch, or `disabled: true` it.
+#     Its row module is ours — '@fractalsynapse/dsh-chapters/preset' (src/preset.ts) — not the
+#   host's '@deepseek-ai/dsh-agent-preset'. It mirrors that plugin line for line (injects
+#   `agentPresets`, preserves child `!!js` expressions, yields the registry disposer to
+#   Cordis) and adds one thing: rows this host cannot import are dropped at boot and NAMED,
+#   because a single unresolvable child row makes the WHOLE preset `broken` — which is the
+#   same user-visible failure as no preset at all (measured: `DECLARED BUT BROKEN —
+#   tool-schedule … never started` on a host where that package was never published). The
+#   host package cannot be named directly because a row that fails to import aborts the
+#   plugin tree of any host predating declaration rows; ours resolves everywhere our
+#   package runs. Support floor: 0.2.0.
+#     After activation the plugin then ASKS THE ROSTER, and the mounted rows: file presence
+#   is not preset existence, and "declared" is not "usable". The `dsh-chapters:` lines at
+#   startup say which of the four states you are in.
+#
+# config:
+#   # ---- identity -------------------------------------------------------
+#   installChaptersPreset: true    # INERT since 0.1.18 — the preset is the `preset-chapters`
+#                                  # row above, so `disabled: true` on THAT row is the switch.
+#                                  # Kept so an existing profile patch still parses.
+#   compactionThresholdRatio: 0.9  # INERT since 0.1.18 for the same reason: it is
+#                                  # `thresholdRatio` on the preset's chapters-engine row now.
+#   #   fallbackPreset: 'chapters'     # preset mounted for children when the
+#                                  # caller's own preset cannot be resolved — and
+#                                  # the id the roster check looks for. This id is
+#                                  # DURABLE STATE: every child's log records it,
+#                                  # so renaming it orphans those sessions.
+#   harnessId: '<hostname>'        # per-machine identity: git commit author,
+#                                  # token scoping, edits/<harness>/ curation
+#                                  # partition, rule-approval authorship
+#
+#   # ---- stores ---------------------------------------------------------
+#   artifactStoreRoot: '.dsh-chapters'  # workspace store: chapters, artifacts,
+#                                       # rules; must be reachable by `read`
+#
+#   # ---- chapters & composition ----------------------------------------
+#   chapterTokenTarget: 8000       # soft per-chapter size target
+#   chapterLimit: 8000             # hard split threshold
+#   warningsDisplayCap: 6            # how many warning TEXTS a door prints before '…and M more' (#61).
+#                                  #   The field failure was delivery: 86 warnings — naming a hollow
+#                                  #   chapter and an unarchived 0-4082 hole — reached a human as
+#                                  #   '(86 warning(s))'. A count is not a message.
+#   segmentCandidateCapTokens: 4000 # ceiling on chapters_segment's oversized-result candidate list (#61):
+#                                  #   it emitted 49,932 chars while reporting 'Omitted 275266 bytes',
+#                                  #   ~81K est tokens into a 32K window. Ranked by size DESC, so the cap
+#                                  #   removes the small stuff, and the response names what was withheld.
+#   diagnosticsLog: ''             # where door/child failures are appended (#61). Empty ⇒ the FIRST door
+#                                  #   that touches a project resolves <store-root>/diagnostics.log;
+#                                  #   DSH_CHAPTERS_ENGINE_ERRORS overrides it; the literal 'off' is the
+#                                  #   only silence. Before this, unset meant NO TRACE ON DISK — the three
+#                                  #   SAIP compaction finalization failures left none.
+#   childAutoArchive: true           # the seventh archive moment (#61): a ch-* continuation child is not a
+#                                  #   subagent, so door 5 never sees it. `ch-dc3be3ab` reached 2,363
+#                                  #   events and 3 completed turns with chapters: [] — nothing failed,
+#                                  #   NO MOMENT WAS WATCHING. Set false to close this door.
+#   childAutoArchiveMinTurns: 4    # after the first archive, how many unarchived completed turns re-arm it
+#                                  #   (the first archive always fires: never-archived is the defect).
+#   chapterOversizeFactor: 2       # hard oversize multiple of chapterTokenTarget (#59): over the
+#                                  #   TARGET warns ("split at the next boundary, never clip"), over
+#                                  #   target × factor every door REFUSES with its numbers before
+#                                  #   reserving one. The field shipped an 89,982-token chapter and a
+#                                  #   237,870-token orphan against an 8K target; a chapter nobody can
+#                                  #   re-read is not an archive. 0/unset behaviour = warn only.
+#   mergeThreshold: 0.3            # τ for merging turns into one chapter at
+#                                  # archive time. Composition is archive-time
+#                                  # only: tune for future archives.
+#   subagentAutoSave: true         # archive a subagent's completed turns into
+#                                  # searchable chapters when its run settles
+#                                  # (save-only: no session, no compaction;
+#                                  # enrichment queued, never per-child).
+#                                  # false = listener never registers.
+#
+#   # ---- context economy -------------------------------------------------
+#   toolResultDeferFloorTokens: 200        # archive-time inline floor
+#   continuationBudgetRatio: 0.25          # notice+note allowance as share of
+#                                          # the window REMAINING AFTER the
+#                                          # header — never of the whole window.
+#                                          # Over budget = refuse with numbers.
+#   searchDefaultMaxTokens: 400            # chapters_search pack size
+#
+#   # ---- knowledge sync --------------------------------------------------
+#   knowledgeRemote: ''            # repo URL; '' = link via /chapters-link
+#                                  # (view | <path> | <url> <token>)
+#   projectKeyOverride: ''         # wins over the remote-derived project key
+#   syncDebounceMs: 30000          # coalesce window for post-archive pushes
+#
+#   # ---- P2 enrichment ---------------------------------------------------
+#   # The host plane is the COMMAND SURFACE (manual drains only); the realm
+#   # engine row owns the auto triggers — enrichmentTrigger exists on the row.
+#   enrichmentEnabled: true        # kill switch: false = pure no-op everywhere,
+#                                  # corpus stays fully working (deterministic)
+#   enrichmentModel: ''            # 'provider/model'; '' = conversation route.
+#                                  # /chapters-enrich model <x|clear> overrides
+#   enrichmentIdleMs: 60000        # idle trigger silence window (row value)
+#   enrichmentBatchCap: 5          # chapters per drain
+#
+#   # ---- P2 vocabulary -----------------------------------------------------
+#   vocabApply: false              # SHADOW by default: candidates are reported
+#                                  # in every sync status, nothing written;
+#                                  # true = git-visible topic-alias curation
+#   vocabCoMin: 3                  # co-occurrences across chapters to trust
+#   vocabOverlapMin: 0.5           # label token-set Jaccard threshold
+#
+#   # ---- P3 rules ----------------------------------------------------------
+#   coreRulesBudgetTokens: 1200    # cap on the notice's CORE RULES block;
+#                                  # overflow refuses with per-rule numbers —
+#                                  # the notice NEVER clips
+#   rulesCoreBonus: 0.15           # rank bonus for rules effective-core on
+#                                  # THIS machine (approval = per-machine
+#                                  # curation fact, record §15)
+#
+#   # ---- prompt recommendations (#71, site §28) ----------------------------
+#   promptModel: ''                # the model that DEFINES the next work.
+#                                  # '' ⇒ the feature does not exist (zero calls,
+#                                  # zero surface); setting one IS the enable.
+#                                  # Runtime: /chapters-prompt model <p/m|clear>
+#   promptContextChars: 4000       # hard budget on the assembled input slice
+#                                  # (chapter summaries + screened live tail)
+#   promptMaxChars: 240            # cap on the recommendation; over-cap ⇒ retry
+#                                  # once ⇒ refuse with numbers, never truncate
+#
+#   # ---- transport (2026-09-21 provider-seam amendment) -------------------
+#   knowledgeProvider: 'auto'      # 'auto' | 'git' | 'treedx'; 'auto' dispatches
+#                                  # on the remote scheme (treedx+ → TreeDX),
+#                                  # an explicit value must match the scheme or
+#                                  # the link refuses — never a silent fallback
+#   treedxFetchTimeoutMs: 15000    # TreeDX HTTP timeout per call
+#   treedxWorkspaceTtlSeconds: 900 # TreeDX workspace lease TTL
+#   treedxLeaseRetries: 3          # pull-retry budget when the lease is held
+#   treedxLeaseRetryDelayMs: 1000  # delay between lease retries
+#
+# Realm-row-only keys (in the preset's engine row, not this patch):
+#   harnessId, sessionRulesEnabled, rulesMarkerPrefix, coreRulesBudgetTokens,
+#   enrichmentMaxTokens (4000 — one auxiliary completion budget; sized to cover
+#   reasoning tokens, since the measured route reports reasoning inside completion usage
+#   and does not enforce max_tokens)
+#   rulesEnrichment (true — the ladder mines standing orders),
+#   rulesMinedPerChapter (3), rulesAutoActivate (true — mined inferences govern on
+#   arrival; false holds them for approve), rulesModel ('' — or a dedicated
+#   'provider/model' for mining, one extra bounded call per chapter),
+#   projectRulesDisplayCap, sessionRulesDisplayCap, rulesRelevance  (#50 §7/§7.5 —
+#   the realm plane owns what an in-place checkpoint renders; the host plugin config
+#   owns what a continuation notice renders; same names, same defaults, set both to
+#   diverge from the default)
+#   thresholdRatio, retainRatio, retainTokens, maxTokens, compactionRetries,
+#   maxOverflowRetries, auto, summarizationProvider/summarizationModel (legacy
+#   override), enrichmentTrigger (afterPush|idle|both|manual),
+#   elicitedPlot (true — one bounded call to mint a missing PLOT note),
+#   toolResultArtifactTokens (8000 — arrival-stub floor; keep ABOVE your chunk
+#   size: a floor below it stubs chunks and compaction silently stops being
+#   needed, measured), plus shared names above honored per plane.
+# ---------------------------------------------------------------------------
+
+- insert:
+    - id: '@fractalsynapse/dsh-chapters'
+      name: '@fractalsynapse/dsh-chapters'
+
+# ── the `chapters` agent preset — a DECLARATION ROW, exactly as @deepseek-ai/dsh-web-app
+#    ships its own presets/standard.patch.yml. Row id `preset-chapters` follows the host's
+#    `preset-<id>` convention; `config.id: chapters` is DURABLE STATE (every continuation
+#    child records it as `agent-preset/selected`, so renaming it orphans those sessions).
+#
+#    The row's `name` is OUR plugin (`@fractalsynapse/dsh-chapters/preset`), which mirrors
+#    @deepseek-ai/dsh-agent-preset line for line — `inject: ['agentPresets']`,
+#    `static [EntryGroup.key] = true` so child `!!js` expressions survive until the child
+#    activates, `[Service.init]` yields the registry disposer so Cordis owns its lifetime —
+#    and drops rows THIS host cannot import before registering. Why not the host package
+#    directly: a row naming @deepseek-ai/dsh-agent-preset is unresolvable on a pre-0.1.7
+#    host and an unresolvable row aborts that host's whole plugin tree, while one stale
+#    child row (e.g. @deepseek-ai/dsh-tool-schedule, unpublished at 0.2.0-rc.2) makes the
+#    ENTIRE preset `broken` — measured both ways. Same row, same visibility in
+#    `dsh --dump-default-config`/the config editor, no boot that it can brick.
+#
+#    Four deltas from the host's own standard list, each ours deliberately:
+#      1. compaction-basic -> chapters-engine (the zero-inference summarize())
+#      2. tool-result-pruner.thresholdChars 8192 -> 1000000 (dormant by choice: chapters
+#         defer oversized results at ARCHIVE time; an in-surface prune is a prefix cliff
+#         on local hardware — and that plugin REJECTS unknown config keys, so the three
+#         keys below are the whole surface)
+#      3. the PLOT: persona suffix, with NO {{cwd}} (hosts from 0.2.1-alpha.2 register only
+#         provider/model and an unregistered variable throws at prompt assembly, killing
+#         every turn of every chapters session)
+#      4. tool-ralph ENABLED (the host standard list mounts it disabled)
+#    `noUnusedLocals`-equivalent discipline applies: keys the host dropped between versions
+#    are not carried here (toolFilter was one — alpha.4 throws on it).
+- insert:
+    - id: preset-chapters
+      name: '@fractalsynapse/dsh-chapters/preset'
+      config:
+        id: chapters
+        name: Chapters
+        description: Full coding agent; context relief via zero-inference chapter compaction.
+        order: 0
+        plugins:
+          - id: persona
+            name: '@deepseek-ai/dsh-persona'
+            config:
+              prefix: You are a coding agent powered by the {{model}} model.
+              suffix: "When a task spans multiple turns, end each reply with one line beginning 'PLOT:' (max 60 words — objective, current hypothesis, immediate next step). A checkpoint carries this plot forward; if it looks stale, revise it on your next plot line.\n\n## Chapters memory and rules\nThis session keeps an archive of its own history, and a rule tier on top of it.\nBefore starting a task, run `chapters_rules` with the task description: it returns the standing orders in force here — project rules your team approved, plus session rules captured from this conversation, including ones nobody spelled out (each says which). Name the rules you actually followed, or say none; a rule cited wrongly twice is one the human revokes with a single command.\nWhen you need earlier work, a past decision, or bug history, run `chapters_search` FIRST — before re-reading files or asking the human. Read a cited chapter for the exact bytes; `chapters_artifact` holds the oversized tool outputs.\nDelegated subagents are covered by the same rules and the same archive: a child inherits the orders of the session that delegated it, so query them rather than assuming a fresh start."
+
+          - id: agent-instructions
+            name: '@deepseek-ai/dsh-agent-instructions'
+            config:
+              maxBytes: 65536
+          - id: time-context
+            name: '@deepseek-ai/dsh-time-context'
+          - id: tool-bash
+            name: '@deepseek-ai/dsh-tool-bash'
+            disabled: !!js process.platform === 'win32'
+          - id: tool-pwsh
+            name: '@deepseek-ai/dsh-tool-pwsh'
+            disabled: !!js process.platform !== 'win32'
+          - id: tool-fs
+            name: '@deepseek-ai/dsh-tool-fs'
+          - id: tool-fs-search
+            name: '@deepseek-ai/dsh-tool-fs-search'
+            config:
+              sampleOverCapGlobResults: false
+          - id: tool-jobs
+            name: '@deepseek-ai/dsh-tool-jobs'
+          - id: tool-schedule
+            name: '@deepseek-ai/dsh-tool-schedule'
+          - id: skill-filesystem
+            name: '@deepseek-ai/dsh-skill-filesystem'
+          - id: tool-skill
+            name: '@deepseek-ai/dsh-tool-skill'
+          - id: command-goal
+            name: '@deepseek-ai/dsh-command-goal'
+          - id: tool-goal
+            name: '@deepseek-ai/dsh-tool-goal'
+          - id: planning
+            name: cordis:group
+            group: true
+            isolate:
+              planMode: true
+            config:
+              - id: plan-mode
+                name: '@deepseek-ai/dsh-plan-mode'
+                config:
+                  section: |
+                    You are in plan mode. Stay in plan mode until exit_plan_mode succeeds or the user switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+                    Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+                    The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed to keep the tool catalog unchanged. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+                    Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+                    Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+                    When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+          - id: compaction
+            name: cordis:group
+            group: true
+            isolate:
+              compaction: true
+              toolResultPruner: true
+            config:
+              - id: chapters-engine
+                name: '@fractalsynapse/dsh-chapters/engine'
+                config:
+                  thresholdRatio: 0.9
+                  # #140: bound the base engine's pressure headroom. Its default (65,536) is a reservation for a routed
+                  # summarize call; this engine's summarize() is deterministic and routes nothing, so on any window under
+                  # 65,536 — 32K is the target hardware — the default makes `contextWindow − reserved − headroom`
+                  # negative and the base THROWS instead of compacting (see docs/backlog.md, #140). 8,192 leaves a
+                  # positive pressure budget at 32K and is inert at 128K, where the ratio still sets the trigger
+                  # (min(window × 0.9, window − 8,192): 115.2K vs 119.8K, so large windows keep the same boundary).
+                  headroomTokens: 8192
+              - id: command-compact
+                name: '@deepseek-ai/dsh-command-compact'
+              - id: tool-result-pruner
+                name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+                config:
+                  thresholdChars: 1000000
+                  headChars: 4096
+                  tailChars: 1024
+          - id: delegation
+            name: cordis:group
+            group: true
+            isolate:
+              workflowEngine: true
+            config:
+              - id: tool-subagent-control
+                name: '@deepseek-ai/dsh-tool-subagent-control'
+              - id: tool-subagent-list-agents
+                name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+              - id: tool-subagent
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: spawn
+                  toolName: subagent
+                  modelSelectionSettings: true
+                  backgroundMode: continuable
+              - id: tool-subagent-fork
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: fork
+                  toolName: subagent_fork
+                  backgroundMode: continuable
+              - id: tool-subagent-codex
+                name: '@deepseek-ai/dsh-tool-subagent'
+                disabled: true
+                config:
+                  provider: codex
+                  toolName: subagent_codex
+                  backgroundMode: one-shot
+                  maxDepth: provider-managed
+              - id: tool-subagent-claude-code
+                name: '@deepseek-ai/dsh-tool-subagent'
+                disabled: true
+                config:
+                  provider: claude-code
+                  toolName: subagent_claude_code
+                  backgroundMode: one-shot
+                  maxDepth: provider-managed
+              - id: workflow-ptc
+                name: '@deepseek-ai/dsh-workflow-ptc'
+                config:
+                  provider: spawn
+              - id: tool-workflow
+                name: '@deepseek-ai/dsh-tool-workflow'
+              - id: tool-ralph
+                name: '@deepseek-ai/dsh-tool-ralph'
+                config:
+                  subagentProvider: spawn
+                  maxRounds: 64
+          - id: tool-ask-user
+            name: '@deepseek-ai/dsh-tool-ask-user'
+          - id: tool-todo
+            name: '@deepseek-ai/dsh-tool-todo'
+            config:
+              allowParallelInProgress: true
+          - id: tool-web
+            name: '@deepseek-ai/dsh-tool-web'
+            config:
+              fetch: true
+              searchTimeoutMs: 60000
+          - id: present
+            name: '@deepseek-ai/dsh-tool-present'
+          - id: tool-plugin-manager
+            name: '@deepseek-ai/dsh-plugin-manager/tools'
+            disabled: true