better-dsh 0.2.4-a → 0.2.4-b

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

@@ -1,109 +0,0 @@
-# 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

@@ -1,106 +0,0 @@
-# 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

@@ -1,111 +0,0 @@
-# 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

@@ -1,106 +0,0 @@
-# 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

@@ -1,132 +0,0 @@
-# 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.