@kodax-ai/kodax 0.7.73 → 0.7.75

package/docs/SDK_EMBEDDER_GUIDE.md

@@ -22,15 +22,19 @@ are NOT obvious from inspecting the type definitions alone:
 12. [Provider credential verification — `verifyProviderCredential`](#12-provider-credential-verification--verifyprovidercredential-feature_216-v0745)
 13. [Inject your product's manual — `selfManual`](#13-inject-your-products-manual--selfmanual-feature_221-v0747)
 14. [Media input artifacts — `@kodax-ai/kodax/media`](#14-media-input-artifacts--kodax-aikodaxmedia-feature_239-v0756)
-15. [Space v0.7.57 follow-up ledger](#15-space-v0757-follow-up-ledger)
-16. [SDK agent-profile surface — `KodaXAgentProfile`](#16-sdk-agent-profile-surface--kodaxagentprofile-feature_247-v0758)
-17. [Runtime SDK, Worker isolation, and local daemon](#17-runtime-sdk-worker-isolation-and-local-daemon-feature_253-feature_257)
-18. [External-agent executor plane](#18-external-agent-executor-plane-feature_258-v0767)
-19. [Session surface filtering and cursor pagination](#19-session-surface-filtering-and-cursor-pagination-feature_261-v0767)
-20. [Cost-disciplined workflow routing and telemetry](#20-cost-disciplined-workflow-routing-and-telemetry-feature_259-v0767)
-21. [Experimental governed memory — `/experimental-memory`](#21-experimental-governed-memory--experimental-memory-feature_260-v0768)
-22. [Bidirectional A2A 1.0 — `/a2a`](#22-bidirectional-a2a-10--a2a-feature_267-v0769)
-23. [Shared Coder daemon for Space and IDE hosts](#23-shared-coder-daemon-for-space-and-ide-hosts-feature_269-v0769)
+15. [Space v0.7.57 follow-up ledger](#15-space-v0757-follow-up-ledger)
+16. [SDK agent-profile surface — `KodaXAgentProfile`](#16-sdk-agent-profile-surface--kodaxagentprofile-feature_247-v0758)
+17. [Runtime SDK, Worker isolation, and local daemon](#17-runtime-sdk-worker-isolation-and-local-daemon-feature_253-feature_257)
+18. [External-agent executor plane](#18-external-agent-executor-plane-feature_258-v0767)
+19. [Session surface filtering and cursor pagination](#19-session-surface-filtering-and-cursor-pagination-feature_261-v0767)
+20. [Cost-disciplined workflow routing and telemetry](#20-cost-disciplined-workflow-routing-and-telemetry-feature_259-v0767)
+21. [Experimental governed memory — `/experimental-memory`](#21-experimental-governed-memory--experimental-memory-feature_260-v0768)
+22. [Bidirectional A2A 1.0 — `/a2a`](#22-bidirectional-a2a-10--a2a-feature_267-v0769)
+23. [Shared Coder daemon for Space and IDE hosts](#23-shared-coder-daemon-for-space-and-ide-hosts-feature_269-v0769)
+24. [Runtime-owned Auto Mode and plan-approval bridges](#24-runtime-owned-auto-mode-and-plan-approval-bridges-v0772v0773)
+25. [Always-on context compaction and bounded transcript recovery](#25-always-on-context-compaction-and-bounded-transcript-recovery-v0774)
+26. [Agent mailbox control versus SDK event telemetry](#26-agent-mailbox-control-versus-sdk-event-telemetry-v0774)
+27. [Windows GUI background subprocess visibility](#27-windows-gui-background-subprocess-visibility-v0775)
 
 §1–§3 (and the Phase-7/8 MCP-popout surface in §1) land in v0.7.42
 under FEATURE_186 (see [ADR-032](ADR.md#adr-032-sdk-embedder-surface-closure-feature_186-v0742)).
@@ -697,19 +701,19 @@ await runKodaX(
 // ✓ ~/.kodax/sessions/s_my_chat.jsonl now exists after the run.
 
 // Same `storage` instance reads back through SessionManager:
-const recent = await listSessions({
-  scope: 'user',
-  surface: 'acp',
-  limit: 50,
-});
-const nextPage = recent.at(-1)?.cursor
-  ? await listSessions({
-      scope: 'user',
-      surface: 'acp',
-      limit: 50,
-      cursor: recent.at(-1)?.cursor,
-    })
-  : [];
+const recent = await listSessions({
+  scope: 'user',
+  surface: 'acp',
+  limit: 50,
+});
+const nextPage = recent.at(-1)?.cursor
+  ? await listSessions({
+      scope: 'user',
+      surface: 'acp',
+      limit: 50,
+      cursor: recent.at(-1)?.cursor,
+    })
+  : [];
 const replay = await loadSession('s_my_chat');
 const scrollback = await loadFullTranscript('s_my_chat');
 const compacted = await compactSession('s_my_chat', { dryRun: true });
@@ -720,10 +724,25 @@ await appendClientNotice('s_my_chat', {
 });
 ```
 
+### Auto-resume selection in v0.7.74
+
+With `session.autoResume: true` (or `resume: true`) and no explicit ID, KodaX
+calls `storage.list(context.gitRoot, { limit: 1000 })` and chooses the first
+newest-first summary whose `msgCount > 0`. This prevents newer zero-message
+ACP/bootstrap placeholders from shadowing a real conversation. An explicit
+`session.id` always wins. Custom `KodaXSessionStorage` implementations should
+therefore honor the optional `limit` argument and return `msgCount` accurately;
+they may return fewer than 1000 records.
+
+The standalone interactive CLI additionally restores the persisted
+workspace/runtime identity before the next turn. SDK embedders still own
+`context.gitRoot`, `context.executionCwd`, and storage construction; do not rely
+on process cwd as a substitute for host-owned runtime context.
+
 ### What `createSessionManager()` returns (v0.7.43+)
 
 ```ts
-interface SessionManager {
+interface SessionManager {
   // Read side (FEATURE_173 v0.7.42)
   listSessions(...): Promise<SessionSummary[]>;
   loadSession(id): Promise<...>;
@@ -738,13 +757,13 @@ interface SessionManager {
   watchSessions(cb): () => void;
   // Write side (v0.7.43 follow-up)
   storage: FileSessionStorage;     // ← NEW — pass into runKodaX
-}
-```
-
-`surface` is an exact filter applied before `limit`. Each returned summary may
-include an opaque `cursor`; pass the last summary's cursor back unchanged to
-continue the stable newest-first listing. Callers must not parse or construct
-cursors themselves.
+}
+```
+
+`surface` is an exact filter applied before `limit`. Each returned summary may
+include an opaque `cursor`; pass the last summary's cursor back unchanged to
+continue the stable newest-first listing. Callers must not parse or construct
+cursors themselves.
 
 ### Active context vs full transcript vs UI replay
 
@@ -967,7 +986,7 @@ running your project's test suite against `main` — you can `npm link`
 the in-tree KodaX checkout instead of waiting for a published version.
 
 As of v0.7.43 the root `package.json` is in **already-published shape**:
-`"name": "@kodax-ai/kodax"` is baked in along with all 10 SDK subpath
+`"name": "@kodax-ai/kodax"` is baked in along with all 10 SDK subpath
 exports. `npm link` "just works" — no need to run `scripts/release.mjs`
 first.
 
@@ -1296,7 +1315,7 @@ import {
 ```ts
 interface KodaXModelCapabilities {
   provider: string;                 // 'anthropic' | 'kimi' | 'ark-coding' | <custom-name>
-  model: string;                    // model id (e.g. 'claude-sonnet-4-6', 'kimi-k2.7-code')
+  model: string;                    // model id (e.g. 'claude-sonnet-4-6', 'kimi-k2.7-code')
   displayName: string;              // human label — falls back to model id
   supportsThinking: boolean;        // native reasoning is available?
   reasoningCapability: 'native-budget' | 'native-effort' | 'native-toggle' | 'prompt-only' | 'none' | 'unknown'; // legacy mechanism label
@@ -1328,8 +1347,8 @@ for (const caps of listAllModelCapabilities()) {
 ```ts
 import { resolveModelCapabilities } from '@kodax-ai/kodax/llm';
 
-const caps = resolveModelCapabilities('kimi', 'kimi-k2.7-code');
-// => { contextWindow: 262_144, supportsThinking: true, reasoningProfile: { defaultEffort: 'high', ... }, ... }
+const caps = resolveModelCapabilities('kimi', 'kimi-k2.7-code');
+// => { contextWindow: 262_144, supportsThinking: true, reasoningProfile: { defaultEffort: 'high', ... }, ... }
 ```
 
 For picker/status UIs, use `reasoningProfile.supportedEfforts` and
@@ -1466,11 +1485,11 @@ and loaded into the in-memory `KODAX_PROVIDER_SNAPSHOTS` export. When upstream
 providers publish a new model or change a context-window cap, the JSON file is
 the patch site — the new value flows to runtime (via `buildProviderConfig`) AND
 to SDK consumers (via the getters) in a single edit. The current snapshot is
-dated 2026-07-16 and includes the GPT-5.4, Kimi K2.7 Code / HighSpeed, GLM-5.2, MiniMax
+dated 2026-07-16 and includes the GPT-5.4, Kimi K2.7 Code / HighSpeed, GLM-5.2, MiniMax
 M3/M2.7, DeepSeek V4, and Doubao Seed 2.0 route refreshes where supported. The
 test suite at
 [`packages/llm/src/providers/model-capabilities.test.ts`](../packages/llm/src/providers/model-capabilities.test.ts)
-locks in specific values (e.g. the public Kimi lineup at 262,144 tokens, deepseek-v4-pro at 1M)
+locks in specific values (e.g. the public Kimi lineup at 262,144 tokens, deepseek-v4-pro at 1M)
 so accidental drift is caught at PR time.
 
 The probe scripts that surveyed upstream APIs live at
@@ -1905,12 +1924,12 @@ Each provider has one `verifyStrategy` value baked into `provider-capabilities.j
 
 | Strategy | What runs | Cost | Used by built-ins |
 |---|---|---|---|
-| `count-tokens` | `client.messages.countTokens({ messages: [{role:'user',content:'hi'}] })` | 0 token | `anthropic`, `kimi-code`, `qwen-token-plan`, `zhipu-coding`, `zai-coding`, `minimax-coding`, `ark-coding` |
+| `count-tokens` | `client.messages.countTokens({ messages: [{role:'user',content:'hi'}] })` | 0 token | `anthropic`, `kimi-code`, `qwen-token-plan`, `zhipu-coding`, `zai-coding`, `minimax-coding`, `ark-coding` |
 | `models-list` | `client.models.list()` | 0 token | `openai`, `deepseek`, `kimi`, `qwen` |
 | `minimal-message` | `chat.completions.create({max_tokens:1, content:'hi'})` (or Anthropic equivalent) | ~6–7 token | `zhipu`, `mimo`, `mimo-coding` |
 | `unsupported` | nothing — short-circuits | — | `gemini-cli`, `codex-cli` (cli-bridge: credentials live in CLI binary) |
 
-`models-list` is NOT used as a universal default because (a) some providers' `/v1/models` is publicly accessible (so a bad key returns 200 — false positive), and (b) some compat layers don't implement it (404) or 401 even for valid keys (false negative). The 2026-05-28 provider probe matrix captured the original per-provider evidence (12 providers at the time; 15 built-in aliases as of 2026-06-28). The current capability catalog has 16 aliases, including `qwen-token-plan` with `count-tokens`; opencode's `setup-recording-env.ts` makes the same per-provider decision across its 20+ providers.
+`models-list` is NOT used as a universal default because (a) some providers' `/v1/models` is publicly accessible (so a bad key returns 200 — false positive), and (b) some compat layers don't implement it (404) or 401 even for valid keys (false negative). The 2026-05-28 provider probe matrix captured the original per-provider evidence (12 providers at the time; 15 built-in aliases as of 2026-06-28). The current capability catalog has 16 aliases, including `qwen-token-plan` with `count-tokens`; opencode's `setup-recording-env.ts` makes the same per-provider decision across its 20+ providers.
 
 ### Custom providers
 
@@ -1954,7 +1973,7 @@ Cli-bridge providers (`gemini-cli`, `codex-cli`) return their CLI binary's known
 
 ### Reference
 
-- Source: `packages/llm/src/providers/verify-credential.ts` (orchestrator + classifier) + `verify-credential.test.ts` (27 unit tests) + `verify-credential-integration.test.ts` (12 gated real-key/fake-key tests, enabled by `KODAX_INTEGRATION_TEST=1`).
+- Source: `packages/llm/src/providers/verify-credential.ts` (orchestrator + classifier) + `verify-credential.test.ts` (27 unit tests) + `verify-credential-integration.test.ts` (12 gated real-key/fake-key tests, enabled by `KODAX_INTEGRATION_TEST=1`).
 - Data: `packages/llm/src/providers/provider-capabilities.json` `verifyStrategy` field per provider.
 - Design notes + probe matrix: [docs/features/v0.7.45.md FEATURE_216](features/v0.7.45.md#feature_216-provider-credential-verification-api).
 
@@ -2003,14 +2022,14 @@ By default your `topics` **extend** the KodaX base manual. v0.7.58 adds
 
 `KODAX_UNDERLYING_CAPABILITY_TOPICS` (exported) is the recommended mechanism-topic
 subset a product built on KodaX should keep even in a full replace — so your users
-still get correct answers about the underlying engine (providers / config /
-permissions / tools / skills / extensions / mcp / repo-intelligence / sessions /
-sdk / custom-providers) without the KodaX brand:
-
-The default full manual also includes the `memory` topic. It is intentionally
-not part of `KODAX_UNDERLYING_CAPABILITY_TOPICS` because `/experimental-memory`
-is opt-in; hosts that expose it should add `memory` explicitly or provide a
-product-specific override.
+still get correct answers about the underlying engine (providers / config /
+permissions / tools / skills / extensions / mcp / repo-intelligence / sessions /
+sdk / custom-providers) without the KodaX brand:
+
+The default full manual also includes the `memory` topic. It is intentionally
+not part of `KODAX_UNDERLYING_CAPABILITY_TOPICS` because `/experimental-memory`
+is opt-in; hosts that expose it should add `memory` explicitly or provide a
+product-specific override.
 
 ```ts
 import {
@@ -2169,30 +2188,32 @@ For streaming follow-ups, use `enqueueWithArtifacts()` instead of the raw
 message queue:
 
 ```ts
-enqueueWithArtifacts({
-  provider: selectedProvider,
-  model: selectedModel,
-  sessionId: activeSessionId,
-  content: followupText,
-  inputArtifacts: [artifact],
-});
-```
-
-The helper validates first and then stores `inputArtifacts` on the queued prompt.
-Queued image follow-ups are rebuilt as multimodal content blocks on the next
-runner turn. Unsupported file/video attachments are rejected before enqueueing.
-Pass `sessionId` whenever the host can run more than one session concurrently;
-it targets that Actor session's root queue without exposing Actor paths. For
-backward compatibility, omitting both `sessionId` and `agentId` still binds to
-the sole active Actor root, or uses the legacy unscoped SA queue when no Actor
-run is active. If multiple Actor roots are active, the helper rejects the
-ambiguous call instead of risking cross-session delivery. Low-level child-Actor
-producers may continue to pass an explicit `agentId`.
-
-`enqueueWithArtifacts()` is an in-process queue helper for direct/inline runs.
-Runtime Worker and daemon clients must use `runtime.runs.submitInput(...)` (with
-the same `sessionId`, `afterRunId`, and `delivery:'after_turn'`) because a
-process-local MessageQueue cannot cross those transport boundaries.
+enqueueWithArtifacts({
+  provider: selectedProvider,
+  model: selectedModel,
+  sessionId: activeSessionId,
+  content: followupText,
+  inputArtifacts: [artifact],
+});
+```
+
+The helper validates first and then stores `inputArtifacts` on the queued prompt.
+Queued image follow-ups are rebuilt as multimodal content blocks on the next
+runner turn. Unsupported file/video attachments are rejected before enqueueing.
+Pass `sessionId` whenever the host can run more than one session concurrently;
+it targets that Actor session's root queue without exposing Actor paths. For
+backward compatibility, omitting both `sessionId` and `agentId` still binds to
+the sole active Actor root, or uses the legacy unscoped SA queue when no Actor
+run is active. If multiple Actor roots are active, the helper rejects the
+ambiguous call instead of risking cross-session delivery. Low-level child-Actor
+producers may continue to pass an explicit `agentId`.
+
+`enqueueWithArtifacts()` is an in-process queue helper for direct/inline runs.
+Runtime Worker and daemon clients must use `runtime.runs.submitInput(...)` (with
+the same `sessionId` and `afterRunId`) because a process-local MessageQueue
+cannot cross those transport boundaries. Use `delivery:'after_turn'` to create
+a continuation Run after the current Run ends, or `delivery:'interrupt'` to
+inject into the current active Actor Run at its next safe Runner boundary.
 
 ### Boundaries
 
@@ -2361,14 +2382,14 @@ The important creation options are:
 | `worker.resourceLimits` | unset | Optional V8 heap/stack limits; requires `isolation: 'worker'`. |
 | `worker.shutdownTimeoutMs` | `2000` | Grace before the parent terminates the Runtime Worker. |
 | `requirements.hardDispose` | `false` | Rejects inline and daemon forms; prevents an accidental weaker ownership form. |
-| `homeDir` | unset | When omitted, use the exact resolved `KODAX_HOME`. When set, this is the base directory that owns `.kodax`, with the same meaning as CLI `daemon --home`; daemon state/config live under `<homeDir>/.kodax`. |
+| `homeDir` | unset | When omitted, use the exact resolved `KODAX_HOME`. When set, this is the base directory that owns `.kodax`, with the same meaning as CLI `daemon --home`; daemon state/config live under `<homeDir>/.kodax`. |
 | `profile` | `'default'` | Daemon uniqueness and runtime configuration namespace. |
 | `sessionsDir` | `<homeDir>/.kodax/sessions` | Explicit session storage override. |
 | `daemonStartupTimeoutMs` | `60000` | Total cold-start/concurrent-owner wait budget. |
-| `daemonConnectTimeoutMs` | `2000` | Per-socket connection timeout. |
-| `autoStartDaemon` | conditional | For `createKodaXRuntime({mode:'daemon'})`, true only when no explicit endpoint/transport is supplied. |
-| `externalAgents` | unset | Host-installed executor factories, dispatch policy, optional credential/artifact policies, and default dispatch context. Inline owner only; see §18. |
-| `requirements.externalAgents` | `false` | Reject a Runtime/daemon connection that does not advertise an installed external-agent plane. |
+| `daemonConnectTimeoutMs` | `2000` | Per-socket connection timeout. |
+| `autoStartDaemon` | conditional | For `createKodaXRuntime({mode:'daemon'})`, true only when no explicit endpoint/transport is supplied. |
+| `externalAgents` | unset | Host-installed executor factories, dispatch policy, optional credential/artifact policies, and default dispatch context. Inline owner only; see §18. |
+| `requirements.externalAgents` | `false` | Reject a Runtime/daemon connection that does not advertise an installed external-agent plane. |
 
 KodaX rejects contradictory options. Worker settings without Worker isolation,
 `requirements.hardDispose` on inline/daemon forms, and any explicit isolation
@@ -2442,20 +2463,20 @@ no explicit `daemonEndpoint` or `daemonTransport` is supplied it starts or reuse
 the local profile daemon. `connectKodaXRuntime()` is attach-only unless
 `autoStart: true` is passed.
 
-SDK auto-start allows `daemonStartupTimeoutMs` (default 60 seconds) and
-`daemonConnectTimeoutMs`. The longer startup budget covers cold machines and
-concurrent test/desktop startup without weakening PID, endpoint, token, or
-runtime-identity validation.
-
-`homeDir` and `KODAX_HOME` deliberately name different levels. Runtime SDK and
-CLI daemon `--home` accept the **base directory that contains `.kodax`**;
-lower-level `KODAX_HOME` points at the **data directory itself** and need not be
-named `.kodax`. To share the default CLI daemon, omit `homeDir`; this honors the
-exact resolved `KODAX_HOME`. Passing `os.homedir()` explicitly instead selects
-`<os.homedir()>/.kodax`, regardless of an ambient custom `KODAX_HOME`. For an
-isolated embedder namespace, pass a private base directory and expect data at
-`<homeDir>/.kodax`. Passing `~/.kodax` as `homeDir` would instead select
-`~/.kodax/.kodax` and a different daemon namespace.
+SDK auto-start allows `daemonStartupTimeoutMs` (default 60 seconds) and
+`daemonConnectTimeoutMs`. The longer startup budget covers cold machines and
+concurrent test/desktop startup without weakening PID, endpoint, token, or
+runtime-identity validation.
+
+`homeDir` and `KODAX_HOME` deliberately name different levels. Runtime SDK and
+CLI daemon `--home` accept the **base directory that contains `.kodax`**;
+lower-level `KODAX_HOME` points at the **data directory itself** and need not be
+named `.kodax`. To share the default CLI daemon, omit `homeDir`; this honors the
+exact resolved `KODAX_HOME`. Passing `os.homedir()` explicitly instead selects
+`<os.homedir()>/.kodax`, regardless of an ambient custom `KODAX_HOME`. For an
+isolated embedder namespace, pass a private base directory and expect data at
+`<homeDir>/.kodax`. Passing `~/.kodax` as `homeDir` would instead select
+`~/.kodax/.kodax` and a different daemon namespace.
 
 ### Worker-hosted embedded usage
 
@@ -2534,16 +2555,16 @@ For a given profile, one owner wins an atomic lock. Concurrent starters wait for
 the winner and connect once it is ready. Stale state is cleaned only after pid,
 endpoint, token, and runtime identity checks. If ownership cannot be verified,
 KodaX reports the daemon as unhealthy instead of killing an arbitrary process.
-SDK auto-start launches a detached `kodax daemon serve` process; it never treats
-an in-process socket listener as daemon mode. Closing the SDK client detaches
-without stopping that shared process. Use `kodax daemon stop` or the explicit
-runtime shutdown protocol to stop the owner.
-
-CLI and SDK startup retain the exact spawned candidate until health confirms
-that candidate PID. Early exit, timeout, identity mismatch, cancellation, or a
-different owner winning the race reclaims only the unsuccessful candidate
-process tree. Once healthy, the owner detaches normally and is not tied to the
-creating client process.
+SDK auto-start launches a detached `kodax daemon serve` process; it never treats
+an in-process socket listener as daemon mode. Closing the SDK client detaches
+without stopping that shared process. Use `kodax daemon stop` or the explicit
+runtime shutdown protocol to stop the owner.
+
+CLI and SDK startup retain the exact spawned candidate until health confirms
+that candidate PID. Early exit, timeout, identity mismatch, cancellation, or a
+different owner winning the race reclaims only the unsuccessful candidate
+process tree. Once healthy, the owner detaches normally and is not tied to the
+creating client process.
 
 ### Daemon startup, conflict, and recovery behavior
 
@@ -2559,18 +2580,18 @@ recovered as `interrupted` with a runtime event; they are not resumed
 automatically. Session and bounded event records remain available for explicit
 reconnect/retry decisions.
 
-Operational guidance:
-
-- use one stable profile for cooperating desktop clients;
-- use a separate `homeDir` or profile for tests, previews, and incompatible
-  configurations;
-- test harnesses that auto-start a process daemon must send authenticated
-  `runtime.shutdown` (or run `kodax daemon stop --home <dir> --profile <name>`)
-  before deleting their temporary home; `runtime.close()` only detaches;
-- KodaX's own Vitest harness also supplies an internal worker-PID marker so a
-  forcibly terminated worker cannot strand its test daemon; this is a test-only
-  fallback, not a public SDK option or a production idle-shutdown policy;
-- query `kodax daemon status --json` before deciding to restart;
+Operational guidance:
+
+- use one stable profile for cooperating desktop clients;
+- use a separate `homeDir` or profile for tests, previews, and incompatible
+  configurations;
+- test harnesses that auto-start a process daemon must send authenticated
+  `runtime.shutdown` (or run `kodax daemon stop --home <dir> --profile <name>`)
+  before deleting their temporary home; `runtime.close()` only detaches;
+- KodaX's own Vitest harness also supplies an internal worker-PID marker so a
+  forcibly terminated worker cannot strand its test daemon; this is a test-only
+  fallback, not a public SDK option or a production idle-shutdown policy;
+- query `kodax daemon status --json` before deciding to restart;
 - inspect `kodax daemon logs --lines 100` when startup times out;
 - custom endpoints and injected transports are attach-only unless the caller
   implements their owner lifecycle explicitly.
@@ -2606,10 +2627,10 @@ Every `KodaXRuntime` exposes the same service set in inline, Worker, and daemon
 | `mcp` | MCP server CRUD, validation, reload, and tool catalog listing. |
 | `artifacts` | Create/get/delete runtime artifact references for file/image/video inputs. |
 | `status` | Runtime snapshot with sessions, runs, permissions, workflows, and daemon counters. |
-| `diagnostics` | Latest context-budget and tool-exposure decisions for GUI/debug surfaces. |
-| `admin.agentRegistrations` | List/upsert, atomically set `enabled` while preserving the full registration, or remove redacted external-agent registrations. Owner/revision-conditional mutation prevents a stale manager from changing a same-ID replacement. With no plane, list is empty and mutations fail clearly. |
-| `agents` | Check `enabled`, list/describe policy-filtered dispatchable agents, and preflight a selected route. |
-| `agentTasks` | Start/list/get/wait/continue/cancel/reconcile durable external-agent tasks and read their ordered event stream. |
+| `diagnostics` | Latest context-budget and tool-exposure decisions for GUI/debug surfaces. |
+| `admin.agentRegistrations` | List/upsert, atomically set `enabled` while preserving the full registration, or remove redacted external-agent registrations. Owner/revision-conditional mutation prevents a stale manager from changing a same-ID replacement. With no plane, list is empty and mutations fail clearly. |
+| `agents` | Check `enabled`, list/describe policy-filtered dispatchable agents, and preflight a selected route. |
+| `agentTasks` | Start/list/get/wait/continue/cancel/reconcile durable external-agent tasks and read their ordered event stream. |
 
 ### Sessions, runs, and queueing
 
@@ -2621,14 +2642,14 @@ runtime close.
 ```ts
 const session = await runtime.sessions.create({ title: 'Shared session' });
 
-const sub = runtime.events.subscribe({ sessionId: session.id }, (event) => {
-  if (event.type === 'assistant.delta') {
-    // Render streaming text in the host UI.
-  }
-});
-// Daemon subscriptions establish a remote handshake. Await this before
-// starting work whose first event must not be missed; local subscriptions omit it.
-await sub.ready;
+const sub = runtime.events.subscribe({ sessionId: session.id }, (event) => {
+  if (event.type === 'assistant.delta') {
+    // Render streaming text in the host UI.
+  }
+});
+// Daemon subscriptions establish a remote handshake. Await this before
+// starting work whose first event must not be missed; local subscriptions omit it.
+await sub.ready;
 
 const artifact = await runtime.artifacts.create({
   kind: 'image',
@@ -2656,14 +2677,14 @@ sub.close();
 
 `runs.start({ options })` is a DTO boundary in Worker and daemon forms. Do not
 pass process-local objects such as `extensionRuntime`, callbacks, `AbortSignal`,
-LSP services, class instances, or cyclic structures. KodaX rejects them before
-transport instead of silently dropping fields.
-
-`events.beforeToolExecute` is an executable policy hook, not an observation
-callback. It is preserved in embedded mode and rejected in daemon mode; install
-the equivalent policy in the daemon owner instead. The KodaX REPL explicitly
-marks and removes only its own legacy approval hook because Runtime-owned
-permission brokering replaces that hook.
+LSP services, class instances, or cyclic structures. KodaX rejects them before
+transport instead of silently dropping fields.
+
+`events.beforeToolExecute` is an executable policy hook, not an observation
+callback. It is preserved in embedded mode and rejected in daemon mode; install
+the equivalent policy in the daemon owner instead. The KodaX REPL explicitly
+marks and removes only its own legacy approval hook because Runtime-owned
+permission brokering replaces that hook.
 
 Use the runtime APIs for cross-boundary behavior:
 
@@ -2692,7 +2713,7 @@ Space-style client can subscribe to permission events and answer a request
 created by a REPL-style client.
 
 ```ts
-const sub = runtime.events.subscribe({ type: 'permission.requested' }, (event) => {
+const sub = runtime.events.subscribe({ type: 'permission.requested' }, (event) => {
   const payload = event.payload;
   if (!payload || typeof payload !== 'object' || typeof payload.id !== 'string') {
     return;
@@ -2701,35 +2722,35 @@ const sub = runtime.events.subscribe({ type: 'permission.requested' }, (event) =
     payload.id,
     { type: 'allow_once' },
     { runId: payload.runId },
-  );
-});
-await sub.ready;
-```
-
-Await `ready` before another client starts work that may request permission;
-this creates an explicit cross-connection ordering boundary. Only the first
-valid response wins. Wrong-run or stale responses are rejected.
-Abort, runtime close, daemon stop, and timeout reject unresolved permission
-requests so tool approval promises do not hang forever.
-
-SDK clients that create a concrete request may pass `toolInput` and
-`executionCwd` to `runtime.permissions.request(...)` in both embedded and
-daemon mode. The Runtime removes raw `toolInput` before publishing the pending
-request, derives the bounded/redacted preview from that concrete input,
-canonicalizes it into a matcher, and returns only opaque `grantSuggestions`.
-A caller-supplied `inputPreview` cannot override this trusted summary.
-`projectRoot`, classifier signals, and other owner-only safety context are
-deliberately not client request fields.
-
-Grant administration is typed through `RuntimePermissionScope` and the
-exported `RuntimePermissionMatcher` union (`exact-command`, `exact-path`, and
-`exact-call`). These types are available from both the package root and
-`@kodax-ai/kodax/runtime`; matcher construction remains Runtime-owned.
-Legacy `allow_always.scope` responses remain accepted for 0.7.x clients, but
-the Runtime narrows them to its concrete candidate and never persists the
-client-provided coarse scope. Legacy persisted grants that lack a Runtime
-matcher remain inspectable and revocable, but never authorize a concrete tool
-call; the user must approve a fresh Runtime-issued exact suggestion.
+  );
+});
+await sub.ready;
+```
+
+Await `ready` before another client starts work that may request permission;
+this creates an explicit cross-connection ordering boundary. Only the first
+valid response wins. Wrong-run or stale responses are rejected.
+Abort, runtime close, daemon stop, and timeout reject unresolved permission
+requests so tool approval promises do not hang forever.
+
+SDK clients that create a concrete request may pass `toolInput` and
+`executionCwd` to `runtime.permissions.request(...)` in both embedded and
+daemon mode. The Runtime removes raw `toolInput` before publishing the pending
+request, derives the bounded/redacted preview from that concrete input,
+canonicalizes it into a matcher, and returns only opaque `grantSuggestions`.
+A caller-supplied `inputPreview` cannot override this trusted summary.
+`projectRoot`, classifier signals, and other owner-only safety context are
+deliberately not client request fields.
+
+Grant administration is typed through `RuntimePermissionScope` and the
+exported `RuntimePermissionMatcher` union (`exact-command`, `exact-path`, and
+`exact-call`). These types are available from both the package root and
+`@kodax-ai/kodax/runtime`; matcher construction remains Runtime-owned.
+Legacy `allow_always.scope` responses remain accepted for 0.7.x clients, but
+the Runtime narrows them to its concrete candidate and never persists the
+client-provided coarse scope. Legacy persisted grants that lack a Runtime
+matcher remain inspectable and revocable, but never authorize a concrete tool
+call; the user must approve a fresh Runtime-issued exact suggestion.
 
 ### Config, catalogs, MCP, and Space-style admin APIs
 
@@ -2802,18 +2823,18 @@ import {
 The schema is additive within this patch line. Removing or changing required
 fields requires a protocol version bump.
 
-### Current verification status
-
-The v0.7.69 release validation covers the runtime migration, the Worker
-isolation follow-ups delivered ahead of their original v0.7.71/v0.7.72
-planning slots, the v0.7.67 external-agent/session additions, the v0.7.68
-experimental Memory Agent surface, and the v0.7.69 A2A/integration/shared-
-daemon delivery:
-
-- Node 20 and Node 22 post-review regression for process cleanup, lock
-  ownership, frozen eval inputs, A2A transport, and the built-in manual;
-- root `tsc --noEmit`, package builds, bundle builds, and all 12 public DTS
-  entries on Node 20 and Node 22;
+### Current verification status
+
+The v0.7.69 release validation covers the runtime migration, the Worker
+isolation follow-ups delivered ahead of their original v0.7.71/v0.7.72
+planning slots, the v0.7.67 external-agent/session additions, the v0.7.68
+experimental Memory Agent surface, and the v0.7.69 A2A/integration/shared-
+daemon delivery:
+
+- Node 20 and Node 22 post-review regression for process cleanup, lock
+  ownership, frozen eval inputs, A2A transport, and the built-in manual;
+- root `tsc --noEmit`, package builds, bundle builds, and all 12 public DTS
+  entries on Node 20 and Node 22;
 - runtime/daemon/SDK/ACP/REPL integration tests, including process-distinct SDK
   auto-start and multi-client sessions/permissions;
 - Worker Runtime identity, service parity, hard close, capability requirements,
@@ -2821,1525 +2842,1806 @@ daemon delivery:
 - constructed-handler reverse tool RPC, abort bridging, CPU-loop termination,
   respawn, and revoke/dispose queue drainage;
 - context/tool-exposure eval gate;
-- embedded and hosted-daemon external-agent catalog/task parity, durable task
-  recovery, policy/credential/artifact gates, and disabled-plane failure;
-- exact session `surface` filtering plus opaque cursor continuation through the
-  narrow `/session` API, embedded Runtime, and daemon transport;
-- scoped zero-wait memory recall, read-only deliberate query, trace-only
-  receipts, bounded episode review, governed consult-before-write promotion,
-  and the self-contained `/experimental-memory` bundle/DTS surface;
-- bidirectional A2A 1.0 discovery/call/serve, durable task replay, no-code
-  configuration, local-Agent binding, exact Skill-script admission, SSRF/
-  credential boundaries, and the self-contained `/a2a` bundle/DTS surface;
-- split MCP/A2A/Extension configuration, lossless migration, canonical-template
-  drift checks, last-known-good hot reload, draining, and restart-required
-  classification;
-- atomic shared-daemon observation/resync, durable operations and same-session
-  ordering, settings/grant CAS, AskUser/permission transport, credential/Host
-  Tool reverse bridges, owner fencing, restart outcomes, and process-distinct
-  client/daemon smokes with credential-canary scans;
-- a fresh `0.7.69` tarball consumer importing all 11 public subpaths, creating a
-  Worker-hosted session, running the packaged CLI, and checking packaged DTS and
-  Worker sidecars; plus a Windows x64 binary/version/sidecar smoke;
-- external fresh npm consumer installation of the `0.7.67` tarball, proving
-  Worker isolation and a distinct daemon PID through the published subpath;
+- embedded and hosted-daemon external-agent catalog/task parity, durable task
+  recovery, policy/credential/artifact gates, and disabled-plane failure;
+- exact session `surface` filtering plus opaque cursor continuation through the
+  narrow `/session` API, embedded Runtime, and daemon transport;
+- scoped zero-wait memory recall, read-only deliberate query, trace-only
+  receipts, bounded episode review, governed consult-before-write promotion,
+  and the self-contained `/experimental-memory` bundle/DTS surface;
+- bidirectional A2A 1.0 discovery/call/serve, durable task replay, no-code
+  configuration, local-Agent binding, exact Skill-script admission, SSRF/
+  credential boundaries, and the self-contained `/a2a` bundle/DTS surface;
+- split MCP/A2A/Extension configuration, lossless migration, canonical-template
+  drift checks, last-known-good hot reload, draining, and restart-required
+  classification;
+- atomic shared-daemon observation/resync, durable operations and same-session
+  ordering, settings/grant CAS, AskUser/permission transport, credential/Host
+  Tool reverse bridges, owner fencing, restart outcomes, and process-distinct
+  client/daemon smokes with credential-canary scans;
+- a fresh `0.7.69` tarball consumer importing all 11 public subpaths, creating a
+  Worker-hosted session, running the packaged CLI, and checking packaged DTS and
+  Worker sidecars; plus a Windows x64 binary/version/sidecar smoke;
+- external fresh npm consumer installation of the `0.7.67` tarball, proving
+  Worker isolation and a distinct daemon PID through the published subpath;
 - Ubuntu Node 22 Unix-domain-socket daemon gate, including two clients sharing
   one runtime and cross-client permission resolution.
 
-The portable manual gates remain in
-`docs/test-guides/FEATURE_255_v0.7.66_TEST_GUIDE.md`,
-`FEATURE_256_v0.7.71_TEST_GUIDE.md`, and
-`FEATURE_257_v0.7.72_TEST_GUIDE.md` for release-machine verification; the latter
-two filenames retain their original planning slots while their content records
-the v0.7.66 delivery. v0.7.67 adds
-`FEATURE_258_v0.7.67_TEST_GUIDE.md`, `FEATURE_259_v0.7.67_TEST_GUIDE.md`, and
-`FEATURE_261_v0.7.67_TEST_GUIDE.md`; v0.7.69 adds
-`FEATURE_267_v0.7.69_TEST_GUIDE.md`, `FEATURE_268_v0.7.69_TEST_GUIDE.md`, and
-`FEATURE_269_v0.7.69_TEST_GUIDE.md`. The earlier release-preparation Actions
-run is not reused after the severe-fix review. Fresh GitHub Actions run
-`29385073422` passes the Node 20/22 build, bundle, DTS, and full-test matrix plus
-the Node 22 Unix-domain-socket daemon gate. npm publication remains a
-maintainer-owned manual step.
-
----
-
-## 18. External-agent executor plane (FEATURE_258, v0.7.67)
-
-FEATURE_258 lets an SDK host register remote agents without teaching the coding
-runtime a specific A2A, MCP, or HTTP client. The public contracts live in
-`@kodax-ai/kodax/agent`; the host-facing catalog and task services live on
-`@kodax-ai/kodax/runtime`.
-
-### Ownership rule
-
-An `AgentExecutorFactory` contains functions, so it cannot cross a Worker or
-daemon DTO boundary. Install factories where the Runtime owner executes:
-
-| Desired owner | Supported construction |
-|---|---|
-| Private in-process owner | `createKodaXRuntime({ mode: 'embedded', isolation: 'inline', externalAgents })` |
-| New locally hosted daemon owner | `createKodaXRuntime({ mode: 'daemon', profile: '<unique>', externalAgents })` |
-| Existing daemon | Configure its owner, then attach with `connectKodaXRuntime({ requirements: { externalAgents: true } })`; a client cannot inject factories. |
-| Runtime Worker | The Worker owner must install factories itself; passing `externalAgents` from the parent is rejected. |
-
-When `mode: 'daemon'` and `externalAgents` are supplied, the caller must win a
-new in-process daemon lease. KodaX rejects an already-running profile instead of
-silently replacing its executor configuration. Closing that owner facade shuts
-down the host it created; closing an ordinary attached client only detaches.
-
-### Minimal owner and task flow
-
-The reference executor below is a contract/conformance adapter. Replace it with
-your own `AgentExecutorFactory` for a real remote protocol.
-
-```ts
-import {
-  createReferenceAgentExecutorFactory,
-  type ExternalAgentRegistration,
-} from '@kodax-ai/kodax/agent';
-import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';
-
-const runtime = await createKodaXRuntime({
-  mode: 'embedded',
-  isolation: 'inline',
-  externalAgents: {
-    factories: [createReferenceAgentExecutorFactory({
-      executorId: 'example-http',
-      protocol: 'http',
-    })],
-    policy: ({ registration, query }) => ({
-      allowed: registration.enabled && query.readOnly === true,
-      reasons: query.readOnly === true ? [] : ['This host allows read-only dispatch only.'],
-    }),
-    defaultContext: { actorId: 'desktop-host' },
-  },
-});
-
-const registration: ExternalAgentRegistration = {
-  agentId: 'external:reviewer',
-  displayName: 'Remote Reviewer',
-  enabled: true,
-  executorId: 'example-http',
-  protocol: 'http',
-  configurationRevision: 'reviewer-config-v1',
-  endpointIdentityHash: 'sha256:replace-with-stable-endpoint-identity',
-  skills: ['code-review'],
-  inputModalities: ['text'],
-  outputModalities: ['text'],
-  capabilities: {
-    streaming: 'supported',
-    durableTasks: 'supported',
-    inputRequired: 'conditional',
-    cancellation: 'supported',
-    artifacts: 'unsupported',
-  },
-  effects: { remote: 'read', workspace: 'proposal' },
-  maxConcurrency: 1,
-};
-
-try {
-  await runtime.admin.agentRegistrations.upsert(registration);
-
-  const query = {
-    actorId: 'desktop-host',
-    requiredSkills: ['code-review'],
-    readOnly: true,
-  } as const;
-  const available = await runtime.agents.listDispatchable(query);
-  const preflight = await runtime.agents.preflight({
-    agentId: 'external:reviewer',
-    query,
-    expectedConfigurationRevision: registration.configurationRevision,
-  });
-  if (!preflight.ok) throw new Error(preflight.reasons.join('; '));
-
-  const started = await runtime.agentTasks.start({
-    agentId: 'external:reviewer',
-    objective: 'Review the supplied immutable patch and return cited findings.',
-    context: { actorId: 'desktop-host', runId: 'host-run-42' },
-    readOnly: true,
-    requiredSkills: ['code-review'],
-    expectedConfigurationRevision: registration.configurationRevision,
-  });
-  const terminal = await runtime.agentTasks.wait(started.taskId, 60_000);
-  console.log(available, terminal.state, terminal.output, terminal.usage);
-} finally {
-  await runtime.close();
-}
-```
-
-`runtime.agents.enabled` is the cheap external-plane feature check. If it is
-false, catalog queries can still return built-in local agents but no external
-agents; registration and task lists are empty, while point reads and mutations
-fail clearly. Set
-`requirements.externalAgents: true` when absence must abort connection.
-
-### Service reference
-
-| Surface | Methods | Contract |
-|---|---|---|
-| `runtime.admin.agentRegistrations` | `list`, `upsert`, `setEnabled`, `remove` | Durable owner configuration. `setEnabled` preserves the complete captured executor registration while changing admission. Mutations accept both `expectedConfigurationRevision` and `expectedManagementOwner`; `setEnabled` can also atomically `claimOwner` on an unowned registration and rejects another owner. List results expose `managementOwner` and `credentialConfigured`, never a credential value. The same contract is carried across the daemon transport. With no plane, `list()` is empty and mutations fail clearly. |
-| `runtime.agents` | `enabled`, `listDispatchable`, `describe`, `preflight` | Applies health, capability, effect, concurrency, credential-presence, configuration-revision, and host-policy checks before dispatch. |
-| `runtime.agentTasks` | `start`, `list`, `get`, `events`, `wait`, `sendInput`, `cancel`, `reconcile` | Durable snapshots and append-only events for external tasks. The task keeps the immutable registration/executor binding captured at start. |
-
-`agentTasks.events(taskId, cursor)` uses the last seen numeric event `seq` as its
-cursor and returns events with a greater sequence. `wait()` resolves only at a
-terminal task state and rejects on a positive `timeoutMs` expiry. `sendInput()`
-is valid only while the task reports `input-required` or `auth-required`.
-`reconcile()` asks the bound executor for authoritative remote state after an
-owner restart or uncertain failure.
-
-For external tasks, the built-in stores persist an internal full registration
-snapshot before the public task ledger. It is keyed by Agent ID and revision,
-is never returned by task or daemon APIs, and lets an admitted task keep using
-its original executor route after registration update/removal and Runtime
-restart. The internal form fixes `enabled: true` and omits management ownership
-and health diagnostics. The task's public route summary is validated against that internal
-snapshot before recovery. Terminal task state is durable before the last
-unreferenced snapshot is removed; startup cleans crash-window orphans.
-
-Custom `AgentExecutorPlaneStore` implementations should implement
-`loadTaskRegistrationSnapshots()` and `saveTaskRegistrationSnapshots()` as a
-pair and give one Runtime exclusive write ownership of that store. Omitting
-both remains compatible, but restart recovery then succeeds only while the
-exact current registration still exists. Store only non-secret executor config
-or secret references in `executorConfig`/`credentialRef`; the broker resolves
-the current referenced credential just in time, so removing a registration is
-not equivalent to revoking that credential at its issuer.
-
-The owner plane has a terminal close contract. Closing it rejects every pending
-`wait()` (including a wait without `timeoutMs`), disposes its executor instances,
-and makes subsequent registration, catalog, preflight, and task calls reject
-with `Agent executor plane is closed.` One overall deadline covers admitted
-work plus executor disposal: the default is 30 seconds, and direct
-`createAgentExecutorPlane()` hosts may supply a positive finite
-`closeTimeoutMs`. A timeout rejects visibly even though already-admitted cleanup
-may finish in the background. Repeated `close()` calls are safe. SDK hosts
-should stop accepting work before closing the owner and must not retain a plane
-service as a reusable handle after Runtime shutdown.
-
-Restricted Workflow scripts use the same route as direct SDK calls. Both
-`wf.spawnAgent()` and `wf.runAgent()` validate and forward
-`target: { agentId, expectedConfigurationRevision? }`; `phase` is forwarded as
-well. A blank ID or revision is rejected at the script boundary instead of
-silently falling back to the native child backend.
-
-### Credential, artifact, and failure boundaries
-
-- Put only a `credentialRef` in a registration. Resolve secret material through
-  `AgentCredentialBroker.withCredential()`; do not place tokens in
-  `executorConfig`, events, diagnostics, or task output.
-- Remote artifacts are denied by default. Supply `artifactPolicy` to authorize
-  each artifact before it materializes in the host boundary.
-- External agents may declare workspace effect `none` or `proposal`; direct
-  workspace mutation is intentionally not a valid external registration.
-- Use `expectedConfigurationRevision` for dispatch. For registration mutations,
-  compare both it and `expectedManagementOwner` so a same-revision ownership
-  change cannot be overwritten from an earlier catalog read. Config managers
-  should set a stable `managementOwner`; they may atomically claim an unowned
-  legacy registration while disabling it, but must not mutate a registration
-  owned by another manager.
-- Treat `configurationRevision` as the stable identity of immutable execution
-  content, not as a small counter. The same content may deterministically reuse
-  the same revision across remove/re-add or Runtime restart, but different
-  endpoint, protocol, executor/auth config, capabilities, effects, Skills,
-  modalities, or resource limits must never reuse it. Built-in A2A
-  configuration derives it from content.
-- A remote start followed by uncertain local persistence is recorded as
-  `unknown` with its executor reference preserved; reconcile it rather than
-  blindly starting a duplicate. Stable idempotency keys protect retries.
-- The durable plane records provider-reported usage when available. It never
-  invents missing token or cost fields.
-
-For a production adapter, implement `preflight?`, `start`, `events`, `get`,
-`sendInput`, `cancel`, `reconcile`, and `dispose` on `AgentExecutor`. The factory
-receives `withCredential()` and `authorizeArtifact()` callbacks so protocol code
-cannot bypass the host's secret/artifact policies.
-
----
-
-## 19. Session surface filtering and cursor pagination (FEATURE_261, v0.7.67)
-
-The narrow session SDK and Runtime facade now share the same listing semantics:
-`surface` is an exact filter applied before `limit`, and `cursor` is an opaque
-continuation token carried by each returned summary.
-
-### Narrow `/session` API
-
-```ts
-import { listSessions, type SessionSummary } from '@kodax-ai/kodax/session';
-
-const all: SessionSummary[] = [];
-let cursor: string | undefined;
-do {
-  const page = await listSessions({
-    scope: 'user',
-    surface: 'partner',
-    limit: 50,
-    ...(cursor ? { cursor } : {}),
-  });
-  all.push(...page);
-  cursor = page.length === 50 ? page.at(-1)?.cursor : undefined;
-} while (cursor);
-```
-
-### Embedded/daemon Runtime API
-
-```ts
-const first = await runtime.sessions.list({ surface: 'acp', limit: 25 });
-const nextCursor = first.at(-1)?.cursor;
-const second = nextCursor
-  ? await runtime.sessions.list({ surface: 'acp', limit: 25, cursor: nextCursor })
-  : [];
-```
-
-The filter also composes with `projectRoot`, `scope`, `includeArchived`, `before`,
-and `tag`. Treat cursors as opaque: do not parse them, compare them to session
-IDs, or manufacture them. An invalid cursor produces an empty page on the narrow
-session API. A page shorter than the requested limit is terminal; a full page
-may continue with its last item's cursor.
-
-The interactive `kodax -r` picker is a consumer of these session semantics, not
-a separate SDK API. Headless hosts should build their own UI on `listSessions()`
-or `runtime.sessions.list()` and resume by the selected full session ID.
-
----
-
-## 20. Cost-disciplined workflow routing and telemetry (FEATURE_259, v0.7.67)
-
-FEATURE_259 adds a public cost/quality contract without making the authoring LLM
-choose provider-specific model names. The SDK host maps semantic tiers to routes;
-workflow/child briefs request intent.
-
-### Configure tiers and bounded concurrency
-
-```ts
-import { join } from 'node:path';
-import { runKodaX } from '@kodax-ai/kodax/coding';
-
-const workflowRunsBaseDir = join(process.cwd(), '.kodax-host', 'workflow-runs');
-const result = await runKodaX({
-  provider: 'zai-coding',
-  model: 'glm-5.2',
-  agentMode: 'amaw',
-  workflowRunsBaseDir,
-  modelTiers: {
-    fast: { provider: 'deepseek', model: 'deepseek-v4-flash' },
-    deep: { provider: 'zai-coding', model: 'glm-5.2' },
-  },
-  workflow: { maxConcurrency: 3 },
-  events: {
-    onWorkflowAgentDigest: ({ runId, event }) => {
-      if (event.type === 'agent_completed' || event.type === 'agent_unverified'
-        || event.type === 'agent_failed') {
-        console.log(runId, event.data);
-      }
-    },
-  },
-}, 'Review this change using scoped evidence packets.');
-
-console.log(result.lastText);
-```
-
-Tier rules are deliberately small:
-
-- `fast`: mechanical read-only lookup. A write child is ineligible and safely
-  inherits the parent route.
-- `balanced`: ordinary implementation/investigation/review; uses the parent
-  route, so there is no separate `balanced` mapping.
-- `deep`: architecture, adversarial verification, severity calibration, and
-  final synthesis.
-- An unconfigured or selector-shadowed tier inherits the appropriate explicit,
-  specialist, or parent route and records why; it does not silently claim the
-  requested route was applied.
-
-The workflow authoring contract also supports `scopeSummary`, `constraints`,
-`evidenceRefs`, `verification`, `readOnly`, `outputSchema`, and `terseResult`.
-Use those fields to transfer a compact immutable packet instead of asking every
-child to rediscover the same repository context.
-
-### Live route facts
-
-Terminal `WorkflowEvent.data` may include `requestedTier`, `tierOutcome`,
-`providerSource`, `modelSource`, initial/final provider and model,
-`fallbackReason`, `iterations`, `durationMs`, `usage`, and `digestUsage`.
-Treat absent fields as unknown. In particular, KodaX does not fabricate usage
-for external executors that did not report it.
-
-Direct child-dispatch consumers receive the typed `KodaXChildAgentResult.routeFacts`
-surface, including resolved effort and input/cache-read/output/digest token
-breakdown when known. Inline workflow consumers can subscribe to the raw
-`onWorkflowAgentDigest` event as above; GUI progress remains available through
-`onWorkflowProcessEvent` / `runtime.workflows`.
-
-### Durable efficiency report
-
-When `workflowRunsBaseDir` is supplied, every terminal workflow writes:
-
-```text
-<workflowRunsBaseDir>/<runId>/run.json
-<workflowRunsBaseDir>/<runId>/events.jsonl
-<workflowRunsBaseDir>/<runId>/artifacts/*.json
-```
-
-`run.json.efficiencyReport` includes:
-
-- total/input/cache-read/output/digest tokens and wall-clock duration;
-- total starts, child turns, starts by `role/tier`, and primary-review starts;
-- duplicate primary packet reads plus verification/synthesis packet reads;
-- review/fix/re-review waves and structured review quality-gate outcomes;
-- `tokenCoverage.ok` plus missing local task IDs;
-- `excludedExternalTaskIds` for external tasks whose executor reported no usage.
-
-Do not interpret `totalModelTokens: 0` as free execution unless
-`tokenCoverage.ok` is true and the relevant external task IDs are not excluded.
-The report is an audit/optimization artifact; correctness still comes from the
-workflow's structured findings, verification results, and quality gates.
-
----
-
-## 21. Experimental governed memory — `/experimental-memory` (FEATURE_260, v0.7.68)
-
-KodaX has one durable memory plane: the F228 Memory Control Plane. FEATURE_260
-adds a thin, opt-in agent/session API over that plane; it does not add a second
-database, filesystem memory actions, a resident memory specialist, or online
-self-modification.
-
-Top-level `runKodaX()` coding runs wire this lifecycle automatically. They build
-an exact-scoped memory pack at session start, keep passive recall off the
-blocking hot path, expose `memory_recall` only when the memory session starts,
-record bounded observations/outcomes, and close the session at the run boundary.
-Use the direct SDK below when a custom host needs to own those boundaries.
-
-### Minimal direct session
-
-```ts
-import { createMemoryControlPlane } from '@kodax-ai/kodax/agent';
-import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory';
-
-const identity = {
-  tenantId: 'tenant:acme',
-  workspaceId: 'workspace:desktop',
-  userId: 'user:42',
-  agentId: 'agent:reviewer',
-  projectId: 'project:kodax',
-  sessionId: 'session:20260712',
-};
-
-const controlPlane = createMemoryControlPlane({
-  cwd: process.cwd(),
-  identity,
-  projectDocs: [],
-  discoverSkills: false,
-});
-const memory = createMemoryAgent({ controlPlane });
-const session = await memory.startSession({
-  identity,
-  objective: 'Review the runtime shutdown change',
-});
-
-const immediate = session.recall({
-  decisionRevision: 'decision:1',
-  objective: 'Review the runtime shutdown change',
-  decisionContext: 'Choosing the first verification step',
-  decisionIntent: 'runtime shutdown regression',
-  throughSequence: 0,
-});
-const deliberate = await session.query({
-  decisionRevision: 'decision:2',
-  need: 'What uncommon daemon cleanup failure happened before?',
-  throughSequence: 0,
-});
-
-await session.complete({
-  status: 'succeeded',
-  summary: 'Shutdown state replacement verified',
-  evidence: [],
-});
-await session.close();
-```
-
-`recall()` is synchronous: exact observations/hints can be returned immediately,
-while an optional semantic prefetch finishes for a later matching decision.
-`query()` is deliberate and read-only; one distinct query is admitted per
-decision epoch, and the result is bounded to at most three prompt-safe hints and
-512 estimated tokens. `undefined` means there is no governed reminder to inject.
-
-### Evidence, tracing, and persistence boundaries
-
-- Recalled content is low-authority evidence. Current repository/config/runtime
-  facts must still come from current tools or host state.
-- `observe()` accepts monotonic, evidence-linked observations and rejects secret
-  material. `rewind()` removes observations after a sequence boundary.
-- `complete()` can emit an Outcome Digest through `persistOutcomeDigest` and run
-  bounded episode review through `reviewEpisode`; cancellation creates neither.
-- `onTrace` receives policy-versioned `MemoryDecisionReceipt` metadata that links
-  candidates, selection, injection, and later outcome influence. Receipts are
-  trace-only and contain no hidden reasoning.
-- Durable memory mutation remains owned by F228's
-  proposal/preview/fingerprint/apply flow. `/memory` is the CLI governance
-  surface; direct file/shell writes to managed memory roots are denied.
-- Identity/applicability matching is exact and fail-closed. Hosts should supply
-  stable tenant/workspace/user/agent/project/session identifiers and must not put
-  credentials into those identifiers.
-
-The subpath is experimental and ESM-only. Treat its exported types as opt-in
-v0.7.x contracts; keep persistence and product policy behind your own adapter.
-
----
-
-## 22. Bidirectional A2A 1.0 — `/a2a` (FEATURE_267, v0.7.69)
-
-`@kodax-ai/kodax/a2a` is the protocol edge for the A2A 1.0 JSON-RPC/SSE
-profile. It composes the protocol-neutral F258 executor plane with the Runtime
-facade; `/agent` and `/coding` remain free of A2A wire types and dependencies.
-
-### Call an A2A Agent through F258
-
-Discovery is an explicit host action. The URL must match `allowedOrigins`, and
-the default safe transport pins the validated DNS address for each connection
-and independently revalidates redirects, rejects public plain HTTP, bounds
-time/body/redirects, and strips authorization on a cross-origin redirect. A
-custom `fetch` option is a trusted transport override: the embedder then owns
-equivalent DNS-to-connection binding in that transport or proxy.
-
-The selected interface must remain on the Card's trusted origin. KodaX parses
-typed Card-level and Skill-level security declarations: requirement objects are
-alternatives (OR), every scheme inside one object is conjunctive (AND), and an
-empty requirement is anonymous. A configured credential is used only when one
-complete requirement is satisfiable; protected Skills that the configured
-profile cannot satisfy are not advertised to the Runtime catalog.
-
-The built-in profiles are HTTP Bearer and OAuth 2.0 Client Credentials. The
-OAuth profile pins the Card scheme, issuer, exact token endpoint, client ID,
-secret reference, scopes, optional RFC 8707 resource, and client authentication
-method. The external Authorization Server—not the Agent and not KodaX—issues
-the access token. KodaX resolves the client secret only for refresh, keeps an
-expiring token in process memory, coalesces refreshes, and retries one RPC once
-with a fresh token after `401`. Card, Agent RPC, and token endpoints remain
-separate safe-fetch trust boundaries, so a remote Agent cannot redirect a task
-payload to the token origin. API key, Basic, interactive OAuth, OIDC, mTLS, and
-multi-scheme AND requirements fail explicitly in the built-in client.
-
-```ts
-import {
-  createA2AAgentExecutorFactory,
-  discoverA2ARegistration,
-} from '@kodax-ai/kodax/a2a';
-import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';
-
-const client = {
-  networkPolicy: {
-    // Card/RPC and OAuth token endpoints are separate trust boundaries.
-    allowedOrigins: ['https://reviewer.example', 'https://identity.example'],
-    allowPrivateAddresses: false,
-    requestTimeoutMs: 10_000,
-    maxResponseBytes: 1_048_576,
-    maxRedirects: 2,
-  },
-  pollIntervalMs: 500,
-} as const;
-
-const discovered = await discoverA2ARegistration({
-  agentId: 'external:a2a-reviewer',
-  agentCardUrl: 'https://reviewer.example/.well-known/agent-card.json',
-  credentialRef: 'a2a/reviewer',
-  effects: { remote: 'read' },
-}, client);
-
-const runtime = await createKodaXRuntime({
-  mode: 'embedded',
-  isolation: 'inline',
-  externalAgents: {
-    factories: [createA2AAgentExecutorFactory(client)],
-    credentialBroker: {
-      async withCredential(ref, use) {
-        const value = ref === 'a2a/reviewer'
-          ? process.env.A2A_REVIEWER_TOKEN
-          : ref === 'a2a/reviewer-client-secret'
-            ? process.env.A2A_REVIEWER_CLIENT_SECRET
-            : undefined;
-        if (!value) throw new Error(`Missing credential for reference: ${ref}.`);
-        return use(value);
-      },
-    },
-    policy: ({ registration }) => ({ allowed: registration.effects.remote === 'read' }),
-    defaultContext: { actorId: 'a2a-host' },
-  },
-});
-
-await runtime.admin.agentRegistrations.upsert(discovered.registration);
-const started = await runtime.agentTasks.start({
-  agentId: discovered.registration.agentId,
-  objective: 'Review this change and return cited findings.',
-  context: { actorId: 'a2a-host' },
-  readOnly: true,
-  expectedConfigurationRevision: discovered.registration.configurationRevision,
-});
-const terminal = await runtime.agentTasks.wait(started.taskId, 60_000);
-```
-
-For OAuth, replace the legacy `credentialRef` input with the structured form;
-the same F258 `credentialBroker` must resolve `clientSecretRef`. The shared
-network policy must admit both origins, while each Card, RPC, and token request
-is still narrowed to its own exact origin:
-
-```ts
-const discovered = await discoverA2ARegistration({
-  agentId: 'external:a2a-reviewer',
-  agentCardUrl: 'https://reviewer.example/.well-known/agent-card.json',
-  authentication: {
-    type: 'oauth2-client-credentials',
-    scheme: 'enterprise-oauth',
-    issuer: 'https://identity.example/',
-    tokenUrl: 'https://identity.example/oauth/token',
-    clientId: 'kodax-reviewer',
-    clientSecretRef: 'a2a/reviewer-client-secret',
-    scopes: ['a2a.invoke'],
-    resource: 'https://reviewer.example/',
-    clientAuthentication: 'client-secret-basic',
-  },
-  effects: { remote: 'read' },
-}, client);
-```
-
-The executor supports durable task start/get, input continuation, cancel,
-reconcile, SSE events, and polling fallback. An ambiguous start is not retried
-automatically. A `credentialRef` is resolved just in time by the F258 broker;
-the registration, task store, and diagnostics never contain the credential.
-Authenticated SSE uses that same broker. JSON-RPC ID/version and task/context
-correlation are validated before an event is accepted; if a stream ends
-normally before a terminal snapshot, the executor resumes bounded polling.
-Streamed `artifactUpdate` chunks are accumulated by artifact ID according to
-`append`, and direct Message file Parts are preserved as authorized artifact
-references.
-
-### Built-in configured path (no host code)
-
-The CLI product path stores one user document at
-`~/.kodax/integrations/a2a.json` and uses the same F258 plane:
-
-```bash
-kodax a2a add reviewer https://reviewer.example/.well-known/agent-card.json \
-  --credential-env A2A_REVIEWER_TOKEN --effect read
-kodax a2a test reviewer
-kodax a2a call reviewer "Review this document"
-```
-
-The no-code OAuth path stores only the environment-variable name for the client
-secret. It can be staged disabled and hot-activated later:
-
-```bash
-export A2A_REVIEWER_CLIENT_SECRET='provisioned-out-of-band'
-# PowerShell: $env:A2A_REVIEWER_CLIENT_SECRET='provisioned-out-of-band'
-# PowerShell: use one line or replace each trailing \ with a backtick.
-kodax a2a add reviewer https://reviewer.example/.well-known/agent-card.json \
-  --disabled --effect read --oauth-scheme enterprise-oauth \
-  --oauth-issuer https://identity.example/ \
-  --oauth-token-url https://identity.example/oauth/token \
-  --oauth-client-id kodax-reviewer \
-  --oauth-client-secret-env A2A_REVIEWER_CLIENT_SECRET \
-  --oauth-scope a2a.invoke --oauth-resource https://reviewer.example/
-kodax a2a enable reviewer
-kodax a2a disable reviewer
-```
-
-Embedded CLI Runtimes and the user-owned daemon automatically reconcile these
-entries as `external:<name>`. Discovery/update failure retains that entry's
-last-known-good registration; another entry can still update. The environment
-broker resolves `credentialEnv` only at call time. Automatic Runtime
-registration accepts public HTTPS and exact loopback targets; explicit private
-network access remains an operator action on the direct CLI/SDK path.
-
-`enabled` is desired state in `a2a.json`, not a fabricated cross-process live
-flag. `a2a list` reports configured entries and that desired state. The owning
-Runtime's `admin.agentRegistrations.list()` is authoritative for applied
-registrations. Automatic reconciliation handles disables/removals first,
-skips unchanged peers, performs no Card or token request for disabled entries,
-and rediscovers before re-enable. Once the owning Runtime observes and applies
-the revision, disable blocks all new starts, including an explicit
-`external:<name>` target, but does not cancel or break an already admitted task.
-The CLI mutation returning is not cross-process acknowledgement. A failed
-activation remains retryable through the owning
-`ConfiguredA2ARuntimeHandle.reload()` even when the disk revision is unchanged;
-the passive `kodax integrations reload` command validates only its own process.
-
-`kodax a2a test` performs Card discovery and security planning only. It never
-requests an OAuth access token; token acquisition starts at `a2a call` or the
-first Runtime dispatch.
-
-Inbound publication is also no-code:
-
-```bash
-export KODAX_A2A_TOKEN='replace-with-a-long-random-token'
-# PowerShell: $env:KODAX_A2A_TOKEN='replace-with-a-long-random-token'
-kodax a2a expose                    # Runtime default Agent
-kodax a2a expose document-agent     # ~/.kodax/agents/document-agent.md
-kodax a2a serve --port 8765
-```
-
-The fixed token above is the compatibility profile. For dynamic production
-tokens, configure KodaX as an OAuth Resource Server and point it at an external
-issuer:
-
-```bash
-kodax a2a expose document-agent --auth oauth2-jwt \
-  --oauth-scheme enterprise-oauth \
-  --oauth-issuer https://identity.example/ \
-  --oauth-audience https://kodax.example/a2a \
-  --oauth-jwks-url https://identity.example/.well-known/jwks.json \
-  --oauth-token-url https://identity.example/oauth/token \
-  --oauth-metadata-url https://identity.example/.well-known/oauth-authorization-server \
-  --required-scope a2a.invoke
-kodax a2a serve --port 8765
-```
-
-The Authorization Server authenticates clients, provisions client IDs/secrets,
-issues/rotates/revokes tokens and, for JWT access tokens, signs them and
-publishes metadata/JWKS. The calling A2A
-client obtains a token out of band or with Client Credentials and sends it in
-the Bearer header. KodaX validates JWT type, asymmetric signature, issuer,
-audience, lifetime, subject, and required scopes before task lookup, then maps
-`sub` to the A2A principal. Missing/invalid credentials return `401`; a valid
-token without the required scope returns `403 insufficient_scope`. KodaX does
-not hold the issuer signing key or expose token, refresh, client-registration,
-login, or consent endpoints. Opaque-token introspection and mTLS deployments
-must use a host authentication adapter or reverse proxy. Offline JWT/JWKS
-validation also cannot observe immediate per-token revocation: use short access
-token lifetimes, signing-key rotation, or an introspecting proxy/adapter when
-that property is required.
-
-#### Upgrade retained pre-realm tasks
-
-Realm-aware task ownership intentionally has no normal-request legacy fallback:
-an authority switch must never adopt tasks merely because it reuses a subject.
-If a v0.7.70 task store must remain addressable after upgrading, stop the A2A
-server and first inspect an exact-owner migration plan:
-
-```bash
-kodax a2a migrate-tasks
-kodax a2a migrate-tasks --apply --confirm-server-stopped
-
-# OAuth identity is token-specific, so provide the known historical subject.
-kodax a2a migrate-tasks --subject trusted-orchestrator
-```
-
-The configured Bearer profile supplies its fixed `principalId`; OAuth requires
-`--subject`. Dry-run does not rewrite `tasks.json`. Apply rekeys only exact
-matches, preserves unmatched records, and refuses a live task-store owner.
-Custom SDK hosts can plan multiple known owners without exposing raw tokens:
-
-```ts
-import { migrateA2ALegacyTaskOwners } from '@kodax-ai/kodax/a2a';
-
-const mappings = [{
-  securityRealm: 'oauth2-jwt:https://identity.example/',
-  subject: 'trusted-orchestrator',
-}] as const;
-const plan = migrateA2ALegacyTaskOwners({
-  dataDir: '/var/lib/kodax/a2a', mappings, apply: false,
-});
-
-// After the host/operator verifies the plan:
-if (plan.matchedLegacyTaskCount > 0) {
-  migrateA2ALegacyTaskOwners({
-    dataDir: '/var/lib/kodax/a2a', mappings, apply: true,
-  });
-}
-```
-
-The SDK also accepts `tenant` when a custom authentication adapter historically
-returned one. Two mappings that claim the same legacy owner for different
-realms are ambiguous and rejected; split or guessed ownership is never applied.
-
-`a2a serve` resolves its Runtime provider in this order: explicit CLI option,
-environment, core configuration, then the built-in default. Provider-compatible
-model selection follows the normal hosted Runtime rule. A selected Markdown
-Agent may declare its own validated `provider`; remote A2A input cannot choose
-or override provider, model, reasoning, profile, workspace, or tools.
-
-`expose` validates a named user Markdown Agent before writing its reference.
-`serve` loads configured MCP and Extensions before it resolves the execution
-binding or opens a socket. Native workspace read tools are admitted by
-workspace access; writes, narrow Extension Tools, MCP capabilities, subagents,
-and isolated Skill scripts require their corresponding exact `toolPolicy`
-authority. Internal Skills come from `~/.kodax/skills`, `~/.agents/skills`,
-plugins, and built-ins; public Agent Card skills are a separate explicit
-projection and never reveal the private Skill inventory.
-
-The running server pins Agent, Skill, workspace, tool registration, process and
-store revisions. Card/auth/limits can hot reload; execution-authority changes
-require an explicit restart. Managed contexts live below
-  `~/kodax_a2a_server_workspace/<runtime-profile>/contexts/<context-key>/`. Exact Skill scripts require
-`process: isolated`, an admitted `scripts/...` path, and a passing
-`kodax sandbox doctor`; KodaX never falls back to an unsandboxed shell.
-
-Every concrete file reached by `read`, `grep`, or `glob` is checked against the
-bound workspace. Child runs inherit ceilings for native reads, tools, Skills,
-and Skill scripts; they cannot expand the parent's admitted authority.
-
-### Publish one KodaX Agent
-
-Publication is host-owned and opt-in. The public card describes only the
-configured Agent, media types, and skills. Authentication runs before task
-lookup; authorization runs per operation; task visibility is principal-scoped.
-
-```ts
-import {
-  createBearerEnvA2AAuthentication,
-  createKodaXA2AServer,
-} from '@kodax-ai/kodax/a2a';
-import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';
-
-const runtime = await createKodaXRuntime({ mode: 'embedded', isolation: 'inline' });
-const server = createKodaXA2AServer({
-  runtime,
-  dataDir: '/var/lib/kodax/a2a',
-  agent: {
-    name: 'KodaX Reviewer',
-    description: 'Reviews bounded code changes.',
-    version: '1.0.0',
-    publicBaseUrl: 'https://kodax.example',
-    skills: [{ id: 'review', name: 'Review', description: 'Review code.', tags: ['code'] }],
-    inputModes: ['text/plain'],
-    outputModes: ['text/plain'],
-  },
-  authentication: createBearerEnvA2AAuthentication({
-    type: 'bearer-env',
-    tokenEnv: 'KODAX_A2A_TOKEN',
-    principalId: 'trusted-orchestrator',
-  }),
-  async authorize({ principal }) { return principal.scopes.includes('a2a:invoke'); },
-  limits: {
-    maxRequestBytes: 1_048_576,
-    maxPartBytes: 524_288,
-    maxConcurrentTasks: 8,
-    maxTaskWaitMs: 30_000,
-    maxActiveTasksPerPrincipal: 8,
-    maxRetainedTasksPerPrincipal: 64,
-    maxEventsPerTask: 1_000,
-    maxEventBytesPerTask: 16_777_216,
-    maxWorkspaceBytesPerContext: 1_073_741_824,
-  },
-});
-
-// Development only: the built-in listener refuses non-loopback hosts.
-const localBaseUrl = await server.listen({ hostname: '127.0.0.1', port: 0 });
-```
-
-Production hosts route `GET /.well-known/agent-card.json` and canonical
-JSON-RPC `POST /a2a` to `server.handle(request)` behind their own TLS
-terminator. `POST /` remains an accepted compatibility alias. `listen()` waits for durable recovery before
-it resolves. A host that wires `handle()` directly may explicitly await
-`server.whenReady()` before it starts accepting traffic; `handle()` also waits
-for the same recovery promise. The durable edge store supports get/list,
-continuation, cancellation, ordered SSE subscription, and surviving Runtime-run
-reattachment after an edge restart. Push notifications, A2A 0.3, gRPC, and
-HTTP+JSON are not advertised; unsupported push methods return the standard
-`PushNotificationNotSupportedError`.
-
-Non-streaming `SendMessage` waits at most `maxTaskWaitMs` (30 seconds by
-default). When that bound is reached the response contains the current working
-task; it does not cancel the Runtime run, and clients can continue with
-`GetTask` or `SubscribeToTask`.
-
-When a task enters `INPUT_REQUIRED`, the next accepted input answers the pending
-interaction on the original Runtime run; it does not start a replacement run.
-History length and list filters are validated and bounded. Task listing uses a
-stable opaque cursor, while per-principal retention prunes only the oldest
-terminal records. Terminal subscriptions and failed-start resources are closed
-by their owning lifecycle.
-
-Remote messages are ordinary user inputs. They cannot select provider, model,
-profile, tools, working directory, permission mode, or Runtime configuration.
-URL parts are rejected; inline raw/data parts are bounded and materialized under
-the server-owned data directory. Responses expose final approved output only,
-not system prompts, reasoning deltas, tool payloads, credentials, or local paths.
-
-Generated files are published only through the trusted output broker: a normal
-tool or Extension stages a file in the context's `.kodax-a2a-staging` area, or
-a successfully admitted `run_skill_script` promotes one of its declared
-outputs. The server rechecks that the result is a regular non-symlink file in
-the real bound workspace and applies part-size/output-mode limits before
-inlining it. A declaration from a failed Skill run, an ordinary `write`/`edit`
-elsewhere in the workspace, and a local path in model text never become A2A
-artifacts implicitly.
-
-The normative baseline is A2A repository commit
-`2183794bfb9b67af4aee1be0a0ef726050642873`, protocol `1.0`, with
-`specification/a2a.proto` SHA-256
-`e195bf96ab630c69797851970203e1b2b6b19528f2e9803b7d904b91a5104016`.
-
----
-
-## 23. Shared Coder daemon for Space and IDE hosts (FEATURE_269, v0.7.69)
-
-FEATURE_269 makes one local daemon the source of truth for a Coder profile.
-CLI, Space, IDE, and SDK clients can observe and control the same sessions and
-runs. The transport remains local to the current OS user; it is not a remote
-collaboration protocol. Closing a client detaches that client and does not stop
-the daemon or another client's run.
-
-Partner is deliberately outside this migration. Keep Partner on its existing
-inline callbacks and give it a distinct product data root and sessions root.
-Do not point a Partner inline Runtime at the Coder daemon profile or the Coder
-data root.
-
-### Connect and fail closed on required capabilities
-
-Space should own the daemon SDK client in Electron Main. Persist a random,
-stable `instanceId` and a separate 32+ character `instanceSecret` per Space
-installation. Store the secret in the OS keychain; never accept either value
-from renderer or model output. `connectKodaXRuntime()` is attach-only unless `autoStart: true`.
-An explicit inline rollback policy blocks auto-start until the owner policy is
-explicitly changed back to daemon.
-
-For Electron, `homeDir` is still the CLI-style base directory, not
-`process.env.KODAX_HOME`. Packaged/asar applications may use `autoStart: true`
-directly; the SDK launches only the daemon child in Electron's Node execution
-mode and does not mutate the application's environment or start a second GUI
-instance. `ELECTRON_RUN_AS_NODE` exists only at the child exec boundary and is
-removed before daemon application code loads, so Bash, MCP, LSP, sandboxed
-commands, and ordinary external processes do not inherit Electron Node mode.
-
-Packaged auto-start requires Electron's `RunAsNode` fuse, which Electron enables
-by default. If an embedder deliberately disables that fuse, the packaged
-executable cannot serve as a detached Node host: start the daemon with an
-ordinary Node/CLI process and use attach-only mode instead. A packaged
-`autoStart: true` timeout includes this fuse requirement in its diagnostic; the
-SDK does not relaunch the GUI or silently fall back to an inline Runtime.
-
-```ts
-import { connectKodaXRuntime } from '@kodax-ai/kodax/runtime';
-
-const runtime = await connectKodaXRuntime({
-  profile: 'coder',
-  autoStart: true,
-  homeDir: coderRuntimeBaseDir, // owns <coderRuntimeBaseDir>/.kodax
-  clientInfo: {
-    name: 'kodax-space',
-    version: '0.1.32',
-    instanceId: spaceInstallationId,
-    instanceSecret: await spaceKeychain.readRuntimeClientSecret(),
-  },
-  capabilities: {
-    richEvents: true,
-    permissionPrompts: true,
-    operationDeduplication: true,
-  },
-  requirements: {
-    operationDeduplication: 1,
-    sessionObservation: 1,
-    afterTurnInput: 1,
-    askUserTransport: 1,
-    permissionCas: 1,
-    providerCredentialBroker: 1,
-    runBoundHostTools: 1,
-    coderOwnerFencing: 1,
-    crashOutcomeModel: 1,
-    coderFeatureMatrix: 1,
-    sessionAdmission: 1,
-    completeObservationSnapshot: 1,
-    connectionLifecycle: 1,
-    typedRuntimeEvents: 1,
-    daemonSafeRunInput: 1,
-    sharedSessionSettings: 1,
-    durableRecoveryQueries: 1,
-    daemonManagement: 1,
-    runtimeAutoModeGuardrail: 3,
-  },
-});
-```
-
-Requirements are server facts, not authorization requests. Check
-`runtime.grantedScopes` before enabling controls. Missing capabilities or
-scopes must disable the affected UI; Space must not silently start inline
-Coder. FEATURE_269 does not advertise `interruptInput`, so an interrupt-only
-product must require `{ interruptInput: 1 }` and fail connection. The supported
-fallback is `delivery: 'after_turn'` only when that is the user's intent.
-
-The v0.7.73 SDK requires `runtimeAutoModeGuardrail:3` automatically for
-`autoStart: true`, even when the caller omits it from `requirements`. If the healthy
-profile daemon advertises v1 or v2, the SDK first requires `daemonManagement:1`,
-takes a revision/owner-policy fenced preflight, and replaces it only when no
-active or queued run, Workflow, Agent turn, pending permission/user input, or
-other logical client exists. A busy or still-older daemon is never stopped: the
-connection rejects with `RuntimeDaemonCapabilityUpgradeError`, whose
-`recoverable` and `restartRequired` fields are `true` and whose optional
-`preflight` explains the blockers. Attach-only connections never mutate daemon
-ownership and must request `runtimeAutoModeGuardrail:1` explicitly when they
-depend only on the v1 owner contract, v2 for bounded input, effective-default
-metadata, structured diagnostics, and speculative-window parity, or v3 for
-opaque exact grant suggestions and concrete permission matchers. Capability
-requirements are minimum versions: v3 satisfies v1/v2, v2 satisfies v1, and an
-older daemon never satisfies a newer requirement.
-
-The `coderFeatureMatrix` capability reports daemon availability for managed
-runs, transcript/session operations, Todo projection, managed tasks, Workflow,
-MCP, Reference External Agent, Memory, and Runtime artifacts. Reference
-External Agent is `false` when the daemon owner did not install its executor
-plane.
-
-The packaged daemon authenticates one local OS-user/profile trust domain with
-a random token stored beside daemon state and a user-only local endpoint. It
-does not issue a different daemon token to each application in v0.7.69. The
-returned scope set is chosen by the host (the packaged host grants the public
-local-user set). `clientInfo.instanceId` is stable attribution for origin and
-operation deduplication. `instanceSecret` proves that a new authenticated
-connection is the same stable client when it resumes that client's credential
-or Host Tool leases; only its hash participates in daemon-owned bridge state.
-Keep all three values in Electron Main. Mutually distrusting processes running
-as the same OS account remain outside this release's threat model.
-
-### Join atomically and resync after disconnect
-
-`sessions.observe()` installs the live subscription before taking the
-snapshot. Its snapshot contains one authoritative `runtimeId`, cursor,
-`transcriptRevision`, complete transcript, versioned settings, run/queue state,
-queued continuation IDs/order/origin/safe previews, pending permission and
-AskUser requests, and live assistant/thinking/tool/Todo/managed-task
-projection. Run requirements include the current credential/Host Tool
-availability. Listener events are strictly after the returned cursor.
-
-```ts
-let observedRuntimeId: string | undefined;
-let lastCursor = 0;
-
-async function openCoderSession(sessionId: string) {
-  const observation = await runtime.sessions.observe(sessionId, (event) => {
-    if (event.seq <= lastCursor) return;
-    applyRuntimeEvent(event);
-    lastCursor = event.seq;
-  });
-
-  const { snapshot } = observation;
-  const runtimeChanged = observedRuntimeId !== undefined
-    && observedRuntimeId !== snapshot.runtimeId;
-  observedRuntimeId = snapshot.runtimeId;
-  lastCursor = snapshot.cursor;
-  replaceSessionProjection(snapshot, { runtimeChanged });
-  return observation;
-}
-```
-
-Subscribe to `runtime.connection` to freeze mutation UI immediately rather
-than waiting for a status poll:
-
-```ts
-runtime.connection?.subscribe((state) => {
-  setCoderConnectionState(state.state, state.reason);
-  if (state.state === 'disconnected' && state.reconnectable) {
-    scheduleReconnect();
-  }
-});
-```
-
-The SDK reports the current `connectionId`, `runtimeEpoch`, optional
-`journalEpoch`, disconnect reason, and whether a new connection may be
-attempted. It does not transparently replay requests or subscriptions. Space
-creates a replacement Runtime client, checks its new epochs, resumes eligible
-leases, and observes the session again.
-
-On transport failure, Runtime change, expired history, or `resync_required`,
-discard the local derived projection and call `sessions.observe()` again. Do
-not merge a new snapshot into the old projection. The handshake buffer is
-bounded; overflow fails explicitly instead of dropping events. A Runtime
-restart changes `runtimeId`, marks persisted non-terminal runs with a durable
-terminal fact, and closes old in-memory AskUser/permission requests through the
-reset boundary.
-
-### Durable mutations, stable ordering, and settings CAS
-
-Every durable public control mutation uses an operation envelope. Credential
-and Host Tool register/revoke/supply/complete requests are reverse-bridge
-control frames and are deliberately excluded from the control journal so
-secrets/results are not persisted. They still enter the daemon management
-draining fence: once an atomic stop begins, they fail with typed `conflict` and
-cannot change reverse-bridge state. The SDK creates an operation ID for
-ordinary one-shot calls. A
-product-level retry after a lost response must reuse its own stable operation
-ID; changing its method, payload, resource, or authenticated principal is
-rejected.
-
-```ts
-const session = await runtime.sessions.create({
-  sessionId: stableSpaceSessionId,
-  title: 'Shared session',
-  surface: 'space-desktop',
-  operation: { operationId: loadOrCreatePendingOperationId('space-session-draft-7') },
-});
-
-const operationId = loadOrCreatePendingOperationId('space-run-draft-42');
-const handle = await runtime.runs.start({
-  sessionId: session.id,
-  input: { type: 'text', text: prompt },
-  options: { provider: 'anthropic' },
-  operation: { operationId },
-});
-
-const current = await runtime.sessions.getSettingsVersioned(session.id);
-const updated = await runtime.sessions.updateSettingsVersioned(
-  session.id,
-  { model: 'claude-sonnet-4-5' },
-  {
-    operationId: loadOrCreatePendingOperationId('space-settings-draft-9'),
-    expectedRevision: current.revision,
-  },
-);
-```
-
-Create retries with the same explicit session and operation IDs cannot overwrite
-an existing session. Same-session starts and after-turn inputs receive a durable `sessionOrder`.
-Retries with the same operation ID return the canonical result and do not
-create another run. Settings use compare-and-swap; a stale revision returns a
-structured conflict and must be reloaded, never silently overwritten. The
-shared settings keys are `provider`, `model`, `effort`, `thinking`,
-`reasoningMode`, `permissionMode`, `executionCwd`, `agentMode`, and
-`autoModeEngine`, `autoModeClassifierModel`, `autoModeTimeoutMs`, and
-`autoModeSpeculativeWindowMs`.
-
-```ts
-const queued = await runtime.runs.submitInput({
-  sessionId: session.id,
-  afterRunId: handle.runId,
-  delivery: 'after_turn',
-  input: { type: 'text', text: 'Also update the tests.' },
-  operation: { operationId: loadOrCreatePendingOperationId('space-input-17') },
-});
-
-if (!queued.accepted) {
-  // stale_run or unsupported_capability: show the factual result.
-}
-```
-
-Run status exposes acceptance/start/queue times, authenticated origin,
-`sessionOrder`, and a single terminal fact. Important terminal codes include
-`runtime_restarted`, `daemon_crashed`, `credential_unavailable`,
-`host_not_dispatched`, `host_outcome_unknown`, and
-`control_history_untrusted`. Respect `effectOutcome`; `unknown` must never be
-presented as success or automatically retried. After a lost response, query
-`runtime.operations.get({ operationId, journalEpoch })`; applied receipts
-include the canonical result. Permission grants remain daemon-owned and
-revisioned.
-
-### AskUser and permission from any client
-
-AskUser is no longer an in-process callback for daemon Coder runs. Any client
-with the responder scope can list the pending request and answer or dismiss it.
-The request revision and run binding prevent a stale UI from answering a new
-request. Exactly one concurrent answer is accepted.
-
-```ts
-for (const request of await runtime.userInputs.listPending({ sessionId })) {
-  const resolution = await runtime.userInputs.respond(request.id, answer, {
-    expectedRevision: request.revision,
-    runId: request.runId,
-  });
-  if (!resolution.accepted) refreshPendingInteractions();
-}
-
-for (const request of await runtime.permissions.listPending({ sessionId })) {
-  const sessionScope = request.grantSuggestions
-    ?.find((candidate) => candidate.kind === 'session');
-  const accepted = await runtime.permissions.respond(
-    request.id,
-    sessionScope
-      ? { type: 'allow_session', suggestionId: sessionScope.id }
-      : { type: 'allow_once' },
-    { runId: request.runId },
-  );
-  if (!accepted) refreshPendingInteractions();
-}
-```
-
-Persistent `allow_always` grants are owned by the daemon and require
-`permission:grant-admin`. Use `permissions.listGrants()` and
-`revokeGrant(grantId, expectedRevision)` for revision-safe administration.
-Clients must return one opaque `grantSuggestions[].id` from the pending request;
-they must not infer, construct, or widen a scope from the display label or input
-preview. A safe request can offer `allow_session` and `allow_always`; a risky or
-dynamic shell request deliberately omits the persistent candidate. Command
-grants match one exact normalized command/cwd/shell/background combination,
-while path grants match one tool and normalized absolute path (the future
-Write/Edit content may differ). Generic extension calls can receive only an
-exact in-memory Session grant. Raw command/argv data is not stored in the
-matcher; grants and audit contain only its fingerprint plus a bounded,
-secret-redacted operator label. Clients must not keep separate persistent
-permission rule stores. Runtime capability `runtimeAutoModeGuardrail` v3 advertises this
-opaque concrete-grant contract; restart or upgrade an older daemon instead of
-falling back to a client-side alias.
-
-### Broker a Space keychain credential
-
-Credentials remain owned by Space's OS keychain. Register a broker in Electron
-Main, bind the returned lease only to runs that Space starts, and return the
-key only after checking the daemon-provided provider/session/run context.
-
-```ts
-const credentialLease = await runtime.credentials.register(
-  { providers: ['anthropic'] },
-  async ({ provider, sessionId: requestedSession, runId }) => {
-    authorizeSpaceRunCredential({ provider, sessionId: requestedSession, runId });
-    return spaceKeychain.readProviderCredential(provider);
-  },
-);
-
-const run = await runtime.runs.start({
-  sessionId,
-  input: { type: 'text', text: prompt },
-  options: { provider: 'anthropic' },
-  credential: { leaseId: credentialLease.id, provider: 'anthropic' },
-  operation: { operationId: loadOrCreatePendingOperationId('space-run-88') },
-});
-```
-
-The secret crosses only the authenticated reverse frame and an in-memory
-run/provider scope. It is excluded from events, status, logs, diagnostics,
-operation records, and Runtime persistence. While such a scope is active,
-provider mismatch fails closed and never falls back to daemon environment.
-Without a stable `instanceSecret`, registration ends when the Space connection
-closes. With it, the daemon keeps the registration owned by that stable client;
-a replacement Space process reattaches the callback with
-`runtime.credentials.resume(leaseId, broker)`. An accepted run has already
-acquired its scoped credential, so it reports `requirements.credential.state`
-as `ready` and may continue after disconnect. If the broker cannot answer, the
-start is rejected instead of accepting an indefinitely waiting run. Expiry or
-Runtime restart is explicit (`expired` or terminal); no provider request is
-automatically replayed.
-
-### Bind Space-owned Host Tools to one run
-
-Register only narrow product capabilities. Descriptors are data; handlers stay
-in Electron Main. A lease grants nothing until its ID is explicitly bound to a
-run.
-
-```ts
-const hostLease = await runtime.hostTools.register([{
-  name: 'space_artifact_create',
-  description: 'Create a Space-owned artifact for this run.',
-  inputSchema: {
-    type: 'object',
-    properties: { title: { type: 'string' } },
-    required: ['title'],
-    additionalProperties: false,
-  },
-  sideEffect: 'non_idempotent',
-}], {
-  async space_artifact_create(invocation) {
-    authorizeBoundSpaceInvocation(invocation);
-    const artifact = await createSpaceArtifact(invocation.input);
-    return { content: `Created artifact ${artifact.displayId}` };
-  },
-});
-
-await runtime.runs.start({
-  sessionId,
-  input: { type: 'text', text: 'Create the report artifact.' },
-  hostTools: { leaseId: hostLease.id },
-  operation: { operationId: loadOrCreatePendingOperationId('space-artifact-run') },
-});
-```
-
-The daemon injects session/run/lease/invocation identity; renderer, model, and
-ordinary tool input cannot choose it. CLI runs never inherit a Space lease just
-because Space later observes their session. The client memoizes one handler
-promise per invocation ID, and the daemon never replays a dispatched Host Tool.
-After a stable-client reconnect, call
-`runtime.hostTools.resume(leaseId, handlers)`. Bound run status reports
-`ready`, `waiting_host`, `expired`, or `terminal`. Disconnect or timeout after dispatch produces `host_outcome_unknown`; Space
-must reconcile the product side effect itself before offering a new user
-action. `runtime.hostTools.getInvocation(invocationId)` returns the durable
-metadata state `prepared`, `dispatched`, `completed`, `unknown`, or
-`not_dispatched`; it never returns handler input, result, or credential data.
-The daemon writes the `dispatched` marker before attempting the reverse frame
-and never auto-replays an invocation.
-
-### Coder admission, typed events, and transport-safe inputs
-
-The daemon enforces Coder session admission on the server for list/create/load,
-run, settings, delete, rewind, fork, compact, transcript, event, interaction,
-and diagnostic paths. Coder
-surfaces are `code`, `cli`, `repl`, `acp`, `a2a`, `sdk`, `ide`, and
-`space-desktop`. A session marked with
-Partner surface/profile metadata, or any unknown product surface, fails with
-typed `session_not_admitted` before mutation. Space must continue marking
-Partner sessions as `surface: 'partner'` and keep their inline storage root
-separate. Legacy sessions without a surface remain admitted for existing Coder
-compatibility, so absence of metadata is not a Partner namespace mechanism.
-
-`RuntimeEventPayloadMap` and `RuntimeTypedEvent` provide the public
-discriminated contract for known events. Existing raw listeners remain
-compatible; consumers can use `parseRuntimeEvent(value)` before exhaustive
-handling. One unknown or malformed event is diagnosed and dropped without
-closing the observation stream.
-
-Daemon clients use `RuntimeDaemonStartRunInput`. Function callbacks,
-`AbortSignal`, Extension Runtime objects, and guardrail instances are excluded
-from that type and rejected at runtime with `RuntimeTransportBoundaryError`
-and an exact value path if an untyped caller supplies them. Host-only values
-remain valid only for embedded Runtime calls.
-
-### Recovery queries and stop preflight
-
-`runtime.status.preflight()` returns the initialized logical-client count,
-active and queued runs, running/paused Workflows, every non-terminal External
-Agent task (including `unknown`), pending AskUser/permission records, blockers,
-and `canStop`. The background-work blockers are `active_workflows` and
-`active_agent_tasks`. The current facade counts as one; daemon self-connections
-and bounded health probes do not count. A second process changes the count to
-two, and its awaited `close()` makes the count converge back to one.
-
-Preflight is useful for UI, but it is not a stop authorization token. Use
-`runtime.daemon.inspect()` to obtain one consistent management revision,
-verified owner fence, owner-policy revision, and preflight projection. Only
-`runtime.daemon.stopForInline()` atomically rechecks and commits a rollback.
-The management revision also advances when the preflight projection changes,
-so a Workflow or AgentTask lifecycle transition between inspect and commit
-invalidates the stale stop. Capability details
-`daemonManagement.backgroundWorkPreflight` and
-`daemonManagement.reverseBridgeDrainingFence` identify this complete contract.
-`runtime.operations.get()` reconciles durable mutations,
-`hostTools.getInvocation()` reconciles Host Tool metadata, and
-`permissions.listGrants()` returns the daemon-owned persistent grant set.
-
-Terminal notification read/unread state is intentionally client-owned in
-v0.7.69 (`durableRecoveryQueries.terminalAcknowledgement === false`): Space
-persists its own UI acknowledgement cursor against Runtime/run terminal facts.
-This avoids a false claim that one client's acknowledgement is global daemon
-truth.
-
-### Owner policy, rollback, and Electron boundary
-
-Daemon and inline Coder use one profile fence. Do not compose
-`status.preflight()` with a low-level unconditional stop: another client or run
-can appear between those calls. The public rollback transaction gates new
-clients and mutations, rechecks the same Runtime and management/policy
-revisions, verifies there is no other client or active/queued/pending work,
-commits sticky inline policy while that daemon still owns the fence, and then
-requests shutdown.
-
-```ts
-import {
-  acquireKodaXInlineOwner,
-  enableKodaXDaemonOwner,
-  getKodaXRuntimeOwnerState,
-} from '@kodax-ai/kodax/runtime';
-
-const management = await runtime.daemon.inspect();
-if (!management.preflight.canStop) {
-  showRollbackBlockers(management.preflight.blockers);
-  return;
-}
-
-const rollback = await runtime.daemon.stopForInline({
-  expectedRuntimeId: management.runtimeId,
-  expectedRevision: management.revision,
-  expectedOwnerPolicyRevision: management.ownerPolicy.revision,
-  operation: { operationId: loadOrCreatePendingOperationId('coder-inline-rollback') },
-});
-
-// `accepted` means inline policy is committed and shutdown is in progress.
-// Wait through the public owner-state query; never infer release from a PID.
-const shutdownDeadline = Date.now() + 30_000;
-while (getKodaXRuntimeOwnerState({ homeDir: kodaxHome, profile: 'coder' }).owner?.runtimeId
-  === rollback.runtimeId) {
-  if (Date.now() >= shutdownDeadline) throw new Error('Timed out waiting for daemon owner release.');
-  await delay(25);
-}
-const releasedOwner = getKodaXRuntimeOwnerState({ homeDir: kodaxHome, profile: 'coder' });
-if (releasedOwner.ownerStatus !== 'unowned') {
-  throw new Error('Coder profile acquired a different owner during rollback.');
-}
-await runtime.close(); // Detach only; it does not perform a second stop.
-const inlineOwner = acquireKodaXInlineOwner({ homeDir: kodaxHome, profile: 'coder' });
-
-// Later, after the inline owner has released its fence:
-inlineOwner.close();
-const daemonPolicy = enableKodaXDaemonOwner({ homeDir: kodaxHome, profile: 'coder' });
-// daemonPolicy.revision is authoritative; no expectedRevision guess is needed.
-```
-
-Any management revision change, another logical client, active or queued run,
-running/paused Workflow, non-terminal/unknown AgentTask, pending
-AskUser/permission, or in-flight mutation returns structured `conflict`; the
-daemon remains running and policy remains unchanged. Draining also rejects
-credential and Host Tool state changes without journaling their secrets or
-results. The inline policy is sticky: later CLI auto-start is rejected until
-`enableKodaXDaemonOwner()` changes it back to `daemon`. `runtime.close()` still
-only detaches. Stale-owner handling validates the owned lock/state and never
-kills a process merely because a PID was reused.
-
-Keep all trusted objects in Electron Main: daemon token/endpoint, stable client
-identity, operation IDs, owner policy, keychain broker, Host Tool handlers, and
-permission-grant administration. Renderer IPC should expose product-specific
-commands and sanitized projections only. Never pass daemon credentials,
-leases, operation epochs, or trusted session/run context to renderer or model
-tool arguments.
-
----
-
-## 24. Runtime-owned Auto Mode and plan-approval bridges (v0.7.72–v0.7.73)
-
-Auto Mode is a Runtime session contract, including in shared-daemon mode. Do
-not implement a second classifier or decide permissions from a client-side
-`beforeToolExecute` hook before the Runtime has classified the call.
-
-### Configure the session, not an individual UI callback
-
-```ts
-await runtime.sessions.updateSettings(session.id, {
-  permissionMode: 'auto',
-  autoModeEngine: 'llm',
-  autoModeClassifierModel: 'zhipu:glm-5.2', // optional; otherwise follow the run model
-  autoModeTimeoutMs: 20_000,                // positive safe integer, optional
-  autoModeSpeculativeWindowMs: 0,           // non-negative safe integer, optional
-  executionCwd: projectDirectory,
-});
-```
-
-All three Auto fields are durable session settings in inline, Worker, and
-daemon forms. A `null` patch removes an optional override. Timeout must be a
-positive safe integer; speculative window must be non-negative, so `0` is a
-valid request to wait for the actual verdict. Daemon capability discovery
-advertises all fields in `sharedSessionSettings.keys`.
-
-SDK hosts that need config precedence without creating a REPL can reuse the
-same typed resolver as KodaX:
-
-```ts
-import {
-  loadAutoModeSettings,
-  resolveAutoModeSettings,
-  type ResolveAutoModeSettingsInput,
-} from '@kodax-ai/kodax/repl';
-
-const persisted = loadAutoModeSettings(process.env);
-const preview = resolveAutoModeSettings({
-  settings: { engine: 'llm', speculativeWindowMs: 0 },
-  env: process.env,
-});
-```
-
-`resolveAutoModeSettings()` is pure. `loadAutoModeSettings()` reads the KodaX
-config once and delegates to that resolver; `loadConfig()` declares and
-returns the same optional `autoMode` object.
-
-Starting with the v0.7.73 patch, `permissionMode: 'auto'` with an omitted
-`autoModeEngine` still means the documented `llm` default and is still owned by
-Runtime. If neither `autoModeClassifierModel` nor the effective run/session/
-Runtime model exists, `runs.start()` rejects with
-`RuntimeAutoModeConfigurationError` (`code:
-'auto_mode_classifier_model_required'`, `recoverable: true`) before provider
-construction, a classifier call, or a pending permission. Blank and malformed
-classifier model specs are rejected by the same typed configuration boundary;
-a live rules-to-LLM switch is blocked rather than converted into approval work.
-
-Direct consumers of `createAutoModeToolGuardrail()` receive the same terminal
-model boundary. After resolving CLI/env/session/settings/live-default
-precedence, an empty effective model returns a local configuration `block`
-before provider lookup. It does not call `askUser`, mutate the denial or
-circuit-breaker trackers, or change the engine to rules. An explicit non-empty
-classifier override remains valid even when the main-session model is empty.
-
-The Runtime owns one serialized permission-settings stream and one shared
-engine/denial/breaker state per Session. It reuses bounded context-specific
-guardrails across turns while provider/model, repository boundary, execution
-directory, classifier model, and timeout remain the same. Updating one of
-those inputs selects a new context guardrail by design without copying stale
-state from a queued turn. Active runs, queued runs, explicit settings updates,
-and automatic LLM-to-rules fallback merge through the same Session mutation
-queue; fallback is persisted before a later classification reads the engine.
-
-### What an embedder should expect
-
-The Runtime's execution order is fixed:
-
-```text
-Runtime Auto Mode guardrail -> host permission bridge only for escalate -> tool execution
-```
-
-Consequently, an LLM/rules `allow` does not create a pending permission request
-just because a host installed a static approval hook. `block` does not become a
-spurious approval prompt. A real `escalate` uses the existing shared
-`runtime.permissions` flow, so another authorized client may render and answer
-it. Hosts should subscribe to permission events to display such a request, but
-must not treat a missing request as an error for a safe tool call.
-
-The classifier deadline remains 20 seconds by default and includes connection
-setup, provider Retry-After/backoff, inference, and stream completion. KodaX
-does not solve timeouts by extending that deadline indefinitely. Before the
-provider call it removes assistant prose/thinking and image paths, limits each
-tool result to 2 KiB and the serialized permission-relevant transcript to
-8 KiB, then enforces 16 KiB action and 32 KiB total-prompt ceilings plus a
-256-token output cap. An oversized action or prompt escalates without a
-provider call; it is never truncated into an automatic allow. These limits are
-owned by `classify()` itself, so custom callers cannot accidentally bypass the
-session-history boundary.
-
-`ClassifyDecision.diagnostics` and the lower-level
-`SideQueryResult.diagnostics` expose provider, model, effective timeout,
-elapsed time, retry count/wait, and a coarse terminal phase without including
-the prompt, action, messages, or response text. `pre_output` means no non-empty
-text delta was observed; `streaming` means output began before termination.
-`firstOutputMs` and `streamMs` are present only when the provider adapter emits
-a text delta. The current provider API cannot honestly separate DNS/connect,
-TLS, provider queueing, and inference, so embedders must not infer those stages
-from `pre_output`.
-
-The permission event's `inputPreview` is a display-safe diagnostic projection:
-it is bounded, credential-redacted, valid JSON, and includes the effective
-execution directory. Use the Runtime owner’s typed tool input for execution;
-do not reconstruct or authorize a tool from the preview. `gitRoot` remains the
-session repository safety boundary, whereas relative operands resolve from the
-validated `executionCwd`. In particular, quoted Python/JavaScript/regexp source
-inside a shell command is not a path operand.
-
-The user-level `.kodax` directory is a credential/configuration boundary, not
-an ordinary project path. Direct shell mutations, output redirects, and
-recognized nested-shell payloads whose target is provably beneath that
-directory are rejected before LLM classification. The check is segment-safe
-and Windows case-insensitive. KodaX deliberately does not scan arbitrary
-quoted language source for path-looking substrings: doing so would turn Python,
-JavaScript, YAML, and regular expressions into false Tier-0 matches. Trusted
-configuration changes should use the KodaX config CLI or SDK configuration API.
-
-### 0.7.x source compatibility
-
-The v0.7.72 public declarations retain the following migration aliases:
-
-| Legacy source | Current source | Contract |
-|---|---|---|
-| `agentMode: 'amaw'` | `'ama'` | accepted as deprecated input and normalized to AMA; no separate AMAW runtime is restored |
-| `SkillSource` | `ResolvedSkillSource` | formal source union remains `project \| user \| plugin \| builtin`; only resolved discovery output adds `learned` |
-| `RuntimeDaemonPreflight.activeAgentTasks` | `activeAgentTurns` | both required fields are returned and reference the same array throughout the 0.7.x line |
-
-### Plan capability is opt-in
-
-`exit_plan_mode` is exposed to a Runtime run only when that run supplies an
-approval bridge. A daemon or headless host that cannot approve a plan should
-leave the bridge absent; KodaX removes the tool from that run's scope.
-
-```ts
-const planned = await runtime.runs.start({
-  sessionId: session.id,
-  prompt: 'Draft a migration plan, then ask for approval.',
-  options: {
-    events: {
-      exitPlanMode: async () => showPlanAndAskUser(),
-    },
-  },
-});
-await planned.result;
-```
+The portable manual gates remain in
+`docs/test-guides/FEATURE_255_v0.7.66_TEST_GUIDE.md`,
+`FEATURE_256_v0.7.71_TEST_GUIDE.md`, and
+`FEATURE_257_v0.7.72_TEST_GUIDE.md` for release-machine verification; the latter
+two filenames retain their original planning slots while their content records
+the v0.7.66 delivery. v0.7.67 adds
+`FEATURE_258_v0.7.67_TEST_GUIDE.md`, `FEATURE_259_v0.7.67_TEST_GUIDE.md`, and
+`FEATURE_261_v0.7.67_TEST_GUIDE.md`; v0.7.69 adds
+`FEATURE_267_v0.7.69_TEST_GUIDE.md`, `FEATURE_268_v0.7.69_TEST_GUIDE.md`, and
+`FEATURE_269_v0.7.69_TEST_GUIDE.md`. The earlier release-preparation Actions
+run is not reused after the severe-fix review. Fresh GitHub Actions run
+`29385073422` passes the Node 20/22 build, bundle, DTS, and full-test matrix plus
+the Node 22 Unix-domain-socket daemon gate. npm publication remains a
+maintainer-owned manual step.
+
+---
+
+## 18. External-agent executor plane (FEATURE_258, v0.7.67)
+
+FEATURE_258 lets an SDK host register remote agents without teaching the coding
+runtime a specific A2A, MCP, or HTTP client. The public contracts live in
+`@kodax-ai/kodax/agent`; the host-facing catalog and task services live on
+`@kodax-ai/kodax/runtime`.
+
+### Ownership rule
+
+An `AgentExecutorFactory` contains functions, so it cannot cross a Worker or
+daemon DTO boundary. Install factories where the Runtime owner executes:
+
+| Desired owner | Supported construction |
+|---|---|
+| Private in-process owner | `createKodaXRuntime({ mode: 'embedded', isolation: 'inline', externalAgents })` |
+| New locally hosted daemon owner | `createKodaXRuntime({ mode: 'daemon', profile: '<unique>', externalAgents })` |
+| Existing daemon | Configure its owner, then attach with `connectKodaXRuntime({ requirements: { externalAgents: true } })`; a client cannot inject factories. |
+| Runtime Worker | The Worker owner must install factories itself; passing `externalAgents` from the parent is rejected. |
+
+When `mode: 'daemon'` and `externalAgents` are supplied, the caller must win a
+new in-process daemon lease. KodaX rejects an already-running profile instead of
+silently replacing its executor configuration. Closing that owner facade shuts
+down the host it created; closing an ordinary attached client only detaches.
+
+### Minimal owner and task flow
+
+The reference executor below is a contract/conformance adapter. Replace it with
+your own `AgentExecutorFactory` for a real remote protocol.
+
+```ts
+import {
+  createReferenceAgentExecutorFactory,
+  type ExternalAgentRegistration,
+} from '@kodax-ai/kodax/agent';
+import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';
+
+const runtime = await createKodaXRuntime({
+  mode: 'embedded',
+  isolation: 'inline',
+  externalAgents: {
+    factories: [createReferenceAgentExecutorFactory({
+      executorId: 'example-http',
+      protocol: 'http',
+    })],
+    policy: ({ registration, query }) => ({
+      allowed: registration.enabled && query.readOnly === true,
+      reasons: query.readOnly === true ? [] : ['This host allows read-only dispatch only.'],
+    }),
+    defaultContext: { actorId: 'desktop-host' },
+  },
+});
+
+const registration: ExternalAgentRegistration = {
+  agentId: 'external:reviewer',
+  displayName: 'Remote Reviewer',
+  enabled: true,
+  executorId: 'example-http',
+  protocol: 'http',
+  configurationRevision: 'reviewer-config-v1',
+  endpointIdentityHash: 'sha256:replace-with-stable-endpoint-identity',
+  skills: ['code-review'],
+  inputModalities: ['text'],
+  outputModalities: ['text'],
+  capabilities: {
+    streaming: 'supported',
+    durableTasks: 'supported',
+    inputRequired: 'conditional',
+    cancellation: 'supported',
+    artifacts: 'unsupported',
+  },
+  effects: { remote: 'read', workspace: 'proposal' },
+  maxConcurrency: 1,
+};
+
+try {
+  await runtime.admin.agentRegistrations.upsert(registration);
+
+  const query = {
+    actorId: 'desktop-host',
+    requiredSkills: ['code-review'],
+    readOnly: true,
+  } as const;
+  const available = await runtime.agents.listDispatchable(query);
+  const preflight = await runtime.agents.preflight({
+    agentId: 'external:reviewer',
+    query,
+    expectedConfigurationRevision: registration.configurationRevision,
+  });
+  if (!preflight.ok) throw new Error(preflight.reasons.join('; '));
+
+  const started = await runtime.agentTasks.start({
+    agentId: 'external:reviewer',
+    objective: 'Review the supplied immutable patch and return cited findings.',
+    context: { actorId: 'desktop-host', runId: 'host-run-42' },
+    readOnly: true,
+    requiredSkills: ['code-review'],
+    expectedConfigurationRevision: registration.configurationRevision,
+  });
+  const terminal = await runtime.agentTasks.wait(started.taskId, 60_000);
+  console.log(available, terminal.state, terminal.output, terminal.usage);
+} finally {
+  await runtime.close();
+}
+```
+
+`runtime.agents.enabled` is the cheap external-plane feature check. If it is
+false, catalog queries can still return built-in local agents but no external
+agents; registration and task lists are empty, while point reads and mutations
+fail clearly. Set
+`requirements.externalAgents: true` when absence must abort connection.
+
+### Service reference
+
+| Surface | Methods | Contract |
+|---|---|---|
+| `runtime.admin.agentRegistrations` | `list`, `upsert`, `setEnabled`, `remove` | Durable owner configuration. `setEnabled` preserves the complete captured executor registration while changing admission. Mutations accept both `expectedConfigurationRevision` and `expectedManagementOwner`; `setEnabled` can also atomically `claimOwner` on an unowned registration and rejects another owner. List results expose `managementOwner` and `credentialConfigured`, never a credential value. The same contract is carried across the daemon transport. With no plane, `list()` is empty and mutations fail clearly. |
+| `runtime.agents` | `enabled`, `listDispatchable`, `describe`, `preflight` | Applies health, capability, effect, concurrency, credential-presence, configuration-revision, and host-policy checks before dispatch. |
+| `runtime.agentTasks` | `start`, `list`, `get`, `events`, `wait`, `sendInput`, `cancel`, `reconcile` | Durable snapshots and append-only events for external tasks. The task keeps the immutable registration/executor binding captured at start. |
+
+`agentTasks.events(taskId, cursor)` uses the last seen numeric event `seq` as its
+cursor and returns events with a greater sequence. `wait()` resolves only at a
+terminal task state and rejects on a positive `timeoutMs` expiry. `sendInput()`
+is valid only while the task reports `input-required` or `auth-required`.
+`reconcile()` asks the bound executor for authoritative remote state after an
+owner restart or uncertain failure.
+
+For external tasks, the built-in stores persist an internal full registration
+snapshot before the public task ledger. It is keyed by Agent ID and revision,
+is never returned by task or daemon APIs, and lets an admitted task keep using
+its original executor route after registration update/removal and Runtime
+restart. The internal form fixes `enabled: true` and omits management ownership
+and health diagnostics. The task's public route summary is validated against that internal
+snapshot before recovery. Terminal task state is durable before the last
+unreferenced snapshot is removed; startup cleans crash-window orphans.
+
+Custom `AgentExecutorPlaneStore` implementations should implement
+`loadTaskRegistrationSnapshots()` and `saveTaskRegistrationSnapshots()` as a
+pair and give one Runtime exclusive write ownership of that store. Omitting
+both remains compatible, but restart recovery then succeeds only while the
+exact current registration still exists. Store only non-secret executor config
+or secret references in `executorConfig`/`credentialRef`; the broker resolves
+the current referenced credential just in time, so removing a registration is
+not equivalent to revoking that credential at its issuer.
+
+The owner plane has a terminal close contract. Closing it rejects every pending
+`wait()` (including a wait without `timeoutMs`), disposes its executor instances,
+and makes subsequent registration, catalog, preflight, and task calls reject
+with `Agent executor plane is closed.` One overall deadline covers admitted
+work plus executor disposal: the default is 30 seconds, and direct
+`createAgentExecutorPlane()` hosts may supply a positive finite
+`closeTimeoutMs`. A timeout rejects visibly even though already-admitted cleanup
+may finish in the background. Repeated `close()` calls are safe. SDK hosts
+should stop accepting work before closing the owner and must not retain a plane
+service as a reusable handle after Runtime shutdown.
+
+Restricted Workflow scripts use the same route as direct SDK calls. Both
+`wf.spawnAgent()` and `wf.runAgent()` validate and forward
+`target: { agentId, expectedConfigurationRevision? }`; `phase` is forwarded as
+well. A blank ID or revision is rejected at the script boundary instead of
+silently falling back to the native child backend.
+
+### Credential, artifact, and failure boundaries
+
+- Put only a `credentialRef` in a registration. Resolve secret material through
+  `AgentCredentialBroker.withCredential()`; do not place tokens in
+  `executorConfig`, events, diagnostics, or task output.
+- Remote artifacts are denied by default. Supply `artifactPolicy` to authorize
+  each artifact before it materializes in the host boundary.
+- External agents may declare workspace effect `none` or `proposal`; direct
+  workspace mutation is intentionally not a valid external registration.
+- Use `expectedConfigurationRevision` for dispatch. For registration mutations,
+  compare both it and `expectedManagementOwner` so a same-revision ownership
+  change cannot be overwritten from an earlier catalog read. Config managers
+  should set a stable `managementOwner`; they may atomically claim an unowned
+  legacy registration while disabling it, but must not mutate a registration
+  owned by another manager.
+- Treat `configurationRevision` as the stable identity of immutable execution
+  content, not as a small counter. The same content may deterministically reuse
+  the same revision across remove/re-add or Runtime restart, but different
+  endpoint, protocol, executor/auth config, capabilities, effects, Skills,
+  modalities, or resource limits must never reuse it. Built-in A2A
+  configuration derives it from content.
+- A remote start followed by uncertain local persistence is recorded as
+  `unknown` with its executor reference preserved; reconcile it rather than
+  blindly starting a duplicate. Stable idempotency keys protect retries.
+- The durable plane records provider-reported usage when available. It never
+  invents missing token or cost fields.
+
+For a production adapter, implement `preflight?`, `start`, `events`, `get`,
+`sendInput`, `cancel`, `reconcile`, and `dispose` on `AgentExecutor`. The factory
+receives `withCredential()` and `authorizeArtifact()` callbacks so protocol code
+cannot bypass the host's secret/artifact policies.
+
+---
+
+## 19. Session surface filtering and cursor pagination (FEATURE_261, v0.7.67)
+
+The narrow session SDK and Runtime facade now share the same listing semantics:
+`surface` is an exact filter applied before `limit`, and `cursor` is an opaque
+continuation token carried by each returned summary.
+
+### Narrow `/session` API
+
+```ts
+import { listSessions, type SessionSummary } from '@kodax-ai/kodax/session';
+
+const all: SessionSummary[] = [];
+let cursor: string | undefined;
+do {
+  const page = await listSessions({
+    scope: 'user',
+    surface: 'partner',
+    limit: 50,
+    ...(cursor ? { cursor } : {}),
+  });
+  all.push(...page);
+  cursor = page.length === 50 ? page.at(-1)?.cursor : undefined;
+} while (cursor);
+```
+
+### Embedded/daemon Runtime API
+
+```ts
+const first = await runtime.sessions.list({ surface: 'acp', limit: 25 });
+const nextCursor = first.at(-1)?.cursor;
+const second = nextCursor
+  ? await runtime.sessions.list({ surface: 'acp', limit: 25, cursor: nextCursor })
+  : [];
+```
+
+The filter also composes with `projectRoot`, `scope`, `includeArchived`, `before`,
+and `tag`. Treat cursors as opaque: do not parse them, compare them to session
+IDs, or manufacture them. An invalid cursor produces an empty page on the narrow
+session API. A page shorter than the requested limit is terminal; a full page
+may continue with its last item's cursor.
+
+The interactive `kodax -r` picker is a consumer of these session semantics, not
+a separate SDK API. Headless hosts should build their own UI on `listSessions()`
+or `runtime.sessions.list()` and resume by the selected full session ID.
+
+---
+
+## 20. Cost-disciplined workflow routing and telemetry (FEATURE_259, v0.7.67)
+
+FEATURE_259 adds a public cost/quality contract without making the authoring LLM
+choose provider-specific model names. The SDK host maps semantic tiers to routes;
+workflow/child briefs request intent.
+
+### Configure tiers and bounded concurrency
+
+```ts
+import { join } from 'node:path';
+import { runKodaX } from '@kodax-ai/kodax/coding';
+
+const workflowRunsBaseDir = join(process.cwd(), '.kodax-host', 'workflow-runs');
+const result = await runKodaX({
+  provider: 'zai-coding',
+  model: 'glm-5.2',
+  agentMode: 'amaw',
+  workflowRunsBaseDir,
+  modelTiers: {
+    fast: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+    deep: { provider: 'zai-coding', model: 'glm-5.2' },
+  },
+  workflow: { maxConcurrency: 3 },
+  events: {
+    onWorkflowAgentDigest: ({ runId, event }) => {
+      if (event.type === 'agent_completed' || event.type === 'agent_unverified'
+        || event.type === 'agent_failed') {
+        console.log(runId, event.data);
+      }
+    },
+  },
+}, 'Review this change using scoped evidence packets.');
+
+console.log(result.lastText);
+```
+
+Tier rules are deliberately small:
+
+- `fast`: mechanical read-only lookup. A write child is ineligible and safely
+  inherits the parent route.
+- `balanced`: ordinary implementation/investigation/review; uses the parent
+  route, so there is no separate `balanced` mapping.
+- `deep`: architecture, adversarial verification, severity calibration, and
+  final synthesis.
+- An unconfigured or selector-shadowed tier inherits the appropriate explicit,
+  specialist, or parent route and records why; it does not silently claim the
+  requested route was applied.
+
+The workflow authoring contract also supports `scopeSummary`, `constraints`,
+`evidenceRefs`, `verification`, `readOnly`, `outputSchema`, and `terseResult`.
+Use those fields to transfer a compact immutable packet instead of asking every
+child to rediscover the same repository context.
+
+### Live route facts
+
+Terminal `WorkflowEvent.data` may include `requestedTier`, `tierOutcome`,
+`providerSource`, `modelSource`, initial/final provider and model,
+`fallbackReason`, `iterations`, `durationMs`, `usage`, and `digestUsage`.
+Treat absent fields as unknown. In particular, KodaX does not fabricate usage
+for external executors that did not report it.
+
+Direct child-dispatch consumers receive the typed `KodaXChildAgentResult.routeFacts`
+surface, including resolved effort and input/cache-read/output/digest token
+breakdown when known. Inline workflow consumers can subscribe to the raw
+`onWorkflowAgentDigest` event as above; GUI progress remains available through
+`onWorkflowProcessEvent` / `runtime.workflows`.
+
+### Durable efficiency report
+
+When `workflowRunsBaseDir` is supplied, every terminal workflow writes:
+
+```text
+<workflowRunsBaseDir>/<runId>/run.json
+<workflowRunsBaseDir>/<runId>/events.jsonl
+<workflowRunsBaseDir>/<runId>/artifacts/*.json
+```
+
+`run.json.efficiencyReport` includes:
+
+- total/input/cache-read/output/digest tokens and wall-clock duration;
+- total starts, child turns, starts by `role/tier`, and primary-review starts;
+- duplicate primary packet reads plus verification/synthesis packet reads;
+- review/fix/re-review waves and structured review quality-gate outcomes;
+- `tokenCoverage.ok` plus missing local task IDs;
+- `excludedExternalTaskIds` for external tasks whose executor reported no usage.
+
+Do not interpret `totalModelTokens: 0` as free execution unless
+`tokenCoverage.ok` is true and the relevant external task IDs are not excluded.
+The report is an audit/optimization artifact; correctness still comes from the
+workflow's structured findings, verification results, and quality gates.
+
+---
+
+## 21. Experimental governed memory — `/experimental-memory` (FEATURE_260, v0.7.68)
+
+KodaX has one durable memory plane: the F228 Memory Control Plane. FEATURE_260
+adds a thin, opt-in agent/session API over that plane; it does not add a second
+database, filesystem memory actions, a resident memory specialist, or online
+self-modification.
+
+Top-level `runKodaX()` coding runs wire this lifecycle automatically. They build
+an exact-scoped memory pack at session start, keep passive recall off the
+blocking hot path, expose `memory_recall` only when the memory session starts,
+record bounded observations/outcomes, and close the session at the run boundary.
+Use the direct SDK below when a custom host needs to own those boundaries.
+
+### Minimal direct session
+
+```ts
+import { createMemoryControlPlane } from '@kodax-ai/kodax/agent';
+import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory';
+
+const identity = {
+  tenantId: 'tenant:acme',
+  workspaceId: 'workspace:desktop',
+  userId: 'user:42',
+  agentId: 'agent:reviewer',
+  projectId: 'project:kodax',
+  sessionId: 'session:20260712',
+};
+
+const controlPlane = createMemoryControlPlane({
+  cwd: process.cwd(),
+  identity,
+  projectDocs: [],
+  discoverSkills: false,
+});
+const memory = createMemoryAgent({ controlPlane });
+const session = await memory.startSession({
+  identity,
+  objective: 'Review the runtime shutdown change',
+});
+
+const immediate = session.recall({
+  decisionRevision: 'decision:1',
+  objective: 'Review the runtime shutdown change',
+  decisionContext: 'Choosing the first verification step',
+  decisionIntent: 'runtime shutdown regression',
+  throughSequence: 0,
+});
+const deliberate = await session.query({
+  decisionRevision: 'decision:2',
+  need: 'What uncommon daemon cleanup failure happened before?',
+  throughSequence: 0,
+});
+
+await session.complete({
+  status: 'succeeded',
+  summary: 'Shutdown state replacement verified',
+  evidence: [],
+});
+await session.close();
+```
+
+`recall()` is synchronous: exact observations/hints can be returned immediately,
+while an optional semantic prefetch finishes for a later matching decision.
+`query()` is deliberate and read-only; one distinct query is admitted per
+decision epoch, and the result is bounded to at most three prompt-safe hints and
+512 estimated tokens. `undefined` means there is no governed reminder to inject.
+
+### Evidence, tracing, and persistence boundaries
+
+- Recalled content is low-authority evidence. Current repository/config/runtime
+  facts must still come from current tools or host state.
+- `observe()` accepts monotonic, evidence-linked observations and rejects secret
+  material. `rewind()` removes observations after a sequence boundary.
+- `complete()` can emit an Outcome Digest through `persistOutcomeDigest` and run
+  bounded episode review through `reviewEpisode`; cancellation creates neither.
+- `onTrace` receives policy-versioned `MemoryDecisionReceipt` metadata that links
+  candidates, selection, injection, and later outcome influence. Receipts are
+  trace-only and contain no hidden reasoning.
+- Durable memory mutation remains owned by F228's
+  proposal/preview/fingerprint/apply flow. `/memory` is the CLI governance
+  surface; direct file/shell writes to managed memory roots are denied.
+- Identity/applicability matching is exact and fail-closed. Hosts should supply
+  stable tenant/workspace/user/agent/project/session identifiers and must not put
+  credentials into those identifiers.
+
+The subpath is experimental and ESM-only. Treat its exported types as opt-in
+v0.7.x contracts; keep persistence and product policy behind your own adapter.
+
+---
+
+## 22. Bidirectional A2A 1.0 — `/a2a` (FEATURE_267, v0.7.69)
+
+`@kodax-ai/kodax/a2a` is the protocol edge for the A2A 1.0 JSON-RPC/SSE
+profile. It composes the protocol-neutral F258 executor plane with the Runtime
+facade; `/agent` and `/coding` remain free of A2A wire types and dependencies.
+
+### Call an A2A Agent through F258
+
+Discovery is an explicit host action. The URL must match `allowedOrigins`, and
+the default safe transport pins the validated DNS address for each connection
+and independently revalidates redirects, rejects public plain HTTP, bounds
+time/body/redirects, and strips authorization on a cross-origin redirect. A
+custom `fetch` option is a trusted transport override: the embedder then owns
+equivalent DNS-to-connection binding in that transport or proxy.
+
+The selected interface must remain on the Card's trusted origin. KodaX parses
+typed Card-level and Skill-level security declarations: requirement objects are
+alternatives (OR), every scheme inside one object is conjunctive (AND), and an
+empty requirement is anonymous. A configured credential is used only when one
+complete requirement is satisfiable; protected Skills that the configured
+profile cannot satisfy are not advertised to the Runtime catalog.
+
+The built-in profiles are HTTP Bearer and OAuth 2.0 Client Credentials. The
+OAuth profile pins the Card scheme, issuer, exact token endpoint, client ID,
+secret reference, scopes, optional RFC 8707 resource, and client authentication
+method. The external Authorization Server—not the Agent and not KodaX—issues
+the access token. KodaX resolves the client secret only for refresh, keeps an
+expiring token in process memory, coalesces refreshes, and retries one RPC once
+with a fresh token after `401`. Card, Agent RPC, and token endpoints remain
+separate safe-fetch trust boundaries, so a remote Agent cannot redirect a task
+payload to the token origin. API key, Basic, interactive OAuth, OIDC, mTLS, and
+multi-scheme AND requirements fail explicitly in the built-in client.
+
+```ts
+import {
+  createA2AAgentExecutorFactory,
+  discoverA2ARegistration,
+} from '@kodax-ai/kodax/a2a';
+import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';
+
+const client = {
+  networkPolicy: {
+    // Card/RPC and OAuth token endpoints are separate trust boundaries.
+    allowedOrigins: ['https://reviewer.example', 'https://identity.example'],
+    allowPrivateAddresses: false,
+    requestTimeoutMs: 10_000,
+    maxResponseBytes: 1_048_576,
+    maxRedirects: 2,
+  },
+  pollIntervalMs: 500,
+} as const;
+
+const discovered = await discoverA2ARegistration({
+  agentId: 'external:a2a-reviewer',
+  agentCardUrl: 'https://reviewer.example/.well-known/agent-card.json',
+  credentialRef: 'a2a/reviewer',
+  effects: { remote: 'read' },
+}, client);
+
+const runtime = await createKodaXRuntime({
+  mode: 'embedded',
+  isolation: 'inline',
+  externalAgents: {
+    factories: [createA2AAgentExecutorFactory(client)],
+    credentialBroker: {
+      async withCredential(ref, use) {
+        const value = ref === 'a2a/reviewer'
+          ? process.env.A2A_REVIEWER_TOKEN
+          : ref === 'a2a/reviewer-client-secret'
+            ? process.env.A2A_REVIEWER_CLIENT_SECRET
+            : undefined;
+        if (!value) throw new Error(`Missing credential for reference: ${ref}.`);
+        return use(value);
+      },
+    },
+    policy: ({ registration }) => ({ allowed: registration.effects.remote === 'read' }),
+    defaultContext: { actorId: 'a2a-host' },
+  },
+});
+
+await runtime.admin.agentRegistrations.upsert(discovered.registration);
+const started = await runtime.agentTasks.start({
+  agentId: discovered.registration.agentId,
+  objective: 'Review this change and return cited findings.',
+  context: { actorId: 'a2a-host' },
+  readOnly: true,
+  expectedConfigurationRevision: discovered.registration.configurationRevision,
+});
+const terminal = await runtime.agentTasks.wait(started.taskId, 60_000);
+```
+
+For OAuth, replace the legacy `credentialRef` input with the structured form;
+the same F258 `credentialBroker` must resolve `clientSecretRef`. The shared
+network policy must admit both origins, while each Card, RPC, and token request
+is still narrowed to its own exact origin:
+
+```ts
+const discovered = await discoverA2ARegistration({
+  agentId: 'external:a2a-reviewer',
+  agentCardUrl: 'https://reviewer.example/.well-known/agent-card.json',
+  authentication: {
+    type: 'oauth2-client-credentials',
+    scheme: 'enterprise-oauth',
+    issuer: 'https://identity.example/',
+    tokenUrl: 'https://identity.example/oauth/token',
+    clientId: 'kodax-reviewer',
+    clientSecretRef: 'a2a/reviewer-client-secret',
+    scopes: ['a2a.invoke'],
+    resource: 'https://reviewer.example/',
+    clientAuthentication: 'client-secret-basic',
+  },
+  effects: { remote: 'read' },
+}, client);
+```
+
+The executor supports durable task start/get, input continuation, cancel,
+reconcile, SSE events, and polling fallback. An ambiguous start is not retried
+automatically. A `credentialRef` is resolved just in time by the F258 broker;
+the registration, task store, and diagnostics never contain the credential.
+Authenticated SSE uses that same broker. JSON-RPC ID/version and task/context
+correlation are validated before an event is accepted; if a stream ends
+normally before a terminal snapshot, the executor resumes bounded polling.
+Streamed `artifactUpdate` chunks are accumulated by artifact ID according to
+`append`, and direct Message file Parts are preserved as authorized artifact
+references.
+
+### Built-in configured path (no host code)
+
+The CLI product path stores one user document at
+`~/.kodax/integrations/a2a.json` and uses the same F258 plane:
+
+```bash
+kodax a2a add reviewer https://reviewer.example/.well-known/agent-card.json \
+  --credential-env A2A_REVIEWER_TOKEN --effect read
+kodax a2a test reviewer
+kodax a2a call reviewer "Review this document"
+```
+
+The no-code OAuth path stores only the environment-variable name for the client
+secret. It can be staged disabled and hot-activated later:
+
+```bash
+export A2A_REVIEWER_CLIENT_SECRET='provisioned-out-of-band'
+# PowerShell: $env:A2A_REVIEWER_CLIENT_SECRET='provisioned-out-of-band'
+# PowerShell: use one line or replace each trailing \ with a backtick.
+kodax a2a add reviewer https://reviewer.example/.well-known/agent-card.json \
+  --disabled --effect read --oauth-scheme enterprise-oauth \
+  --oauth-issuer https://identity.example/ \
+  --oauth-token-url https://identity.example/oauth/token \
+  --oauth-client-id kodax-reviewer \
+  --oauth-client-secret-env A2A_REVIEWER_CLIENT_SECRET \
+  --oauth-scope a2a.invoke --oauth-resource https://reviewer.example/
+kodax a2a enable reviewer
+kodax a2a disable reviewer
+```
+
+Embedded CLI Runtimes and the user-owned daemon automatically reconcile these
+entries as `external:<name>`. Discovery/update failure retains that entry's
+last-known-good registration; another entry can still update. The environment
+broker resolves `credentialEnv` only at call time. Automatic Runtime
+registration accepts public HTTPS and exact loopback targets; explicit private
+network access remains an operator action on the direct CLI/SDK path.
+
+`enabled` is desired state in `a2a.json`, not a fabricated cross-process live
+flag. `a2a list` reports configured entries and that desired state. The owning
+Runtime's `admin.agentRegistrations.list()` is authoritative for applied
+registrations. Automatic reconciliation handles disables/removals first,
+skips unchanged peers, performs no Card or token request for disabled entries,
+and rediscovers before re-enable. Once the owning Runtime observes and applies
+the revision, disable blocks all new starts, including an explicit
+`external:<name>` target, but does not cancel or break an already admitted task.
+The CLI mutation returning is not cross-process acknowledgement. A failed
+activation remains retryable through the owning
+`ConfiguredA2ARuntimeHandle.reload()` even when the disk revision is unchanged;
+the passive `kodax integrations reload` command validates only its own process.
+
+`kodax a2a test` performs Card discovery and security planning only. It never
+requests an OAuth access token; token acquisition starts at `a2a call` or the
+first Runtime dispatch.
+
+Inbound publication is also no-code:
+
+```bash
+export KODAX_A2A_TOKEN='replace-with-a-long-random-token'
+# PowerShell: $env:KODAX_A2A_TOKEN='replace-with-a-long-random-token'
+kodax a2a expose                    # Runtime default Agent
+kodax a2a expose document-agent     # ~/.kodax/agents/document-agent.md
+kodax a2a serve --port 8765
+```
+
+The fixed token above is the compatibility profile. For dynamic production
+tokens, configure KodaX as an OAuth Resource Server and point it at an external
+issuer:
+
+```bash
+kodax a2a expose document-agent --auth oauth2-jwt \
+  --oauth-scheme enterprise-oauth \
+  --oauth-issuer https://identity.example/ \
+  --oauth-audience https://kodax.example/a2a \
+  --oauth-jwks-url https://identity.example/.well-known/jwks.json \
+  --oauth-token-url https://identity.example/oauth/token \
+  --oauth-metadata-url https://identity.example/.well-known/oauth-authorization-server \
+  --required-scope a2a.invoke
+kodax a2a serve --port 8765
+```
+
+The Authorization Server authenticates clients, provisions client IDs/secrets,
+issues/rotates/revokes tokens and, for JWT access tokens, signs them and
+publishes metadata/JWKS. The calling A2A
+client obtains a token out of band or with Client Credentials and sends it in
+the Bearer header. KodaX validates JWT type, asymmetric signature, issuer,
+audience, lifetime, subject, and required scopes before task lookup, then maps
+`sub` to the A2A principal. Missing/invalid credentials return `401`; a valid
+token without the required scope returns `403 insufficient_scope`. KodaX does
+not hold the issuer signing key or expose token, refresh, client-registration,
+login, or consent endpoints. Opaque-token introspection and mTLS deployments
+must use a host authentication adapter or reverse proxy. Offline JWT/JWKS
+validation also cannot observe immediate per-token revocation: use short access
+token lifetimes, signing-key rotation, or an introspecting proxy/adapter when
+that property is required.
+
+#### Upgrade retained pre-realm tasks
+
+Realm-aware task ownership intentionally has no normal-request legacy fallback:
+an authority switch must never adopt tasks merely because it reuses a subject.
+If a v0.7.70 task store must remain addressable after upgrading, stop the A2A
+server and first inspect an exact-owner migration plan:
+
+```bash
+kodax a2a migrate-tasks
+kodax a2a migrate-tasks --apply --confirm-server-stopped
+
+# OAuth identity is token-specific, so provide the known historical subject.
+kodax a2a migrate-tasks --subject trusted-orchestrator
+```
+
+The configured Bearer profile supplies its fixed `principalId`; OAuth requires
+`--subject`. Dry-run does not rewrite `tasks.json`. Apply rekeys only exact
+matches, preserves unmatched records, and refuses a live task-store owner.
+Custom SDK hosts can plan multiple known owners without exposing raw tokens:
+
+```ts
+import { migrateA2ALegacyTaskOwners } from '@kodax-ai/kodax/a2a';
+
+const mappings = [{
+  securityRealm: 'oauth2-jwt:https://identity.example/',
+  subject: 'trusted-orchestrator',
+}] as const;
+const plan = migrateA2ALegacyTaskOwners({
+  dataDir: '/var/lib/kodax/a2a', mappings, apply: false,
+});
+
+// After the host/operator verifies the plan:
+if (plan.matchedLegacyTaskCount > 0) {
+  migrateA2ALegacyTaskOwners({
+    dataDir: '/var/lib/kodax/a2a', mappings, apply: true,
+  });
+}
+```
+
+The SDK also accepts `tenant` when a custom authentication adapter historically
+returned one. Two mappings that claim the same legacy owner for different
+realms are ambiguous and rejected; split or guessed ownership is never applied.
+
+`a2a serve` resolves its Runtime provider in this order: explicit CLI option,
+environment, core configuration, then the built-in default. Provider-compatible
+model selection follows the normal hosted Runtime rule. A selected Markdown
+Agent may declare its own validated `provider`; remote A2A input cannot choose
+or override provider, model, reasoning, profile, workspace, or tools.
+
+`expose` validates a named user Markdown Agent before writing its reference.
+`serve` loads configured MCP and Extensions before it resolves the execution
+binding or opens a socket. Native workspace read tools are admitted by
+workspace access; writes, narrow Extension Tools, MCP capabilities, subagents,
+and isolated Skill scripts require their corresponding exact `toolPolicy`
+authority. Internal Skills come from `~/.kodax/skills`, `~/.agents/skills`,
+plugins, and built-ins; public Agent Card skills are a separate explicit
+projection and never reveal the private Skill inventory.
+
+The running server pins Agent, Skill, workspace, tool registration, process and
+store revisions. Card/auth/limits can hot reload; execution-authority changes
+require an explicit restart. Managed contexts live below
+  `~/kodax_a2a_server_workspace/<runtime-profile>/contexts/<context-key>/`. Exact Skill scripts require
+`process: isolated`, an admitted `scripts/...` path, and a passing
+`kodax sandbox doctor`; KodaX never falls back to an unsandboxed shell.
+
+Every concrete file reached by `read`, `grep`, or `glob` is checked against the
+bound workspace. Child runs inherit ceilings for native reads, tools, Skills,
+and Skill scripts; they cannot expand the parent's admitted authority.
+
+### Publish one KodaX Agent
+
+Publication is host-owned and opt-in. The public card describes only the
+configured Agent, media types, and skills. Authentication runs before task
+lookup; authorization runs per operation; task visibility is principal-scoped.
+
+```ts
+import {
+  createBearerEnvA2AAuthentication,
+  createKodaXA2AServer,
+} from '@kodax-ai/kodax/a2a';
+import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';
+
+const runtime = await createKodaXRuntime({ mode: 'embedded', isolation: 'inline' });
+const server = createKodaXA2AServer({
+  runtime,
+  dataDir: '/var/lib/kodax/a2a',
+  agent: {
+    name: 'KodaX Reviewer',
+    description: 'Reviews bounded code changes.',
+    version: '1.0.0',
+    publicBaseUrl: 'https://kodax.example',
+    skills: [{ id: 'review', name: 'Review', description: 'Review code.', tags: ['code'] }],
+    inputModes: ['text/plain'],
+    outputModes: ['text/plain'],
+  },
+  authentication: createBearerEnvA2AAuthentication({
+    type: 'bearer-env',
+    tokenEnv: 'KODAX_A2A_TOKEN',
+    principalId: 'trusted-orchestrator',
+  }),
+  async authorize({ principal }) { return principal.scopes.includes('a2a:invoke'); },
+  limits: {
+    maxRequestBytes: 1_048_576,
+    maxPartBytes: 524_288,
+    maxConcurrentTasks: 8,
+    maxTaskWaitMs: 30_000,
+    maxActiveTasksPerPrincipal: 8,
+    maxRetainedTasksPerPrincipal: 64,
+    maxEventsPerTask: 1_000,
+    maxEventBytesPerTask: 16_777_216,
+    maxWorkspaceBytesPerContext: 1_073_741_824,
+  },
+});
+
+// Development only: the built-in listener refuses non-loopback hosts.
+const localBaseUrl = await server.listen({ hostname: '127.0.0.1', port: 0 });
+```
+
+Production hosts route `GET /.well-known/agent-card.json` and canonical
+JSON-RPC `POST /a2a` to `server.handle(request)` behind their own TLS
+terminator. `POST /` remains an accepted compatibility alias. `listen()` waits for durable recovery before
+it resolves. A host that wires `handle()` directly may explicitly await
+`server.whenReady()` before it starts accepting traffic; `handle()` also waits
+for the same recovery promise. The durable edge store supports get/list,
+continuation, cancellation, ordered SSE subscription, and surviving Runtime-run
+reattachment after an edge restart. Push notifications, A2A 0.3, gRPC, and
+HTTP+JSON are not advertised; unsupported push methods return the standard
+`PushNotificationNotSupportedError`.
+
+Non-streaming `SendMessage` waits at most `maxTaskWaitMs` (30 seconds by
+default). When that bound is reached the response contains the current working
+task; it does not cancel the Runtime run, and clients can continue with
+`GetTask` or `SubscribeToTask`.
+
+When a task enters `INPUT_REQUIRED`, the next accepted input answers the pending
+interaction on the original Runtime run; it does not start a replacement run.
+History length and list filters are validated and bounded. Task listing uses a
+stable opaque cursor, while per-principal retention prunes only the oldest
+terminal records. Terminal subscriptions and failed-start resources are closed
+by their owning lifecycle.
+
+Remote messages are ordinary user inputs. They cannot select provider, model,
+profile, tools, working directory, permission mode, or Runtime configuration.
+URL parts are rejected; inline raw/data parts are bounded and materialized under
+the server-owned data directory. Responses expose final approved output only,
+not system prompts, reasoning deltas, tool payloads, credentials, or local paths.
+
+Generated files are published only through the trusted output broker: a normal
+tool or Extension stages a file in the context's `.kodax-a2a-staging` area, or
+a successfully admitted `run_skill_script` promotes one of its declared
+outputs. The server rechecks that the result is a regular non-symlink file in
+the real bound workspace and applies part-size/output-mode limits before
+inlining it. A declaration from a failed Skill run, an ordinary `write`/`edit`
+elsewhere in the workspace, and a local path in model text never become A2A
+artifacts implicitly.
+
+The normative baseline is A2A repository commit
+`2183794bfb9b67af4aee1be0a0ef726050642873`, protocol `1.0`, with
+`specification/a2a.proto` SHA-256
+`e195bf96ab630c69797851970203e1b2b6b19528f2e9803b7d904b91a5104016`.
+
+---
+
+## 23. Shared Coder daemon for Space and IDE hosts (FEATURE_269, v0.7.69)
+
+FEATURE_269 makes one local daemon the source of truth for a Coder profile.
+CLI, Space, IDE, and SDK clients can observe and control the same sessions and
+runs. The transport remains local to the current OS user; it is not a remote
+collaboration protocol. Closing a client detaches that client and does not stop
+the daemon or another client's run.
+
+Partner is deliberately outside this migration. Keep Partner on its existing
+inline callbacks and give it a distinct product data root and sessions root.
+Do not point a Partner inline Runtime at the Coder daemon profile or the Coder
+data root.
+
+### Connect and fail closed on required capabilities
+
+Space should own the daemon SDK client in Electron Main. Persist a random,
+stable `instanceId` and a separate 32+ character `instanceSecret` per Space
+installation. Store the secret in the OS keychain; never accept either value
+from renderer or model output. `connectKodaXRuntime()` is attach-only unless `autoStart: true`.
+An explicit inline rollback policy blocks auto-start until the owner policy is
+explicitly changed back to daemon.
+
+For Electron, `homeDir` is still the CLI-style base directory, not
+`process.env.KODAX_HOME`. Packaged/asar applications may use `autoStart: true`
+directly; the SDK launches only the daemon child in Electron's Node execution
+mode and does not mutate the application's environment or start a second GUI
+instance. `ELECTRON_RUN_AS_NODE` exists only at the child exec boundary and is
+removed before daemon application code loads, so Bash, MCP, LSP, sandboxed
+commands, and ordinary external processes do not inherit Electron Node mode.
+
+Packaged auto-start requires Electron's `RunAsNode` fuse, which Electron enables
+by default. If an embedder deliberately disables that fuse, the packaged
+executable cannot serve as a detached Node host: start the daemon with an
+ordinary Node/CLI process and use attach-only mode instead. A packaged
+`autoStart: true` timeout includes this fuse requirement in its diagnostic; the
+SDK does not relaunch the GUI or silently fall back to an inline Runtime.
+
+```ts
+import { connectKodaXRuntime } from '@kodax-ai/kodax/runtime';
+
+const runtime = await connectKodaXRuntime({
+  profile: 'coder',
+  autoStart: true,
+  homeDir: coderRuntimeBaseDir, // owns <coderRuntimeBaseDir>/.kodax
+  clientInfo: {
+    name: 'kodax-space',
+    version: '0.1.32',
+    instanceId: spaceInstallationId,
+    instanceSecret: await spaceKeychain.readRuntimeClientSecret(),
+  },
+  capabilities: {
+    richEvents: true,
+    permissionPrompts: true,
+    operationDeduplication: true,
+  },
+  requirements: {
+    operationDeduplication: 1,
+    sessionObservation: 1,
+    afterTurnInput: 1,
+    interruptInput: 1,
+    askUserTransport: 1,
+    permissionCas: 1,
+    providerCredentialBroker: 1,
+    runBoundHostTools: 1,
+    coderOwnerFencing: 1,
+    crashOutcomeModel: 1,
+    coderFeatureMatrix: 1,
+    sessionAdmission: 1,
+    completeObservationSnapshot: 1,
+    connectionLifecycle: 1,
+    typedRuntimeEvents: 1,
+    daemonSafeRunInput: 1,
+    sharedSessionSettings: 1,
+    durableRecoveryQueries: 1,
+    daemonManagement: 1,
+    runtimeAutoModeGuardrail: 3,
+  },
+});
+```
+
+Requirements are server facts, not authorization requests. Check
+`runtime.grantedScopes` before enabling controls. Missing capabilities or
+scopes must disable the affected UI; Space must not silently start inline
+Coder. Products that depend on same-Run delivery should require
+`{ interruptInput: 1 }`. Individual active Runs without a safe Actor boundary
+(for example, SA execution) still return `unsupported_capability`; do not
+silently substitute `delivery:'after_turn'` unless that is the user's intent.
+
+The v0.7.73 SDK requires `runtimeAutoModeGuardrail:3` automatically for
+`autoStart: true`, even when the caller omits it from `requirements`. If the healthy
+profile daemon advertises v1 or v2, the SDK first requires `daemonManagement:1`,
+takes a revision/owner-policy fenced preflight, and replaces it only when no
+active or queued run, Workflow, Agent turn, pending permission/user input, or
+other logical client exists. A busy or still-older daemon is never stopped: the
+connection rejects with `RuntimeDaemonCapabilityUpgradeError`, whose
+`recoverable` and `restartRequired` fields are `true` and whose optional
+`preflight` explains the blockers. Attach-only connections never mutate daemon
+ownership and must request `runtimeAutoModeGuardrail:1` explicitly when they
+depend only on the v1 owner contract, v2 for bounded input, effective-default
+metadata, structured diagnostics, and speculative-window parity, or v3 for
+opaque exact grant suggestions and concrete permission matchers. Capability
+requirements are minimum versions: v3 satisfies v1/v2, v2 satisfies v1, and an
+older daemon never satisfies a newer requirement.
+
+The `coderFeatureMatrix` capability reports daemon availability for managed
+runs, transcript/session operations, Todo projection, managed tasks, Workflow,
+MCP, Reference External Agent, Memory, and Runtime artifacts. Reference
+External Agent is `false` when the daemon owner did not install its executor
+plane.
+
+The packaged daemon authenticates one local OS-user/profile trust domain with
+a random token stored beside daemon state and a user-only local endpoint. It
+does not issue a different daemon token to each application in v0.7.69. The
+returned scope set is chosen by the host (the packaged host grants the public
+local-user set). `clientInfo.instanceId` is stable attribution for origin and
+operation deduplication. `instanceSecret` proves that a new authenticated
+connection is the same stable client when it resumes that client's credential
+or Host Tool leases; only its hash participates in daemon-owned bridge state.
+Keep all three values in Electron Main. Mutually distrusting processes running
+as the same OS account remain outside this release's threat model.
+
+### Join atomically and resync after disconnect
+
+`sessions.observe()` installs the live subscription before taking the
+snapshot. Its snapshot contains one authoritative `runtimeId`, cursor,
+`transcriptRevision`, complete transcript, versioned settings, run/queue state,
+queued continuation IDs/order/origin/safe previews, pending permission and
+AskUser requests, and live assistant/thinking/tool/Todo/managed-task
+projection. Run requirements include the current credential/Host Tool
+availability. Listener events are strictly after the returned cursor.
+
+```ts
+let observedRuntimeId: string | undefined;
+let lastCursor = 0;
+
+async function openCoderSession(sessionId: string) {
+  const observation = await runtime.sessions.observe(sessionId, (event) => {
+    if (event.seq <= lastCursor) return;
+    applyRuntimeEvent(event);
+    lastCursor = event.seq;
+  });
+
+  const { snapshot } = observation;
+  const runtimeChanged = observedRuntimeId !== undefined
+    && observedRuntimeId !== snapshot.runtimeId;
+  observedRuntimeId = snapshot.runtimeId;
+  lastCursor = snapshot.cursor;
+  replaceSessionProjection(snapshot, { runtimeChanged });
+  return observation;
+}
+```
+
+Subscribe to `runtime.connection` to freeze mutation UI immediately rather
+than waiting for a status poll:
+
+```ts
+runtime.connection?.subscribe((state) => {
+  setCoderConnectionState(state.state, state.reason);
+  if (state.state === 'disconnected' && state.reconnectable) {
+    scheduleReconnect();
+  }
+});
+```
+
+The SDK reports the current `connectionId`, `runtimeEpoch`, optional
+`journalEpoch`, disconnect reason, and whether a new connection may be
+attempted. It does not transparently replay requests or subscriptions. Space
+creates a replacement Runtime client, checks its new epochs, resumes eligible
+leases, and observes the session again.
+
+On transport failure, Runtime change, expired history, or `resync_required`,
+discard the local derived projection and call `sessions.observe()` again. Do
+not merge a new snapshot into the old projection. The handshake buffer is
+bounded; overflow fails explicitly instead of dropping events. A Runtime
+restart changes `runtimeId`, marks persisted non-terminal runs with a durable
+terminal fact, and closes old in-memory AskUser/permission requests through the
+reset boundary.
+
+### Durable mutations, stable ordering, and settings CAS
+
+Every durable public control mutation uses an operation envelope. Credential
+and Host Tool register/revoke/supply/complete requests are reverse-bridge
+control frames and are deliberately excluded from the control journal so
+secrets/results are not persisted. They still enter the daemon management
+draining fence: once an atomic stop begins, they fail with typed `conflict` and
+cannot change reverse-bridge state. The SDK creates an operation ID for
+ordinary one-shot calls. A
+product-level retry after a lost response must reuse its own stable operation
+ID; changing its method, payload, resource, or authenticated principal is
+rejected.
+
+```ts
+const session = await runtime.sessions.create({
+  sessionId: stableSpaceSessionId,
+  title: 'Shared session',
+  surface: 'space-desktop',
+  operation: { operationId: loadOrCreatePendingOperationId('space-session-draft-7') },
+});
+
+const operationId = loadOrCreatePendingOperationId('space-run-draft-42');
+const handle = await runtime.runs.start({
+  sessionId: session.id,
+  input: { type: 'text', text: prompt },
+  options: { provider: 'anthropic' },
+  operation: { operationId },
+});
+
+const current = await runtime.sessions.getSettingsVersioned(session.id);
+const updated = await runtime.sessions.updateSettingsVersioned(
+  session.id,
+  { model: 'claude-sonnet-4-5' },
+  {
+    operationId: loadOrCreatePendingOperationId('space-settings-draft-9'),
+    expectedRevision: current.revision,
+  },
+);
+```
+
+Create retries with the same explicit session and operation IDs cannot overwrite
+an existing session. Same-session starts and after-turn inputs receive a durable `sessionOrder`.
+Retries with the same operation ID return the canonical result and do not
+create another run. Settings use compare-and-swap; a stale revision returns a
+structured conflict and must be reloaded, never silently overwritten. The
+shared settings keys are `provider`, `model`, `effort`, `thinking`,
+`reasoningMode`, `permissionMode`, `executionCwd`, `agentMode`, and
+`autoModeEngine`, `autoModeClassifierModel`, `autoModeTimeoutMs`, and
+`autoModeSpeculativeWindowMs`.
+
+```ts
+const queued = await runtime.runs.submitInput({
+  sessionId: session.id,
+  afterRunId: handle.runId,
+  delivery: 'after_turn',
+  input: { type: 'text', text: 'Also update the tests.' },
+  operation: { operationId: loadOrCreatePendingOperationId('space-input-17') },
+});
+
+if (!queued.accepted) {
+  // stale_run, unsupported_capability, or interrupt_window_closed:
+  // show the factual result and preserve the user's unsent input.
+}
+```
+
+For input that must join the current active Run, submit `delivery:'interrupt'`.
+This does not create a Run. Each accepted input appears as `queued` in the
+owning Run's `interruptInputs`. At the next safe boundary, all accumulated
+interrupts are drained FIFO, remain separate user messages in one next LLM
+request, and produce one `run.input.delivered` event whose `inputs` array is the
+complete ordered batch. Exact operation retries return the same `inputId`.
+The accepted result's `runId` is the existing owning Run (equal to
+`afterRunId`), not a newly created continuation.
+
+Interrupt admission closes when the Runner publishes its final completion or
+terminal error signal, or when the Run's supplied `abortSignal` aborts, even if
+the outer Run is still settling. Non-terminal observer diagnostics do not close
+the window. A submission after closure returns `accepted:false` with
+`reason:'interrupt_window_closed'` and is not queued. Keep the original input
+available for retry after the Run ends; do not silently change its delivery to
+`after_turn`. As a final race/recovery
+guard, inspect terminal Run status: any `interruptInputs` entry whose state is
+`terminal` was not delivered. Reconcile it by `inputId` and present a visible
+non-delivery outcome rather than leaving a pending queue indicator.
+
+```ts
+const interrupted = await runtime.runs.submitInput({
+  sessionId: session.id,
+  afterRunId: handle.runId,
+  delivery: 'interrupt',
+  input: { type: 'text', text: 'Also preserve the public API.' },
+  operation: { operationId: loadOrCreatePendingOperationId('space-input-18') },
+});
+```
+
+Run status exposes acceptance/start/queue times, authenticated origin,
+`sessionOrder`, and a single terminal fact. Important terminal codes include
+`runtime_restarted`, `daemon_crashed`, `credential_unavailable`,
+`host_not_dispatched`, `host_outcome_unknown`, and
+`control_history_untrusted`. Managed tasks that require user input use
+`terminal.code = 'blocked'`; surface `terminal.message` when present instead of
+replacing it with a generic run failure. Respect `effectOutcome`; `unknown` must
+never be presented as success or automatically retried. After a lost response,
+query `runtime.operations.get({ operationId, journalEpoch })`; applied receipts
+include the canonical result. Permission grants remain daemon-owned and
+revisioned.
+
+### AskUser and permission from any client
+
+AskUser is no longer an in-process callback for daemon Coder runs. Any client
+with the responder scope can list the pending request and answer or dismiss it.
+The request revision and run binding prevent a stale UI from answering a new
+request. Exactly one concurrent answer is accepted.
+
+```ts
+for (const request of await runtime.userInputs.listPending({ sessionId })) {
+  const resolution = await runtime.userInputs.respond(request.id, answer, {
+    expectedRevision: request.revision,
+    runId: request.runId,
+  });
+  if (!resolution.accepted) refreshPendingInteractions();
+}
+
+for (const request of await runtime.permissions.listPending({ sessionId })) {
+  const sessionScope = request.grantSuggestions
+    ?.find((candidate) => candidate.kind === 'session');
+  const accepted = await runtime.permissions.respond(
+    request.id,
+    sessionScope
+      ? { type: 'allow_session', suggestionId: sessionScope.id }
+      : { type: 'allow_once' },
+    { runId: request.runId },
+  );
+  if (!accepted) refreshPendingInteractions();
+}
+```
+
+Persistent `allow_always` grants are owned by the daemon and require
+`permission:grant-admin`. Use `permissions.listGrants()` and
+`revokeGrant(grantId, expectedRevision)` for revision-safe administration.
+Clients must return one opaque `grantSuggestions[].id` from the pending request;
+they must not infer, construct, or widen a scope from the display label or input
+preview. A safe request can offer `allow_session` and `allow_always`; a risky or
+dynamic shell request deliberately omits the persistent candidate. Command
+grants match one exact normalized command/cwd/shell/background combination,
+while path grants match one tool and normalized absolute path (the future
+Write/Edit content may differ). Generic extension calls can receive only an
+exact in-memory Session grant. Raw command/argv data is not stored in the
+matcher; grants and audit contain only its fingerprint plus a bounded,
+secret-redacted operator label. Clients must not keep separate persistent
+permission rule stores. Runtime capability `runtimeAutoModeGuardrail` v3 advertises this
+opaque concrete-grant contract; restart or upgrade an older daemon instead of
+falling back to a client-side alias.
+
+### Broker a Space keychain credential
+
+Credentials remain owned by Space's OS keychain. Register a broker in Electron
+Main, bind the returned lease only to runs that Space starts, and return the
+key only after checking the daemon-provided provider/session/run context.
+
+```ts
+const credentialLease = await runtime.credentials.register(
+  { providers: ['anthropic'] },
+  async ({ provider, sessionId: requestedSession, runId }) => {
+    authorizeSpaceRunCredential({ provider, sessionId: requestedSession, runId });
+    return spaceKeychain.readProviderCredential(provider);
+  },
+);
+
+const run = await runtime.runs.start({
+  sessionId,
+  input: { type: 'text', text: prompt },
+  options: { provider: 'anthropic' },
+  credential: { leaseId: credentialLease.id, provider: 'anthropic' },
+  operation: { operationId: loadOrCreatePendingOperationId('space-run-88') },
+});
+```
+
+The secret crosses only the authenticated reverse frame and an in-memory
+run/provider scope. It is excluded from events, status, logs, diagnostics,
+operation records, and Runtime persistence. While such a scope is active,
+provider mismatch fails closed and never falls back to daemon environment.
+Without a stable `instanceSecret`, registration ends when the Space connection
+closes. With it, the daemon keeps the registration owned by that stable client;
+a replacement Space process reattaches the callback with
+`runtime.credentials.resume(leaseId, broker)`. An accepted run has already
+acquired its scoped credential, so it reports `requirements.credential.state`
+as `ready` and may continue after disconnect. If the broker cannot answer, the
+start is rejected instead of accepting an indefinitely waiting run. Expiry or
+Runtime restart is explicit (`expired` or terminal); no provider request is
+automatically replayed.
+
+### Bind Space-owned Host Tools to one run
+
+Register only narrow product capabilities. Descriptors are data; handlers stay
+in Electron Main. A lease grants nothing until its ID is explicitly bound to a
+run.
+
+```ts
+const hostLease = await runtime.hostTools.register([{
+  name: 'space_artifact_create',
+  description: 'Create a Space-owned artifact for this run.',
+  inputSchema: {
+    type: 'object',
+    properties: { title: { type: 'string' } },
+    required: ['title'],
+    additionalProperties: false,
+  },
+  sideEffect: 'non_idempotent',
+}], {
+  async space_artifact_create(invocation) {
+    authorizeBoundSpaceInvocation(invocation);
+    const artifact = await createSpaceArtifact(invocation.input);
+    return { content: `Created artifact ${artifact.displayId}` };
+  },
+});
+
+await runtime.runs.start({
+  sessionId,
+  input: { type: 'text', text: 'Create the report artifact.' },
+  hostTools: { leaseId: hostLease.id },
+  operation: { operationId: loadOrCreatePendingOperationId('space-artifact-run') },
+});
+```
+
+The daemon injects session/run/lease/invocation identity; renderer, model, and
+ordinary tool input cannot choose it. CLI runs never inherit a Space lease just
+because Space later observes their session. The client memoizes one handler
+promise per invocation ID, and the daemon never replays a dispatched Host Tool.
+After a stable-client reconnect, call
+`runtime.hostTools.resume(leaseId, handlers)`. Bound run status reports
+`ready`, `waiting_host`, `expired`, or `terminal`. Disconnect or timeout after dispatch produces `host_outcome_unknown`; Space
+must reconcile the product side effect itself before offering a new user
+action. `runtime.hostTools.getInvocation(invocationId)` returns the durable
+metadata state `prepared`, `dispatched`, `completed`, `unknown`, or
+`not_dispatched`; it never returns handler input, result, or credential data.
+The daemon writes the `dispatched` marker before attempting the reverse frame
+and never auto-replays an invocation.
+
+### Coder admission, typed events, and transport-safe inputs
+
+The daemon enforces Coder session admission on the server for list/create/load,
+run, settings, delete, rewind, fork, compact, transcript, event, interaction,
+and diagnostic paths. Coder
+surfaces are `code`, `cli`, `repl`, `acp`, `a2a`, `sdk`, `ide`, and
+`space-desktop`. A session marked with
+Partner surface/profile metadata, or any unknown product surface, fails with
+typed `session_not_admitted` before mutation. Space must continue marking
+Partner sessions as `surface: 'partner'` and keep their inline storage root
+separate. Legacy sessions without a surface remain admitted for existing Coder
+compatibility, so absence of metadata is not a Partner namespace mechanism.
+
+`RuntimeEventPayloadMap` and `RuntimeTypedEvent` provide the public
+discriminated contract for known events. Existing raw listeners remain
+compatible; consumers can use `parseRuntimeEvent(value)` before exhaustive
+handling. One unknown or malformed event is diagnosed and dropped without
+closing the observation stream.
+
+Daemon clients use `RuntimeDaemonStartRunInput`. Function callbacks,
+`AbortSignal`, Extension Runtime objects, and guardrail instances are excluded
+from that type and rejected at runtime with `RuntimeTransportBoundaryError`
+and an exact value path if an untyped caller supplies them. Host-only values
+remain valid only for embedded Runtime calls.
+
+### Recovery queries and stop preflight
+
+`runtime.status.preflight()` returns the initialized logical-client count,
+active and queued runs, running/paused Workflows, every non-terminal External
+Agent task (including `unknown`), pending AskUser/permission records, blockers,
+and `canStop`. The background-work blockers are `active_workflows` and
+`active_agent_tasks`. The current facade counts as one; daemon self-connections
+and bounded health probes do not count. A second process changes the count to
+two, and its awaited `close()` makes the count converge back to one.
+
+Preflight is useful for UI, but it is not a stop authorization token. Use
+`runtime.daemon.inspect()` to obtain one consistent management revision,
+verified owner fence, owner-policy revision, and preflight projection. Only
+`runtime.daemon.stopForInline()` atomically rechecks and commits a rollback.
+The management revision also advances when the preflight projection changes,
+so a Workflow or AgentTask lifecycle transition between inspect and commit
+invalidates the stale stop. Capability details
+`daemonManagement.backgroundWorkPreflight` and
+`daemonManagement.reverseBridgeDrainingFence` identify this complete contract.
+`runtime.operations.get()` reconciles durable mutations,
+`hostTools.getInvocation()` reconciles Host Tool metadata, and
+`permissions.listGrants()` returns the daemon-owned persistent grant set.
+
+Terminal notification read/unread state is intentionally client-owned in
+v0.7.69 (`durableRecoveryQueries.terminalAcknowledgement === false`): Space
+persists its own UI acknowledgement cursor against Runtime/run terminal facts.
+This avoids a false claim that one client's acknowledgement is global daemon
+truth.
+
+### Owner policy, rollback, and Electron boundary
+
+Daemon and inline Coder use one profile fence. Do not compose
+`status.preflight()` with a low-level unconditional stop: another client or run
+can appear between those calls. The public rollback transaction gates new
+clients and mutations, rechecks the same Runtime and management/policy
+revisions, verifies there is no other client or active/queued/pending work,
+commits sticky inline policy while that daemon still owns the fence, and then
+requests shutdown.
+
+```ts
+import {
+  acquireKodaXInlineOwner,
+  enableKodaXDaemonOwner,
+  getKodaXRuntimeOwnerState,
+} from '@kodax-ai/kodax/runtime';
+
+const management = await runtime.daemon.inspect();
+if (!management.preflight.canStop) {
+  showRollbackBlockers(management.preflight.blockers);
+  return;
+}
+
+const rollback = await runtime.daemon.stopForInline({
+  expectedRuntimeId: management.runtimeId,
+  expectedRevision: management.revision,
+  expectedOwnerPolicyRevision: management.ownerPolicy.revision,
+  operation: { operationId: loadOrCreatePendingOperationId('coder-inline-rollback') },
+});
+
+// `accepted` means inline policy is committed and shutdown is in progress.
+// Wait through the public owner-state query; never infer release from a PID.
+const shutdownDeadline = Date.now() + 30_000;
+while (getKodaXRuntimeOwnerState({ homeDir: kodaxHome, profile: 'coder' }).owner?.runtimeId
+  === rollback.runtimeId) {
+  if (Date.now() >= shutdownDeadline) throw new Error('Timed out waiting for daemon owner release.');
+  await delay(25);
+}
+const releasedOwner = getKodaXRuntimeOwnerState({ homeDir: kodaxHome, profile: 'coder' });
+if (releasedOwner.ownerStatus !== 'unowned') {
+  throw new Error('Coder profile acquired a different owner during rollback.');
+}
+await runtime.close(); // Detach only; it does not perform a second stop.
+const inlineOwner = acquireKodaXInlineOwner({ homeDir: kodaxHome, profile: 'coder' });
+
+// Later, after the inline owner has released its fence:
+inlineOwner.close();
+const daemonPolicy = enableKodaXDaemonOwner({ homeDir: kodaxHome, profile: 'coder' });
+// daemonPolicy.revision is authoritative; no expectedRevision guess is needed.
+```
+
+Any management revision change, another logical client, active or queued run,
+running/paused Workflow, non-terminal/unknown AgentTask, pending
+AskUser/permission, or in-flight mutation returns structured `conflict`; the
+daemon remains running and policy remains unchanged. Draining also rejects
+credential and Host Tool state changes without journaling their secrets or
+results. The inline policy is sticky: later CLI auto-start is rejected until
+`enableKodaXDaemonOwner()` changes it back to `daemon`. `runtime.close()` still
+only detaches. Stale-owner handling validates the owned lock/state and never
+kills a process merely because a PID was reused.
+
+Keep all trusted objects in Electron Main: daemon token/endpoint, stable client
+identity, operation IDs, owner policy, keychain broker, Host Tool handlers, and
+permission-grant administration. Renderer IPC should expose product-specific
+commands and sanitized projections only. Never pass daemon credentials,
+leases, operation epochs, or trusted session/run context to renderer or model
+tool arguments.
+
+---
+
+## 24. Runtime-owned Auto Mode and plan-approval bridges (v0.7.72–v0.7.73)
+
+Auto Mode is a Runtime session contract, including in shared-daemon mode. Do
+not implement a second classifier or decide permissions from a client-side
+`beforeToolExecute` hook before the Runtime has classified the call.
+
+### Configure the session, not an individual UI callback
+
+```ts
+await runtime.sessions.updateSettings(session.id, {
+  permissionMode: 'auto',
+  autoModeEngine: 'llm',
+  autoModeClassifierModel: 'zhipu:glm-5.2', // optional; otherwise follow the run model
+  autoModeTimeoutMs: 20_000,                // positive safe integer, optional
+  autoModeSpeculativeWindowMs: 0,           // non-negative safe integer, optional
+  executionCwd: projectDirectory,
+});
+```
+
+All three Auto fields are durable session settings in inline, Worker, and
+daemon forms. A `null` patch removes an optional override. Timeout must be a
+positive safe integer; speculative window must be non-negative, so `0` is a
+valid request to wait for the actual verdict. Daemon capability discovery
+advertises all fields in `sharedSessionSettings.keys`.
+
+SDK hosts that need config precedence without creating a REPL can reuse the
+same typed resolver as KodaX:
+
+```ts
+import {
+  loadAutoModeSettings,
+  resolveAutoModeSettings,
+  type ResolveAutoModeSettingsInput,
+} from '@kodax-ai/kodax/repl';
+
+const persisted = loadAutoModeSettings(process.env);
+const preview = resolveAutoModeSettings({
+  settings: { engine: 'llm', speculativeWindowMs: 0 },
+  env: process.env,
+});
+```
+
+`resolveAutoModeSettings()` is pure. `loadAutoModeSettings()` reads the KodaX
+config once and delegates to that resolver; `loadConfig()` declares and
+returns the same optional `autoMode` object.
+
+Starting with the v0.7.73 patch, `permissionMode: 'auto'` with an omitted
+`autoModeEngine` still means the documented `llm` default and is still owned by
+Runtime. If neither `autoModeClassifierModel` nor the effective run/session/
+Runtime model exists, `runs.start()` rejects with
+`RuntimeAutoModeConfigurationError` (`code:
+'auto_mode_classifier_model_required'`, `recoverable: true`) before provider
+construction, a classifier call, or a pending permission. Blank and malformed
+classifier model specs are rejected by the same typed configuration boundary;
+a live rules-to-LLM switch is blocked rather than converted into approval work.
+
+Direct consumers of `createAutoModeToolGuardrail()` receive the same terminal
+model boundary. After resolving CLI/env/session/settings/live-default
+precedence, an empty effective model returns a local configuration `block`
+before provider lookup. It does not call `askUser`, mutate the denial or
+circuit-breaker trackers, or change the engine to rules. An explicit non-empty
+classifier override remains valid even when the main-session model is empty.
+
+The Runtime owns one serialized permission-settings stream and one shared
+engine/denial/breaker state per Session. It reuses bounded context-specific
+guardrails across turns while provider/model, repository boundary, execution
+directory, classifier model, and timeout remain the same. Updating one of
+those inputs selects a new context guardrail by design without copying stale
+state from a queued turn. Active runs, queued runs, explicit settings updates,
+and automatic LLM-to-rules fallback merge through the same Session mutation
+queue; fallback is persisted before a later classification reads the engine.
+
+### What an embedder should expect
+
+The Runtime's execution order is fixed:
+
+```text
+Runtime Auto Mode guardrail -> host permission bridge only for escalate -> tool execution
+```
+
+Consequently, an LLM/rules `allow` does not create a pending permission request
+just because a host installed a static approval hook. `block` does not become a
+spurious approval prompt. A real `escalate` uses the existing shared
+`runtime.permissions` flow, so another authorized client may render and answer
+it. Hosts should subscribe to permission events to display such a request, but
+must not treat a missing request as an error for a safe tool call.
+
+The classifier deadline remains 20 seconds by default and includes connection
+setup, provider Retry-After/backoff, inference, and stream completion. KodaX
+does not solve timeouts by extending that deadline indefinitely. Before the
+provider call it removes assistant prose/thinking and image paths, limits each
+tool result to 2 KiB and the serialized permission-relevant transcript to
+8 KiB, then enforces 16 KiB action and 32 KiB total-prompt ceilings plus a
+256-token output cap. An oversized action or prompt escalates without a
+provider call; it is never truncated into an automatic allow. These limits are
+owned by `classify()` itself, so custom callers cannot accidentally bypass the
+session-history boundary.
+
+`ClassifyDecision.diagnostics` and the lower-level
+`SideQueryResult.diagnostics` expose provider, model, effective timeout,
+elapsed time, retry count/wait, and a coarse terminal phase without including
+the prompt, action, messages, or response text. `pre_output` means no non-empty
+text delta was observed; `streaming` means output began before termination.
+`firstOutputMs` and `streamMs` are present only when the provider adapter emits
+a text delta. The current provider API cannot honestly separate DNS/connect,
+TLS, provider queueing, and inference, so embedders must not infer those stages
+from `pre_output`.
+
+The permission event's `inputPreview` is a display-safe diagnostic projection:
+it is bounded, credential-redacted, valid JSON, and includes the effective
+execution directory. Use the Runtime owner’s typed tool input for execution;
+do not reconstruct or authorize a tool from the preview. `gitRoot` remains the
+session repository safety boundary, whereas relative operands resolve from the
+validated `executionCwd`. In particular, quoted Python/JavaScript/regexp source
+inside a shell command is not a path operand.
+
+The user-level `.kodax` directory is a credential/configuration boundary, not
+an ordinary project path. Direct shell mutations, output redirects, and
+recognized nested-shell payloads whose target is provably beneath that
+directory are rejected before LLM classification. The check is segment-safe
+and Windows case-insensitive. KodaX deliberately does not scan arbitrary
+quoted language source for path-looking substrings: doing so would turn Python,
+JavaScript, YAML, and regular expressions into false Tier-0 matches. Trusted
+configuration changes should use the KodaX config CLI or SDK configuration API.
+
+### 0.7.x source compatibility
+
+The v0.7.72 public declarations retain the following migration aliases:
+
+| Legacy source | Current source | Contract |
+|---|---|---|
+| `agentMode: 'amaw'` | `'ama'` | accepted as deprecated input and normalized to AMA; no separate AMAW runtime is restored |
+| `SkillSource` | `ResolvedSkillSource` | formal source union remains `project \| user \| plugin \| builtin`; only resolved discovery output adds `learned` |
+| `RuntimeDaemonPreflight.activeAgentTasks` | `activeAgentTurns` | both required fields are returned and reference the same array throughout the 0.7.x line |
+
+### Plan capability is opt-in
+
+`exit_plan_mode` is exposed to a Runtime run only when that run supplies an
+approval bridge. A daemon or headless host that cannot approve a plan should
+leave the bridge absent; KodaX removes the tool from that run's scope.
+
+```ts
+const planned = await runtime.runs.start({
+  sessionId: session.id,
+  prompt: 'Draft a migration plan, then ask for approval.',
+  options: {
+    events: {
+      exitPlanMode: async () => showPlanAndAskUser(),
+    },
+  },
+});
+await planned.result;
+```
+
+The callback belongs in a trusted host process (for Electron, Main rather than
+renderer). It is intentionally not inferred from the presence of a permission
+UI: tool permission and plan approval are different user decisions.
+
+See [ADR-056](ADR.md#adr-056-runtime-owns-auto-mode-permission-decisions-and-host-capability-exposure)
+for the ownership decision, [the v0.7.72 design](features/v0.7.72.md#2026-07-18-runtime-permission-queue-and-resume-closure)
+for the release boundary, and [Known Issue 187](KNOWN_ISSUES.md#187-shared-daemon-auto-permission-ownership-upgrade-fencing-preview-bounds-and-sdk-compatibility-were-incomplete)
+for the final capability-upgrade and compatibility closure.
+
+---
+
+## 25. Always-on context compaction and bounded transcript recovery (v0.7.74)
+
+Automatic large compaction is always enabled. `enabled` remains accepted for
+v0.7.x source compatibility, but `false` is normalized to `true`.
+`triggerPercent` defaults to `75` and is clamped to `15..90`. The optional
+absolute threshold is inactive when omitted or zero; otherwise the smaller
+percentage, absolute, and physical-capacity threshold wins.
+
+```ts
+const run = await startKodaX({
+  provider: 'zhipu-coding',
+  model: 'glm-5.2',
+  compaction: {
+    triggerPercent: 60,
+    triggerTokens: 300_000,
+  },
+});
+```
+
+The recent raw tail is 20% of that effective trigger, not 20% of the model's
+maximum context window. A manual Runtime compact bypasses only the trigger
+comparison and uses the Session's same effective policy:
+
+```ts
+await runtime.sessions.updateSettings(session.id, {
+  compactionTriggerPercent: 60,
+  compactionTriggerTokens: 300_000,
+});
+
+await runtime.sessions.compact({ sessionId: session.id });
+```
+
+Setting `compactionTriggerTokens: 0` removes the absolute Session override.
+Percentage updates are normalized to `15..90`; negative/fractional absolute
+values are rejected. Explicit per-run `options.compaction` values override
+Session settings.
+
+Large compaction covers the complete eligible prefix once, preserves an atomic
+recent tail, and installs a synthetic user checkpoint. Every genuine user query
+is rendered mechanically in its checkpoint ledger; tool-result wire messages
+and synthetic prompts are excluded. The normal summary request preserves the
+main request's system, message, tool, model, and reasoning prefix and appends a
+text-only ephemeral instruction so providers can reuse prompt/KV cache.
+
+The exact pre-compaction transcript has a separate durability guarantee. The
+root host persists all pre-compaction messages (including messages created in
+the active Run) before old payload is evicted from memory. Island records are
+flushed before a slim main JSONL is published. If the main replacement fails,
+main and sidecar may temporarily overlap, but stable entry IDs project the
+logical entry once. A persistence failure keeps the exact live copy; child
+compaction never writes root Session lineage.
+
+The in-process `onCompactedMessages` callback may return a `Promise`. KodaX
+awaits it before the next provider request and before
+`context.compaction.finished`. Embedded and daemon Runtime execution always
+uses Runtime-owned Session storage, regardless of a client-side
+`persistedByHost` value; a daemon client cannot be the durability owner because
+its callback is not present in the daemon process. Runtime-backed Ink and
+classic REPL hosts therefore update only their live projection after the
+Runtime acknowledgement; they do not perform a second Session write. If a
+headless Runtime Run compacts before its first routine snapshot, Runtime seeds
+the new Session from explicit Run metadata before applying the exact compact
+transaction. A rejected durability callback also rolls back the tentative
+`contextRevision`, so a later successful compact does not expose a phantom gap.
+
+### Context-owned events
+
+`context.compaction.finished` is the canonical post-commit Runtime fact. It
+includes stable root/child identity, revision, before/after tokens, strategy,
+effective trigger, protected budget, and component accounting. Consumers must
+not use `scope: 'worker'` as a parent/child identity substitute.
+
+```ts
+const subscription = runtime.events.subscribe(
+  { sessionId: session.id, types: ['context.compaction.finished'] },
+  (event) => {
+    if (event.type !== 'context.compaction.finished') return;
+    const fact = event.payload;
+    if (fact.contextKind === 'root' && fact.committed) {
+      renderRootContext(fact.tokensAfter, fact.tokensBefore);
+    }
+  },
+);
+```
+
+Legacy `onCompactStats`/`onCompact` callbacks remain compatibility projections.
+The old `onCompact` callback now receives the post-compact count; it no longer
+echoes the pre-compact `currentTokens` value. Hosts that need ownership or
+component metrics should use `onContextCompactionFinished` or the Runtime
+event. Compatibility success callbacks fire only after a strict token
+reduction has restored physical request validity and committed. An unchanged,
+failed, stale, or still-oversized candidate is not a successful compaction.
+
+### Transcript observation below the daemon frame limit
+
+`sessions.observe()` no longer embeds `FullTranscriptSessionData`. Its snapshot
+contains a bounded `RuntimeTranscriptSlice`. Inline entries carry the complete
+transcript entry; an oversized entry carries an explicit descriptor.
+
+```ts
+const observation = await runtime.sessions.observe(session.id, onLiveEvent);
+let page = observation.snapshot.transcript;
+
+while (page) {
+  for (const descriptor of page.entries) {
+    if (descriptor.entry) consume(descriptor.entry);
+    else await consumeEntryChunks(runtime, session.id, page.revision, descriptor.index);
+  }
+  if (!page.hasMore) break;
+  page = await runtime.sessions.transcriptPage({
+    sessionId: session.id,
+    cursor: page.nextCursor,
+  });
+}
+```
+
+`transcriptEntryChunk()` returns lossless `base64-json` chunks. Concatenate the
+decoded bytes and parse JSON only after `hasMore` becomes false. Page and entry
+cursors are opaque and revision-bound; a changed transcript produces an
+explicit resync error, so restart from a fresh observation. The shared daemon's
+legacy `session.transcript` method rejects payloads above 512 KiB and names the
+page/chunk methods rather than attempting a frame near the 8 MiB ceiling.
+
+### Search compacted history before fetching exact content
+
+Use `transcriptSearch()` when the host or user knows a historical detail but
+not its page/index. It searches the authoritative main-plus-sidecar lineage and
+returns bounded revision-bound hits with stable `entryId`/`logicalId`, entry
+index, role/source, timestamp, active/compacted status, and a citation:
+
+```ts
+const found = await runtime.sessions.transcriptSearch({
+  sessionId: session.id,
+  query: 'permission test output capture',
+  role: 'assistant',
+  limit: 5,
+});
+
+for (const hit of found.hits) {
+  renderSearchHit(hit.citation, hit.snippet);
+  // For an oversized exact entry, pass found.revision + hit.entryIndex to
+  // transcriptEntryChunk(); ordinary entries can be obtained from the page.
+}
+```
+
+Search is deterministic Unicode lexical/metadata ranking, not an embedding or
+background-model index. The Action LLM gets the corresponding
+`session_history_search` and `session_history_read` pair only when its current
+Run owns full-lineage-capable Session storage. A root Run reads its root
+lineage. A persistent child Run gets a separately minted hidden
+`managed-task-worker` Session and can recover only that child's compacted
+history; it is never given root-history access. Storage-less Runs and a tool
+visibility policy that hides either member expose neither member. Results are
+low-authority historical evidence; current instructions and freshly verified
+workspace state take precedence. System/control entries, hidden-only content,
+synthetic current or legacy `[对话历史摘要]` checkpoints, and `[compacted]`
+placeholders are neither searchable nor directly readable. Short ordinary
+terms do not gain a metadata match merely because they occur inside a random
+entry ID; direct identifier lookup is reserved for a sufficiently specific ID
+query. Sessions compacted by older builds without an exact main/sidecar copy
+cannot reconstruct bytes that were already discarded.
+
+Clients that depend on these guarantees should require
+`contextCompaction: 3`, `transcriptPaging: 1`, and `transcriptSearch: 1` during
+connection.
+
+---
+
+## 26. Agent mailbox control versus SDK event telemetry (v0.7.74)
+
+The model-visible `wait_agent` tool and the public Runtime Actor event APIs have
+different jobs. Do not expose `runtime.agents.wait()` to the model as though it
+were the same operation.
+
+| Need | API | Wake/data contract |
+|---|---|---|
+| Let the action model yield until useful coordination evidence exists | `wait_agent({ timeout_ms })` | Caller-scoped Agent mailbox, root user input, interruption, or timeout; returns only a small acknowledgement. |
+| Render or diagnose Actor activity | `runtime.agents.events(sessionId, afterSequence?)` | Bounded event snapshot/replay, including progress and terminal events. |
+| Long-poll Actor telemetry from a host | `runtime.agents.wait(sessionId, afterSequence?, timeoutMs?)` | Returns the next sequenced Actor event, including progress. |
+| Read one known result | `runtime.agents.output(sessionId, actorPath, turnId?)` | Bounded current/terminal output and structured artifact metadata. |
+| Deliver a real user follow-up to the active root Run | `runtime.runs.submitInput(...)` | Ordered active-run input delivered at the next safe Runner boundary; requires `interruptInput:1`. |
+
+For example, a host activity view can replay the current tail and then wait
+from its last sequence without causing another action-model request:
+
+```ts
+const snapshot = await runtime.agents.events(session.id);
+for (const event of snapshot) renderActorEvent(event);
+
+const afterSequence = snapshot.at(-1)?.sequence;
+const next = await runtime.agents.wait(session.id, afterSequence, 30_000);
+if (next) renderActorEvent(next);
+```
+
+Model `wait_agent` has only `timeout_ms` in its schema (10,000 to 3,600,000 ms,
+default 120,000). Actor progress and Runtime `system-reminder` messages do not
+end that wait. A scoped Agent message/completion produces `mailbox`; queued root
+input produces `user_input_pending`; cancellation and expiry produce
+`interrupted` and `wait_expired`. Authenticated Agent evidence is drained at the
+next safe Runner boundary as synthetic context, while root input remains a real
+user turn. The acknowledgement itself never carries raw event batches.
+
+Completion delivery is post-transcript and crash-recoverable. The Actor snapshot
+persists the explicit root completion turn IDs that still await transcript
+acknowledgement. A hard restart republishes only those IDs; a same-process
+Runtime rebuild deduplicates the projected queue by child turn ID. Once the
+parent transcript commits and acknowledges the completion, later restores do
+not replay it. Legacy snapshots without the explicit pending set do not infer
+replay work from historical mailbox content.
+
+This separation changes no Actor event capability or daemon version: existing
+SDK snapshot, replay, and long-poll clients keep their telemetry surface. It
+only prevents high-frequency progress from becoming a model control signal.
 
-The callback belongs in a trusted host process (for Electron, Main rather than
-renderer). It is intentionally not inferred from the presence of a permission
-UI: tool permission and plan approval are different user decisions.
+---
 
-See [ADR-056](ADR.md#adr-056-runtime-owns-auto-mode-permission-decisions-and-host-capability-exposure)
-for the ownership decision, [the v0.7.72 design](features/v0.7.72.md#2026-07-18-runtime-permission-queue-and-resume-closure)
-for the release boundary, and [Known Issue 187](KNOWN_ISSUES.md#187-shared-daemon-auto-permission-ownership-upgrade-fencing-preview-bounds-and-sdk-compatibility-were-incomplete)
-for the final capability-upgrade and compatibility closure.
+## 27. Windows GUI background subprocess visibility (v0.7.75)
+
+KodaX SDK hosts do not need to add process-wide console suppression around the
+Runtime. In the v0.7.75 release candidate, Runtime Worker-reachable
+non-interactive/background child processes request `windowsHide: true` at their
+own spawn boundary. The covered paths include:
+
+- memory and Git metadata probes;
+- provider CLI execution and ACP servers;
+- LSP acquisition and language servers;
+- clipboard helpers, worktrees, review commands, and extension commands;
+- managed-task checkpoints and sandbox helpers.
+
+The contract is intentionally narrow. Explicit external editors, terminal
+commands, and PTY sessions remain interactive. POSIX-only `ps`, `tmux`, and
+sandbox branches are reviewed bundle-audit exceptions rather than Windows
+visibility paths.
+
+`npm run build:bundle` audits every statically identifiable child-process call
+reachable from `dist/runtime-worker.js`. The packaged Electron daemon smoke then
+runs 20 ordinary queries with a Win32 probe and checks that the expected Git
+children never own a visible console window. These checks validate the SDK
+boundary, but they do not replace product-level validation in the packaged host.
+KodaX Space should install the exact v0.7.75 tarball and complete
+[`ISSUE_205_v0.7.75_REGRESSION_GUIDE.md`](test-guides/ISSUE_205_v0.7.75_REGRESSION_GUIDE.md)
+on Windows 10 and Windows 11 as a non-blocking product validation follow-up.
+This follow-up does not gate SDK packaging, tagging, or publication.
 
 ---
 
@@ -4348,4 +4650,8 @@ for the final capability-upgrade and compatibility closure.
 - [README.md](../README.md) — end-user CLI quick start
 - [docs/ADR.md ADR-024](ADR.md#adr-024-npm-发布物正名-kodax-aikodax--sdk-subpath-exports-形式化-v0739) — SDK subpath architecture rationale
 - [docs/ADR.md ADR-032](ADR.md#adr-032-sdk-embedder-surface-closure-feature_186-v0742) — FEATURE_186 design record (all 8 phases)
-- [docs/features/v0.7.42.md FEATURE_186](features/v0.7.42.md#feature_186-sdk-embedder-surface-closure--kodax-space-gap-list--mcp-popout) — gap-by-gap landing matrix
+- [docs/ADR.md ADR-057](ADR.md#adr-057-large-compaction-is-an-always-on-context-scoped-full-coverage-transaction) — v0.7.74 compaction and exact-history ownership
+- [docs/ADR.md ADR-058](ADR.md#adr-058-model-agent-wait-is-mailbox-control-not-event-telemetry) — mailbox control versus Actor telemetry
+- [docs/features/v0.7.42.md FEATURE_186](features/v0.7.42.md#feature_186-sdk-embedder-surface-closure--kodax-space-gap-list--mcp-popout) — gap-by-gap landing matrix
+- [docs/features/v0.7.74.md](features/v0.7.74.md) — v0.7.74 release-candidate design and verification record
+- [docs/features/v0.7.75.md](features/v0.7.75.md) — v0.7.75 Windows GUI and Sidecar/Runtime stabilization candidate