better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch12-persistence-catalog.md

@@ -0,0 +1,109 @@
+# Chapter 12: Persistence Catalog
+
+## Core Idea
+Session persistence is one **durable, replayable, append-only event log**: every record is a `SessionEvent` envelope (`type`, monotonic `seq`, epoch-ms `time`, `data`, optional `ignorable`, conditional `surfaceOp`/`sourceEventSeqs`). This catalog documents the *event vocabulary* (`SessionEventMap`) and the surface/log-only split — it does NOT document on-disk store layout, DSH_HOME anatomy, or durability mechanics (those live in `subsystems/persistence.md`, the doc's own cross-ref target). A log event is **not a Cordis event**: it reaches listeners through the single `session/event` emit.
+
+## Frameworks Introduced
+- **`SessionEventMap` (merge-extensible vocabulary)**: the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge into `@deepseek-ai/dsh-session/types`; a downstream plugin can merge further current-version event types (outside this catalog by construction, requiring explicit disposition at a later format edge).
+  - When to use: declaring a new durable event type. How: merge the key into `SessionEventMap`; surface types also join `SurfaceEventType`.
+- **Surface vs log-only split**: `SurfaceEventType` = `'user/message' | 'assistant/message' | 'tool/result'` — the only types that produce LLM messages and may carry `SurfaceOp`. Everything else is **log-only**: durable + replayable, zero derived-history contribution.
+  - When to use: a type enters the model transcript only if it is a surface type; audit/boundary/state records stay log-only.
+- **`SurfaceOp` join rule**: `'append'` (tail) or `{ op:'replace', start, end }` (replaces surface nodes start..end; node's `sourceEventSeqs` must include every shadowed node). Used by compaction; any surface-replacing producer may use it.
+- **`ignorable` marker protocol**: absent = **required** — a reader meeting an unrecognized type without `true` MUST refuse reconstruction (not silently drop), because a required event may change how the rest of the log interprets. A writer sets `true` only on purely informational records whose loss cannot affect reconstruction.
+- **Shadow-price protocol (compaction)**: a surface `replace` event is priced by the metering event *immediately before* it (`compaction/summary` for a summarizing compaction, `compaction/prune` for a model-free prune), stating `shadowedRange`/`shadowedSeqs`/`shadowedTokenCount` — so a pure consumer can subtract the exact replaced range without retaining per-node prices.
+- **Version lifecycle**: current writers stamp `SESSION_FORMAT_VERSION`; supported historical artifacts reach the current vocabulary through the build-static adjacent migration catalog (see `subsystems/persistence.md`).
+- **JSON-serializability gate**: every payload is JSON-serializable, enforced at `Session.append` via `isJsonValue` — a non-serializable `meta` is rejected at the source, so replay reproduces the identical record.
+
+## Key Concepts
+- **SessionEvent**: discriminated union over `type` (so `switch (event.type)` narrows `event.data` without casts); envelope = `{ type, seq, time, data, ignorable?, sourceEventSeqs?, surfaceOp? }`.
+- **SurfaceEventType**: the 3 message-producing types; only these may carry `SurfaceOp`; user/tool may cite `sourceEventSeqs`.
+- **log-only**: durable, replayable, no `surfaceOp`, never in derived history (`deriveMessages()` ignores it).
+- **session/end-seed**: durable projection of `Session.firstLiveSeq`; events before it (smaller seq) came from seed (resume/fork/replay). A fresh fork child owns one `{ inherited: true }` marker at its exact inherited-prefix cut; the last tagged marker is the current Session's cut.
+- **session/event emit**: the single bus wiring — the log is not Cordis events; listeners hear via this one emit.
+- **deriveMessages() projection**: the surface ordering → LLM messages (see `subsystems/session.md`).
+- **Latest-wins fold events**: whole-value, non-surface state knobs whose LAST event is the session override — `plan/mode`, `sandbox/mode`, `approval/policy`, `session/title`, `todo/write`, `permission/preset`, `model/selection`.
+
+## Mental Models
+- Think of the **log as ground truth, the surface as derived history**: only `user/message`/`assistant/message`/`tool/result` join the model transcript; everything else is replayable audit.
+- Think of **compaction as a surface `replace` + an adjacent metering event**: the replacement is priced by the event directly before it, never by per-node bookkeeping.
+- Use **`ignorable: true` sparingly**: defaulting to *required* means a forgotten marker over-refuses (inconvenience) rather than silently resuming a gutted session.
+- Treat **state knobs as latest-wins**: the projection unit folds the log to the last event; the model learns policy from runtime-context snapshot + live notices, not from these events.
+
+## Anti-patterns
+- **Silently dropping an unrecognized required event**: readers must refuse reconstruction unless `ignorable: true` is set — loss can change how the remaining log is interpreted.
+- **A plugin appending `session/end-seed`**: only the `Session` constructor is a legitimate writer; a plugin doing so silently classifies every live bracket before it as seed history.
+- **Appending a non-JSON-serializable `tool/result` `meta`**: rejected at `Session.append` (isJsonValue); the producing tool owns `meta` shape but it MUST be JSON.
+- **Treating a log event as a Cordis event**: the durable log reaches listeners only through `session/event`; do not wire Cordis event listeners to it.
+
+## Code Examples
+```ts
+export type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result'
+export type SurfaceOp = 'append' | { op: 'replace'; start: SessionSeq; end: SessionSeq }
+export type SessionEvent<T extends SessionEventType = SessionEventType> = {
+  [K in SessionEventType]: {
+    type: K; seq: SessionSeq; time: number; data: SessionEventMap[K]; ignorable?: true
+  } & (K extends SurfaceEventType
+      ? { sourceEventSeqs?: SessionSeq[]; surfaceOp?: SurfaceOp }
+      : object)
+}[T]
+```
+```ts
+// Shadow price (compaction): metering event immediately precedes the replace.
+'compaction/prune': {
+  shadowedRange: { start: SessionSeq; end: SessionSeq }
+  shadowedSeqs: SessionSeq[]          // all shadowed surface nodes, surface order
+  shadowedTokenCount: number          // heuristic price, fixed estimator
+}
+// tool/call pairs with tool/result by callId; arguments kept as the model's raw JSON string.
+'tool/call': { turn: number; step: number; callId: ToolCallId; name: string; arguments: string }
+```
+
+## Reference Tables
+Full payload declarations + JSDoc live in `src/docs/persistence-catalog.md` (~38KB, generated by `gen-persistence-catalog`, verified by `verify-persistence-catalog`). ★ = surface type (the only ones joining the model transcript).
+
+| Family | Members | Badge |
+|---|---|---|
+| `user/*` | `user/message` | ★ surface |
+| `assistant/*` | `assistant/message` ★, `assistant/attempt` | surface + log-only |
+| `tool/*` | `tool/result` ★, `tool/call`, `tool/code-dispatch`, `tool/code-dispatch-start` | surface + log-only |
+| `turn/*` | `turn/start`, `turn/end` | log-only |
+| `step/*` | `step/start`, `step/end` | log-only |
+| `request/*` | `request/header`, `request/context` | log-only |
+| `session/*` | `session/end-seed`, `session/title`, `session/title-llm-request` | log-only |
+| `agent/*` | `agent/inbox/spliced` | log-only |
+| `agent-preset/*` | `agent-preset/selected` | log-only |
+| `approval/*` | `approval/asked`, `approval/decided`, `approval/policy` | log-only |
+| `sandbox/*` | `sandbox/mode` | log-only |
+| `permission/*` | `permission/preset` | log-only |
+| `plan/*` | `plan/mode` | log-only |
+| `model/*` | `model/selection` | log-only |
+| `command/*` | `command/run`, `command/done` | log-only |
+| `compaction/*` | `compaction/start`, `compaction/end`, `compaction/summary`, `compaction/prune` | log-only |
+| `feedback/*` | `feedback/record` | log-only |
+| `goal/*` | `goal/change` | log-only |
+| `hook/*` | `hook/invoked`, `hook/result` | log-only |
+| `llm/*` | `llm/retry`, `llm/retry-started` | log-only |
+| `schedule/*` | `schedule/change` | log-only |
+| `session-log-deepseek/*` | `session-log-deepseek/delivery-accepted` | log-only |
+| `subagent/*` | `subagent/descriptor`, `subagent/model-selection-policy` | log-only |
+| `team/*` | `team/member`, `team/task`, `team/message/queued`, `team/message/delivered` | log-only |
+| `todo/*` | `todo/write` | log-only |
+| `tool-workflow/*` | `tool-workflow/run-start`, `run-end`, `agent-start`, `agent-end` | log-only |
+| `web/*` | `web/deepseek-search-llm-request` | log-only |
+
+Envelope facts: `seq` = monotonic per-session; `time` = Unix epoch ms; `data` = `SessionEventMap[K]`; `ignorable?` skip marker; `sourceEventSeqs?`/`surfaceOp?` surface-only. A log-only event never carries surface metadata (compiler-enforced at `Session.append`).
+
+## Key Takeaways
+1. Only three event types touch the model transcript: `user/message`, `assistant/message`, `tool/result` — all others are log-only durable audit.
+2. A log event is **not** a Cordis event; wire to `session/event`, and project the surface with `deriveMessages()`.
+3. Default unrecognized events to *required* (refuse reconstruction); opt into `ignorable: true` only for loss-safe informational records.
+4. Compaction replaces surface nodes with `surfaceOp: { replace }`, priced by the metering event immediately before it (`compaction/summary` or `compaction/prune`).
+5. Versioning: writers stamp `SESSION_FORMAT_VERSION`; historical artifacts migrate via the build-static migration catalog — not by hand.
+6. Store layout / DSH_HOME anatomy / durability are **not** here — they are `subsystems/persistence.md`'s job; this catalog is the event-format vocabulary only.
+
+## Connects To
+- **Ch 13**: `Session.append`, `firstLiveSeq`, `deriveMessages()` projection — the core-session surface this log backs.
+- **Ch 16**: `fs/observed`, preset/audit state — the durable facts consumed as session data.
+- **Ch 17**: `TokenUsage` referenced by `assistant/message` and `compaction/summary` payloads.
+- **Ch 14**: the agent loop commits `turn/start`..`turn/end`, `step/start`..`step/end`, `tool/call`/`tool/result`.
+- **Ch 11**: tools emit `tool/call`, `tool/result`, `tool/code-dispatch*` as their durable effects.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch13-subsystems-core-session.md

@@ -0,0 +1,106 @@
+# Chapter 13: Subsystems — Core, Session & Conversation
+
+## Core Idea
+The `packages/core` spine drives one loop — claim queued input → open a turn on the append-only `SessionEvent` log → assemble the request prefix via `ctx.systemPrompt` → stream the model → dispatch tools → append every model-visible fact back to the log. Message history is *derived* from the log (`deriveMessages()`), never stored; everything a plugin touches (agent handle, inbox, prompt sections, conversation nodes, scope) hangs off that log.
+
+## Frameworks Introduced
+- **Core spine (6 packages)**: `session/` (log, `ctx.sessions`), `system-prompt/` (`ctx.systemPrompt`), `tools/` (`ctx.tools`), `agent/` (`ctx.agents`), `agent-loop/` (concrete driver, `ctx.agentLoop`), `scope/` (dependency-free primitive below session/system-prompt to avoid cycles).
+  - When to use: any extension — depend on `agent`, never `agent-loop` directly (keeps the loop swappable). `dsh-base` is the default composition; `dsh-sdk-minimal` the smaller tree.
+- **Subsystem taxonomy (README grouping)**: ~50 pages, one per subsystem, each owning vocabulary + wiring + generated Cordis API section. Clusters: core loop (core, session, system-prompt, tools, scope), LLM (llm-streaming, token-meter), persistence/settings/credentials seams, session-derived surfaces (query, feedback, title, reference, projection, telemetry), execution seams (shell, subprocess, terminal, sandbox, code-runtime, filesystem, lsp), agent fan-out (subagent, agent-team, workflow, jobs), UI (web-client, client-modules, slots, conversation), gating/audit (approval, permission-presets, plan, invariants), infra (web-server, webhook, storage, workspace, extensions).
+- **AgentHandle ownership model**: `AgentHandle { agent, dispose() }` from `ctx.agents.create()/resume()`; dispose = stop loop → await exit → unregister → remove session → unwind scoped world. The factory provider is a structural owner; config-created agents are owned by the loop fiber.
+  - How: `setup(agentCtx)` composes the scoped world before `agent/created` publication; a setup rejection/commit throw/owner disposal rolls back both ids unpublished.
+- **Inbox delivery vocabulary**: `InboxTarget = 'next-turn' | 'next-step'`; `send(message, target, wakeup)` is the unified route; `followup`/`steer`/`inject` are fixed presets (sole ordinary turn message / nearest step boundary / next pre-step without waking).
+- **Conversation node assembly**: one `ConversationNodeAssembler` per Session applies registered Definitions over a contiguous `SessionEventLikeEntry` window; Definitions correlate by stable `(kind, id)`, fold deterministic State, publish target-owned nodes.
+- **Runtime invariants registry** (`ctx.invariants`): package-owned checks; every workspace package publishes a `./invariant` companion registering under its exact npm name.
+
+## Key Concepts
+- **AgentStatus**: `'idle' | 'running'`; `running` is the driver-wide drain interval (may span queued turns), not proof a turn is open; disposal is not a status.
+- **SessionEvent envelope**: `{ type, seq (monotonic, seq = log.length), time, data }`, discriminated union over `type`; conditional `sourceEventSeqs`/`surfaceOp` only on surface types; optional `ignorable?: true` lets safe-skipping readers skip unknown informational events (absent = required — refuse to reconstruct).
+- **SurfaceEventType**: `user/message | assistant/message | tool/result` — the only types producing LLM messages; `SurfaceOp = 'append' | { op: 'replace', start, end }` (compaction shadows inclusive seq ranges).
+- **EpochHeader**: logged request state — `{ config: LlmCallConfig, adapterDefaults?, system?, tools? }`; `request/header` reasons: `'initial' | 'resume' | 'change' | 'series'` (+ `startsSeries`); `foldRequestHeader` takes the latest snapshot. `request/context` records route capacity separately (never folded into header equality).
+- **TurnEndReason** (merge-extensible): `completed | aborted(reason: TurnEndCancelCause) | blocked | error(LlmFailure) | max-tokens | interrupted` — `interrupted` is synthesized only by crash recovery, never emitted live; any max-tokens step makes the whole turn `max-tokens`.
+- **session/end-seed**: constructor-only writer marking seed-vs-live cut; last `{ inherited: true }` marker = fork lineage cut; lets bracket owners (e.g. compaction) treat pre-boundary open markers as dead lifecycles.
+- **Initiator scope**: `ctx.agents.currentInitiator()/requireInitiator()/withInitiator(agent, op)/withoutInitiator(op)` — same-process causal attribution only; ambient presence is neither liveness proof nor authorization.
+- **Predecessor reads**: `start` receives a `ConversationContextReader`; `reader.previous<State>(kind)` returns the nearest earlier started Context; the assembler reruns dependents when an older prepend revises it.
+- **Dynamic Cordis extensions**: `ctx.dynamicCordisRunner` — versioned immutable Packages under stable Plugin ids, Host/Client halves, approval-gated Client activation (`ApprovalRequestId`, `approveFutureVersions`), `inventory()`/`snapshot(agent)`/`inspectPackage()` source-free reads.
+
+## Mental Models
+- Think of the Session log as the database and `deriveMessages()` as a materialized cached view — replay is re-derivation, requests are pure functions of the log (reconstructability).
+- Use `inject()` for model-facing context without waking the driver; `steer()` to bend the nearest step; `followup()` when the message must own its own turn.
+- Think of Scope as "one registration context = per-agent visibility + shared lifetime": `ScopeKey` (opaque object; the live Agent is its own key), `Scoped<T>` carrier for scope-filtered events, `Scope { ctx, rawDispose, dispose }` for ordered composite teardown.
+- Treat prompt assembly as cooperative: sections/contexts/tools/variables assemble → `system-prompt/assemble` waterfall → an effective `complete` section is restored afterwards as the sole section.
+
+## Anti-patterns
+- **Switching with `assertNever` over `SessionEvent`**: the map is merge-extensible; a plugin variant is a valid unknown — handle known cases, fall through `default`.
+- **Scanning the event window / all Contexts per append in a Definition**: breaks the D-matches + O(1) key-lookup property; use State, Location data, `reader.previous()`.
+- **Appending `session/end-seed` from a plugin**: would silently classify all live events before it as seed history; the Session constructor is the only legitimate writer.
+- **Non-JSON event data (Map/Set/Date/class instance, negative zero, …)**: `Session.append` throws at the source — fail at append, never at backend flush.
+- **Withdrawing a published conversation node with `null`**: keep the key, use `visibility: 'hidden'`.
+- **Assigning updates to "the latest unfinished Context"**: every correlated event must carry or derive the same stable business id.
+
+## Code Examples
+```ts
+// Delivery routing (Agent handle)
+send(message: UserMessage, target: 'next-turn' | 'next-step', wakeup: boolean): void
+cancel(cause: AgentCancelCause /* 'user'|'parent'|{kind:'hook',reason}|'disposed' */,
+       options?: { keepInbox?: boolean }): void
+runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T> // from true idle only
+
+// Inbox splices (durable, via agent/inbox/spliced)
+claim(target): removes all next-step input + one next-turn message at turn boundary (no discard emits)
+
+// Conversation Definition shape
+interface ConversationNodeDefinition<S> {
+  kind: string; target: string;
+  match(event): { id: string; role: 'start' | 'update' } | null;
+  start(context, match): S; update(context, match): S;
+  publication?: 'immediate' | 'animation-frame' | 'none';
+  buildLocationData?(context, scope): LocationData | null;
+  buildViewNode?(context): Node | null; // must pair with target
+}
+
+// Invariants
+type InvariantFailure = (message: string) => never  // throws InvariantError code:'INVARIANT'
+ctx.invariants.register(packageName, { inject?, (ctx, fail) => {...} })
+```
+
+## Reference Tables
+| Prompt contributor | Register via | Ordering |
+|---|---|---|
+| PromptSection (`complete?`, `{{var}}` text) | `ctx.systemPrompt.section()` | ascending `order`, ties by name; repo orders via `getSectionOrder()` |
+| PromptContext (durable user-role snapshot) | `ctx.systemPrompt.context()` | ascending `order`; `getContextOrder()`; `suppressRuntimeContext()` to hide all |
+| Tool schemas | `ctx.systemPrompt.tools(provider)` | `ToolProviderResult { schemas, knownNames? }`; reserved `TOOL_ORDER_REST` name fails assembly |
+| Variables `[a-z][a-z0-9_]*` | `ctx.systemPrompt.variable(name, provider)` | scoped shadows global |
+
+| Agent event | Mode | Contract |
+|---|---|---|
+| `agent/pre-step` | waterfall | reject/enter with messages; only waterfall before request derivation |
+| `agent/request` | waterfall | replace frozen `LlmCallConfig`; cannot mutate messages |
+| `agent/request-error` | waterfall | return `{kind:'retry'}` without `next()` to own recovery |
+| `agent/turn-stopping` | serial | object by calling `agent.steer(...)`; data decides, order can't |
+| `agent/session-start` | emit | seed via `agent.inject()`; source `startup|resume|clear|compact` |
+| `agent/assistant-stream` | emit | transient start/chunk/end frames before durable settlement |
+| `session/event` | emit | post-commit firehose; constructor seeds never emit |
+| `session/flush` | parallel | durability checkpoint via `ctx.sessions.flush(session)` only |
+
+| Invariant selection (`Config`) | Default | Semantics |
+|---|---|---|
+| `enabled` | `true` | global switch |
+| `package_allowlist` | `[]` (admit all) | unanchored regex sources, `new RegExp(source)` |
+| `package_blocklist` | — | overrides an allowlist match |
+
+## Key Takeaways
+1. Never persist or cache message history — derive from the log; append is synchronous, durability is async (`session/flush` via `ctx.sessions.flush`).
+2. Plugin event types must be log-only (no `surfaceOp`) unless they produce messages; merge `SessionEventMap`/`TurnEndReasonMap` by declaration merging, switch with `default` not `assertNever`.
+3. For ordered agent teardown use `prepare`/`enter`/`announce` (exact Cordis disposer identity is load-bearing); plain `ctx.sessions.create` is for fiber-owned sessions only.
+4. Fork via `ctx.sessions.fork(source, boundary?)` — must end outside an open turn; `recompose`/`composeFrom` bind children to the parent's exact preset generation, never re-resolve by id.
+5. Invariant companions: register under the exact npm name; empty installers must start `No runtime invariant:` with a package-specific reason — `verify-package-invariants` mechanically rejects violations.
+6. Checks assert event/data relationships, never service or method presence; a reservation holds even when filters disable the installer (no silent name theft).
+
+## Connects To
+- **Ch 14**: the agent loop drives this spine turn-by-turn; interception contracts detail.
+- **Ch 15**: `ctx.tools` registry and the guarded execution pipeline behind `tool/call`/`tool/result`.
+- **Ch 16**: persistence (`SessionPersistence`, JSONL, crash recovery, `SessionHeader`) consumes the durability contract here.
+- **Ch 17**: `Message`/`ContentBlock`/`StreamChunk` vocabulary the log embeds.
+- **Ch 08**: architecture page owns the cross-subsystem event taxonomy and lifecycle.
+- **Ch 04/05**: Scope/ScopedLayers and the dispatch modes (emit/waterfall/serial/parallel) are Cordis primitives used throughout.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch14-subsystems-agent-loop.md

@@ -0,0 +1,111 @@
+# Chapter 14: Subsystems — Agent Loop (Goals, Plans, Subagents, Compaction)
+
+## Core Idea
+The agent-loop **spine** lives in core; these are **optional capability seams** the loop never depends on. Delegation (subagent), orchestration (workflow, agent-team), persistent collaboration state (goal, plan, todo), and context management (compaction, spill) each compose in only when a provider/consumer plugin is loaded.
+
+## Frameworks Introduced
+- **Subagent capability seam** (`ctx.subagents` → `SubagentRuntime`): named provider registry; one-shot `SubagentRun` + continuable children. Providers are trusted same-process transports.
+  - When to use: delegate one self-contained task (`start`) or a steerable multi-turn child (`startContinuable`).
+  - How: `start(name, request)` → `SubagentRun` (await `result`, always `dispose`); continuable path uses `startContinuable`/`sendMessage`/`interrupt`.
+- **SubagentCapabilities** (`agentOptions`, `outputSchema`, `depthLimit`, `toolFilter`, `persona`): start-time feature flags.
+  - When to use: request any non-default option; the service rejects unsupported requests loud (`SubagentError('UNSUPPORTED_CAPABILITY')`) — never accepted-then-ignored.
+- **Continuation manager / Activation**: one durable child `Session` ⇒ at most one process-local **Activation** (resident reconstructed `Agent`).
+  - How: `startContinuable` → `{ childId, messageId }`; turns ordered via `Agent.steer()` into the Agent inbox (the only queue).
+- **Workflow seam** (`ctx.workflowEngine` → `WorkflowEngine`, abstract): runs a model-written orchestration **script** that spawns subagents.
+  - How: `start(request)` → `WorkflowRun`; `meta`/`args` are plain JSON DATA validated before any script text runs.
+- **GoalService** (`ctx.goals`): event-sourced same-session goal, backed exclusively by the owning session log.
+  - How: compare-and-set mutations via `GoalRef {id, revision}`; every mutation appends a `goal/change` event.
+- **CompactionEngine** (`ctx.compaction`, abstract): replaces a surface range with one summary node.
+  - How: `compactIfNeeded(agent, trigger, signal)` / `compactNow` / `compactRegion(start, end, agent, signal)`.
+- **SpillStore** (`ctx.spillStore`, abstract): persists oversized tool text, returns a locator + retrieval hint.
+  - How: `saveText(input) → Promise<SpillRef>`.
+- **TeamService** (`ctx.agentTeams`): experimental implicit-root multi-agent topology.
+- **PlanModeController** (`ctx.planMode`): soft plan-mode guidance.
+
+## Key Concepts
+- **Activation**: process-local period a continuable child `Agent` is resident; one per child Session, may run many FIFO turns, stays while descendants run.
+- **Continuable child**: durable child Session with an optional live Activation; no `SubagentRun`, no Task wrapper.
+- **SubagentRun**: holder-owned one-shot handle — `id`, `localAgent?`, `result`, `dispose()`. No steering/resume.
+- **SubagentStopReason**: merge-extensible `completed | aborted | error | max-tokens | refusal`; map non-`completed` to `isError`.
+- **WorkflowMeta**: identity block `{name, description, whenToUse?, phases?}`; matches Claude Code dynamic-workflows meta vocabulary.
+- **WorkflowError.fatal**: hook misuse (`fatal: true`) is re-thrown by `parallel()`/`pipeline()`, never folded to `null`.
+- **GoalPhase**: durable `active | paused | blocked | complete`; **activation** (process-local continuation eligibility) is separate and never persisted.
+- **GoalMessageSource**: `{kind:'goal', goalId, revision, round}` — positive sequential round attribution on admitted `user/message`.
+- **CompactionTrigger**: `'pressure' | 'context-overflow'`; overflow may force a reduction even below threshold.
+- **SpillRef / SpillLocator**: saved artifact (`locator` opaque branded, `bytes`, `retrievalHint`); consumers render hint, never parse locator.
+
+## Mental Models
+- Use **one-shot subagents** when the child is a single foreground delegation you await and dispose; use **continuable children** when the parent must steer/interrupt/resume across turns.
+- Think of **compaction as surface-node shadowing, not deletion**: the append-only log retains everything; `shadowedSeqs` is the authoritative shadowed set, `shadowedRange` a position span (can have `start > end` after prior replaces).
+- Think of **goal phase vs activation** as two questions: "what happened to the objective" (durable) vs "may a continuation consumer start another round" (process-local).
+- Think of **spill** as "save text, return locator" — storage only; no retention, no tool-result replacement, no retrieval API.
+
+## Anti-patterns
+- **Accepting an unsupported subagent capability silently**: requests must reject loud; flags are checked before `start()`.
+- **Reporting partial output as success**: a non-`completed` `stopReason` means `output` may be partial — map to `isError`.
+- **Rejecting `result` on child-level failure**: a model/transport failure resolves with `stopReason:'error'`; only unrepresentable infrastructure faults reject.
+- **Folding workflow hook misuse into `null`**: fatal `WorkflowError` must kill the script; `null` is reserved for child-run failures and ordinary stage errors.
+- **Giving a listener a live `WorkflowRun` or the result value**: events carry DATA SNAPSHOTS (`WorkflowRunInfo`), and `workflow/end` omits `value`.
+- **Coupling a provider's settlement/cleanup to a sibling**: providers isolate operation-local mutable state; a shared capacity controller may delay but never couple.
+
+## Code Examples
+```ts
+// subagent routing by Activation state (SubagentRuntime.sendMessage)
+//   running  → steer nearest step in same Activation
+//   waiting  → wake and steer same Activation
+//   no Activation → cold-resume a new Activation, then steer
+
+// goal lifecycle (ctx.goals)
+get(agent): GoalView | undefined
+create(agent, { objective, maxGoalRounds? }): GoalView
+edit(agent, ref, { objective?, maxGoalRounds? }): GoalView
+pause(agent, ref) | resume(agent, ref) | complete(agent, ref): GoalView
+block(agent, ref, { code, message }): GoalView
+clear(agent, ref): GoalRef          // durable tombstone
+disarm(agent): GoalView | undefined // process-local, no phase change
+
+// plan mode (ctx.planMode)
+get(agent): { active: boolean; pending?: boolean }
+set(agent, active): 'committed' | 'queued' | 'cancelled' | 'noop'
+
+// compaction (ctx.compaction)
+compactIfNeeded(agent, 'pressure'|'context-overflow', signal): Promise<CompactionResult | null>
+compactNow(agent, signal, sourceCommandId?): Promise<CompactionResult | null>
+compactRegion(start, end, agent, signal?): Promise<CompactionResult>
+
+// spill (ctx.spillStore)
+saveText({ owner: {sessionId}, source: {toolName, callId, label},
+           suggestedName, content }): Promise<SpillRef>
+```
+
+## Reference Tables
+
+**Compaction session events (all log-only):**
+| Event | Payload | Role |
+|---|---|---|
+| `compaction/start` | `{ turn }` | lock; number = open auto turn, `null` = standalone manual |
+| `compaction/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | safe projection + reconstructable one-shot call envelope |
+| `compaction/end` | `{ turn, error? }` | releases lock; `error` = unsuccessful attempt |
+
+**`ManualCompactionErrorCode`:** `busy` · `cancelled` · `changed` · `summary` · `commit` · `persistence`.
+
+**Subagent provider registry names:** `spawn`, `fork`, `acp`, `codex`, `claude-code`, `dsh-sdk` (packages `dsh-subagent-<name>-in-process` / `-acp` / `-codex` / `-claude-code` / `-dsh-sdk`).
+
+**Team task DAG statuses:** `pending` (unstarted/released) · `in_progress` (has owner) · `completed` (satisfies blockers) · `deleted` (tombstone); `blockedBy` must be acyclic and name non-deleted tasks.
+
+## Key Takeaways
+1. `subagent`, `workflow`, `compaction`, `spill`, `plan`, `goal` are all optional seams — the loop spine never imports them.
+2. `sendMessage` routes purely by Activation residency; authority comes from the exact live sender (direct parent or direct continuable child only — siblings, ancestors, self, one-shot rejected).
+3. `ctx.tokenMeter` owns compaction estimation/replay; `dsh-compaction-basic` owns thresholds, retention, sequencing, and routed summarization calls.
+4. Compaction's only surface mutation is a `user/message` with `surfaceOp: {op:'replace', start, end}`; region edges must preserve tool-call/result pairing (`toolPairingBalancedBefore/After`).
+5. Goal `resume` re-arms after a session-start edge while round budget remains; `create` may replace only a `complete` goal — otherwise `clear` or `resume` first.
+6. Plan mode is soft guidance — sandbox mode and approval policy enforce independently and never read/write plan state.
+7. Spill `saveText` rejects on real storage failure; the policy consumer degrades best-effort by keeping the inline result.
+
+## Connects To
+- **Ch15 (Tool Execution)**: `ctx.spillStore`/`dsh-spill-policy` are invoked from the `tools/post-execute` policy seam; `todo/write`, `exit_plan_mode` are model-facing tools.
+- **Ch13 (Core Session)**: `Session`, `SessionSeq`, `session/end-seed`, `Agent.steer()`, inbox events, and `surfaceOp` underpin subagent, compaction, goal, and plan state.
+- **Ch17 (LLM Streaming)**: compaction uses `ctx.llm.stream()` (the `llmStreamCall` marker); `ContentBlock` vocabulary is shared.
+- **Ch16 (Session Data)**: `subagent/descriptor`, `goal/change`, `todo/write`, `plan/mode`, `compaction/*` are durable session events recovered on resume/fork/compaction.
+- **Ch06 (Architecture) / Ch07 (Capability Seams)**: every entry here follows the Service Definition / Provider / Consumer split (e.g. `dsh-spill` + `dsh-spill-local` + `dsh-spill-policy`).
+- **Ch09 (API Gateway)**: `ctx.subagents` exposes `@Remote` faces (`remoteExportList`, `prompt`, `interruptByParent`); `ctx.agentTeams` exposes `remoteView`/`remoteCreateTask`/`remoteUpdateTask`.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch15-subsystems-tool-execution.md

@@ -0,0 +1,106 @@
+# Chapter 15: Subsystems — Tool Execution (Shell, Sandbox, FS)
+
+## Core Idea
+`ctx.tools` (`ToolRuntime`) is the single registration/dispatch pipeline every tool call traverses (`tools/pre-execute` → guards → `tools/execute` → `tools/post-execute` → `finalizeContent` → `tools/result`), while each execution capability — shell, filesystem, subprocess, sandbox, LSP, code-runtime — is an optional **capability seam** (Service Definition + Provider + Consumer) whose provider can be swapped without changing tool schemas. Two independent knobs, sandbox mode (`sandbox/mode`) and approval policy (`approval/policy`), are resolved **per call** and fail closed.
+
+## Frameworks Introduced
+- **ToolRuntime dispatch pipeline**: registry + extensible waterfalls over one call.
+  - When to use: register tools, gate calls, wrap dispatch, observe outcomes.
+  - How: `ctx.tools.register(definition)` (global or agent scope); `execute(ToolExecutionInput)` materializes/freezes args, assigns an opaque `ToolExecutionToken`, then runs the waterfalls in fixed order; `schemas(scope)` projects an allowlist (`name`/`description`/`parameters` only) so `output`/`execute`/callbacks never leak into model requests.
+- **Capability seam pattern**: abstract service (`ctx.shell`, `ctx.fs`, `ctx.subprocess`, `ctx.sandbox`, `ctx.lsp`, `ctx.codeRuntime`), one provider per context (a second throws, cordis duplicate-service behavior), and a tool Consumer owning the model-facing schema.
+  - When to use: adding an alternate backend (remote fs, sandboxed bash) or a new tool-backed capability.
+  - How: subclass the abstract seam, load as plugin; the seam — not the loop spine — owns the vocabulary.
+- **`resolve()` request/spec split**: caller-facing request has optional fields; `resolve()` fills implementation defaults/caps into a fully-resolved spec.
+  - When to use: "explicit > implicit at package boundaries" — never hide a `??` default inside the execution method. Used by `ctx.shell.resolve`, mirrored by `SubprocessSpawnSpec` (no defaults at all).
+- **Observation policy (read-before-write)**: `dsh-fs-observation-policy` turns bare `write`/`edit` into guarded mutations via `fs/*` events.
+  - How: tool dispatches `fs/write-intent`/`fs/edit-intent` (single-slot first-wins waterfalls) and emits `fs/observed` (sync, side-effect-only listener); policy keeps `WeakMap<owner(session), Map<targetKey, FsObservation>>`.
+- **Per-call sandbox policy**: `ctx.sandboxPolicy.resolve({session, mode?})` — precedence: approved explicit mode > session's last `sandbox/mode` event > deployment default; workspace root = session's immutable cwd (fs-canonicalized before lexical normalization). `ctx.sandbox.confine(argv, policy)` returns wrapped argv or throws.
+- **Fail-closed approval**: only `allowed-once` grants; everything else denies.
+
+## Key Concepts
+- **ToolDefinition**: `ToolSchema` + mandatory `output` (schema + `render` + optional `presentationMeta`), `execute(args, exec)`, optional `timeoutMs`, `isConcurrencySafe`, `finalizeContent`, `presentCall`/`presentResult`.
+- **PreToolDecision**: `{allow}` / `{deny, reason}` / `{ask, reason?}` — `ask` proceeds only on `allowed-once`; arguments can never be rewritten (history/audit/UI/execution must agree).
+- **ToolGuard**: monotonic post-waterfall check — returns a denial reason or `undefined`; no allow result, so ordering can't undo a denial.
+- **PostToolDecision**: `accept` (replace content XOR value — value is revalidated and recomputes content) or `block` (feedback becomes `isError`).
+- **ToolRestriction**: per-scope `{allow?, deny?}` over inherited global tools; restrictions intersect; own scoped registrations stay exempt (delegated children keep their tools).
+- **ShellExecSpec / ShellRunResult**: resolved spec; orthogonal outcome fields (`timedOut` XOR `aborted`, `exitCode`, `signal`) so a killed run never reads as clean success.
+- **ShellProcess**: background handle — `readOutput()` is incremental/consuming, `done` never rejects, `kill()` idempotent; no id/owner (generic job runtime owns identity).
+- **CollectedOutput**: truncated stream keeps the **tail** in `text` + `spillPath` to the complete stream.
+- **FsTarget / FsVersion**: opaque branded identity and freshness token — consumers must not parse `targetKey` or interpret versions; use `processPath`/`fileUrl`/`contains` for cross-capability coordinates.
+- **ConfinedArgv**: wrapped argv + `enforcement` + `denialSignatures` (this backend's dialect) + `runnerFailureRules`.
+- **ApprovalOutcome**: `'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'` — closed; missing/throwing/non-conforming answerer normalizes to `unavailable`.
+- **CodeBindingNamespace**: one program-visible global of async host functions; args/resolutions must be lossless JSON; names are hostile input (null-prototype, `__proto__` is an own property).
+
+## Mental Models
+- Think of tool dispatch as a **fixed waterfall with monotone permissions**: policy can only shrink access (pre-execute deny/ask → guard deny); post-execute can reshape results but never retro-authorize.
+- Use `ask` when a call is conditionally safe — it is a denial unless an approval service returns `allowed-once`; prefer `deny` for never-safe and `allow` for always-safe.
+- Think of the sandbox as an **argv wrapper, not a jail**: `confine()` swaps the argv and hands back classification dialects; the consumer spawns and attributes outcomes. Network/process visibility are outside the vocabulary.
+- Treat FS authorization as **freshness, not windows**: any windowed read that emits a present `fs/observed` authorizes a later guarded write/edit iff the version is unchanged; there is deliberately no `FS_PARTIAL_OBSERVATION`.
+
+## Anti-patterns
+- **Silent unconfined passthrough**: illegal for a confined policy — no usable backend must surface as `SANDBOX_UNAVAILABLE` (foreground throw) or `runnerFailed` (settled background), never as an unsandboxed run.
+- **Inferring denial from exit status or cross-backend stderr unions**: exit status never proves runner failure; match only the returned backend's own `denialSignatures` (EROFS/bwrap, EACCES/Landlock, EPERM/Seatbelt), and check `runnerFailureRules` (fatal signature + optional exit-code gate, informational lines excluded) first.
+- **Parsing `targetKey`/`FsVersion` or host-path rules on LSP URIs**: both are branded opaque; use `processPath`, `contains`, and `resolvedWorkspaceUri`.
+- **Adding a `timeoutMs` to fs reads**: the seam can't enforce a deadline on an in-progress `fsync`/`rename` — cancellation propagates via the execution signal only (bash/web/glob/grep are process-backed and do carry timeouts).
+- **Treating `isolation` (`'worker-thread'|'process'|'container'`) as a security claim**: it's a diagnostic label; sandboxing is the sandbox seam's job.
+- **Async listener in `fs/observed`**: must be synchronous and side-effect-free — a throw can replace a read error or surface after a successful mutation.
+
+## Code Examples
+```ts
+type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+type SandboxEnforcement = 'full' | 'partial';
+type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
+type ApprovalPolicy = 'ask' | 'never';   // never: rejected before any answerer runs
+type PreToolDecision =
+  | { kind: 'allow' }
+  | { kind: 'deny'; reason: string }
+  | { kind: 'ask'; reason?: string };
+type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover';
+type CodeRunFailureKind =
+  'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit';
+```
+```ts
+// Escalation path (one-shot, strictly wider):
+const spec = ctx.shell.resolve({ command, workdir, sandboxPolicy:
+  ctx.sandboxPolicy.resolve({ session, mode: 'workspace-write' }) });
+// model-side: sandbox_permissions + justification on a denied call;
+// ctx.approval must grant that exact call before anything executes.
+```
+
+## Reference Tables
+
+| SandboxMode | File effects | Notes |
+|---|---|---|
+| `read-only` | denies writes; POSIX grants `/dev/null` sink | Windows ACL runner: no writable root, reports `partial` |
+| `workspace-write` | workspace root + backend temp area | root = session immutable cwd |
+| `danger-full-access` | bypass | consumer spawns original argv, never calls `ctx.sandbox` |
+
+| FS state → decision | write | edit |
+|---|---|---|
+| unseen | `createIfAbsent` | `FS_NOT_OBSERVED` |
+| absent | `createIfAbsent` | `FS_NOT_FOUND` |
+| present@version | `replaceIfVersion` | version guard (checked **before** literal match) |
+
+| Preset (default table) | sandbox | approval |
+|---|---|---|
+| `workspace-write` | workspace-write | ask |
+| `danger-full-access` | danger-full-access | never |
+| `custom` (derived-only) | — | — reserved key, never a switch target |
+
+Key `FsErrorCode`s: `FS_NOT_OBSERVED` (no prior observation / create hit existing), `FS_STALE_VERSION`, `FS_SANDBOX_DENIED` (policy fence — distinct from kernel `FS_PERMISSION_DENIED`), `FS_TOO_LARGE`, `FS_AMBIGUOUS_EDIT`, `FS_EDIT_NOT_FOUND`, `FS_ABORTED`. LSP codes: `LSP_UNAVAILABLE`, `LSP_CONFLICT`, `LSP_INVALID_PROVIDER`, `LSP_DISPOSED`, `LSP_UNSUPPORTED_OPERATION`, `LSP_MALFORMED_RESPONSE`.
+
+## Key Takeaways
+1. Register via `defineTool` (validates/narrows args, infers return from `output.schema`); raw `ToolDefinition`s validate their own `args: unknown`. Mismatches throw `ToolArgsError` (`INVALID_ARGS`) / `ToolOutputError` (`INVALID_TOOL_OUTPUT`); invisible tools fail as `UNKNOWN_TOOL` without ending the turn.
+2. `ctx.shell.run()` resolves on nonzero exit/timeout/abort (rejects only for infrastructure failures); `start()` returns a handle the tool adapts into `ctx.jobs` — the shell seam itself is task-free.
+3. `DSH_*` env is a managed namespace: executors discard ambient values and merge `ctx.shellEnv`'s snapshot last, so caller `env` entries can never displace managed facts; `stdin`/`env`/`stdoutMaxBytes` are trusted-plugin-only, not model parameters.
+4. `SubprocessHandle.terminate()` (SIGTERM→`graceMs`→SIGKILL, tree-scoped, also fired by the spec's abort signal) is the only termination verb; `waitForExit()` observes the whole tree; `done` carries exit facts only — cause classification (`timedOut`/`aborted`) belongs to the caller.
+5. Approval `request()` requires an open turn and appends the `approval/asked`/`approval/decided` audit pair (log-only, outside the model transcript); abort → `cancelled`, late answers discarded.
+6. Presets own no enforcement: `set()` writes through `setSandboxMode` + `setApprovalPolicy` only when a knob changes, after a log-only `permission/preset` event; requires a confining executor (with `sandboxMode` capability fact) or load fails.
+7. `ctx.codeRuntime.run()` reports errors as result fields, never rejections; programs run as async-function bodies (top-level `await`/`return`); `language` is `'typescript'` (released) / `'python'` (experimental, private).
+
+## Connects To
+- **Ch 07**: capability seams — the Service Definition/Provider/Consumer split formalized here per capability.
+- **Ch 11**: tool catalog — the concrete first-party tools (`bash`, `read`/`write`/`edit`, `lsp`, `run_code`) built on these seams.
+- **Ch 14**: the agent loop drives `executionMode` (parallel/exclusive barriers from `isConcurrencySafe`) and commits `tool/call`/`tool/result` events.
+- **Ch 10**: config keys (`sandbox/mode`, `approval/policy`, preset tables, executor defaults/caps).
+- **Ch 16**: `fs/observed` state and audit/preset events are session-log-owned durable facts.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch16-subsystems-session-data.md

@@ -0,0 +1,132 @@
+# Chapter 16: Subsystems — Session Data (Projection, Storage, Jobs)
+
+## Core Idea
+Every subsystem around the event log — projections, queries, references, titles, telemetry, persistence, domain storage, attachments, workspaces, jobs — layers over one source of truth: the in-memory append-only `Session` log, made durable by `SessionPersistence`. Derive rather than duplicate: fold the log into whole values, and keep non-log state in typed storage domains.
+
+## Frameworks Introduced
+- **ProjectionDefinition** (`ctx.sessionProjections.register`): "the framework drives, the domain computes" — the registry subscribes to `session/event` once and folds every committed event through every registered unit; domains hold no subscriptions, clients never fold.
+  - When to use: any per-session derived state, host-only or client-visible.
+  - How: `{key, stateSchema, init(header, inheritedEventCount), apply(state, event), wire?: {viewSchema, view}, stateVersion}` — all functions synchronous, state plain JSON; the disposer rides the calling fiber (unload ⇒ key reads as capability absence).
+- **SessionQueryEngine** (`ctx.sessionQuery`): live-preferred reads over live + persisted sessions.
+  - When to use: list/filter/search/trace anything beyond the current live session.
+  - How: concrete `listSessions` (newest-first), `readSession`, `readSurface`, `filterSessions`/`filterEvents`, `readEvent`, `traceSession`, `traceEvent`, `readTitle(s)`; a backend implements only the abstract `searchSessions`/`searchEvents`.
+- **SessionReferenceResolver** (`ctx.sessionReferenceResolver`): structured cross-session references (not fork semantics).
+  - When to use: host mention/autocomplete (`@[label](dsh-session:…)`) and cross-session context injection.
+  - How: `listCandidates(agent, query)` (keystroke-rate, self excluded, cwd-affinity ranked); `prepare(agent, content, references)` snapshots the referenced session's current surface into one aggregated untrusted `additionalContext`.
+- **SessionTitleService** (`ctx.sessionTitle`): log-backed latest-wins title fold plus one optional async provider.
+  - When to use: naming sessions or shipping a custom title generator.
+  - How: `get`/`rename`/`refresh`/`register(provider)`; provider `{id, automatic: 'first-prompt'|'all-prompts', generate(request)}`; the service owns acceptance (seq ordering, normalization, byte limit).
+- **SessionTelemetrySink** (`ctx.sessionTelemetry`): canonical-event capture under the boundary axiom — the harness aspect ends at `emit()`; batching, retry, queueing, and loss policy belong to the reporting SDK.
+  - When to use: outbound session reporting (the OTel backend is the shipped provider).
+  - How: implement `emit` (non-blocking enqueue), optional `flush`, `shutdown` (drain to quiescence); redact through the `session-telemetry/record` waterfall.
+- **SessionPersistence** (`ctx.sessionPersistence`): the durability seam — `create`/`open`/`stat`/`list` returning per-session `SessionHandle` (`read`/`append`/`flush`/`close`).
+  - When to use: resume, cold reads, out-of-tree storage backends.
+  - How: `open(id, 'write')` claims single-writer ownership (`SessionAlreadyOwnedError` on contention); `append` is best-effort — only a resolved `flush` (handle or service-wide) promises crash survival and cross-process materialization.
+- **DomainSpec / defineDomain** (`ctx.storageDomain` ≡ `ctx.storage.domain`): typed KV domains routed over registered backends (`json`, `sqlite`).
+  - When to use: plugin-owned persistent data that is not a session event.
+  - How: declare the spec once (zod record schemas, `layout: 'single'|'per-record'`, `compatibleVersions`, `invalidRecords: 'backup-and-skip'`); `open(spec)` validates the medium; reads are synchronous, writes chain durability → memory → `domain/changed`.
+- **AttachmentStore** (`ctx.attachments`) + **FileUploads** (`ctx.fileUploads`): immutable content-addressed binaries under the persist-before-event rule.
+  - When to use: images/files in prompts or model output; browser upload staging.
+  - How: `saveImages`/`admitPromptContent` validate every member before committing any; session events carry refs (`ImageAttachmentRef`/`FileAttachmentRef`), never bytes, object URLs, or paths; `ctx.fileUploads` stages receipts bound to the receiving Agent (`bindPrompt`/`retirePrompt`).
+- **WorkspaceRegistry** (`ctx.workspaceRegistry`): stable uuid identity over canonical (`fs.realpath`) directories plus header-validated session accounts.
+  - When to use: host-side grouping of sessions by working directory (invisible to models).
+  - How: `create(path, title?)` is idempotent per canonical path; membership = account entry ∧ canonical header cwd equals path; `attachSession` prepends, activity never reorders.
+- **JobRegistry** (`ctx.jobs`): background job identity, authorization, and settlement.
+  - When to use: long-running producers (shipped kinds `bash`, `subagent`; extend `JobKindMap` by declaration merging).
+  - How: `start({kind, label, owner?, run(): JobHooks})` after preflight; hooks `{cancel, done, readOutput?}`; `kill` requests cancellation and marks `stopping`/`reported`.
+
+## Key Concepts
+- **Whole-value event rule**: state-carrying log events carry the complete post-change state, never a delta — transitions stay trivially cheap, served values self-describing.
+- **`Object.is` discipline**: `apply` returns the same state reference when uninterested (zero downstream work); an object-valued `view` reuses its reference to suppress publication.
+- **`asOfSeq`**: snapshot watermark — seq of the last event every value reflects (`-1` for an empty log); `snapshot()` is fully synchronous, so one cut covers values and cursor in one tick.
+- **Live-preferred corpus**: query prefers live `ctx.sessions`, falls back to persisted logs; `SessionRecord {header, live, persisted}` separates source availability from the cloned header.
+- **`inheritedEventCount`**: exact fork-inherited prefix length stored beside the header; seeds projection `init` and completes cache-row identity.
+- **Projection cache rows**: `(sessionId, key, ver, seq, val)` in the `session_projcache` domain; a `stateVersion` mismatch discards old rows rather than forward-folding them into garbage.
+- **Revision token**: opaque change token from `stat`/`list`; equal ⇒ may treat the log as unchanged, unequal promises nothing; keys cold-read caches and plays no part in open/read/resume.
+- **`domain/changed`**: fires strictly after backend durability in write-chain order; `put` carries only the new value (never the old); a throwing listener is contained — the write is already durable.
+- **`reported` flag**: suppresses redundant job-completion notices once any reporter commits; teardown claims it so owner disposal spends no model request.
+- **Telemetry dedupe**: ledger records mirror events one-to-one — receivers dedupe on `(session.id, session.format_version, event.seq)`; ops records (`agent-error`, `shutdown`) deliberately carry no identity.
+
+## Mental Models
+- Think of projections as a fold server: domains register pure units, carriers receive finished whole values — never fold `session/event` client-side.
+- Think of a storage domain as a synchronous cache over a serial write chain: a rejected backend write leaves memory untouched, so reads never diverge from the medium.
+- Think of jobs as split ownership: runtime owns identity/access/lifecycle, producer owns execution resources; `done` resolves after resources are released, not when work finishes.
+- Treat `SessionHeader` as metadata-beside-the-log (`cwd`, `parentSession`, `isSeeded`, `origin`, `delegationDepth`, `agentPreset`) — it never enters `SessionEventMap` or `deriveMessages()`.
+
+## Anti-patterns
+- **Async projection unit / non-JSON state**: tears the carriers' consistency cut and breaks the persisted-cache precondition.
+- **Mutating returned references**: `stateOf` values and domain table records are live or shared — replace via `put`/`update`, never mutate in place.
+- **Parsing `AttachmentId` as a path**: it is opaque (`sha256:<digest>` today); ask `imageHostPath()`/`fileHostPath()` and let the execution world judge readability.
+- **Blocking `emit()`**: it runs synchronously on the `session/event` hot path — anything slower than a queue push taxes the agent loop.
+- **Expecting persistence to repair crashed turns**: it returns the valid contiguous log and truncates only the torn physical tail; appending `interruptedTurnClosers` is the resuming reader's job, under write ownership.
+- **Relying on job-id secrecy**: ids are predictable (`<kind>-N`); the boundary is owner-session authorization.
+
+## Code Examples
+```ts
+ctx.sessionProjections.register({
+  key, stateSchema, stateVersion: 1,
+  init: (header, inheritedEventCount) => empty,
+  apply: (s, e) => e.type === 'my/state' ? e.data.state : s, // same ref ⇒ no work
+  wire: { viewSchema, view: s => clientShape(s) },
+}); // disposer rides the calling fiber
+
+const spec = defineDomain({
+  name: 'my-plugin', version: 2, layout: 'per-record',
+  compatibleVersions: [1], invalidRecords: 'backup-and-skip',
+  tables: { items: domainTable<ItemId, Item>(ItemSchema) },
+});
+const domain = await ctx.storageDomain.open(spec);
+
+const id = ctx.jobs.start({
+  kind: 'bash', label: command, owner: agent,
+  run: () => ({ cancel: reason => proc.kill(), done, readOutput: () => drain() }),
+});
+```
+
+## Reference Tables
+
+| Projection read ladder | I/O | freshness |
+|---|---|---|
+| `sessionProjectionCache.cachedSnapshot(meta, inheritedEventCount)` / registry `viewCheckpoint(rows)` | zero | as stale as the last checkpoint, never wrong |
+| `sessionProjectionCache.hydratePrepared(session, events)` | no extra read | observation cut |
+| `sessionProjectionCache.coldSnapshot(meta, inheritedEventCount, events)` / registry `restore(rows, events, baseSeq)` | log suffix from `restoreFloor`, seeded by usable rows | log end |
+
+| Storage `open(spec)` failure ladder | code |
+|---|---|
+| name already open/closing | `already-open` |
+| route unresolved | `backend-not-found` |
+| backend lacks `kv` facet | `facet-unsupported` |
+| unit stamp/parse | `version-mismatch` / `malformed-medium` |
+| record schema | `invalid-record` (or backup-and-skip) |
+
+| Jobs semantics | rule |
+|---|---|
+| `start` | preflight (access, cleanup, admission) → sync `run()`; after it returns, registration cannot fail |
+| `kill` | returns `'requested' \| 'already-finished'`; marks `stopping` + `reported` |
+| `wait(id, timeoutMs)` | bounded, never cancels; post-settlement the terminal snapshot wins |
+| settlement | first-wins; completion announced last (a reporter may open a model turn) |
+| admission | `maxConcurrentJobsPerOwner` default 10, counting `running`+`stopping` per exact owner |
+
+| Attachment admission (local backend) | limit |
+|---|---|
+| images / encoded bytes per message | 20 / 200 MiB |
+| per source | 20 MiB, 64,000,000 px, ≤8192 px per side |
+| normalization defaults | long edge 2048 px, 4 MiB encoded |
+
+## Key Takeaways
+1. Register a projection unit instead of subscribing to `session/event`: the framework drives every unit once per committed event, lazily backfolds late registrations over the in-memory log, and checkpoints through `session_projcache` (mandatory points: session creation, `turn/end`, disposal; otherwise throttled write-behind).
+2. Gate crash survival on `flush`, not `append` — a session that never materialized before a crash never existed. Repair of an interrupted turn (missing tool errors, open `step/end`, synthetic `turn/end {reason: 'interrupted'}`) is written by resume under write ownership; `interrupted` is the one `TurnEndReason` no loop emits.
+3. Fork/replay is `ctx.agents.create({sessionId, seed, meta})` with `inheritedEventCount` and `meta.isSeeded: true`; resuming a persisted session is `ctx.agents.resume({resumeSessionId})`.
+4. Prefer `per-record` layout + `compatibleVersions` + `invalidRecords: 'backup-and-skip'` for disposable derived data (the projection-cache pattern); keep the rejecting `single` default for authoritative data.
+5. Consume sessions through `ctx.sessionQuery` concrete reads; full-text queries are data, never executable FTS syntax, and within-session pages carry the target header even with zero hits.
+6. Workspace membership needs both the account entry and canonical header-cwd equality — one session belongs to at most one workspace; registry `delete` retains sessions (they become Ungrouped). A `user`-source title rename pins the title; `refresh` is the deliberate unpin.
+7. Redaction lives in the `session-telemetry/record` waterfall (fail-closed, exported copy only — the canonical log is never rewritten); the seam ships no rules, so exported data is exactly as clean as what the deployment mounts.
+
+## Connects To
+- **Ch 13**: the `Session`/`SessionEvent`/`SessionHeader` vocabulary every fold and read here consumes.
+- **Ch 12**: persistence-catalog enumerates the exact log events mirrored by ledger telemetry and query folds.
+- **Ch 14**: agent-loop owns resume repair and the `turn/end`/`session/flush` checkpoints that drain persistence write-behind.
+- **Ch 15**: tool-execution backgrounds `bash`/`subagent` work through `ctx.jobs` kinds.
+- **Ch 09**: gateway controllers (session, workspace, file-upload, directory-picker) are the Remote consumers of these registries.
+- **Ch 07**: each subsystem here is an optional capability seam, deliberately off the agent-loop spine.
+- **Ch 05**: registration-as-effect, merge-extensible maps (`JobKindMap`, `StorageForms`), and waterfall semantics are Cordis mechanics.