@kodax-ai/kodax 0.7.78 → 0.7.80

package/docs/SDK_EMBEDDER_GUIDE.md

@@ -28,17 +28,17 @@ are NOT obvious from inspecting the type definitions alone:
 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--feature_275-v0768v0777)
+21. [Experimental governed memory — `/experimental-memory`](#21-experimental-governed-memory--experimental-memory-feature_260--feature_275-v0768v0777)
 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)
-28. [Host-configurable Shell Execution Contract](#28-host-configurable-shell-execution-contract-v0777)
-29. [Evidence-gated background Skill learning](#29-evidence-gated-background-skill-learning-feature_263-v0778)
-30. [Standalone sandbox SDK](#30-standalone-sandbox-sdk-v0778)
-- [Learned Skill promotion reference](#learned-skill-promotion-reference-v0778)
+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)
+28. [Host-configurable Shell Execution Contract](#28-host-configurable-shell-execution-contract-v0777)
+29. [Evidence-gated background Skill learning](#29-evidence-gated-background-skill-learning-feature_263-v0778)
+30. [Standalone sandbox SDK](#30-standalone-sandbox-sdk-v0778)
+- [Learned Skill promotion reference](#learned-skill-promotion-reference-v0778)
 
 §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)).
@@ -678,7 +678,10 @@ missing-storage warning by itself.
 
 ```ts
 import { runKodaX } from '@kodax-ai/kodax/coding';
-import { createSessionManager } from '@kodax-ai/kodax/session';
+import {
+  createSessionManager,
+  exportSessionBundle,
+} from '@kodax-ai/kodax/session';
 
 // One manager per host process; reuse across runs so the
 // per-session write queue + append-watermark caches stay coherent.
@@ -687,6 +690,8 @@ const {
   listSessions,
   loadSession,
   loadFullTranscript,
+  readFullTranscript,
+  readSessionCapture,
   appendClientNotice,
   compactSession,
 } = createSessionManager();
@@ -720,6 +725,17 @@ const nextPage = recent.at(-1)?.cursor
   : [];
 const replay = await loadSession('s_my_chat');
 const scrollback = await loadFullTranscript('s_my_chat');
+const historyAbort = new AbortController();
+const strictScrollback = await readFullTranscript('s_my_chat', {
+  timeoutMs: 15_000,
+  signal: historyAbort.signal,
+});
+const capture = await readSessionCapture('s_my_chat', {
+  timeoutMs: 15_000,
+});
+const bundle = await exportSessionBundle('s_my_chat', {
+  timeoutMs: 15_000,
+});
 const compacted = await compactSession('s_my_chat', { dryRun: true });
 
 await appendClientNotice('s_my_chat', {
@@ -728,6 +744,14 @@ await appendClientNotice('s_my_chat', {
 });
 ```
 
+`readSessionCapture()` returns the active `data` and full `transcript` from one
+immutable storage boundary. `readFullTranscript()` and
+`readSessionCapture()` are strict read-only APIs: timeout/cancellation,
+corruption, version drift, or resync fail explicitly and never trigger legacy
+Session migration or recovery. `exportSessionBundle()` preserves the exact
+main/sidecar bytes with hashes and compatibility diagnostics; use it for a
+support or recovery bundle, not as proof that a Session can resume.
+
 ### Auto-resume selection in v0.7.74
 
 With `session.autoResume: true` (or `resume: true`) and no explicit ID, KodaX
@@ -751,6 +775,9 @@ interface SessionManager {
   listSessions(...): Promise<SessionSummary[]>;
   loadSession(id): Promise<...>;
   loadFullTranscript(id): Promise<...>;
+  readFullTranscript(id, options?): Promise<...>;
+  readConversationHistory(id, options?): Promise<...>;
+  readSessionCapture(id, options?): Promise<SessionReadCapture | null>;
   appendClientNotice(id, opts): Promise<SessionTranscriptEntry | null>;
   compactSession(id, opts?): Promise<CompactSessionResult>;
   forkSession(id, opts?): Promise<...>;
@@ -776,13 +803,22 @@ Session persistence exposes three related but different layers:
 | Need | Use | Meaning |
 |---|---|---|
 | Continue a model turn | `loadSession(id)` | Active branch only. This is the context KodaX would resume from. |
-| Render a host sidebar / scrollback | `loadFullTranscript(id)` | Append-order transcript entries, including entries no longer on the active branch when available. |
+| Render the ordinary conversation | `readConversationHistory(id)` | SDK-resolved conversation order with proven compaction copies folded and ambiguity reported. |
+| Render audit / raw scrollback | `readFullTranscript(id)` or `loadFullTranscript(id)` | Append-order physical entries, including archived islands and non-active branches. |
 | Reuse TUI display projection | `SessionData.uiHistory` | Optional bounded replay cache. Interactive REPL sessions may write it; headless SDK sessions may not. |
 
-For product UI, prefer `loadFullTranscript(id)` for conversation history and
-treat `loadSession(id)` as the model-context API. Do not assume `uiHistory`
-exists. It is intentionally a small, lossy replay cache; canonical facts remain
-in `messages` / `lineage`.
+For product UI, use `readConversationHistory(id)` for the ordinary chat and
+keep `readFullTranscript(id)` available for an audit/details view.
+`loadSession(id)` remains the model-context API. Do not assume `uiHistory`
+exists; it is intentionally a small, lossy replay cache.
+
+`loadSession(id)` and Runtime `sessions.load(id)` are pure snapshot reads. They
+do not emit `session.loaded`; a host that explicitly loads a snapshot should
+update its own selected/loaded UI state from the resolved promise. The
+compatibility `session.loaded` event (and the CLI bridge's `onSessionStart`)
+remains bound to the Provider Run execution boundary, where a Session actually
+becomes active. Do not use that Run-lifecycle event as a generic data-load
+notification.
 
 `loadFullTranscript(id).transcriptEntries` is the structured host-facing
 scrollback. Each entry has stable ownership and ordering fields:
@@ -806,14 +842,145 @@ interface SessionTranscriptEntry {
 
 `entryId` is the physical lineage node id. `logicalId` is stable across
 forked/cloned copies of the same transcript item, and `sourceEntryId` is present
-on cloned entries to point back to the root physical source entry. Hosts that
-want to fold cloned history should group by `logicalId`, not by
-`message.role`, content, timestamp, or `[compacted]` placeholders.
+on cloned entries to point back to the root physical source entry. These fields
+support audit inspection, but a host must not infer the complete ordinary-chat
+fold merely by grouping them: legacy omissions and conflicting metadata require
+lineage validation. Use `readConversationHistory()` instead of implementing
+host-side folding, and never guess from `message.role`, content, timestamp,
+`turnId`, or `[compacted]` placeholders.
 Legacy entries without persisted provenance use `logicalId === entryId` and omit
 `sourceEntryId`; treat that as "unknown/not cloned", not as content-based proof
 that no older clone exists.
 `loadFullTranscript()` still returns raw append-order scrollback; it does not
-hide compaction notices or silently merge branches.
+hide archived islands or non-active branches, and it does not silently merge
+branches. The host owns branch visibility, folding, and main-chat presentation.
+
+`readConversationHistory()` is the supported folding boundary. Every returned
+entry has a physical `boundaryId` and `auditEntryIds` naming all copies that the
+SDK could prove represent the same interaction. Modern Sessions use
+`logicalId` / `sourceEntryId`; legacy copies are folded only when a persisted
+compaction boundary and one unique lineage suffix prove the relationship.
+An inactive compaction epoch or non-leaf ancestor is crossed only when a
+contiguous retained prefix has exact provenance and its complete parent path
+predates the compaction in append order. Content-only legacy matching never
+authorizes that fallback.
+KodaX never globally sorts or deduplicates by content, timestamp, or `turnId`.
+
+The result status is part of the contract:
+
+- `resolved`: every fold and branch predecessor used by the projection was
+  proven. A persisted Session with no conversation records is also resolved
+  with empty `entries` and `issues`, including the normal interval after a Run
+  is accepted but before its body enters canonical history.
+- `partial`: persisted lineage or transcript identity needed for a complete
+  projection of one or more existing conversation records is unavailable.
+  Available physical records are retained; Actor/Run state by itself does not
+  make an otherwise empty persisted conversation partial.
+- `ambiguous`: multiple legacy interpretations remain. All candidates are
+  retained and `issues[]` explains why; the host must not present the result as
+  confidently deduplicated.
+
+Issues are bounded diagnostic summaries: `occurrenceCount` is the number of
+diagnostics represented, `entryCount` is the pre-bounding evidence-reference
+count, and `entryIds` is a bounded exact sample. Conversation entries themselves
+are never removed to make diagnostic metadata fit a transport page.
+
+Runtime exposes the identical projection in embedded and daemon modes through
+`sessions.conversation()`, `sessions.conversationPage()`, and
+`sessions.conversationEntryChunk()`. Modern Session writes prepare a bounded
+on-disk page index, so the first finite page reads only its metadata, fixed-size
+index records, and requested inline bodies instead of materializing all history.
+A source-boundary-fenced copy of the Session's minimal admission identity lets
+the shared daemon authorize that bounded read before checking cursors, capacity,
+or entry metadata; it does not perform a full Session `peek()` on a cache hit.
+A cache-less older Session is upgraded by one canonical fallback read. Direct
+and paged reads share the same `revision`, `sourceRevision`, status, issues, and
+logical entry order. Page and chunk cursors are revision-fenced: if the Session
+changes, the Runtime returns `resync_required` and the host must request a fresh
+first page. Derived manifest, descriptor, and chunk reads have fixed allocation
+ceilings; a corrupt or concurrently replaced generation is rejected rather
+than trusted. Pages are fetched newest-tail-first while each page is internally in
+forward order, so prepend each fetched page to reconstruct `conversation().entries`;
+do not append pages in fetch order.
+Request `requirements: { conversationHistory: 1 }` when connecting to a daemon
+that must support this contract.
+
+For write-side hosts that already own a newly produced append tail,
+`await FileSessionStorage.prepareSessionAppend(id)` returns an authenticated
+one-shot boundary or `null` when no canonical cache witness is available.
+`appendPreparedSessionTail(id, delta)` appends only the supplied new linear
+lineage, artifact, and extension records. The delta deliberately has no
+historical-array field: its read and compute cost is bounded by the new tail,
+and a stale boundary, prefix/sidecar change, duplicate identity, non-linear
+lineage tail, or concurrent durable write fails with
+`SessionReadError.code === 'data_changed'`. Reload, obtain a fresh boundary,
+and rebuild the tail before retrying.
+
+A non-null fulfilled append result is the reusable successor boundary. A
+fulfilled `null` means the tail did commit exactly once, but the successor
+could not be witnessed; reload before another append and do not retry that
+tail. Use `appendSessionDelta(id, data)` for a full mutable snapshot, a `null`
+prepared boundary, or any historical rewrite; that API performs the exact
+canonical merge and persists index, nested-object, and post-helper mutations.
+Data returned by `storage.load()` remains an ordinary mutable,
+`structuredClone()`-compatible `KodaXSessionData` object. The derived page
+cache is only a recoverable acceleration structure: its fixed-size identity
+filter is accepted for appends only when its exact bundle revision and hash
+match canonical metadata in the Session main file.
+
+```ts
+const baseline = await storage.prepareSessionAppend(sessionId);
+if (baseline === null) {
+  await storage.appendSessionDelta(sessionId, completeMutableSnapshot);
+} else {
+  const successor = await storage.appendPreparedSessionTail(sessionId, {
+    baseline,
+    title,
+    activeEntryId: newEntry.id,
+    lineageEntries: [newEntry],
+  });
+  if (successor === null) {
+    await storage.load(sessionId); // committed; resync before the next tail
+  }
+}
+```
+
+Use a returned entry as a revision-fenced fork or rewind boundary instead of
+guessing from content or a historical `turnId`:
+
+```ts
+const history = await runtime.sessions.conversation(sessionId);
+const item = history?.entries.find((entry) => entry.boundaryId !== undefined);
+if (history && item?.boundaryId) {
+  await runtime.sessions.fork({
+    sessionId,
+    historyBoundary: {
+      entryId: item.boundaryId,
+      sourceRevision: history.sourceRevision,
+    },
+  });
+}
+```
+
+If the Session changes before the mutation, the Runtime returns
+`resync_required`; an unknown boundary returns `null` and never falls back to a
+different point.
+
+The standalone session API accepts the same boundary (named `boundaryId` on
+that surface) and fails closed with `null`:
+
+```ts
+const history = await manager.readConversationHistory(sessionId);
+const item = history?.entries.at(-1);
+if (history && item?.boundaryId) {
+  await manager.forkSession(sessionId, {
+    historyBoundary: {
+      boundaryId: item.boundaryId,
+      sourceRevision: history.sourceRevision,
+    },
+  });
+}
+```
 
 Since v0.7.63, rewind audit markers are represented as
 `type: 'rewind_marker'`. They are useful for host scrollback and audit UI, but
@@ -1328,7 +1495,8 @@ interface KodaXModelCapabilities {
     supportedEfforts?: Array<{ value: string; isDefault?: boolean; isUserVisible?: boolean }>;
   };
   contextWindow?: number;           // input tokens (provider default + per-model override cascade)
-  maxOutputTokens?: number;         // per-turn max_tokens KodaX requests — see note below
+  maxOutputTokens?: number;         // per-turn output limit KodaX requests — see note below
+  maxOutputTokensField?: 'max_tokens' | 'max_completion_tokens';
   thinkingBudgetCap?: number;       // tokens (native-budget providers only)
   isDefault: boolean;               // true for the provider's default model
 }
@@ -1435,9 +1603,10 @@ for (const providerName of Object.keys(KODAX_PROVIDER_SNAPSHOTS)) {
 
 ### A note on `maxOutputTokens`
 
-`KodaXModelCapabilities.maxOutputTokens` is the **per-turn `max_tokens`
-KodaX requests**, NOT the upstream "theoretical maximum". The two
-diverge because:
+`KodaXModelCapabilities.maxOutputTokens` is the **per-turn output-token limit
+KodaX requests**, NOT the upstream "theoretical maximum". For OpenAI-compatible
+routes, `maxOutputTokensField` reports whether that limit is serialized as
+`max_tokens` or `max_completion_tokens`. The two size concepts diverge because:
 
 - **What upstream advertises is often unreliable.** A 2026-05 probe
   against `zhipu-coding` / `kimi-code` / `minimax-coding` / `ark-coding`
@@ -1951,10 +2120,19 @@ registerCustomProviders([{
   baseUrl: 'https://api.example.com/v1',
   apiKeyEnv: 'MY_GATEWAY_KEY',
   model: 'gpt-4-mini',
+  maxOutputTokensField: 'max_completion_tokens',
   verifyStrategy: 'minimal-message',  // optional override
 }]);
 ```
 
+For an OpenAI-compatible endpoint that follows DeepSeek Chat Completions, set
+`maxOutputTokensField: 'max_tokens'`. The default is
+`max_completion_tokens`; an object entry in `models[]` may override the
+provider-level value for a mixed gateway. DeepSeek V4 custom configurations
+should likewise use the model-specific `deepseek-v4-flash-openai` or
+`deepseek-v4-pro-openai` reasoning preset. Both built-in DeepSeek V4 routes are
+text-only.
+
 The validator rejects illegal combinations:
 - `protocol: 'openai'` + `verifyStrategy: 'count-tokens'` → throws (OpenAI protocol has no count_tokens endpoint).
 
@@ -2385,6 +2563,7 @@ The important creation options are:
 | `isolation` | `'inline'` | Embedded-only. `'worker'` creates a private Runtime Worker; daemon rejects any explicit isolation because it is already process-isolated. |
 | `worker.resourceLimits` | unset | Optional V8 heap/stack limits; requires `isolation: 'worker'`. |
 | `worker.shutdownTimeoutMs` | `2000` | Grace before the parent terminates the Runtime Worker. |
+| `worker.configuredA2A` | `false` | Explicitly lets the Worker owner load and reconcile `<homeDir>/.kodax/integrations/a2a.json`; installs the full list/describe/spawn/task plane inside the 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`. |
 | `profile` | `'default'` | Daemon uniqueness and runtime configuration namespace. |
@@ -2472,6 +2651,15 @@ SDK auto-start allows `daemonStartupTimeoutMs` (default 60 seconds) and
 concurrent test/desktop startup without weakening PID, endpoint, token, or
 runtime-identity validation.
 
+On Windows, current child cleanup verifies observed process identities and
+reports indeterminate outcomes instead of falling back to bare-PID success.
+That is not Job Object-grade containment: if an intermediate process exits
+between snapshots, an already-running descendant can become unobservable.
+Until Issue 256 is resolved (scheduled for v0.7.84) with spawn-time Job Object
+assignment and a host-issued Worker owner lease, embedders must not treat
+Runtime/Worker close or executor cleanup as proof that every descendant has
+terminated.
+
 `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
@@ -2493,7 +2681,9 @@ const runtime = await createKodaXRuntime({
   worker: {
     resourceLimits: { maxOldGenerationSizeMb: 1024 },
     shutdownTimeoutMs: 2000,
+    configuredA2A: true,
   },
+  requirements: { externalAgents: true },
 });
 
 try {
@@ -2515,6 +2705,12 @@ Worker `resourceLimits` bound parts of the V8 heap only. They do not cover every
 kind of native/external memory and do not make Node code safe to treat as
 untrusted. Worker isolation is a fault boundary, not a security sandbox.
 
+Configured A2A is loaded by the Worker owner, not serialized from a parent
+factory closure. `worker.configuredA2A` is therefore an explicit opt-in. When
+enabled, the Worker reconciles the same user document as the CLI/daemon path,
+advertises `externalAgents`, and backs `listDispatchable`, `describe`,
+`preflight`, and external Actor dispatch with one real executor plane.
+
 Callers that cannot accept a silent fallback can require the capability:
 
 ```ts
@@ -2543,6 +2739,33 @@ The same method name deliberately has deployment-specific ownership effects:
 automatically retry or replay an in-flight run after a Worker/daemon owner dies,
 because provider and tool side effects may already have happened.
 
+`runtime.shutdown` and `stopForInline()` responses mean the fenced stop was
+accepted; host-close logging and owner-lock release are also intermediate
+progress boundaries. A successful `kodax daemon stop` / `restart` additionally
+waits for the original daemon PID to disappear and verifies a shutdown-success
+outcome bound to that exact Runtime ID and PID. Before that process exits, the
+serve host completes bounded A2A/extension, LSP, managed-child-tree, and tracing
+cleanup; an unverified current-owner child tree, cleanup timeout, failed outcome,
+or missing outcome makes CLI stop fail instead of reporting a false success.
+The stop client also owns an outer watchdog that starts when the request is
+accepted. On Windows it captures the daemon's creation identity before
+requesting shutdown and can therefore reclaim that exact process tree if
+Runtime close never settles or synchronous code blocks the daemon event loop.
+Node 20 exposes only cached-PID signaling on POSIX, so KodaX fails closed there
+instead of risking a reused PID/PGID; the result is `cleanup_unverified` and the
+process is left to an external lifecycle manager until Issue 269 supplies a
+retained native handle/supervisor. A forced exit without a matching success
+outcome is never success. After the original PID exits, the client re-reads the profile; JSON
+results use `replacementRunning: true` and return the current state/health when
+a replacement daemon has already acquired the owner lock. Such a result also
+uses `stopped: false` and `reason: 'replacement_running'`, so existing callers
+that gate cleanup on `stopped` remain safe. Callers must not clean or rebuild a
+profile while that flag is present or health is non-missing.
+The administrative connection also verifies that `initialize.identity` still
+matches the Runtime ID/profile observed before connecting; if an old owner exits
+and a replacement binds the same endpoint first, the stale stop command fails
+without sending `daemon.stop` to the replacement.
+
 ### Daemon ownership and state
 
 Daemon ownership is scoped by `homeDir + profile`.
@@ -2591,7 +2814,9 @@ Operational guidance:
   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;
+  before deleting their temporary home; use the CLI command when the caller
+  needs a completed process-exit boundary, because `runtime.close()` only
+  detaches and the low-level shutdown response is acceptance, not completion;
 - 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;
@@ -2779,11 +3004,11 @@ await runtime.mcp.upsertServer('filesystem', {
 });
 await runtime.mcp.reloadServers();
 
-const commands = await runtime.catalog.commands(process.cwd());
-const skills = await runtime.catalog.skills({ projectRoot: process.cwd() });
-```
-
-This is the intended path for KodaX Space, IDE adapters, and settings UIs:
+const commands = await runtime.catalog.commands(process.cwd());
+const skills = await runtime.catalog.skills({ projectRoot: process.cwd() });
+```
+
+This is the intended path for KodaX Space, IDE adapters, and settings UIs:
 session defaults go through `sessions.updateSettings()`, one-turn overrides go
 through `runs.start({ options })`, and daemon/profile config goes through
 `config`, `catalog`, and `mcp`.
@@ -2803,19 +3028,19 @@ engine:
 Hosts that set `capabilities.contextDiagnostics: true` can read:
 
 ```ts
-const budget = await runtime.diagnostics.latestContextBudget({ sessionId });
-const exposure = await runtime.diagnostics.latestToolExposure({ sessionId });
-const cache = await runtime.diagnostics.latestProviderCacheDiagnostic({ sessionId });
-```
-
-Pass `{ sessionId, contextKind: 'child', agentId }` to query one logical child
-even though its physical transcript uses an isolated Session. Diagnostic
-payloads carry `contextId` and, for children, `parentContextId`; reconnecting
-hosts can use the same latest APIs instead of fabricating identity fields.
-These diagnostics are designed for status panels and debugging. Budget
-snapshots contain counts, and cache diagnostics contain hashes plus
-Provider-reported usage; they do not contain raw prompt or sensitive tool
-input/output.
+const budget = await runtime.diagnostics.latestContextBudget({ sessionId });
+const exposure = await runtime.diagnostics.latestToolExposure({ sessionId });
+const cache = await runtime.diagnostics.latestProviderCacheDiagnostic({ sessionId });
+```
+
+Pass `{ sessionId, contextKind: 'child', agentId }` to query one logical child
+even though its physical transcript uses an isolated Session. Diagnostic
+payloads carry `contextId` and, for children, `parentContextId`; reconnecting
+hosts can use the same latest APIs instead of fabricating identity fields.
+These diagnostics are designed for status panels and debugging. Budget
+snapshots contain counts, and cache diagnostics contain hashes plus
+Provider-reported usage; they do not contain raw prompt or sensitive tool
+input/output.
 
 ### Protocol schema and versioning
 
@@ -2834,7 +3059,11 @@ import {
 The schema is additive within this patch line. Removing or changing required
 fields requires a protocol version bump.
 
-### Current verification status
+### v0.7.69 Runtime verification record
+
+This subsection is the historical verification record for the original shared
+Runtime delivery. Current 0.7.80 release gates and evidence live in
+[`docs/release.md`](release.md#v0780-release-preparation).
 
 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
@@ -2912,7 +3141,7 @@ daemon DTO boundary. Install factories where the Runtime owner executes:
 | 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. |
+| Runtime Worker | Use `worker: { configuredA2A: true }` for the built-in configured A2A plane. Custom factories must still be installed by a custom Worker owner; passing function-valued `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
@@ -3230,7 +3459,7 @@ workflow's structured findings, verification results, and quality gates.
 
 ---
 
-## 21. Experimental governed memory — `/experimental-memory` (FEATURE_260 + FEATURE_275, v0.7.68–v0.7.77)
+## 21. Experimental governed memory — `/experimental-memory` (FEATURE_260 + FEATURE_275, v0.7.68–v0.7.77)
 
 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
@@ -3291,53 +3520,53 @@ await session.complete({
 await session.close();
 ```
 
-`recall()` is synchronous and exact. `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.
-
-### Sparse foreground intervention (FEATURE_275, v0.7.77)
-
-`MemorySession.intervene()` replaces the old timing-ineffective semantic
-prefetch. It is awaited only after `tool_failure`, `verification_failure`, or a
-durably committed `context_compacted` event, then supplies at most three
-prompt-safe, low-authority evidence items to the next Action-LLM request. The
-candidate set is rebuilt from current objective/open todos, recent governed
-observations, and a fresh F228 pack. Exact selection is deterministic; stale,
-unknown, malformed, timed-out, cancelled, or failed semantic results are
-discarded without blocking the coding run.
-
-Top-level coding runs wire the deterministic path automatically and make zero
-selector calls by default. An inline host that deliberately wants semantic
-selection can provide the coding-owned forced-tool runner:
-
-```ts
-import {
-  createCodingMemoryInterventionRunner,
-  runKodaX,
-} from '@kodax-ai/kodax/coding';
-import { resolveProvider } from '@kodax-ai/kodax/llm';
-
-const memoryRecallRunner = createCodingMemoryInterventionRunner({
-  provider: resolveProvider('zhipu-coding'),
-  model: 'glm-5.2',
-});
-
-await runKodaX(
-  {
-    provider: 'zhipu-coding',
-    model: 'glm-5.2',
-    memoryRecallRunner,
-  },
-  'Finish the repository migration and verify it.',
-);
-```
-
-`memoryRecallRunner` is a process-local function binding. Worker and daemon DTO
-options reject it instead of silently dropping it; configure the binding
-inside the Runtime owner or keep this run inline. The selector can return only
-exact IDs from the closed offered set and is capped at three calls per memory
-Session.
+`recall()` is synchronous and exact. `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.
+
+### Sparse foreground intervention (FEATURE_275, v0.7.77)
+
+`MemorySession.intervene()` replaces the old timing-ineffective semantic
+prefetch. It is awaited only after `tool_failure`, `verification_failure`, or a
+durably committed `context_compacted` event, then supplies at most three
+prompt-safe, low-authority evidence items to the next Action-LLM request. The
+candidate set is rebuilt from current objective/open todos, recent governed
+observations, and a fresh F228 pack. Exact selection is deterministic; stale,
+unknown, malformed, timed-out, cancelled, or failed semantic results are
+discarded without blocking the coding run.
+
+Top-level coding runs wire the deterministic path automatically and make zero
+selector calls by default. An inline host that deliberately wants semantic
+selection can provide the coding-owned forced-tool runner:
+
+```ts
+import {
+  createCodingMemoryInterventionRunner,
+  runKodaX,
+} from '@kodax-ai/kodax/coding';
+import { resolveProvider } from '@kodax-ai/kodax/llm';
+
+const memoryRecallRunner = createCodingMemoryInterventionRunner({
+  provider: resolveProvider('zhipu-coding'),
+  model: 'glm-5.2',
+});
+
+await runKodaX(
+  {
+    provider: 'zhipu-coding',
+    model: 'glm-5.2',
+    memoryRecallRunner,
+  },
+  'Finish the repository migration and verify it.',
+);
+```
+
+`memoryRecallRunner` is a process-local function binding. Worker and daemon DTO
+options reject it instead of silently dropping it; configure the binding
+inside the Runtime owner or keep this run inline. The selector can return only
+exact IDs from the closed offered set and is capped at three calls per memory
+Session.
 
 ### Evidence, tracing, and persistence boundaries
 
@@ -3347,11 +3576,11 @@ Session.
   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
-  offered `candidateIds`, validated `selectedCandidateIds`, exposed
-  `injectedEvidenceRefs`, triggers, and later outcome influence. Receipts are
-  trace-only and contain no hidden reasoning; exposure is not proof of
-  causality.
+- `onTrace` receives policy-versioned `MemoryDecisionReceipt` metadata that links
+  offered `candidateIds`, validated `selectedCandidateIds`, exposed
+  `injectedEvidenceRefs`, triggers, and later outcome influence. Receipts are
+  trace-only and contain no hidden reasoning; exposure is not proof of
+  causality.
 - 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.
@@ -3502,6 +3731,23 @@ kodax a2a test reviewer
 kodax a2a call reviewer "Review this document"
 ```
 
+Private-address access and plaintext HTTP beyond exact loopback are independent
+persisted permissions. Both default to false; private HTTP requires both:
+
+```bash
+kodax a2a add intranet http://10.20.30.40/.well-known/agent-card.json \
+  --allow-private --allow-insecure-http --effect read
+```
+
+Private HTTPS requires only `--allow-private`. Public HTTP requires only
+`--allow-insecure-http`, but TLS remains the recommended deployment. The flags
+are persisted under the Agent's `network` block and are honored by Card
+discovery, interface execution, Runtime registration, and task execution.
+Private-address permission also applies to HTTPS OAuth endpoints, but OAuth
+token endpoints deliberately retain the stricter HTTPS-or-exact-loopback
+protocol rule; Agent-transport plaintext authorization does not weaken OAuth.
+`a2a test` and `a2a call` also accept the flags as one-shot overrides.
+
 The no-code OAuth path stores only the environment-variable name for the client
 secret. It can be staged disabled and hot-activated later:
 
@@ -3524,8 +3770,9 @@ 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.
+registration accepts public HTTPS and exact loopback targets; private-address
+and non-loopback plaintext access require their independent persisted operator
+permissions.
 
 `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
@@ -3699,16 +3946,16 @@ const server = createKodaXA2AServer({
   },
 });
 
-// Development only: the built-in listener refuses non-loopback hosts.
-const localBaseUrl = await server.listen({ hostname: '127.0.0.1', port: 0 });
-```
-
-The listener also refuses an explicit port blocked by WHATWG Fetch clients.
-With `port: 0`, it retries ephemeral allocation rather than returning a URL
-that Fetch would reject before connecting.
-
-Production hosts route `GET /.well-known/agent-card.json` and canonical
-JSON-RPC `POST /a2a` to `server.handle(request)` behind their own TLS
+// Development only: the built-in listener refuses non-loopback hosts.
+const localBaseUrl = await server.listen({ hostname: '127.0.0.1', port: 0 });
+```
+
+The listener also refuses an explicit port blocked by WHATWG Fetch clients.
+With `port: 0`, it retries ephemeral allocation rather than returning a URL
+that Fetch would reject before connecting.
+
+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
@@ -3792,14 +4039,14 @@ 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,
-  // Opt in only when this product remains the visible owner of the daemon.
-  // If the product crashes, the daemon stops after its final client is gone
-  // and governed work becomes idle.
-  daemonOrphanExitMs: 30_000,
-  homeDir: coderRuntimeBaseDir, // owns <coderRuntimeBaseDir>/.kodax
+const runtime = await connectKodaXRuntime({
+  profile: 'coder',
+  autoStart: true,
+  // Opt in only when this product remains the visible owner of the daemon.
+  // If the product crashes, the daemon stops after its final client is gone
+  // and governed work becomes idle.
+  daemonOrphanExitMs: 30_000,
+  homeDir: coderRuntimeBaseDir, // owns <coderRuntimeBaseDir>/.kodax
   clientInfo: {
     name: 'kodax-space',
     version: '0.1.32',
@@ -3831,10 +4078,11 @@ const runtime = await connectKodaXRuntime({
     sharedSessionSettings: 1,
     durableRecoveryQueries: 1,
     daemonManagement: 1,
-    runtimeAutoModeGuardrail: 4,
-  },
-});
-```
+    runtimeEventCoalescing: 1,
+    runtimeAutoModeGuardrail: 4,
+  },
+});
+```
 
 Requirements are server facts, not authorization requests. Check
 `runtime.grantedScopes` before enabling controls. Missing capabilities or
@@ -3844,35 +4092,54 @@ Coder. Products that depend on same-Run delivery should require
 (for example, SA execution) still return `unsupported_capability`; do not
 silently substitute `delivery:'after_turn'` unless that is the user's intent.
 
-The SDK requires `runtimeAutoModeGuardrail:4` automatically for ordinary
-`autoStart: true`. Supplying `daemonOrphanExitMs` additionally requires the
-dedicated `daemonOrphanExit:1` capability and passes the option only when
-spawning a new daemon. It does not silently reinterpret an already-running
-persistent daemon: the SDK uses the normal fenced capability-upgrade path and
-replaces it only when preflight proves that doing so is safe. After the daemon
-has observed a logical client, final-client detach arms the requested grace
-period; a new client cancels it, and active/queued runs, Workflow, Agent turns,
-pending permission/user input, or other governed work defer exit until
-preflight is idle. Omit the option for CLI-style daemons that are intentionally
-persistent.
-
-An embedder can inspect `KODAX_RUNTIME_SDK_CAPABILITIES.daemonOrphanExit`
-before calling an auto-start API. This prevents an older SDK from spawning a
-persistent daemon and only then discovering that it cannot honor the requested
-lifecycle policy. The connected daemon capability remains the authoritative
-check that the current host actually enabled the policy.
-
-When a healthy profile daemon is too old, 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
-the exact capabilities they depend on. Capability requirements are minimum
-versions: v4 satisfies v1-v3, v3 satisfies v1/v2, v2 satisfies v1, and an older
-daemon never satisfies a newer requirement.
+The SDK requires `runtimeAutoModeGuardrail:4` automatically for ordinary
+`autoStart: true`. Supplying `daemonOrphanExitMs` additionally requires the
+dedicated `daemonOrphanExit:1` capability and passes the option only when
+spawning a new daemon. It does not silently reinterpret an already-running
+persistent daemon: the SDK uses the normal fenced capability-upgrade path and
+replaces it only when preflight proves that doing so is safe. After the daemon
+has observed a logical client, final-client detach arms the requested grace
+period; a new client cancels it, and active/queued runs, Workflow, Agent turns,
+pending permission/user input, or other governed work defer exit until
+preflight is idle. Omit the option for CLI-style daemons that are intentionally
+persistent.
+
+An embedder can inspect `KODAX_RUNTIME_SDK_CAPABILITIES.daemonOrphanExit`
+before calling an auto-start API. This prevents an older SDK from spawning a
+persistent daemon and only then discovering that it cannot honor the requested
+lifecycle policy. The connected daemon capability remains the authoritative
+check that the current host actually enabled the policy.
+
+`KODAX_RUNTIME_SDK_CAPABILITIES.runtimeEventCoalescing` performs the same
+local-SDK preflight for bounded source-level text/reasoning coalescing. Requiring
+`runtimeEventCoalescing:1` lets auto-start replace only an idle legacy daemon;
+a busy or otherwise unsafe owner produces the normal capability-upgrade error.
+The capability changes event allocation/persistence pressure, not reconstructed
+stream content: flush boundaries remain explicit and an accumulated merge
+never exceeds 8 KiB.
+
+Observation boundaries such as `events.subscribe()`, `events.replay()`, and
+Session status projection flush pending events before answering, so they can
+surface a durable-persistence failure instead of returning a stale waterline.
+A determinate append failure retains one bounded batch for a later explicit
+retry. If both append and rollback fail, commit state is unknowable: the error
+is intentionally sticky and the Runtime must be closed/recreated rather than
+guessing or replaying the batch. Latest-only progress coalescing preserves its
+required first sample plus the most recent sample; discarded intermediate
+snapshots are not lifecycle events, and surviving samples retain their latest
+emission order.
+
+When a healthy profile daemon is too old, 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
+the exact capabilities they depend on. Capability requirements are minimum
+versions: v4 satisfies v1-v3, 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,
@@ -3891,11 +4158,116 @@ 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.
 
+### Query authoritative Session and Run lifecycle
+
+Use `runtime.runs.get(runId)` for the exact Run and
+`runtime.sessions.status(sessionId)` for the one current Session projection.
+Do not infer completion from assistant text:
+
+```ts
+const run = await runtime.runs.get(runId);
+const sessionStatus = await runtime.sessions.status(sessionId);
+
+switch (run.phase) {
+  case 'running':
+  case 'waiting_agent':
+  case 'recovering':
+  case 'waiting_permission':
+  case 'waiting_user_input':
+    renderActive(run.phase);
+    break;
+  case 'unknown':
+    renderUnconfirmedExecution(run.error);
+    break;
+  case 'completed':
+  case 'cancelled':
+  case 'interrupted':
+  case 'failed':
+    renderTerminal(run.terminal);
+    break;
+}
+```
+
+`phase` answers whether the Run is queued, active, terminal, or unconfirmed.
+Use `stage` for the finer executor location: `executing`,
+`waiting_agent`, `recovering`, managed phases such as `worker` or `verifying`,
+and `finalizing`. In particular, managed status `completed` first appears as
+`phase:'running', stage:'finalizing'`; it is not terminal until the outer
+executor settles. `stageChangedAt` timestamps that transition, and
+`activeSubtaskCount` is present only when the managed executor reported an
+authoritative count. If Runtime shutdown begins after an executor terminal
+callback was latched, that terminal fact is persisted synchronously before the
+owner-liveness endpoint is released. Result-handle resolution and queue drain
+still wait for the executor result or the deferred lost-result fallback.
+Destructive Session mutations remain fenced across the same settlement window.
+
+Run ownership is private persistence metadata, not a public ordering field. A
+second Runtime may observe a live owner's status but cannot abort or mutate
+that Run. A definitely dead owner is recovered to a durable `interrupted`
+result. If liveness cannot be proven either way, the observer returns
+`phase: 'unknown'`; it does not report a successful stop and does not overwrite
+the original non-terminal record. The same rule applies to ownerless legacy
+non-terminal records. A durable terminal event is reconciled before this
+fallback; non-terminal evidence such as an input-delivery event may refine the
+read projection but does not prove that execution stopped. Persisted terminal
+states are monotonic.
+
+`runtime.status.preflight()` treats `queued`, all active/waiting/recovery
+phases, and `unknown` as stop blockers. A host must never infer completion from
+reply text or convert `unknown` into success.
+
+`runtime.runs.abort(runId)` requests Stop; it does not manufacture an
+acknowledgement. Queued work can become `cancelled` immediately. For an active
+executor, inspect `run.stop`: while termination is unconfirmed, the Run reports
+`phase/stage:'unknown'` and `stop.state/outcome:'unknown'`. A later executor
+result confirms the actual outcome, including `completed` when the executor
+ignored Stop and completed normally. Terminal callback order is latched before
+deferred result settlement: Stop cannot rewrite an earlier completion as
+interrupted, and late finalizer/recovery progress cannot revive an unconfirmed
+stopped Run. If the Runtime owner then dies, recovery resolves the pending Stop
+as `confirmed/interrupted`.
+
+For support bundles, use the pure read-only compositor:
+
+```ts
+import { captureRuntimeSessionDiagnostics } from '@kodax-ai/kodax/runtime';
+
+const diagnostic = await captureRuntimeSessionDiagnostics(runtime, {
+  sessionId,
+  runId,
+  timeoutMs: 10_000,
+  signal: abortController.signal,
+});
+```
+
+The schema-versioned result includes SDK/Runtime/daemon versions, Runtime and
+Session identity, observation cursor/transcript revision, Run/Turn identity,
+phase/stage and stage time, terminal fact/time, Run-owned active child count,
+Stop and chat-interrupt records, and structured errors. If the selected Run
+did not persist an authoritative child count, the result returns
+`activeSubtaskCount:null` and `activeSubtaskCountSource:'unknown'`; it never
+attributes a later Session-wide child sample to that Run. If a historical
+Session has no Run control record, it returns `controlRecord:'unknown'` with
+`run_control_unknown`; it never infers completion from transcript text.
+`owner_liveness_unconfirmed`, `owner_recovery_required`,
+`stop_outcome_unconfirmed`, `run_failed`, `run_status_unknown`, and
+`terminal_time_unknown` remain distinct. These are independent facts rather
+than an enum: for example, an unavailable owner and an unconfirmed Stop appear
+together in `errors`. `sdkVersion` is the calling SDK package version;
+`runtimeVersion` and `daemonVersion` identify the connected daemon in daemon
+mode, so a support bundle preserves version skew. One timeout/cancellation
+budget covers the transcript, settings, pending interactions, and owner
+liveness inspection. The helper uses the dedicated
+`sessions.diagnostics()` read boundary: it never runs status preflight,
+resumes, repairs, migrates, takes ownership, or evicts a retained transcript
+page boundary. Embedded and daemon facades use the same schema-validated
+`session.diagnostics` contract.
+
 ### 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,
+`transcriptRevision`, bounded transcript slice, 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
@@ -3918,6 +4290,10 @@ async function openCoderSession(sessionId: string) {
   observedRuntimeId = snapshot.runtimeId;
   lastCursor = snapshot.cursor;
   replaceSessionProjection(snapshot, { runtimeChanged });
+  void observation.invalidated.then((reason) => {
+    discardSessionProjection(reason);
+    scheduleFreshObservation(sessionId);
+  });
   return observation;
 }
 ```
@@ -3944,9 +4320,14 @@ 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.
+restart changes `runtimeId`. The observation's `invalidated` promise reports
+`event_overflow`, `event_order`, `runtime_changed`, or
+`transport_disconnected`; after it resolves, no state derived from that
+observation remains authoritative. Restart recovery interrupts only a Run
+whose owner is definitely gone; uncertain external execution is `unknown`.
+Timeout or cancellation removes the daemon request immediately. If a
+third-party transport ignores cancellation and later returns an observation,
+the client compensates by unsubscribing that late observation.
 
 ### Durable mutations, stable ordering, and settings CAS
 
@@ -4022,17 +4403,17 @@ 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. Same-Run lifecycle continuations also have a fixed internal
-allowance beyond the configured iteration ceiling; the Runner closes admission
-before its final absolute generation so repeated submissions cannot keep one
-Run alive indefinitely. The allowance never expands an admitted manifest's
-`maxIterations` governance cap. 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
+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. Same-Run lifecycle continuations also have a fixed internal
+allowance beyond the configured iteration ceiling; the Runner closes admission
+before its final absolute generation so repeated submissions cannot keep one
+Run alive indefinitely. The allowance never expands an admitted manifest's
+`maxIterations` governance cap. 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.
@@ -4059,6 +4440,16 @@ query `runtime.operations.get({ operationId, journalEpoch })`; applied receipts
 include the canonical result. Permission grants remain daemon-owned and
 revisioned.
 
+Runtime startup restores all indexed active Runs and at most 200 recent
+terminal Runs from a bounded durable status index. `runs.get(runId)` remains an
+exact persisted lookup even when an older terminal Run is outside that recent
+window. The first start after upgrading an unindexed home may perform one full
+compatibility scan. A start after a crash, or a concurrent Runtime starting
+while a live writer has intentionally left the index dirty, may likewise do
+one authoritative reconciliation. Normal writers publish canonical
+`status.json` first and keep the derived index recovery-fenced across those
+crashes and concurrent Runtime instances.
+
 ### AskUser and permission from any client
 
 AskUser is no longer an in-process callback for daemon Coder runs. Any client
@@ -4102,11 +4493,11 @@ 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` v4
-advertises this opaque concrete-grant contract plus the intent-aligned
-retry/Accept-edits behavior that never changes the engine to rules. Embedded,
-Worker, and daemon hosts all report `fallbackPersistsEngine:false`; restart or
-upgrade an older daemon instead of falling back to a client-side alias.
+permission rule stores. Runtime capability `runtimeAutoModeGuardrail` v4
+advertises this opaque concrete-grant contract plus the intent-aligned
+retry/Accept-edits behavior that never changes the engine to rules. Embedded,
+Worker, and daemon hosts all report `fallbackPersistsEngine:false`; restart or
+upgrade an older daemon instead of falling back to a client-side alias.
 
 ### Broker a Space keychain credential
 
@@ -4330,7 +4721,7 @@ 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
+  autoModeTimeoutMs: 30_000,                // positive safe integer, optional
   autoModeSpeculativeWindowMs: 0,           // non-negative safe integer, optional
   executionCwd: projectDirectory,
 });
@@ -4385,9 +4776,9 @@ 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 explicit engine changes merge through the same Session mutation queue.
-Classifier infrastructure failures do not mutate the engine to rules.
+state from a queued turn. Active runs, queued runs, explicit settings updates,
+and explicit engine changes merge through the same Session mutation queue.
+Classifier infrastructure failures do not mutate the engine to rules.
 
 ### What an embedder should expect
 
@@ -4401,35 +4792,129 @@ Exactly modeled ordinary reads and workspace/system-temp mutations are admitted
 before classifier latency, independent of sandbox readiness. Other calls are
 reviewed against the latest genuine user request, bounded user-only intent
 evidence, and exact operation facts. Consequently, an LLM/rules `allow` does
-not create a pending permission request just because a host installed a static
-approval hook. Classifier concerns, critical deterministic matches, and rules
-concerns use the existing shared
-`runtime.permissions` flow, so another authorized client may render and answer
+not create a pending permission request just because a host installed a static
+approval hook. Classifier concerns, critical deterministic matches, and rules
+concerns use 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
-retries one timeout/provider/response-contract failure once; a second failure
-uses the Accept-edits safety boundary and never switches to Auto[rules].
-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.
+Direct guardrail embedders should supply `projectRoot` or `executionCwd` for
+path-bearing calls. If both are absent, KodaX keeps those targets unresolved
+instead of treating the host process cwd as the user's workspace.
+
+On PowerShell, deterministic read admission includes independently validated
+sequential/pipeline stages such as `where.exe`, ordinary `rg` inspection,
+non-sensitive `$env:NAME` reads, and constrained `Where-Object` /
+`Select-Object` expressions. This is a structural allowlist, not a blanket
+"review task" exemption. The executable token must be an admitted bare command
+name; path-qualified executables, arbitrary `& script.cmd`, effectful `find` /
+`awk` / `sed` forms, script blocks, sensitive credential environment names,
+external ripgrep preprocessors, and file redirection continue through the LLM
+classifier. They reach user approval only when the classifier identifies a
+concrete hazard (or when its bounded retry and fallback policy requires it).
+Authenticated child constraints are checked before deterministic admission:
+for example, `Do not execute shell commands` keeps even a read-only shell call
+under review, while `Do not modify files` does not make an ordinary read ask.
+
+The classifier deadline is 45 seconds for the first default attempt and 90
+seconds for its one retry. A configured `timeoutMs` overrides both attempts
+with the same explicit deadline. Each deadline includes connection setup,
+provider Retry-After/backoff, inference, and stream completion. A second
+timeout/provider/response-contract failure uses the Accept-edits safety
+boundary and never switches to Auto[rules]. 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 first-attempt output cap. If that answer is truncated before a
+decision, the retry uses 1024 tokens instead of repeating the same impossible
+budget. 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.
+
+Deterministic read admission keeps ordinary project directories, structured
+`grep`/`glob`, ripgrep/GNU-grep filters, and other bounded search selectors on
+the read fast path. A wildcard remains unresolved only when it can reach a
+protected credential area or its path boundary cannot be established.
+Explicit PowerShell `-LiteralPath` remains literal. Indirect file lists,
+dynamic Git pathspecs, and expanded `git grep --no-index`/`--untracked` scopes
+remain LLM-reviewed when their targets cannot be bounded safely. Git
+line-log `-L` paths, patch-enabling short-option clusters, and merge-diff modes
+are resolved before deciding whether output is scoped. Exact-file reads and
+metadata-only output such as `git show --stat` remain deterministic. Exclusion
+selectors do not become input targets. On Windows, protected-name checks also
+cover trailing-dot/space aliases, alternate data streams, and canonicalized
+existing 8.3 names. Git-config
+regexp/URL reads account for accepted option abbreviations and effective
+boolean-option ordering; only complete anchored selectors over known
+non-secret metadata can take the deterministic fast path. Likewise, incomplete
+current-user content may still admit a proven read, but a complete current
+request that explicitly prohibits reading or shell execution routes the
+matching read-only operation through the classifier. Ordinary review and
+read-only requests remain deterministic. `currentUserContentTruncated:true` prevents a
+write, delete, move, copy, or unmodeled execution from relying on the compacted
+fragment alone. On classifier failure, Accept-edits fallback is available only
+when the full structured review would pass the same deterministic predicate;
+protected/unresolved targets and partial/risky reviews remain approval-bound.
 
 `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`.
+elapsed time, retry count/wait, provider stop reason, response byte/text-block
+counts, 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.
+Each classifier attempt may additionally expose `observedProtocol`
+(`structured_v2`, `legacy_v1`, or `unknown`) and a bounded
+`parseFailureCode` when no valid unambiguous decision exists. When exactly one
+valid `decision=allow|ask` (or legacy `block=no|yes`) is present, that decision
+is authoritative. Missing, malformed, or contradictory `hazard` / `reason`
+fields and surrounding-format defects are reported as bounded
+`outputWarnings`; they do not change the decision, consume the retry, increment
+the circuit breaker, or create an approval request after `allow`. Runtime
+permission requests copy these fields into `autoModeDiagnostics`, allowing a
+host to distinguish an LLM confirmation decision (`source:
+classifier_confirm`) from provider/decision-contract failure (`source:
+classifier_failure`) without retaining model output. Missing or invalid
+decision values and ambiguous duplicate/mixed decisions remain contract
+failures and receive the same single bounded retry. The current
+provider API cannot honestly separate DNS/connect, TLS, provider queueing, and
+inference, so embedders must not infer those stages from `pre_output`.
+Because raw classifier text is deliberately not retained, these diagnostics
+cannot retroactively prove the shape of an older response. A future
+`observedProtocol:legacy_v1` value is evidence for that attempt; compatibility
+with `legacy_v1` alone is not proof that a prior provider returned it.
+`outputWarnings` explain the accepted attempt; they are not a second verdict.
+Under the LLM engine, a broken/non-string tool projection and an unavailable or
+faulty direct-read analyzer are recoverable metadata faults: KodaX records a
+warning, builds a bounded credential-redacted fallback projection, and still
+asks the classifier. They do not directly create a user approval request.
+Extension/provider exception bodies are omitted entirely from Auto-mode logs
+and approval reasons; only the stable failure stage and exception category are
+retained. All Auto-mode host warning messages are additionally
+credential-redacted, normalized to one line, and capped at 768 characters.
+Logging is best-effort observation: an embedder logger that throws cannot alter
+the permission decision or interrupt the documented fallback.
+For source compatibility, the public `ClassifierDecision` allow branch keeps
+`hazard?: 'none'`. If a model returns `decision=allow` with another hazard, the
+allow remains authoritative, `decision_hazard_conflict` appears in
+`outputWarnings`, and the contradictory hazard value is not placed in that
+legacy field.
+Auto[LLM] is allow-by-default automatic review. An operational classifier is
+instructed to return `ask` only for one of two evidence-based classes: a
+concrete read from a known key/token/credential store or a mutation to KodaX
+authorization controls; or direct system destruction/resource exhaustion that
+can destabilize the OS or unrelated software. Ordinary project mutations, Git
+stash and other Git writes, and normal global dependency install/uninstall/
+reinstall do not require per-command root authorization. Syntax complexity,
+incomplete analysis, general uncertainty, and command category are not ask
+reasons. Static signals, including historical catastrophic-pattern matches,
+are classifier facts rather than a second Auto[LLM] verdict; explicit
+Auto[Rules] retains its legacy deterministic gate. A host must honor a valid
+classifier `allow` without manufacturing another approval. Infrastructure or
+decision-contract failure still uses the bounded retry and documented
+Accept-edits fallback; only exhaustion beyond that fallback reaches approval.
 
 The permission event's `inputPreview` is a display-safe diagnostic projection:
 it is bounded, credential-redacted, valid JSON, and includes the effective
@@ -4439,21 +4924,21 @@ 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.
 
-Every Runtime permission request has a deadline. If the host does not answer,
-the current operation is not executed and the guardrail returns a stable
-`approval_timeout` result telling the main model to try a safer, narrower, or
-reversible approach, or stop and wait for explicit user approval. A timeout is
-not serialized as an ordinary user rejection.
-
-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 identified before LLM classification and routed to permission
-approval rather than permanently policy-blocked. 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.
+Every Runtime permission request has a deadline. If the host does not answer,
+the current operation is not executed and the guardrail returns a stable
+`approval_timeout` result telling the main model to try a safer, narrower, or
+reversible approach, or stop and wait for explicit user approval. A timeout is
+not serialized as an ordinary user rejection.
+
+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 identified before LLM classification and supplied as precise
+facts rather than permanently policy-blocked. 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
 
@@ -4613,8 +5098,12 @@ while (page) {
 
 `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
+cursors are opaque and revision-bound. Runtime retains a bounded immutable
+snapshot for an in-progress cursor, so new appends do not create duplicates,
+gaps, or an endless moving boundary. Once that snapshot is no longer retained,
+the next read returns `resync_required`; restart from a fresh observation.
+All transcript/history methods accept `{ timeoutMs, signal }` as their final
+read options in embedded and daemon mode. 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.
 
@@ -4737,394 +5226,455 @@ 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.
-
----
-
-## 28. Host-configurable Shell Execution Contract (v0.7.77)
-
-The shared daemon is long-lived, so its startup `process.env.PATH` is not a
-reliable description of every project's toolchain. A host can opt a Session
-into a serializable shell contract:
-
-```ts
-await runtime.sessions.updateSettings(session.id, {
-  executionCwd: projectDirectory,
-  shellExecution: {
-    version: 1,
-    shell: {
-      kind: 'pwsh',             // pwsh | powershell | cmd | bash | zsh
-      profile: 'default',
-    },
-    environment: {
-      inherit: 'filtered',
-      // Trusted host code, not model input. Use it for a directory-aware
-      // activation command when the shell profile does not switch on cwd.
-      setup: 'fnm use --silent-if-unchanged',
-      windowsPath: 'registry',
-    },
-    cache: {
-      ttlMs: 30_000,
-      refreshToken: 'toolchain-revision-1',
-    },
-    probeTimeoutMs: 10_000,
-  },
-});
-```
-
-An individual Run can supply `options.context.shellExecution`; a concrete Run
-contract overrides the Session setting. An omitted value or explicit
-`undefined` does not erase the Session setting. Use a `null` Session patch to
-remove it.
-
-The contract supports an optional absolute `shell.executable` (for example Git
-Bash) and bounded fixed `shell.args`. Command/file/persistence/profile/server
-and working-directory control flags are rejected from those fixed arguments.
-`environment.set` is for non-secret host variables. `denyPatterns` can remove
-additional names but cannot weaken the built-in Provider credential deny set.
-`inherit: "none"` retains only the OS variables required to start the selected
-shell. On Windows, `windowsPath: "registry"` re-reads current Machine/User
-environment values instead of reusing the daemon's startup PATH.
-
-Resolution is two-stage and uses the effective cwd:
-
-1. sanitize the bootstrap environment, including credentials for built-in,
-   custom, active, inactive, and stacked runtime Providers;
-2. start the selected shell, load the requested profile/setup, capture a
-   random-framed environment, validate and sanitize it again;
-3. execute the actual command through that same explicit interpreter.
-
-The cache is in-memory and isolated by normalized contract, canonical cwd,
-Session scratch identity, credential deny names, and refresh generation. TTL
-is bounded to ten minutes; zero disables caching. Daemon restart clears it.
-`clearShellExecutionEnvironmentCache()` is available for an in-process owner
-that needs immediate global invalidation.
-
-Native children, nested Actor turns, Workflow child paths, and deterministic
-build/test/lint evaluators inherit the effective contract. Runtime exact-command
-permission grants bind the interpreter family and contract fingerprint, so a
-grant created under cmd cannot silently authorize the same command after a
-switch to PowerShell or Bash.
-
-Configured-shell failures are visible and fail closed: KodaX does not reinterpret
-the command through another shell. When `shellExecution` is absent, KodaX keeps
-the pre-v0.7.77 platform-shell behavior for compatibility. See
-[`ISSUE_214_v0.7.77_REGRESSION_GUIDE.md`](test-guides/ISSUE_214_v0.7.77_REGRESSION_GUIDE.md)
-for cross-project, cache, cancellation, credential, and Windows argv checks.
-
----
-
-## 29. Evidence-gated background Skill learning (FEATURE_263, v0.7.78)
-
-F263 completes the existing Learning Center rather than introducing a second
-queue or client-owned Skill store. Episode review runs after durable foreground
-completion and stays off the active Run's latency path. A correction, failure,
-or verifier result is Memory evidence first; it does not itself authorize a
-Skill mutation.
-
-A low-risk declarative Skill can enter automatic project-scoped testing only
-after an explicit preserve-as-Skill request with verified terminal evidence,
-or repeated independent root episodes plus independent verified artifact
-evidence. The owner writes an immutable revision and its canonical capability
-record before discovery can expose it. Formal/builtin/plugin/human Skills keep
-precedence and cannot be shadowed. Protected/formal changes, user-global
-promotion, and Extension authoring remain explicit user actions.
-
-Hosts that require this behavior should negotiate both Runtime capabilities:
-
-```ts
-const runtime = await createKodaXRuntime({
-  mode: 'daemon',
-  requirements: {
-    learningCenter: 1,
-    skillLearningLoop: 1,
-  },
-  clientInfo: {
-    name: 'my-host',
-    instanceId: stableClientId,
-    instanceSecret: keychainSecret,
-  },
-});
-
-const snapshot = await runtime.learning.getSnapshot();
-const page = await runtime.learning.list({ limit: 50 });
-
-for await (const event of runtime.learning.subscribe({
-  afterRevision: snapshot.revision,
-})) {
-  renderLearningEvent(event);
-}
-```
-
-`runtime.learning` is the authoritative host surface:
-
-| Need | API |
-|---|---|
-| Render inventory or one exact record | `list()` / `get()` |
-| Render client-specific badges | `getSnapshot()` |
-| Replay or follow durable lifecycle events | `events()` / `subscribe()` |
-| Clear or defer only this client's notice | `acknowledge()` / `snooze()` |
-| Explicitly control a learned revision | `reject()` / `disable()` / `rollback()` / `review()` / `trust()` |
-| Promote to the user scope | `promote(nameOrSlugOrId, 'user')` |
-
-Do not scan learned files and infer activation from their presence. Discovery
-requires the canonical record, matching project identity, lifecycle,
-fingerprint, regular-file checks, formal-name policy, and exact revision.
-Testing admission permits one concurrent root binding and at most three
-exact-revision invocations. Promotion requires independently verified success;
-failed or inconclusive canaries return to Ready/attention. A Run retains the
-revision it captured at admission, so rollback or replacement affects future
-bindings without mutating an in-flight prompt.
-
-Learning Center notification state is client-specific, but capability
-lifecycle and project canary state are owner-global. Renderer code should
-receive sanitized records/events through host IPC; it should not receive
-daemon credentials or mutate files directly. Inline, Worker, and daemon
-facades expose the same learning methods. A host missing `skillLearningLoop:1`
-may still support the older Ready/manual Learning Center surface, but must not
-claim the complete F263 project-canary contract.
-
----
-
-## 30. Standalone sandbox SDK (v0.7.78)
-
-ASRT containment is a public SDK capability, not an Auto[LLM]-only
-implementation detail. Import the dedicated subpath when a host needs to
-sandbox its own commands or scripts:
-
-```ts
-import {
-  activateKodaXSandbox,
-  doctorKodaXSandbox,
-  getKodaXSandboxCapability,
-  getKodaXSandboxSetupGuidance,
-  runKodaXSandboxed,
-} from '@kodax-ai/kodax/sandbox';
-
-const capability = getKodaXSandboxCapability();
-const doctor = await doctorKodaXSandbox({ refresh: true });
-
-if (!doctor.ready) {
-  showSandboxInfo(getKodaXSandboxSetupGuidance(doctor));
-  // Call only from an explicit setup/onboarding action. On Windows this may
-  // display UAC; ordinary SDK calls never invoke it automatically.
-  const activation = await activateKodaXSandbox();
-  if (activation.status !== 'ready') {
-    showSandboxInfo(activation.guidance);
-  }
-}
-```
-
-Platform behavior:
-
-- Windows uses the pinned ASRT restricted-user/WFP setup. The parent terminal
-  does not need to be elevated; the one-time installer requests UAC itself.
-- macOS uses Seatbelt through `sandbox-exec` and requires ripgrep. Guide users
-  to `brew install ripgrep` when doctor reports it missing.
-- Linux uses bubblewrap and requires `bubblewrap`, `socat`, and `ripgrep`.
-  Present the emitted `apt`/`dnf`/`pacman` guidance; do not run `sudo` or a
-  package manager silently.
-
-Do not call `activateKodaXSandbox()` during ordinary Runtime startup, tool
-execution, or a background permission check. KodaX's own first-run/setup UI
-checks once; a declined UAC prompt or missing dependency is reported there and
-is not repeatedly surfaced until the user runs setup again.
-
-### Run a host-owned command with an explicit policy
-
-```ts
-import os from 'node:os';
-import path from 'node:path';
-import { runKodaXSandboxed } from '@kodax-ai/kodax/sandbox';
-
-const result = await runKodaXSandboxed({
-  command: process.execPath,
-  args: ['scripts/generate-report.mjs'],
-  cwd: projectDirectory,
-  filesystem: {
-    allowRead: [projectDirectory, process.execPath],
-    allowWrite: [projectDirectory, os.tmpdir()],
-    denyRead: [path.join(os.homedir(), '.ssh')],
-    denyWrite: [path.join(projectDirectory, '.git', 'config')],
-  },
-  network: {
-    mode: 'allowlist',
-    origins: ['https://api.example.com'],
-  },
-  // false by default: start with KodaX's minimal execution environment.
-  inheritEnvironment: false,
-  env: { REPORT_FORMAT: 'pdf' },
-  timeoutMs: 120_000,
-  maxOutputBytes: 2 * 1024 * 1024,
-});
-
-if (result.status === 'unavailable') {
-  // The command was NOT run. Decide explicitly whether your product should
-  // wait for setup, reject the operation, or use its own non-sandbox path.
-  showSandboxInfo(getKodaXSandboxSetupGuidance(result.doctor));
-} else if (result.exitCode !== 0) {
-  throw new Error(result.stderr || `sandboxed command exited ${result.exitCode}`);
-}
-```
-
-The generic executor supports network `allow`, `deny`, and exact HTTP(S)
-origin `allowlist` modes plus filesystem policy roots, environment inheritance,
-timeout, cancellation, and bounded output. ASRT permits ordinary reads by
-default: `denyRead` removes access and a more specific `allowRead` carves access
-back. `allowWrite` defines the writable roots, while `denyWrite` removes
-subtrees and always takes precedence over `allowWrite`. The HTTP(S) `origins`
-are normalized to the hostname/port pair enforced by ASRT's network proxy. It
-never silently runs without containment: sandbox unavailability is the typed
-`{ status: 'unavailable', sandboxed: false, doctor }` result.
-
-KodaX's own local workspace-shell policy supplies a stricter `denyRead` set
-than the generic SDK default: common home credential locations, sensitive
-private-key/environment filenames, and the complete resolved agent home are
-denied. Home-local executable search paths nested below those roots are not
-re-granted. This policy belongs to KodaX's command adapter; a standalone SDK
-host must declare the sensitive paths required by its own threat boundary.
-
-`command` and `args` remain separate process arguments. On Windows KodaX uses
-an encoded bootstrap followed by `shell: false`, so `%VAR%`, `&`, embedded
-quotes, and spaces are not expanded or re-parsed by the host shell. The
-explicit environment policy is overlaid into ASRT's fresh restricted-user
-environment; ASRT-owned proxy, CA, and Git safety variables retain precedence.
-`timeoutMs` covers the complete broker lifecycle, including ASRT
-initialization, the command, and cleanup. Windows ACL initialization on a cold
-path can take tens of seconds, so do not reuse a classifier-scale 20–30 second
-deadline unless that early cancellation is intentional.
-
-This is intentionally different from KodaX's local permission fallback. When
-ASRT is unavailable, Auto[LLM] still makes the same deterministic/LLM/user
-permission decision and an admitted local shell may use the ordinary execution
-path; only OS containment is absent. The same local fallback applies when
-ASRT preparation or backend initialization fails before the target process
-starts. KodaX never retries after the target has started, so a sandbox fault
-cannot duplicate command side effects. Remote A2A admitted Skill scripts
-retain their stronger isolation contract and do not fall back to an
-unsandboxed script. Embedded and daemon Runtime capability metadata expose
-`sandboxRuntime` with the platform backend, ASRT version, supported control
-dimensions, elevation behavior, and fallback semantics.
-
-Local workspace commands reuse one long-lived ASRT session per canonical
-workspace. Session-level ACL/WFP initialization is warmed once; the owner
-coordinates short wrap/cleanup RPCs without locking across the target process
-lifetime, so concurrent and background targets do not block later preparation.
-Per-command target attestation and fallback remain independent. Session reset
-happens only after an idle drain or host-process shutdown, never on the
-interactive command critical path. A cold first command may still wait for
-platform initialization, but later commands must not repeatedly pay that
-setup/reset cost. Abort signals and the command deadline cover that prepare
-wait; a cancelled/timed-out prepare never starts the target or changes to the
-ordinary fallback path. Explicit
-Windows system-temp operations that ASRT cannot safely ACL-manage are not
-selected for containment and keep the already-approved normal execution path.
-
-An unhealthy session fails the current prepare immediately so the host can use
-its normal permission fallback. Cleanup continues out of band. On Windows the
-owner first closes its command input and allows up to 130 seconds for ASRT
-0.0.65's two serial ACL cleanup helpers to finish; only then may process-tree
-termination be forced. The failed workspace session is not replaced until
-that bounded cleanup settles, preventing a replacement from racing stale ACL
-recovery. macOS and Linux use the same EOF-first sequence with a shorter
-bounded termination grace.
-
-Runtime event streams may also contain one terminal `tool.sandbox` observation
-associated with the tool ID. `applied` is emitted only after the in-sandbox
-bootstrap confirms that the real target process reached Node's `spawn` event;
-wrapper startup alone is not sufficient. Before that handshake, a local
-backend failure may fall back to normal execution. After it, KodaX never
-restarts the target:
-
-```ts
-runtime.events.subscribe({ sessionId: session.id, type: 'tool.sandbox' }, (event) => {
-  if (event.type !== 'tool.sandbox') return;
-  const { observation } = event.payload.update;
-  // observation.state: 'applied' | 'fallback' | 'not_selected'
-  diagnostics.recordSandboxRoute(observation);
-});
-```
-
-This event is optional diagnostics, not conversation content. It is never added
-to model-visible messages. Default consumer UX should not render it in startup
-output, command cards, notifications, or conversation history; expose it only
-in an explicit advanced diagnostics view. KodaX's own Ink REPL does not
-subscribe to the event and refreshes human-readable status only when the user
-runs `/sandbox`. Explicit JSON output and SDK subscriptions retain the
-structured event for professional diagnostics. `/sandbox` is read-only and
-never activates the backend or requests elevation.
-
----
-
-## Learned Skill promotion reference (v0.7.78)
-
-Promotion is the explicit transfer of one immutable, reviewed `ready` or
-`active_learned` Skill revision into the formal user catalog. It is not the
-evidence-driven `testing -> active_learned` canary transition. The public named
-service type is exported from the Runtime SDK:
-
-```ts
-import {
-  createKodaXRuntime,
-  type RuntimeLearningService,
-} from '@kodax-ai/kodax/runtime';
-
-const runtime = await createKodaXRuntime({
-  requirements: {
-    learningCenter: 1,
-    skillLearningLoop: 1,
-  },
-});
-
-const learning: RuntimeLearningService = runtime.learning;
-const record = await learning.get('normalize-release-notes');
-
-try {
-  await learning.promote(record.capabilityId, 'user');
-} finally {
-  await runtime.close();
-}
-```
-
-`name`, `slug`, and exact `capabilityId` are accepted. Exact IDs are preferred
-when multiple projects expose the same display name or slug. `'user'` is the
-only supported scope. Daemon clients need the server-issued
-`learning:control` scope; advertising a client capability does not grant it.
-Inline, Worker, and daemon facades carry the same v2 learned-record shape and
-promotion method.
-
-The Runtime verifies the source is a regular non-symlink file inside the exact
-project Learned Area and that its content still matches the recorded
-fingerprint. It then creates the configured user Skill destination—normally
-`~/.kodax/skills/<slug>/SKILL.md`—with atomic exclusive-publish semantics.
-Existing identical content is idempotent; the final path appears only after the
-complete temporary file is synced. Different formal content returns an
-`action_failed` error and is never overwritten. On success the canonical
-project record changes to `promoted_user`.
-
-Terminal users can inspect the same contract with:
-
-```text
-/learn promote --help
-/learn help promote
-/help learn promote
-```
-
-The canonical command is
-`/learn promote <name|slug|capability-id> --scope user`; omitting the scope is a
-backward-compatible shorthand for the same user scope. Unknown, duplicate, or
-unsupported options fail before the Runtime mutation.
-
----
-
-## See also
-
-- [README.md](../README.md) — end-user CLI quick start
+This follow-up does not gate SDK packaging, tagging, or publication.
+
+---
+
+## 28. Host-configurable Shell Execution Contract (v0.7.77)
+
+The shared daemon is long-lived, so its startup `process.env.PATH` is not a
+reliable description of every project's toolchain. A host can opt a Session
+into a serializable shell contract:
+
+```ts
+await runtime.sessions.updateSettings(session.id, {
+  executionCwd: projectDirectory,
+  shellExecution: {
+    version: 1,
+    shell: {
+      kind: 'pwsh',             // pwsh | powershell | cmd | bash | zsh
+      profile: 'default',
+    },
+    environment: {
+      inherit: 'filtered',
+      // Trusted host code, not model input. Use it for a directory-aware
+      // activation command when the shell profile does not switch on cwd.
+      setup: 'fnm use --silent-if-unchanged',
+      windowsPath: 'registry',
+    },
+    cache: {
+      ttlMs: 30_000,
+      refreshToken: 'toolchain-revision-1',
+    },
+    probeTimeoutMs: 10_000,
+  },
+});
+```
+
+An individual Run can supply `options.context.shellExecution`; a concrete Run
+contract overrides the Session setting. An omitted value or explicit
+`undefined` does not erase the Session setting. Use a `null` Session patch to
+remove it.
+
+The contract supports an optional absolute `shell.executable` (for example Git
+Bash) and bounded fixed `shell.args`. Command/file/persistence/profile/server
+and working-directory control flags are rejected from those fixed arguments.
+`environment.set` is for non-secret host variables. `denyPatterns` can remove
+additional names but cannot weaken the built-in Provider credential deny set.
+`inherit: "none"` retains only the OS variables required to start the selected
+shell. On Windows, `windowsPath: "registry"` re-reads current Machine/User
+environment values instead of reusing the daemon's startup PATH.
+
+The CLI config and SDK expose the same small command-target setting for commands
+that intentionally need host credentials:
+
+```json
+{
+  "sandbox": {
+    "envPass": ["GH_TOKEN", "GITHUB_TOKEN"]
+  }
+}
+```
+
+SDK callers pass the same shape per Run, without mutating `process.env` config:
+
+```ts
+const handle = await runtime.runs.start({
+  sessionId: session.id,
+  prompt: 'Inspect the authenticated GitHub repository.',
+  options: {
+    sandbox: { envPass: ['GH_TOKEN', 'GITHUB_TOKEN'] },
+  },
+});
+```
+
+Direct `runKodaX()` / `startKodaX()` callers use the same
+`KodaXOptions.sandbox` field. The option is Run-scoped, overrides the process-
+level fallback even when `envPass` is empty, and is inherited by native child
+Agents, Workflow children, and deterministic evaluators. Concurrent SDK Runs
+can therefore use different lists without changing global configuration.
+
+`sandbox.envPass` defaults to empty and stores exact names, never values. It
+does not expose credentials to shell profile/setup resolution; the current
+host values are restored only into the final command environment, which then
+flows to ASRT or the ordinary fallback path. Windows matching is
+case-insensitive; POSIX matching is case-sensitive. `NODE_OPTIONS`, `BASH_ENV`,
+`RIPGREP_CONFIG_PATH`, and imported Bash functions remain blocked even if
+named. The CLI projects its user config to the Run option through
+`KODAX_SANDBOX_ENV_PASS`; that environment variable remains a CLI/backward-
+compatibility fallback rather than the SDK API. Worker and daemon transports
+carry names only. Values are read from the command-execution host environment;
+an auto-started daemon inherits that environment, while an attached persistent
+daemon must already have the variables and must restart after they change.
+
+Resolution is two-stage and uses the effective cwd:
+
+1. sanitize the bootstrap environment, including credentials for built-in,
+   custom, active, inactive, and stacked runtime Providers;
+2. start the selected shell, load the requested profile/setup, capture a
+   random-framed environment, validate and sanitize it again;
+3. execute the actual command through that same explicit interpreter.
+
+The cache is in-memory and isolated by normalized contract, canonical cwd,
+Session scratch identity, credential deny names, and refresh generation. TTL
+is bounded to ten minutes; zero disables caching. Daemon restart clears it.
+`clearShellExecutionEnvironmentCache()` is available for an in-process owner
+that needs immediate global invalidation.
+
+Native children, nested Actor turns, Workflow child paths, and deterministic
+build/test/lint evaluators inherit the effective contract. Runtime exact-command
+permission grants bind the interpreter family and contract fingerprint, so a
+grant created under cmd cannot silently authorize the same command after a
+switch to PowerShell or Bash.
+
+Configured-shell failures are visible and fail closed: KodaX does not reinterpret
+the command through another shell. When `shellExecution` is absent, KodaX keeps
+the pre-v0.7.77 platform-shell interpreter behavior for compatibility; the
+credential filter and explicit `sandbox.envPass` final-target restoration still
+apply. See
+[`ISSUE_214_v0.7.77_REGRESSION_GUIDE.md`](test-guides/ISSUE_214_v0.7.77_REGRESSION_GUIDE.md)
+for cross-project, cache, cancellation, credential, and Windows argv checks.
+
+---
+
+## 29. Evidence-gated background Skill learning (FEATURE_263, v0.7.78)
+
+F263 completes the existing Learning Center rather than introducing a second
+queue or client-owned Skill store. Episode review runs after durable foreground
+completion and stays off the active Run's latency path. A correction, failure,
+or verifier result is Memory evidence first; it does not itself authorize a
+Skill mutation.
+
+A low-risk declarative Skill can enter automatic project-scoped testing only
+after an explicit preserve-as-Skill request with verified terminal evidence,
+or repeated independent root episodes plus independent verified artifact
+evidence. The owner writes an immutable revision and its canonical capability
+record before discovery can expose it. Formal/builtin/plugin/human Skills keep
+precedence and cannot be shadowed. Protected/formal changes, user-global
+promotion, and Extension authoring remain explicit user actions.
+
+Hosts that require this behavior should negotiate both Runtime capabilities:
+
+```ts
+const runtime = await createKodaXRuntime({
+  mode: 'daemon',
+  requirements: {
+    learningCenter: 1,
+    skillLearningLoop: 1,
+  },
+  clientInfo: {
+    name: 'my-host',
+    instanceId: stableClientId,
+    instanceSecret: keychainSecret,
+  },
+});
+
+const snapshot = await runtime.learning.getSnapshot();
+const page = await runtime.learning.list({ limit: 50 });
+
+for await (const event of runtime.learning.subscribe({
+  afterRevision: snapshot.revision,
+})) {
+  renderLearningEvent(event);
+}
+```
+
+`loadFullTranscript()` remains the nullable compatibility API.
+`readFullTranscript()` is the strict host/audit API: it reads main and sidecars
+under one Session boundary without migration, execution recovery, takeover, or
+repair. It reports `data_corrupt`, `version_incompatible`, `read_timeout`, and
+`read_cancelled` instead of turning those cases into an empty/null history.
+`readConversationHistory()` uses that same read-only boundary, then derives the
+ordinary conversation projection without changing Session or Run state.
+
+For an old or incompatible Session that cannot safely resume, use the
+top-level `exportSessionBundle(id, options?)`. It returns the exact main,
+`.islands.jsonl`, and legacy `.archive.jsonl` bytes plus hashes and
+compatibility diagnostics. Export is read-only and fails closed on ambiguous
+duplicate main files; it does not choose a Session, migrate it, or claim that
+the task is resumable. Decode each file's `contentBase64` for the canonical
+lossless bytes; `content` is only a UTF-8 compatibility preview. `byteLength`
+and `sha256` are computed from the original bytes.
+
+`runtime.learning` is the authoritative host surface:
+
+| Need | API |
+|---|---|
+| Render inventory or one exact record | `list()` / `get()` |
+| Render client-specific badges | `getSnapshot()` |
+| Replay or follow durable lifecycle events | `events()` / `subscribe()` |
+| Clear or defer only this client's notice | `acknowledge()` / `snooze()` |
+| Explicitly control a learned revision | `reject()` / `disable()` / `rollback()` / `review()` / `trust()` |
+| Promote to the user scope | `promote(nameOrSlugOrId, 'user')` |
+
+Do not scan learned files and infer activation from their presence. Discovery
+requires the canonical record, matching project identity, lifecycle,
+fingerprint, regular-file checks, formal-name policy, and exact revision.
+Testing admission permits one concurrent root binding and at most three
+exact-revision invocations. Promotion requires independently verified success;
+failed or inconclusive canaries return to Ready/attention. A Run retains the
+revision it captured at admission, so rollback or replacement affects future
+bindings without mutating an in-flight prompt.
+
+Learning Center notification state is client-specific, but capability
+lifecycle and project canary state are owner-global. Renderer code should
+receive sanitized records/events through host IPC; it should not receive
+daemon credentials or mutate files directly. Inline, Worker, and daemon
+facades expose the same learning methods. A host missing `skillLearningLoop:1`
+may still support the older Ready/manual Learning Center surface, but must not
+claim the complete F263 project-canary contract.
+
+---
+
+## 30. Standalone sandbox SDK (v0.7.78)
+
+ASRT containment is a public SDK capability, not an Auto[LLM]-only
+implementation detail. Import the dedicated subpath when a host needs to
+sandbox its own commands or scripts:
+
+```ts
+import {
+  activateKodaXSandbox,
+  doctorKodaXSandbox,
+  getKodaXSandboxCapability,
+  getKodaXSandboxSetupGuidance,
+  runKodaXSandboxed,
+} from '@kodax-ai/kodax/sandbox';
+
+const capability = getKodaXSandboxCapability();
+const doctor = await doctorKodaXSandbox({ refresh: true });
+
+if (!doctor.ready) {
+  showSandboxInfo(getKodaXSandboxSetupGuidance(doctor));
+  // Call only from an explicit setup/onboarding action. On Windows this may
+  // display UAC; ordinary SDK calls never invoke it automatically.
+  const activation = await activateKodaXSandbox();
+  if (activation.status !== 'ready') {
+    showSandboxInfo(activation.guidance);
+  }
+}
+```
+
+Platform behavior:
+
+- Windows uses the pinned ASRT restricted-user/WFP setup. The parent terminal
+  does not need to be elevated; the one-time installer requests UAC itself.
+- macOS uses Seatbelt through `sandbox-exec` and requires ripgrep. Guide users
+  to `brew install ripgrep` when doctor reports it missing.
+- Linux uses bubblewrap and requires `bubblewrap`, `socat`, and `ripgrep`.
+  Present the emitted `apt`/`dnf`/`pacman` guidance; do not run `sudo` or a
+  package manager silently.
+
+Do not call `activateKodaXSandbox()` during ordinary Runtime startup, tool
+execution, or a background permission check. KodaX's own first-run/setup UI
+checks once; a declined UAC prompt or missing dependency is reported there and
+is not repeatedly surfaced until the user runs setup again.
+
+### Run a host-owned command with an explicit policy
+
+```ts
+import os from 'node:os';
+import path from 'node:path';
+import { runKodaXSandboxed } from '@kodax-ai/kodax/sandbox';
+
+const result = await runKodaXSandboxed({
+  command: process.execPath,
+  args: ['scripts/generate-report.mjs'],
+  cwd: projectDirectory,
+  filesystem: {
+    allowRead: [projectDirectory, process.execPath],
+    allowWrite: [projectDirectory, os.tmpdir()],
+    denyRead: [path.join(os.homedir(), '.ssh')],
+    denyWrite: [path.join(projectDirectory, '.git', 'config')],
+  },
+  network: {
+    mode: 'allowlist',
+    origins: ['https://api.example.com'],
+  },
+  // false by default: start with KodaX's minimal execution environment.
+  inheritEnvironment: false,
+  env: { REPORT_FORMAT: 'pdf' },
+  timeoutMs: 120_000,
+  maxOutputBytes: 2 * 1024 * 1024,
+});
+
+if (result.status === 'unavailable') {
+  // The command was NOT run. Decide explicitly whether your product should
+  // wait for setup, reject the operation, or use its own non-sandbox path.
+  showSandboxInfo(getKodaXSandboxSetupGuidance(result.doctor));
+} else if (result.exitCode !== 0) {
+  throw new Error(result.stderr || `sandboxed command exited ${result.exitCode}`);
+}
+```
+
+The generic executor supports network `allow`, `deny`, and exact HTTP(S)
+origin `allowlist` modes plus filesystem policy roots, environment inheritance,
+timeout, cancellation, and bounded output. ASRT permits ordinary reads by
+default: `denyRead` removes access and a more specific `allowRead` carves access
+back. `allowWrite` defines the writable roots, while `denyWrite` removes
+subtrees and always takes precedence over `allowWrite`. The HTTP(S) `origins`
+are normalized to the hostname/port pair enforced by ASRT's network proxy. It
+never silently runs without containment: sandbox unavailability is the typed
+`{ status: 'unavailable', sandboxed: false, doctor }` result.
+
+KodaX's own local workspace-shell policy supplies a stricter `denyRead` set
+than the generic SDK default: common home credential locations, sensitive
+private-key/environment filenames, and the complete resolved agent home are
+denied. Home-local executable search paths nested below those roots are not
+re-granted. This policy belongs to KodaX's command adapter; a standalone SDK
+host must declare the sensitive paths required by its own threat boundary.
+
+`command` and `args` remain separate process arguments. On Windows KodaX uses
+an encoded bootstrap followed by `shell: false`, so `%VAR%`, `&`, embedded
+quotes, and spaces are not expanded or re-parsed by the host shell. The
+explicit environment policy is overlaid into ASRT's fresh restricted-user
+environment; ASRT-owned proxy, CA, and Git safety variables retain precedence.
+`timeoutMs` covers the complete broker lifecycle, including ASRT
+initialization, the command, and cleanup. Windows ACL initialization on a cold
+path can take tens of seconds, so do not reuse a classifier-scale 20–30 second
+deadline unless that early cancellation is intentional.
+
+This is intentionally different from KodaX's local permission fallback. When
+ASRT is unavailable, Auto[LLM] still makes the same deterministic/LLM/user
+permission decision and an admitted local shell may use the ordinary execution
+path; only OS containment is absent. The same local fallback applies when
+ASRT preparation or backend initialization fails before the target process
+starts. KodaX never retries after the target has started, so a sandbox fault
+cannot duplicate command side effects. Remote A2A admitted Skill scripts
+retain their stronger isolation contract and do not fall back to an
+unsandboxed script. Embedded and daemon Runtime capability metadata expose
+`sandboxRuntime` with the platform backend, ASRT version, supported control
+dimensions, elevation behavior, and fallback semantics.
+
+Local workspace commands reuse one long-lived ASRT session per canonical
+workspace. Session-level ACL/WFP initialization is warmed once; the owner
+coordinates short wrap/cleanup RPCs without locking across the target process
+lifetime, so concurrent and background targets do not block later preparation.
+Per-command target attestation and fallback remain independent. Session reset
+happens only after an idle drain or host-process shutdown, never on the
+interactive command critical path. A cold first command may still wait for
+platform initialization, but later commands must not repeatedly pay that
+setup/reset cost. Abort signals and the command deadline cover that prepare
+wait; a cancelled/timed-out prepare never starts the target or changes to the
+ordinary fallback path. Explicit
+Windows system-temp operations that ASRT cannot safely ACL-manage are not
+selected for containment and keep the already-approved normal execution path.
+
+An unhealthy session fails the current prepare immediately so the host can use
+its normal permission fallback. Cleanup continues out of band. On Windows the
+owner first closes its command input and allows up to 130 seconds for ASRT
+0.0.65's two serial ACL cleanup helpers to finish; only then may process-tree
+termination be forced. The failed workspace session is not replaced until
+that bounded cleanup settles, preventing a replacement from racing stale ACL
+recovery. macOS and Linux use the same EOF-first sequence with a shorter
+bounded termination grace.
+
+Runtime event streams may also contain one terminal `tool.sandbox` observation
+associated with the tool ID. `applied` is emitted only after the in-sandbox
+bootstrap confirms that the real target process reached Node's `spawn` event;
+wrapper startup alone is not sufficient. Before that handshake, a local
+backend failure may fall back to normal execution. After it, KodaX never
+restarts the target:
+
+```ts
+runtime.events.subscribe({ sessionId: session.id, type: 'tool.sandbox' }, (event) => {
+  if (event.type !== 'tool.sandbox') return;
+  const { observation } = event.payload.update;
+  // observation.state: 'applied' | 'fallback' | 'not_selected'
+  diagnostics.recordSandboxRoute(observation);
+});
+```
+
+This event is optional diagnostics, not conversation content. It is never added
+to model-visible messages. Default consumer UX should not render it in startup
+output, command cards, notifications, or conversation history; expose it only
+in an explicit advanced diagnostics view. KodaX's own Ink REPL does not
+subscribe to the event and refreshes human-readable status only when the user
+runs `/sandbox`. Explicit JSON output and SDK subscriptions retain the
+structured event for professional diagnostics. `/sandbox` is read-only and
+never activates the backend or requests elevation.
+
+---
+
+## Learned Skill promotion reference (v0.7.78)
+
+Promotion is the explicit transfer of one immutable, reviewed `ready` or
+`active_learned` Skill revision into the formal user catalog. It is not the
+evidence-driven `testing -> active_learned` canary transition. The public named
+service type is exported from the Runtime SDK:
+
+```ts
+import {
+  createKodaXRuntime,
+  type RuntimeLearningService,
+} from '@kodax-ai/kodax/runtime';
+
+const runtime = await createKodaXRuntime({
+  requirements: {
+    learningCenter: 1,
+    skillLearningLoop: 1,
+  },
+});
+
+const learning: RuntimeLearningService = runtime.learning;
+const record = await learning.get('normalize-release-notes');
+
+try {
+  await learning.promote(record.capabilityId, 'user');
+} finally {
+  await runtime.close();
+}
+```
+
+`name`, `slug`, and exact `capabilityId` are accepted. Exact IDs are preferred
+when multiple projects expose the same display name or slug. `'user'` is the
+only supported scope. Daemon clients need the server-issued
+`learning:control` scope; advertising a client capability does not grant it.
+Inline, Worker, and daemon facades carry the same v2 learned-record shape and
+promotion method.
+
+The Runtime verifies the source is a regular non-symlink file inside the exact
+project Learned Area and that its content still matches the recorded
+fingerprint. It then creates the configured user Skill destination—normally
+`~/.kodax/skills/<slug>/SKILL.md`—with atomic exclusive-publish semantics.
+Existing identical content is idempotent; the final path appears only after the
+complete temporary file is synced. Different formal content returns an
+`action_failed` error and is never overwritten. On success the canonical
+project record changes to `promoted_user`.
+
+Terminal users can inspect the same contract with:
+
+```text
+/learn promote --help
+/learn help promote
+/help learn promote
+```
+
+The canonical command is
+`/learn promote <name|slug|capability-id> --scope user`; omitting the scope is a
+backward-compatible shorthand for the same user scope. Unknown, duplicate, or
+unsupported options fail before the Runtime mutation.
+
+---
+
+## See also
+
+- [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/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
-- [docs/features/v0.7.77.md](features/v0.7.77.md) — v0.7.77 adaptive-quality, governed-memory, and release-hardening record
+- [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
+- [docs/features/v0.7.77.md](features/v0.7.77.md) — v0.7.77 adaptive-quality, governed-memory, and release-hardening record