stitchkit 0.103.12 → 0.104.0

package/llms-full.txt

@@ -54,10 +54,11 @@ own, recorded as an ADR.
 | `stitchkit/server` | server (Bun) | stable | `createServer`, `implement`, hooks, auth, Socket.IO server, server primitives |
 | `stitchkit/node` | server (Node ≥ 22) | stable | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
 | `stitchkit/tools` | server | stable | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
+| `stitchkit/tools/mcp` | server (Bun or Node) | evolving | the canonical MCP HTTP/stdio server, schemas and typed MCP presenters; only Zod and the MCP server SDK peers |
 | `stitchkit/tools/contract` | browser + server | evolving | the shapes a tool surface speaks — async-operation contract, snapshot and cancel schemas, view-file input/output — without the runtime that serves them |
 | `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` — the CLI transport, light (no MCP SDK / `ai`) |
+| `stitchkit/cli` | server | stable | `createCli` / `createCliInvoker` — runtime and strict NodeNext declarations without MCP SDK / `ai` |
 | `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` | server (Bun or Node) | stable | peer-free managed local-file boundary |
@@ -71,12 +72,12 @@ 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 48 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 49 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 48 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 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/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 |
@@ -89,7 +90,7 @@ own, recorded as an ADR.
 | `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 11 of the 48 minors since 0.56.2, most recently 0.103.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `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/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 |
@@ -3131,6 +3132,13 @@ URLs.
 
 ## `ApiError`
 
+On native Bun, both client paths disable Bun's separate socket idle timer while preserving
+the framework deadline and caller signal. A long declared deadline therefore remains the
+request policy. Explicit or patched fetch implementations, including Next, keep their own
+transport behavior; Node and browsers receive no Bun-specific fetch options. Raw responses
+and contract streams retain their existing header timeout and caller-owned body lifetime.
+See [Bun's idle timeout contract](https://bun.sh/reference/globals/BunFetchRequestInit/timeout).
+
 A non-2xx response is thrown as an `ApiError`:
 
 ```ts
@@ -3145,6 +3153,7 @@ try {
     err.message  // 'Note not found'
     err.details  // structured details, if any
     err.hint     // optional hint
+    err.retryable // optional explicit recommendation, true or false
     err.traceId  // x-request-id — correlate this failure with backend logs
     err.cause    // concrete injected transport failure, when delivery failed
   }
@@ -3158,6 +3167,12 @@ browser code can read it through Stitchkit's default CORS expose list; a custom
 
 The error model is shared with the server — see [Auth & errors](./auth-and-errors.md).
 
+`retryable` preserves an explicit boolean in the server error envelope; an absent declaration
+remains absent. This metadata does not change the HTTP transport retry policy. The existing
+seventh constructor argument remains `ErrorOptions`, including `cause`; the optional
+retryability argument is eighth. Closed error/frame schemas must accept the new optional
+field before their producer declares it.
+
 ## Auth events
 
 The HTTP client emits events your app can react to globally:
@@ -3611,13 +3626,20 @@ get the view's defaults and projected answer, which is what `collectTools` and
 
 ## MCP — `createMcpHandler`
 
+An MCP-only server imports `stitchkit/tools/mcp` and installs
+`stitchkit`, `zod` and `@modelcontextprotocol/server`. The leaf's runtime and strict
+NodeNext declarations require no `ai`. It exports the existing HTTP/stdio server,
+schema policy, catalog and resource helpers; their implementation and security are shared
+with the full `stitchkit/tools` barrel. Use that full barrel when the application also
+needs its AI SDK features.
+
 `createMcpHandler` builds a complete stateless Streamable-HTTP MCP endpoint on
 the official TypeScript SDK v2 server package. It owns server creation,
 protocol-era negotiation and shutdown; application code does not import the SDK
 to mount a normal endpoint.
 
 ```ts
-import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools'
+import { createMcpHandler, createMcpHttpRoute } from 'stitchkit/tools/mcp'
 import { createServer } from 'stitchkit/server'
 
 const mcp = createMcpHandler({
@@ -3751,7 +3773,7 @@ Every advertised tool and every tool result therefore carries the fingerprint of
 the catalog it came from:
 
 ```ts
-import { readMcpCatalogStamp } from 'stitchkit/tools';
+import { readMcpCatalogStamp } from 'stitchkit/tools/mcp';
 
 const listed = await client.listTools();
 let known = readMcpCatalogStamp(listed.tools[0]?._meta); // { digest, tools }
@@ -4256,7 +4278,7 @@ If you already run an `McpServer` from the SDK, `mountMcp` adds contract tools
 to it instead of owning the lifecycle:
 
 ```ts
-import { mountMcp } from 'stitchkit/tools'
+import { mountMcp } from 'stitchkit/tools/mcp'
 
 mountMcp(mcpServer, [usersService], { context: { source: 'mcp' } })
 ```
@@ -4272,7 +4294,7 @@ client (Claude Desktop, Claude Code, Cursor, Codex), on the user's machine, so
 it can reach the local filesystem.
 
 ```ts
-import { bindStdioProcessSignals, createStdioMcpServer } from 'stitchkit/tools'
+import { bindStdioProcessSignals, createStdioMcpServer } from 'stitchkit/tools/mcp'
 
 const stdio = await createStdioMcpServer({
   serverInfo: { name: 'my-app', version: '1.0.0' },
@@ -4427,7 +4449,7 @@ through the contract's typed client:
 ```ts
 import { createHttpClient } from 'stitchkit'
 import { implementRemote } from 'stitchkit/remote'
-import { createStdioMcpServer } from 'stitchkit/tools'
+import { createStdioMcpServer } from 'stitchkit/tools/mcp'
 
 const http = createHttpClient({
   baseUrl: 'https://api.example.com',
@@ -4453,6 +4475,17 @@ no duplicated business logic.
 `transformArgs` hook that rewrites a call's arguments before they are forwarded
 — e.g. to upload a local file referenced in the args and swap in its URL.
 
+The call's signal reaches the existing typed HTTP client's request options, for endpoints
+with or without arguments. An already cancelled call, including cancellation while an async
+argument transform runs, dispatches no request. Bind your process signal to `createCli` or
+`createCliInvoker`; `REQUEST_ABORTED` is a safe nonretryable failure with CLI exit130.
+Cooperative origins observe `ctx.signal` and release resources when their work ends. An
+origin or provider ignoring cancellation may continue after the local wait stops.
+
+An explicit `AppError.retryable` boolean also survives this remote hop. `false` on502 and
+`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.
+
 ## Structured output
 
 When a contract endpoint or runtime tool declares `output`, its MCP tool
@@ -6809,7 +6842,7 @@ description: Compose process-local resources, schedules, readiness, drain and op
 type: architecture
 status: active
 created: 2026-08-23
-updated: 2026-09-30 17:41 +07:00
+updated: 2026-10-04 13:28 +07:00
 ---
 
 # Managed application kernel
@@ -7792,49 +7825,101 @@ deadline holds `stop()` — and so the resource's `force()` — for that one cal
 so give the transport a timeout. Superseding a key that is being sent right now
 does not recall it: the send completes, and only its receipt is not written.
 
-`createDirectoryInbox` is the receiving side for another program on the same
-host: it drops entries — a release transition, say — into a directory, and
-the application takes each one at least once. It is a managed resource of its
-own (`createDirectoryInbox({ id, directory, schema, handle })`, imported from
-`stitchkit/application/directory-inbox` because it touches files; its types
-and schemas are in `stitchkit/application`) and publishes a handle with
-`flush()` and `state()`. The producer writes each entry
-atomically as `<name>.json` — a temporary name, then a rename; names that start
-with a dot are never read. Entries are delivered in name order, and only after
-`activate`: none reaches the application before it is ready. `stopAdmission`
-stops taking new ones, `drain` waits for the one in flight, and `force` aborts
-the `signal` its handler was given.
-
-Taken and done are separate durable records. Before `handle` runs, the entry
-is claimed with a lease (`leaseMs`, default five minutes); after it returns,
-a receipt replaces the claim and only then is the file removed. A process that
-died mid-delivery leaves a claim, and the entry is taken again once the lease
-runs out — at least once, not exactly once, so a handler that sends somewhere
-should carry the entry's `key` as its idempotency key. A process that died
-after the receipt leaves only the file, which the next pass removes without
-delivering it again. A handler that throws is retried after a backoff from one
-second doubling to five minutes; an entry that fails `schema`, is over
-`maxEntryBytes` or was taken `maxAttempts` times (default 20 — the count
-survives restarts, so an entry whose handling kills the process is not taken
-forever) is moved to `rejected/` with its reason and reported to `onRejected`,
-and the entries after it keep flowing. The state lives in
-`<directory>/.inbox-state.json` under `createFileStateStore`'s inter-process
-lock unless a `store` is supplied.
-
-These primitives depend on the structural `StateStore`. On a server,
-`createFileStateStore` supplies the shared Zod-validated JSON adapter with an
-inter-process lock, unique temporary file, fsync and atomic rename. The lock
-is a file with a heartbeat: the holder refreshes its mtime every third of
-`staleLockMs` (default 3 s), a contender waits up to `lockTimeoutMs` (default
-10 s), and the stale bound must sit inside the timeout — otherwise a crashed
-holder blocks every update until the lock ages out, which the constructor
-refuses. A lock whose heartbeat is stale is reclaimed once its recorded pid is
-gone; a live or unverifiable pid (a reused number, another user's process)
-keeps it for ten stale bounds — and never fewer than thirty missed heartbeats,
-so a scheduler stall on a loaded host cannot pull a live lock from under its
-holder — after which the heartbeat wins and the lock is abandoned. Temporary files a crashed writer left beside the state are swept on
-the store's first update. Ledger corruption may be declared reconstructable;
-an outbox must fail closed rather than silently discard pending delivery.
+`createDirectoryInbox` receives entries from another program on the same host,
+or directly from a transport adapter. Import the resource from
+`stitchkit/application/directory-inbox`; its contracts live in
+`stitchkit/application`. Its published handle has `accept({ source, key, entry })`,
+`flush()` and `state()`:
+
+```ts
+const inbox = createDirectoryInbox({
+  id: 'updates',
+  directory: env.INBOX_DIRECTORY,
+  schema: UpdateSchema,
+  handle: ({ identity, entry, signal }) => processUpdate(identity, entry, signal),
+})
+const ingress = defineManagedResource({
+  id: 'ingress',
+  dependsOn: [inbox],
+  start(context) {
+    const intake = context.use(inbox)
+    return { value: (key: string, entry: Update) =>
+      intake.accept({ source: 'client-updates', key, entry }) }
+  },
+})
+```
+
+`accept` is available after the resource starts, including before activation.
+It validates the entry and full producer identity, writes a lossless JSON envelope,
+syncs its file and parent directory, then returns
+`{ status: 'accepted' | 'duplicate', filename }`. Automatic delivery starts at
+`activate`; an explicit `flush()` is available before activation. A producer
+should acknowledge its provider only after acceptance resolves. Failure after
+publication can mean the entry was accepted but its acknowledgement was lost:
+retry the same identity, and `duplicate` keeps the original payload.
+
+The identity is the pair `source` (1–128 characters) and `key` (1–1024 characters).
+A hash of the pair names the file; the full pair is retained inside its envelope
+and checked against existing files and records. Two sources may use the same key.
+The handler's legacy `key` remains the filename; programmatic entries additionally
+carry `identity`. No Telegram numeric update id or MTProto event shape is invented.
+
+The default `maxPendingEntries: 1000` refuses new programmatic entries when the
+pending directory is full, without publishing another file; duplicate acceptance
+still succeeds. `maxEntryBytes` defaults to 1 MiB and counts the complete UTF-8
+envelope. A completed identity is deduplicated while its receipt is retained
+(`retain`, default 1000); a rejected envelope also deduplicates while its file
+remains in `rejected/`. Choose the retention and rejected-file cleanup policy to
+match the provider's replay window. Provider cursors, identity extraction and
+external-effect idempotency remain application responsibilities.
+
+The original file-producer path also remains: atomically publish
+`<name>.json`, using a temporary name followed by a rename. Names starting with
+a dot are ignored; `intake-<64 hex characters>.json` is reserved for programmatic
+envelopes. Entries are delivered in filename order. The reader refuses unsafe
+leaf symlinks, multiple links and files changed during reading.
+`stopAdmission` stops new acceptance and delivery, `drain` waits for accepted
+storage operations and the handler in flight, and `force` aborts its handler
+signal. A handler ignoring that signal may still finish an external effect;
+the inbox leaves its entry unsettled rather than claiming it was cancelled.
+
+Taken and done are separate durable records. Before `handle`, the entry is
+claimed with a unique expiring lease (`leaseMs`, default five minutes). A
+long handler renews that lease; an expired or replaced lease cannot complete,
+reject, retry or remove the successor's file. Success first commits a receipt,
+then removes only that file generation under a new protected transaction.
+A crash after receipt commit is recovered by cleanup without redelivery. A crash
+before receipt commit may redeliver: the guarantee is at least once, so use the
+full producer identity as the external idempotency key.
+
+A throwing handler retries after a backoff from one second to five minutes.
+Schema failures, oversize files and `maxAttempts` exhaustion (default 20) are
+recorded before their files move to `rejected/`, with `onRejected` reporting the
+reason. The state defaults to `<directory>/.inbox-state.json`, or uses the supplied
+`store`. Manual file producers are responsible for atomic publication and capacity.
+
+These primitives share the structural `StateStore`. `update` owns one atomic
+read/modify/write transaction and passes a `StateStoreUpdateContext` as the
+transition's second argument. Its `await context.assertHeld()` checks that the
+transaction is still active and its exclusive generation is still owned. A custom
+store must implement both real serialization/atomic commit and this guard;
+a no-op guard does not satisfy the contract. Ordinary one-argument transition
+callbacks remain valid.
+
+On a server, `createFileStateStore` uses the same process-instance lock as
+`withExclusiveLock`, unique staging files and atomic directory-durable publication.
+`lockTimeoutMs` (default 10 s, zero means one attempt) bounds acquisition only.
+A live or unattributable owner is never replaced by age, including after an event
+loop stall or `SIGSTOP`; only a provably dead local process instance is reclaimed.
+Legacy readable pid/token records without a host are unknown owners and need
+operator recovery after the old writer is verified stopped.
+
+`staleLockMs` and `retryMs` are removed and are refused at runtime. The current
+write removes its own staging file; unknown historical temporary files are
+preserved, without an age sweep. Directory durability requires a filesystem
+supporting directory sync (Linux and macOS); Windows is refused explicitly.
+Ledger corruption may be declared reconstructable; an outbox must fail closed
+rather than discard pending delivery.
 
 ## Recovering change subscriptions
 
@@ -8045,7 +8130,7 @@ description: Native IO для Bun и Node, с явно выбранной durabi
 type: guide
 status: active
 created: 2026-10-01 20:44 +07:00
-updated: 2026-10-03 13:36 +07:00
+updated: 2026-10-04 09:40 +07:00
 participants:
   - role: authored
     harness: Codex
@@ -8059,6 +8144,10 @@ participants:
     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
@@ -8286,10 +8375,35 @@ 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.
 
-Darwin consumers need the published native binaries at the bundled loader's relative native
-directory. A JS-only bundle is not portable evidence. Qualify the packed library outside its
-build tree in Bun and Node, test its declarations, and check that importing an unbundled
-Stitchkit leaf fails there. A separate schema-only entry must not import the native entry.
+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.
+
+```sh
+bun build src/native.ts --target=bun --minify --outdir=dist
+bun build src/native.ts --compile --bytecode --format=esm --outfile=dist/native
+```
+
+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.
+
+If the Darwin backend cannot load, `observeProcessInstance` still returns `unavailable`.
+Its backend `Error` preserves the original `cause`; JSON serialization carries only the stable
+`DARWIN_BACKEND_UNAVAILABLE` code, architecture, safe message and failure stage
+(`architecture`, `resolve`, `load` or `surface`), plus a recognized native error code when present.
+It excludes stack, paths and nested cause. This backend diagnosis does not reclassify kernel
+failures or turn unavailable identity into proof that an owner is dead. If a runtime provides
+no recognized native error code, the stage stays `load`; the loader never infers errno from text.
 
 This delivery removes a runtime kernel installation; it does not remove the build-time
 Stitchkit installation or create an independent lightweight npm package.
@@ -8454,7 +8568,7 @@ description: Executable patterns for moving database, poller, queue and operatio
 type: architecture
 status: active
 created: 2026-08-24
-updated: 2026-08-24
+updated: 2026-10-04 13:28 +07:00
 ---
 
 # Application migration recipes
@@ -8488,6 +8602,131 @@ The application still owns the client, ORM configuration, transactions,
 migrations and reconnect policy. The executable recipe deliberately fails after
 allocation and proves one rollback close.
 
+## Stateful clients, including MTProto
+
+An application-owned client is an ordinary managed resource. Keep SDK creation,
+credentials, authorization and reconnect policy in the application; no Telegram
+client SDK is required by Stitchkit. Create a fresh client inside each `start`,
+publish it after connection/readiness succeeds, and share one memoized destroy
+promise between partial-start cleanup, `close` and `force`:
+
+```ts
+let generation: { destroy(): Promise<void> } | undefined
+
+const client = defineManagedResource({
+  id: 'client',
+  async start({ signal }) {
+    const connection = createClient() // Your SDK and configuration.
+    let destruction: Promise<void> | undefined
+    const destroy = () => destruction ??= Promise.resolve()
+      .then(() => connection.destroy())
+    generation = { destroy }
+    let ready = false
+    let startFailure: unknown
+    let startFailed = false
+    let cleanupFailure: unknown
+    let cleanupFailed = false
+    try {
+      await connection.connect(signal)
+      await connection.assertReady()
+      signal.throwIfAborted()
+      ready = true
+    } catch (error) {
+      startFailure = error
+      startFailed = true
+    } finally {
+      if (!ready) {
+        try { await destroy() }
+        catch (cleanup) {
+          cleanupFailure = cleanup
+          cleanupFailed = true
+        }
+      }
+    }
+    if (startFailed) {
+      if (cleanupFailed) throw new AggregateError([startFailure, cleanupFailure],
+        'Client startup and cleanup failed', { cause: startFailure })
+      throw startFailure
+    }
+    return { value: connection }
+  },
+  close: () => generation?.destroy(),
+  force: () => generation?.destroy(),
+})
+
+const api = defineManagedResource({
+  id: 'api',
+  dependsOn: [client],
+  start(context) {
+    const connection = context.use(client)
+    return { value: async () => {
+      const lease = context.admission.acquire()
+      if (!lease) throw new ApplicationAdmissionError()
+      try { return await connection.invoke() }
+      finally { lease.release() }
+    } }
+  },
+})
+```
+
+`createClient` supplies a client whose `destroy` safely cleans partial connection
+setup; its adapter must honor cancellation or otherwise reconcile late SDK effects.
+The destroy cache belongs to one generation and is reset by the next `start`.
+Successful startup keeps the connection alive. Dependants start after readiness,
+requests acquire admission before invoking the client, and dependent HTTP resources
+close before the client. A subtree restart builds a new client and new dependants.
+
+The packed-consumer fixture
+[`managed-client-composition.mjs`](../../packages/core/scripts/consumer-lane/fixtures/minimal/src/managed-client-composition.mjs)
+proves readiness/admission, partial startup, close order, forced cleanup and restart
+with a fake client on Bun and Node. It does not claim a live provider acceptance test.
+
+## Custom StateStore transaction guards
+
+Transitions now receive `(current, context)`. Keep ordinary callbacks that only use
+`current`; update custom store implementations to pass a real protected context.
+For an in-memory test store, queue transactions and invalidate the context when
+the transaction finishes:
+
+```ts
+function memoryStore<T>(): StateStore<T> {
+  let state: T | null = null
+  let tail: Promise<unknown> = Promise.resolve()
+  return {
+    read: async () => state,
+    update(transition) {
+      const work = tail.then(async () => {
+        let active = true
+        const context: StateStoreUpdateContext = {
+          async assertHeld() {
+            if (!active) throw new Error('Transaction is no longer active')
+          },
+        }
+        try {
+          const next = await transition(state, context)
+          await context.assertHeld()
+          state = next.state
+          return next.result
+        } finally { active = false }
+      })
+      tail = work.catch(() => undefined)
+      return work
+    },
+  }
+}
+```
+
+This recipe is process-local and has no restart durability. A database store must
+guard its real transaction/generation and commit atomically; an escaped or lost
+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
+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).
+
 ## Long-running poller
 
 Return separate readiness and completion promises. Readiness says dependants may
@@ -8727,6 +8966,46 @@ It exists for what the other three surfaces cannot do: a generation kicked off
 with `Bash(run_in_background)` that notifies on exit, a `SKILL.md` that shells
 out in one line, a pipeable terminal command.
 
+## Installation and types
+
+Install `stitchkit` and `zod` for a CLI. The public `stitchkit/cli` runtime and
+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
+definition returned by `defineRuntimeTool` or `createRuntimeToolFactory` can be
+passed directly to both CLI and SDK mounts.
+
+Keep transport-specific `present` on that typed SDK definition, rather than on
+an inline object in `CliConfig.runtimeTools`. CLI never executes those presenters;
+its neutral configuration does not validate SDK presentation. Native CLI command
+presentation remains on `defineCliCommand({ present })` and retains its inferred
+output type.
+
+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 { z } from 'zod'
+
+const input = z.object({ text: z.string() })
+const output = z.object({ size: z.number() })
+const measure = {
+  name: 'measure', description: 'Measure text',
+  identity: { serviceName: 'text', action: 'measure', method: 'POST' },
+  transports: ['CLI'], input, output,
+  handler: ({ input }) => ({ size: input.text.length }),
+} satisfies RuntimeToolExecutionWithOutput<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.
+
 ## Exposure is opt-in
 
 Unlike MCP and agent — where an endpoint with no `expose` is a tool by default —
@@ -8907,6 +9186,16 @@ there stays a positional, and `--` makes a literal `false` one too. The same
 holds for a short alias, a framework flag such as `--json false` and an
 application option.
 
+Every declared non-array option is single-use, including framework and
+application globals. Bare, separate-value, inline, negative and short-alias
+forms of a command option count as the same name: `--active=false --active`,
+`--active false --no-active` and `-f --active` are argument errors even when
+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.
+
 Without presentation configuration, positional arguments fill non-boolean
 fields in declaration order, so `myapp generate "a fox"` is
 `--prompt "a fox"`. A piped value fills the first required unset field:
@@ -9357,6 +9646,88 @@ manifest URL is configuration you wrote, while an asset URL arrives inside a
 document the endpoint served, and a document is exactly what an SSRF boundary
 exists to distrust.
 
+### Publishing a complete version
+
+`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:
+
+```ts
+import { publishCli } from 'stitchkit/cli'
+
+const result = await publishCli({
+  storageRoot: '/srv/myapp/cli',
+  name: 'myapp', version: cliVersion, commit: selectedCliCommit,
+  baseUrl: 'https://downloads.example.com/cli/',
+  targets: [{ platform: 'linux', arch: 'x64' }],
+  signal,
+  admit: ({ phase, identity, signal }) => assertSelectedSource({ phase, identity, signal }),
+  build: ({ target, stamp, signal }) => compileSelectedSource({ target, stamp, signal }),
+})
+// result.outcome: 'published' | 'existing'; result.manifest is ready to serve.
+```
+
+The builder returns `Uint8Array` or `ReadableStream<Uint8Array>` containing the
+executable. Every target receives the same immutable `{ version, commit,
+builtAt }` stamp; carry it inside the binary. The publisher owns staging,
+gzip assets, paths and manifests. Callbacks receive the cancellation signal and
+run under the publication lock. Admission phases are `prepare`, each target's
+`build`, `commit`, and `promote`; validate the selected source through commit
+and promotion. A backend release can explicitly select an unchanged older CLI
+identity. The helper never substitutes a different commit or rebuilds an
+existing version under a new identity.
+
+Assets live at `<version>/<name>-<platform>-<arch>.gz`, with an immutable
+`<version>/manifest.json` and a public `manifest.json`. A verified repeat keeps
+the exact bytes and `builtAt`, requires the same target set and base URL, and
+returns `existing` without invoking the builder. A version committed before a
+failed promotion is recovered and promoted without rebuilding. Conflicting
+same-version commits, downgrades, unsafe components, corrupt manifests and
+assets are refused. Version/name/target components are validated before any
+build; `storageRoot` is absolute and its existing parent must be trusted.
+
+All limits are finite positive safe integers; `limits` overrides these defaults:
+
+| Field | Default | Enforced boundary |
+| --- | --- | --- |
+| `maxTargets` | 16 | Requested and verified target count |
+| `maxManifestBytes` | 256 KiB | Read and written manifest bytes |
+| `maxAssetBytes` | 256 MiB | Builder and decompressed executable bytes |
+| `maxCompressedBytes` | 256 MiB | Archived asset bytes |
+| `maxDirectoryEntries` | 128 | Version layout, root scan and commit space |
+| `maxStoredVersions` | 16 | Verified publisher-owned history |
+| `lockTimeoutMs` | 10,000 | Wait to acquire the lock |
+| `timeoutMs` | 600,000 | Whole publication deadline |
+
+`retention` defaults to 2 and keeps the current and previous published versions.
+It must be at least 2 and less than `maxStoredVersions` (at least 3), leaving a
+recovery slot. Older versions are pruned only after their own identity, exact
+layout, raw size and digest are verified. Runtime folders and foreign semver
+directories remain untouched. A full or unverifiable store refuses further
+publication; repeated completed candidates stay inside the owned history cap.
+Cancelled or failed incomplete staging is removed only while its root and
+directory generations still match. The shared asynchronous gzip decoder also
+bounds updater expansion by the declared raw size and configured byte cap.
+
+The publisher rejects symlink roots/versions/assets, non-regular files and
+multiply linked files, and checks held-lock, root and prior-pointer generations
+before commit and promotion. This is cooperative publication under a trusted
+parent directory. Portable path checks do not provide an atomic comparison with
+a hostile process replacing ancestors between syscalls. Durability uses file
+and directory sync on POSIX; Windows publication is refused. A deadline stops
+callback/stream waits and blocks late promotion; trusted callbacks remain
+responsible for cancelling their own subprocesses and external effects.
+
+A failure after an immutable commit reports that the publication outcome must
+be checked. A failure after public-pointer rename may already have published;
+`AtomicFilePublicationError.published` remains available when the atomic writer
+reports that boundary. Read the durable manifest and retry the admitted same
+identity to recover; an error does not promise rollback. Optional `signing` and
+`trust` reuse the Ed25519 contract below. The generated shell installer checks
+raw digest and size; the updater checks manifest authorship when given a trust
+root.
+
 ### Proving who built it — signing the manifest
 
 The asset digest proves the bytes that arrived are the bytes the manifest named.
@@ -9595,6 +9966,10 @@ const discovered = await mountConnections([
     transport: { url },
     token: () => key,
     transports: ['CLI'],   // the opt-in: this server's tools are commands
+    limits: {
+      discovery: { timeoutMs: 30_000, maxResponseBytes: 4 * 1024 * 1024 },
+      call: { timeoutMs: 120_000 },
+    },
   }),
 ])
 await createCli({ name: 'myapp', version, runtimeTools: discovered, commands: [...] })
@@ -9608,6 +9983,35 @@ One unconvertible schema no longer takes the connection down with it. 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.
 
+MCP connection limits follow the operation phase. `initialize`, the initialized
+notification, `tools/list` and legacy endpoint discovery use `limits.discovery`;
+`tools/call` uses `limits.call`. A mounted call's handshake still uses discovery
+limits. Each logical operation has one deadline, including initial transport
+negotiation and response-body reading. Legacy endpoint readiness has a discovery
+deadline; the lifetime of an established SSE stream does not.
+
+Omitted phase fields inherit the existing connection-level `timeoutMs` and
+`maxResponseBytes`, whose defaults are 30 seconds and 1 MiB. Values must be positive
+safe integers; `timeoutMs` must also fit the runtime timer range. The byte ceiling
+counts raw UTF-8 body bytes, including SSE framing, regardless of `Content-Length`.
+Pending legacy calls also count comments and wrong-id frames. `budget.maxTools`
+and `budget.maxSchemaBytes` remain separate mount limits.
+
+Only the initial `initialize` can negotiate HTTP-to-legacy fallback on 400, 404
+or 405. A failed `tools/call` is not replayed. Caller cancellation preserves its
+original reason for in-process observers.
+
+Expected local failures produce safe tool errors: `CONNECTION_TIMEOUT` (exit 7),
+`CONNECTION_RESPONSE_TOO_LARGE` (exit 1), `UNAUTHORIZED` (exit 2), `FORBIDDEN`
+(exit 3) or `CONNECTION_REQUEST_FAILED` (exit 1). Deadline and response-limit
+failures include fixed `operation`/`phase`, the applicable bound and measured
+`observedReadBytes`. The public `ConnectionTimeoutError` and
+`ConnectionResponseTooLargeError` classes carry the same diagnostics. Raw URL,
+credential, body, identity and stack stay with the original in-process cause in
+`onToolError` / `afterToolCall`; tool errors produce no process console dump.
+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`),
@@ -11725,12 +12129,15 @@ error round-trips without adding correlation data to the response body.
 A `code` is a free string — your app codes (`BOT_NOT_FOUND`, …) are yours and the
 core never models them (ADR 0002). But stitchkit itself emits a set of its own:
 `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `METHOD_NOT_ALLOWED`,
-`CONFLICT`, `RATE_LIMITED`, `VALIDATION_ERROR`, `FILE_INVALID_PATH`,
+`CONFLICT`, `RATE_LIMITED`, `REQUEST_ABORTED`, `REQUEST_TIMEOUT`,
+`VALIDATION_ERROR`, `FILE_INVALID_PATH`,
 `FILE_OUTSIDE_ROOT`, `FILE_NOT_FOUND`, `FILE_NOT_REGULAR`,
 `FILE_INSPECTION_REJECTED`, `FILE_TOO_LARGE`, `FILE_EXISTS`,
 `REALTIME_CONTRACT_VIOLATION`, `APPLICATION_NOT_ACCEPTING`, `NOT_IMPLEMENTED`,
 `WAIT_TIMEOUT`,
 `WAIT_FAILED`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
+`CONNECTION_TIMEOUT`, `CONNECTION_RESPONSE_TOO_LARGE`,
+`CONNECTION_REQUEST_FAILED`, `UPSTREAM_TOOL_ERROR`,
 `OPERATION_NOT_SUCCEEDED`, `STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,
 `STREAM_TERMINAL_MISSING`, `STREAM_LIFETIME_EXCEEDED`,
 `GRAMMY_WEBHOOK_NOT_ACCEPTING`, `SANDBOX_UNAVAILABLE`, `SANDBOX_INSUFFICIENT`,
@@ -14183,7 +14590,8 @@ const report = await runTelegramBroadcast({
   `retry_after` and sends the same recipient again; a server error is retried
   with backoff up to `maxAttempts`, then `failed`. A message Telegram cannot
   parse is not the recipient's fault: the run **halts** with them still pending,
-  so the run after the fix reaches them. So does Telegram being unreachable.
+  so the run after the fix reaches them. An unknown transport outcome becomes
+  `uncertain` immediately and halts the run; resume never sends to that recipient again.
 - **Pacing** is `ratePerSecond`, 25 by default. `dryRun` counts and writes
   nothing. One runner per name: a second concurrent run is refused.
 
@@ -14192,6 +14600,66 @@ application (the application's signal, with admission held by the caller).
 The recipient state contains Telegram ids: keep it in the state directory, out
 of git.
 
+### Injecting another transport's failure policy
+
+`classify(error)` returns the public `TelegramBroadcastFailure` union. It lets
+an application use its own client without adding that SDK to Stitchkit:
+
+```ts
+const report = await runTelegramBroadcast({
+  name: 'announcement',
+  directory: env.STATE_DIRECTORY,
+  recipients: () => audience.activeSubscribers(),
+  send: ({ recipient }) => client.sendMessage(recipient, message),
+  classify(error) {
+    if (isFloodWait(error))
+      return { kind: 'retry-after', retryAfterMs: error.seconds * 1000,
+        reason: 'provider-rate-limit' }
+    if (isRecipientGone(error))
+      return { kind: 'permanent', recipientUnreachable: true,
+        reason: 'recipient-gone' }
+    return { kind: 'ambiguous', reason: 'unknown-provider-outcome' }
+  },
+  maxRetryDelayMs: 60_000,
+  signal: stop.signal,
+})
+```
+
+The four variants are `retry-after` (exact `retryAfterMs`), `transient` (bounded
+backoff), `permanent` (optionally `recipientUnreachable` or `stopBroadcast`), and
+`ambiguous`. Retry variants certify that the failed attempt had no external
+effect. Lack of an HTTP status does not establish that fact: a server may have
+accepted the message before the connection failed. `ambiguous` durably records
+`uncertain`, then halts; resuming the name skips that recipient.
+
+`maxRetryDelayMs` defaults to 60 seconds. A provider wait above it halts with the
+recipient pending; it is never shortened to send early. `maxAttempts` is an
+integer from 1 to 100, `maxRetryDelayMs` is an integer from 0 to 2,147,483,647,
+and pacing/progress intervals must fit native timers. The optional
+`sleep(milliseconds, signal)` receives cancellation; the runner also stops waiting
+when the signal aborts if a custom sleeper ignores it. A send already in flight
+finishes and is recorded before stopping.
+
+Without `classify`, known Bot API 429, unreachable-recipient, malformed-message
+and server-error behavior remains. Unknown/no-status failures now halt as
+uncertain, rather than being automatically retried. Existing custom `send`
+implementations that relied on those retries must supply an explicit classifier
+for proven pre-effect failures. `report.halt` now carries
+`TelegramBroadcastFailure`; inspect `halt.kind` instead of the old send-failure
+`scope`/`retryable` fields.
+
+The runner uses the shared process-instance lock and checks its generation before
+sends and journal writes. The audience and initial journal directory entry are
+synced before sending. Lost ownership cannot write a stale delivered receipt or
+start another send; the persisted intent becomes uncertain on recovery. Old
+pid-only broadcast locks have unknown ownership and require recovery after their
+writers are verified stopped, rather than automatic age-based deletion.
+
+The installed
+[`telegram-broadcast-classifier.mjs`](../../packages/core/scripts/consumer-lane/fixtures/minimal/src/telegram-broadcast-classifier.mjs)
+fixture checks injected rate limits, ambiguity/no resend, wait budgets and abort
+on Bun and Node without a client SDK.
+
 ## Message markup
 
 `stitchkit/telegram/html` is Telegram's HTML parse mode as a tree, with no peer
@@ -14788,6 +15256,123 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.104.0
+
+### CLI runtime-tool construction
+
+**Who must act:** callers writing a schema-dependent handler or MCP/AI `present` directly
+inside an annotated `CliConfig.runtimeTools` or `CliInvokerConfig.runtimeTools` object.
+Native `commands` and values returned by `defineRuntimeTool` / `createRuntimeToolFactory`
+remain valid. Execution, auth, validation and the invocation result envelope keep their behavior.
+
+Construct a CLI-only managed definition with the neutral schema-aware type before registration:
+
+```ts
+import type { CliInvokerConfig, RuntimeToolExecutionWithOutput } from 'stitchkit/cli'
+import { z } from 'zod'
+
+const input = z.object({ text: z.string() })
+const output = z.object({ size: z.number() })
+// Before: handler receives the heterogeneous registry context.
+const config: CliInvokerConfig = {
+  name: 'app',
+  runtimeTools: [{
+    name: 'measure', description: 'Measure text',
+    identity: { serviceName: 'text', action: 'measure', method: 'POST' },
+    transports: ['CLI'], input, output,
+    handler: ({ input }) => ({ size: String(input.text).length }),
+  }],
+}
+// After: handler input and output derive from the construction schemas.
+const measure = {
+  name: 'measure', description: 'Measure text',
+  identity: { serviceName: 'text', action: 'measure', method: 'POST' },
+  transports: ['CLI'], input, output,
+  handler: ({ input }) => ({ size: input.text.length }),
+} satisfies RuntimeToolExecutionWithOutput<typeof input, typeof output>
+const nextConfig: CliInvokerConfig = { name: 'app', runtimeTools: [measure] }
+```
+
+For a shared MCP/AI tool, construct the definition with `defineRuntimeTool` from
+`stitchkit/tools`, including its typed SDK `present` callbacks, then pass the returned value
+to `runtimeTools`. Install the corresponding SDK peers for that integration. A CLI-only
+consumer needs `stitchkit`, `zod` and its ordinary Node type tooling.
+
+`RuntimeToolExecution` names the heterogeneous registration contract. Call a registered
+operation through `createCli` or `createCliInvoker`; its erased handler input is `never`
+because the managed runner owns schema validation before execution. For a managed void
+definition, use `RuntimeToolDefinitionWithoutOutput<typeof input>`.
+
+### MCP construction, state stores and delivery
+
+**Who must act:** schema-dependent runtime tool literals written directly inside MCP mount
+configuration, MCP presenters returning malformed content or metadata, custom `StateStore`
+implementations, file-store consumers using retired lock
+options, broadcast consumers reading `halt` or retrying unknown send outcomes, and consumers
+that validate HTTP error envelopes with a closed schema. Applications collecting raw tool
+causes from `console.error` must configure an internal tool hook sink.
+
+MCP-only code can import the existing server factories from `stitchkit/tools/mcp` and
+construct its schema-aware tool before heterogeneous registration:
+
+```ts
+import { buildMcpServer, type RuntimeMcpToolDefinitionWithOutput } from 'stitchkit/tools/mcp'
+import { z } from 'zod'
+const input = z.object({ value: z.number() })
+const output = z.object({ doubled: z.number() })
+// Before: runtimeTools: [{ input, output, handler, present }]
+const double = {
+  name: 'double', description: 'Double a number',
+  identity: { serviceName: 'numbers', action: 'double', method: 'POST' },
+  input, output,
+  handler: ({ input }) => ({ doubled: input.value * 2 }),
+  present: { mcp: ({ doubled }) => ({ content: [{ type: 'text', text: String(doubled) }] }) },
+} satisfies RuntimeMcpToolDefinitionWithOutput<typeof input, typeof output>
+const server = buildMcpServer({ serverInfo: { name: 'numbers', version: '1' }, services: [], runtimeTools: [double] })
+```
+
+Full MCP/AI integrations keep `defineRuntimeTool` from `stitchkit/tools`; those typed values
+remain accepted by the MCP leaf and CLI. The leaf requires the MCP SDK and Zod, with no AI peer.
+
+`RuntimeMcpPresentation` preserves the official SDK's required `content` and typed `_meta`
+fields. A presenter returning `{}` must return `{ content: [] }`; text blocks require string
+text, and metadata must be an object. `structuredContent` and `isError` remain framework-owned.
+This restores SDK checks that an indexed mapped type previously erased.
+
+Unexpected tool causes remain in `hooks.onToolError` and the `error` field of
+`hooks.afterToolCall`. Protocol stderr carries safe errors. MCP resolver failures use those
+same observers without executing the handler or its lifecycle again. HTTP's default
+unexpected-error logging retains its behavior.
+
+A custom state adapter's `update` must invoke `transition(current, context)` while it still
+owns the serialized transaction. `context.assertHeld()` checks the actual transaction or lock
+generation and refuses after completion, rollback or ownership loss. A no-op guard cannot
+satisfy this contract. Existing transition callbacks may keep one parameter. For the owning
+file adapter, replace `{ staleLockMs, retryMs, lockTimeoutMs }` with `{ lockTimeoutMs }`:
+the remaining budget controls acquisition waiting, never expiry of a live transaction.
+Unknown legacy PID locks and historical temporary files are preserved; recover them only
+after independently proving their owner is gone.
+
+Broadcast consumers change `report.halt.reason` checks to the closed `halt.kind` union:
+`retry-after`, `transient`, `permanent` or `ambiguous`. A custom MTProto adapter can classify
+an acknowledged flood refusal as `{ kind: 'retry-after', retryAfterMs: wait }`; the exact
+provider wait is respected. A wait over `maxRetryDelayMs` halts with the recipient pending.
+Unknown write outcome becomes `uncertain`; restarting the same broadcast does not send it
+again. A retry classification must certify that the attempt did not apply the external effect.
+
+HTTP errors gain optional boolean `error.retryable`; framed contract streams use the same
+field. Update closed consumer schemas before producers declaring it. `false` on 502 and
+`true` on 409 remain explicit recommendations through the remote tool path. An absent field
+retains prior status-derived defaults; the field does not change the HTTP client's retry policy.
+The existing seventh `ApiError` constructor argument remains `ErrorOptions`; retryability is
+the new eighth argument.
+
+Caller cancellation now reaches `implementRemote`'s existing HTTP call. Applications bind
+signals to `createCli` / `createCliInvoker` and cooperative handlers observe `ctx.signal`.
+`REQUEST_ABORTED` is nonretryable and exits 130. A disconnected caller does not prove that
+an origin ignoring cancellation or an external provider stopped; keep resource leases until
+that work actually completes.
+
 ## Released migration: 0.103.0
 
 ### Diagnostic journal startup preserves torn evidence and inspects archives
@@ -19025,7 +19610,7 @@ from the root `stitchkit`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `AppError` | class | the framework error — `code` / `status` / `details` / `hint` |
-| `ErrorEnvelope` | _type_ | the JSON shape of an error response |
+| `ErrorEnvelope` | _type_ | the JSON shape of an error response, preserving optional declared boolean `error.retryable` without changing HTTP retry policy |
 | `notFound` | function | throw `404 NOT_FOUND` — [guide](../guide/auth-and-errors.md#throwing-errors) |
 | `badRequest` | function | throw `400 BAD_REQUEST` |
 | `unauthorized` | function | throw `401 UNAUTHORIZED` |
@@ -19188,6 +19773,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `respondJson` | function | a raw route's JSON response (`204` for null/undefined) |
 | `errorResponse` | function | any thrown value → the framework error envelope + `x-request-id` |
 | `normalizeError` | function | any thrown value → an `AppError` (`ZodError` → `VALIDATION_ERROR` 400 with structured `details.issues`, else generic 500) — the framework's canonical classification, for a bespoke `onError` |
+| `NormalizeErrorOptions` | _type_ | `logUnexpected` defaults to logging the raw server-side cause; tool adapters disable process dumps while their existing observers retain that cause |
 | `errorCode` | function | the stable error code for a thrown value (side-effect-free — for log attribution) |
 | `formatZodError` | function | a `ZodError` → a readable, field-summarised string |
 | `zodIssues` | function | a `ZodError` → structured `{ path, code, message }[]` — the machine-readable sibling of `formatZodError` |
@@ -19404,7 +19990,9 @@ 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_ | managed resource delivering each `<name>.json` entry another program drops into a directory to the application at least once, after readiness; separate durable taken/done records, leases, bounded retry |
+| `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 |
+| `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`) |
 | `ApplicationHandle.restart` | method | replace one resource and everything that depends on it, leaving the rest of the graph running and the process epoch unchanged |
 | `ApplicationRestartInputSchema` / `ApplicationRestartInput` | schema / _type_ | the resource to replace, by id, and optionally `gracePeriodMs` / `forceTimeoutMs` for this restart — the application's own shutdown budget otherwise |
@@ -20589,6 +21177,7 @@ Advanced building blocks — the shared machinery the mounts are built on.
 | `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 |
 | `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
 | `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments |
 | `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 |
@@ -20598,6 +21187,22 @@ Advanced building blocks — the shared machinery the mounts are built on.
 
 ---
 
+## `stitchkit/tools/mcp`
+
+A server-only leaf over the same MCP owner as `stitchkit/tools`. Its runtime and strict
+NodeNext declarations require Zod and `@modelcontextprotocol/server`, with no AI SDK peer.
+HTTP/stdio factories, mounts, schema policy, catalog and resource helpers keep their canonical
+behavior and names. See [MCP guide](../guide/mcp-and-agents.md#mcp--createmcphandler).
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `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 |
+| `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`
 
 Server-only subexport that consumes external MCP servers and OpenAPI specifications
@@ -20609,6 +21214,9 @@ and approval path.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `defineMcpClientConnection` | function | declare one external MCP server connection over Streamable HTTP with an optional SSE fallback |
+| `ConnectionOperationLimits` / `McpConnectionLimits` | _type_ | positive finite deadline/raw byte ceilings with independent discovery/call overrides; omitted fields inherit the shared bounds |
+| `ConnectionPhase` / `ConnectionOperation` / `ConnectionFailureContext` | _type_ | closed operation/phase vocabulary and measured read context for existing typed connection errors |
+| `ConnectionTimeoutError` / `ConnectionResponseTooLargeError` | class | bounded operation refusal, with phase, operation and finite observed bytes; safe tool projection retains the raw cause locally |
 | `defineOpenApiConnection` | function | declare one OpenAPI document (object, JSON text or JSON URL) as a tool surface |
 | `mountConnections` | function | discover every connection and return readonly `RuntimeToolDefinition`s for `mountAgent` |
 | `ConnectionAuthorizationRequiredError` | class | typed reauthorization signal raised on `401` with credentials resolved again on the next call |
@@ -20748,8 +21356,9 @@ injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 | `classifyTelegramSendFailure` | function | name a refused Bot API send and separate "retry this send" from "stop addressing this recipient" |
 | `TelegramSendFailure` | _type_ | reason, `status`, Telegram-stated `retryAfterSeconds`, `retryable`, `recipientUnreachable` and which evidence produced the answer |
 | `TelegramSendFailureReason` / `TELEGRAM_SEND_FAILURE_REASONS` | _type_ / constant | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `rate-limited` / `message-invalid` / `server-error` / `unknown`, and the same as a list; a `Record<TelegramSendFailureReason, …>` over them fails to compile when a reason is added |
-| `runTelegramBroadcast` | function | a resumable broadcast by `name` under a state `directory`: audience written once, an append-only journal, pacing at `ratePerSecond` (25), 429 waits `retry_after`, unreachable recipients never addressed again, a `message-invalid` or unreachable Telegram halts without charging the recipient, a send in flight at a crash is `uncertain` and not repeated, `dryRun`, one runner per name |
+| `runTelegramBroadcast` | function | a resumable broadcast by `name` under a state `directory`: audience and journal durably recorded, pacing at `ratePerSecond` (25), exact retry delays within the finite declared budget, injected classifier, uncertain send outcomes never replayed, `dryRun`, one fenced runner per name |
 | `TelegramBroadcastConfig` / `TelegramBroadcastSend` / `TelegramBroadcastReport` / `TelegramBroadcastRunOutcome` / `TelegramBroadcastOutcome` / `TelegramBroadcastRecipient` | _type_ | `name`, `directory`, `recipients()`, `send({ recipient, attempt })`, `maxAttempts`, `signal`, `onProgress`; counts `delivered` / `unreachable` / `failed` / `uncertain` / `pending` and `finished` / `stopped` / `halted` / `dry-run` |
+| `TelegramBroadcastFailureSchema` / `TelegramBroadcastFailure` | schema / _type_ | injected `classify` answers retry-after/transient/permanent/ambiguous; exact provider delay is bounded by `maxRetryDelayMs` without shortening, unknown outcome remains uncertain and is never replayed |
 | `telegramBroadcastSender` / `TelegramBroadcastSenderConfig` / `TelegramBroadcastMessage` | function / _type_ | the standard `send`: `sendMessage` with a text or `copyMessage` of a prepared message, through the Bot API |
 | `createTelegramOperatorChannel` | function | the operator chat, apart from the journal: `post(text, topic?)` returns at once and never throws; paced sends into forum topics, 429 honoured, oldest dropped on overflow, `drain(signal)` and `close()` for the way down |
 | `TelegramOperatorChannelConfig` / `TelegramOperatorChannel` / `TelegramOperatorMessage` / `TelegramOperatorDrop` / `TelegramChatId` | _type_ | `chatId`, `topics`, `send`, `maxQueued`, `minIntervalMs`, `maxAttempts`, `onDropped`, `sensitivePatterns` and `sensitiveValues` (a bot token is always masked), `dedupe`; a drop is `overflow` / `refused` / `attempts` / `closed` / `repeated` / `over-budget` with its classification |
@@ -21092,6 +21701,7 @@ 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 |
@@ -21123,6 +21733,9 @@ 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` |
+| `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 |
 | `CliCommandDefinitionWithOutput` | _type_ | native command with validated declared output and typed optional `present` / successful `exitCode` callbacks |