@kodax-ai/kodax 0.7.95 → 0.7.96-alpha.2

package/dist/types-chunks/{utils.d-CWUyLiXo.d.ts → utils.d-CnxefMos.d.ts}

@@ -1,10 +1,10 @@
-import { k as KodaXMessage, G as KodaXReasoningMode, d as KodaXCustomProviderConfig, q as KodaXProviderCapabilityProfile } from './types.d-CK9A9rpP.js';
-import { df as WorkflowProcessSource } from './controller.d-C5noq5-w.js';
-import { Q as KodaXContextTokenSnapshot, aD as KodaXSkillDynamicContextPolicy, t as KodaXAgentMode, ai as KodaXRepoIntelligenceMode, a4 as KodaXOptions, aE as KodaXSkillInvocationContext } from './bash-prefix-extractor.d-B2rxNI4L.js';
-import { e as AgentsFile, t as AutoModeStats, T as KodaXMcpServersConfig } from './guardrail.d-DqHD-61O.js';
+import { k as KodaXMessage, G as KodaXReasoningMode, d as KodaXCustomProviderConfig, q as KodaXProviderCapabilityProfile } from './types.d-Xy0f3x4i.js';
+import { df as WorkflowProcessSource } from './controller.d-C7tXUcXo.js';
+import { Q as KodaXContextTokenSnapshot, aD as KodaXSkillDynamicContextPolicy, t as KodaXAgentMode, ah as KodaXRepoIntelligenceMode, a3 as KodaXOptions, aE as KodaXSkillInvocationContext } from './bash-prefix-extractor.d-DQOlA8cy.js';
+import { e as AgentsFile, t as AutoModeStats, T as KodaXMcpServersConfig } from './guardrail.d-DKTyEHJa.js';
 import * as readline from 'readline';
-import { aq as KodaXSessionUiHistoryItem, af as KodaXSessionLineage, a6 as KodaXSessionArtifactLedgerEntry, V as KodaXExtensionSessionState, U as KodaXExtensionSessionRecord, am as KodaXSessionRuntimeInfo } from './types.d-rUOjXych.js';
-import { S as PermissionMode, L as LearningBinding, G as LearningSurfaceSnapshot } from './public-api.d-D7fXaWW8.js';
+import { aq as KodaXSessionUiHistoryItem, af as KodaXSessionLineage, a6 as KodaXSessionArtifactLedgerEntry, V as KodaXExtensionSessionState, U as KodaXExtensionSessionRecord, am as KodaXSessionRuntimeInfo } from './types.d-BbZjR0Wr.js';
+import { S as PermissionMode, L as LearningBinding, G as LearningSurfaceSnapshot } from './public-api.d-Dx3L3W4Z.js';
 import { SpawnSyncReturns } from 'child_process';
 
 /**

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@kodax-ai/kodax",
-  "version": "0.7.95",
+  "version": "0.7.96-alpha.2",
   "description": "KodaX lightweight coding agent - TypeScript implementation with 16 built-in LLM provider aliases, published as a Node-free single-file CLI and SDK",
   "type": "module",
   "private": false,
+  "packageManager": "npm@10.9.8",
   "publishConfig": {
     "access": "public"
   },
@@ -81,12 +82,13 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "npm run config:templates:check && npm run build:packages && npm run build:bundle && npm run build:dts",
+    "build": "npm run config:templates:check && npm run build:packages && npm run build:native && npm run build:bundle && npm run build:dts",
     "config:templates:sync": "node scripts/sync-config-templates.mjs",
     "config:templates:check": "node scripts/sync-config-templates.mjs --check",
     "build:dts": "node scripts/build-dts.mjs",
     "build:packages": "tsc -b tsconfig.build.json && npm run copy:builtin -w @kodax-ai/agent && npm run copy:provider-caps -w @kodax-ai/llm",
     "build:bundle": "node scripts/build-bundle.mjs",
+    "build:native": "node scripts/build-native.mjs",
     "dev": "node --max-old-space-size=4096 --require ./scripts/production-env.cjs --import tsx src/kodax_bootstrap.ts",
     "dev:cli": "node --max-old-space-size=4096 --require ./scripts/production-env.cjs --import tsx src/kodax_bootstrap.ts",
     "dev:mem-diag": "node scripts/mem-diag-launch.cjs",
@@ -98,6 +100,8 @@
     "build:binary": "node scripts/build-binary.mjs",
     "build:binary:all": "node scripts/build-binary.mjs --all",
     "test": "vitest run",
+    "test:native": "node scripts/test-native.mjs",
+    "test:packed-native": "node scripts/test-packed-native.mjs",
     "test:fast": "vitest run -c vitest.fast.config.ts",
     "test:changed": "vitest run --changed",
     "test:unit": "vitest run -c vitest.unit.config.ts",
@@ -183,6 +187,7 @@
     "ink-testing-library": "^4.0.0",
     "rollup": "^4.60.4",
     "rollup-plugin-dts": "^6.4.1",
+    "undici": "^6.28.0",
     "vitest": "^3.2.4"
   },
   "engines": {
@@ -202,12 +207,14 @@
     "dist/runtime-worker.js",
     "dist/constructed-handler-worker.js",
     "dist/types-chunks",
+    "dist/native",
     "config-templates",
     "scripts/kodax-bin.cjs",
     "scripts/production-env.cjs",
     "README.md",
     "README_CN.md",
-    "docs/SDK_EMBEDDER_GUIDE.md",
+    "public_docs/sdk/embedder-guide.md",
+    "public_docs/configuration/sandbox.md",
     "LICENSE",
     "CHANGELOG.md"
   ]

package/public_docs/README.md

@@ -0,0 +1,130 @@
+# KodaX Documentation
+
+Public documentation for KodaX users and SDK integrators.
+
+The current release is `v0.7.96-alpha.2` (GitHub pre-release; npm publication
+remains manual). It separates trusted text transactions from platform shell
+containment on Windows, Linux, and macOS: controlled text tools commit in the
+trusted KodaX Runtime with per-file kernel locking, revision CAS, and flushed
+atomic replacement, while Windows shell commands run through the native
+restricted-token runner (native shell protocol version 7, Windows
+`sandboxRuntime:6`, one-time `kodax sandbox setup` cutover). It replaces the
+local tool-result capacity hard gate with capacity-debt admission and a
+bounded recovery ladder (`capacityDebt` metadata, floor-bounded output
+reserve, `failureKind: "context_capacity"` with structured `contextTokens`),
+exposes one credential-safe `failureDetail` across failure events, Run
+result/status, and Session diagnostics, and registers the
+`deepseek-v4-flash-vision-exp` and `glm-5.3-flash` models plus the custom
+provider `imageInput` flag. On top of v0.7.95: self-healing
+Windows sandbox cleanup (Windows `sandboxRuntime:5`,
+`runtimeExitSettlement:2`),
+Issue 301 learning-lock / fullscreen-terminal / Explicit-Skill recovery, and
+Issue 302 coding-result finalization before the public completion signal, on
+top of the v0.7.94 concurrent
+sandboxed text mutations, Issue 300 authorized-root git trust, scheduled
+shutdown failure reporting, missing-workspace Run start, and
+`conversationHistory:2`, the
+v0.7.93 failed-exit fast settlement, previous-boot ACL recovery, and isolated
+provider abort classification, plus the v0.7.92 filesystem-effect
+operation-token coordinator, recorded-release owners, managed Session-before-
+completion ordering, canonical-first resume reconstruction, `sandboxRuntime:4`,
+and `crashOutcomeModel:2`. Issue 256's
+lost-ancestor descendant-closure boundary remains open. The same guidance still
+covers the v0.7.89 Issue 293
+topology-transparent conversation projection, FEATURE_293 zero-service web
+search fallback, and FEATURE_294 run-scoped Host Tools. The host-tool surface is
+leased to one Run, registry-first, revocation-safe, and absent from unrelated
+CLI runs. Its custom web-search endpoint remains isolated. The v0.7.88 SDK
+guidance adds the GLM-5.3 Coding Plan
+routes with verbatim model IDs, keeps GLM-5.2 selectable, defaults
+`zhipu-coding`, `zai-coding`, and `ark-coding` to 5.3, and documents the GLM-5.3
+always-thinking effort mapping. It also covers atomic Runtime owner
+recovery, process-start identity locks, Windows sandbox termination attestation,
+durable ACL owner markers, and Windows workspace Shell PATH/executable scoping
+with quoted `cmd.exe` argument preservation. POSIX workspace sessions initialize
+fresh-home policy roots, settle workspace-local warm-up within the Shell
+abort/deadline, retire invalid sessions after lease-cleanup failure, and fail closed when process-tree cleanup is unconfirmed,
+in addition to the v0.7.85 Session-scoped
+Runtime Event Journals, the `sessionEventJournal:1` daemon contract,
+conversation-first Memory management, the additive experimental Memory
+management facade, and the startup/Worker lifecycle boundaries. Issue 256's
+remaining Worker owner-lease boundary remains open after v0.7.89; this release
+assigns no replacement target.
+
+The current source additionally documents structured, credential-safe Runtime
+`failureDetail`. Stable KodaX classification stays separate from optional
+bounded upstream identifiers, and failure/settlement events, Run result/status,
+and Session diagnostics project the same fact when it exists. This additive
+contract ships in `v0.7.96-alpha.2`; consumers of older published packages must
+tolerate an absent field.
+
+The v0.7.90 SDK guidance also documents orderly retirement for timed-out
+workspace sessions, actionable daemon Error/aggregate/cause diagnostics, direct
+clone-predecessor lineage and topology-correct archive markers, and provider-
+valid object schemas for run-scoped tools. npm publication remains a manual
+operator step.
+
+The v0.7.91 SDK guidance adds the crash-resumable
+`settleKodaXRuntimeExit()` transaction and `runtimeExitSettlement:1` capability,
+effective live output segments (`responseId` + `providerRequestId`), and
+standalone lazy provider dependency bundling. It also documents bounded
+AskUser/permission deadlines, owner AbortSignal propagation,
+`handleRuntimePermissionRequest()`, validated default answers, and stale
+prepared-Session-tail recovery after a `data_changed` race.
+
+The v0.7.94 SDK guidance documents concurrent sandboxed text mutations,
+authorized-root git trust (`gitSafeDirectory: authorized-repo-roots`),
+byte-bounded linked-worktree and submodule relationship reads, observed
+text-helper stdin failures, scheduled shutdown failure reporting, omitting
+the text sandbox when the workspace directory does not exist,
+`conversationHistory:2`, independent explicit Skill invocation, diagnosed
+invalid `allowed-tools` / malformed hook JSON, `PostToolUse` after an
+embedder observer throw, fail-closed Run terminal settlement, observed
+sandbox/managed-child cleanup rejection, typed daemon disconnect facts,
+bounded credential-safe `failureKind`, and exact-`runId` result recovery. An
+admitted Run is queried and awaited after reconnect; it is never started
+again. `sandboxRuntime:4` and `crashOutcomeModel:2` are unchanged.
+
+The v0.7.93 SDK guidance documents that a durable Windows `failed` shutdown
+outcome ends the orderly exit wait, previous-boot shared ACL markers may be
+recovered after a verified boot change, and Anthropic/OpenAI abort wrappers
+are classified by isolated SDK class identity. Capability versions are
+unchanged.
+
+The v0.7.92 SDK guidance adds `sandboxRuntime:4` and `crashOutcomeModel:2` as
+pre-start facts. Auto-start replaces an idle older daemon and fails closed
+while it is busy. Managed `onComplete` is not terminal authority. Hosts must
+not delete ProgramData lock files to recover a stuck coordinator. Resume
+reconstruction uses canonical Session `messages` as the transcript; `uiHistory`
+may overlay tool cards and display-only entries but cannot hide ordinary
+conversation. Presentation-only `agent-completed` / `task-completed` events
+stay host-owned when a non-empty CLI `uiHistory` exists.
+
+## Getting Started
+
+- [Overview](./getting-started/overview.md) — What KodaX is and how it compares
+- [Installation](./getting-started/installation.md) — npm, single binary, build from source
+- [Quickstart](./getting-started/quickstart.md) — Your first session
+
+## Configuration
+
+- [Providers & API Keys](./configuration/providers.md) — 16 built-in provider aliases
+- [Custom Providers](./configuration/custom-providers.md) — OpenAI/Anthropic-compatible endpoints
+- [Configuration Files](./configuration/config-files.md) — config.json, split files, env vars
+- [Permission Modes](./configuration/permissions.md) — Plan / Edits / Auto + Shell Execution Contract
+- [Sandbox](./configuration/sandbox.md) — Optional OS-level containment (ASRT)
+
+## SDK
+
+- [Embedder Guide](./sdk/embedder-guide.md) — Full SDK integration guide for
+  host applications, including
+  [structured credential-safe Runtime failures](./sdk/embedder-guide.md#structured-credential-safe-runtime-failures),
+  explicit-vs-model Skill invocation, and dynamic-context policy
+
+## Guides
+
+*(More standalone guides coming soon: CLI reference, REPL commands, sessions, multi-agent, skills, extensions, MCP, A2A, repo intelligence, memory, workflows, compaction, doctor, tools reference. Current Skill SDK semantics are documented in the Embedder Guide.)*
+
+## Reference
+
+*(Coming soon: troubleshooting, FAQ, comparison, license.)*

package/public_docs/configuration/sandbox.md

@@ -0,0 +1,289 @@
+# Sandbox
+
+KodaX supports an optional OS-level sandbox for model-issued shell commands.
+On Windows, ASRT owns network/account setup while the KodaX native runner owns
+the restricted token and process Job; macOS and Linux use ASRT's platform
+backends directly.
+
+## Activate the sandbox
+
+```bash
+kodax sandbox doctor    # Check readiness
+kodax sandbox setup     # Activate
+```
+
+`kodax setup` and first-run setup also check sandbox readiness once.
+
+Trusted text tools have a separate native diagnostic because they do not use
+the shell sandbox. Run `kodax doctor --native-text` to explicitly load and
+verify the packaged trusted-text addon. This check does not require
+`kodax sandbox setup` and does not change shell sandbox state.
+
+## Platform backends
+
+| Platform | Backend | Dependencies |
+|---|---|---|
+| **Windows** | Restricted sandbox account + network policy | None (UAC during activation; an upgrade SID rotation may require a second confirmation) |
+| **macOS** | Seatbelt (`sandbox-exec`) | ripgrep (`brew install ripgrep`) |
+| **Linux** | bubblewrap | `bubblewrap`, `socat`, `ripgrep` |
+
+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.
+
+On Linux, the kernel and host security policy must also permit unprivileged
+user namespaces. Some hardened distributions disable them even when
+`bubblewrap` is installed. KodaX does not change sysctls or AppArmor policy;
+if the broker proves the wrapper could not spawn the target, the standalone SDK reports
+`reason: 'backend_launch_failed'` with a bounded diagnostic instead of claiming
+that the command completed inside the sandbox. A spawned wrapper that exits
+without target-start authority, or any missing or invalid broker-only control
+frame, returns `execution_uncertain`; the command may have started and must not
+be retried blindly.
+
+## REPL diagnostics
+
+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.
+
+## Environment variable passthrough
+
+Credential-shaped environment variables are filtered from model-issued shell
+commands by default. To expose specific host variables to those command targets:
+
+```json
+{
+  "sandbox": {
+    "envPass": ["GH_TOKEN", "GITHUB_TOKEN", "OPENAI_API_KEY"]
+  }
+}
+```
+
+The default list is empty. Values remain in the host environment and are never
+stored in `config.json`; project configuration cannot extend the list. Matching
+is exact (case-insensitive on Windows), and execution-control variables such as
+`NODE_OPTION` and `BASH_ENV` remain blocked.
+
+Restart KodaX after changing the host variables or this setting; stop/restart a
+persistent KodaX daemon so it receives the new environment and configuration.
+
+## Historical Windows workspace Shell behavior (v0.7.86-v0.7.95)
+
+Windows workspace Shell calls preserve the case-insensitive `PATH`/`Path` and
+`PATHEXT` environment contract across the Runtime and sandbox brokers. KodaX
+derives read grants from the final resolved PATH and shell executable, including
+the bounded traversal needed by profile-manager junctions, rather than granting
+the whole user application tree. `cmd.exe` command arguments retain their
+verbatim-argument contract, so quoted paths and profile-managed executables are
+not re-parsed by an intermediate broker.
+
+The packaged Electron and Runtime smoke paths exercise this behavior. A missing
+or unprovable sandbox lifecycle attestation after target start remains
+fail-closed; KodaX does not retry a command that may already have started.
+Commands with the same canonical workspace, Agent Home, additional filesystem,
+toolchain, and network policy can share one Windows policy group across KodaX
+processes. An incompatible policy or sandbox infrastructure failure before
+target start returns the already-authorized command to normal permission
+execution. Runtime sandbox capability v3 first fenced older daemon policy
+revisions in v0.7.86. The v0.7.95 contract was `sandboxRuntime:5`: auto-start
+replaces an idle v4-or-older Windows daemon and fails closed while it is busy.
+The v5 advance marks self-healing Windows cleanup
+(`delayedEffectDrainRecovery: 'automatic'`,
+`sameBootAclRecovery: 'sandbox-user-process-probe'`): the machine-global
+cleanup Job is recoverable across reboots, recovery tickets repair without
+operator input, and background retries observe the exact daemon and supervisor
+process generations. Do not
+delete `model-filesystem-effects.lock` by hand; on Windows the coordinator
+state lives under `C:\ProgramData\KodaX\sandbox-runtime\runtime\`.
+
+## Trusted text tools (v0.7.96)
+
+On Windows, Linux, and macOS, Runtime `write`, `edit`, `multi_edit`,
+`insert_after_anchor`, and `undo` are trusted KodaX host operations. They do not enter ASRT, a
+workspace session, the native shell runner, or a sandbox helper. The host
+authorizes the final canonical local path and uses a short cross-Runtime
+per-file kernel lock, locked reread, revision/content CAS, a flushed
+same-directory temporary file, and atomic replacement. Symlink/reparse and
+multi-link targets, remote filesystems, and sensitive KodaX/Git control
+locations fail closed; Windows additionally rejects UNC/device/ADS and other
+alias namespaces. These tools are host-policy
+constrained; they are not advertised as OS-token-sandboxed writes.
+
+Atomic replacement is the commit point. If a Unix parent-directory flush or
+escape rollback cannot be proven after that point, the tool returns
+`text_mutation_commit_uncertain` with the complete pre/post receipt and tells
+the caller to reread; do not retry the same edit blindly. Existing-file edits
+retain their Undo backup. An uncertain Undo rebinds that backup to the observed
+post-commit revision for a later CAS-checked resolution. A newly created file
+still reports `before.state: missing` in the error receipt, but this does not
+create a legacy Undo entry that deletes the file. Linux ZFS and casefold directories
+are currently rejected because their namespace case/normalization semantics are
+not yet proven by the native descriptor path.
+
+Arbitrary shell programs do not participate in the text-tool lock. If the
+locked final reread observes a shell change, the text operation returns a
+structured stale conflict and does not overwrite the newer bytes; an
+incompatible writer handle at that reread returns contention. On Windows a
+delete/write reservation excludes a new writer between final CAS and the
+POSIX-semantics atomic replace while compatible readers keep complete old/new
+handles. On Unix, an uncooperative write, replace, or rename after final reread
+remains an ordinary operating-system race.
+Different canonical files do not share a transaction lock.
+
+On Windows the kernel lock lives in a private namespace bound to the trusted
+host user, so the restricted shell account cannot precreate its name. On Unix,
+a fixed per-UID system coordination root is host-owned with mode `0700` and is
+shared across Runtime config homes; its per-resource inode carries kernel
+`flock`. The native binding is stored separately below
+`KODAX_HOME/native-text-state-v1` and loaded through a no-follow descriptor
+whose digest matches its content-addressed directory. Sandboxed shell policy
+cannot read or write either root, and symlinked Agent Home state fails closed. File presence
+does not mean the lock is held. Process death releases either lock
+automatically and no PID/ticket recovery protocol is required. Unix atomic
+replacement preserves ownership, mode, extended attributes, Linux
+user-modifiable inode flags, and macOS extended ACL/file flags or fails closed.
+On Windows, replacing a file left by an older sandbox identity makes the new
+file trusted-host-owned while retaining its ordered effective ACE policy. The
+filesystem may canonicalize DACL protection/inheritance control at the atomic
+namespace commit; stale inherited authority is not copied from a former parent.
+A low-integrity sandbox label normalizes to ordinary
+host integrity instead of being reapplied. Thus an obsolete sandbox owner cannot permanently
+block Write/Edit and does not require manual ACL repair.
+
+## Background commands and session reuse (v0.7.96)
+
+Windows v2 shell commands use a separate native host/runner protocol. ASRT
+supplies the network proxy, WFP/CA integration, and the dedicated account;
+KodaX supplies a restricted policy token, framed stdin/stdout/stderr, and a
+no-breakaway, kill-on-close Job. The target is created suspended and assigned
+to that Job before it may run, and a nonce-bound private desktop whose access
+requires the exact policy capability avoids both
+the known null-desktop loader failure and exposure to the interactive desktop. No filesystem-effect fence, workspace-session
+owner, reset, cleanup, or poison gate spans the command lifetime, so shell
+commands from different policies, Sessions, and Runtime processes may overlap.
+A long-running shell therefore cannot make a trusted text tool unavailable.
+Workspace-local `.kodax/runtime` state is excluded from shell read and write
+authority even though the surrounding workspace is writable; Session journals,
+cursor files, daemon records, and grants remain host-owned control state.
+The private desktop uses an ephemeral full-policy capability. Filesystem write
+authority instead uses stable capabilities derived from the sandbox-account
+generation, final canonical root, and `allowRead`/`allowWrite`/`denyWrite`
+clause. Every read root has an exact allow-read capability and a read-only root
+implicitly carries its deny-write capability. The dedicated account,
+per-launch logon, and Everyone SIDs remain in the restricting set because real
+subprocess creation requires them, matching current Codex; Issue 309 documents
+the remaining ambient-trustee child-DACL boundary. The shared sandbox group
+supplies the normal access-check pass. The target's enabled Windows traverse
+privilege reaches an exact allowed root without persistent ACEs on its private
+ancestors; KodaX never rewrites a profile/container DACL merely to make a child
+root reachable. Every target is preflighted before one atomic ACL transaction. Windows
+`WRITE_RESTRICTED` does not enforce restricting SIDs for reads, so `denyRead`
+uses an execution-logon deny under a short ACL mutex. A durable receipt records
+the no-follow volume/file identity before mutation; exact cleanup follows Job
+drain. A later shell host recovers a crashed owner only when PID creation time
+and target identity prove the receipt stale. A missing or replaced target keeps
+the receipt and blocks shell admission until repair, but cannot block trusted
+text tools.
+Within one Runtime, commands whose canonical network policy and sandbox-account
+generation match share one process-level ASRT network broker; their native
+requests, restricted policy tokens, controller connections, and Jobs remain
+independent. Different network policies never share that authority. ASRT
+0.0.65 still consumes two fixed-range ports for each distinct broker and has no
+authenticated connection identity for routing unlike policies through one
+ingress. Issue 308 tracks this capacity difference from Codex; KodaX does not
+widen a policy or serialize shell lifetimes to conceal it.
+The broker also owns a verified native liveness controller. Its named pipe is
+created with a protected Host/SYSTEM-only DACL, rejects remote clients, and
+keeps multiple pending instances for concurrent host launches. Restricted
+targets cannot connect to or exhaust this control path. Broker/controller loss
+closes every controller handle, drains active Jobs, and lets a later command
+create a fresh broker.
+This authority split is advertised as `sandboxRuntime:6`; auto-started clients
+replace an idle older daemon and fail closed instead of joining a busy one.
+Upgrading an existing Windows installation requires one `kodax sandbox setup`
+cutover. Setup waits for old sandbox processes to exit, recovers recorded ACL
+work, recreates the dedicated account with a new SID, and records that SID and
+the native protocol in machine state. Doctor and native shell admission remain
+fail-closed if that state is missing or mismatched; trusted text tools remain
+available throughout. The embedded release manifest pins each native sidecar
+protocol/SHA-256 plus the ASRT release version/SHA-256. Verified bytes are
+staged in a protected content-addressed LocalAppData store independent of
+`KODAX_HOME`; ASRT is checked before materialization and again before broker
+startup. Windows text bytes remain Host/SYSTEM-only; the dedicated sandbox
+group SID receives read/execute, but not write/delete, on the shell artifact;
+and local Users receive only read/execute on the pinned ASRT executable. Fixed
+Agent Home and credential read denies are installed once on exact roots through
+native no-follow handles; cold admission idempotently guards an exact sensitive
+directory created after setup. They are not rebuilt for each shell command. The
+ASRT directory is not passed as a final-target policy root. A fixed System32
+provisioner may run during this artifact bootstrap; text content and shell
+stdin never enter it.
+
+In a bundled build, the package-source ASRT executable may be a package-store
+hardlink. KodaX does not trust that link relationship: it performs a
+handle-bound bounded read and requires the complete bytes to match the embedded
+release SHA-256 before copying them into the protected cache. Filesystem
+development manifests and sources remain single-link. The executable used by
+the broker still has one link and must pass the protected ACL and digest checks.
+This prevents a valid installation layout from being mistaken for sandbox failure.
+
+If a prior host died before a native request was consumed, explicit setup can
+self-heal the protected control directory after proving the sandbox SID idle.
+It retires only an expired request whose creator PID is dead, an aged
+unconsumed network request from a dead PID, or a dead-owner terminal record
+that already says `jobDrained: true`. Doctor never performs this cleanup.
+Live, unexpired, malformed, unknown, and `windows-deny` recovery records remain
+fail-closed instead of being treated as disposable files.
+
+The final target is in its Job at process creation. ASRT still creates the
+shared-account runner before KodaX code can apply runner-process hardening;
+Issue 307 tracks that narrow upstream pre-main window, which current Codex also
+retains. The KodaX host requests inherited error-mode suppression before ASRT
+launch and runner code repeats it after entry, but the ASRT-owned cross-account
+creation contract still controls loader faults before runner `main`; final target
+faults are suppressed. It does not affect trusted text tools. Closing it requires an ASRT
+creation-time process/thread security contract or privileged spawn service,
+not another post-spawn patch.
+
+Issue 309 documents the remaining Windows compatibility limitation: an explicit
+ACE for a retained compatibility trustee can bypass a later root capability.
+The ACE may be left by a sandbox command or already exist on an external or
+host-owned descendant. KodaX requires exact read/write capabilities for normal
+declared roots, but the primary account, logon, and Everyone SIDs must remain
+for working subprocesses; closing explicit child-DACL reuse needs a different
+loader/token architecture.
+
+Linux and macOS shell calls remain ASRT-contained per command through
+bubblewrap or Seatbelt/`sandbox-exec`. They do not keep a KodaX workspace-
+session owner, reset/poison state, or filesystem-effect lease across the shell
+lifetime. On every platform, an arbitrary shell writer is an ordinary OS race
+and does not join trusted-text CAS.
+
+## SDK sandbox
+
+SDK callers pass the same shape per Run as `KodaXOptions.sandbox`, so concurrent
+Runs can use different lists without mutating process-global configuration.
+
+```ts
+await runKodaX({
+  provider: 'openai',
+  sandbox: { envPass: ['GH_TOKEN'] },
+}, 'Inspect the authenticated repository.');
+```
+
+SDK embedders can also use the standalone shell sandbox capability
+independently through `@kodax-ai/kodax/sandbox`. Its readiness and setup state
+apply to shell/process containment only. A failed or unavailable shell runner
+does not change the trusted text-tool path. An unavailable result may include
+`reason: 'doctor_not_ready' | 'backend_launch_failed'`; the latter also includes
+a bounded `diagnostic` and is never reported as a sandboxed completion. A
+separate `execution_uncertain` result means target-start authority could not be
+recovered and callers must reread external state before deciding what to do.
+
+## See also
+
+- [Permissions](./permissions.md) — Permission modes and Auto Mode
+- [Configuration files](./config-files.md) — Config.json reference
+- [SDK overview](../sdk/overview.md) — SDK sandbox subpath