stitchkit 0.104.1 → 0.105.0

package/llms-full.txt

@@ -59,6 +59,7 @@ own, recorded as an ADR.
 | `stitchkit/tools/invoker` | server | stable | peer-free `createToolInvoker` over the canonical contract tool runner |
 | `stitchkit/tools/connections` | server (Bun or Node) | evolving | consume external MCP servers and a bounded OpenAPI subset — typed reauthorization, a per-request host fence and per-call credentials |
 | `stitchkit/cli` | server | stable | `createCli` / `createCliInvoker` — runtime and strict NodeNext declarations without MCP SDK / `ai` |
+| `stitchkit/cli/publish` | build and release tooling (Bun or Node, POSIX) | evolving | `publishCli` — commit a verified CLI distribution and move its public manifest last; see [CLI guide](cli.md#publishing-a-complete-version) |
 | `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
 | `stitchkit/process` | server (Bun or Node, POSIX) | evolving | finite native commands, byte sinks, bounded capture and process-group cancellation |
 | `stitchkit/files/packaging` | build time (Bun or Node) | evolving | installed native asset graph, integrity and Bun packaging plugin; no runtime install policy |
@@ -73,25 +74,24 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 49 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 50 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the managed-resource conformance kit |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 49 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 50 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
 | `stitchkit/agent-runtime/coding-tools` | server (Bun or Node) | evolving | bounded host-authorized direct file and shell tools; a root boundary, not an OS sandbox |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
 | `stitchkit/agent-runtime/browser` | browser + server | evolving | canonical agent records, events, reconnect cursor and optional conversation controller |
-| `stitchkit/agent-runtime/harness-tools` | server | evolving | full mountAgent configuration with the current run fence |
-| `stitchkit/agent-runtime/react` | browser + server | evolving | React subscription to an application-owned agent controller |
-| `stitchkit/agent-runtime/realtime` | server (Bun or Node) | evolving | authorized agent control over the existing Socket.IO server |
+| `stitchkit/agent-runtime/react` | browser + server | evolving, experimental: no committed consumer | React subscription to an application-owned agent controller |
+| `stitchkit/agent-runtime/realtime` | server (Bun or Node) | evolving, experimental: no committed consumer | authorized agent control over the existing Socket.IO server |
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 12 of the 49 minors since 0.56.2, most recently 0.104.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 13 of the 50 minors since 0.56.2, most recently 0.105.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -197,7 +197,6 @@ map — feature → packages:
 | MCP / agent adapters (`stitchkit/tools`) | `@modelcontextprotocol/server` `ai` |
 | Agent application runtime (`stitchkit/agent-runtime`) | `ai` |
 | Headless Agent harness (`stitchkit/agent-runtime/harness`) | `ai` |
-| Harness tools (`stitchkit/agent-runtime/harness-tools`) | `ai` `@modelcontextprotocol/server` (tool declarations) |
 | Agent coding tools (`stitchkit/agent-runtime/coding-tools`) | — |
 | OpenRouter runtime adapter (`stitchkit/agent-runtime/openrouter`) | `ai` `@openrouter/ai-sdk-provider` |
 | SQLite agent store (`stitchkit/agent-runtime/sqlite/bun` or `/node`) | — (runtime built-in) |
@@ -1207,7 +1206,7 @@ Three boundaries worth knowing:
 
 - A field of another scope is not a compile error on access — `RuntimeContext`
   keeps its `[key: string]: unknown` index signature (transports write through
-  it). It degrades to `unknown`, so it can no longer pose as a `string`; using it
+  it). It degrades to `unknown`, so it cannot pose as a `string`; using it
   in a typed position fails.
 - The map states what **your** `beforeHandle` / `createAuthHook.inject` puts on
   the context. The framework does not verify a hand-written claim (→ ADR 0075) —
@@ -4229,15 +4228,17 @@ For example, an optional object `value` in `single` and a required array `value`
 in `group` advertise:
 
 ```text
-When kind = group: Two to ten references.
 When kind = single: One reference.
-Available if kind = group | single. Required if kind = group
+When kind = group: Two to ten references.
+Available if kind = single | group. Required if kind = group
 ```
 
 A third branch without `value` is absent from those labels. The object and array
 retain their separate shapes; the array's minimum length does not apply to the object.
-Discriminator values, branch explanation labels and joined property order are
-deterministic under branch reordering. → ADR [0221](../decisions/0221-flat-field-explanations-retain-branch-meaning.md).
+Discriminator values, branch explanation labels, enum values and joined
+properties keep the order of their first appearance across the variants, so the
+order you declare is the order the model reads. Alternatives of different kinds
+keep one canonical order, so one declaration always yields one document. → ADR [0221](../decisions/0221-flat-field-explanations-retain-branch-meaning.md).
 
 **A field several variants declare keeps its type.** Flattening puts every
 variant's fields side by side, so a key two variants share has to be advertised
@@ -4487,6 +4488,18 @@ An explicit `AppError.retryable` boolean also survives this remote hop. `false`
 `true` on409 remain the application's recommendation through HTTP, CLI, MCP and AI tools.
 Absent metadata keeps the previous defaults and does not alter HTTP transport retries.
 
+A remote failure that carries no stitchkit error envelope — an HTML `503` from a proxy
+during a deploy, a `429` from a rate limiter, a `404` page, a refused connection — keeps
+what the caller can act on and drops what it must not see. A response with a status
+becomes `HTTP_ERROR` with that status and a fixed message; a failure with no response
+becomes `CONNECTION_REQUEST_FAILED` (`502`). Neither carries `details`: the upstream
+body, URL and credentials stay in the raw cause that `onToolError` and `AgentToolError.cause`
+expose in-process. One rule decides `retryable` for every origin: the declared value wins,
+otherwise the status decides (`408`, `429`, `502`, `503`, `504` are retryable, as for any
+local tool). A call the caller cancelled (`REQUEST_ABORTED`) declares `retryable: false`;
+a deadline the remote client hit (`REQUEST_TIMEOUT`, `408`) follows the status like a
+`408` from a local handler.
+
 ## Structured output
 
 When a contract endpoint or runtime tool declares `output`, its MCP tool
@@ -5147,15 +5160,6 @@ identical. Write the handler once; it serves every surface.
 # Guide: Agent application runtime  (docs/guide/agent-runtime.md)
 ==============================================================================
 
----
-title: "Agent application runtime"
-description: Configure Stitchkit's optional durable history, stream loop, run coordination and managed-tool fencing.
-type: architecture
-status: active
-created: 2026-08-22
-updated: 2026-10-02 16:28 +07:00
----
-
 # Agent application runtime
 
 > **Maturity: evolving.** This surface is still finding its shape and may be
@@ -6697,20 +6701,6 @@ existing runtime configurations need no migration.
 # Guide: Agent composition  (docs/guide/agent-composition.md)
 ==============================================================================
 
----
-title: "Agent composition without a second runtime"
-description: "Compose contract tools, authenticated realtime control, React views and exact-run behavioral checks."
-type: architecture
-status: active
-created: 2026-09-30 22:45 +07:00
-updated: 2026-09-30 23:03 +07:00
-participants:
-  - role: authored
-    harness: Codex
-    model: GPT-6
-    at: 2026-09-30 22:45 +07:00
----
-
 # Compose an agent application
 
 Use these pieces when an application wants the existing headless harness and a generic
@@ -6726,7 +6716,7 @@ import {
   createAgentHarnessFileResources,
   createHeadlessAgentHarness,
 } from 'stitchkit/agent-runtime/harness';
-import { createAgentHarnessTools } from 'stitchkit/agent-runtime/harness-tools';
+import { composeToolLifecycle, mountAgent } from 'stitchkit/tools';
 
 const resources = createAgentHarnessFileResources({
   roots: [{ id: 'guide', kind: 'instruction', path: instructionRoot }],
@@ -6735,27 +6725,31 @@ const resources = createAgentHarnessFileResources({
 const harness = createHeadlessAgentHarness({
   protocol, store, models, promptBudget,
   resources,
-  tools: createAgentHarnessTools(({ context, run }) => ({
-    services: [catalogService],
-    context: { ...context, messageId: run.assistantMessageId },
-    runtimeTools: resources.runtimeTools,
-    lifecycle: authorizeTools,
-    hooks: observeTools,
-  })),
+  tools: ({ context, run, toolFenceLifecycle }) =>
+    mountAgent([catalogService], {
+      context: { ...context, messageId: run.assistantMessageId },
+      runtimeTools: resources.runtimeTools,
+      lifecycle: composeToolLifecycle(authorizeTools, toolFenceLifecycle),
+      hooks: observeTools,
+    }),
 });
 ```
 
-The factory composes application authorization then the runtime fence through `mountAgent`.
-The optional harness-tools leaf preserves the complete tool types, including MCP presenter
-declarations; install the same `ai` and `@modelcontextprotocol/server` peers as for
-`stitchkit/tools`. The base harness stays AI-only. Every mount option remains available, including registry, runtime tools, extension,
-coercion, output stripping, hooks and durability. Async per-run configuration is supported.
-The original tools callback still accepts arbitrary typed AI SDK tools and prepareStep.
+`tools` is called for each run with its validated context. Mount through `mountAgent` and
+compose your authorization with the run's `toolFenceLifecycle` by `composeToolLifecycle`: the
+fence rejects a call from a run that no longer owns the conversation, and it must run exactly
+once. Every mount option remains available, including registry, runtime tools, extension,
+coercion, output stripping, hooks and durability, and the callback may be async. The same callback
+still accepts arbitrary typed AI SDK tools and prepareStep. `stitchkit/tools` needs the same `ai` and
+`@modelcontextprotocol/server` peers as any `mountAgent` use; the base harness stays AI-only.
 The resource reader is explicitly selected: filtered allowlists do not gain tools merely
 because a loader exists. Root IDs, kinds, provenance and limits are unchanged.
 
 ## Server and browser
 
+`stitchkit/agent-runtime/realtime` and `stitchkit/agent-runtime/react` are evolving and
+experimental: no application has committed to them yet, so expect their shape to change.
+
 ```ts
 import { bindAgentHarnessRealtime } from 'stitchkit/agent-runtime/realtime';
 
@@ -6767,11 +6761,19 @@ const binding = bindAgentHarnessRealtime(harness, socket, {
   },
   onError: reportServerError,
 });
+
+// When an application withdraws someone's access, tell the binding.
+await removeMember(conversationId, userId);
+binding.revoke(conversationId, (identity) => identity.userId === userId);
 ```
 
 `socket` is the existing `createSocketIOServer` handle, attached to `createServer` (Bun)
-or the Node adapter. The access policy checks every operation, file/reference and metadata
-as well as snapshot/event reads. Session handshake authentication alone is insufficient.
+or the Node adapter. The access policy checks every request, file/reference and metadata, and
+the attach that opens a stream. Events then flow under that grant without a call per token;
+Without a `revoke()` call a grant lasts until the socket disconnects or the conversation is detached: events keep flowing even if your own permission data changed. That fail-open default is deliberate (one check per request, not one per token), so call `revoke` whenever access is withdrawn. `revoke` ends the grant, the next event is re-authorized (`source: 'delivery'`), and a refusal
+or failure detaches the conversation and delivers `access-denied`, which puts the controller in
+`error` with code `FORBIDDEN` instead of leaving a frozen view. Session handshake
+authentication alone is insufficient.
 Conversation ownership and observer/controller roles are application policy; the canonical
 control server additionally enforces its exclusive controller lease.
 
@@ -6809,7 +6811,10 @@ view does not interrupt its remote run. Use explicit `interrupt` for cancellatio
 Reconnect reattaches and reads durable state. Mutations are not retried automatically:
 if an acknowledgement is lost, retain the original idempotency key. Incoming event
 buffers and outgoing requests have finite limits; capacity/overflow/lease failures stay
-visible. A server overflow deliberately disconnects the transport; reconnect explicitly.
+visible, each with a code from the one `AgentControlErrorCode` vocabulary. A reconnect
+rejects the requests of the previous connection at once and attaches again, so they
+cannot hold capacity the new attach needs. A server overflow deliberately disconnects the
+transport; reconnect explicitly.
 
 ## Check behavior, not just admission
 
@@ -6837,15 +6842,6 @@ The helper does not invoke a model or poll; the existing runtime ticket owns exe
 # Guide: Managed application kernel  (docs/guide/application-kernel.md)
 ==============================================================================
 
----
-title: Managed application kernel
-description: Compose process-local resources, schedules, readiness, drain and optional provider adapters without building a second job platform.
-type: architecture
-status: active
-created: 2026-08-23
-updated: 2026-10-04 13:28 +07:00
----
-
 # Managed application kernel
 
 > **Maturity: evolving.** This surface is still finding its shape and may be
@@ -7029,9 +7025,8 @@ lifecycle context; the application decides when a database/provider probe runs.
 
 **A `reportHealth` call inside `start` is kept.** A resource that says nothing
 is assumed healthy once it is ready; one that reports its own health has already
-answered the question, and the answer stands. (It used to be overwritten — and
-the example above hides that, because `healthy` is the same value that
-overwrote it.)
+answered the question, and the answer stands. The readiness default never
+overwrites it.
 
 **Reporting the same health again is not a change.** A resource may confirm its
 health on a timer; a report with the value it already reported publishes
@@ -7527,9 +7522,48 @@ The caller owns file selection and coordination with an active rotator.
 Writer startup inspects retained and active files under its lock. On damage,
 `journal.getStatus().recovery` contains counts and first/last anomaly locations, reconstructed
 again on restart from the preserved bytes. This describes startup observations, not live
-continuous inspection. `maxFiles: 1` cannot preserve a torn active file by rotation and throws
-`DiagnosticJournalRecoveryError` before removing any evidence; configure at least two slots.
-Normal rotation retains the existing finite eviction policy. → [ADR 0219](../decisions/0219-journal-damage-is-data-and-io-failure-is-failure.md).
+continuous inspection. Normal rotation retains the existing finite eviction policy.
+→ [ADR 0219](../decisions/0219-journal-damage-is-data-and-io-failure-is-failure.md).
+
+A file opening cannot keep in place — a torn active file with `maxFiles: 1`, a generation name
+that is not a regular file, a retained file it cannot read — is renamed to
+`<file>.quarantined-<epoch>` beside it, and the journal starts (`onStartupRefusal: 'quarantine'`,
+the default). Nothing is deleted; quarantined files are outside retention and yours to remove.
+Every open lists them in `getStatus().recovery.quarantined` until you do: the ones it moved
+first, with their `reason`, then the ones earlier runs left, without one — at most 32, and
+`quarantinedUnlisted` counts the rest.
+A journal whose damage must stop the process — one that is a source of truth, not diagnostics —
+declares `onStartupRefusal: 'fail'` and gets a typed `DiagnosticJournalRecoveryError`:
+
+```ts
+import { DiagnosticJournalRecoveryError } from 'stitchkit/application'
+
+// A diagnostic journal: start, then say what is set aside.
+const journal = await createDiagnosticJournal({ ...config })
+const { quarantined = [], quarantinedUnlisted = 0 } = journal.getStatus().recovery ?? {}
+for (const entry of quarantined) {
+  // `reason` is present only for a file this start moved; an earlier run's has none.
+  internalLogger.warn({ file: entry.file, movedTo: entry.quarantinedAs, reason: entry.reason })
+}
+if (quarantinedUnlisted > 0) internalLogger.warn({ quarantinedUnlisted })
+
+// A journal that is a source of truth: refuse to start over damage.
+try {
+  await createDiagnosticJournal({ ...config, onStartupRefusal: 'fail' })
+} catch (error) {
+  if (error instanceof DiagnosticJournalRecoveryError) {
+    // error.reason: 'torn-without-retention-slot' | 'not-a-regular-file' | 'unreadable'
+  }
+  throw error
+}
+```
+
+A quarantining journal writes, so the managed resource that owns it reports `healthy`, and its
+dependants read `recovery` from the value they `use()`. There is no degraded journal: the kernel
+degrades only optional resources, and a required resource cannot depend on one.
+`DiagnosticJournalRecoveryStatusSchema` is evolving and `.strict()`; if you embed it in your own
+protocol, every change to its shape is listed under breaking changes.
+→ [ADR 0240](../decisions/0240-a-diagnostic-journal-quarantines-what-it-cannot-keep.md).
 
 Shutdown performs one phase barrier at a time: stop admission everywhere,
 cancel future schedules, drain admitted work, then close in reverse stable
@@ -7983,17 +8017,6 @@ boundary is required. Send and projection callbacks own their external deadlines
 # Guide: Optional process sandbox  (docs/guide/sandbox.md)
 ==============================================================================
 
----
-title: Optional process sandbox
-description: Linux namespace isolation, durable workspaces and a host credential gateway.
-updated: 2026-10-03 14:47 +07:00
-participants:
-  - role: implemented
-    harness: Codex
-    model: GPT-6
-    at: 2026-10-03 14:47 +07:00
----
-
 # Optional process sandbox
 
 `stitchkit/agent-runtime/sandbox` is a server-only, evolving API. Existing coding
@@ -8057,6 +8080,9 @@ access the same workspace through the host's contained-file implementation;
 commands run inside the namespace with `/workspace` as their root. The host-only
 `handle.coding` binding never belongs in model input or persisted state.
 Unsupported backends omit the binding and the factory refuses explicitly.
+When the adapter's `probe()` or `prepare()` fails, the agent gets `SANDBOX_UNAVAILABLE` with a
+fixed reason; the adapter's own error is the refusal's `cause`, delivered to the mount's
+`hooks.onToolError`, which is where an application logs it.
 
 Stop also kills coding commands. Both launch paths share the configured
 `maxConcurrentCommands` admission limit (default 8); an occupied slot gives
@@ -8125,37 +8151,25 @@ be refused explicitly by the backend.
 # Guide: Native IO  (docs/guide/native-io.md)
 ==============================================================================
 
----
-title: Конечные команды и файловые гарантии
-description: Native IO для Bun и Node, с явно выбранной durability, безопасными bounds и caller lifetime.
-type: guide
-status: active
-created: 2026-10-01 20:44 +07:00
-updated: 2026-10-04 20:04 +07:00
-participants:
-  - role: authored
-    harness: Codex
-    model: GPT-6
-    at: 2026-10-01 20:44 +07:00
-  - role: implemented
-    harness: Codex
-    model: GPT-6
-    at: 2026-10-02 00:08 +07:00
-  - role: implemented
-    harness: Codex
-    model: GPT-6
-    at: 2026-10-03 13:36 +07:00
-  - role: implemented
-    harness: Codex
-    model: GPT-6
-    at: 2026-10-04 09:21 +07:00
----
-
 # Native IO
 
-Примеры используют публичные imports и одинаково исполняются в Bun и Node ≥22.
+Shortest working example: publish a file atomically, then run one bounded command.
+
+```ts
+import { writeFileAtomic } from 'stitchkit/files'
+import { runNativeCommand } from 'stitchkit/process'
+
+await writeFileAtomic('/srv/app/state.json', '{"version":2}')
+const { exitCode, stdout } = await runNativeCommand({
+  executable: '/usr/bin/git', args: ['rev-parse', 'HEAD'], cwd: '/srv/app',
+  capture: true, maxOutputBytes: 4096, timeoutMs: 5000,
+})
+console.log(exitCode, new TextDecoder().decode(stdout))
+```
 
-## Запись файла
+The examples use public imports and run the same in Bun and Node >= 22.
+
+## Writing a file
 
 ```ts
 import { writeFileAtomic, AtomicFilePublicationError } from 'stitchkit/files'
@@ -8168,7 +8182,7 @@ try {
   })
 } catch (error) {
   if (error instanceof AtomicFilePublicationError) {
-    // target уже виден. Проверьте receipt, прежде чем решать о повторе.
+    // The target is already visible. Check the receipt before deciding whether to retry.
     console.error(error.phase, error.cause)
   } else throw error
 }
@@ -8177,25 +8191,50 @@ await writeFileAtomic('/srv/app/state.json', '{"version":2}', {
 })
 ```
 
-По умолчанию `replace: true`, `durability: 'file'`, `mode: 0o600`: existing вызовы сохраняют
-file-fsync и atomic replacement. `durability: 'none'` отключает sync; `'directory'` выполняет
-полную запись → exact descriptor chmod → file fsync → rename (replace) либо link (create) →
-удаление staging link → parent fsync. `writeFileAtomicSync` имеет те же options и порядок.
-Create отказывает с native `EEXIST` при существующем файле, symlink или concurrent winner.
-Никогда не переводите этот отказ в replace автоматически.
+The defaults are `replace: true`, `durability: 'file'` and `mode: 0o600`: file fsync and atomic
+replacement. `durability: 'none'` skips every sync. `'directory'` runs the full sequence: write all
+bytes, exact descriptor chmod, file fsync, rename (replace) or link (create), remove the staging
+link, parent directory fsync. `writeFileAtomicSync` takes the same options and runs the same order.
+Create fails with the native `EEXIST` when the target exists, is a symlink, or a concurrent writer
+won. Never turn that refusal into a replace automatically.
+
+`AtomicFilePublicationError.published === true` tells a visible target from an unconfirmed
+acknowledgement. `phase` is `cleanup`, `directory-sync` or `directory-close`; the primary cause is
+kept in `cause`. An error before publication leaves the previous target untouched. Cleanup errors are
+secondary to the primary error. While a create is in flight a second hardlink briefly exists, so a
+strict single-link reader may refuse in that window.
+
+### Abandoned staging files
+
+The bytes are staged beside the target under `.stitchkit-<24 lowercase hex>.tmp`, the same name for
+`writeFileAtomic`, `writeFileAtomicSync`, the managed writer and the chunk spool. A process killed
+between the staging and the publication (SIGKILL, OOM, power loss) leaves that file behind, and no
+later write removes it: a random name alone cannot tell an abandoned write from one in flight.
+Removing it is the caller's responsibility:
+
+```ts
+import { isAtomicStagingName, sweepAtomicStaging } from 'stitchkit/files'
+
+// At startup, or before trusting that a directory holds only your own records:
+const removed = await sweepAtomicStaging({ directory: '/srv/app/registry', olderThanMs: 60 * 60_000 })
 
-`AtomicFilePublicationError.published === true` отличает видимость от неподтверждённого
-acknowledgement. `phase` — `cleanup`, `directory-sync` или `directory-close`; первичная причина
-сохранена в `cause`. Ошибка до publish оставляет прежний target. Cleanup вторичен к первичной ошибке.
-При create кратко существует второй hardlink; strict single-link reader вправе отказать в этом окне.
+// Skip staging files when listing a directory of your records:
+const records = (await readdir('/srv/app/registry')).filter((name) => !isAtomicStagingName(name))
+```
 
-Directory fsync — native POSIX/filesystem capability. Windows явно отказывает; иной filesystem
-может отказать при open/sync. Проверка на Linux не подтверждает поведение macOS, сетевой FS или
-сохранность при отключении питания. Состояние диска определяется гарантиями самой FS/ОС.
-`createManagedFileBoundary.write(..., { durable: true })` использует тот же publish owner и parent sync;
-его create по умолчанию остаётся create, а `replace: true` явно разрешает replacement.
+`olderThanMs` is required and must exceed the longest write in flight; a younger staging file is
+left alone. The sweep removes only regular files, never follows a symlink and never enters a
+subdirectory. The name form is a stable public contract: changing it is a breaking change of
+`stitchkit/files`. An exclusive lock's `.lock-*.tmp` file is not an atomic-write staging file and
+does not match.
 
-## Строгое чтение
+Directory fsync is a native POSIX filesystem capability. Windows refuses it explicitly, and another
+filesystem may refuse at open or sync. A check on Linux does not confirm macOS behavior, network
+filesystems or survival of a power loss; the disk state is whatever the filesystem and OS guarantee.
+`createManagedFileBoundary.write(..., { durable: true })` uses the same publish owner and parent sync;
+its create stays a create, and `replace: true` allows replacement explicitly.
+
+## Strict reads
 
 ```ts
 import { createManagedFileBoundary } from 'stitchkit/files'
@@ -8206,25 +8245,27 @@ const source = await files.read('receipt.json', {
 })
 console.log(source.observation) // dev, ino, size, nlink, mtimeMs, ctimeMs
 const receipt = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(source.bytes))
-// schema.parse(receipt) и проверка digest принадлежат приложению.
+// Schema parsing and digest checks belong to the application.
 ```
 
-Без новых options ответ сохраняет `{ ref, bytes }`, допускает trusted in-root symlink и hardlink.
-`rejectSymlinks` запрещает requested leaf, `singleLink` проверяет `nlink` открытого descriptor,
-`stable` сравнивает dev/ino/size/mtime/ctime/nlink вокруг byte read; `observe` добавляет metadata.
-`FILE_NOT_FOUND`, `FILE_NOT_REGULAR`, `FILE_UNSAFE_LINK`, `FILE_TOO_LARGE`, `FILE_CHANGED`,
-`FILE_UNSUPPORTED` и `FILE_IO_ERROR` различаются. Abort сохраняет caller reason.
-Nonblocking open позволяет отказать FIFO без ожидания writer. Bytes ограничены во время чтения,
-включая рост файла, не только initial stat. Chunk allocation ≤ maxBytes+1+64 KiB, flatten ≤ maxBytes;
-FD закрывается при success, отказе, abort и IO error.
-Ошибка close сохраняет первичную ошибку чтения; после успешного чтения ошибка close возвращается caller.
+Without options the result is `{ ref, bytes }` and a trusted in-root symlink or hardlink is
+allowed. `rejectSymlinks` refuses a symlink at the requested leaf, `singleLink` checks `nlink` of
+the opened descriptor, `stable` compares dev/ino/size/mtime/ctime/nlink around the byte read, and
+`observe` adds the metadata. These refusals are distinct: `FILE_NOT_FOUND`, `FILE_NOT_REGULAR`,
+`FILE_UNSAFE_LINK`, `FILE_TOO_LARGE`, `FILE_CHANGED`, `FILE_UNSUPPORTED` and `FILE_IO_ERROR`. Abort
+keeps the caller's reason. A nonblocking open lets a FIFO be refused without waiting for a writer.
+Bytes are bounded while reading, including a file that grows, not only by the initial stat. Chunk
+allocation is at most `maxBytes + 1 + 64 KiB` and the flattened result at most `maxBytes`. The
+descriptor closes on success, refusal, abort and IO error. A close error keeps the primary read error;
+after a successful read a close error is returned to the caller.
 
-Root и ancestors принадлежат trusted actor. Эти options не дают descriptor-relative containment
-при hostile concurrent ancestor replacement. Отдельного переключателя «считать ancestors безопасными»
-нет: portable owner не предоставляет такую capability. Metadata stability не доказывает immutable
-snapshot против произвольного hostile writer; используйте application lock/immutable publication.
+The root and its ancestors belong to a trusted actor. These options do not give
+descriptor-relative containment against a hostile concurrent ancestor replacement, and there is no
+switch to treat ancestors as safe: the portable owner has no such capability. Metadata stability does
+not prove an immutable snapshot against an arbitrary hostile writer; use an application lock or
+immutable publication.
 
-## Команды
+## Commands
 
 ```ts
 import { runNativeCommand } from 'stitchkit/process'
@@ -8246,21 +8287,23 @@ await runNativeCommand({
 })
 ```
 
-Команда требует caller signal или finite `timeoutMs` (1–2147483647 ms: native timer range; большее значение отказывается, не превращается в 1 ms). Streaming имеет caller lifetime, без скрытого
-60-second timeout или 1-MiB output limit. `capture` по умолчанию false; true требует
-`maxOutputBytes` для суммарных stdout+stderr. Лимит считает исходные bytes; API возвращает
-`Uint8Array`, не преобразует invalid UTF-8. Result содержит наблюдаемый `exitCode: number | null`
-и `signal: string | null`; signal termination не превращается в выдуманный exit code. `maxOutputBytes` может ограничивать и streaming.
-`stdin` — bytes с `maxStdinBytes` (default 1 MiB). `envPolicy` default `declared-only`: отсутствие env
-означает пустой environment; `ambient` явно разрешает наследование. Cwd/executable policy остаётся
-приложению; этот primitive запускает native executable и сам не создаёт shell.
+A command needs a caller `signal` or a finite `timeoutMs` (1 to 2147483647 ms, the native timer
+range; a larger value is refused, never turned into 1 ms). Streaming runs for the caller's lifetime,
+with no hidden 60-second timeout or 1 MiB output limit. `capture` defaults to false; `true` requires
+`maxOutputBytes` for the combined stdout and stderr. The limit counts source bytes; the API returns
+`Uint8Array` and does not decode invalid UTF-8. The result holds the observed `exitCode: number | null`
+and `signal: string | null`; a signal termination is never turned into an invented exit code.
+`maxOutputBytes` may bound streaming too. `stdin` is bytes bounded by `maxStdinBytes` (default 1 MiB).
+`envPolicy` defaults to `declared-only`: no `env` means an empty environment, and `ambient` inherits
+explicitly. The application owns cwd and executable policy; the primitive launches a native
+executable and never creates a shell.
 
-Машинная классификация limit error использует `NativeCommandError.reason`: `deadline` при
-истечении собственного `timeoutMs`, `output-budget` при превышении суммарных bytes stdout+stderr
-в capture или streaming. Оба случая сохраняют `code: 'COMMAND_LIMIT'`; `message` служит
-диагностике, не протоколу. У `COMMAND_UNAVAILABLE` и `COMMAND_CLEANUP` reason отсутствует;
-caller abort и sink failure сохраняют исходную ошибку. При cleanup failure первоначальный
-limit вместе с reason остаётся внутри `AggregateError` cause.
+`NativeCommandError.reason` classifies a limit error by machine: `deadline` when the command's own
+`timeoutMs` expires, `output-budget` when the combined stdout and stderr bytes exceed the limit, in
+capture or streaming. Both keep `code: 'COMMAND_LIMIT'`; `message` is for diagnosis, not for
+protocols. `COMMAND_UNAVAILABLE` and `COMMAND_CLEANUP` have no reason. A caller abort and a sink
+failure keep the original error. When cleanup fails, the original limit and its reason stay inside the
+`AggregateError` cause.
 
 ```ts
 import { NativeCommandError } from 'stitchkit/process'
@@ -8276,38 +8319,112 @@ try {
 }
 ```
 
-Конструктор сохраняет вызов `new NativeCommandError(code, message, { cause })` и принимает
-`{ cause, reason: 'deadline' | 'output-budget' }` только для `COMMAND_LIMIT`. Owner всегда
-заполняет reason для собственных limits. Созданная вызывающей стороной ошибка без reason
-не получает выдуманную причину из текста; её reason остаётся `undefined`.
-
-Вывод читается с backpressure отдельно для stdout/stderr: один выполняющийся sink на канал плюс
-bounded native Readable buffer; накопления всей истории при streaming нет. Callback получает
-lifetime signal. Abort освобождает ожидание даже игнорирующего signal callback, но не способен
-отменить сторонние действия, которые сам callback продолжит после abort. Sink обязан отменять свои
-IO, не сохранять бесконечную историю и не изменять shared descriptor flags. После abort новых
-callbacks owner не запускает. Normal completion ждёт всех bytes и sinks.
-
-Cleanup: POSIX process group, TERM, `killGraceMs` (default 100, maximum 10 000), затем KILL;
-`cleanupTimeoutMs` (default 2000, maximum 30 000) ограничивает ожидание close после сигналов.
-На Darwin временный `EPERM` при сигнале группе может означать zombies, ещё не убранные
-OS reaper. Повтор ограничен `cleanupTimeoutMs`; успех требует доставленного сигнала или
-`ESRCH`, постоянный отказ сохраняется в cause. Закрытие каждого owned pipe и выход leader
-наблюдаются отдельно, включая отсутствие общего `child.close` при teardown.
-Сохраняется caller/sink причина; failure cleanup — `NativeCommandError` с `COMMAND_CLEANUP` и
-AggregateError cause. Даже вышедший parent не исключает helper, удерживающий pipe. Windows
-отказывает с `COMMAND_UNAVAILABLE`; потомок, самостоятельно покинувший группу через setsid,
-лежит за границей этой capability. Это one-shot execution, не PTY, supervisor или daemon host.
-
-## Механическая адаптация
-
-Atomic file wrapper заменяется одним вызовом `writeFileAtomic` с выбранными options. Bounded
-regular-file read заменяется `files.read`; JSON/schema, receipt conflicts, journal rotation и
-application locks сохраняются. Spawn/drain/capture/cancellation wrapper заменяется `runNativeCommand`;
-shell policy, command admission, логирование, redaction, bytes→text decoder и operator sink сохраняются.
-Длительные signal-only команды остаются streaming; bounded tar/capture получают свои явные limits.
-Импорт leaf не делает установку всего npm package маленькой; выбирайте dependency после измерения
-packed размера и dependency closure.
+The constructor is `new NativeCommandError(code, message, { cause })`; it accepts
+`{ cause, reason: 'deadline' | 'output-budget' }` only for `COMMAND_LIMIT`. The owner always sets the
+reason for its own limits. An error a caller constructs without a reason gets none inferred from the
+text; its `reason` is `undefined`.
+
+Output is read with backpressure, stdout and stderr separately: one running sink per channel plus a
+bounded native Readable buffer, with no accumulation of the whole history while streaming. The
+callback receives the lifetime signal. Abort releases the wait even for a callback that ignores the
+signal, but it cannot cancel third-party work the callback continues after the abort. A sink must
+cancel its own IO, must not keep an unbounded history and must not change shared descriptor flags.
+After an abort the owner starts no new callbacks. Normal completion waits for all bytes and sinks.
+
+Cleanup uses the POSIX process group under the `stop` policy, then KILL; `cleanupTimeoutMs`
+(default 2000, maximum 30 000) bounds the wait for close after the signals. On
+Darwin a transient `EPERM` when signalling a group can mean zombies the OS reaper has not collected
+yet. The retry is bounded by `cleanupTimeoutMs`; success needs a delivered signal or `ESRCH`, and a
+permanent refusal is kept in the cause. The close of every owned pipe and the leader's exit are
+observed separately, including the absence of a shared `child.close` during teardown. The caller or
+sink cause is kept; a cleanup failure is a `NativeCommandError` with `COMMAND_CLEANUP` and an
+`AggregateError` cause. Even an exited parent does not exclude a helper that holds a pipe. Windows
+refuses with `COMMAND_UNAVAILABLE`; a descendant that leaves the group on its own with `setsid` is
+outside this capability. This is one-shot execution, not a PTY, a supervisor or a daemon host.
+
+### Stopping a command: the `stop` policy
+
+A caller abort, the `timeoutMs` deadline, an exceeded output budget and a failing sink all stop the
+command the same way, by its `stop` policy:
+
+| field | meaning |
+|---|---|
+| `target` | `'group'`: `signal` goes to every member of the group. `'leader'`: `signal` goes to the leader alone; the leader's exit ends the grace at once. Required. |
+| `signal` | `SIGTERM` (default), `SIGINT`, `SIGHUP`, `SIGQUIT`, `SIGUSR1` or `SIGUSR2`. KILL is not a stop signal: it is what the grace ends in. |
+| `graceMs` | How long the leader (or the group) has to leave before the whole group gets KILL. 0 to 3 600 000 (one hour). Required. |
+| `killOn` | Optional `AbortSignal`. Its abort stops the command with KILL to the whole group at once, also in the middle of a grace. |
+
+Omitting `stop` means `{ target: 'group', signal: 'SIGTERM', graceMs: 100 }`.
+
+```ts
+// Cooperative cancellation: the leader rolls its work back, its helpers are not asked.
+await runNativeCommand({
+  executable: '/usr/local/bin/migrate', args: ['apply'], signal: request.signal,
+  stop: { target: 'leader', signal: 'SIGINT', graceMs: 15 * 60_000, killOn: shutdown.signal },
+})
+```
+
+With `target: 'leader'` the rest of the group never receives the cooperative signal: they are
+processes the leader started, and the leader decides what happens to them. Whatever is left in the
+group when the leader exits, or when the grace ends, gets KILL, including a helper with its stdio
+closed that no pipe would have revealed. A leader that has already exited is never signalled again.
+
+The output pipes stay open until the stop sequence ends. Output a stopping command writes is read and
+dropped, never passed to `onOutput` and never captured, so a leader that writes while it shuts down
+does not meet a broken pipe. The result rejects with the abort reason once the group is gone and the
+pipes are closed, so it can take `graceMs` plus `cleanupTimeoutMs` after the abort.
+
+The grace is a timer inside the process that runs the command. If that process exits first, the
+timer is gone and the group, which is detached into its own session, keeps running: nothing in this
+package can bound it from outside. Abort `killOn` in your shutdown path, so the group is killed
+before the process exits, and let the supervisor own the case where the process dies without a
+shutdown. Under systemd, keep `KillMode=control-group` (the default) so the stop of the unit
+reaches every process in its cgroup, whatever its process group; launchd only kills the job's own
+process group, which a command's group is not.
+
+### Stopping a group and its descendants
+
+A group is signalled only while the kernel still reports members. `ESRCH` from the first signal,
+or from the existence probe that follows it during the grace, means no member is left: no KILL
+is sent afterwards, because a numeric group id that has vanished can already belong to an
+unrelated group. A group that is still visible after the grace period receives KILL.
+
+`descendants` declares what happens to processes the leader left running once it has exited
+successfully:
+
+| `descendants` | After the leader exits |
+|---|---|
+| `'terminate-after-leader'` (the default) | The group is stopped right after `onLeaderSettled` returns and before the pipes drain: with `target: 'group'` by the same signal, grace, KILL sequence as cancellation; with `target: 'leader'` by KILL at once, since the leader has already exited. Descendants that left the group with `setsid` stay out of reach. |
+| `'leave'` | Nothing. A helper started with its stdio detached keeps running. One that inherited stdout or stderr keeps the pipes open, and the command then waits for it until its deadline or abort. |
+
+Omitting the option means `'terminate-after-leader'`: a command does not leak the helpers it
+started. A real daemon detaches into its own session (`setsid`, as `daemon(3)` does), is no member
+of the group and is unaffected. Declare `'leave'` only for a helper that has to outlive the
+command while staying in its group:
+
+```ts
+await runNativeCommand({
+  executable: '/usr/local/bin/start-helper', timeoutMs: 60_000,
+  // the helper started here outlives this command on purpose
+  descendants: 'leave',
+})
+```
+
+A command whose group this package did not create (a structural
+launcher supplied by a host) has no group to stop, and `descendants` has nothing to act on there.
+
+
+## Replacing hand-written wrappers
+
+An atomic-file wrapper becomes one `writeFileAtomic` call with the chosen options. A bounded
+regular-file read becomes `files.read`; JSON and schema parsing, receipt conflicts, journal rotation
+and application locks stay with the application. A spawn, drain, capture and cancellation wrapper
+becomes `runNativeCommand`; shell policy, command admission, logging, redaction, the bytes-to-text
+decoder and the operator sink stay with the application. Long signal-only commands stay streaming;
+bounded tar or capture commands get their own explicit limits. Importing one leaf does not make
+installing the whole npm package smaller; choose a dependency after measuring packed size and its
+dependency closure.
+
 ## Resource-scoped launchers and shared owners
 
 `onLeaderSettled(event, signal)` observes leader exit before inherited stdout/stderr pipes
@@ -8349,8 +8466,23 @@ syscall interruptible or provide a snapshot against a hostile writer.
 An exclusive lock applies exact requested permissions through its creating descriptor,
 independent of umask. Default `0600` stays private. Shared `0640` requires a common group and
 traversable directories; another UID also needs directory write permission to reclaim a
-proven-dead owner's file. Set `ownerlessGraceMs: null` to refuse every age-only reclaim,
-including ownerless reclaim guards. The default remains 5000 ms for existing clients.
+proven-dead owner's file.
+
+The lock is published with its owner already recorded: the owner record is written to a
+private temporary file in the lock's directory, then hard-linked to the lock name. `link`
+fails with `EEXIST` for every caller but one, and the name never exists without a complete
+record, so a holder that stalls or dies before publishing leaves no lock and cannot be
+displaced. The directory must therefore be on a filesystem that supports hard links. A crash
+between the temporary write and the link can leave a `.lock-*.tmp` file behind; it is not a
+lock and nothing waits on it.
+
+`ownerlessGraceMs` defaults to `null`: a lock file with no readable owner is never taken
+because of its age. This library does not produce such a file; only a writer that creates the name
+before its owner record can leave one (for example an empty file from a crashed process).
+`ownerlessGraceMs: <ms>` opts in to reclaiming an empty lock file older than that, and also governs
+abandoned empty reclaim guards.
+When unset, an empty reclaim guard left by an older writer is taken after 5 000 ms so recovery
+is never disabled for good; `null` refuses that too.
 Stale reclaim guards use the same lock owner and a child guard for the inode check and
 unlink. Recovery depth is capped at 16; a deeper stale chain refuses recovery with a depth diagnosis retained as the cause of
 the bounded `LOCK_TIMEOUT`. Live owners, unknown process-lifetime evidence and unsafe records are never
@@ -8376,27 +8508,26 @@ version: carry their reachable relative `.d.ts` closure, rather than emitting re
 instead emit declarations for only that DTO contract. Keep the library's manifest at runtime
 `dependencies: {}` and `peerDependencies: { zod: ... }` when that is its declared promise.
 
-The packaged Darwin loader has static references to both architecture addons. Bun compilation
-embeds the matching `.node` asset; ordinary Bun bundling emits native assets alongside its JS
-output. Publish **every output returned by `Bun.build`**, preserving relative paths. Copying only
-the JS file drops its native dependency. No runtime Stitchkit installation or manually chosen
-native path is required for these bundled artifacts.
+The packaged Darwin loader names its addons by a path computed at run time, so a bundler
+never follows it: bundling `stitchkit/server`, `stitchkit/files` or `stitchkit/process` yields
+the same single JS file on every operating system, with no `.node` output, and
+`bun build --outfile` works. Such a bundle looks for the addon beside the original package
+files, never inside itself. Where that file is absent (an artifact moved to another machine)
+the Darwin backend is `unavailable`: process identity cannot be recorded, so a lock held by a
+crashed owner is not reclaimed. An artifact that must carry the Darwin addon uses the packaging
+plugin of the next section; it is the only way a static loader enters a bundle.
 
 ```sh
-bun build src/native.ts --target=bun --minify --outdir=dist
-bun build src/native.ts --compile --bytecode --format=esm --outfile=dist/native
+bun build src/native.ts --target=bun --minify --outfile=dist/native.js
 ```
 
-For a JS build that previously used `--outfile=dist/native.js`, use
-`--outdir=dist --entry-naming=native.js` instead: the output can now include native assets.
-The standalone executable still uses `--outfile` because those assets are embedded inside it.
-
 Qualify the complete output outside its build tree and installed dependency graph. Test process
-identity, live-owner refusal, dead-owner recovery and contained file operations in the resulting
-JS bundle and standalone executable. Bun and Node package imports retain the same lazy loader;
-importing a portable leaf does not load a Darwin addon on another OS. Test declarations too,
-and check that importing an unbundled Stitchkit leaf fails in a deliberately isolated library
-distribution. A separate schema-only entry must not import the native entry.
+identity, live-owner refusal, dead-owner recovery and contained file operations in artifacts built
+with the packaging plugin, and check that an unpackaged build reports the backend `unavailable`
+rather than certifying a dead owner. Bun and Node package imports retain the same
+lazy loader; importing a portable leaf does not load a Darwin addon on another OS. Test
+declarations too, and check that importing an unbundled Stitchkit leaf fails in a deliberately
+isolated library distribution. A separate schema-only entry must not import the native entry.
 
 If the Darwin backend cannot load, `observeProcessInstance` still returns `unavailable`.
 Its backend `Error` preserves the original `cause`; JSON serialization carries only the stable
@@ -8412,17 +8543,17 @@ Stitchkit installation or create an independent lightweight npm package.
 ## Public native packaging
 
 Custom archives and installers use `stitchkit/files/packaging` at **build time**.
-`createNativePackaging` resolves the installed version and target addon with its original SHA256;
-its Bun-compatible plugin integrates that asset with the same lazy native loader.
+`createNativePackaging` resolves the installed version and target addon, reads the addon once and
+checks it against the size and SHA256 that Stitchkit published in its `native-assets.json` when the
+package was built. A ready asset carries those verified `bytes` with the published `size` and
+`sha256`; its Bun-compatible plugin integrates the same bytes with the same lazy native loader.
+Each call reads and hashes the selected addons, so call it once per build and reuse the result.
 The leaf is evolving. It requires no optional peer or Bun ambient declarations for Node imports.
 It must run unbundled from its installed package, never from an application's runtime artifact.
-This contract is available from 0.104.1; versions 0.103.13–0.104.0 use the complete-output recipe
-in the previous section.
 
 ```ts
 import { createNativePackaging } from 'stitchkit/files/packaging'
-import { createHash } from 'node:crypto'
-import { copyFileSync, mkdirSync, readFileSync } from 'node:fs'
+import { mkdirSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 
 const native = createNativePackaging({
@@ -8436,14 +8567,11 @@ const result = await Bun.build({
   plugins: [native.plugin],
 })
 if (!result.success) throw new AggregateError(result.logs, 'Build failed')
-// Preserve every result.outputs file under dist, then add the selected companion.
+// Preserve every result.outputs file under dist, then write the verified companion bytes.
 for (const asset of native.assets) {
-  const bytes = readFileSync(asset.sourcePath)
-  if (createHash('sha256').update(bytes).digest('hex') !== asset.sha256)
-    throw new Error('Native asset changed during build')
   const destination = join('dist', asset.outputPath)
   mkdirSync(dirname(destination), { recursive: true })
-  copyFileSync(asset.sourcePath, destination)
+  writeFileSync(destination, asset.bytes)
 }
 ```
 
@@ -8452,23 +8580,67 @@ absolute paths, traversal or overlapping file/directory paths. `entryPath` is fi
 Bun naming templates such as `[dir]` or `[name]`. Companion JS builds require one entry, no splitting,
 and `naming.entry` exactly matching `entryPath`; the plugin rejects a mismatching layout.
 Choose any application layout; the framework does not prescribe an app directory or installer.
-Keep every bundler output, then verify copied addon bytes against the original SHA256.
-Archive the complete output directory with an integrity manifest, unpack to a clean directory,
-verify the same hashes there, and run offline without the build tree or `node_modules`.
-A digest provides integrity, not authenticity: signature and trust policy remain application-owned.
+Keep every bundler output and write `asset.bytes`; never read the addon from `node_modules` a
+second time. An installed addon whose size or SHA256 differs from the published manifest refuses
+with `mismatch` / `NATIVE_ASSET_DIGEST_MISMATCH`, so a file substituted after installation never
+reaches an artifact. Archive the complete output directory with an integrity manifest that records
+`asset.sha256`, unpack to a clean directory, verify the same hashes there, and run offline without
+the build tree or `node_modules`. The published digest ties the bytes to the package Stitchkit
+built; the package itself is only as trusted as its tarball (the lockfile integrity of the install).
+Signature and trust policy remain application-owned.
+
+One JS artifact can run on both Darwin architectures; change only the packaging inputs:
+
+```ts
+const native = createNativePackaging({
+  platform: 'darwin', architecture: ['arm64', 'x64'], delivery: 'companion',
+  entryPath: 'app/native.js',
+  assetPath: { arm64: 'addons/arm.node', x64: 'addons/intel.node' },
+})
+```
+
+Use the same single plugin and write loop above. A single-target loader deliberately refuses the
+other architecture; two competing plugins cannot produce a universal loader. The array form
+requires exactly one distinct output path per declared target. A ready result carries the target
+array and both verified assets with their published digests; `NativePackagingOptions<true>` /
+`NativePackagingResult<true>` describe this form when explicitly annotating variables.
+The loader selects only `process.arch`: a missing or wrong-architecture selected addon refuses,
+even when the other valid addon is present. Linux runtime imports remain lazy and use Linux
+process primitives without loading Darwin assets. Qualify the exact same JS bytes on real
+Darwin arm64 and x64 machines, with both companions preserved through archive delivery.
+Build-machine architecture and cross-build success cannot establish universal native support.
 
 For a standalone executable use `delivery: 'embedded'` and the same plugin in `Bun.build`
-with `compile: { outfile: ... }`. Bun embeds the selected addon; `assets` identifies its
-original bytes for qualification, not a companion that must be installed beside the executable.
+with `compile: { outfile: ... }`. Bun embeds the selected addon from the verified bytes the
+plugin holds, not from a second read of the file; `assets` identifies those bytes and their
+published digest for qualification, not a companion that must be installed beside the executable.
 Cross-builds must select the requested architecture explicitly; the artifact must run on that target.
 The installed package must contain that target's addon. No automatic fallback/downgrade occurs.
 
-The API returns `unsupported` / `NATIVE_TARGET_UNSUPPORTED` for non-Darwin or unsupported
-architectures, and `missing` / `NATIVE_ASSET_MISSING` for a missing addon. Portable Linux libraries
-use their normal build, without a Darwin plugin; merely importing the build leaf loads no addon.
-Malformed inputs, unsupported metadata versions and other IO errors throw before packaging.
-Runtime missing/corrupt companions preserve the native `unavailable` result and safe stage/code
-from the existing observer; they never certify a dead owner. Preserve the raw cause internally.
+`platform` is the closed set of platforms with native addons, today `'darwin'`: another name is a
+type error and a schema refusal that throws, so pass the literal (or narrow `process.platform`
+with `=== 'darwin'`) rather than a free string. The API returns `unsupported` /
+`NATIVE_TARGET_UNSUPPORTED` for an unsupported architecture, `missing` / `NATIVE_ASSET_MISSING` for
+an addon the package does not publish or whose file is gone, and `mismatch` /
+`NATIVE_ASSET_DIGEST_MISMATCH` for an addon whose bytes differ from the published size or SHA256.
+A `mismatch` names the first differing `architecture` and carries `expected` (the published
+`{ size, sha256 }`) and `actual` (the installed file's size and the SHA256 of the bytes read), so
+a build log can tell a truncated copy from a substituted one:
+
+```ts
+if (native.state === 'mismatch')
+  throw new Error(
+    `${native.architecture} addon: expected ${native.expected.size} bytes ` +
+      `${native.expected.sha256}, found ${native.actual.size} bytes ${native.actual.sha256}`,
+  )
+```
+
+Portable libraries
+and Linux builds use their normal build, without a Darwin plugin; merely importing the build leaf
+loads no addon.
+Malformed inputs, a manifest whose `formatVersion` is not 2 and other IO errors throw before packaging.
+A missing or corrupt companion at runtime yields the native `unavailable` result with the safe
+stage and code from the observer; it never certifies a dead owner. Preserve the raw cause internally.
 The plugin does not parse consumer JS or establish a second runtime native implementation.
 
 ## Qualification boundaries
@@ -8487,24 +8659,19 @@ the qualification for native Darwin behavior.
 
 Local filesystem tests do not attest delayed NFS visibility, shared-volume microVM or gVisor
 ownership, actual PGID reuse, power-loss durability or macOS full-sync behavior. Those
-require their actual topology or failure environment. The default ownerless grace remains
-5000 ms; stricter callers can retain `ownerlessGraceMs: null`. No age-only observation
-proves a partially published owner's process dead.
+require their actual topology or failure environment. No age-only observation proves a
+process dead; the lock's owner record exists before its name does.
+
+A sandbox admission slot is released once a direct command's pipes have closed and its owner has settled.
+A `COMMAND_CLEANUP` outcome means the death of its group was not proven, so the slot stays
+occupied, `stop` keeps rejecting with the cleanup error, and the sandbox session is recreated to
+recover.
 
 
 ==============================================================================
 # Guide: Generic application primitives  (docs/guide/primitives.md)
 ==============================================================================
 
----
-title: Generic application primitives
-description: Declare lifecycle, access, exact values, audit, delivery and exports without moving application infrastructure into Stitchkit.
-type: guide
-status: active
-created: 2026-09-01
-updated: 2026-10-01 21:03 +07:00
----
-
 # Generic application primitives
 
 `stitchkit/primitives` is an optional browser-safe leaf. It declares values and policies; it does
@@ -8607,33 +8774,50 @@ const bytes = canonicalJson({ '2': 'two', '10': 'ten', optional: undefined, nest
 // Native crypto or browser WebCrypto hashes these same UTF-8 bytes.
 ```
 
-`canonicalJson` использует единый serializer исторических digest: object keys в UTF-16 code-unit
-order, включая integer-like keys; array order сохраняется. Optional object members с undefined
-опускаются. Top-level/array undefined, sparse arrays, functions/symbols/BigInt, non-finite numbers,
-negative zero, cycles, user prototypes, accessors, non-enumerable/symbol members отказаны до
-serialization. Приложение валидирует свою schema первым; canonical boundary не заменяет её.
+`canonicalJson` is the one serializer behind the digests: object keys sort by UTF-16 code unit,
+integer-like keys included; array order is kept; object members that are `undefined` are omitted.
+It refuses, before serializing, a top-level or array `undefined`, sparse arrays, functions, symbols,
+BigInt, non-finite numbers, negative zero, cycles, user prototypes, accessors and non-enumerable or
+symbol members. Validate your own schema first; the canonical boundary does not replace it.
+
+Defaults: depth 100 (the maximum), nodes 100 000, UTF-8 bytes 1 MiB. Invalid options throw a Zod
+validation error. A refused value throws `CanonicalJsonError`, a `TypeError` whose `reason` is a
+`CanonicalJsonRefusal`; branch on the reason, never on the message:
 
-Defaults: depth 100 (maximum 100), nodes 100 000, UTF-8 bytes 1 MiB. Превышение или не-JSON data —
-TypeError; неверные options — Zod validation error. Это browser-safe leaf без Node/Bun/crypto,
-agent-runtime/testing или optional peers. Native и browser используют один algorithm; hashing
-остаётся platform adapter. Переносите только serializer recursion, сохраняя proof schemas и
-verification boundary. Существующие внутренние historical normalization/digest fixtures не меняются;
-новый public boundary сознательно отказывает неоднозначным values вместо фиктивной совместимости.
+| `reason` | Meaning |
+|---|---|
+| `depth` | The value is nested deeper than `maxDepth`. |
+| `nodes` | The value has more nodes than `maxNodes`. |
+| `bytes` | The output is longer than `maxBytes` in UTF-8. |
+| `cycle` | The value contains a cycle. |
+| `negative-zero` | The value contains `-0`, which JSON cannot carry. |
+| `not-json` | The value is not bounded plain JSON: sparse arrays, non-finite numbers, non-plain objects, accessors. |
+
+`depth`, `nodes` and `bytes` are the caller's limits being exceeded; the other three say the value is
+not JSON data at all.
+
+```ts
+import { CanonicalJsonError, canonicalJson } from 'stitchkit/primitives'
+
+try {
+  canonicalJson(payload, { maxBytes: 4096 })
+} catch (error) {
+  if (error instanceof CanonicalJsonError && error.reason === 'bytes') {
+    // too large: reject the request
+  } else throw error
+}
+```
+
+The leaf is browser-safe: no Node, Bun or crypto, no `agent-runtime/testing`, no optional peers. Native
+and browser code run the same algorithm; hashing stays a platform adapter. A consumer that needs the
+same bytes moves only the serializer recursion and keeps its own proof schemas and verification
+boundary.
 
 
 ==============================================================================
 # Guide: Application migration recipes  (docs/guide/application-migration-recipes.md)
 ==============================================================================
 
----
-title: Application migration recipes
-description: Executable patterns for moving database, poller, queue and operational publishing lifecycle into the managed application kernel.
-type: architecture
-status: active
-created: 2026-08-24
-updated: 2026-10-04 13:28 +07:00
----
-
 # Application migration recipes
 
 These recipes are the migration companion to the
@@ -8785,10 +8969,10 @@ guard must refuse. Filesystem mutations made inside inbox transactions call
 `assertHeld` immediately before publication or cleanup.
 
 For `createFileStateStore`, remove `staleLockMs` and `retryMs` from configuration.
-`lockTimeoutMs` remains the acquisition budget. Timestamp age no longer revokes
+`lockTimeoutMs` is the acquisition budget. Timestamp age never revokes
 a live or unknown writer. Stop and verify old writers before recovering a legacy
-pid-only lock; do not invent owner metadata. Historical temporary files are no
-longer deleted by age. See the [durable intake contract](application-kernel.md#durable-process-facts-and-owner-notifications).
+pid-only lock; do not invent owner metadata. Temporary files are never
+deleted by age. See the [durable intake contract](application-kernel.md#durable-process-facts-and-owner-notifications).
 
 ## Long-running poller
 
@@ -9036,9 +9220,10 @@ declarations do not require `ai`, the MCP SDK or Bun globals. Node consumers can
 use strict `NodeNext` resolution with `skipLibCheck: false` and ordinary Node
 types; the package keeps its required dependencies separate from optional SDKs.
 
-CLI runtime tools use the shared executable contract: identity, input and output
-schemas, handler, and explicit CLI exposure. SDK presenters belong to the MCP/AI
-definitions in `stitchkit/tools`, which require the corresponding peers. A typed
+CLI runtime tools use the one runtime-tool declaration: identity, input and output
+schemas, handler, and explicit CLI exposure. SDK presenters are the adapter's extension
+of that declaration (the fourth type argument of `RuntimeToolDefinitionWithOutput`, or
+`defineRuntimeTool` in `stitchkit/tools`), which requires the corresponding peers. A typed
 definition returned by `defineRuntimeTool` or `createRuntimeToolFactory` can be
 passed directly to both CLI and SDK mounts.
 
@@ -9052,7 +9237,7 @@ For a CLI-only managed tool, use the neutral generic construction contract to
 infer the handler from its schemas:
 
 ```ts
-import type { RuntimeToolExecutionWithOutput } from 'stitchkit/cli'
+import type { RuntimeToolDefinitionWithOutput } from 'stitchkit/cli'
 import { z } from 'zod'
 
 const input = z.object({ text: z.string() })
@@ -9062,12 +9247,14 @@ const measure = {
   identity: { serviceName: 'text', action: 'measure', method: 'POST' },
   transports: ['CLI'], input, output,
   handler: ({ input }) => ({ size: input.text.length }),
-} satisfies RuntimeToolExecutionWithOutput<typeof input, typeof output>
+} satisfies RuntimeToolDefinitionWithOutput<typeof input, typeof output>
 ```
 
-Pass `measure` to `runtimeTools`. The heterogeneous registration type preserves
-the definition without inventing a common handler input; execute it through
-`createCli` or `createCliInvoker` so validation remains on the canonical path.
+Pass `measure` to `runtimeTools`. `RuntimeToolDefinition`, the heterogeneous
+registration type, accepts it unchanged, and types an inline handler written directly
+in `runtimeTools` by the parsed object (use the construction type above to type the
+input from the schema). Execute it through `createCli` or `createCliInvoker` so
+validation remains on the canonical path.
 
 ## Exposure is opt-in
 
@@ -9257,7 +9444,9 @@ the values agree. Duplicates are refused before command execution. Array
 options accumulate across long and short forms; unknown non-dotted passthrough
 options retain their raw-list grammar. Tokens after `--` are literal data.
 Command `--help` and `-h` keep their diagnostic precedence over malformed
-operation arguments; application globals are validated before routing.
+operation arguments; application globals are validated before routing. Help is a
+request, not a setting, so repeating it in any spelling (`-h -h`, `-h --help`) asks once
+and never errors.
 
 Without presentation configuration, positional arguments fill non-boolean
 fields in declaration order, so `myapp generate "a fox"` is
@@ -9484,8 +9673,10 @@ Declared aliases render beside their canonical options, for example
 The argument table and `Application options:` show bounds from their JSON Schema,
 for example `<integer> [>=1, <=50]`, `<string> [length >=1, length <=12]`, and
 `<value…> [items >=2, items <=4]`. Numeric `>` and `<` are exclusive, while `>=`
-and `<=` include the endpoint; a zero limit is displayed too. Unbounded fields
-keep just their type and description. Bounds on an array's items are not bounds
+and `<=` include the endpoint; a zero limit is displayed too. Only limits the
+schema declares are shown: the safe-integer range every `z.int()` carries is the
+type, not a bound, so a bare integer prints `<integer>`, `.min(1)` prints `>=1` and
+`.positive()` prints `>0`. Unbounded fields keep just their type and description. Bounds on an array's items are not bounds
 on the array itself.
 
 Composed schemas retain their meaning: `any of:` and `one of:` separate
@@ -9713,11 +9904,16 @@ exists to distrust.
 
 `publishCli` is an opt-in publisher for a local application-owned distribution
 directory. It commits every target and its version manifest before atomically
-replacing the public `manifest.json`. Your application selects the CLI source
-identity and admits that snapshot at each phase:
+replacing the public `manifest.json`. It ships from its own evolving entrypoint,
+`stitchkit/cli/publish`: release infrastructure follows how distributions are
+published, so it is not held to the stable promise of `stitchkit/cli`
+([ADR 0245](../decisions/0245-cli-publication-is-an-evolving-leaf.md)). The
+manifest, signatures, installer and updater it writes for stay in
+`stitchkit/cli`. Your application selects the CLI source identity and admits
+that snapshot at each phase:
 
 ```ts
-import { publishCli } from 'stitchkit/cli'
+import { publishCli } from 'stitchkit/cli/publish'
 
 const result = await publishCli({
   storageRoot: '/srv/myapp/cli',
@@ -10042,7 +10238,7 @@ await createCli({ name: 'myapp', version, runtimeTools: discovered, commands: [.
 commands, and a connection without it still contributes nothing to the CLI —
 exposure stays explicit, as it is everywhere else in the framework.
 
-One unconvertible schema no longer takes the connection down with it. The tool
+One unconvertible schema does not take the connection down. The tool
 is skipped and **named** (`onSkippedTool`, or a stderr line by default), so a
 surface of two hundred tools is not lost to one.
 
@@ -10075,13 +10271,12 @@ credential, body, identity and stack stay with the original in-process cause in
 Unknown throws remain `INTERNAL_SERVER_ERROR`. A timeout is not proof that a
 write did not happen: verify the remote outcome before repeating an operation.
 
-**A remote refusal keeps its code.** A failed `tools/call` used to become a
-one-sentence `Error` with the result discarded, which cost three things at once:
-the code (so `exitCodes` had nothing to map and every remote failure exited `1`),
-the message the operator needed, and the error's own class — a plain `Error` is
-an *unexpected* error to the runner, so it printed a code frame of the framework
-bundle before the JSON failure and was then scrubbed to `INTERNAL_SERVER_ERROR`.
-A structured `{ error, details }` body is now relayed as the contract error it
+**A remote refusal keeps its code.** A failed `tools/call` must keep three things:
+the code (so `exitCodes` can map it instead of every remote failure exiting `1`),
+the message the operator needs, and the error's own class — a plain `Error` is
+an *unexpected* error to the runner, which would print a code frame of the framework
+bundle before the JSON failure and scrub it to `INTERNAL_SERVER_ERROR`.
+A structured `{ error, details }` body is relayed as the contract error it
 is, on every transport; anything else fails as `UPSTREAM_TOOL_ERROR` carrying
 what the server did send. Not `INTERNAL_SERVER_ERROR`, because nothing of ours
 broke.
@@ -11230,15 +11425,6 @@ watch client; silent lost notifications are repaired by hub reconciliation.
 # Guide: Live data  (docs/guide/live.md)
 ==============================================================================
 
----
-title: Live data — announcements, watched reads, keyspaces and the trust fence
-description: How to declare events beside the operation contract, share one server-side read between every browser asking the same question, keep authoritative memory in front of a durable backend, and refuse a request whose authority you never agreed to answer on.
-type: guide
-status: active
-created: 2026-09-02
-updated: 2026-09-02
----
-
 # Live data
 
 Four things an application builds by hand the second time it needs them.
@@ -11650,11 +11836,11 @@ Every refusal answers the same bare 403. A response that said *which* rule
 refused would let a caller learn your trusted list one guess at a time; the
 reason goes to `onRefused` and the log, where you are.
 
-### One thing that changed
+### Group hooks
 
-A route group can no longer declare `onRequest`. It never worked — the framework
-dispatched only the server-level hook — and it could not be made to work without
-matching group prefixes a second time, ahead of the real router. Use the
+A route group cannot declare `onRequest`: the framework dispatches only the
+server-level hook, and a group hook would need group prefixes matched a second
+time, ahead of the real router. Use the
 server-level `hooks.onRequest` to refuse before dispatch, or the group's
 `authorize` to gate once the endpoint is known.
 
@@ -12329,7 +12515,7 @@ whether the code declares `details`:
 
 The model-facing envelope is `{ error, retryable, details?, _hint? }`; for a code with no
 details schema the framework fills `details` with `{ message }`, so declaring a
-message changes what the model reads there — it used to be the code itself. Put
+message changes what the model reads there; without one it is the code itself. Put
 anything the model must reliably read in `details` or `hint`, not in `message`.
 
 With no `details` schema, the options object forbids `details`. A required
@@ -12842,6 +13028,32 @@ Without an `observability` the work still runs inside a context, so trace ids,
 decision from having a context. `traceparent` continues the trace of whatever
 scheduled the work, instead of starting an unrelated one.
 
+### CPU is not attributed to work
+
+Request rows, `runUnitOfWork` rows and schedule status carry durations and
+counts, never CPU. One JavaScript thread interleaves every operation, so a
+`process.cpuUsage()` delta across an operation's start and end measures
+everything the process ran in that time — a long wait reads as the CPU of the
+timers that fired during it. The correct basis is the synchronous segment, and
+Bun gives no callback when a continuation is entered or left
+([ADR 0244](../decisions/0244-cpu-is-not-attributed-to-operations.md)).
+
+Process CPU per window is the number you can observe:
+
+```ts
+let last = process.cpuUsage()
+setInterval(() => {
+  const now = process.cpuUsage() // cumulative { user, system } in µs
+  logger.info('cpu', { cpuUserUs: now.user - last.user, cpuSystemUs: now.system - last.system })
+  last = now
+}, 60_000)
+```
+
+If you build attribution yourself: credit an operation only the CPU of the
+synchronous segments it ran, never its waiting time; put everything outside those
+segments into `unattributed`; never credit a window to the one operation in
+flight — that operation is usually the one waiting.
+
 ### Write the calls that changed something
 
 `auditChanges` is the filter most projects end up writing, shipped so they do not
@@ -12916,8 +13128,8 @@ needed:
 createServer({ services, logging, observability: observability.request })
 ```
 
-`wrapInRequestContext` remains available for a custom fetch pipeline that does
-not use `createHandler`; it is no longer part of built-in HTTP audit wiring:
+`wrapInRequestContext` serves a custom fetch pipeline that does not use
+`createHandler`; built-in HTTP audit wiring does not use it:
 
 ```ts
 Bun.serve({ fetch: wrapInRequestContext(customFetch) })
@@ -13254,9 +13466,9 @@ which the built-in **tool** row does not read: a tool event takes
 `errorCode` / `errorMessage` / `errorDetail` from the `ToolResult`, and only
 identity and `dimensions` from the context. Calling it in `onToolError` would
 leave the tool row exactly as scrubbed as before. It is right for the **HTTP**
-path, where the request *is* the record. (Since ADR 0045 a tool call runs in its
-own context, so it can no longer write into the enclosing `/mcp` request's row
-either — the call is simply not where that helper belongs.)
+path, where the request *is* the record. (A tool call runs in its own context, ADR 0045,
+so it cannot write into the enclosing `/mcp` request's row either — the call is
+simply not where that helper belongs.)
 
 ### One row that names the cause
 
@@ -14107,15 +14319,6 @@ per-transport tenant plumbing.
 # Guide: Frontend integrations  (docs/guide/frontend-integrations.md)
 ==============================================================================
 
----
-title: Frontend integrations
-description: Compose Stitchkit with Next.js, React Router or a separate Vite development server
-type: architecture
-status: active
-created: 2026-08-08
-updated: 2026-08-08
----
-
 # Frontend integrations
 
 The official `bun create stitchkit` application uses Next.js with a separate
@@ -14177,15 +14380,6 @@ shared contract remains the only transport schema source.
 # Guide: React Query policy  (docs/guide/react.md)
 ==============================================================================
 
----
-title: React Query policy
-description: One request-local server client, one browser singleton and explicit retry rules for Stitchkit API errors
-type: guide
-status: active
-created: 2026-09-06
-updated: 2026-09-06
----
-
 # React Query policy
 
 `stitchkit/react` contains policy adapters for TanStack Query. It does not own
@@ -14240,15 +14434,6 @@ endpoint or cookie vocabulary.
 # Guide: Keyboard layers and list zones  (docs/guide/keyboard.md)
 ==============================================================================
 
----
-title: Keyboard layers and list zones
-description: One listener decides which part of a screen gets a key; lists move real focus with the arrows
-type: guide
-status: active
-created: 2026-09-29
-updated: 2026-09-29
----
-
 # Keyboard layers and list zones
 
 `stitchkit/react/keyboard` answers one question for a React screen: **who gets
@@ -15112,8 +15297,8 @@ the press was forged (a client can send any bytes) and goes to `onStale`.
 
 A press on a message the record does not know — an older menu higher up — is
 answered in place: a one-message view takes that message over, a longer view is
-sent below it and the pressed message is deleted. Either way the previously
-recorded view is removed: one live menu per chat.
+sent below it and the pressed message is deleted. Either way the recorded
+view is removed: one live menu per chat.
 
 For a message the screens do not own — a notification from the backend —
 `screens.button(link('🔑 Refresh token', refreshToken, { botId }))` makes a
@@ -15227,15 +15412,6 @@ an incoming message to HTML, and a history stack.
 # Guide: GeoIP  (docs/guide/geo.md)
 ==============================================================================
 
----
-title: GeoIP
-description: A server-only managed GeoIP reader with three observable states and last-known-good generation reloads.
-type: guide
-status: active
-created: 2026-09-06
-updated: 2026-09-06
----
-
 # GeoIP
 
 `stitchkit/geo` is a server-only, evolving entrypoint for reading local GeoIP
@@ -15319,6 +15495,413 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.105.0
+
+### CLI publication has its own entrypoint
+
+**Who must act:** code that imports `publishCli`, `CliPublicationOptions`, `CliPublicationPhase` or
+`CliPublicationResult` from `stitchkit/cli`. Everything else in `stitchkit/cli` — `createCli`, the
+manifest schemas, signatures, `renderCliInstaller` and the updater — is unchanged.
+
+`publishCli` is release infrastructure, so it now ships from the evolving entrypoint
+`stitchkit/cli/publish` instead of the stable `stitchkit/cli`
+([ADR 0245](../decisions/0245-cli-publication-is-an-evolving-leaf.md)). Its options, result and
+behaviour are the same.
+
+1. Move the publication names to the new specifier; keep every other CLI import where it is:
+
+   ```ts
+   // before
+   import { publishCli, type CliPublicationOptions, verifyCliManifest } from 'stitchkit/cli'
+   // after
+   import { verifyCliManifest } from 'stitchkit/cli'
+   import { publishCli, type CliPublicationOptions } from 'stitchkit/cli/publish'
+   ```
+
+   Search pattern: `\b(publishCli|CliPublication(Options|Phase|Result))\b` in files that import
+   from `'stitchkit/cli'`.
+2. Type-check: an import left on `stitchkit/cli` fails with "has no exported member".
+3. `stitchkit/cli/publish` is evolving: read its breaking entries in each minor you upgrade across.
+
+### a command stops by its `stop` policy
+
+**Who must act:** callers of `runNativeCommand` (`stitchkit/process`) that pass `killGraceMs`.
+Callers that omit it need no change: the default stop is the same TERM to the group, 100 ms, KILL.
+
+1. Replace `killGraceMs: N` with a group stop of the same grace:
+
+   ```ts
+   // before
+   await runNativeCommand({ executable, args, signal, killGraceMs: 500 })
+   // after
+   await runNativeCommand({ executable, args, signal, stop: { target: 'group', graceMs: 500 } })
+   ```
+
+   Search pattern: `killGraceMs:\s*(\d[\d_]*)` → `stop: { target: 'group', graceMs: $1 }`.
+2. If your own wrapper signals only the leader and waits a long grace (cooperative cancellation),
+   replace it with `stop: { target: 'leader', signal: 'SIGINT', graceMs }` (up to one hour). Pass
+   `killOn` with your shutdown signal so an application that stops sooner kills the group first.
+3. The result of a stopped command rejects once the group is gone, up to `graceMs` plus
+   `cleanupTimeoutMs` after the abort; size your caller deadlines on that sum.
+
+### a command stops what its leader left
+
+**Who must act:** callers of `runNativeCommand` (`stitchkit/process`) whose command starts a helper
+in its own process group that must keep running after the command returns. A daemon that detaches
+with `setsid` (as `daemon(3)` does) is not in the group and needs
+no change.
+
+`descendants` now defaults to `'terminate-after-leader'`
+([ADR 0246](../decisions/0246-a-command-stops-its-descendants-by-default.md)): when the leader
+exits, the members it left in the group are stopped by the command's `stop` policy before the
+pipes drain.
+
+1. Find the commands that start a background helper on purpose (a `&` in a shell script, a spawned
+   child the leader does not wait for) and declare `'leave'` on them:
+
+   ```ts
+   // before
+   await runNativeCommand({ executable, args, timeoutMs })
+   // after
+   await runNativeCommand({ executable, args, timeoutMs, descendants: 'leave' })
+   ```
+
+2. Remove an explicit `descendants: 'terminate-after-leader'`, or keep it: it is now the default.
+3. A command whose helper inherited stdout or stderr used to wait for that helper until its
+   deadline. It now completes when the leader exits; drop a workaround that killed the helper from
+   `onLeaderSettled`.
+
+### native packaging verifies published digests
+
+**Who must act:** build scripts that call `createNativePackaging` (`stitchkit/files/packaging`) and
+read `asset.sourcePath`, hash the addon themselves, switch over the refusal `state`/`code`, pass a
+`platform` other than the literal `'darwin'`, or parse `node_modules/stitchkit/native-assets.json`.
+
+The package now publishes the `size` and SHA256 of each Darwin addon, computed when Stitchkit is
+built, in `native-assets.json` at `formatVersion: 2`. `createNativePackaging` reads each selected
+addon once, compares it with that digest and returns the verified bytes. An installed addon that
+differs refuses with `NATIVE_ASSET_DIGEST_MISMATCH`.
+
+1. Replace every read of `asset.sourcePath` with `asset.bytes`, and delete your own re-hash of the
+   addon: the result's `sha256` is the published digest and `bytes` already match it.
+
+   ```ts
+   // before
+   const bytes = readFileSync(asset.sourcePath)
+   if (createHash('sha256').update(bytes).digest('hex') !== asset.sha256) throw …
+   copyFileSync(asset.sourcePath, destination)
+   // after
+   writeFileSync(destination, asset.bytes)
+   ```
+
+2. Handle the third refusal. A `switch` over `result.state` gains `'mismatch'`
+   (`code: 'NATIVE_ASSET_DIGEST_MISMATCH'`); treat it as a failed build, never as a missing addon.
+   It carries the differing `architecture` with `expected` (published) and `actual` (installed)
+   `{ size, sha256 }`; log both pairs.
+3. Pass the target platform as the literal `'darwin'`. `platform` is a closed enum, so a free
+   string (a target name read from configuration, `process.platform`) no longer type-checks, and
+   another platform throws instead of returning `unsupported`. Skip packaging for non-Darwin
+   targets before the call:
+
+   ```ts
+   // before
+   const native = createNativePackaging({ platform: target.platform, architecture, … })
+   if (native.state === 'unsupported') return
+   // after
+   if (target.platform !== 'darwin') return
+   const native = createNativePackaging({ platform: target.platform, architecture, … })
+   ```
+
+   `unsupported` now means only an architecture the package has no addon for.
+4. Call `createNativePackaging` once per build and pass the result (its `assets` and `plugin`)
+   where it is needed. Each call reads and hashes the selected addons again.
+5. If you read `native-assets.json` directly, read `assets.<arch>.path`, `.size` and `.sha256`
+   instead of a bare path per architecture; an architecture with no entry is not published.
+
+### exclusive locks publish their owner first
+
+**Who must act:** callers of `withExclusiveLock` (`stitchkit/files`) that rely on a lock file with no
+readable owner being taken by age, and anything that puts lock files on a filesystem without hard
+links. Every other caller needs no change.
+
+A lock is now written to a private `.lock-<id>.tmp` file in the lock's directory, then hard-linked to
+the lock name. The name never exists without a complete owner record, so `ownerlessGraceMs` defaults
+to `null` instead of 5 000 ms: a lock file with no readable owner is never taken because of its age.
+
+1. If you depended on age-based reclaim of an empty lock file left by an older writer, opt in:
+
+   ```ts
+   // before: an empty lock older than 5 s was taken by default
+   await withExclusiveLock(path, run)
+   // after: say so; only legacy empty files need it
+   await withExclusiveLock(path, run, { ownerlessGraceMs: 5_000 })
+   ```
+
+2. Keep lock directories on a filesystem that supports hard links (local ext4, xfs, APFS and the
+   like). `link` failing with `EPERM` or `ENOTSUP` fails the acquisition.
+3. Expect a `.lock-*.tmp` sibling only after a holder was killed between writing its record and
+   publishing it. It is not a lock; the next reclaim in that directory removes the ones whose owner
+   is gone on this machine. Exclude the pattern from directory-size caps or backups if you have any.
+
+### one runtime-tool declaration
+
+**Who must act:** code that names `RuntimeToolExecution`, `RuntimeToolExecutionWithOutput`,
+`RuntimeMcpToolDefinition`, `RuntimeMcpToolDefinitionWithOutput` or `ToolSurfaceDefinition`; code
+that annotates a definition carrying `present` as `RuntimeToolDefinitionWithOutput<I, O>` from
+`stitchkit/tools`; imports of `stitchkit/agent-runtime/harness-tools`; code that compares agent
+control error codes; and callers that send a JSON array as text to a string-or-array tool field.
+Definitions returned by `defineRuntimeTool` / `createRuntimeToolFactory`, native CLI `commands` and
+contract tools need no change.
+
+A runtime tool now has one declaration, `RuntimeToolDefinitionWithOutput` /
+`RuntimeToolDefinitionWithoutOutput`, exported with the same name from `stitchkit/cli`,
+`stitchkit/tools` and `stitchkit/tools/mcp`. It carries no SDK type: the presenters are the adapter's
+extension, named as the fourth type argument. `RuntimeToolDefinition` is the one registration type.
+
+1. Replace each removed name.
+
+   | before | after |
+   |---|---|
+   | `RuntimeToolExecutionWithOutput<I, O>` (`stitchkit/cli`) | `RuntimeToolDefinitionWithOutput<I, O>` |
+   | `RuntimeToolExecution` (`stitchkit/cli`) | `RuntimeToolDefinition` |
+   | `RuntimeMcpToolDefinitionWithOutput<I, O>` (`stitchkit/tools/mcp`) | `RuntimeToolDefinitionWithOutput<I, O, undefined, RuntimeMcpToolPresenters<z.output<O>>>` |
+   | `RuntimeMcpToolDefinition` (`stitchkit/tools/mcp`) | `RuntimeToolDefinition` |
+   | `ToolSurfaceDefinition` (`stitchkit/tools`) | `ToolSurfaceProjection<RuntimeToolDefinition>` |
+
+2. In `stitchkit/tools`, a type that names a definition with presenters passes the presenter type:
+
+   ```ts
+   // before
+   const tool: RuntimeToolDefinitionWithOutput<typeof input, typeof output> = defineRuntimeTool({ …, present })
+   // after: let defineRuntimeTool infer it, or name the presenters
+   const tool = defineRuntimeTool({ …, present })
+   const named: RuntimeToolDefinitionWithOutput<typeof input, typeof output, undefined, RuntimeToolPresenters<z.output<typeof output>>> = tool
+   ```
+
+3. An inline handler in `runtimeTools: [...]` needs no wrapper: it is typed by the parsed object.
+   To type `input` from the schema, construct with `defineRuntimeTool` (or
+   `satisfies RuntimeToolDefinitionWithOutput<typeof input, typeof output>`) before registering.
+
+4. Replace `createAgentHarnessTools` (`stitchkit/agent-runtime/harness-tools`) with the call it made:
+
+   ```ts
+   // before
+   tools: createAgentHarnessTools(({ context }) => ({ services: [svc], context, lifecycle: auth }))
+   // after
+   import { composeToolLifecycle, mountAgent } from 'stitchkit/tools'
+   tools: ({ context, toolFenceLifecycle }) =>
+     mountAgent([svc], { context, lifecycle: composeToolLifecycle(auth, toolFenceLifecycle) })
+   ```
+
+5. Agent control codes: `ACCESS_DENIED` is `FORBIDDEN`, and `CONNECTION_CLOSED` is returned for a closed
+   connection. `AgentControlErrorCode` lists every code. `authorize` now runs once per request; after you
+   withdraw someone's access, call `binding.revoke(conversationId, matches?)` so an open stream is
+   re-authorized and ends with an `access-denied` delivery.
+
+6. A string-or-array field that receives `'["a","b"]'` now fails with `VALIDATION_ERROR` ("`paths` is a
+   list written as text"). Send the array itself. A string that is not a list the array member accepts
+   (`[preview].png`) is still one plain string.
+
+### flattened unions keep declaration order
+
+**Who must act:** consumers that use `flattenUnionInput: true` and keep snapshot tests, golden
+files or provider prompt caches of flattened tool schemas.
+
+A flattened union now lists its properties, enum values and branch labels in the order they first
+appear across the variants, not alphabetically. Declaration order often encodes priority, so the
+model now reads the order you wrote. Alternatives of different kinds (`anyOf`) keep their
+canonical order, independent of variant order.
+
+1. Regenerate every snapshot or golden file of a flattened tool listing (`buildToolManifest`,
+   `listToolNames`, MCP `tools/list`, Agent tool schemas) and review the diff: only ordering moves.
+2. Expect one provider prompt-cache miss per flattened tool after the upgrade.
+3. To keep an order you prefer, declare the variants and fields in that order.
+
+### connection limits are validated
+
+**Who must act:** callers that pass `timeoutMs` or `maxResponseBytes` to a connection and relied
+on an invalid value silently becoming the default.
+
+`stitchkit/tools/connections` throws a `RangeError` when `timeoutMs` is not a positive integer
+within timer range (at most 2 147 483 647) or `maxResponseBytes` is not a positive safe integer.
+Before 0.104.0 a value of 0, a negative number, a fraction or an out-of-range number fell back to
+the default without a message.
+
+```ts
+// Before: { timeoutMs: 0 } meant "use the default" by accident.
+// After: omit the option to take the default, or pass a real limit.
+{ timeoutMs: 30_000 }
+```
+
+### one canonical JSON serializer
+
+**Who must act:** tests that call `serializeSurfaceValue` from `stitchkit/testing`, and code that
+puts a value nested deeper than 100 levels into agent store events, archives or projections
+through `canonicalAgentJson`.
+
+`canonicalJson` from `stitchkit/primitives` is the package's one canonical serializer. It
+admits dense arrays, plain objects, strings, booleans, `null` and finite numbers; an `undefined`
+object member is omitted. It refuses everything else with a `CanonicalJsonError`, a `TypeError`
+whose `reason` says why: `'depth'`, `'nodes'` and `'bytes'` are the limits you set, while
+`'cycle'`, `'negative-zero'` and `'not-json'` say the value is not JSON data.
+
+`serializeSurfaceValue` is removed. It produced the same bytes without limits:
+
+```ts
+// Before
+import { serializeSurfaceValue } from 'stitchkit/testing'
+const text = serializeSurfaceValue(manifest)
+// After: the limits default to 100 levels, 100 000 nodes and 1 MiB; raise them for a large manifest
+import { canonicalJson } from 'stitchkit/primitives'
+const text = canonicalJson(manifest, { maxBytes: 16 * 1024 * 1024 })
+```
+
+`canonicalAgentJson` in `stitchkit/agent-runtime` is `canonicalJson` with the node and byte
+limits at their maximum. A value both accepted has the same bytes as before, so stored digests
+and archives still match: like `z.json()` before it, the store hashes `-0` as `0` and drops an
+own `__proto__` member (the public `canonicalJson` refuses `-0` and keeps `__proto__`). What
+changed is the refusal table: an `undefined` object member used to fail and is now omitted, and
+a value nested deeper than 100 levels is now refused.
+
+```ts
+// Before: canonicalAgentJson({ a: undefined }) threw a ZodError
+// After:  canonicalAgentJson({ a: undefined }) === '{}'
+//         canonicalAgentJson(nestedBeyond100Levels) throws CanonicalJsonError (reason 'depth')
+```
+
+### directory inbox entries
+
+**Who must act:** producers that drop hard links into an inbox directory, and callers that pass
+`accept` the output of a transforming schema.
+
+A file dropped into the inbox directory with more than one link is set aside as `invalid`
+(detail `managed file has multiple links`). Another name can still rewrite such a file after it
+was validated, so it is never trusted. Write each entry as its own regular file: a temporary
+name in the same directory, then a rename onto `<name>.json`.
+
+`accept` takes the schema's input type, stores that input as given and parses it with the
+schema on delivery. A schema without a transform has the same input and output type and needs
+no change. With a transform, pass the input:
+
+```ts
+const schema = z.object({ amount: z.string().transform(Number) })
+// Before: accept({ source, key, entry: { amount: 42 } })   // typed as the output; `z.string()` refused it
+// After:  accept({ source, key, entry: { amount: '42' } })  // delivered as { amount: 42 }
+```
+
+A name that is already in `rejected/` no longer stops the pass: identical bytes are the entry
+already set aside, different bytes are kept as `rejected/<name>.<16 hex digits>`.
+
+### journal startup scan
+
+**Who must act:** operators that read `status.recovery` right after `createDiagnosticJournal` to
+find damaged rows in the middle of a file.
+
+Opening a journal reads only the last line of the active file and of every retained
+generation (`startupScan: 'tails'`, the default). A crash tears the end of a file, so a torn tail
+is still reported and still rotated away, and opening no longer parses and validates every
+line of every generation. It still reads each file once in large blocks to count lines, so the time
+grows with the bytes retained, at read speed. Pass `startupScan: 'full'` to read and validate every line as before:
+
+```ts
+// Before: every open parsed every line of every generation.
+// After:  the same full scan, on request.
+const journal = await createDiagnosticJournal({ path, eventSchema, limits, startupScan: 'full' })
+```
+
+### journal startup quarantine
+
+**Who must act:** operators of a journal that is a source of truth and must not start over
+damaged retained files; code that constructs `DiagnosticJournalRecoveryError` or reads its
+`recovery`; protocols that embed `DiagnosticJournalRecoveryStatusSchema`, and their readers.
+A diagnostic journal needs no change.
+
+Opening a journal no longer refuses to start over a torn active file with `maxFiles: 1`, a
+generation name that is not a regular file or a retained file it cannot read. It renames the file
+to `<file>.quarantined-<epoch>` beside the journal, starts, and lists the move in
+`getStatus().recovery.quarantined`. Quarantined files are outside retention and never deleted;
+every later open lists them again, without a `reason`, until you remove them.
+
+1. A journal whose damage must stop the process declares the old behaviour:
+
+   ```ts
+   // Before: refusing was the only behaviour.
+   await createDiagnosticJournal({ path, eventSchema, limits })
+   // After:
+   await createDiagnosticJournal({ path, eventSchema, limits, onStartupRefusal: 'fail' })
+   ```
+
+2. Branch on the refusal's `reason` instead of its message or error class. Every startup refusal
+   about retained evidence is a `DiagnosticJournalRecoveryError`, including the former plain
+   `Error` for a non-file generation and the raw `EACCES` for an unreadable one (now in `cause`):
+
+   ```ts
+   // Before: catch (error) { if (error instanceof DiagnosticJournalRecoveryError) use(error.recovery) }
+   // After:
+   catch (error) {
+     if (error instanceof DiagnosticJournalRecoveryError && error.reason === 'torn-without-retention-slot') use(error.recovery)
+   }
+   ```
+
+   `recovery` is present only for `torn-without-retention-slot`. The constructor takes one
+   options object: `new DiagnosticJournalRecoveryError({ reason, file, recovery?, cause? })`.
+
+3. A protocol that embeds `DiagnosticJournalRecoveryStatusSchema` carries the new optional
+   `quarantined` array (at most 32 entries, `reason` optional) and `quarantinedUnlisted` count.
+   The schema is `.strict()`: upgrade every reader that parses it with its own copy before a
+   writer on this version sends a status with either field, or bump your protocol version.
+
+### error constructors take named options
+
+**Who must act:** code that constructs an `AppError` or an `ApiError` with anything beyond its
+code, and classes that extend `AppError` and call `super(code, message, status, …)`. Code that
+only throws the `notFound`, `badRequest`, `unauthorized`, `forbidden`, `conflict` and
+`rateLimited` helpers, or only reads `code`, `status`, `details`, `hint`, `traceId`,
+`retryable` and `cause` from a caught error, needs no change.
+
+`AppError` (`stitchkit/contract`, `stitchkit/server`, `stitchkit/node`) and `ApiError`
+(`stitchkit`) keep the code as the one positional argument. Every other value is a named
+option, so a call site reads without the signature open. `new AppError(code)` and
+`new ApiError(code)` are unchanged. The compiler finds every old call: a string or number
+in the second position is a type error.
+
+1. `AppError`: move `message`, `status`, `details`, `hint`, `traceId` and `retryable` into one
+   object after the code. `status` defaults to 500 and `message` to the code.
+
+   ```ts
+   // before
+   throw new AppError('CONFLICT', 'Selection is stale', 409, { revision: 7 })
+   throw new AppError('BUSY', 'Try later', 503, undefined, undefined, undefined, true)
+   // after
+   throw new AppError('CONFLICT', { message: 'Selection is stale', status: 409, details: { revision: 7 } })
+   throw new AppError('BUSY', { message: 'Try later', status: 503, retryable: true })
+   ```
+
+2. A subclass passes the same object to `super`:
+
+   ```ts
+   // before
+   super('FEATURE_LOCKED', 'locked', 403)
+   // after
+   super('FEATURE_LOCKED', { message: 'locked', status: 403 })
+   ```
+
+3. `ApiError`: the old order was `code, status, details, message, hint, traceId, errorOptions,
+   retryable`. Name each value; `status` defaults to 0 and the former `ErrorOptions` argument
+   is now the `cause` option.
+
+   ```ts
+   // before
+   new ApiError('RATE_LIMITED', 429, undefined, 'slow down', 'wait', 'trace-1', { cause }, true)
+   new ApiError('VALIDATION_ERROR', 0, { issues }, 'bad input')
+   // after
+   new ApiError('RATE_LIMITED', { status: 429, message: 'slow down', hint: 'wait', traceId: 'trace-1', retryable: true, cause })
+   new ApiError('VALIDATION_ERROR', { status: 0, details: { issues }, message: 'bad input' })
+   ```
+
+4. Both classes accept the standard `cause`, which `error.cause` returns; omit the option to
+   leave the property absent.
+
 ## Released migration: 0.104.0
 
 JS bundles carrying Darwin native capabilities also need the
@@ -15444,10 +16027,20 @@ that work actually completes.
 
 ### Darwin native assets in JS distributions
 
-**Who must act:** Bun JS builds using `--outfile`, copying only `outputs[0]`, custom
-single-file/archive packagers and installers delivering native process/files capabilities.
-First affected publication: **0.103.13**. It shipped as a patch; its changed delivery graph
-requires this migration despite unchanged API signatures.
+**Who must act:** Bun builds that import `stitchkit/server`, `stitchkit/files` or
+`stitchkit/process` (Linux-only server apps included) and use `--outfile`, copy only
+`outputs[0]`, or package a single file; custom single-file/archive packagers and installers
+delivering native process/files capabilities.
+First affected publication: **0.103.13**, through **0.104.2**. It shipped as a patch; its
+changed delivery graph requires this migration despite unchanged API signatures.
+
+In those versions every Bun bundle that reaches the lock or process-identity code,
+`stitchkit/server` included, carries both Darwin `.node` addons as extra outputs on every
+operating system. `bun build --outfile` then fails with
+`cannot write multiple output files without an output directory`, and `--outdir` writes the
+addons next to a Linux artifact. Releases after 0.104.2 resolve the default loader at run time,
+so these bundles are one JS file with no `.node` output again. The static loader exists only
+in a build that uses the `stitchkit/files/packaging` plugin.
 
 ```sh
 # Before: one JS file was assumed to be the entire distribution.
@@ -15464,12 +16057,39 @@ Custom output layout uses the evolving build-only packaging contract in the
 
 Three deliveries have different rules: an ordinary npm install retains the package's
 native assets; a JS distribution must ship its complete output graph; a Bun compiled
-executable embeds the matching addon and may still use `--outfile`.
+executable embeds the matching addon and may still use `--outfile`. In 0.103.13–0.104.2 a plain
+`bun build` carries the addon without a plugin; later releases carry it only when the build
+uses `createNativePackaging` (`delivery: 'companion'` for JS, `'embedded'` for a compiled
+executable).
 The [native IO guide](native-io.md#libraries-with-a-zod-only-runtime) is the canonical recipe.
 Check the resulting artifact offline outside the build tree and `node_modules`, including
 process identity, live-owner lock refusal, dead-owner recovery and contained IO.
 A missing or corrupt addon remains `unavailable`, never evidence that an owner died.
 
+### CLI: repeated options are refused
+
+**Who must act:** wrappers, aliases and scripts that append `--json`, `--profile X` or an
+application global to arguments the user may already have given, and anything that passes the
+same global twice.
+First affected publication: **0.103.13**. It shipped as a patch; the change in grammar needs
+this migration.
+
+A repeated option that is not an array field is an argument error:
+`--json --json` and `--profile a --profile b` fail with `--json was passed 2 times`. Before
+0.103.13 the last value won, for framework globals, application globals and repeated
+`kind: 'other'` fields alike. Array fields, and untyped passthrough fields that keep their
+raw-list grammar, still repeat.
+
+```sh
+# Before: a wrapper appended its default and the last value won.
+mytool deploy --profile staging "$@" --profile production
+# After: build the argument list once, so each option appears once.
+mytool deploy --profile "${PROFILE:-production}" "$@"
+```
+
+Dotted leaves such as `--filter.name` follow the same rule as their parent field. Declare a
+field as an array when repetition is meant.
+
 ## Released migration: 0.103.0
 
 ### Diagnostic journal startup preserves torn evidence and inspects archives
@@ -19257,15 +19877,6 @@ end of this file.
 # Guide: Project declaration  (docs/guide/declaration.md)
 ==============================================================================
 
----
-title: Project declaration
-description: One machine-readable statement a repository makes about itself — identity, roles, build, requirements, release steps and the names of the values a deployment supplies.
-type: architecture
-status: active
-created: 2026-08-25
-updated: 2026-08-30
----
-
 # Project declaration
 
 > **Maturity: evolving.** This surface is still finding its shape and may be
@@ -19828,6 +20439,7 @@ schedules, transports and file generation remain application-owned.
 |---|---|---|
 | `canonicalJson` | function | bounded plain JSON, UTF-16 key sort, optional object members omitted |
 | `CanonicalJsonOptions` | type | inferred depth/node/UTF-8 bytes limits |
+| `CanonicalJsonError` / `CanonicalJsonRefusal` | class / _type_ | the `TypeError` of a refusal and its `reason`: `cycle`, `negative-zero`, `depth`, `nodes`, `bytes` or `not-json` |
 
 
 ## `stitchkit/server`
@@ -19981,7 +20593,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 ### Primitives
 
 | `createFileStateStore` | function | cross-process locked atomic JSON state updates over one Zod schema |
-| `FileStateStoreCorruption` / `FileStateStoreOptions` | _type_ | explicit corrupt-state report/policy and lock timing configuration |
+| `FileStateStoreCorruption` / `FileStateStoreOptions` | _type_ | explicit corrupt-state report/policy, lock timing and the state read cap `maxBytes`; a transition whose resulting state encodes to the bytes it started from writes nothing |
 | Export | Kind | Summary |
 |--------|------|---------|
 | `streamSSE` | function | an async generator → SSE `Response` — [guide](../guide/server.md#sse-streaming) |
@@ -20087,7 +20699,7 @@ cutovers are covered by the executable
 | `NotificationOutboxItem` / `NotificationOutboxReceipt` / `NotificationOutboxState` / `NotificationSend` / `NotificationFailureClassification` / `DroppedNotification` / `EnqueueNotification` | _type_ | versioned queue records, stable send identity and delivery decisions |
 | `notificationOutboxStateSchema` | function | strict persisted-state schema over an application payload schema |
 | `notificationOutboxResource` / `NotificationOutboxResource` / `NotificationOutboxResourceConfig` | function / _type_ | thin managed-resource scheduler over an outbox handle |
-| `createDirectoryInbox` (from `stitchkit/application/directory-inbox`) / `DirectoryInbox` / `DirectoryInboxConfig` / `DirectoryInboxDelivery` / `DirectoryInboxResource` | function / _type_ | one managed directory inbox for files or durable `accept({ source, key, entry })`; first payload wins, bounded capacity/bytes/receipts and renewable fenced leases; delivery begins after readiness and effects remain at least once |
+| `createDirectoryInbox` (from `stitchkit/application/directory-inbox`) / `DirectoryInbox` / `DirectoryInboxConfig` / `DirectoryInboxDelivery` / `DirectoryInboxResource` | function / _type_ | one managed directory inbox for files or durable `accept({ source, key, entry })` (`entry` is the schema's input, stored as given); a hard-linked file is set aside as `invalid`; first payload wins, bounded capacity/bytes/receipts and renewable fenced leases; delivery begins after readiness and effects remain at least once |
 | `DirectoryInboxIdentitySchema` / `DirectoryInboxIdentity` / `DirectoryInboxAccept` / `DirectoryInboxAcceptResultSchema` / `DirectoryInboxAcceptResult` | schema / _type_ | validated source/key, typed entry and durable accepted/duplicate result with filename; duplicates do not replace the first payload |
 | `StateStoreUpdateContext` | _type_ | real active protected transaction: `assertHeld()` refuses after ownership loss or completion; custom adapters supply this context to their transition |
 | `DirectoryInboxStateSchema` / `DirectoryInboxState` / `DirectoryInboxRejection` / `DirectoryInboxRejectionReasonSchema` / `DirectoryInboxRejectionReason` | schema / _type_ | the inbox's claims, receipts and rejections (`invalid`, `too-large`, `attempt-limit`) |
@@ -20173,9 +20785,10 @@ cutovers are covered by the executable
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createDiagnosticJournal` | function | create one schema-owned FIFO JSONL writer with bounded retained memory, exclusive local path ownership and finite rotation |
-| `DiagnosticJournalConfig` / `DiagnosticJournal` | _type_ | owner schema/path/limits/failure observer and the synchronous `submit`, bounded-wait `flush`/`close`, status handle |
+| `DiagnosticJournalConfig` / `DiagnosticJournal` | _type_ | owner schema/path/limits/failure observer, `startupScan` (`tails` by default, or `full`), `onStartupRefusal` (`quarantine` by default, or `fail`) and the synchronous `submit`, bounded-wait `flush`/`close`, status handle |
 | `DiagnosticJournalLimitsSchema` / `DiagnosticJournalLimits` | schema / _type_ | positive event, pending-item, pending-byte, file-byte and retained-file limits |
 | `DiagnosticJournalLockPolicySchema` / `DiagnosticJournalLockPolicy` | schema / _type_ | `refuse` (default) or `reclaim-stale`, which reclaims only a lock whose recorded owner is provably gone |
+| `DiagnosticJournalStartupScanSchema` / `DiagnosticJournalStartupScan` | schema / _type_ | how much of the retained generations opening a journal reads: `tails` (default) checks only the end of each file for a torn line, `full` parses every line |
 | `readDiagnosticJournalLockDiagnosis` / `DiagnosticJournalLockDiagnosis` | function / _type_ | why a `reclaim-stale` acquisition refused — attribution, PID liveness and optional process `identity` evidence (`matched`, `different-boot`, `reused-pid`, `pid-gone`, `legacy`, `unavailable`) — read off the thrown `EEXIST` |
 | `DiagnosticJournalSubmitResultSchema` / `DiagnosticJournalSubmitResult` | schema / _type_ | accepted epoch/sequence or explicit invalid, oversized, capacity, closed or failed refusal |
 | `DiagnosticJournalStatusSchema` / `DiagnosticJournalStatus` | schema / _type_ | state, limits, exact admission/write/failure counters, pending ownership, rotations, partial tails and last safe sequences |
@@ -20188,8 +20801,10 @@ cutovers are covered by the executable
 | `DiagnosticJournalWaitOptions` / `DiagnosticJournalFailure` | _type_ | caller wait signal/timeout and isolated internal failure callback record |
 | `DiagnosticJournalAnomalySchema` / `DiagnosticJournalAnomaly` | schema / _type_ | corrupt-row reason, file, zero-based byte offset, one-based line, tail/interior position and skipped bytes |
 | `createDiagnosticJournalReadResultSchema` / `DiagnosticJournalReadResult` | function / _type_ | owner-schema frame output or explicit anomaly; retains transformed event output types |
-| `DiagnosticJournalRecoveryStatusSchema` / `DiagnosticJournalRecoveryStatus` | schema / _type_ | bounded startup inspection counts and first/last anomaly locations |
-| `DiagnosticJournalRecoveryError` | class | torn single-file startup refusal carrying recovery observations, preserving evidence and releasing its lock |
+| `DiagnosticJournalRecoveryStatusSchema` / `DiagnosticJournalRecoveryStatus` | schema / _type_ | bounded startup inspection counts, first/last anomaly locations and every quarantined file beside the journal (`quarantined`, this open's moves first with their `reason`, at most 32; `quarantinedUnlisted` counts the rest); evolving and `.strict()`, so every shape change is a breaking changelog item |
+| `DiagnosticJournalStartupRefusalPolicySchema` / `DiagnosticJournalStartupRefusalPolicy` | schema / _type_ | `quarantine` (default) renames a file opening cannot keep in place to `<file>.quarantined-<epoch>` and starts; `fail` throws and moves nothing |
+| `DiagnosticJournalStartupRefusalReasonSchema` / `DiagnosticJournalStartupRefusalReason` | schema / _type_ | `torn-without-retention-slot \| not-a-regular-file \| unreadable` |
+| `DiagnosticJournalRecoveryError` / `DiagnosticJournalRecoveryErrorOptions` | class / _type_ | typed startup refusal (`reason`, `file`, optional `recovery`, `quarantineFailed`) thrown under `fail` or when moving a file aside failed; preserves evidence and releases its lock |
 
 `accepted` is bounded in-memory admission and `written` is completed append, not `fsync` or durable
 delivery. Its filesystem reader is in the diagnostic-journal leaf; there is no managed replay/upload API. See the
@@ -20495,7 +21110,7 @@ Server-only optional application runtime. See the
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `AgentConversationArchiveSchema` / `AgentConversationArchive` / `encodeAgentConversationArchive` / `decodeAgentConversationArchive` / `canonicalAgentJson` | schema / _type_ / functions | canonical validated conversation archive with exact ledger events, recovery projection and durable spill payloads |
+| `AgentConversationArchiveSchema` / `AgentConversationArchive` / `encodeAgentConversationArchive` / `decodeAgentConversationArchive` / `canonicalAgentJson` | schema / _type_ / functions | canonical validated conversation archive (`canonicalAgentJson` is `canonicalJson` with the node and byte limits at their maximum, reading `-0` as `0` like `z.json()`) with exact ledger events, recovery projection and durable spill payloads |
 | `AgentStoreEventEnvelopeSchema` / `AgentStoreEventEnvelope` / `AgentStoreEventKindSchema` / `AgentStoreEventKind` / `AgentStoreEventPageSchema` / `AgentStoreEventPage` | schema / _type_ | append-only event envelope, closed current vocabulary (including `provider/request` and `provider/response`) and bounded page |
 | `AppendAgentStoreEventSchema` / `AppendAgentStoreEvent` / `ReadAgentStoreEventsSchema` / `ReadAgentStoreEvents` | schema / _type_ | required append and bounded-read store contracts |
 | `AgentStoreTransitionSchema` / `AgentStoreTransition` / `AgentStoreEventDraft` / `AgentStoreEventDecodeAccepted` / `AgentStoreEventDecodeIgnored` / `AgentStoreEventDecodeResult` / `decodeAgentStoreEvent` | schema / _types_ / function | normalized runtime mutations, append drafts and strict current/ignorable future-event decoding outcomes |
@@ -20505,7 +21120,7 @@ Server-only optional application runtime. See the
 | `defineStateSlot` / `AgentStateSlotDefinition` / `AgentStateSlotStore` / `AgentStateSlotValue` / `AnyAgentStateSlot` / `createAgentStateSlotStore` / `renderAgentStateSlots` | functions / _types_ | typed durable state written as ledger events and injected on every provider request |
 | `agentGoalStateSlot` / `agentTodoStateSlot` / `createAgentStateTools` | constants / function | built-in goal/todo state and bound `goal_*` / `todo_write` Agent tools |
 | `AgentSandboxGradeSchema` / `AgentSandboxGrade` / `AgentSandboxRestrictionSchema` / `AgentSandboxRestriction` / `AgentProcessSandbox` | schema / _type_ | host-provided process sandbox capability and explicit restriction vocabulary |
-| `probeAgentProcessSandbox` / `missingSandboxRestrictions` / `recordAgentSandboxProbe` | functions | process-cached probe, fail-closed required-gap calculation and durable probe record |
+| `probeAgentProcessSandbox` / `missingSandboxRestrictions` / `recordAgentSandboxProbe` | functions | probe cached per sandbox object (keep the sandbox long-lived), fail-closed required-gap calculation and durable probe record; a probe that throws or returns no valid grade resolves to `unavailable` with a fixed reason, its cause emitted as a process warning (the coding tools instead carry it as the refusal's `cause` to the mount's `onToolError` hook) |
 | `AgentSandboxProcess` / `AgentSandboxOutputStream` | _types_ | structural child/output interface for optional lifecycle-owned `AgentProcessSandbox.spawn`, without Node ambient type dependencies |
 | `AgentEventSearchResultSchema` / `AgentEventSearchResult` / `createSqliteAgentEventSearch` / `createAgentEventSearchTools` | schema / _type_ / functions | authorized FTS5 search with exact event addresses and `session_*` tools |
 | `createSqliteAgentSpillStore` | function | durable content-address-checked artifact storage, bounded read/search, retention facts and archive participation |
@@ -20800,7 +21415,10 @@ terminal and provider-envelope schemas/types listed under
 including `AgentAttemptResetEventSchema` for `attempt-reset`),
 `AgentRuntimeEventCursorSchema`, `advanceAgentRuntimeEventCursor`,
 `AgentControlRequestSchema` / `AgentControlRequest`, `AgentControlResponseSchema` /
-`AgentControlResponse`, `AgentControlDeliverySchema` / `AgentControlDelivery`, `AgentMultiSessionCursorSchema` /
+`AgentControlResponse`, `AgentControlDeliverySchema` / `AgentControlDelivery`,
+`AgentControlErrorCodeSchema` / `AgentControlErrorCode` (the one vocabulary of every control
+error code: `FORBIDDEN`, `CONNECTION_CLOSED`, `REQUEST_CAPACITY`, `ATTACHMENT_CAPACITY`,
+`LEASE_CONFLICT`, `EVENT_OVERFLOW` and the rest), `AgentMultiSessionCursorSchema` /
 `AgentMultiSessionCursor`, `AgentConversationView`, `AgentControlView`,
 `advanceAgentMultiSessionCursor`, `createAgentControlView`, `reduceAgentControlSnapshot`,
 `reduceAgentControlEvent` and
@@ -20830,9 +21448,12 @@ attachment per conversation on that transport; share the controller between view
 `submit` requires a caller-owned idempotency key. Unknown-outcome mutations are never
 replayed automatically. `AgentControllerState` distinguishes connecting, ready,
 disconnected, error and closed and retains the canonical full `view` plus safe error
-code/message. Errors in automatic attach/refresh appear there. Reconnect attaches again
-and reads a snapshot; snapshot gaps coalesce, stale generations cannot overwrite state,
-and buffers/queues are bounded. Overflow or failed refresh is visible and requires
+code/message. Errors in automatic attach/refresh appear there, and so does an
+`access-denied` delivery: the server detached the conversation, the state becomes
+`error` with code `FORBIDDEN`, and nothing arrives until the controller attaches again.
+Reconnect attaches again and reads a snapshot; requests of the previous connection are
+rejected at once and release their capacity, snapshot gaps coalesce, stale generations
+cannot overwrite state, and buffers/queues are bounded. Overflow or failed refresh is visible and requires
 explicit recovery. Closing detaches without closing the shared transport or remote run.
 
 See [agent composition](../guide/agent-composition.md) for a complete wiring example.
@@ -21061,10 +21682,10 @@ payload.
 | `McpMountConfig` | _type_ | config for `mountMcp` |
 | `McpSchemaValidationConfig` | _type_ | shared `{ policy, requireTypedProperties, allowUntyped, requirePortableFormats, allowFormats }` profile |
 | `ValidateMcpSchemasConfig` | _type_ | standalone validation profile plus `services`, `extend`, flattening and logger |
-| `RuntimeToolDefinition` | _type_ | transport-neutral pathless operation with identity, schemas, handler and optional presenters |
+| `RuntimeToolDefinition` | _type_ | heterogeneous registration of pathless operations in `runtimeTools: [...]`; an inline handler is contextually typed by the parsed object, a definition constructed with its own schema registers unchanged, and the runner validates input before the handler |
 | `RuntimeToolDefinitionBase` | _type_ | common name, identity, input, exposure and MCP metadata fields |
-| `RuntimeToolDefinitionWithOutput` | _type_ | runtime definition whose handler and presenters share a validated output type |
-| `RuntimeToolDefinitionWithoutOutput` | _type_ | runtime definition with a void handler and no presentation callbacks |
+| `RuntimeToolDefinitionWithOutput` | _type_ | the one neutral construction: identity, schemas and a handler typed from them; the fourth type argument names the adapter's `present` extension (`RuntimeToolPresenters<…>` here, `RuntimeMcpToolPresenters<…>` on `stitchkit/tools/mcp`, none by default) |
+| `RuntimeToolDefinitionWithoutOutput` | _type_ | the same construction with a void handler and no presentation callbacks |
 | `RuntimeToolFactory` | _type_ | identity/context-bound runtime-tool definition factory |
 | `RuntimeToolFactoryConfig` | _type_ | factory service identity and context schema |
 | `RuntimeToolFactoryDefinitionWithOutput` | _type_ | factory-authored runtime tool with a validated output schema |
@@ -21273,10 +21894,9 @@ Advanced building blocks — the shared machinery the mounts are built on.
 | `ToolCallRecord` | _type_ | the structured record `createToolLogger` passes to `onRecord` |
 | `TransportSummary` | _type_ | `{ contractServices, runtimeTools, totals, sources }` from `summarizeTransports` |
 | `TransportCounts` | _type_ | per-transport counts (`{ HTTP, MCP, AGENT, CLI }`) |
-| `ToolSurfaceDefinition` | _type_ | shared object-shaped `{ services?, runtimeTools? }` introspection surface |
-| `ToolSurfaceProjection` | _type_ | one readonly services/runtime container shared by full and MCP-only surfaces; executable mounts specialize the runtime definition without pulling in another adapter's peers |
+| `ToolSurfaceProjection` | _type_ | the one readonly `{ services?, runtimeTools? }` container shared by full, MCP-only and introspection surfaces (`buildToolManifest`, `listToolNames`, `summarizeTransports` take `ToolSurfaceProjection<RuntimeToolDefinition>`) |
 | `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
-| `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments |
+| `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments; throws a `ZodError` naming the field when a union that keeps a string member receives a string that parses to an array its array member accepts |
 | `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; scalar collisions retain provable types, object/array collisions retain structural alternatives, and field descriptions retain discriminator labels plus availability/requiredness hints; the projection never executes validation |
 | `ToolPresentationSchema` | _type_ | immutable model-facing JSON Schema document shared by tool transports |
 | `MountableTool` | _type_ | one operation with separate executable CLI argument schema and model-facing presentation schema |
@@ -21295,10 +21915,9 @@ behavior and names. See [MCP guide](../guide/mcp-and-agents.md#mcp--createmcphan
 |--------|------|---------|
 | `createMcpHandler` / `createMcpHttpRoute` / `buildMcpServer` / `mountMcp` | function | the shared authenticated HTTP handler, raw-route adapter, SDK server and contract mount |
 | `createStdioMcpServer` / `bindStdioProcessSignals` | function | the shared stdio server and bounded process cleanup |
-| `RuntimeMcpToolDefinitionWithOutput` | _type_ | schema-aware MCP-only construction with concrete handler output and presenter input |
-| `RuntimeMcpToolDefinition` | _type_ | heterogeneous MCP registration; the canonical runner validates input/output before invocation |
+| `RuntimeToolDefinitionWithOutput` / `RuntimeToolDefinitionWithoutOutput` | _type_ | the one neutral construction, shared with `stitchkit/cli` and `stitchkit/tools`; MCP-only presenters are its fourth type argument, `RuntimeMcpToolPresenters<z.output<typeof output>>` |
+| `RuntimeToolDefinition` | _type_ | heterogeneous registration; the canonical runner validates input/output before invocation |
 | `RuntimeMcpToolPresenters` / `RuntimeMcpPresentation` | _type_ | official SDK content without framework-owned `structuredContent` or `isError`; one presenter owner shared with the full SDK surface |
-| `RuntimeToolDefinitionWithoutOutput` | _type_ | the shared neutral void definition |
 
 ## `stitchkit/tools/connections`
 
@@ -21398,7 +22017,6 @@ handler pipeline without opening a TCP port.
 | `McpSchemaValidationConfig` / `IncompatibleSchemaPolicy` | _type_ | canonical MCP schema-preparation policy used by real mounts and manifests |
 | `SurfaceRealtimeSchemaPairSchema` | schema | input/output digest pair for args or acknowledgements |
 | `SurfaceSchemaDigestsSchema` | schema | params/input/output/multipart digest object |
-| `serializeSurfaceValue` | function | canonical versioned serialization used for deterministic digests |
 
 ---
 
@@ -21419,8 +22037,10 @@ available from `stitchkit/contract`.
 | `ManagedFileError` / `ManagedFileErrorCode` | class / _type_ | stable boundary failures; registered `FILE_*` mistakes are caller-safe while `FILE_IO_ERROR` remains internal |
 | `ManagedFileInspector` | _type_ | bounded-prefix read/write inspection callback with a finite cancellation signal that cannot own path or size |
 | `ManagedFileInspectionInput` / `ManagedFileInspection` | _type_ | inspector prefix/name/declared media/signal input and validated metadata-only result |
-| `writeFileAtomic` / `writeFileAtomicSync` / `WriteFileAtomicOptions` | function / _type_ | replace a file atomically: a random staging name created exclusively (never through a planted link), the mode set on the descriptor before the file is visible (default `0o600`, not masked by the umask), `fsync`, rename; a failure leaves the target and no staging file. The asynchronous form keeps the event loop running |
-| `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time and nullable kernel process identity); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; an ownerless lock only after `ownerlessGraceMs` (default 5000 ms, `null` disables age-based reclaim including guards); exact `mode` is independent of umask; shared readers need a common group and traversable directories |
+| `writeFileAtomic` / `writeFileAtomicSync` / `WriteFileAtomicOptions` | function / _type_ | replace a file atomically: a random staging name created exclusively (never through a planted link), the mode set on the descriptor before the file is visible (default `0o600`, not masked by the umask), `fsync`, rename; a failure leaves the target and no staging file. The asynchronous form keeps the event loop running. A process killed before publication leaves its staging file; sweeping it is the caller's job |
+| `isAtomicStagingName` | function | true for a staging file name of an atomic write of this library (`.stitchkit-<24 lowercase hex>.tmp`, also used by the managed writer and the chunk spool); the form is a stable contract, and changing it is a breaking change ([ADR 0242](../decisions/0242-atomic-staging-name-is-a-public-contract.md)) |
+| `sweepAtomicStaging` / `SweepAtomicStagingOptions` | function / _type_ | remove abandoned staging files from one `directory`: only regular files matching `isAtomicStagingName` and older than the required `olderThanMs`, never following a symlink or entering a subdirectory; stops on `signal`; returns the removed names |
+| `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time and nullable kernel process identity); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; the lock is published with its owner already recorded (temporary file plus hard link), so a stalled holder is never displaced; a legacy empty lock file is taken by age only when `ownerlessGraceMs` is a number (default `null`: never; an abandoned empty reclaim guard is taken after 5 000 ms unless a value is set); exact `mode` is independent of umask; shared readers need a common group and traversable directories |
 | `ExclusiveLockError` | class | `LOCK_TIMEOUT` naming the resource and its holder, or `LOCK_ABORTED` with the signal's reason |
 | `createChunkSpool` | function | the server half of a chunked upload: parts on disk under `owner` + client-minted `uploadId`, each with a size+sha256 receipt; idempotent `open` and `put`, the first writer of a part wins across processes, `assemble` in order once every part is in, `sweep` of untouched uploads — [guide](../guide/client.md#chunked-uploads) |
 | `ChunkSpool` / `ChunkSpoolConfig` / `ChunkSpoolKey` / `ChunkSpoolOpen` / `ChunkSpoolPart` / `ChunkSpoolAssembly` | _type_ | the spool, its directory, part size, file limit, meta schema and age; an upload's key; its declaration; one part; the assembled parts with a concatenating `stream()` |
@@ -21798,7 +22418,6 @@ SDK nor the `ai` peer.
 | `checkCliUpdate` | function | bounded, interval-limited, never-throwing check for a newer published build |
 | `applyCliUpdate` | function | download, verify the decompressed digest and replace the binary by rename |
 | `assertCliPublishable` | function | refuse republishing one version from a different commit — takes one manifest or every manifest already published, because the promise a version makes does not stop at a channel boundary |
-| `publishCli` / `CliPublicationOptions` / `CliPublicationPhase` / `CliPublicationResult` | function / _type_ | optional bounded builder/admission over one immutable name/version/commit stamp; commit verified assets before the manifest pointer, recover exact completed versions, retain verified history; existing signatures/installer/updater own the wire contract |
 | `rollbackCliUpdate` / `CliRollbackConfig` / `RolledBackCliUpdate` | function / _types_ | put the kept previous build back, digest-checked first and written by the same atomic rename the update uses |
 | `signCliManifest` / `verifyCliManifest` / `cliManifestSigningPayload` | function | Ed25519 over `{name, version, commit, builtAt, assets[]}` — every asset's digest included, so the chain closes on the file that executes |
 | `cliSignatureAccepted` / `CliSignatureVerdict` | function / _type_ | `valid` \| `unenforced` \| `missing` \| `unknown-key` \| `invalid`; `unenforced` keeps an unpinned build updating while making the absence of a check visible |
@@ -21830,8 +22449,8 @@ SDK nor the `ai` peer.
 | `CliConfig` | _type_ | config for `createCli`; `defaultCommand`, `globalOptions`, `optionAliases` and `positionals` define the shared command presentation policy |
 | `CliPresentationPolicyConfig` | _type_ | shared command presentation-policy subset of `CliConfig` |
 | `CliSurfaceSource` | _type_ | static service/runtime array or identity-dependent factory |
-| `RuntimeToolExecution` | _type_ | neutral heterogeneous runtime-tool registration; handlers execute through the schema-validating managed runner |
-| `RuntimeToolExecutionWithOutput` | _type_ | strict neutral managed definition with schema-derived handler input/output; construct before adding to CLI `runtimeTools` |
+| `RuntimeToolDefinition` | _type_ | neutral heterogeneous runtime-tool registration; an inline handler is contextually typed, and handlers execute through the schema-validating managed runner |
+| `RuntimeToolDefinitionWithOutput` | _type_ | strict neutral managed definition with schema-derived handler input/output, the same declaration `stitchkit/tools` constructs with presenters |
 | `RuntimeToolDefinitionWithoutOutput` | _type_ | strict neutral managed void definition without an output contract or transport presenters |
 | `CliCommandDefinition` | _type_ | native command definition union |
 | `CliCommandDefinitionBase` | _type_ | native command name, description and input schema |
@@ -21848,6 +22467,22 @@ SDK nor the `ai` peer.
 
 ---
 
+## `stitchkit/cli/publish`
+
+Build and release tooling, evolving. Publishes a CLI distribution into a local
+application-owned directory; the manifest, signatures, installer and updater it
+writes for stay in `stitchkit/cli` — [guide](../guide/cli.md#publishing-a-complete-version),
+[ADR 0245](../decisions/0245-cli-publication-is-an-evolving-leaf.md).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `publishCli` | function | optional bounded builder/admission over one immutable name/version/commit stamp; commit verified assets before the manifest pointer, recover exact completed versions, retain verified history |
+| `CliPublicationOptions` | _type_ | identity, storage root, base URL, targets, limits, retention, the `admit` and `build` callbacks, optional signing and trust |
+| `CliPublicationPhase` | _type_ | the step `admit` is asked about — `prepare`, `build`, `commit` or `promote` |
+| `CliPublicationResult` | _type_ | `published` or `existing`, with the manifest ready to serve |
+
+---
+
 ## `stitchkit/react`
 
 Browser- and server-render-safe React data-layer helpers. Needs the
@@ -21936,11 +22571,20 @@ network enforcement, gateway credentials and platform/resource boundaries.
 
 ## `stitchkit/agent-runtime/realtime`
 
-Optional evolving Socket.IO server binding. `bindAgentHarnessRealtime` takes `(harness, socket, config)` and returns `close()` for its subscriptions and control connections, without closing
-socket or harness. `AgentHarnessRealtimeConfig` requires `authorize({ identity, request,
-signal })`: return `{ context }` after verifying the session principal, conversation,
-operation, files and metadata, or `null`. Identity is `socket.data` from the application's
-verified handshake. Every request and event delivery is authorized. Observe access does
+Optional evolving Socket.IO server binding, experimental: no committed consumer yet.
+`bindAgentHarnessRealtime` takes `(harness, socket, config)` and returns an
+`AgentHarnessRealtimeBinding`: `close()` for its subscriptions and control connections, without closing
+socket or harness, and `revoke(conversationId, matches?)`. `AgentHarnessRealtimeConfig` requires
+`authorize({ identity, request, source, signal })`: return `{ context }` after verifying the session
+principal, conversation, operation, files and metadata, or `null`. Identity is `socket.data` from the
+application's verified handshake. Every request is authorized on arrival. The events of an
+attached conversation are delivered under the grant the latest successful request created, so a
+token stream costs no authorization call per event. `revoke` drops the grant of every matching
+socket; the next event is re-authorized (`source: 'delivery'`, an `operation: 'snapshot'` request),
+and a refusal or failure detaches the conversation and sends an `access-denied` delivery, which
+turns the browser controller into an `error` state. Without a `revoke` call a grant lasts until the socket disconnects or the conversation
+is detached; this fail-open default is deliberate, so call `revoke` whenever access to a conversation may
+have been withdrawn. An authorization that began before a `revoke` never restores the grant. Observe access does
 not grant mutation; controller leases and approval policy still belong to the harness.
 
 `maxPendingEvents` and `maxPendingAttachments` forward to the canonical control server;
@@ -21952,23 +22596,11 @@ application transport. A transport's Engine.IO payload limit remains application
 
 ## `stitchkit/agent-runtime/react`
 
-Optional evolving React peer leaf. `useAgent` takes a controller and subscribes through
+Optional evolving React peer leaf, experimental: no committed consumer yet. `useAgent` takes a controller and subscribes through
 `useSyncExternalStore`, returning the same `AgentControllerState` as `getSnapshot()`.
 Create and close the controller at application/session scope. Multiple components can
 observe it; StrictMode and unmount release only the component's own subscription.
 
-## `stitchkit/agent-runtime/harness-tools`
-
-Optional evolving composition of the full `mountAgent` configuration with the runtime
-fence. Its runtime peer is `ai`; its full tool presenter declarations also require
-`@modelcontextprotocol/server`, as `stitchkit/tools` does. The base harness retains its
-AI-only peer boundary. Existing custom tool callbacks need no new import.
-
-| Export | Kind | Summary |
-|--------|------|---------|
-| `createAgentHarnessTools` / `AgentHarnessToolsConfig` | function / _type_ | async per-run full mount configuration (`services` plus all `AgentMountConfig` options); composes application lifecycle then runtime fence exactly once |
-
-
 ## `stitchkit/process`
 
 Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/native-io.md).
@@ -21976,7 +22608,8 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 | Export | Kind | Purpose |
 |---|---|---|
 | `runNativeCommand` | function | caller-lifetime streaming or explicitly bounded binary capture |
-| `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink and finite cleanup limits |
+| `NativeCommandOptions` | type | executable/args, env policy, signal/deadline, bytes sink, finite cleanup limits, the `stop` policy and `descendants` (`'terminate-after-leader'`, the default: stop the group after the leader exits, or `'leave'`) |
+| `NativeCommandStopPolicy` | type | how a cancelled command stops: `target` `'group'` (signal every member) or `'leader'` (signal only the leader; its exit ends the grace), `signal` (default `SIGTERM`), `graceMs` (at most one hour) before KILL to the group, and `killOn`, an `AbortSignal` that skips the grace; default `{ target: 'group', signal: 'SIGTERM', graceMs: 100 }` |
 | `NativeCommandResult` | type | observed nullable exit code/signal and captured stdout/stderr bytes |
 | `NativeCommandError` | class | COMMAND_LIMIT with machine reason `deadline` or `output-budget`; COMMAND_UNAVAILABLE / COMMAND_CLEANUP have no limit reason. Preserves internal cause and existing constructor; caller-created limits without supplied reason remain unclassified |
 
@@ -21989,12 +22622,27 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 
 `stitchkit/files/packaging` owns `createNativePackaging` and the types
 `NativePackagingOptions`, `NativePackagingAsset`, `NativePackagingPlugin`, `NativePackagingResult`.
-It resolves the installed package's target/version and original addon SHA256.
-`platform`, `architecture`, `delivery`, `entryPath` and `assetPath` are explicit public inputs.
-The result is `ready` with assets and a structural Bun plugin, or `unsupported`/`missing` with a safe code.
-Malformed options/metadata and other filesystem errors fail rather than masquerade as missing.
-Companion mode places an external addon relative to the emitted entry; embedded mode lets
-Bun compile retain the matching addon. Keep JS builds without splitting, preserve every output,
-and copy each original asset to its `outputPath` after verifying `sha256`.
+It resolves the installed package's target/version, reads each selected addon once and checks it
+against the `size` and `sha256` published in the package's `native-assets.json` (`formatVersion: 2`,
+written when Stitchkit is built). Call it once per build and reuse the result.
+`platform`, `architecture`, `delivery`, `entryPath` and `assetPath` are explicit public inputs;
+`platform` is the closed set `'darwin'`, and another name is a type error and a schema refusal.
+The result is `ready` with verified assets and a structural Bun plugin, or `unsupported` /
+`missing` / `mismatch` with the safe code `NATIVE_TARGET_UNSUPPORTED`, `NATIVE_ASSET_MISSING` or
+`NATIVE_ASSET_DIGEST_MISMATCH`. A `mismatch` names the first differing `architecture` with
+`expected` (published) and `actual` (installed) `{ size, sha256 }`.
+Malformed options, a manifest of another `formatVersion` and other filesystem errors throw rather
+than masquerade as missing.
+Companion accepts a single `architecture` string with an `assetPath` string, or an architecture
+array with an exact per-architecture `assetPath` map. `NativePackagingOptions<true>` and
+`NativePackagingResult<true>` describe the array form; default types preserve single-target signatures.
+A ready array-form result carries the architecture array; `NativePackagingAsset<true>` identifies
+each asset architecture. A single-target asset has four fields: `outputPath`, the verified `bytes`,
+and the published `size` and `sha256`.
+Targets must be unique; entry and all asset paths must be disjoint. One lazy loader chooses only
+the actual runtime architecture, with no fallback.
+Companion mode places external addons relative to the emitted entry; embedded mode gives
+Bun compile the verified bytes of the matching addon. Keep JS builds without splitting, preserve
+every output, and write each asset's `bytes` to its `outputPath`.
 This evolving entrypoint is a build dependency; runtime imports do not reach it.
 The detailed recipe is in [native IO](../guide/native-io.md#public-native-packaging).