@kodax-ai/kodax 0.7.77 → 0.7.78

package/CHANGELOG.md

@@ -6,12 +6,184 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.7.78] - 2026-07-29
+
+### Added
+
+- **Evidence-Gated Background Skill Learning (FEATURE_263).** Completed the
+  Memory-first learning loop with durable non-blocking review, immutable
+  project-scoped learned Skill revisions, canonical record/fingerprint-gated
+  discovery, exact-use outcome attribution, bounded three-use canaries,
+  independently verified project activation, and full `/learn`/Runtime Learning
+  Center controls. Protected/formal Skills, global promotion, and Extension
+  authoring remain explicit user actions.
+- **Complete First-Run Split Configuration (FEATURE_276).** `kodax setup`,
+  first-run onboarding, and `--custom` now create and validate the core, MCP,
+  Extensions, and A2A active files plus annotated templates without
+  overwriting existing configuration or collecting secrets. Legacy integration
+  declarations are preserved and all cooperating writers share the same
+  lock/revision boundary.
+- **Standalone Sandbox SDK.** Added the `@kodax-ai/kodax/sandbox` subpath with
+  typed capability, doctor, setup/activation guidance, and explicit
+  host-owned contained command execution. The generic API reports structured
+  unavailability and never silently executes without containment.
+- Added read-only `/sandbox` diagnostics and optional `tool.sandbox` Runtime
+  events. Ordinary startup, history, and command cards remain quiet.
+
+### Changed
+
+- **Intent-Aligned Auto[LLM] Permission and ASRT Execution (FEATURE_277).**
+  Precisely modeled ordinary reads and workspace/system-temp mutations bypass
+  classifier latency independently of sandbox readiness. Other actions are
+  reviewed against bounded user intent and exact side effects; approval timeout
+  cancels only the current operation. ASRT is optional execution containment,
+  not permission authority, and admitted commands reuse a workspace-scoped
+  session instead of paying initialization/reset per command.
+- The published bundle now exposes 12 SDK subpaths (13 entries including the
+  root), adding `/sandbox`; README, README_CN, the SDK embedder guide, and
+  `kodax_manual` describe the same surface.
+
+### Fixed
+
+- The v0.7.78 semantic release gates now use frozen, resumable current-policy
+  runners instead of absent or historical fixtures. F263 revision
+  `f263-v0.7.78.4` freezes production learning-review and downstream action
+  bytes; F277 revision `f277-v0.7.78.4` freezes the intent-aligned permission
+  prompt and exact action evidence. Both default to zero provider calls, require
+  explicit owner authorization plus a feature-specific generation flag, keep
+  raw/blind-review evidence outside the repository, and fail closed on
+  case/prompt/scorer drift.
+- The first F263 paid validity pilot (`f263-v0.7.78.2`) correctly stopped after
+  4 calls: three outputs were rejected by the production normalizer and neither
+  positive sample produced a project canary. The production report contract now
+  requires `memoryPlan` and `capabilityDecision` as top-level siblings and
+  states the governed `requiresApproval=true` invariant without weakening the
+  strict normalizer or changing Skill admission policy.
+- The subsequent F263 `.3` safety panel found no credible high-severity harm:
+  no negative case normalized to a project canary and all nine positive raw
+  decisions selected `project_canary`. It also exposed one systematic utility
+  mismatch: six human-readable Skill names failed the production slug
+  invariant, leaving only 3/9 normalized positive canaries. The production
+  prompt/tool schema now state the existing lowercase hyphenated-slug and
+  64-character constraints. Strict validation, evidence thresholds, scope,
+  canary admission, and promotion policy remain unchanged; downstream expansion
+  stopped and fresh `.4` revisions bind the corrected bytes to one exact
+  candidate.
+- Runtime Actor trees now persist one exclusive owner per Session. A second live
+  Runtime can no longer recover another Runtime's active child turns; stale
+  controllers self-fence on CAS conflict, physically abort local executors,
+  refresh durable state and mailbox events, and expose actionable
+  `actor_owner_conflict` diagnostics. Runtime close and Session deletion release
+  ownership safely; archive/delete retain the owner through the filesystem
+  operation, while deletion quiesces executors before removing the file and
+  then performs a no-write local dispose. A per-Session gate closes Run/Agent
+  admission races with archive/delete, and SA root Runs now claim the same
+  owner fence. A Runtime-scoped loopback identity challenge now distinguishes
+  a live owner from an unrelated process that reused its PID: refused or
+  completed mismatched challenges prove stale, while timeouts and unknown
+  failures stay fail-closed. Legacy snapshots without an identity challenge
+  remain fail-closed because their live owner cannot be proven. Archived Sessions
+  reject Run/Agent execution and in-place mutation until unarchived, and
+  archived Actor CAS writes stay in the exact archived file instead of
+  recreating an active duplicate. Failed deletion retains its authoritative
+  snapshot and owner for retry, paired archive moves roll back on sidecar
+  failure, and external task aborts cover queued, preflight, pending, and
+  ambiguous start admission with a prompt `AbortSignal`, A2A request-level
+  propagation, retained per-Agent start ordering, coalesced reference-aware
+  cancellation, and bounded Actor-turn convergence.
+  Actor recovery preflight is byte-for-byte read-only, and Session recovery re-reads under the
+  cross-process lock without bypassing Actor ownership or moving archived data.
+  Stale full Session saves cannot replace the Actor CAS sub-snapshot, and all
+  full rewrites/island maintenance retain the resolved archived path.
+  Failed initialization releases a newly claimed fence and supports
+  same-instance/double-failure cleanup. Raw maintenance and retention reject
+  owned/non-terminal trees, complete Session file sets delete through
+  rollback-safe staging, and cross-process append revalidates and merges stale
+  watermarks plus same-length identity rewrites on the exact resolved path.
+  Runtime client, Worker, hosted-daemon, host, lease, and executor-plane close
+  attempts are shared and retryable after partial failure or timeout.
+- SDK daemon auto-start accepts an opt-in `daemonOrphanExitMs` lifecycle
+  contract. A newly ready daemon arms bootstrap grace even if its launching
+  client crashes before initialize; attach cancels the timer, and loss of the
+  final logical client starts a fresh full grace period. Other clients cancel
+  it, governed active work defers shutdown until terminal/idle state, and only
+  then does the daemon release its endpoint, state, and owner lock. Ordinary
+  CLI persistent daemons remain unchanged. The dedicated
+  `daemonOrphanExit:1` capability reports that the current host actually has
+  the policy enabled, and both Runtime facades safely replace an idle
+  persistent owner before relying on it.
+- Invalid optional MCP, A2A, or Extension configuration no longer aborts
+  daemon cold start. Each domain fails independently to a visible safe-empty
+  state, retains last-known-good data on later invalid edits, watches legacy
+  `config.json` fallbacks, and hot-recovers without mutating user files.
+  Detached bootstrap output is retained in continuously bounded logs, and the
+  daemon advertises the versioned `integrationConfigResilience` contract.
+- Auto[LLM] now retries classifier timeout/provider/contract failures once,
+  enforces its deadline even when a provider ignores cancellation, exposes
+  bounded prompt-size and TTFT phase diagnostics, and then degrades at the
+  Accept-edits boundary without switching to Auto[rules]. Classifier
+  concerns request user confirmation instead of hard-blocking. Exact,
+  explicitly requested workspace copy/move/rename/delete/write/create shell
+  calls can proceed without an LLM round trip independently of sandbox
+  readiness. ASRT adds optional execution containment; unavailable or
+  pre-launch-failed local containment falls back to the ordinary path without
+  another classifier/approval. Admitted commands in one workspace reuse a
+  long-lived ASRT session, so session-level initialization/reset is not paid
+  on every command. Normal history stays quiet, while `/sandbox` provides
+  explicit diagnostics and SDK hosts can opt into structured events.
+- Runtime Auto capability negotiation now requires
+  `runtimeAutoModeGuardrail:4` for daemon auto-start and consistently reports
+  `fallbackPersistsEngine:false` from embedded, Worker, and daemon hosts. An
+  idle v3 daemon is replaced before a v0.7.78 client relies on the
+  intent-preserving, non-Rules fallback contract.
+- The built-in A2A listener now rejects explicit Fetch-blocked ports and
+  retries ephemeral allocation when the operating system selects one, so a
+  successfully returned loopback URL is usable by Fetch-compatible clients.
+- `/learn promote` now has dedicated help, strict `--scope user` validation,
+  name/slug/capability-ID disambiguation, command completion, v2 learned-record
+  transport across inline/Worker/daemon, reviewed `ready` or `active_learned`
+  admission, and atomic non-overwriting publication with symlink/junction
+  containment and idempotent repeat behavior.
+- Learned Skill canaries now remain in `testing` until all three exact-revision
+  outcomes settle, activate only with at least one independently verified
+  success, and revalidate revision/fingerprint inside the second locked
+  invocation mutation. A stale artifact identity cannot consume a canary slot
+  or be attributed to the current revision.
+- Root AMA runs now execute the same governed MemorySession lifecycle as the
+  standard Agent path. The new root-only `memory_intent` signal binds an exact
+  current-user quote, distinguishes captured/queued/applied states, retains
+  durable review evidence, serializes review drains, and prevents generated
+  resume text or child Agents from authorizing Memory writes. Explicit
+  host-bound intent survives a later root cancellation without preserving
+  observations or lessons from the cancelled task; foreground completion still
+  stops at durable review enqueue rather than waiting for semantic review.
+- Workspace ASRT shell containment now denies reads from sensitive home
+  credential paths and the complete resolved agent home. Home-local executable
+  search paths cannot carve access back into a denied subtree; ordinary
+  external reads, workspace/temp writes, bootstrap execution, and the existing
+  network policy remain unchanged.
+- Edit mode no longer sends already-allowed static Skill loading to the client
+  permission broker, and Plan mode can load static instructions without
+  authorizing their later side effects. Dynamic Skill commands are blocked
+  live in Plan and otherwise require an explicit host-controlled executor;
+  protected writes and non-read-only shell actions keep their normal gates.
+- Managed Workflow Actor waits no longer turn the Actor API's internal
+  30-second polling window into a misleading `undefinedms` failure when the
+  workflow has no explicit timeout. Explicit deadlines remain authoritative,
+  and terminal Actor output closes event-delivery races.
+- The resume Session picker now renders stored timestamps in the host's local
+  timezone instead of presenting UTC values without a timezone marker.
+- The Windows ordinary-query regression now gives temporary recursive removal
+  a bounded native retry window for the intentionally non-blocking governed
+  Memory review queue. The release gate no longer fails with transient
+  `ENOTEMPTY`, without making background review block foreground completion.
+
 ## [0.7.77] - 2026-07-27
 
-> Release-ready candidate prepared at `@kodax-ai/kodax@0.7.77`. The Git tag,
-> GitHub Release, and npm publication are not created yet. Frozen F274/F275
-> paid evaluation completed with a joint owner `SHIP` decision; no unmeasured
-> task-effect, token, or latency improvement is claimed.
+> Released as Git tag `v0.7.77`, GitHub Release, and
+> `@kodax-ai/kodax@0.7.77` on npm. Frozen F274/F275 paid evaluation completed
+> with a joint owner `SHIP` decision; no unmeasured task-effect, token, or
+> latency improvement is claimed.
 
 ### Added
 

package/README.md

@@ -41,21 +41,30 @@
 ```bash
 npm i -g @kodax-ai/kodax
 
-# Pick any one you have an API key for:
-export ZHIPU_API_KEY=...        # or ANTHROPIC_API_KEY / OPENAI_API_KEY / KIMI_API_KEY /
-                                # MINIMAX_API_KEY / MIMO_API_KEY / ARK_API_KEY / QWEN_API_KEY /
-                                # QWEN_TOKEN_API_KEY /
-                                # DEEPSEEK_API_KEY / GEMINI_API_KEY
+# Pick any one you have an API key for (`kodax setup --help` lists all):
+export ZHIPU_API_KEY=...        # ANTHROPIC_API_KEY / OPENAI_API_KEY / DEEPSEEK_API_KEY /
+                                # KIMI_API_KEY / KIMI_CODE_API_KEY / QWEN_API_KEY /
+                                # QWEN_TOKEN_API_KEY / ZHIPU_CODING_API_KEY /
+                                # ZAI_CODING_API_KEY / MINIMAX_CODING_API_KEY /
+                                # MIMO_API_KEY / MIMO_CODING_API_KEY / ARK_CODING_API_KEY
 
 kodax
 ```
 
-That's it. You're in the REPL — ask anything in natural language. If this is a
-new machine with no provider selection or supported API-key environment
-variable, the bare `kodax` launch opens a metadata-only setup flow first. It
-never asks for the key itself; after choosing a provider/model, set the named
-environment variable, restart the terminal, and run `kodax` again. Use
-`kodax setup` to rerun that flow explicitly.
+That's it. You're in the REPL — ask anything in natural language. On a new
+machine with no selected provider, bare interactive `kodax` opens setup first,
+even if a supported credential environment variable already exists. Setup
+checks core, MCP, Extensions, and A2A active files plus all annotated templates
+without overwriting existing files. It never asks for the key itself; after
+choosing a provider/model, set the named environment variable, restart the
+terminal, and run `kodax` again. Use `kodax setup` to rerun the flow,
+`kodax setup --custom` for a guided custom provider, and `kodax setup --help`
+(or REPL `/setup --help`) for paths, provider variables, commands, and
+shortcuts. Interactive setup also checks the optional ASRT sandbox once:
+Windows may show a one-time UAC prompt; macOS/Linux report any required
+Seatbelt/bubblewrap dependencies. Declining or missing a dependency does not
+break ordinary permission handling, and normal startup will not keep reminding
+you.
 
 > **No-Node target machines:** download a Bun-compiled single binary for Windows / macOS / Linux × x64 + arm64 from the [GitHub Releases](https://github.com/icetomoyo/KodaX/releases) page. See [docs/release.md](docs/release.md) for the build pipeline.
 
@@ -147,23 +156,69 @@ npm link
 
 KodaX reads API keys from environment variables. For built-in providers, the fastest path is:
 
-```bash
-# Interactive metadata-only provider/model setup (does not collect a key)
-kodax setup
-```
-
-The command tells you the exact environment-variable name to set and exits so
-you can restart the terminal. You can also configure it directly:
+```bash
+# Interactive metadata-only provider/model setup (does not collect a key)
+kodax setup
+
+# Guided custom OpenAI/Anthropic-compatible provider
+kodax setup --custom
+
+# Complete guide; does not change files
+kodax setup --help
+```
+
+Setup checks these active files and matching `*.example.jsonc` references:
+
+- `~/.kodax/config.json` and `~/.kodax/config.example.jsonc`
+- `~/.kodax/integrations/mcp.json`
+- `~/.kodax/integrations/extensions.json`
+- `~/.kodax/integrations/a2a.json`
+
+The core active file remains strict JSON. The first line of the annotated
+`config.example.jsonc` points to all split files and documents every supported
+core setting. Setup preserves existing files and stages readable legacy
+`config.json#mcpServers` / `config.json#extensions` before creating empty
+authoritative split files. It tells you the exact environment-variable name to
+set and exits so you can restart the terminal. Existing active files are
+validated first; an invalid file is reported without creating or overwriting
+configuration. You can also configure it directly:
 
 ```bash
 # macOS / Linux
 export ZHIPU_API_KEY=your_api_key
 
 # PowerShell
-$env:ZHIPU_API_KEY="your_api_key"
-```
-
-For Qwen Token Plan, select `qwen-token-plan` and use its separate credential;
+$env:ZHIPU_API_KEY="your_api_key"
+```
+
+### 2.1 Activate the optional sandbox
+
+`kodax setup` and first-run setup check sandbox readiness. You can inspect or
+activate it explicitly:
+
+```bash
+kodax sandbox doctor
+kodax sandbox setup
+```
+
+- Windows uses a restricted sandbox account and network policy. A normal
+  terminal is sufficient; approve the one-time UAC prompt.
+- macOS uses Seatbelt/`sandbox-exec` and requires ripgrep
+  (`brew install ripgrep`).
+- Linux uses bubblewrap and requires `bubblewrap`, `socat`, and `ripgrep`
+  (install them with your distro's `apt`, `dnf`, or `pacman`).
+
+KodaX never runs `sudo` or a package manager automatically. If the sandbox is
+not active, deterministic safe operations and Auto[LLM] decisions keep the
+same permission behavior; only OS-level containment is absent. Ordinary runs
+do not repeatedly prompt for setup. In the REPL, `/sandbox` refreshes readiness
+and diagnostics without activating the backend or requesting elevation.
+Per-command sandbox routing remains internal and is not shown in normal command
+history. SDK embedders can use the same capability independently through
+`@kodax-ai/kodax/sandbox`; see the
+[SDK sandbox guide](docs/SDK_EMBEDDER_GUIDE.md#30-standalone-sandbox-sdk-v0778).
+
+For Qwen Token Plan, select `qwen-token-plan` and use its separate credential;
 `QWEN_API_KEY` does not authenticate this route:
 
 ```bash
@@ -412,7 +467,7 @@ for K2.7 Code, alongside `kimi-for-coding-highspeed` and the 1M `k3` tier. K3
 supports `low` / `high` / `max` reasoning with `high` as default; the 256K
 route supports image input but not video input.
 
-**v0.7.77 release-ready candidate:** AMA now chooses and composes six named
+**v0.7.77 release:** AMA now chooses and composes six named
 problem-solving patterns through the existing Actor control plane instead of
 using a fixed topology or hidden Workflow. Optional strategy metadata becomes
 a bounded, fact-only `PatternTrace`; the existing Sidecar remains the only
@@ -430,7 +485,42 @@ joint `SHIP` decision for the deterministic contracts. Semantic memory
 selection remains experimental and host opt-in; no task-quality, token, or
 latency improvement is claimed.
 
-The same candidate adds an opt-in, host-configurable Shell Execution Contract.
+**v0.7.78 evidence-gated learning, setup, and permission/sandbox release:**
+Background learning is Memory-first. Only repeated independently verified
+evidence, or an explicit preserve-as-Skill request with verified terminal
+evidence, can admit a low-risk declarative Skill to a bounded immutable
+project canary; three exact-revision uses and independently verified success
+are required before automatic project trust. Every revision remains visible
+and reversible in `/learn`. Protected/formal Skills, global promotion, and
+Extension authoring remain explicit user actions.
+
+First-run setup now creates and validates the split core/MCP/Extensions/A2A
+files and annotated templates without overwriting existing configuration or
+collecting secrets. Auto[LLM] admits precisely modeled ordinary reads and
+workspace/temp mutations before classifier latency, retries classifier
+infrastructure failure once, then falls back at the Accept-edits boundary
+without switching to rules. ASRT is optional execution containment rather
+than permission authority; `/sandbox` is the explicit diagnostic surface, and
+SDK hosts can use the standalone `/sandbox` subpath without a silent
+unsandboxed fallback. KodaX's workspace containment denies reads from common
+home credential paths and the complete resolved agent home without turning
+ordinary external reads into an allowlist. See the
+[v0.7.78 design](docs/features/v0.7.78.md), the
+[release checklist](docs/release.md#v0778-release-verification), and
+[SDK guide sections 29–30](docs/SDK_EMBEDDER_GUIDE.md#29-evidence-gated-background-skill-learning-feature_263-v0778).
+
+The release closure also preserves intent across adjacent surfaces: static
+Skill instructions load in Edit/Plan without granting later side effects,
+dynamic Skill commands require an explicit host-controlled executor, root AMA
+uses the governed `memory_intent` lifecycle (including explicit intent captured
+before a later cancellation), Workflow Actor waits remain
+unbounded unless the workflow sets a deadline, and Runtime Auto capability v4
+advertises `fallbackPersistsEngine:false` across embedded, Worker, and daemon
+hosts. Actor ownership additionally uses Runtime identity rather than PID alone,
+so PID reuse cannot pin a crashed owner. The resume Session picker also renders
+timestamps in the host's local timezone.
+
+The v0.7.77 release also adds an opt-in, host-configurable Shell Execution Contract.
 Runtime Session settings or an individual Run can select `pwsh`, Windows
 PowerShell, `cmd`, `bash`, `zsh`, or an explicit Git Bash executable; KodaX
 resolves the shell environment in the effective project cwd and then executes
@@ -487,12 +577,14 @@ The Space/IDE shared-daemon contract is documented in
 [SDK Embedder Guide section 23](docs/SDK_EMBEDDER_GUIDE.md#23-shared-coder-daemon-for-space-and-ide-hosts-feature_269-v0769).
 
 **v0.7.72–v0.7.73 Runtime permission contract:** Auto Mode is owned by the Runtime session,
-not by a UI hook. It reuses its LLM/rules guardrail across turns, classifies
-before the shared permission bridge, and persists an automatic fallback to
-rules. The same session settings can select a classifier model and bounded
-timeout; `auto` defaults to LLM classification and fails with a recoverable
-configuration error when no effective classifier model exists, rather than
-silently falling back. Runtime permission prompts now offer opaque, exact
+not by a UI hook. It reuses its LLM/rules guardrail across turns, classifies
+before the shared permission bridge, and persists explicit engine selection.
+The same session settings can select a classifier model and bounded
+timeout; `auto` defaults to LLM classification and fails with a recoverable
+configuration error when no effective classifier model exists, rather than
+silently falling back. In v0.7.78, classifier failures retry once and then use
+the Accept-edits safety boundary; they never change the engine to rules.
+Runtime permission prompts offer opaque, exact
 allow-once/session/persistent grant suggestions; persistent grants are
 daemon-owned and revisioned. Host plan exit is exposed only when the host
 supplies an approval callback. See the [Runtime Auto Mode integration guide](docs/SDK_EMBEDDER_GUIDE.md#24-runtime-owned-auto-mode-and-plan-approval-bridges-v0772v0773).
@@ -510,7 +602,7 @@ kodax --repo-intelligence full --repo-intelligence-trace
 
 ## Architecture
 
-KodaX uses a **monorepo architecture** with npm workspaces. Source layout currently has 4 workspace packages; published as a single bundled npm package `@kodax-ai/kodax` with 11 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/media`, `/repl`, `/skills`, `/mcp`, `/session`, `/runtime`, `/a2a`, `/experimental-memory`; ADR-024 + ADR-032 + ADR-038, with ADR-036 consolidation):
+KodaX uses a **monorepo architecture** with npm workspaces. Source layout currently has 4 workspace packages; published as a single bundled npm package `@kodax-ai/kodax` with 12 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/media`, `/repl`, `/skills`, `/mcp`, `/session`, `/runtime`, `/sandbox`, `/a2a`, `/experimental-memory`; ADR-024 + ADR-032 + ADR-038, with ADR-036 consolidation):
 
 ```
 KodaX/
@@ -536,9 +628,9 @@ KodaX/
 │
 ├── src/                     # CLI entry + SDK subpath entries
 │   ├── kodax_cli.ts         # Main CLI entry point (bin: `kodax`)
-│   └── sdk-*.ts             # SDK subpath re-exports → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime,a2a,experimental-memory}
-│
-└── package.json             # Root workspace config; release.mjs rewrites name + injects subpath exports
+│   └── sdk-*.ts             # SDK subpath re-exports → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime,sandbox,a2a,experimental-memory}
+│
+└── package.json             # Publish-shaped exports; release.mjs only toggles private during pack/publish
 ```
 
 ### Package Dependencies
@@ -585,9 +677,9 @@ Source-side workspace package names (`@kodax-ai/*`). npm consumers install the s
 KodaX has two layers that consumers should understand separately:
 
 - **Source-side**: 4 workspace packages above (what developers see when reading the repo).
-- **npm-published**: a single bundled package `@kodax-ai/kodax` with 11 SDK subpaths (what SDK consumers `import` from). The subpaths are split into two roles:
+- **npm-published**: a single bundled package `@kodax-ai/kodax` with 12 SDK subpaths (what SDK consumers `import` from). The subpaths are split into two roles:
   - **Full-package subpaths** (`/agent`, `/llm`, `/coding`, `/repl`) — each one maps 1:1 to a source workspace and exposes its complete public API.
-  - **Integration and narrow subpaths** (`/media`, `/skills`, `/mcp`, `/session`, `/runtime`, `/a2a`, `/experimental-memory`) — focused host surfaces. `/a2a` composes the neutral F258 plane with the Runtime facade; it does not add A2A wire types to `/agent`.
+  - **Integration and narrow subpaths** (`/media`, `/skills`, `/mcp`, `/session`, `/runtime`, `/sandbox`, `/a2a`, `/experimental-memory`) — focused host surfaces. `/a2a` composes the neutral F258 plane with the Runtime facade; it does not add A2A wire types to `/agent`.
 
 | Source package | npm subpath | Type | What you get | Example consumer |
 |---|---|---|---|---|
@@ -599,9 +691,10 @@ KodaX has two layers that consumers should understand separately:
 | `packages/agent`  | `@kodax-ai/kodax/experimental-memory` | **Experimental subset** | Thin F228-backed `MemoryAgent` / `MemorySession` contracts for scoped recall, deliberate query, observations, and outcomes | SDK hosts explicitly evaluating FEATURE_260 |
 | `packages/coding` | `@kodax-ai/kodax/coding`  | Full package | Coding agent + 50+ tools + repo-intelligence (505 exports) | Build a Claude Code-shape product |
 | `packages/repl`   | `@kodax-ai/kodax/repl`    | Full package | Ink TUI + permission modes + commands (217 exports) | Terminal-UI consumers |
-| `packages/repl`   | `@kodax-ai/kodax/session` | **Narrow subset** | Session management only — `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` / ... (17 exports) | IDE plugins and desktop hosts reading session history |
-| `src`             | `@kodax-ai/kodax/runtime` | Host API | Embedded/Worker/daemon runtime facade, sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics/external agents, daemon protocol schema (10 exports) | SDK hosts, Space/IDE clients, daemon clients |
-| `src`             | `@kodax-ai/kodax/a2a` | Integration edge | A2A 1.0 Agent Card discovery, JSON-RPC/SSE F258 executor, safe fetch policy, and authenticated Runtime-backed Agent server | Agent orchestrators and KodaX hosts |
+| `packages/repl`   | `@kodax-ai/kodax/session` | **Narrow subset** | Session management only — `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` / ... (17 exports) | IDE plugins and desktop hosts reading session history |
+| `src`             | `@kodax-ai/kodax/runtime` | Host API | Embedded/Worker/daemon runtime facade, sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics/external agents, daemon protocol schema (10 exports) | SDK hosts, Space/IDE clients, daemon clients |
+| `src`             | `@kodax-ai/kodax/sandbox` | Host API | Explicit ASRT capability/doctor/setup and host-owned contained command execution; unavailability never means silent ordinary execution | SDK hosts that need standalone process containment |
+| `src`             | `@kodax-ai/kodax/a2a` | Integration edge | A2A 1.0 Agent Card discovery, JSON-RPC/SSE F258 executor, safe fetch policy, and authenticated Runtime-backed Agent server | Agent orchestrators and KodaX hosts |
 
 **Rule of thumb**: if you need Runner / Agent / fan-out, import from `/agent`. If you only need skills or mcp APIs, import from `/skills` or `/mcp` to get a smaller bundle. The narrow subsets are subsets of the full packages — they do **not** expose extra symbols.
 
@@ -633,7 +726,7 @@ KodaX has two layers that consumers should understand separately:
 
 **Experimental Memory Agent SDK (FEATURE_260, v0.7.68)**: `/experimental-memory` exposes the thin agent-layer `MemoryAgent` and scoped `MemorySession` lifecycle over the existing governed F228 plane. Passive recall is zero-wait; `query()` is read-only and deliberate; durable changes still require the proposal/preview/fingerprint/apply path. The Action LLM remains the final decision maker, recalled content stays low-authority, and safety/scope gates remain deterministic. See the [direct session and boundary guide](docs/SDK_EMBEDDER_GUIDE.md#21-experimental-governed-memory--experimental-memory-feature_260-v0768).
 
-**Bidirectional A2A 1.0 (FEATURE_267, v0.7.69)**: `/a2a` discovers allowed Agent Cards and installs a JSON-RPC/SSE executor through the existing F258 plane. Configured outbound Agents are also registered automatically as `external:<name>` in embedded CLI and user-daemon Runtimes, so the main Agent can orchestrate them without host code. One `a2a.json` may hold many outbound registrations and at most one inbound server, which publishes either the Runtime default or one validated `~/.kodax/agents/*.md` Agent behind an authenticated Runtime facade. The built-in listener is loopback-only; public deployment uses `handle()` behind host-owned TLS and authorization. A2A 0.3, gRPC, HTTP+JSON, push notifications, and automatic public exposure are not advertised. See the [client/server recipes and security boundaries](docs/SDK_EMBEDDER_GUIDE.md#22-bidirectional-a2a-10--a2a-feature_267-v0769).
+**Bidirectional A2A 1.0 (FEATURE_267, v0.7.69)**: `/a2a` discovers allowed Agent Cards and installs a JSON-RPC/SSE executor through the existing F258 plane. Configured outbound Agents are also registered automatically as `external:<name>` in embedded CLI and user-daemon Runtimes, so the main Agent can orchestrate them without host code. One `a2a.json` may hold many outbound registrations and at most one inbound server, which publishes either the Runtime default or one validated `~/.kodax/agents/*.md` Agent behind an authenticated Runtime facade. The built-in listener is loopback-only and will not return a port blocked by Fetch-compatible clients; public deployment uses `handle()` behind host-owned TLS and authorization. A2A 0.3, gRPC, HTTP+JSON, push notifications, and automatic public exposure are not advertised. See the [client/server recipes and security boundaries](docs/SDK_EMBEDDER_GUIDE.md#22-bidirectional-a2a-10--a2a-feature_267-v0769).
 
 **A2A interoperability and authentication hardening** keeps a discovered
 interface on the trusted Agent Card origin and sends credentials only when one
@@ -692,8 +785,9 @@ kodax a2a expose                 # or: kodax a2a expose document-agent
 kodax a2a serve                  # loopback http://127.0.0.1:8765
 ```
 
-MCP, A2A, and Extension declarations live in one user file per domain under
-`~/.kodax/integrations/`. Use `kodax config template <mcp|a2a|extensions>`,
+MCP, A2A, and Extension declarations live in one user file per domain under
+`~/.kodax/integrations/`. Use `kodax config paths`,
+`kodax config template <core|mcp|a2a|extensions>`,
 `kodax integrations migrate --apply`, and the `kodax mcp`, `kodax a2a`, or
 `kodax extensions` commands to manage them. Migration imports only legacy
 `config.json#mcpServers` and `config.json#extensions`; A2A has no legacy source.
@@ -844,12 +938,14 @@ import { createImageArtifactFromPath } from '@kodax-ai/kodax/media'; // input ar
 import { SkillRegistry } from '@kodax-ai/kodax/skills';         // zero-dep skill loader
 import { loadConfig } from '@kodax-ai/kodax/repl';              // REPL config / session helpers
 import { createMcpManager } from '@kodax-ai/kodax/mcp';         // MCP popout manager (v0.7.42)
-import { listSessions } from '@kodax-ai/kodax/session';         // session history helpers
-import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';   // embedded/daemon runtime API
-import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';    // A2A 1.0 client/server edge
-```
-
-All 12 SDK entries (root + 11 subpaths) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
+import { listSessions } from '@kodax-ai/kodax/session';         // session history helpers
+import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';   // embedded/daemon runtime API
+import { runKodaXSandboxed } from '@kodax-ai/kodax/sandbox';    // standalone ASRT containment
+import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';    // A2A 1.0 client/server edge
+import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-in memory SDK
+```
+
+All 13 SDK entries (root + 12 subpaths) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
 
 For the complete host-facing contract — including embedded/Worker/daemon ownership,
 external-agent registration and task control, session cursor pagination, workflow
@@ -1000,16 +1096,19 @@ KodaX provides 3 permission modes for fine-grained control:
 **Features:**
 - In `accept-edits` mode, choosing "always" can persist safe Bash allow-patterns
 - Plan mode includes system prompt context for LLM awareness
-- Permanent protection zones: `.kodax/`, `~/.kodax/`, paths outside project
+- Sensitive/protected or unresolved targets enter Auto[LLM]/approval review;
+  ordinary reads outside the project are allowed
 - Pattern-based permission: Allow specific Bash commands (e.g., `Bash(npm install)`)
 - Unified diff display for write/edit operations
-- Auto Mode runs guardrail classification before the permission UI; a safe
-  allow verdict does not create a pending approval request. The session records
-  an automatic LLM-to-rules fallback for later turns.
+- Auto Mode first admits exactly modeled safe reads and workspace/temp
+  mutations without classifier latency. Remaining actions are reviewed against
+  bounded user intent and exact operation facts; a safe verdict creates no
+  pending approval request. Classifier failures retry once, then use the
+  Accept-edits safety boundary rather than silently switching to Auto[rules].
 - Shift-Tab cycles `Plan -> Edits -> Auto`; Shift+Enter inserts a newline. Auto
   immediately displays `Auto[LLM]` or `Auto[RULES]`, and rapid mode changes are
-  persisted in input order. `Auto[RULES]` is a valid sticky fallback/manual
-  state; use `/auto-engine llm` to opt back into LLM classification.
+  persisted in input order. `Auto[RULES]` remains an explicit/manual engine;
+  use `/auto-engine llm` to select LLM classification.
 - Runtime-backed prompts can offer exact `allow once`, `allow this session`,
   and `always allow` choices. Return the Runtime-issued opaque suggestion;
   never derive or widen a permission rule from the displayed command or path.
@@ -1176,7 +1275,7 @@ await runKodaX({
 
 ## SDK Usage
 
-KodaX ships as a single npm package `@kodax-ai/kodax` with 11 SDK subpath exports (ADR-024 v0.7.39 + ADR-032 v0.7.42 + ADR-038 v0.7.49 + v0.7.56 `/media` + v0.7.64 `/runtime` + v0.7.68 `/experimental-memory` + v0.7.69 `/a2a`). Each subpath is tree-shake-friendly so consumers pull only what they need:
+KodaX ships as a single npm package `@kodax-ai/kodax` with 12 SDK subpath exports (ADR-024 v0.7.39 + ADR-032 v0.7.42 + ADR-038 v0.7.49 + v0.7.56 `/media` + v0.7.64 `/runtime` + v0.7.68 `/experimental-memory` + v0.7.69 `/a2a` + v0.7.78 `/sandbox`). Each subpath is tree-shake-friendly so consumers pull only what they need:
 
 ```bash
 npm install @kodax-ai/kodax
@@ -1190,10 +1289,11 @@ import { KODAX_TOOLS } from '@kodax-ai/kodax/coding';             // tools + pro
 import { createImageArtifactFromPath } from '@kodax-ai/kodax/media'; // input artifact helpers
 import { runInkInteractiveMode } from '@kodax-ai/kodax/repl';     // Ink TUI entrypoint
 import { SkillRegistry } from '@kodax-ai/kodax/skills';           // zero-dep skill loader
-import { createMcpManager } from '@kodax-ai/kodax/mcp';           // MCP popout manager (v0.7.42)
-import { listSessions } from '@kodax-ai/kodax/session';           // session history helpers
-import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';     // embedded/daemon runtime API
-import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';      // A2A 1.0 client/server edge
+import { createMcpManager } from '@kodax-ai/kodax/mcp';           // MCP popout manager (v0.7.42)
+import { listSessions } from '@kodax-ai/kodax/session';           // session history helpers
+import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';     // embedded/daemon runtime API
+import { runKodaXSandboxed } from '@kodax-ai/kodax/sandbox';      // explicit standalone containment
+import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';      // A2A 1.0 client/server edge
 import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-in experimental memory SDK
 ```
 
@@ -1368,8 +1468,8 @@ await runInkInteractiveMode({ provider: 'zhipu-coding', effort: 'auto' });
 | mimo-coding | `MIMO_CODING_API_KEY` | Native | mimo-v2.5-pro (Xiaomi Token Plan, Anthropic-compat) |
 | ark-coding | `ARK_CODING_API_KEY` | Native | glm-5.2 (Volcengine Ark Coding Plan — GLM-5.2 (alias: `glm-latest`) · Kimi K2.7 Code / K2.6 · MiniMax M3 / M2.7 · DeepSeek V4 Pro / V4 Flash · Doubao Seed 2.0 Code / Pro / Lite · Doubao Seed Code) |
 | deepseek | `DEEPSEEK_API_KEY` | Native | deepseek-v4-flash (`deepseek-v4-pro` via `/model`) |
-| gemini-cli | `GEMINI_API_KEY` | Prompt-only / CLI bridge | (via gemini CLI) |
-| codex-cli | `OPENAI_API_KEY` | Prompt-only / CLI bridge | (via codex CLI) |
+| gemini-cli | Provider CLI authentication (no KodaX API-key variable) | Prompt-only / CLI bridge | (via gemini CLI) |
+| codex-cli | Provider CLI authentication (no KodaX API-key variable) | Prompt-only / CLI bridge | (via codex CLI) |
 
 > **Custom providers**: any OpenAI- or Anthropic-compatible endpoint can be added via `customProviders[]` in `~/.kodax/config.json` (CLI) or `registerCustomProviders()` (library). See the [Quick Start](#2-configure-a-provider) for the configuration shape.
 
@@ -1483,9 +1583,45 @@ Built-in skills include:
 - **tdd** - Test-driven development workflow
 - **git-workflow** - Git commit and workflow automation
 
-Skills are stored in `~/.kodax/skills/` and can be extended with custom skills.
-
----
+Skills are stored in `~/.kodax/skills/` and can be extended with custom skills.
+F263 background learning is Memory-first: a single correction does not create
+a Skill. Repeated independently verified evidence can create a low-risk,
+immutable project-scoped testing revision for at most three exact-revision
+uses. Promotion requires independently verified success. Use `/learn` to
+inspect, disable, rollback, trust, or reject learned revisions. Protected or
+formal Skills, user-global promotion, and Extension authoring remain explicit
+user actions.
+
+### Promote a learned Skill to the user catalog
+
+Automatic canary activation and user-catalog promotion are different:
+
+- independently verified canary success changes `testing` to
+  `active_learned` inside the project-scoped Learned Area;
+- `/learn promote` is an explicit ownership transfer that copies one exact
+  reviewed `ready` or `active_learned` revision into the formal user Skill
+  catalog and changes its lifecycle to `promoted_user`.
+
+Inspect the revision first, then promote it by name, slug, or exact capability
+ID:
+
+```text
+/learn show normalize-release-notes
+/learn promote normalize-release-notes --scope user
+```
+
+`--scope user` is the only supported scope and may be omitted. Invalid scopes,
+unknown options, duplicate scope options, and extra operands fail without
+changing the catalog. Promotion writes to the configured KodaX user Skill
+directory—normally `~/.kodax/skills/<slug>/SKILL.md`—and never overwrites
+different formal Skill content.
+
+Use `/learn promote --help`, `/learn help promote`, or
+`/help learn promote` for the dedicated command reference. In the Ink Learning
+Center, open `/learn`, select an `active_learned` Skill, and choose
+**Promote to user catalog**.
+
+---
 
 ## Commands (CLI)