better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch17-subsystems-llm-streaming.md

@@ -0,0 +1,128 @@
+# Chapter 17: Subsystems — LLM Streaming, Tokens & Credentials
+
+## Core Idea
+dsh's LLM spine is provider-neutral at the wire: adapters emit a closed `StreamChunk` protocol, one shared `BlockAssembler` folds it back into `ContentBlock`s, and four edges handle the rest — credentials (secrets stay out of config), token metering (request-pressure pricing), typert (Remote-call typing), and client-modules (browser bundle loading).
+
+## Frameworks Introduced
+- **`StreamChunk`**: closed discriminated union (7 variants) — raw adapter protocol; `switch` over `type` ends in `assertNever`, so a new variant breaks every consumer that must handle it.
+  - When to use: every adapter `stream()` return; every consumer fold.
+  - How: emit `usage` before `finish`, nothing after; `index` ties deltas to a block, `block-end` carries the assembled `ContentBlock`.
+- **`LlmAdapter`** (abstract class): the provider contract — subclass, implement `stream()`, register with `ctx.llm.registerAdapter(providers, adapter)`.
+  - When to use: adding a model provider.
+  - How: `GenerateOptions.provider` selects the adapter; `model` need not be registered at lifecycle start; duplicate routes fail atomically.
+- **`BlockAssembler`**: single shared fold from `StreamChunk` stream → `ContentBlock[]` + usage + finish + replay.
+  - When to use: any consumer needing the assembled result without re-implementing the fold.
+  - How: `push()` each chunk, then read `blocks()` / `message()` / `usage` / `finish`; `interruptedBlocks()` on cancellation.
+- **`CredentialProvider`** (abstract seam): two disjoint key spaces answer two questions.
+  - When to use: reading/writing secrets for plugins.
+  - How: `CredentialRef` (env-var name) resolves per operation; `CredentialKey` (plugin id) uses read-modify-write only.
+- **`TokenMeter`**: replay owner for request-pressure + surface pricing; `measure(session, requestHeader?)` / `estimateMessage(message)`.
+- **Typert**: generated Remote-call typing via `InvocationDescriptor` + `TypertCodec` (`strict` schema | `src-json`).
+- **`ClientModuleRegistry`**: Node half of `dsh.client` scan → `WebBootGraph` → `/plugins` combo route + index-injection rows.
+
+## Key Concepts
+- **`ContentBlockMap`** — merge-extensible union: `text`, `reasoning`, `image`, `file`, `tool-call`, `tool-result`; a new modality lands only when adapter, UI, compaction, and replay all honor it.
+- **`Message`** — immutable `{ id, role: 'system'|'user'|'assistant', content: ContentBlock[], source }` shared by delivery, durable history, and model requests.
+- **`MessageSourceMap`** — merge-extensible provenance sum: `user`, `plugin` (with `plugin` + `ContextFormed`), `model`, `tool`.
+- **`ContextForm`** — semantic producer-declared info kind: `instructions` | `catalog` | `snapshot` (has `sections`) | `notice` (has `summary`) | `relay` | `recall`; never visual (colors/icons/ordering are the consumer's).
+- **`TokenUsage`** — disjoint counts: `inputTokens` (uncached only) + `cacheReadTokens?` + `cacheWriteTokens?` = billed input; `outputTokens`; `reasoningTokens?` already inside `outputTokens`; `totalTokens?` exact or omitted.
+- **`LlmFailure`** — serializable provider-neutral failure: `message`, `code`, `status?`, `providerRetryAfterMs?` (validated delay, not a retry decision), `requestId?: ProviderRequestId`.
+- **`FinishReasonMap`** — `stop`, `tool-calls`, `max-tokens`, `aborted {failure}`, `error {failure}`.
+- **`ReplayEnvelope`** — `{ response: unknown, blocks?: readonly unknown[] }`; adapter-owned halves, shared split so assembly prunes per-block entries in step with dropped blocks.
+- **`ResolvedRetryPolicy`** — immutable discriminated union: `normal` (`maxRetries`, `retryableCodes`, `initialDelayMs`, `maxDelayMs`, `jitterRatio`) or `always` (same backoff, no cap); normal default = 5 retries.
+- **`CredentialRef`** — `Branded<'CredentialRef'>`; a POSIX-style env-var name (shell-identifier syntax validated).
+- **`WebBootGraph`** — `{ rev, entries, batches }` injected as `window.__DSH_BOOT__`; single wire source between Node and browser halves.
+
+## Mental Models
+- **Use one adapter call = one provider attempt**: adapters disable library retries; agent-level recovery opens another numbered turn.
+- **Think of credential resolution as a per-operation read**: `resolve(ref)` re-reads every call; that (not the `reference-updated` event) is the hot-update path — a rotated credential reaches the next request with no restart.
+- **Think of the model catalog as advisory, never a whitelist**: routing keys on the registered provider; adapters may accept unlisted ids.
+- **Think of `usage before finish` as the ordering invariant**: defer both to the provider's end-of-stream marker so a trailing usage-only chunk can't violate it.
+
+## Anti-patterns
+- **Caching a credential across operations**: breaks hot-update; re-resolve per operation.
+- **Folding cache hits into `inputTokens`**: counts are disjoint; DeepSeek adapters subtract `prompt_tokens` cache fold back out.
+- **Treating catalog absence as request rejection**: `listModels` is advisory; consumers must not turn absence into a 404.
+- **Re-stringifying parsed tool args mid-stream**: keep `arguments` raw JSON end-to-end; partials via `argumentsDelta`.
+- **Hand-copying the version into `AppIdentity`**: source it from package metadata; all fields are public product facts (no secrets, paths, session ids).
+
+## Code Examples
+
+```ts
+type StreamChunk =
+  | { type: 'block-start'; index: number; blockType: ContentBlockType }
+  | { type: 'text-delta'; index: number; text: string }
+  | { type: 'reasoning-delta'; index: number; text: string }
+  | { type: 'tool-call-delta'; index: number; id: ToolCallId; name?: string; argumentsDelta: string }
+  | { type: 'block-end'; index: number; block: ContentBlock }
+  | { type: 'usage'; usage: TokenUsage }
+  | { type: 'finish'; reason: FinishReason; replayState?: ReplayEnvelope }
+```
+
+```ts
+abstract class LlmAdapter {
+  providerInfo(provider: string): LlmProviderInfo
+  providerRetryPolicy(_provider: string): ResolvedRetryPolicy | undefined
+  imageRequestPricing(_provider: string, _model: string): LlmImageRequestPricing | undefined
+  listModels(_provider: string): Promise<readonly LlmModelInfo[]>
+  resolveModel(provider, model, _signal?): Promise<LlmResolvedModelInfo>
+  async prepareCall(provider, model, signal?): Promise<PreparedAdapterCall>
+  abstract stream(options: GenerateOptions): AsyncIterable<StreamChunk>
+}
+```
+
+```ts
+ctx.llm.registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle
+ctx.llm.stream(options: GenerateOptions): AsyncIterable<StreamChunk>  // wrapped by 'llm/stream' waterfall
+ctx.credentials.resolve(ref): Promise<ResolvedCredential | undefined>
+ctx.credentials.modifyRecord(key, mutate): Promise<CredentialRecord | undefined>
+ctx.tokenMeter.measure(session, requestHeader?): TokenMeasurement
+ctx.clientModules.rebuilt(id): string | undefined   // ONLY entry point for bundle content changes
+```
+
+`/plugins/??<a>/client.js,<b>/client.js&rev=<rev>` — one-or-more-resource combo; `sourceMappingURL` mirrors as `.client.js.map` (Indexed Source Map v3); unknown/altered/stale lists → 404, other methods → 405.
+
+## Reference Tables
+
+| StreamChunk | payload |
+|---|---|
+| `block-start` | `index`, `blockType` |
+| `text-delta` / `reasoning-delta` | `index`, `text` |
+| `tool-call-delta` | `index`, `id`, `name?`, `argumentsDelta` |
+| `block-end` | `index`, `block: ContentBlock` |
+| `usage` | `usage: TokenUsage` |
+| `finish` | `reason: FinishReason`, `replayState?` |
+
+| LlmRuntime event | mode | purpose |
+|---|---|---|
+| `llm/stream` | waterfall | around every model call (retry/replay/routing); `next()` reaches adapter |
+| `llm/adapters-updated` | emit | registry topology changed; re-read `listProviders()` etc. |
+| `credentials/reference-updated(ref)` | emit | set/unset/external edit; ambient env changes never emit |
+| `credentials/record-updated(key)` | emit | `modifyRecord`/`deleteRecord`/external edit |
+| `authorization/settled(key, settlement)` | emit | every terminal attempt outcome, failures included |
+
+| Error code | meaning |
+|---|---|
+| `DUPLICATE_ADAPTER` | provider already has an adapter (all-or-nothing) |
+| `REGISTRATION_DISPOSED` | `replace()` after release |
+| `CONTEXT_WINDOW_EXCEEDED` | canonical overflow code; route on code, not provider text |
+| `EMPTY_RESPONSE` | terminal `stop` with zero content blocks — retryable |
+| `gateway/*` (e.g. `lookup-not-found`, `service-unavailable`) | `TypertGatewayErrorCode` — ordinary `RemoteError` codes |
+
+## Key Takeaways
+1. The `StreamChunk` closed union + `BlockAssembler` split means an adapter only emits well-formed chunks — block reassembly is never each adapter's problem.
+2. Tool-call `arguments` stay raw JSON strings end-to-end; `block-end` re-stringifies if the provider parsed them.
+3. Two sanctioned failure paths, one `LlmFailure` type: THROW from `stream()` (transport) or end with `finish {kind:'error'|'aborted'}` (in-band).
+4. Secrets live in `CredentialProvider`, not config — settings carry `CredentialRef` names only; resolve per operation.
+5. `TokenMeasurement` reprices images through `ctx.llm.imageRequestPricing` per route; `baseline.kind` is `usage` (reusable anchor) or `estimated`.
+6. A browser page with no valid `dsh.client` manifest cannot boot; `rebuilt(id)` is the sole path by which bundle content reaches the graph.
+
+## Connects To
+- **Ch04 cordis-fundamentals / Ch05 cordis-api**: all services here (`ctx.llm`, `ctx.credentials`, `ctx.tokenMeter`, `ctx.typert`, `ctx.clientModules`) are Cordis services; `llm/stream` is a waterfall, others emit.
+- **Ch06 architecture**: `ctx.llm.stream()` and the `llm/stream` waterfall sit in the turn flow.
+- **Ch14 subsystems-agent-loop**: the loop builds `GenerateOptions` from logged `EpochHeader`, logs raw chunks, and commits `assistant/attempt` on failure.
+- **Ch15 subsystems-tool-execution**: `ToolSchema` is the wire type; `ToolDefinition` (schema + `execute`) lives in dsh-tools.
+- **Ch16 subsystems-session-data**: the Session log embeds `AssistantStreamRecord[]` under `assistant/message` / `assistant/attempt`; `EpochHeader` is the token meter's request envelope.
+- **Ch18 subsystems-web-ui**: `ctx.clientModules` feeds the web stack's `webserver/index-inject`; `ctx.credentialsController` backs `ctx.remote.credentials`.
+- **Ch09 api-gateway**: typert's `TypertGateway` and `gateway/*` codes are the Remote-call dispatch seam.
+- **Ch10 config-catalog**: `LlmCallConfig` input fields and credential references surface in settings schemas.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch18-subsystems-web-ui.md

@@ -0,0 +1,142 @@
+# Chapter 18: Subsystems — Web Server, Client & UI Slots
+
+## Core Idea
+The Web surface is a layered pair: a dumb Host HTTP carrier (`ctx.webServer`) whose security comes entirely from the composition (Connection plugin: Host/Origin checks + browser-session auth on every `/api` route), and a browser-side Cordis application whose only sanctioned UI extension point is the typed Slots system (`ctx.slots.inject`/`register`) — never cross-plugin imports. Around this sit the interaction subsystems (settings, commands, user-questions, skills, feedback, webhook, schedule, terminals) that plugins consume via narrow registries.
+
+## Frameworks Introduced
+- **WebServer route registry**: named `exact`/`prefix` routes + one claimable fallback seat.
+  - When to use: serving plugin bundles, feature routes, webhook ingress on a second server.
+  - How: `ctx.webServer.register({kind, path, handler})` → disposer; duplicate `(kind, path)` throws. Match order: exact table → longest prefix → fallback. Fallback is one-owner (SPA dist server claims it).
+- **Index injection pipeline**: structured rows before raw HTML taps.
+  - When to use: putting anything into index.html (boot script, meta).
+  - How: answer `webserver/index-inject` emit with `IndexInjection[]` rows; `tapIndex(transform)` is the escape hatch, applied in registration order after structured rows.
+- **Browser boot (WebBootGraph)**: Host writes composed graph to `window.__DSH_BOOT__` + installs module-loader facade before parser-preloaded scripts.
+  - When to use: understanding plugin client-half load order.
+  - How: lazy CommonJS table; boot kernel prefetches `immediately` entries, mounts vendored Cordis Loader; Cordis service injection (not graph order) determines activation; final step is the sole `ctx.slots.renderSlot('root')`.
+- **Slots composition system**: typed React registry (`dsh-client-ui-slots`) + renderer (`dsh-client-ui-renderer`, only package using `useSyncExternalStore`/React contexts).
+  - When to use: any browser UI contribution from a plugin.
+  - How: declare via declaration-merge on `SlotMap` + `children` entry in the owning component; contribute via `ctx.slots.inject(key, callback)` → `ctx.slots.register({name, id, order}, Component)`.
+- **Settings namespaces**: one user document, per-plugin sections resolved as schema defaults → composition `base` → user layer.
+  - When to use: user-editable config distinct from `cordis.yml`.
+  - How: `ctx.settings.register(ns, schema, {base, applies, validate})` → `SettingsScope` (`get`/`watch`/`update`/`replace`).
+- **Layered provider registries** (skills): host + per-scope layers; nearest layer wins duplicate names outright; rank → provider order → local order within one layer.
+
+## Key Concepts
+- **Trusted hosts**: `dsh web` binds loopback by default and rejects `--host 0.0.0.0`; non-loopback exposure requires the composition to supply TLS/auth/Origin policy itself (carrier owns none).
+- **WebRouteKind**: `'exact' | 'prefix'`; paths absolute, no trailing slash; handlers own the full response lifecycle (may hold SSE open).
+- **Client models**: React-free mirrors of Host state (`ClientSessions → SessionManager → Session`, `ClientWorkspaceModel` → `ctx.workspaces`); UI packages never reproduce transport state in component stores.
+- **Cardinality axes**: `single` (one winner by priority) / `list` (id + order) / `keyed` (entryKey dispatch) / `chain` (first non-null `select(owner)` wins); scope: `root` / `session-maybe` / `session`.
+- **priority**: shadowing rank, lower renders first; reusing a shipped cell's id/key replaces its presentation — the sanctioned "override" mechanism (not import shadowing).
+- **SettingsDescriptor**: `{ns, schema, value, revision, base?, user?, applies, secrets?}`; `redactSecrets: true` mandatory on wire surfaces; writes use `expectedRevision` CAS and `SettingsPathOp` (`set`/`unset`) so redacted callers can't delete unseen secrets.
+- **TerminalSessionService**: exact-`Agent`-owned PTY sessions; one exclusive `TerminalSendOperation` per session; `TerminalWaitReason` (`stdin_read|inferred_idle|timeout|session_exit`) independent of session status.
+- **CommandResult**: `{kind:'success', text?, sourceEventSeq?}` or `{kind:'error', text}` — direct UI outcomes, not tool results; slash commands bypass the model entirely.
+- **SkillInvocationPolicy**: `modelInvocable`/`userInvocable` booleans from frontmatter keys `disable-model-invocation` and `user-invocable` (default true).
+- **Fire-and-forget webhook**: no queue, retry, dedup, or completion state; a `WebhookRule`'s `WebhookSessionRequest` creates an ordinary root Session whose first message is a user-role follow-up with `source.kind: "webhook"`.
+- **schedule/change**: version-1 Session event, the only durable Schedule authority; strict decoder rejects unknown versions/extra fields/reused ids.
+
+## Mental Models
+- Think of `ctx.webServer` as a dumb pipe: it knows no harness concepts; every feature route (including `/api`) is registered by another plugin. Security is a composition property, not a server property.
+- Use `ctx.slots.inject(key, cb)` when contributing to a slot you don't own; the callback re-runs for each owner declaration lifetime and is cleaned up when the owner collapses.
+- Think of settings layers as three-deep inheritance: schema defaults ⊂ composition `base` ⊂ user section; `replace({})` re-inherits everything (the reset path).
+- Treat a `single` or occupied keyed cell as a replacement point; use a fresh list `id` for additive extension.
+
+## Anti-patterns
+- **Runtime-importing another feature plugin's values**: hard boundary; only `import type` for declarations is allowed — cross-package UI goes through slots.
+- **Passing `ctx`, transport objects, or model services to slot components**: components get only derived props, hooks, store actions, inject faces; services stay in the `apply` closure.
+- **`replace()` from a redacted descriptor view**: silently deletes every secret the wire never returned; use path ops (`mutate`).
+- **Registering a second fallback handler or duplicate `(kind, path)` route**: throws — composition-level contract.
+- **Expecting webhook/schedule delivery guarantees**: webhook is at-most "repeated delivery may create repeated Sessions"; schedule is at-least-once (crash interval can duplicate reminder content); neither has receipts or completion state.
+- **`every` schedule catch-up enumeration**: only the latest due occurrence dispatches; missed intervals are never replayed.
+
+## Code Examples
+```ts
+// Slot injection (plugin client half)
+export const inject = ['slots']
+export function apply(ctx: Context): void {
+  ctx.slots.inject('conversation.session.header.actions', () =>
+    ctx.slots.register({
+      name: 'conversation.session.header.actions',
+      id: 'review', order: 100,
+    }, HeaderAction))
+}
+// Component props derive, never copy:
+type HeaderActionProps = PropsRuntime<'conversation.session.header.actions'>
+```
+```ts
+// Settings registration
+const scope = ctx.settings.register('my-plugin', MySchema, {
+  base: { feature: true },          // composition layer
+  applies: 'live',                  // or 'restart' (UI hint)
+  validate: v => { if (!v.ok) throw new Error('cross-field') },
+})
+scope.watch((next, prev) => ...)    // after commit, deep-equal-gated
+```
+```ts
+// WebServer route
+ctx.webServer.register({ kind: 'prefix', path: '/plugins', handler })
+// Index injection: answer 'webserver/index-inject' emit; or escape hatch:
+ctx.webServer.tapIndex(html => html.replace('</head>', snippet + '</head>'))
+```
+```ts
+// Webhook rule
+ctx.webhookRuntime.register({
+  id: 'nightly', kind: 'github',
+  run: async (delivery, signal) => ({
+    workspacePath, title, text, agentPreset, permissionPreset, model?,
+  }), // null = no session
+})
+```
+
+## Reference Tables
+| Slot (key extension surfaces) | Cardinality | Scope |
+|---|---|---|
+| `sidebar.brand.mark` / `sidebar.brand.name` / `sidebar.footer.action` | — | root |
+| `sidebar.workspaces` (+ `.directoryFlow`) | — | root |
+| `settings.general.item` | list | root |
+| `settings.models.provider-card` / `settings.models.footer` | list | root |
+| `settings.plugins.tab` (+ `settings.plugin.item`) | list | root |
+| `conversation.session.header.actions` | list | session-maybe |
+| `conversation.chat.node` (+ `assistant-actions`, `commandview`, `turnTail`) | — | session |
+| `tool.call.toolview` (+ `tool.call.images`, `tool.view.cordis`) | — | session |
+| `conversation.composer.bar` (+ `input.attachments/plan/model`) | list | session |
+| `conversation.input.left` / `.right` / `.overlay` / `.dock` | list | session |
+| `shell.overlay` | — | root |
+
+Live tree query: `cordis_inspect what:"client"`; catalog regenerated by `pnpm run gen-client-catalog`.
+
+| Skill discovery rank | Source | Root |
+|---|---|---|
+| 100 | project-dsh | `<projectRoot>/.dsh/skills` |
+| 200 | project-agents | `<projectRoot>/.agents/skills` |
+| 300 | custom | `Config.customSkillDirs` |
+| 400 | user-dsh | `<dshHome>/skills` |
+| 500 | user-agents | `<agentsHome>/skills` |
+| 600 | bundled | `Config.bundledSkillDir` |
+
+Project root = nearest `.git` ancestor, else cwd. Formats: `<name>/SKILL.md` bundle or flat `<name>.md`; no recursive `**/SKILL.md`.
+
+| WebServer config | Default | Notes |
+|---|---|---|
+| `host` | `127.0.0.1` | only `0.0.0.0` alternative; `dsh web` rejects it |
+| `port` | — | `0` = OS-assigned (read back via service `port`) |
+| `compression` | `'none'` | shipped Web bundle: gzip level 1 |
+| `compressionThresholdBytes` | 1024 | unknown-length streams always eligible |
+
+## Key Takeaways
+1. Add plugin UI exclusively through `ctx.slots.inject()` into shipped slot keys; check the generated client catalog (`cordis_inspect what:"client"`) for cardinality/scope/occupants before choosing an id.
+2. The HTTP carrier is deliberately dumb — any non-loopback deployment must supply auth/Origin/TLS at the composition layer; webhook ingress should mount a second isolated WebServer (GitHub review guide pattern).
+3. Never send a settings `replace` rebuilt from a redacted descriptor; wire surfaces always pass `redactSecrets: true` and edits travel as `SettingsPathOp`s with `expectedRevision`.
+4. Slot components receive no `ctx`; four injection channels are ranked: owner props (render-time values) → registration `inject` (entry-private callbacks/observables) → slot-level `inject` (owner-controlled capability, e.g. `useTurnData`) → declared store (shared mutable view state).
+5. Slash commands (`ctx.commands`) execute without creating model messages; lifecycle is logged as `command/run`/`command/done` direct appends with `sourceEventSeq` linking to richer domain events.
+6. Skills: nearest scope layer wins outright; body-only edits change later `skill` tool calls without emitting catalog messages (catalog carries only name + description, default 500 chars).
+7. Schedule is session-local: no external notification, no cold-session scheduling; dispatch waits for full Agent idleness and uses `followup()`, never `steer()`.
+
+## Connects To
+- **Ch 09**: the `/api` bridge, Connection generations, and Remote dispatch this server carries.
+- **Ch 07**: capability-seam pattern shared by web access, skills, and user-questions providers.
+- **Ch 02/03**: plugin packaging — client half registration and bundle serving via `/plugins/??<id>/client.js`.
+- **Ch 10**: config keys cited here (`customSkillDirs`, `bundledSkillDir`, `collectCacheMaxEntries`, `catalogDescriptionMaxLength`).
+- **Ch 13**: Session persistence barrier that schedule management and feedback sidecar writes wait on.
+- **Ch 16**: storage domains (`message_feedback`) and the persistence catalog indexing `schedule/change`.
+- **Ch 11**: tool contracts for `skill`, `schedule_*`, and `web_search`/`web_fetch` consumers.
+- **Ch 20**: `pnpm run gen-client-catalog` / `verify-cordis-catalog` in doc-sync.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch19-cookbook.md

@@ -0,0 +1,149 @@
+# Chapter 19: Extension Cookbook
+
+## Core Idea
+Every dsh product feature is a listener on a documented Cordis extension point — the microkernel claim, made checkable. The cookbook gives the exact files, code shapes, and verify commands for each extension recipe; no row modifies the agent loop.
+
+## Frameworks Introduced
+- **defineTool (typed tool contract)**: `ctx.tools.register(defineTool({ name, description, parameters, output: { schema, render }, execute(args, exec) }))`. Raw JSON-Schema `ToolDefinition`s are also accepted (that is how MCP tools arrive); `defineTool` is the typed first-party helper.
+  - When to use: any first-party model-facing tool.
+  - How: registration is `ctx.effect`-based (dispose unregisters; HMR-safe); schemas auto-flow into the system-prompt assembly.
+- **Tool execution policy waterfall**: `tools/pre-execute` (extensible allow/deny/ask) → `ctx.tools.guard()` (monotonic final deny) → `tools/execute` (wrap dispatch: deadline/retry/metrics) → `tools/post-execute` (transform result) → `tools/result` (observe immutable outcome).
+- **LlmAdapter**: `class MyAdapter extends LlmAdapter { async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> }`, registered via `ctx.llm.registerAdapter(['my-provider'], new MyAdapter())`. One adapter per route; duplicates throw; multi-route registration is all-or-nothing.
+- **TypertRemoteService / @Remote**: remote-API owner extends `TypertRemoteService`, marks methods `@Remote('list')`; failures are one `RemoteError` class + a `RemoteErrorDetailsMap` code table.
+- **dsh.client packaging**: a plugin's browser half ships via `dsh.client` in package.json + `exports["./client"]`, served by the client module system — appears on page with no web-app rebuild.
+
+## Key Concepts
+- **Waterfall**: reorderable middleware chain on a Cordis interception point; `next()` continues, a returned value short-circuits.
+- **Canonical value**: the single lossless-JSON value `execute` returns; snapshotted, validated, frozen, passed to `output.render(args, value)`.
+- **exec identity**: `callId`, `name`, `arguments`, `agent`, `token`, `signal`, optional `parent` are immutable through dispatch; only an around-dispatch wrapper may replace `exec.signal` (to impose a deadline), never remove it.
+- **presentationMeta**: `output.presentationMeta(args, value)` derives replayable JSON; core persists it on `tool/result` for cards.
+- **Render-intent union**: `presentCall`/`presentResult` return a `card`-tagged view (`generic`/`terminal`/`diff`/`read`/`search`/`web`); pure functions of args (+result) — run on replay, so NO I/O/state/clock.
+- **RemoteResult<T>**: client-remote call result; branch `if (!result.ok)`, discriminate by `code` (narrows `details`), never `instanceof`.
+- **Vendoring**: pinned source under `vendor/<dir>/` (not an npm dep); publishable release member (no `private`, `publishConfig.access: public`).
+- **Role suffix**: `Controller`/`Store`/`Directory`/`Presenter`/`Registry`/`Runtime`/`Resolver`/`Binder`/`Engine`/`Policy`/`Executor`/`Gateway`/`Provider`/`Backend`/`Handle`/`Config`/`Service` — name the stable current responsibility, not the first implementation.
+- **settingsScope**: browser-side `ctx.settingsScope.bind({ namespace })` fences each write with the revision it read; `set(field,value)`/`unset(field)`.
+- **stackEntry**: GitHub's authoritative stacked-PR object — `PullRequest.stack` + `stackEntry.position` prove recognition; base branches establish order.
+
+## Mental Models
+- **Think of a permission gate as the reorderable policy layer**: hook plugins return a typed decision from `tools/pre-execute`; sandbox, permission, and plan-mode plugins reuse the same point. A "native hook" is an ordinary Cordis plugin — no external protocol.
+- **Use `tools/result` for observation, `tools/post-execute` only to transform**: observing the immutable final outcome vs. replacing value/content/attaching context.
+- **Think of the namespace as the join key**: the Host serves a settings namespace; the Plugins tab keys its card on that namespace; both halves register the same string → auto-paired, no repo change.
+- **Think of a Remote call as non-throwing**: it returns `RemoteResult<T>`, never rejects; an assembly mistake should crash, not a defensive catch.
+
+## Anti-patterns
+- **Parsing prose for ids**: PTC mode / background branches must never recover a `jobId` from human prose — return `{ kind: 'background', jobId }` as the canonical handle.
+- **UI formatting in the model result**: fenced `console` blocks, diffs, relativized paths belong in `presentationMeta` + card presenters, not `output.render`/canonical value.
+- **Ad-hoc key files in adapters**: secrets are cordis-native (schemastery Config with env fallback, `!!js process.env.MY_KEY`); never read key files in code.
+- **Silently dropping unsupported options**: throw `LlmError(..., 'UNSUPPORTED_OPTION')` rather than ignore a `GenerateOptions` field the provider can't honor.
+- **`--force` on a rewritten stack push**: must be lease-protected, abort rather than overwrite a concurrently advanced remote head.
+- **Copying the `api/remotes` split**: new packages never copy its repo-specific Host/Client phase split; an ordinary package joins exactly one aggregate.
+- **Deep-comparing Remote errors**: assert `code` + details via `remoteErrorOf(...).toMatchObject`, never `toEqual` or `instanceof`.
+
+## Code Examples
+
+```ts
+// Tool — minimal shape (typed args, canonical value, signal)
+export const name = 'my-tool'; export const inject = ['tools']
+export function apply(ctx: Context) {
+  ctx.tools.register(defineTool({
+    name: 'read_file', description: 'Read a file from disk.',
+    parameters: { path: { type: 'string', required: true, description: 'Absolute path' } },
+    output: { schema: { type: 'string' }, render: (_a, v) => [{ type: 'text', text: v }] },
+    async execute(args, exec) {
+      return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
+    },
+  }))
+}
+```
+
+```ts
+// Hook (permission gate)
+export function apply(ctx: Context) {
+  ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
+    if (!(await isAllowed(exec))) return { kind: 'deny', reason: 'Denied by policy.' }
+    return next()
+  })
+}
+```
+
+```ts
+// Remote API owner + failure table
+export class NotesController extends TypertRemoteService {
+  constructor(ctx: Context) { super(ctx, 'notesController', { namespace: 'notes' }) }
+  @Remote('list')
+  async remoteExportList(agent: Agent, signal: AbortSignal): Promise<NoteRow[]> { return this.list(agent, signal) }
+}
+declare module '@deepseek-ai/dsh-typert-protocol' {
+  interface RemoteErrorDetailsMap {
+    'note/not-found': { readonly noteId: string }
+  }
+}
+throw new RemoteError('note/not-found', `no note "${noteId}"`, { noteId })
+```
+
+```ts
+// Client remote consume
+export const inject = ['remote', 'remote.notes']
+const result = await ctx.remote.notes.list()
+if (!result.ok) { if (result.error.code === 'note/not-found') return []; throw result.error }
+```
+
+```jsonc
+// Browser-half packaging
+{
+  "exports": {
+    ".": { "types": "./lib/types/index.d.ts", "default": "./lib/index.js" },
+    "./client": { "types": "./lib/types/client/index.d.ts", "default": "./lib/client.js" }
+  },
+  "dsh": { "client": { "platform": "web", "inject": ["@deepseek-ai/dsh-client-ui-settings-plugins"] } }
+}
+```
+
+## Reference Tables
+
+### Recipe skeleton (goal → files → key shape → verify)
+
+| Recipe | Files touched | Key shape | Verify |
+|---|---|---|---|
+| **New workspace package** | `packages/<group>/<pkg>/{package.json,tsconfig.json,src/index.ts,README.md}` + `tsconfig.{host,client}.json` references | `private:true`, cordis in peer+dev, schemastery in `dependencies`, `files` = `lib/index.js` + `lib/types/**/*.d.ts`; `.ts` import specifiers | `pnpm install` → `pnpm run doc-sync` → `pnpm run constraints && pnpm run typecheck && pnpm run lint` → `pnpm run build && pnpm run hygiene` |
+| **Vendored package** | `vendor/<dir>/{package.json,tsconfig.json,src/,README.md}` + `tsconfig.base.json` paths + `tsconfig.host.json` ref (before `packages/*`) + `vendor/README.md` manifest row | rescope name, keep exports/type, `publishConfig.access:public` (no `private`), `outDir: lib/types`, strictness relaxations | `pnpm install` → `pnpm run typecheck` → `pnpm run build && pnpm run constraints`; stage manifest alongside source (`scripts/check-vendor-manifest.sh`) |
+| **Add a tool** | one `src/index.ts` plugin; card methods `presentCall`/`presentResult` | `defineTool` + `execute(args, exec)` returning one canonical value | repository testing policy + owning package test docs |
+| **Settings card** | Host `src/` + browser `src/client/` in one package, `dsh.client` export | Host `settingsCtx.settings.installSection(ctx, NS, Config, config, {validate, setSource, onChange})`; browser `ctx.slots.inject('settings.plugin.item', …)` | no repo change; appears when `cordis.yml` mounts it |
+| **LLM adapter** | `packages/llm/llm-<name>/` | `extends LlmAdapter` + `stream()` generator + `registerAdapter` | repository testing policy (real-provider checks) |
+| **Remote API** | Host controller (`packages/api/`) + client consumer | `TypertRemoteService` + `@Remote` + `RemoteErrorDetailsMap`; client `inject ['remote','remote.<ns>']` | `pnpm run build:lib` (after signature/code-table/namespace change) → `pnpm run typecheck` → `npx vitest run <owner> <client>` |
+
+### LLM adapter protocol obligations
+| Obligation | Rule |
+|---|---|
+| Ordering | Emit `usage` BEFORE `finish`; emit NOTHING after `finish` |
+| Tool args | RAW JSON strings end-to-end; stream as `argumentsDelta`; re-stringify at `block-end` |
+| Block index | Allocate in first-seen stream order; reuse for every delta |
+| Errors | THROW (`LlmError` + stable code) OR `finish {kind:'error'|'aborted'}` — pick per class, document |
+| Unsupported | `LlmError(..., 'UNSUPPORTED_OPTION')` for unhonoable `GenerateOptions` |
+| Replay | `finish.replayState` = minimal lossless-JSON projection; validate when rebuilding history |
+
+### Remote failure code placement
+| Situation | Declare where |
+|---|---|
+| One producer | In the producing package, next to the throw |
+| Several producers | Lowest domain package both depend on |
+| Carrier codes `gateway/bad-request|cancelled|internal` | In protocol/gateway — use, never copy |
+| Never crosses wire | Out of the code table; caller's own type |
+
+## Key Takeaways
+1. Every extension is a listener on a documented point; `ctx.effect`-based registration means vendored HMR "just works".
+2. A tool's `execute` returns one canonical value; keep human prose in `output.render` and replayable UI state in `presentationMeta` + card presenters — they are pure (replay-safe).
+3. Gate long work through `ctx.jobs.start({ kind, label, owner: exec.agent, run })`; a successful background branch returns `{ kind: 'background', jobId }`, never prose.
+4. Register a new package by copying `packages/core/tools` and joining exactly one aggregate (`tsconfig.host.json` OR `tsconfig.client.json`); `pnpm run constraints` enforces the package.json invariants.
+5. Vendor upstream Cordis packages as pinned `vendor/` source, not npm deps; stage the manifest alongside source or the pre-commit hook fails.
+6. Remote failures are one `RemoteError` + code table, consumed as `RemoteResult<T>`; discriminate by `code`, not `instanceof`.
+7. On a stacked-PR chain, fix the introducing PR then propagate up-stack (`gh stack rebase`/`gh stack push`), one worktree per PR, distinct commit per fix, never raw `--force`.
+
+## Connects To
+- **Ch 02**: `defineTool`/`ctx.tools.register` is the plugin-basics authoring path.
+- **Ch 05**: `ctx.on`/`ctx.effect`/waterfall semantics are the Cordis API these recipes build on.
+- **Ch 06**: the architecture doc owns the system + extension-point map that the feature→mechanism table summarizes.
+- **Ch 09**: decorator semantics, lookup resolution, and the `/api` route (Remote mechanism) live in the API Gateway reference.
+- **Ch 11**: `defineTool` soft-validation, `output.render`, and the card union feed the tool catalog.
+- **Ch 15**: `tools/pre-execute`/`execute`/`post-execute`/`result` and the background-job runtime are the tool-execution subsystem.
+- **Ch 20**: repository testing policy owns coverage/real-provider checks each recipe defers to.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch20-development-testing.md

@@ -0,0 +1,87 @@
+# Chapter 20: Development & Testing Workflow
+
+## Core Idea
+dsh development runs on a two-aggregate TypeScript build (Host/Client), a tiered test policy whose highest-value tier is the keyless real-entry-path smoke, and a doc-standard (AGENTS.md) that enforces "one home per fact" through mechanical gates.
+
+## Frameworks Introduced
+- **Two-aggregate tsconfig solution**: `tsconfig.json` (solution root) → `tsconfig.host.json` + `tsconfig.client.json` programs sharing `tsconfig.base.json` as a paths facade.
+  - When to use: any new package registration, build-script, or program-seeding work.
+  - How: register a package in exactly one aggregate; seed `ts.Program` scripts with the aggregate, never the root (flattening both collides the cordis `Context` declaration merges).
+- **Face-phased build (`DSH_BUILD_FACE`)**: `tsc -b tsconfig.host.json` → `tsdown --env.DSH_BUILD_FACE host` → `tsc -b tsconfig.client.json` → `tsdown --env.DSH_BUILD_FACE client` → `pnpm run build:web`.
+  - When to use: complete builds; `pnpm run build` wraps it and embeds version + 7-char commit + dirty marker, writing a build record that release packing and web tests validate.
+  - How: `pnpm run build`; Typert (Host reflection + Remote projection) runs only in the host tsdown pass.
+- **Testing tiers**: unit → coverage gate → real-API e2e → expected-output → session snapshot → web browser snapshot.
+- **Doc tier taxonomy**: root AGENTS.md / architecture / subsystems / Agent Notes / postmortems / cookbook / user / package README / generated references / skills — each fact has exactly one home.
+- **Type-equivalence fences**: ` ```ts type-equiv ` / ` ```ts public-api ` registered in `scripts/type-equiv.manifest.json`.
+  - When to use: pasting source declarations into docs.
+  - How: `{doc, symbol, source}` (+`"projection": "public-api"`); `pnpm run verify-type-equiv` (in doc-sync) fails on drift.
+
+## Key Concepts
+- **Host/Client aggregates**: one program per side because both declaration-merge cordis `Context` under the same keys; collision exists only inside a `ts.Program`, never in module resolution.
+- **Shared leaves**: `host/webserver`, `compaction/compaction`, `typert/registry` registered in both aggregates so each side type-checks the same source.
+- **Split packages**: six packages (e.g. `api/remotes`, `session-log-export`) carry separate Host/Client leaf tsconfigs; the workspace `constraints` gate auto-discovers them via presence of both leaf configs.
+- **Source plane**: vitest resolves workspace imports via `tsconfig.base.json` paths to `src`, never through package `exports` to built `lib/` (avoids duplicate module singletons).
+- **Coverage gate**: per-file 100% on `packages/*/*/src`; an uncovered line is usually dead code to delete, not a missing test.
+- **With-key policy**: "we are DeepSeek — do not ration real-API tests"; suites self-skip without keys so keyless CI stays green.
+- **Snapshot fixture naming**: `session[.vN].jsonl` parents, `session.<ordinal>[.vN].jsonl` children; v0 suffixless, versions lowercase `.vN`; `snapshot.yml` declares profile/composition/policy.
+- **TODO markers**: `FIXME` (release blocker) > `TODO` (soon) > `XXX` (someday).
+- **Lefthook hooks**: pre-commit (staged pairing records, Oxlint staged profile, THIRD_PARTY_NOTICES, whitespace, vendor manifest guard), pre-merge-commit, pre-push (`pnpm run typecheck`). Hooks deliberately do not run tests/builds — CI owns exhaustive coverage.
+
+## Mental Models
+- Think of the repo as two type worlds sharing one paths facade: resolution may cross faces freely, but programs may not.
+- Use a smoke test (boot shipped profile, one prompt, check the world) when you need to catch "green unit tests, broken product"; it needs no key when the operation doesn't call the model.
+- Treat snapshot refresh as fixture production, not correctness review: semantic assertions must exist independently of expected outputs.
+- Treat doc budgets as guardrails, not reduction targets: at/below target keep ≥5% headroom; above target freeze the ceiling until relocation/condensation.
+
+## Anti-patterns
+- **Hand-mounting plugins in tests** (`ctx.plugin({...})`): bypasses the Loader; cannot validate how the plugin actually loads.
+- **Verifying the agent's self-report**: assert by re-running the command or re-reading the file externally; keyword probes let a cheating agent pass.
+- **Adding `include`/`files` to `tsconfig.base.json`**: leaks into every extending package and narrows the match-all facade.
+- **Restating catalogs/JSDoc/status in prose**: hand-restated inventories rot; link or generate.
+- **Narrating change history in durable prose** ("previously", "now", PR numbers): document the live mechanism; put stories in commits/Agent Notes/postmortems.
+
+## Code Examples
+```sh
+pnpm install            # also installs worktree-local Lefthook + pairing merge driver
+pnpm run typecheck      # setup complete when this exits 0
+pnpm run build          # tsc host → tsdown host → tsc client → tsdown client → build:web
+pnpm run check:all      # opt-in comprehensive local gate set
+pnpm dsh --profile headless "summarize this workspace"   # needs DEEPSEEK_API_KEY
+```
+```ts
+// namespace plugin form — never add `export default apply`
+export const name = 'acp'
+export const inject = ['agents', 'sessions', 'sessionPersistence']
+export function apply(ctx: Context, config: AcpConfig): void { /* … */ }
+```
+
+## Reference Tables
+| Tier | Command | Key rule |
+|---|---|---|
+| Unit | `pnpm run test` | vitest, tests beside code; every registry gets an HMR-safety dispose test |
+| Coverage | `pnpm run test:coverage` | per-file 100% on `packages/*/*/src` |
+| Real-API e2e | `pnpm run test:e2e` | self-skips per missing key (`DEEPSEEK_API_KEY`, `EXA_API_KEY`, …) |
+| Expected output | `pnpm run test:expected` | keyless assembled CLI/process expectations |
+| Snapshot | `pnpm run test:snapshot[:record|:refresh]` | review every diff |
+| Web snapshot | `pnpm run test:web` | Linux PR gate; CI forces read-only replay |
+
+| Env var | Purpose |
+|---|---|
+| `DEEPSEEK_API_KEY` | real-API e2e + demos |
+| `DEEPSEEK_BASE_URL` | optional, defaults to public API |
+| `DSH_BUILD_FACE` | host/client phase selector for tsdown configs |
+| `DSH_SNAPSHOT=replay` | CI-forced read-only web snapshot mode |
+
+## Key Takeaways
+1. Register new packages in exactly one tsconfig aggregate; seed repo-wide programs from an aggregate, never the solution root.
+2. Preselect the smallest checks covering your changed surface; `pnpm run check:all` is opt-in, not an agent instruction.
+3. Tests resolve source, not builds: built artifacts are consumed only via explicit `lib`-mode subprocesses and built smokes; run profile subprocesses through the shared dual-mode launcher, never hand-written `--import tsx`.
+4. Every non-trivial model/protocol/UI change adds a keyless recorded-session scenario in the same PR; snapshot evidence is not replaced by package or mock-only tests.
+5. Docs: one home per fact, one physical line per paragraph, fenced `ts` must compile, pairs update together; classify tutorial vs reference before writing.
+6. When the doc-budget gate goes red: relocate → condense → only then raise the ceiling with a justified manifest diff.
+
+## Connects To
+- **Ch 06**: architecture.md's place in the doc tier taxonomy.
+- **Ch 13–18**: subsystems pages own the type definitions that type-equiv fences mirror.
+- **Ch 21**: postmortems are the failure lessons behind many testing rules codified here.
+- **Ch 22**: the bilingual pairing contract is part of doc-sync gates contributors run.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch21-postmortems.md

@@ -0,0 +1,82 @@
+# Chapter 21: Postmortems (Failure Lessons)
+
+## Core Idea
+dsh postmortems record process failures — why every safety net missed a shipped bug — and each one motivates durable guardrails; the lessons are reusable rules for plugin exports, config interpolation, agent acceptance loops, and process attribution.
+
+## Frameworks Introduced
+- **Postmortem format**: Executive summary (30-second paragraph) → Summary / Timeline / Root cause / Guardrails.
+  - When to use: a bug is subtle (non-obvious mechanism), systemic (gap in tests/tooling/conventions), and costly to rediscover — and it reached a real user, merged PR, or release.
+  - How: chronology records evidence, not teaching sequence; link the guardrails (tests, AGENTS.md rules) the postmortem motivated.
+- **Namespace-plugin/export invariant** (0001): cordis `Loader.unwrapExports` prefers `exports.default ?? exports`.
+- **`!!js` interpolation scope** (0002): JS expressions evaluate only in plugin `config`; entry metadata like `disabled` stays literal.
+- **Acceptance-target identity** (0003): an agent's verification must name one exact origin and observe the change there externally.
+- **Conjunction-of-evidence classification** (0004): `RunnerFailureRule` = allowed exit codes + per-line fatal signatures + exact informational exclusions.
+
+## Key Concepts
+- **Agent Note vs postmortem**: an Agent Note records a deliberate decision and rejected alternatives (forward-looking); a postmortem records a failure (backward-looking).
+- **`unwrapExports` trap**: a default export resolves to the bare function, discarding sibling `name`/`inject`/`Config`; the plugin fiber is built with empty `inject`.
+- **Ancestor-only fiber walk**: the `reflect.ts` `get` handler walks only ancestors; a sibling-branch service read via `ctx.<name>` through a foreign shadow throws at root. `ctx.get(name)` uses the topology-independent global isolate-keyed store.
+- **Top-level bypass**: from test code (`ctx.fiber.runtime === null`), property reads bypass the fiber walk entirely — masking shadow-path failures.
+- **Expression-object truthiness**: a parsed `!!js` value in `disabled` is a truthy object → always disabled; no load-time diagnostic because the YAML tag is valid.
+- **`window.__DSH_BOOT__`**: injected only by the full `dsh web` host; bare Vite HTTP 200 is transport readiness, not application readiness.
+- **Launcher contract (Landlock)**: exit 125 + fatal `landlock-run:` line = launcher failure; exact notice `landlock-run: partial enforcement (older Landlock ABI)` = informational before a normal child run.
+- **In-band stderr**: a confined child can deliberately reproduce a runner's fatal line and exit status; a shared prefix is not a protocol.
+
+## Mental Models
+- Use a keyless real-Loader e2e when the headline operation doesn't call the model — it belongs in CI, not behind a key gate.
+- Think of snapshot refresh as recording whatever the system now does; semantic impossibilities (e.g. `UNKNOWN_TOOL`) need assertions independent of expected outputs.
+- Think of every verification fact (source edit, build, HTTP 200, boot manifest, user's page) as separate; acceptance = the exact origin + external observation.
+- Use overlays (`fs.cordis.yml`) when you need conditional composition; runtime permission presets cannot mount/unmount plugin fibers.
+
+## Anti-patterns
+- **`export default apply` in a namespace plugin**: Loader unwraps to the bare function and drops `inject` → `cannot get property "x" without inject` at load time.
+- **`ctx.<optionalService>` for services not in `static inject`**: ancestor-only shadow walk throws; use `ctx.get(name)` (inactive backend reads as `undefined`).
+- **`disabled: !!js ...` on a Loader entry**: never evaluated; entry stays permanently disabled.
+- **Launching a replacement server to verify a change**: a second service proves only itself; the existing page may have already picked up rebuilt artifacts.
+- **Classifying failure by stderr substring + nonzero exit**: joins unrelated facts from different processes; ordinary child exits (ripgrep's 1 = no matches) get mislabeled `SANDBOX_UNAVAILABLE`.
+- **Trusting an elegant theory over the trace**: instrument the actual mechanism (fiber walk, real subprocess) before reasoning.
+
+## Code Examples
+```ts
+// 0001 fix — delete the stray line:
+// export default apply            // ← Loader unwraps .default, drops inject
+
+// 0001 fix #2 — optional service read:
+// this.ctx.sessionPersistence     // throws through foreign shadow
+this.ctx.get('sessionPersistence') // topology-independent lookup
+```
+```ts
+// unwrapExports (vendor/loader): prefers .default
+exports = exports.default ?? exports
+if (!exports.__esModule) return exports
+return exports.default ?? exports
+```
+```ts
+// RunnerFailureRule (0004 guardrail):
+{ allowedExitCodes?: number[],      // Landlock: [125]
+  fatalSignatures: string[],        // per-line, case-insensitive
+  informationalExclusions: string[] } // exact lines, e.g. the partial-enforcement notice
+```
+
+## Reference Tables
+| # | Incident | Root cause | Durable lesson |
+|---|---|---|---|
+| 0001 | ACP crashed on connect (`session/new`, `session/load`) | `export default apply` dropped `inject`; shadow-walk read of sibling service | Namespace exports and default export are mutually exclusive; optional services via `ctx.get()`; test the real Loader path |
+| 0002 | Filesystem snapshot tools always disabled | `!!js` only interpolates `config`, not `disabled`; truthy expression object; snapshot refresh accepted `UNKNOWN_TOOL` | Verify which fields are interpolated; snapshot ≠ correctness review; conditional composition via overlays |
+| 0003 | Web agent validated a replacement server, not the GUI | No model-visible identity for current GUI/URL/mode; bare Vite 200 treated as success | `DSH_WEB_URL` + `app:web-surface` prompt; reject standalone Vite before listen; acceptance names the exact origin |
+| 0004 | Landlock notice misclassified child failures as `SANDBOX_UNAVAILABLE` | one substring signature + any nonzero exit; bash search replaced structured errors with `SEARCH_FAILED` | Conjunction of independent evidence; exact informational exclusions; preserve structured seam failures |
+
+## Key Takeaways
+1. 100% line coverage proves lines ran, not that the feature works as shipped — hand-mounted tests bypass both the Loader and fiber topology.
+2. A no-key test of the real entry path (boot the profile through Loader, assert the first RPC) catches load-shape bugs unit tests structurally cannot.
+3. `TSX_TSCONFIG_PATH` in subprocess spawns makes source resolution cwd-independent — otherwise imports silently fall back to stale built `lib/`.
+4. Permission controls describe only the capabilities they govern; bash sandbox presets cannot retroactively confine in-process filesystem providers.
+5. A regression test must be able to fail for the reported mechanism: process timeout ≠ fail-fast; post-exit port availability ≠ never bound.
+6. Platform-dependent behavior (Landlock ABI) needs a deterministic fake at the native boundary plus one assembled product-path snapshot; a self-skipping real-kernel test cannot carry the regression.
+
+## Connects To
+- **Ch 04/05**: cordis fibers, shadows, `ctx.get` semantics behind 0001.
+- **Ch 10**: `!!js` interpolation scope in cordis config entries (0002).
+- **Ch 15**: tool execution and `UNKNOWN_TOOL` guardrail.
+- **Ch 18**: Web GUI runtime modes, HMR, `__DSH_BOOT__` (0003).
+- **Ch 20**: testing rules ("test the real entry path", "verify the world") codified from these incidents.