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

package/README.md

@@ -61,7 +61,8 @@ KodaX opens the provider/model metadata setup. 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
+Windows requests UAC during activation (an existing v2 account rotation may
+require a second confirmation); 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.
@@ -206,11 +207,13 @@ kodax sandbox setup
 ```
 
 - Windows uses a restricted sandbox account and network policy. A normal
-  terminal is sufficient; approve the one-time UAC prompt.
+  terminal is sufficient; approve the activation UAC confirmation(s).
 - 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`).
+  (install them with your distro's `apt`, `dnf`, or `pacman`). The host kernel
+  and security policy must also permit unprivileged user namespaces; KodaX
+  reports a failed backend launch and does not change system policy itself.
 
 KodaX never runs `sudo` or a package manager automatically. If the sandbox is
 not active, deterministic safe operations and Auto[LLM] decisions keep the
@@ -341,34 +344,28 @@ Sidecar verifier judge calls use provider-level forced tool choice when supporte
 
 #### Opting a custom provider into image / vision input (FEATURE_134 v0.7.40)
 
-If your custom provider's underlying model supports image input (vision), add a `capabilityProfile.multimodalSupport: "image-input"` block so KodaX does not artificially block multimodal requests at the SA-path policy gate. Built-in vision-capable aliases (Anthropic, OpenAI, compatible aliases such as Kimi, Qwen, Zhipu, MiniMax, MiMo, Ark, plus Gemini-CLI via the CLI's `@<path>` file-include syntax) already ship with this flag enabled by default. DeepSeek V4 and Codex-CLI are text-only; custom providers need to opt in when their underlying model supports image input.
+If your custom provider's underlying model supports image input (vision), set `"imageInput": true` so KodaX's image routing and the provider-policy gate both let image artifacts through. This is the typical shape for self-hosted multimodal models served by vLLM or SGLang behind an OpenAI-compatible endpoint (Qwen-VL-style models):
 
 ```json
 {
   "customProviders": [
     {
-      "name": "my-vision-provider",
+      "name": "my-vllm",
       "protocol": "openai",
-      "baseUrl": "https://example.com/v1",
-      "apiKeyEnv": "MY_LLM_API_KEY",
-      "model": "my-vision-model",
-      "capabilityProfile": {
-        "transport": "native-api",
-        "conversationSemantics": "full-history",
-        "mcpSupport": "none",
-        "contextFidelity": "full",
-        "toolCallingFidelity": "full",
-        "sessionSupport": "full",
-        "longRunningSupport": "full",
-        "multimodalSupport": "image-input",
-        "evidenceSupport": "full"
-      }
+      "baseUrl": "http://localhost:8000/v1",
+      "apiKeyEnv": "MY_VLLM_API_KEY",
+      "model": "Qwen/Qwen3.8-27B-Instruct",
+      "imageInput": true
     }
   ]
 }
 ```
 
-The serializer layer (`packages/llm/src/providers/anthropic.ts:770` for Anthropic-compat, `openai.ts:904` for OpenAI-compat) forwards image blocks automatically through base-class inheritance. The flag only gates whether KodaX's policy layer pre-rejects multimodal requests — the model-level vision contract remains your upstream provider's responsibility. If the model is actually text-only, you'll see the real upstream API error instead of a KodaX-side rejection.
+`imageInput: true` forces `capabilityProfile.multimodalSupport: "image-input"` on every KodaX surface (provider instance, capability queries, policy gates), overriding an explicit `"none"`. The advanced alternative — a hand-written `capabilityProfile` block with `"multimodalSupport": "image-input"` — works too; see [Custom Providers](public_docs/configuration/custom-providers.md). Leave it unset for text-only models and image artifacts are rejected with `MODEL_INPUT_UNSUPPORTED` before the request is sent.
+
+Built-in vision-capable aliases (Anthropic, OpenAI, compatible aliases such as Kimi, Qwen, Zhipu, MiniMax, MiMo, Ark, plus Gemini-CLI via the CLI's `@<path>` file-include syntax) already ship with image input enabled. DeepSeek V4's default models (`deepseek-v4-flash` / `deepseek-v4-pro`) and Codex-CLI are text-only — on the built-in `deepseek` alias only `deepseek-v4-flash-vision-exp` takes images; custom providers need to opt in when their underlying model supports image input.
+
+The serializer layer (`packages/llm/src/providers/anthropic.ts:1431` for Anthropic-compat, `openai.ts:1496` for OpenAI-compat) forwards image blocks automatically through base-class inheritance — OpenAI-compatible endpoints receive standard `image_url` blocks. The flag only gates whether KodaX's policy layer pre-rejects multimodal requests — the model-level vision contract remains your upstream provider's responsibility. If the model is actually text-only, you'll see the real upstream API error instead of a KodaX-side rejection.
 
 ### 3. Start in REPL or run a one-shot task
 
@@ -436,6 +433,37 @@ const isolated = await createKodaXRuntime({
 });
 ```
 
+### Structured Runtime failures
+
+Since v0.7.96, when Runtime has a structured failure fact, failed/cancelled runs
+and unknown settlement states project the same credential-safe `failureDetail`
+through failure or settlement events, `handle.result` / `runs.await()`,
+`runs.get()` / `runs.list()`, and `sessions.diagnostics()`. Branch on the stable
+KodaX `providerErrorCode`; use `safeMessage` for display, and treat
+`upstreamErrorCode`, `requestId`, `httpStatus`, and `retryAfterMs` as optional
+support metadata.
+
+```ts
+const session = await isolated.sessions.create({ title: 'Repository summary' });
+const handle = await isolated.runs.start({
+  sessionId: session.id,
+  input: { type: 'text', text: 'Summarize this repo.' },
+});
+const result = await handle.result;
+
+if (result.failureDetail) {
+  const { providerErrorCode, safeMessage, requestId } = result.failureDetail;
+  showFailure(safeMessage, { providerErrorCode, requestId });
+}
+```
+
+`safeMessage` is a bounded KodaX-owned template, not copied upstream text. The
+Runtime never copies credentials, prompts, request/response bodies, raw header
+collections, URLs, full local paths, stacks, or raw `Error` objects into
+`failureDetail`; only the documented allowlisted metadata may be extracted.
+See [Structured Runtime failures](public_docs/sdk/embedder-guide.md#structured-credential-safe-runtime-failures)
+for the field contract, taxonomy, migration guidance, and security boundary.
+
 Inline is private and lowest-overhead; Worker is private and hard-disposable;
 daemon is process-isolated and shared. `runtime.close()` closes private
 inline/Worker ownership, but only detaches one daemon client. Contradictory
@@ -484,7 +512,8 @@ bootstrap-only child exec boundary and removed before daemon or ordinary user
 child code loads. The default-enabled Electron `RunAsNode` fuse is required;
 hosts that disable it must start the daemon through ordinary Node/KodaX CLI and
 connect in attach-only mode. For SDK calls, `homeDir` is the CLI-style base
-directory that owns `.kodax`, not the `.kodax` path itself.
+directory that owns `.kodax`, not the `.kodax` path itself. Electron embedders
+must also follow the [native artifact unpacking contract](public_docs/sdk/embedder-guide.md#packaged-electron-native-artifact-layout).
 
 **v0.7.75 Windows GUI stabilization candidate:** Runtime Worker-reachable
 non-interactive subprocesses request hidden Windows consoles across memory/Git,
@@ -726,6 +755,102 @@ permission UI, and recovers stale prepared Session tails through an
 authoritative merge. Background persistence failures are surfaced as
 diagnostics rather than hidden.
 
+**v0.7.96-alpha.2 release (Windows hotfix):** restored the Windows
+boot-identity PowerShell resolution helper that the FEATURE_295 cleanup
+deleted while its last caller stayed. On v0.7.96-alpha.1 every Windows exit
+settlement crashed with `windowsAclPowerShellExecutable is not defined` and
+left sandbox cleanup `unverified`; the restored helper plus a win32 regression
+test close Issue 325. v0.7.96-alpha.1 is broken on Windows — upgrade to
+v0.7.96-alpha.2. See the
+[v0.7.96-alpha.2 release checklist](docs/release.md#v0796-alpha2-release-preparation).
+
+**v0.7.96-alpha.1 release:** controlled
+text tools and shell containment are separate authorities on every desktop
+platform. `write`, `edit`, `multi_edit`,
+`insert_after_anchor`, and `undo` run in the trusted KodaX Runtime with final
+path/identity policy checks, a cross-Runtime per-file kernel lock, revision
+CAS, metadata-preserving flushed atomic replacement, and a protected native
+state root. They do not enter ASRT, a workspace
+session, shell runner, setup, cleanup, owner, reset, or poison state, and are
+not described as OS-token-sandboxed. The root and `/coding` direct SDK entries
+(`runKodaX`, `startKodaX`, `runManagedTask`, `createKodaXTaskRunner`, `createDefaultCodingAgent`,
+`KodaXClient`, and its `Client` alias) bind the same native text
+authority by default and read newly registered linked-worktree roots at
+transaction time. Windows shell commands keep ASRT only for network/account
+services and use the KodaX native restricted-token runner with
+a nonce-bound per-policy private desktop, creation-time Job containment, and framed stdio. Native shell commands from
+different policies, Sessions, and Runtime processes do not share a
+command-lifetime filesystem-effect lease. Commands in one Runtime with the
+same network policy and sandbox-account generation share one ASRT network
+broker while retaining independent policy tokens and Jobs. Unlike policies do
+not share authority; Issue 308 tracks ASRT 0.0.65's remaining fixed-port
+capacity limit across distinct policies and Runtime processes. Arbitrary shell writes remain normal
+OS races; only controlled text tools participate in KodaX CAS. Target stdin EOF
+does not close the native control stream. Authenticated directional pipes keep
+control and events independent; timeout/cancel validates a nonce-bound runner
+Job-drain record before returning the original stop reason.
+Windows trusted replacement automatically converts an obsolete sandbox-owned
+file to trusted-host ownership and preserves the ordered effective ACE policy.
+The filesystem may canonicalize DACL protection/inheritance control at the
+atomic namespace commit; stale inherited authority is not copied from an old
+parent. The
+shell cannot read or write workspace-local `.kodax/runtime` control state even
+when the surrounding workspace is writable.
+Each shared broker owns a verified native liveness controller whose named pipe
+is created with a protected Host/SYSTEM-only DACL and multiple pending
+instances. Restricted targets cannot connect or exhaust it; controller or
+broker loss closes the channel and drains every attached command Job.
+Native request/terminal state is kept in a no-reparse, host/SYSTEM-only control
+directory; both SDK policy validation and the native host reject overlapping
+allow roots and deny roots at/below it before target launch. Doctor only
+verifies. After proving the sandbox account idle, explicit setup can retire an
+expired dead-PID request or a dead-owner terminal record that already proves
+Job drainage before repairing host-owned state. Live, unexpired, malformed,
+unknown, and deny-recovery records remain fail-closed.
+If Unix cannot prove directory durability after the atomic commit, the tool
+returns `text_mutation_commit_uncertain` with the complete pre/post receipt and
+requires a reread instead of a blind retry. Existing-file edits retain their
+Undo backup; a commit-uncertain Undo is rebound to the observed post-commit
+revision so a later CAS-checked Undo can resolve it. See
+[ADR-066](docs/ADR.md#adr-066-trusted-text-transactions-and-a-native-windows-shell-sandbox-are-separate-authorities).
+This incompatible authority split is fenced by `sandboxRuntime:6`, so a new
+client never silently reuses a daemon that still implements the v0.7.95 graph.
+Existing Windows installations run `kodax sandbox setup` once: the cutover
+waits for old sandbox processes to exit, recreates the dedicated account with
+a new SID, and records the native protocol/SID generation. Missing migration
+state blocks native shell admission, not trusted text tools.
+On Windows, the embedded release manifest pins text/shell protocols and hashes
+plus the ASRT release version and hash. Verified executables are staged in a
+content-addressed protected LocalAppData store independent of `KODAX_HOME`;
+ASRT is checked before materialization and again before broker startup. Text
+remains Host/SYSTEM-only, the dedicated sandbox group SID receives read/execute
+on the shell artifact, and local Users receive read/execute on ASRT; neither
+sandbox trustee nor local Users receives write/delete authority.
+A package-store hardlink is accepted only in bundled builds, through a
+handle-bound bounded read whose complete bytes match the embedded release
+digest; development manifests and sources remain single-link. The executable
+used by the broker is still a separate, protected single-link file. Allow-root
+authorization changes only exact canonical roots and never rewrites their
+private ancestor DACLs.
+Linux and macOS use the same trusted-text authority with native no-follow/
+`flock`/CAS/atomic commit, while shell commands remain per-command ASRT
+bubblewrap/Seatbelt invocations with no KodaX workspace-session owner.
+Issue 307 tracks the narrower ASRT-owned runner pre-main creation window that
+also remains in current Codex; final command targets are still placed in their
+Job at process creation, and trusted text tools never enter that boundary.
+Issue 309 records the other Codex-compatible Windows residual: stable root
+capabilities do not override an explicit ambient loader-compatibility ACE,
+whether left by an earlier sandbox command or already present on an external or
+host-owned descendant. This release also replaces the local tool-result
+capacity hard gate with capacity-debt admission and a bounded recovery
+ladder (ADR-067), classifies local capacity terminals as
+`failureKind: "context_capacity"` with structured `contextTokens`, and
+exposes one credential-safe `failureDetail` across failure events, Run
+result/status, and Session diagnostics. It advertises Windows
+`sandboxRuntime:6`; `runtimeExitSettlement:2` and `crashOutcomeModel:2` are
+unchanged. See the
+[v0.7.96-alpha.1 release checklist](docs/release.md#v0796-alpha1-release-preparation).
+
 **v0.7.95 release:** stale learning locks with zero-byte,
 malformed, or truncated owner records self-recover after an unchanged
 bytes/stat check. Same-boot Windows `unconfirmed-owner` cleanup retries until
@@ -943,7 +1068,7 @@ KodaX/
 │   ├── 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,sandbox,a2a,experimental-memory}
 │
-└── package.json             # Publish-shaped exports; release.mjs only toggles private during pack/publish
+└── package.json             # Publish-shaped exports; publish ships the CI-built tarball (release.mjs), local --pack-only keeps private:true
 ```
 
 ### Package Dependencies
@@ -1147,7 +1272,7 @@ changes require an explicit server restart. Managed
 A2A contexts default to `~/kodax_a2a_server_workspace/<runtime-profile>/contexts/`.
 Exact Skill scripts require the opt-in isolated policy and a passing
 `kodax sandbox doctor` (`kodax sandbox setup` performs the explicit Windows
-one-time provisioning).
+provisioning or v2 account-SID cutover).
 
 ---
 
@@ -1796,7 +1921,7 @@ await runInkInteractiveMode({ provider: 'zhipu-coding', effort: 'auto' });
 | mimo | `MIMO_API_KEY` | Native | mimo-v2.5-pro (Xiaomi MiMo pay-per-token, Anthropic-compat) |
 | 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.3 (Volcengine Ark Coding Plan — GLM-5.3 (1M ctx, 128K out) · 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`) |
+| deepseek | `DEEPSEEK_API_KEY` | Native | deepseek-v4-flash (`deepseek-v4-pro` plus vision model `deepseek-v4-flash-vision-exp` with image input, via `/model`) |
 | 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) |
 

package/README_CN.md

@@ -58,7 +58,8 @@ kodax
 provider/model 元数据设置。使用 `kodax setup` 重新运行设置，
 使用 `kodax setup --custom` 配置自定义 provider；使用 `kodax setup --help` 或
 REPL `/setup --help` 查看完整路径、环境变量、命令和快捷键。交互式 setup 还会检查
-一次可选 ASRT sandbox：Windows 可能弹出一次 UAC；
+一次可选 ASRT sandbox：Windows 激活时会请求 UAC（已有安装进行 v2 账户 SID
+轮换时可能需要第二次确认）；
 macOS/Linux 会报告 Seatbelt/bubblewrap 所需依赖。拒绝 UAC 或缺少依赖不会破坏普通
 权限管理，日常启动也不会反复提醒。
 
@@ -92,12 +93,39 @@ data/session root 下的 inline Runtime，不参与 Coder owner fence。capabili
 fail closed，不能静默退回 inline Coder。完整接入说明见
 [SDK Embedder Guide §23](public_docs/sdk/embedder-guide.md#23-shared-coder-daemon-for-space-and-ide-hosts-feature_269-v0769)。
 
+### 结构化且凭据安全的 Runtime 错误
+
+自 v0.7.96 起，当 Runtime 已生成结构化失败事实时，失败和取消 Run
+会在终端事件、
+`handle.result` / `runs.await()`、
+`runs.get()` / `runs.list()` 以及 `sessions.diagnostics()` 中提供一致的
+`failureDetail`；Runtime 收尾失败形成 `unknown` 状态时通过 `run.updated` 透出。
+上述字段是可选的，只在 Runtime 已生成结构化失败事实时出现。宿主应按稳定的
+KodaX `providerErrorCode` 处理错误，向用户展示
+`safeMessage`；`upstreamErrorCode`、`requestId`、`httpStatus` 和
+`retryAfterMs` 仅作为可能缺失的支持信息。
+
+```ts
+const result = await handle.result;
+if (result.failureDetail) {
+  const { providerErrorCode, safeMessage, requestId } = result.failureDetail;
+  showFailure(safeMessage, { providerErrorCode, requestId });
+}
+```
+
+`safeMessage` 是长度受限的 KodaX 固定文案，不复制上游错误正文；Runtime 不会把
+凭据、prompt、请求/响应正文、原始 headers 集合、URL、完整本地路径、stack 或原始
+`Error` 复制进 `failureDetail`，仅提取文档明确列出的 allowlist 元数据。字段定义、
+分类表、迁移方法和安全边界详见
+[Structured Runtime failures](public_docs/sdk/embedder-guide.md#structured-credential-safe-runtime-failures)。
+
 **v0.7.71 Electron 打包修复**：packaged/asar Electron 宿主可以直接自动启动
 daemon，不会再次打开 GUI。`ELECTRON_RUN_AS_NODE` 只存在于子进程启动边界，
 在 daemon 与普通用户子进程代码加载前即被移除。该路径要求 Electron 默认开启的
 `RunAsNode` fuse；主动关闭该 fuse 的宿主必须通过普通 Node/KodaX CLI 启动 daemon，
 再使用 attach-only 模式连接。SDK 的 `homeDir` 是拥有 `.kodax` 的 CLI 风格基础目录，
-不是 `.kodax` 目录本身。
+不是 `.kodax` 目录本身。Electron 宿主还必须遵循
+[native artifact 解包契约](public_docs/sdk/embedder-guide.md#packaged-electron-native-artifact-layout)。
 
 **v0.7.75 Windows GUI 稳定性候选版**：Runtime Worker 可达的非交互后台子进程
 在 Windows 上统一请求隐藏控制台，覆盖 memory/Git、provider CLI/ACP、LSP、
@@ -266,6 +294,76 @@ SDK 系统代码契约更新，但没有放宽 shell/sandbox 的 fail-closed 边
 `handleRuntimePermissionRequest()` 管理 SDK 权限 UI，并在 prepared Session 尾部遇到
 `data_changed` 时通过权威 delta 合并恢复；后台持久化失败会显示为诊断，不再静默丢失。
 
+**v0.7.96-alpha.2 发布（Windows 修复）**：恢复被 FEATURE_295 清理误删的
+Windows boot-identity PowerShell 解析函数（其唯一调用方仍保留）。在
+v0.7.96-alpha.1 上，每次 Windows exit settlement 都会以
+`windowsAclPowerShellExecutable is not defined` 崩溃，sandbox cleanup 只能标记为
+`unverified`；恢复后的实现附带 win32 回归测试，关闭 Issue 325。Windows 用户请
+从 v0.7.96-alpha.1 升级到 v0.7.96-alpha.2。详见
+[v0.7.96-alpha.2 发布清单](docs/release.md#v0796-alpha2-release-preparation)。
+
+**v0.7.96-alpha.1 发布**：所有桌面平台的受控
+文本工具与 shell containment 拆分为两个独立权威。`write`、`edit`、`multi_edit`、`insert_after_anchor`、
+`undo` 在可信 KodaX Runtime 中完成最终路径/identity 策略校验、跨 Runtime
+逐文件内核锁、revision CAS、元数据保留的 flush 后原子替换与受保护 native 状态根；它们不进入 ASRT、workspace
+session、shell runner、setup、cleanup、owner、reset 或 poison 状态，也不宣称受到
+OS token sandbox enforcement。根入口和 `/coding` 的 `runKodaX`、`startKodaX`、
+`runManagedTask`、`createKodaXTaskRunner`、`createDefaultCodingAgent`、`KodaXClient` 及其 `Client` 别名默认绑定同一 native 文本权威，并在每次事务读取新注册的 linked-
+worktree 根。Windows shell 仅由 ASRT 提供网络/专用账户服务，
+KodaX native runner 负责 restricted token、nonce 绑定且按 policy 隔离的私有 desktop、创建时 Job containment 和 framed stdio；
+不同 policy、Session、Runtime 的 native shell 不共享覆盖命令生命周期的 filesystem-
+effect lease。同一 Runtime 中具有完全相同网络策略和 sandbox 账户代际的命令共享
+一个 ASRT 网络 broker，但仍各自拥有 policy token 与 Job；不同策略绝不共享权威。
+Issue 308 记录 ASRT 0.0.65 对不同策略/Runtime 仍存在的固定端口容量限制。任意 shell 写文件仍是正常 OS 数据竞争，KodaX CAS 只约束受控文本
+工具。目标 stdin EOF 不会关闭 native 控制流；控制与事件使用相互独立且认证过的
+单向管道。timeout/cancel 只有在校验 nonce 绑定的 runner 终态记录、确认整个 Job
+已排空后才返回原始停止原因。每个共享 broker 还拥有一个经校验的 native 存活
+controller。Windows 可信替换会把旧 sandbox owner 的文件自动归一为可信 host
+owner，并保留有序的最终有效 ACE 策略；文件系统可在原子命名空间提交时规范化
+DACL protection/inheritance 控制位，旧父目录的继承权限不会被原样冻结。
+即使工作区整体可写，shell 也不能读写工作区内的 `.kodax/runtime` 控制状态。
+其 named pipe 创建时即应用仅 Host/SYSTEM 的 protected DACL，并保留
+多个 pending instance。受限目标无法连接或耗尽它；controller/broker 丢失会关闭
+通道并排空所有关联命令的 Job。native 请求与终态记录位于无 reparse、仅 host/SYSTEM
+可访问的控制目录；SDK policy 校验和 native host 都会在目标启动前拒绝与该目录
+祖先或子孙重叠的 allow root，以及指向该目录或其子项的 deny root。doctor 只验证；
+显式 setup 会先证明 sandbox 账户已空闲，只回收已过 deadline 且 owner PID 已死的
+请求，或已证明 Job 排空的死 owner 终态记录，再修复 host-owned 状态；live、未过期、
+损坏、未知及 deny-recovery 记录继续 fail-closed。Unix 在原子提交后若无法证明目录 durability，会携带
+完整的提交前/后 receipt 返回 `text_mutation_commit_uncertain`，要求先重读，禁止盲目重试。已有文件的修改会
+保留 Undo backup；若 Undo 本身处于提交不确定状态，其 receipt 会重绑定到观测到的
+提交后 revision，之后只能通过 CAS 校验的 Undo 继续收敛。详见
+[ADR-066](docs/ADR.md#adr-066-trusted-text-transactions-and-a-native-windows-shell-sandbox-are-separate-authorities)。
+这次不兼容的权威拆分由 `sandboxRuntime:6` 门禁；新客户端不会静默复用仍执行
+v0.7.95 旧调用图的 daemon。
+现有 Windows 安装需要运行一次 `kodax sandbox setup`：切换流程会等待旧沙箱进程
+退出，使用新 SID 重建专用账户，并记录 native protocol/SID 代际。迁移状态缺失时
+只阻止 native shell 准入，不会阻止可信文本工具。
+Windows 的嵌入发布 manifest 会钉住 text/shell 的 protocol 与 hash，以及 ASRT
+release version 与 hash。已校验的可执行文件进入独立于 `KODAX_HOME` 的 LocalAppData
+content-addressed 受保护存储；ASRT 在落库前与 broker 启动前都会重验。text 仅
+Host/SYSTEM 可访问，专用 sandbox group SID 对 shell artifact 只有 read/execute，
+local Users 对 ASRT 只有 read/execute；sandbox trustee 与 local Users 均无
+write/delete 权限。
+包存储中的 hardlink 仅在 bundled 构建中可作为 ASRT 来源，并通过同一文件句柄的
+有界读取核对完整字节与内嵌发布 digest；开发态 manifest 与来源仍须单链接。broker
+实际执行的仍是独立、受保护、单链接文件。allow-root 授权只修改精确 canonical
+root，不再改写其私有祖先目录的 DACL。
+Linux/macOS 使用同一可信文本权威及 native no-follow/`flock`/CAS/原子提交；
+shell 仍是逐命令 ASRT bubblewrap/Seatbelt 执行，不保留 KodaX workspace-session owner。
+Issue 307 记录 ASRT 所有的 runner 在 KodaX 代码运行前启动这一更窄的 pre-main
+窗口；当前 Codex 也保留相同边界。最终命令仍在创建时加入 Job，可信文本工具完全
+不经过该边界。Issue 309 记录另一个与 Codex 相同的 Windows 残余：稳定 root
+capability 无法覆盖显式 ambient loader-compatibility ACE；该 ACE 既可能由此前
+sandbox 命令留下，也可能原本就存在于 external 或 host-owned descendant 上。
+本版本同时以容量债务准入（capacity-debt admission）和有界恢复阶梯取代本地
+tool-result 容量硬门禁（ADR-067），本地容量终态归类为
+`failureKind: "context_capacity"` 并附带结构化 `contextTokens`，失败事件、Run
+结果/状态与 Session 诊断提供同一份凭据安全的 `failureDetail`。本版本广告
+Windows `sandboxRuntime:6`；`runtimeExitSettlement:2` 与 `crashOutcomeModel:2`
+不变。详见
+[v0.7.96-alpha.1 发布清单](docs/release.md#v0796-alpha1-release-preparation)。
+
 **v0.7.95 发布**：零字节、畸形或截断 owner 的过期 learning lock
 会在字节与 stat 二次确认未变后自动恢复。同一次 Windows 启动内的
 `unconfirmed-owner` 会持续自动重试，只有精确 sandbox-user SID 探针证明空闲后
@@ -518,12 +616,13 @@ kodax sandbox doctor
 kodax sandbox setup
 ```
 
-- Windows 使用受限 sandbox 账户和网络策略。普通 Terminal 即可，按提示同意一次
-  UAC；不必先以管理员身份启动 Terminal。
+- Windows 使用受限 sandbox 账户和网络策略。普通 Terminal 即可，按提示同意激活
+  所需的 UAC 确认；不必先以管理员身份启动 Terminal。
 - macOS 使用 Seatbelt/`sandbox-exec`，需要 ripgrep：
   `brew install ripgrep`。
 - Linux 使用 bubblewrap，需要 `bubblewrap`、`socat` 和 `ripgrep`，请根据发行版用
-  `apt`、`dnf` 或 `pacman` 安装。
+  `apt`、`dnf` 或 `pacman` 安装。宿主内核与安全策略还必须允许非特权 user
+  namespace；若 backend 无法启动，KodaX 会明确报告，且不会自行修改系统策略。
 
 KodaX 不会自动运行 `sudo` 或系统包管理器。sandbox 未激活时，确定性安全操作与
 Auto[LLM] 的权限体验保持一致，只缺少 OS 级 containment；普通运行不会反复打扰。
@@ -723,34 +822,28 @@ Verifier 的 `revise` / `blocked` 可执行消息；JSONL 输出使用同形
 
 #### 给自定义 provider 开图片 / vision 输入（FEATURE_134 v0.7.40）
 
-如果你的自定义 provider 后面的模型支持 vision，加 `capabilityProfile.multimodalSupport: "image-input"` 显式开启，KodaX 的 SA-path policy gate 就不会人为拦截多模态请求。内置 vision-capable alias（Anthropic、OpenAI、Kimi、Qwen、Zhipu、MiniMax、MiMo、Ark，以及通过 CLI `@<path>` file-include 语法传图的 Gemini-CLI）已经默认开了这个 flag。DeepSeek V4 和 Codex-CLI 是纯文本模型；自定义 provider 在底层模型支持图片输入时需要手动 opt-in。
+如果你的自定义 provider 后面的模型支持 vision，设置 `"imageInput": true` 即可，KodaX 的图片路由和 provider policy gate 都会放行图片输入。这是自托管多模态模型（vLLM / SGLang 部署 Qwen-VL 类模型、OpenAI-compatible 端点）的典型用法：
 
 ```json
 {
   "customProviders": [
     {
-      "name": "my-vision-provider",
+      "name": "my-vllm",
       "protocol": "openai",
-      "baseUrl": "https://example.com/v1",
-      "apiKeyEnv": "MY_LLM_API_KEY",
-      "model": "my-vision-model",
-      "capabilityProfile": {
-        "transport": "native-api",
-        "conversationSemantics": "full-history",
-        "mcpSupport": "none",
-        "contextFidelity": "full",
-        "toolCallingFidelity": "full",
-        "sessionSupport": "full",
-        "longRunningSupport": "full",
-        "multimodalSupport": "image-input",
-        "evidenceSupport": "full"
-      }
+      "baseUrl": "http://localhost:8000/v1",
+      "apiKeyEnv": "MY_VLLM_API_KEY",
+      "model": "Qwen/Qwen3.8-27B-Instruct",
+      "imageInput": true
     }
   ]
 }
 ```
 
-序列化层（Anthropic-compat 走 `packages/llm/src/providers/anthropic.ts:770`，OpenAI-compat 走 `openai.ts:904`）通过基类继承自动转发 image block。这个 flag 只控制 KodaX 自身是否预先拒绝多模态请求 —— 上游模型到底支不支持 vision 由 provider 自己决定。如果模型实际是 text-only，你会看到真实的上游 API 错误，而不是 KodaX 一侧的 `[Provider Policy] multimodal requests are unsupported` 预拦截。
+`imageInput: true` 会在 KodaX 所有层面（provider 实例、能力查询、policy gate）强制 `capabilityProfile.multimodalSupport: "image-input"`，显式写了 `"none"` 也会被覆盖。进阶写法 —— 手写 `capabilityProfile` 块并设 `"multimodalSupport": "image-input"` —— 同样有效，详见 [Custom Providers](public_docs/configuration/custom-providers.md)。纯文本模型保持不设即可，图片 artifact 会在请求发出前被 `MODEL_INPUT_UNSUPPORTED` 拒绝。
+
+内置 vision-capable alias（Anthropic、OpenAI、Kimi、Qwen、Zhipu、MiniMax、MiMo、Ark，以及通过 CLI `@<path>` file-include 语法传图的 Gemini-CLI）已经默认开了图片输入。DeepSeek V4 默认模型（`deepseek-v4-flash` / `deepseek-v4-pro`）和 Codex-CLI 是纯文本 —— 内置 `deepseek` 只有 `deepseek-v4-flash-vision-exp` 这一个路由收图；自定义 provider 在底层模型支持图片输入时需要手动 opt-in。
+
+序列化层（Anthropic-compat 走 `packages/llm/src/providers/anthropic.ts:1431`，OpenAI-compat 走 `openai.ts:1496`）通过基类继承自动转发 image block —— OpenAI-compatible 端点收到的是标准 `image_url` 块。这个 flag 只控制 KodaX 自身是否预先拒绝多模态请求 —— 上游模型到底支不支持 vision 由 provider 自己决定。如果模型实际是 text-only，你会看到真实的上游 API 错误，而不是 KodaX 一侧的 `[Provider Policy] multimodal requests are unsupported` 预拦截。
 
 库模式下用 `registerCustomProviders()` 显式注册：
 
@@ -873,7 +966,7 @@ dist/binary/linux-x64/
 | mimo | `MIMO_API_KEY` | Native | mimo-v2.5-pro（小米 MiMo 按量计费，Anthropic 协议） |
 | mimo-coding | `MIMO_CODING_API_KEY` | Native | mimo-v2.5-pro（小米 MiMo Token Plan，Anthropic 协议） |
 | ark-coding | `ARK_CODING_API_KEY` | Native | glm-5.3（火山方舟 Coding Plan — GLM-5.3（1M ctx、128K out） · GLM-5.2（别名 `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（可 `/model` 切换 `deepseek-v4-pro`） |
+| deepseek | `DEEPSEEK_API_KEY` | Native | deepseek-v4-flash（可 `/model` 切换 `deepseek-v4-pro` 及视觉模型 `deepseek-v4-flash-vision-exp`，后者支持图片输入） |
 | gemini-cli | 由 Provider CLI 完成认证（无 KodaX API-key 环境变量） | Prompt-only / CLI bridge | （通过 gemini CLI） |
 | codex-cli | 由 Provider CLI 完成认证（无 KodaX API-key 环境变量） | Prompt-only / CLI bridge | （通过 codex CLI） |
 
@@ -1145,7 +1238,7 @@ KodaX/                       # 4 workspace packages(FEATURE_194 v0.7.43)
 ├── scripts/
 │   ├── build-bundle.mjs     # esbuild 单 bundle 多 entry 打包（CLI + root + 12 SDK subpath + chunks）
 │   ├── build-binary.mjs     # Bun --compile 单文件二进制打包
-│   └── release.mjs          # 构建/审计后仅临时切换 private 以 pack/publish
+│   └── release.mjs          # 发布 CI 构建的通用 tarball；本地 --pack-only 保持 private:true
 └── .github/workflows/
     └── release.yml          # 推 v* tag 自动发布 GitHub Release
 ```

package/config-templates/config.example.jsonc

@@ -10,7 +10,7 @@
   // "model": "deepseek-v4-flash",
   // Add or reorder model ids shown by `/model` for a provider.
   // "providerModels": {
-  //   "deepseek": ["deepseek-v4-flash", "deepseek-v4-pro"]
+  //   "deepseek": ["deepseek-v4-flash", "deepseek-v4-pro", "deepseek-v4-flash-vision-exp"]
   // },
 
   // Interactive Runtime hosting: "embedded" (this process) or "daemon".
@@ -81,6 +81,7 @@
   //     "maxOutputTokens": 8192,
   //     "maxOutputTokensField": "max_completion_tokens",
   //     "thinkingBudgetCap": 32000,
+  //     "imageInput": true,
   //     "promptCacheAffinity": false,
   //     "replayReasoningContent": false,
   //     "strictThinkingSignature": false,