Merge pull request #1362 from deepseek-harness/fix/landlock-runner-failure-classification

Fix false sandbox failures from Landlock partial-enforcement notices
2026-08-05 13:59:47 +08:00
parent b5da33c9ac 75bd2b8aaa
commit 61e46f077e
58 changed files with 1418 additions and 250 deletions
--- a/packages/sandbox/sandbox-local/README.i18n.yaml
+++ b/packages/sandbox/sandbox-local/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/sandbox/sandbox-local/README.md
-README.md: 923d983be8c2ccd60ed6eabcf9212dd89ef9bce3
-README.zh.md: c85fd7e36b8575709ce9341f337da3a8bafd25b0
+README.md: f7dd5619fa69ae226def78415a91d51ba99e0a65
+README.zh.md: c8abe05408ac8917b2c5dc39acdbdf9d9539744d
--- a/packages/sandbox/sandbox-local/README.md
+++ b/packages/sandbox/sandbox-local/README.md
@@ -6,9 +6,9 @@ Local implementation of the [`dsh-sandbox`](../sandbox/) seam. It selects and ca

 The package root exports the default and named `LocalSandboxProvider` plugin, `Config`, and its public test-injection seam; platform profile builders stay internal.

-Unsupported platforms and unusable runners fail closed with `SANDBOX_UNAVAILABLE`; execution never silently falls through unconfined. Each wrap carries runner-failure signatures so consumers can distinguish a broken sandbox from a command failure. The [sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) owns selection rationale and profile differences.
+Unsupported platforms and unusable runners fail closed with `SANDBOX_UNAVAILABLE`; execution never silently falls through unconfined. Each wrap carries structured runner-failure rules so consumers can distinguish a broken sandbox from a command failure. The [sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) owns selection rationale and profile differences.

-Policy is per call; the provider stores only the mechanism and cached runner verdict. Each wrap reports enforcement completeness plus backend-specific denial and runner-failure signatures. `runnerCommand` is an operator assertion of a bwrap-shaped runner and skips probes, but missing or unexecutable commands still fail closed at execution. Because its mechanism is unknown, it carries both Linux denial dialects. `probeTimeoutMs` bounds functional probes. The [sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) owns selection and failure semantics.
+Policy is per call; the provider stores only the mechanism and cached runner verdict. Each wrap reports enforcement completeness plus backend-specific denial signatures and runner-failure rules. Landlock requires exit 125 and a `landlock-run:` fatal line after excluding only the exact partial-enforcement notice; a notice with child exit 1, 2, or 125 remains a child outcome. Bubblewrap and Seatbelt remain signature-only because neither public contract reserves a launcher-failure status. Consumers spawn the returned argv directly, so a missing or unexecutable runner is an out-of-band spawn failure while a successfully launched child exit 126 or 127 remains ordinary. `runnerCommand` skips probes and requires one or more non-empty, single-line, case-insensitive `runnerFailureSignatures` entries for the custom runner's own fatal dialect. Because its mechanism is unknown, it carries both Linux denial dialects. `probeTimeoutMs` bounds functional probes. The [sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) owns selection and failure semantics.

 The Seatbelt profile is allow-default with `(deny file-write*)` plus write allow-lists, so exactly the mode's promised file effects are governed: `read-only` grants the `/dev/null` literal alone; `workspace-write` adds the workspace root, `/tmp`, and the per-user darwin temp dir (`os.tmpdir()` — the platform's real temp area for mkstemp-family tools), every root canonicalized because Seatbelt matches resolved paths (`/tmp` IS `/private/tmp`). Apple marks the `sandbox-exec` CLI deprecated but ships it on every macOS; the functional probe is what fails closed if that ever changes.

@@ -37,4 +37,4 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 - **Landlock may be partial** — older supported kernel ABIs confine only the access classes they expose, reported as `enforcement: 'partial'` rather than overstated as full.
 - **Seatbelt depends on deprecated `sandbox-exec`** — macOS still ships it, but this provider cannot replace or probe that private policy engine if Apple removes it.
 - **Runner selection is cached for the provider lifetime** — installing, removing, or repairing a runner requires reloading the plugin before selection changes.
- **`runnerCommand` is an operator assertion** — a configured custom runner skips functional probes and is assumed to implement the bwrap-shaped profile honestly.
+- **`runnerCommand` is an operator assertion** — a configured custom runner skips functional probes and is assumed to implement the bwrap-shaped profile honestly; if it is itself a Bash script, its interpreter startup runs before that script applies confinement.
--- a/packages/sandbox/sandbox-local/README.zh.md
+++ b/packages/sandbox/sandbox-local/README.zh.md
@@ -6,9 +6,9 @@

 包根目录导出默认及命名的 `LocalSandboxProvider` 插件、`Config` 和公共测试注入 seam；平台 profile builder 仍为内部实现。

-不受支持的平台和不可用 runner 会以 `SANDBOX_UNAVAILABLE` 拒绝执行；执行绝不会静默回退为不受限制。每次包装都携带 runner 失败签名，使消费方能够区分损坏的沙箱与命令失败。[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责说明选择依据与 profile 差异。
+不受支持的平台和不可用 runner 会以 `SANDBOX_UNAVAILABLE` 拒绝执行；执行绝不会静默回退为不受限制。每次包装都携带结构化 runner 失败规则，使消费方能够区分损坏的沙箱与命令失败。[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责说明选择依据与 profile 差异。

-策略逐调用传入；提供方只存储机制与缓存的 runner 结论。每次包装都会报告强制执行完整度，以及后端专用的拒绝和 runner 失败签名。`runnerCommand` 是操作方对 bwrap 形式 runner 的断言，会跳过探测；但命令缺失或不可执行时，执行仍会被拒绝。由于其机制未知，它会同时携带两种 Linux 拒绝方言。`probeTimeoutMs` 限制功能探测。[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责说明选择与失败语义。
+策略逐调用传入；提供方只存储机制与缓存的 runner 结论。每次包装都会报告强制执行完整度，以及后端专用的拒绝签名和 runner 失败规则。Landlock 只有在退出码为 125，且排除唯一精确匹配的部分强制执行通知后仍存在一行 `landlock-run:` 致命诊断时，才判定 runner 失败；携带该通知的子进程即使以 1、2 或 125 退出，也仍按子进程结果处理。Bubblewrap 和 Seatbelt 仍仅依据签名，因为两者的公开契约均未保留 launcher 失败状态。消费方会直接 spawn 返回的 argv，因此 runner 缺失或不可执行属于带外 spawn 失败，而成功启动的子进程以 126 或 127 退出时仍按普通结果处理。`runnerCommand` 会跳过探测，并要求为自定义 runner 自身的致命方言提供一个或多个非空、单行、不区分大小写的 `runnerFailureSignatures` 条目。由于其机制未知，它会同时携带两种 Linux 拒绝方言。`probeTimeoutMs` 限制功能探测。[沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)负责说明选择与失败语义。

 Seatbelt profile 默认允许，但带 `(deny file-write*)` 和写入 allow-list，因此恰好约束相应模式承诺的文件操作：`read-only` 只授予 `/dev/null` 字面路径；`workspace-write` 另加工作区根目录、`/tmp` 和逐用户 darwin 临时目录（`os.tmpdir()`，即平台供 mkstemp 家族工具使用的真实临时区域）。每个根目录都经过规范化，因为 Seatbelt 匹配解析后的路径（`/tmp` 就是 `/private/tmp`）。Apple 将 `sandbox-exec` CLI（命令行界面）标为 deprecated，但所有 macOS 系统仍会提供它；若情况发生变化，功能探测会使执行被拒绝。

@@ -37,4 +37,4 @@ Seatbelt profile 默认允许，但带 `(deny file-write*)` 和写入 allow-list
 - **Landlock 可能只实现部分强制执行**：较旧且受支持的内核 ABI 只能限制自身公开的访问类别，因此报告 `enforcement: 'partial'`，不会夸大为完整强制执行。
 - **Seatbelt 依赖已弃用的 `sandbox-exec`**：macOS 仍会提供它，但若 Apple 移除该私有策略引擎，该提供方无法替换或探测。
 - **runner 选择在提供方生命周期内缓存**：安装、移除或修复 runner 后，必须重载插件才能改变选择。
- **`runnerCommand` 是操作方断言**：配置的自定义 runner 会跳过功能探测，并假定它诚实实现 bwrap 形式的 profile。
+- **`runnerCommand` 是操作方断言**：配置的自定义 runner 会跳过功能探测，并假定它诚实实现 bwrap 形式的 profile；如果它本身是 Bash 脚本，其解释器启动发生在该脚本施加约束之前。
--- a/packages/sandbox/sandbox-local/src/index.ts
+++ b/packages/sandbox/sandbox-local/src/index.ts
@@ -1,18 +1,23 @@
 /**
 * Local sandbox backend. It selects the platform runner chain (Linux bwrap then
 * Landlock; macOS Seatbelt), functionally probes competing candidates once, and
- * reports each wrap's enforcement and stderr dialects. Missing or unusable
+ * reports each wrap's enforcement and stderr classification facts. Missing or unusable
 * confinement fails closed rather than returning the original argv.
 * @module @deepseek-ai/dsh-sandbox-local
 */

 import { spawnSync } from 'node:child_process'
-import { LAUNCHER_BIN, launcherPath as landlockLauncherPath, probe as defaultProbeLandlock } from 'node-addon-landlock-run'
+import {
+  LAUNCHER_BIN,
+  LAUNCHER_FAILURE_EXIT,
+  launcherPath as landlockLauncherPath,
+  probe as defaultProbeLandlock,
+} from 'node-addon-landlock-run'
 import { Context } from 'cordis'
 import z from 'schemastery'
 import { assertNever } from '@deepseek-ai/dsh-llm'
 import { SandboxProvider, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
-import type { ConfinedArgv, ConfinedSandboxMode, SandboxEnforcement, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
+import type { ConfinedArgv, ConfinedSandboxMode, RunnerFailureRule, SandboxEnforcement, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import { bwrapProfileArgs, landlockProfileArgs, seatbeltProfileArgs } from './profiles.ts'

 /** Plugin config. All optional — `static Config` supplies the defaults. */
@@ -20,17 +25,18 @@ export interface Config {
  /**
   * Override the runner argv; bwrap-shaped profile arguments are appended. A
   * non-empty override asserts full enforcement and skips built-in selection and
-   * probing; a broken runner then fails at execution and must be identifiable by
-   * {@link runnerFailureSignatures}.
+   * probing. A runner that starts but refuses its profile must be identifiable by
+   * {@link runnerFailureSignatures}. Consumers classify spawn rejection; only
+   * attributable `ENOENT` or `EACCES` with runner argv[0] provenance becomes an
+   * infrastructure failure.
   */
  runnerCommand?: string[]
  /**
   * Case-insensitive stderr substrings emitted when a configured
   * {@link runnerCommand} refuses its profile before executing the wrapped
   * command. Required and non-empty with `runnerCommand`; rejected without
-   * it. Missing/unexecutable runner errors are added automatically from
-   * `runnerCommand[0]`, while these signatures cover an executable runner's
-   * own failure dialect.
+   * it. Each entry is a non-empty, single-line, case-insensitive substring
+   * covering the executable runner's own failure dialect.
   */
  runnerFailureSignatures?: string[]
  /** Positive timeout for each functional probe; zero would mean unbounded to Node. */
@@ -142,15 +148,22 @@ const DENIAL_SIGNATURES = {
 } as const satisfies Record<SelectedRunner['runner'] | 'runnerCommand', readonly string[]>

 /**
- * Runner-owned stderr prefixes cover both internal refusal and shell-level
- * not-found errors. Consumers match these before denial text because the
- * command never ran on this path.
+ * Runner-owned fatal diagnostics. Landlock has a versioned exit-125 plus
+ * fatal-line launcher-failure contract. Bubblewrap's current fatal paths exit
+ * 1 but its public contract does not reserve that status, while sandbox-exec
+ * publishes no launcher-failure status; those backends remain signature-only.
+ * Keep the Landlock tuple aligned with the assembled snapshot fixture at
+ * `examples/acp-agent/tests/fixtures/partial-landlock-sandbox.ts`.
 */
-const RUNNER_FAILURE_SIGNATURES = {
-  bwrap: ['bwrap: '],
-  landlock: [`${LAUNCHER_BIN}: `],
-  seatbelt: ['sandbox-exec: '],
-} as const satisfies Record<SelectedRunner['runner'], readonly string[]>
+const RUNNER_FAILURE_RULES = {
+  bwrap: [{ fatalSignatures: ['bwrap: '] }],
+  landlock: [{
+    allowedExitCodes: [LAUNCHER_FAILURE_EXIT],
+    fatalSignatures: [`${LAUNCHER_BIN}: `],
+    informationalLines: [`${LAUNCHER_BIN}: partial enforcement (older Landlock ABI)`],
+  }],
+  seatbelt: [{ fatalSignatures: ['sandbox-exec: '] }],
+} as const satisfies Record<SelectedRunner['runner'], readonly RunnerFailureRule[]>

 /**
 * Local process-sandbox provider. Registers as `ctx.sandbox`. Stateless
@@ -187,8 +200,8 @@ export class LocalSandboxProvider extends SandboxProvider {
    if (runner.length > 0 && runnerFailureSignatures.length === 0) {
      throw new Error('sandbox-local: runnerCommand requires at least one runnerFailureSignatures entry')
    }
-    if (runnerFailureSignatures.some(signature => signature.trim().length === 0)) {
-      throw new Error('sandbox-local: runnerFailureSignatures entries must be non-empty')
+    if (runnerFailureSignatures.some(signature => signature.trim().length === 0 || /[\r\n]/u.test(signature))) {
+      throw new Error('sandbox-local: runnerFailureSignatures entries must be non-empty single-line strings')
    }
    this.runnerCommand = runner.length > 0 ? runner : undefined
    this.configuredRunnerFailureSignatures = runnerFailureSignatures
@@ -204,33 +217,25 @@ export class LocalSandboxProvider extends SandboxProvider {
   * @param argv - the exact argv the caller is about to spawn.
   * @param policy - the file-effect policy this execution runs under.
   * @returns the wrapped argv plus the selected backend's enforcement completeness, denial
-   *   signatures, and runner-failure signatures; throws the fail-closed
+   *   signatures, and structured runner-failure rules; throws the fail-closed
   *   `SANDBOX_UNAVAILABLE` error when the platform has no usable runner.
   */
  confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv {
    if (this.runnerCommand !== undefined) {
-      const argv0 = this.runnerCommand[0] as string
      return {
        argv: [...this.runnerCommand, ...bwrapProfileArgs(policy), '--', ...argv],
        enforcement: 'full',
        denialSignatures: DENIAL_SIGNATURES.runnerCommand,
-        // The operator names the configured runner's own pre-exec refusal dialect; the consumer
-        // additionally re-joins the wrap through an outer `bash -c 'exec …'`, so we can add the
-        // missing/unexecutable outer-shell shapes ourselves.
-        runnerFailureSignatures: [
-          ...this.configuredRunnerFailureSignatures,
-          `exec: ${argv0}: not found`,
-          `${argv0}: No such file or directory`,
-          `${argv0}: Permission denied`,
-        ],
+        runnerFailureRules: [{ fatalSignatures: this.configuredRunnerFailureSignatures }],
      }
    }
    const selected = this.selectRunner(policy.mode)
+    const runnerArgv = this.runnerArgv(selected.runner, policy)
    return {
-      argv: [...this.runnerArgv(selected.runner, policy), '--', ...argv],
+      argv: [...runnerArgv, '--', ...argv],
      enforcement: selected.enforcement,
      denialSignatures: DENIAL_SIGNATURES[selected.runner],
-      runnerFailureSignatures: RUNNER_FAILURE_SIGNATURES[selected.runner],
+      runnerFailureRules: RUNNER_FAILURE_RULES[selected.runner],
    }
  }

--- a/packages/sandbox/sandbox-local/tests/local.spec.ts
+++ b/packages/sandbox/sandbox-local/tests/local.spec.ts
@@ -12,6 +12,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
+import { LAUNCHER_FAILURE_EXIT } from 'node-addon-landlock-run'
 import { SANDBOX_UNAVAILABLE, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
 import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import {
@@ -35,7 +36,7 @@ async function setup(config: Config = {}, internals: LocalSandboxProvider['inter
 function fakeLauncher(report = 'landlock: fully enforced'): string {
  const dir = mkdtempSync(join(tmpdir(), 'dsh-fake-landlock-'))
  const launcher = join(dir, 'landlock-run')
-  writeFileSync(launcher, `#!/bin/sh\nif [ "$1" = "--probe" ]; then echo "${report}"; exit 0; fi\nexit 125\n`, { mode: 0o755 })
+  writeFileSync(launcher, `#!/bin/sh\nif [ "$1" = "--probe" ]; then echo "${report}"; exit 0; fi\nexit ${LAUNCHER_FAILURE_EXIT}\n`, { mode: 0o755 })
  return launcher
 }

@@ -111,16 +112,7 @@ describe('runnerCommand config', () => {
      // An operator runner's kernel mechanism is unknown: both Linux
      // file-denial dialects, never bare EPERM.
      denialSignatures: ['read-only file system', 'permission denied'],
-      // The runner's own dialect is unknown, but the consumer re-joins the
-      // wrap through an outer `bash -c 'exec …'` — a missing or
-      // unexecutable runner fails with the OUTER shell's argv0-scoped
-      // shapes, and those classify as sandbox failures like any rung.
-      runnerFailureSignatures: [
-        'fake-runner: profile rejected',
-        'exec: fake-runner: not found',
-        'fake-runner: No such file or directory',
-        'fake-runner: Permission denied',
-      ],
+      runnerFailureRules: [{ fatalSignatures: ['fake-runner: profile rejected'] }],
    })
    expect(probeBwrap).not.toHaveBeenCalled()
    expect(probeLandlock).not.toHaveBeenCalled()
@@ -146,11 +138,14 @@ describe('runnerCommand config', () => {
    )
  })

-  it('rejects blank configured-runner failure signatures', async () => {
-    await expect(setup({ runnerCommand: ['fake-runner'], runnerFailureSignatures: ['  '] })).rejects.toThrow(
-      'runnerFailureSignatures entries must be non-empty',
-    )
-  })
+  it.each(['  ', 'fatal\ncontinued', 'fatal\rcontinued'])(
+    'rejects an unusable configured-runner failure signature %j',
+    async (signature) => {
+      await expect(setup({ runnerCommand: ['fake-runner'], runnerFailureSignatures: [signature] })).rejects.toThrow(
+        'runnerFailureSignatures entries must be non-empty single-line strings',
+      )
+    },
+  )
 })

 describe('the platform chains', () => {
@@ -163,7 +158,7 @@ describe('the platform chains', () => {
      argv: ['bwrap', ...bwrapProfileArgs(RO), '--', 'true'],
      enforcement: 'full',
      denialSignatures: ['read-only file system'],
-      runnerFailureSignatures: ['bwrap: '],
+      runnerFailureRules: [{ fatalSignatures: ['bwrap: '] }],
    })
    expect(probeLandlock).not.toHaveBeenCalled()
  })
@@ -178,14 +173,18 @@ describe('the platform chains', () => {
      argv: [launcher, ...landlockProfileArgs(WW), '--', 'bash', '-c', 'echo hi'],
      enforcement: 'full',
      denialSignatures: ['permission denied'],
-      runnerFailureSignatures: ['landlock-run: '],
+      runnerFailureRules: [{
+        allowedExitCodes: [LAUNCHER_FAILURE_EXIT],
+        fatalSignatures: ['landlock-run: '],
+        informationalLines: ['landlock-run: partial enforcement (older Landlock ABI)'],
+      }],
    })
    expect(probeLandlock).toHaveBeenCalledWith(launcher)
  })

  it('darwin selects its sole candidate WITHOUT probing: nothing to arbitrate', async () => {
    // The safety property moves to execution time: an unusable sandbox-exec
-    // refuses to run the command, and the wrap's runnerFailureSignatures let
+    // refuses to run the command, and the wrap's runnerFailureRules let
    // the consumer classify that as a sandbox failure, not a task failure.
    const probeSeatbelt = vi.fn(() => true)
    const { sandbox } = await setup({}, { platform: 'darwin', probeSeatbelt })
@@ -194,7 +193,7 @@ describe('the platform chains', () => {
      argv: ['sandbox-exec', ...seatbeltProfileArgs(RO), '--', 'bash', '-c', 'echo hi'],
      enforcement: 'full',
      denialSignatures: ['operation not permitted'],
-      runnerFailureSignatures: ['sandbox-exec: '],
+      runnerFailureRules: [{ fatalSignatures: ['sandbox-exec: '] }],
    })
    expect(probeSeatbelt).not.toHaveBeenCalled()
  })
@@ -311,7 +310,7 @@ describe('the default landlock probe (launcher CLI contract)', () => {
  it('reads a failing launcher as unusable: the chain ends and fails closed', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'dsh-fake-landlock-'))
    const launcher = join(dir, 'landlock-run')
-    writeFileSync(launcher, '#!/bin/sh\nexit 125\n', { mode: 0o755 })
+    writeFileSync(launcher, `#!/bin/sh\nexit ${LAUNCHER_FAILURE_EXIT}\n`, { mode: 0o755 })
    const { sandbox } = await setup({}, { platform: 'linux', probeBwrap: () => false, landlockLauncher: launcher })
    expect(() => sandbox.confine(['true'], RO)).toThrow(expect.objectContaining({ code: SANDBOX_UNAVAILABLE }))
  })
@@ -360,7 +359,7 @@ describe('the default seatbelt probe (sandbox-exec contract)', () => {
      argv: [exec, ...seatbeltProfileArgs(RO), '--', 'true'],
      enforcement: 'full',
      denialSignatures: ['operation not permitted'],
-      runnerFailureSignatures: ['sandbox-exec: '],
+      runnerFailureRules: [{ fatalSignatures: ['sandbox-exec: '] }],
    })
  })

--- a/packages/sandbox/sandbox/README.i18n.yaml
+++ b/packages/sandbox/sandbox/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/sandbox/sandbox/README.md
-README.md: 99f0641560937f66df6db76ae55c90595329792f
-README.zh.md: dff077779153f15aa54ccc24ca1e8551ce3b75df
+README.md: 1b522b2c72d00bfed89650aa7f22b65a72d26085
+README.zh.md: adccd4421a74ef073ad3ffc3a23bccb0354d99aa
--- a/packages/sandbox/sandbox/README.md
+++ b/packages/sandbox/sandbox/README.md
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)

 Abstract process-sandbox seam. Owns the `ctx.sandbox` service contract ([`SandboxProvider`](src/index.ts)) and the confinement vocabulary the harness shares: `SandboxMode` (`read-only` / `workspace-write` / `danger-full-access`, file effects only), `SandboxEnforcement` (`full` / `partial`, per kernel ABI), `SandboxExecutionPolicy` (the complete per-call mode + workspace root), `SandboxPolicy` (its confined subset), and the fail-closed `SANDBOX_UNAVAILABLE` error. Interface package of the [capability-seam split](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): depends only on cordis (+ the harness error base), never on a backend.

-The contract in one line: `ctx.sandbox.confine(argv, policy)` returns the argv to spawn INSTEAD of your own — wrapped so the process (and everything it spawns) runs confined — plus two facts about the selected backend: the enforcement completeness it achieves and its denial dialect (`denialSignatures`, the stderr substrings its kernel prints on a denied file effect — what stderr-inferring consumers match instead of a cross-backend union); when no backend is usable it throws rather than passing the argv through unconfined.
+The contract in one line: `ctx.sandbox.confine(argv, policy)` returns the argv to spawn INSTEAD of your own — wrapped so the process (and everything it spawns) runs confined — plus the selected backend's enforcement completeness, denial dialect (`denialSignatures`), and structured runner-failure evidence (`runnerFailureRules`); when no backend is usable it throws rather than passing the argv through unconfined. The [core type catalog](../../../docs/core-data-structures/sandbox.md#wrapped-argv-and-classification-dialects) owns the exact classifier shape.

 Policy rides the call, not the provider: two consumers may confine under different policies at the same instant (bash under `read-only` while a confined child agent keeps its state directory writable), and an approved escalated retry is just a new call with a wider policy.

@@ -39,4 +39,5 @@ Append-only; newly visible content follows the reusable request prefix and does
 - **File effects are the whole policy vocabulary** — the seam expresses no network, process, syscall, device, or credential restrictions.
 - **Same-world confinement only** — containers, microVMs, and remote execution require replacing capability implementations rather than adding a provider here.
 - **Denial reporting is a stderr dialect** — the seam returns backend signatures instead of a typed runtime denial channel, so consumers that need classification must infer it from the child process's output.
+- **Runner diagnostics are in-band** — exit status plus stderr evidence cannot prove which process wrote a matching line, so a confined child that deliberately mimics its runner can cause an availability/diagnostic false attribution. This cannot bypass confinement; an out-of-band runner-status channel is deferred.
 - **One provider per context** — composing different sandbox mechanisms simultaneously requires a provider-level ladder or separate Cordis contexts; callers choose policy per call, not backend identity.
--- a/packages/sandbox/sandbox/README.zh.md
+++ b/packages/sandbox/sandbox/README.zh.md
@@ -4,7 +4,7 @@

 抽象进程沙箱 seam。负责定义 `ctx.sandbox` 服务契约（[`SandboxProvider`](src/index.ts)）与 harness 共享的限制词汇：`SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`，仅限文件操作）、`SandboxEnforcement`（`full`／`partial`，针对每种内核 ABI）、`SandboxExecutionPolicy`（每次调用的完整模式及工作区根目录）、`SandboxPolicy`（其中受限制的子集），以及故障时拒绝放行的 `SANDBOX_UNAVAILABLE` 错误。它是[能力 seam 拆分](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)的接口包：只依赖 cordis（及 harness 错误基类），绝不依赖后端。

-用一句话概括契约：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；另附所选后端的两个事实：它达到的强制执行完整度，以及拒绝方言（`denialSignatures`，即内核在文件操作被拒绝时打印到 stderr 的子字符串；通过 stderr 推断的消费方会匹配这些字符串，而不是统一的跨后端签名集合）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。
+用一句话概括契约：`ctx.sandbox.confine(argv, policy)` 返回用于 spawn、应当取代调用方原始 argv 的 argv。返回值经过包装，使进程及其派生的所有进程都在限制下运行；还会附带所选后端达到的强制执行完整度、拒绝方言（`denialSignatures`）和结构化 runner 失败证据（`runnerFailureRules`）。没有可用后端时，它会抛出异常，绝不会原样传递 argv 使其不受限制地运行。[核心类型目录](../../../docs/core-data-structures/sandbox.md#wrapped-argv-and-classification-dialects)负责定义分类器的精确结构。

 策略随调用传递，而不属于提供方：两个消费方可以同时按不同策略施加限制（bash 使用 `read-only`，而受限制的子 agent（智能体）保持其状态目录可写）；获批的升权重试只是使用更宽策略发起的新调用。

@@ -39,4 +39,5 @@ sandbox mode "<mode>" is requested but no sandbox backend is usable on this host
 - **文件操作是完整的策略词汇**：该 seam 不表达网络、进程、系统调用、设备或凭据限制。
 - **只支持与宿主共享文件系统和内核的限制**：容器、microVM 与远程执行需要替换能力实现，而不是在此处增加提供方。
 - **拒绝报告是一种 stderr 方言**：该 seam 返回后端签名，而非类型化运行时拒绝通道，因此需要分类的消费方必须从子进程输出推断。
+- **Runner 诊断使用带内通道**：退出状态与 stderr 证据无法证明匹配行由哪个进程写入，因此受限子进程若故意模仿 runner，就可能造成可用性或诊断误归因。这无法绕过约束；带外 runner 状态通道暂缓实现。
 - **每个上下文只有一个提供方**：同时组合不同沙箱机制需要提供方级阶梯或独立 Cordis 上下文；调用方逐调用选择策略，而非后端标识。
--- a/packages/sandbox/sandbox/src/index.ts
+++ b/packages/sandbox/sandbox/src/index.ts
@@ -62,6 +62,22 @@ export interface SandboxPolicy extends SandboxExecutionPolicy {
  mode: ConfinedSandboxMode
 }

+/**
+ * Evidence that identifies a sandbox runner failing before it executes the
+ * wrapped command. A consumer first applies {@link allowedExitCodes} when
+ * present, removes {@link informationalLines} by case-insensitive exact line
+ * equality, then matches {@link fatalSignatures} case-insensitively within
+ * each remaining stderr line. Exit status alone never proves runner failure.
+ */
+export interface RunnerFailureRule {
+  /** Nonzero process exit codes on which this rule may match; omitted permits any nonzero exit. */
+  allowedExitCodes?: readonly number[]
+  /** Non-empty substrings identifying a fatal runner diagnostic on one stderr line. */
+  fatalSignatures: readonly string[]
+  /** Benign stderr lines excluded by exact full-line equality before fatal matching. */
+  informationalLines?: readonly string[]
+}
+
 /**
 * A {@link SandboxProvider.confine} result: the argv to spawn in place of
 * the caller's own, plus the enforcement completeness the selected backend
@@ -82,11 +98,12 @@ export interface ConfinedArgv {
   */
  denialSignatures: readonly string[]
  /**
-   * Case-insensitive signatures for runner failure before command execution.
-   * Consumers check these before denial signatures: runner failure means the
+   * Structured runner-failure evidence rules. Consumers require a matching
+   * fatal stderr line (after informational exclusions) and any rule-specific
+   * exit-code gate before checking denial signatures: runner failure means the
   * command never ran, while denial means confinement worked and blocked it.
   */
-  runnerFailureSignatures: readonly string[]
+  runnerFailureRules: readonly RunnerFailureRule[]
 }

 /**