@kodax-ai/kodax 0.7.77 → 0.7.78

package/dist/types-chunks/{types.d-DCQVBqVn.d.ts → types.d-BbtGlKZu.d.ts}

@@ -56,6 +56,11 @@ interface SkillMetadata {
     argumentHint?: string;
     path: string;
     source: ResolvedSkillSource;
+    readonly learned?: {
+        readonly capabilityId: string;
+        readonly revision: number;
+        readonly fingerprint: string;
+    };
     /** If true, exclude from system prompt; still invokable by explicit slash forms. */
     disableModelInvocation: boolean;
 }
@@ -204,7 +209,22 @@ interface SkillPathsConfig {
     userPaths: string[];
     pluginPaths: string[];
     builtinPath: string;
+    /**
+     * Deprecated loose-file path. It remains in the public shape for source
+     * compatibility but is intentionally not discovered without a manifest.
+     */
     learnedPath?: string;
+    learnedArea?: LearnedSkillDiscoveryConfig;
+}
+interface LearnedSkillDiscoveryConfig {
+    readonly rootDir: string;
+    readonly expectedScope: {
+        readonly configHomeHash: string;
+        readonly tenantHash: string;
+        readonly projectHash: string;
+    };
+    readonly testingBindings?: Readonly<Record<string, string>>;
+    readonly now?: string;
 }
 /**
  * Get default skill discovery paths
@@ -215,13 +235,15 @@ interface SkillPathsConfig {
  * 3. User - ~/.agents/skills/ (AgentSkills standard)
  * 4. Plugin - (dynamic)
  * 5. Builtin - packages/skills/src/builtin/
- * 6. Learned - ~/.kodax/learned/skills/ (never shadows a formal source)
+ * Learned Skills are supplied separately through a record-gated Learned Area
+ * and never through a loose directory.
  */
 declare function getDefaultSkillPaths(projectRoot?: string): SkillPathsConfig;
 /**
  * All skill paths in priority order (highest to lowest)
  *
- * Priority: Project > User > Plugin > Builtin > Learned
+ * Priority: Project > User > Plugin > Builtin. Record-gated Learned Skills
+ * are appended by discovery after these formal sources.
  * - Project: Project-specific skills override everything else
  * - User: User preferences (~/.kodax/ and ~/.agents/)
  * - Plugin: Third-party plugins
@@ -234,4 +256,4 @@ declare function getSkillPathsFlat(config: SkillPathsConfig): Array<{
 }>;
 
 export { getDefaultSkillPaths as m, getSkillPathsFlat as n };
-export type { ISkillRegistry as I, ResolvedSkillSource as R, Skill as S, IVariableResolver as a, SkillArtifact as b, SkillContext as c, SkillDynamicContextExecutor as d, SkillFile as e, SkillFrontmatter as f, SkillHook as g, SkillHooks as h, SkillMetadata as i, SkillPathsConfig as j, SkillResult as k, SkillSource as l };
+export type { ISkillRegistry as I, LearnedSkillDiscoveryConfig as L, ResolvedSkillSource as R, Skill as S, IVariableResolver as a, SkillArtifact as b, SkillContext as c, SkillDynamicContextExecutor as d, SkillFile as e, SkillFrontmatter as f, SkillHook as g, SkillHooks as h, SkillMetadata as i, SkillPathsConfig as j, SkillResult as k, SkillSource as l };

package/dist/types-chunks/{types.d-DCsKM8aT.d.ts → types.d-DVDTIfB_.d.ts}

@@ -1,8 +1,8 @@
 import { a9 as KodaXWireReasoningEffort, a1 as KodaXToolDefinition, a3 as KodaXToolResultContentItem, k as KodaXMessage } from './types.d-DIpZJKUl.js';
 import { K as KodaXBaseProvider } from './base.d-4e74xDdy.js';
 import { C as CapabilityKind, a as CapabilityProvider } from './capability.d-K664nHOS.js';
-import { by as KodaXJsonValue, bm as KodaXExtensionSessionRecord, bo as KodaXExtensionStore } from './types.d-RdWRfUEs.js';
-import { aK as KodaXToolExecutionContext, br as ToolSideEffect } from './bash-prefix-extractor.d-pZdu6qt7.js';
+import { bF as KodaXJsonValue, bt as KodaXExtensionSessionRecord, bv as KodaXExtensionStore } from './types.d-BA-Jwpfs.js';
+import { aP as KodaXToolExecutionContext, bx as ToolSideEffect } from './bash-prefix-extractor.d-uAe2Oqda.js';
 
 /**
  * KodaX Constructed-World types (FEATURE_087, v0.7.28).

package/dist/types-chunks/{utils.d-CDduqbFw.d.ts → utils.d-CVp6bFl9.d.ts}

@@ -1,9 +1,9 @@
 import { k as KodaXMessage, F as KodaXReasoningMode, d as KodaXCustomProviderConfig, p as KodaXProviderCapabilityProfile } from './types.d-DIpZJKUl.js';
-import { O as KodaXContextTokenSnapshot, an as KodaXSkillDynamicContextPolicy, t as KodaXAgentMode, a7 as KodaXRepoIntelligenceMode, a1 as KodaXOptions, ao as KodaXSkillInvocationContext } from './bash-prefix-extractor.d-pZdu6qt7.js';
-import { bX as KodaXSessionUiHistoryItem, bM as KodaXSessionLineage, bD as KodaXSessionArtifactLedgerEntry, bn as KodaXExtensionSessionState, bm as KodaXExtensionSessionRecord, bT as KodaXSessionRuntimeInfo, eb as WorkflowProcessSource } from './types.d-RdWRfUEs.js';
-import { d as AgentsFile, r as AutoModeStats, x as KodaXMcpServersConfig } from './guardrail.d-B0PwAZVR.js';
+import { c3 as KodaXSessionUiHistoryItem, bU as KodaXSessionLineage, bL as KodaXSessionArtifactLedgerEntry, bu as KodaXExtensionSessionState, bt as KodaXExtensionSessionRecord, b$ as KodaXSessionRuntimeInfo, e$ as WorkflowProcessSource } from './types.d-BA-Jwpfs.js';
+import { O as KodaXContextTokenSnapshot, as as KodaXSkillDynamicContextPolicy, t as KodaXAgentMode, a8 as KodaXRepoIntelligenceMode, a1 as KodaXOptions, at as KodaXSkillInvocationContext } from './bash-prefix-extractor.d-uAe2Oqda.js';
+import { d as AgentsFile, s as AutoModeStats, J as KodaXMcpServersConfig } from './guardrail.d-CXDYRgZ3.js';
 import * as readline from 'readline';
-import { R as PermissionMode, L as LearningBinding, E as LearningSurfaceSnapshot } from './public-api.d--fF88JrC.js';
+import { R as PermissionMode, L as LearningBinding, E as LearningSurfaceSnapshot } from './public-api.d-B3AohsxN.js';
 import { SpawnSyncReturns } from 'child_process';
 
 /**
@@ -310,6 +310,22 @@ interface CommandCallbacks {
     rewindSession?: (selector?: string) => Promise<SessionRewindStatus>;
     getCostReport?: () => string | null;
     getRuntimeStatus?: () => Promise<RuntimeSurfaceStatus | undefined>;
+    /** Canonical host parser used by `/setup` for the root-owned A2A schema. */
+    validateSetupA2AConfig?: (value: unknown) => unknown;
+    /** Root-owned sandbox activation because ASRT is distributed by the host package. */
+    prepareSetupSandbox?: () => Promise<{
+        readonly status: 'ready' | 'cancelled' | 'unavailable';
+        readonly lines: readonly string[];
+    }>;
+    /** Explicit read-only `/sandbox` probe. Ordinary startup never calls it. */
+    inspectSandbox?: () => Promise<{
+        readonly ready: boolean;
+        readonly platform: string;
+        readonly version: string;
+        readonly backend: string;
+        readonly diagnostics: readonly string[];
+        readonly guidance: readonly string[];
+    }>;
     learning?: LearningBinding;
     getLearningSummary?: () => Promise<LearningSurfaceSnapshot>;
     openLearningCenter?: (nameOrSlug?: string) => Promise<void>;
@@ -364,7 +380,7 @@ interface CommandDefinition {
     aliases?: string[];
     description: string;
     usage?: string;
-    detailedHelp?: () => void;
+    detailedHelp?: (args?: readonly string[]) => void;
     handler: CommandHandler;
     source?: CommandSource;
     priority?: CommandPriority;
@@ -406,7 +422,7 @@ interface Command {
     description: string;
     usage?: string;
     handler: CommandHandler;
-    detailedHelp?: () => void;
+    detailedHelp?: (args?: readonly string[]) => void;
     source?: CommandSource;
     priority?: CommandPriority;
     location?: 'user' | 'project' | 'path';

package/docs/SDK_EMBEDDER_GUIDE.md

@@ -33,8 +33,12 @@ are NOT obvious from inspecting the type definitions alone:
 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)
+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)).
@@ -3695,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
@@ -3784,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',
@@ -3819,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
@@ -3832,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,
@@ -4076,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
 
@@ -4357,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
 
@@ -4369,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
@@ -4405,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
 
@@ -4773,6 +4814,309 @@ 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