4. FAQ & troubleshooting
Commands “don’t run” in a brand-new session
Section titled “Commands “don’t run” in a brand-new session”The harness draft screen turns composer text into the first message, not a command — so /chapters-status typed cold just messages the agent. Send any short opener first (or ask the agent to check status in prose) and the command surface works for the rest of the session. This is a client draft-routing behavior, not plugin state; it’s documented wherever commands appear.
/chapters-status says local-only — no credentials / no upstream linked
Section titled “/chapters-status says local-only — no credentials / no upstream linked”Correct, not broken. Before you link a pool, the archive is on disk and fully usable — open it, grep it, commit it; the model reads chapters by path with read, and chapters_search answers honestly (“no knowledge mirror yet”) until a link materializes its index. The status command reports the transport state and names the failed step precisely — Part III explains linking.
origin changed — rebuilding mirror
Section titled “origin changed — rebuilding mirror”You relinked to a different upstream. The mirror is transport, the store is truth: the plugin rebuilds from local state and republishes. This is the designed recovery, logged loudly with its reason.
Cache hit rate drops when many agents share one local model
Section titled “Cache hit rate drops when many agents share one local model”That is llama.cpp KV capacity, not dsh-chapters. On a single-slot server, interleaved sessions can only keep the shared prefix cached; divergent tails re-prefill. dsh-chapters’ own serial sessions warm to 99.7%+ (measured). Full writeup with numbers: §21 Cache behavior on llama.cpp.
I updated the plugin but nothing changed
Section titled “I updated the plugin but nothing changed”Restart dsh web — bundles load at boot (dsh plugin --profile web update … && restart). Same applies after an upgrade that changes cordis.patch.yml defaults.
A continuation said “over budget” and refused
Section titled “A continuation said “over budget” and refused”Budget is newly added context after the header; the plugin refuses with per-rule numbers and never silently truncates a handoff note (a clipped note is the lossy behavior the whole design rejects). Trim the note or raise continuationBudgetRatio (default 0.25) — §7.
My model never writes PLOT: lines, so checkpoints have no plot
Section titled “My model never writes PLOT: lines, so checkpoints have no plot”Fine — the plugin elicits one bounded call to author the plot over the region being condensed, and (since 0.1.3) logs why if it declines. Reason strings land in the diagnostics sink if you set DSH_CHAPTERS_ENGINE_ERRORS. This exact pipeline is a case study in §26 changelog and the field study.
How do I check what a chapter actually contains?
Section titled “How do I check what a chapter actually contains?”It is a file. cat .dsh-chapters/<root>/chapters/001-*.md. The archive is plain Markdown on purpose — no API, no format lock-in.
Where do credentials live?
Section titled “Where do credentials live?”Per-project, 0600, under the DSH home — never in the repo, never in a chapter, never in the corpus. See §27 security.