@kodax-ai/kodax 0.7.76 → 0.7.78

package/docs/SDK_EMBEDDER_GUIDE.md

@@ -28,13 +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-v0768)
+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)
+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)
 
 §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)).
@@ -2775,11 +2779,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`.
@@ -2799,12 +2803,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 });
-```
-
-These diagnostics are designed for status panels and debugging. They should not
-contain raw 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
 
@@ -3219,7 +3230,7 @@ workflow's structured findings, verification results, and quality gates.
 
 ---
 
-## 21. Experimental governed memory — `/experimental-memory` (FEATURE_260, v0.7.68)
+## 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
@@ -3280,11 +3291,53 @@ await session.complete({
 await session.close();
 ```
 
-`recall()` is synchronous: exact observations/hints can be returned immediately,
-while an optional semantic prefetch finishes for a later matching decision.
-`query()` is deliberate and read-only; one distinct query is admitted per
-decision epoch, and the result is bounded to at most three prompt-safe hints and
-512 estimated tokens. `undefined` means there is no governed reminder to inject.
+`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
 
@@ -3294,9 +3347,11 @@ decision epoch, and the result is bounded to at most three prompt-safe hints and
   material. `rewind()` removes observations after a sequence boundary.
 - `complete()` can emit an Outcome Digest through `persistOutcomeDigest` and run
   bounded episode review through `reviewEpisode`; cancellation creates neither.
-- `onTrace` receives policy-versioned `MemoryDecisionReceipt` metadata that links
-  candidates, selection, injection, and later outcome influence. Receipts are
-  trace-only and contain no hidden reasoning.
+- `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.
@@ -3644,12 +3699,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 });
-```
-
-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
@@ -3733,10 +3792,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,
-  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',
@@ -3768,10 +3831,10 @@ const runtime = await connectKodaXRuntime({
     sharedSessionSettings: 1,
     durableRecoveryQueries: 1,
     daemonManagement: 1,
-    runtimeAutoModeGuardrail: 3,
-  },
-});
-```
+    runtimeAutoModeGuardrail: 4,
+  },
+});
+```
 
 Requirements are server facts, not authorization requests. Check
 `runtime.grantedScopes` before enabling controls. Missing capabilities or
@@ -3781,21 +3844,35 @@ 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 v0.7.73 SDK requires `runtimeAutoModeGuardrail:3` automatically for
-`autoStart: true`, even when the caller omits it from `requirements`. If the healthy
-profile daemon advertises v1 or v2, the SDK first requires `daemonManagement:1`,
-takes a revision/owner-policy fenced preflight, and replaces it only when no
-active or queued run, Workflow, Agent turn, pending permission/user input, or
-other logical client exists. A busy or still-older daemon is never stopped: the
-connection rejects with `RuntimeDaemonCapabilityUpgradeError`, whose
-`recoverable` and `restartRequired` fields are `true` and whose optional
-`preflight` explains the blockers. Attach-only connections never mutate daemon
-ownership and must request `runtimeAutoModeGuardrail:1` explicitly when they
-depend only on the v1 owner contract, v2 for bounded input, effective-default
-metadata, structured diagnostics, and speculative-window parity, or v3 for
-opaque exact grant suggestions and concrete permission matchers. Capability
-requirements are minimum versions: v3 satisfies v1/v2, v2 satisfies v1, and an
-older daemon never satisfies a newer requirement.
+The 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 `coderFeatureMatrix` capability reports daemon availability for managed
 runs, transcript/session operations, Todo projection, managed tasks, Workflow,
@@ -3945,13 +4022,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. 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.
@@ -3968,13 +4049,13 @@ const interrupted = await runtime.runs.submitInput({
 
 Run status exposes acceptance/start/queue times, authenticated origin,
 `sessionOrder`, and a single terminal fact. Important terminal codes include
-`runtime_restarted`, `daemon_crashed`, `credential_unavailable`,
-`host_not_dispatched`, `host_outcome_unknown`, and
-`control_history_untrusted`. Managed tasks that require user input use
-`terminal.code = 'blocked'`; surface `terminal.message` when present instead of
-replacing it with a generic run failure. Respect `effectOutcome`; `unknown` must
-never be presented as success or automatically retried. After a lost response,
-query `runtime.operations.get({ operationId, journalEpoch })`; applied receipts
+`runtime_restarted`, `daemon_crashed`, `credential_unavailable`,
+`host_not_dispatched`, `host_outcome_unknown`, and
+`control_history_untrusted`. Managed tasks that require user input use
+`terminal.code = 'blocked'`; surface `terminal.message` when present instead of
+replacing it with a generic run failure. Respect `effectOutcome`; `unknown` must
+never be presented as success or automatically retried. After a lost response,
+query `runtime.operations.get({ operationId, journalEpoch })`; applied receipts
 include the canonical result. Permission grants remain daemon-owned and
 revisioned.
 
@@ -4021,9 +4102,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` v3 advertises this
-opaque concrete-grant contract; 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
 
@@ -4302,9 +4385,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 automatic LLM-to-rules fallback merge through the same Session mutation
-queue; fallback is persisted before a later classification reads the engine.
+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
 
@@ -4314,16 +4397,22 @@ The Runtime's execution order is fixed:
 Runtime Auto Mode guardrail -> host permission bridge only for escalate -> tool execution
 ```
 
-Consequently, an LLM/rules `allow` does not create a pending permission request
-just because a host installed a static approval hook. `block` does not become a
-spurious approval prompt. A real `escalate` uses the existing shared
-`runtime.permissions` flow, so another authorized client may render and answer
-it. Hosts should subscribe to permission events to display such a request, but
-must not treat a missing request as an error for a safe tool call.
-
-The classifier deadline remains 20 seconds by default and includes connection
-setup, provider Retry-After/backoff, inference, and stream completion. KodaX
-does not solve timeouts by extending that deadline indefinitely. Before the
+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
+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
@@ -4350,14 +4439,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.
 
-The user-level `.kodax` directory is a credential/configuration boundary, not
-an ordinary project path. Direct shell mutations, output redirects, and
-recognized nested-shell payloads whose target is provably beneath that
-directory are rejected before LLM classification. The check is segment-safe
-and Windows case-insensitive. KodaX deliberately does not scan arbitrary
-quoted language source for path-looking substrings: doing so would turn Python,
-JavaScript, YAML, and regular expressions into false Tier-0 matches. Trusted
-configuration changes should use the KodaX config CLI or SDK configuration API.
+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.
 
 ### 0.7.x source compatibility
 
@@ -4609,49 +4705,426 @@ parent transcript commits and acknowledges the completion, later restores do
 not replay it. Legacy snapshots without the explicit pending set do not infer
 replay work from historical mailbox content.
 
-This separation changes no Actor event capability or daemon version: existing
-SDK snapshot, replay, and long-poll clients keep their telemetry surface. It
-only prevents high-frequency progress from becoming a model control signal.
+This separation changes no Actor event capability or daemon version: existing
+SDK snapshot, replay, and long-poll clients keep their telemetry surface. It
+only prevents high-frequency progress from becoming a model control signal.
+
+---
+
+## 27. Windows GUI background subprocess visibility (v0.7.75)
+
+KodaX SDK hosts do not need to add process-wide console suppression around the
+Runtime. In the v0.7.75 release candidate, Runtime Worker-reachable
+non-interactive/background child processes request `windowsHide: true` at their
+own spawn boundary. The covered paths include:
+
+- memory and Git metadata probes;
+- provider CLI execution and ACP servers;
+- LSP acquisition and language servers;
+- clipboard helpers, worktrees, review commands, and extension commands;
+- managed-task checkpoints and sandbox helpers.
+
+The contract is intentionally narrow. Explicit external editors, terminal
+commands, and PTY sessions remain interactive. POSIX-only `ps`, `tmux`, and
+sandbox branches are reviewed bundle-audit exceptions rather than Windows
+visibility paths.
+
+`npm run build:bundle` audits every statically identifiable child-process call
+reachable from `dist/runtime-worker.js`. The packaged Electron daemon smoke then
+runs 20 ordinary queries with a Win32 probe and checks that the expected Git
+children never own a visible console window. These checks validate the SDK
+boundary, but they do not replace product-level validation in the packaged host.
+KodaX Space should install the exact v0.7.75 tarball and complete
+[`ISSUE_205_v0.7.75_REGRESSION_GUIDE.md`](test-guides/ISSUE_205_v0.7.75_REGRESSION_GUIDE.md)
+on Windows 10 and Windows 11 as a non-blocking product validation follow-up.
+This follow-up does not gate SDK packaging, tagging, or publication.
 
 ---
 
-## 27. Windows GUI background subprocess visibility (v0.7.75)
+## 28. Host-configurable Shell Execution Contract (v0.7.77)
 
-KodaX SDK hosts do not need to add process-wide console suppression around the
-Runtime. In the v0.7.75 release candidate, Runtime Worker-reachable
-non-interactive/background child processes request `windowsHide: true` at their
-own spawn boundary. The covered paths include:
+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:
 
-- memory and Git metadata probes;
-- provider CLI execution and ACP servers;
-- LSP acquisition and language servers;
-- clipboard helpers, worktrees, review commands, and extension commands;
-- managed-task checkpoints and sandbox helpers.
+```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,
+  },
+});
+```
 
-The contract is intentionally narrow. Explicit external editors, terminal
-commands, and PTY sessions remain interactive. POSIX-only `ps`, `tmux`, and
-sandbox branches are reviewed bundle-audit exceptions rather than Windows
-visibility paths.
+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.
 
-`npm run build:bundle` audits every statically identifiable child-process call
-reachable from `dist/runtime-worker.js`. The packaged Electron daemon smoke then
-runs 20 ordinary queries with a Win32 probe and checks that the expected Git
-children never own a visible console window. These checks validate the SDK
-boundary, but they do not replace product-level validation in the packaged host.
-KodaX Space should install the exact v0.7.75 tarball and complete
-[`ISSUE_205_v0.7.75_REGRESSION_GUIDE.md`](test-guides/ISSUE_205_v0.7.75_REGRESSION_GUIDE.md)
-on Windows 10 and Windows 11 as a non-blocking product validation follow-up.
-This follow-up does not gate SDK packaging, tagging, or publication.
+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
+
+- [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/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