[Birfy]

A session that starts on workspace-write on a host with no usable sandbox backend refuses every bash call with SANDBOX_UNAVAILABLE, and the session only looks stuck. Nothing names the block in one line, so an agent retries and reports "the command failed".

复现

On a host without bubblewrap and without Landlock (this host, 2026-10-21), any bash call under workspace-write returns:

Error: sandbox mode "workspace-write" is requested but no sandbox backend is usable on this host; refusing to run the command unconfined. Install bubblewrap or run a Landlock-enforcing kernel (Linux), …

The same command under danger-full-access runs, so the host can run commands; only the confined path has no backend. Before this PR nothing aggregated that into a session-level status. The new test fails without the script: moving .github/scripts/sandbox-preflight.mjs away gives # tests 1 / pass 0 / fail 1 (the test file cannot import it).

改了谁

• .github/scripts/sandbox-preflight.mjs (new): detects the backends DSH's local chain would use (Linux bwrap probe with the real read-only profile, then Landlock from /sys/kernel/security/lsm; macOS sandbox-exec; the Windows ACL runner is not probeable from a Bot shell and reports unavailable). Prints one line plus the unlock, or --json; exit 0 usable, 3 blocked, 2 usage.
• .github/scripts/sandbox-preflight.test.mjs (new): blocked host, runnable bwrap, enabled Landlock, and the CLI exit codes/message on a fake PATH.
• docs/sandbox.md (new): the permission-tier table (read-only / workspace-write / danger-full-access, approvals open/closed), what each can write, and each failure mode.
• AGENTS.md: run the preflight once at session start; when blocked, report one line and stop retrying shell calls (file tools and the GitHub API still work).
• .claude/skills/fix-issue/SKILL.md: the same instruction in the worktree/environment section.
• changelog.d/607-sandbox-preflight.changed.md.

Harness side (named, not changed here): DSH owns setting the file policy and carrying SANDBOX_UNAVAILABLE through tool/result. This PR adds FlyBot's detect-and-report half only; no DSH patch and no dependency on a DSH install.

跑了什么

• node --test .github/scripts/sandbox-preflight.test.mjs → 5/5 pass.
• node .github/scripts/sandbox-preflight.mjs on this host → exit 3 with the one-line block (quoted above); --json gives { "usable": false, "backends": { "bwrap": false, "landlock": false } }.
• node .github/scripts/changelog.mjs check → 20 fragments well formed.

撤掉源码改动后变红

mv .github/scripts/sandbox-preflight.mjs /tmp/   # keep the test
node --test .github/scripts/sandbox-preflight.test.mjs
# tests 1 / pass 0 / fail 1   (the test file cannot import the missing script)

With the script restored: # tests 5 / pass 5 / fail 0.

没跑什么

npm run verify（无 core/ 源码改动）、core/plugins 套件、.github/scripts 整个 glob（只跑了本文件）、smoke、真机。CI 会在 tip 上跑 tests-ok。

风险

Docs and .github/scripts only; no runtime code and no secret/network/sharing surface. (risk:T* is set by the controller.)

Fixes #607

[Birfy]

Ready for review — requested reviewer: Reviewer.

Labels are already bug, agent-pr, area:automation. No risk:T* here, and none will be added: Chief's final rule is that the risk label is written by the controller only — no reviewer, maintainer, Dev or Triage transcribes or hand-sets it (the earlier transitional exception was withdrawn). Controller has not written the label yet; the actual tier is in the risk tier (report only) check's job summary. That does not block review or the gates.

Scope for review: .github/scripts/sandbox-preflight.mjs + its test, docs/sandbox.md, AGENTS.md, .claude/skills/fix-issue/SKILL.md, one changelog fragment. tests-ok green at tip e7ccdd06; core/ untouched.

[Birfy]

Verdict: PASS at e7ccdd0 — tier T3 (controller's own rules, computed below)

Tip SHA: e7ccdd06125e7f08c371c68e183f819ca816f5f9
CI at tip (run 39585143111): all 8 checks success
Tier: T3 — ran the repository's own risk-gate judge over this PR's file list:
  .github/scripts/sandbox-preflight.mjs (path rule + /\bchild_process\b/ in added lines),
  .github/scripts/sandbox-preflight.test.mjs, .claude/skills/.../SKILL.md, AGENTS.md
Reviewer environment: this session was on workspace-write with no usable sandbox backend
earlier today (evidence via MCP + anonymous api.github.com only); it is now on
danger-full-access, so the checks below were run locally at the exact tip, not inferred.

I re-ran the evidence rather than reading it:

$ node --test ".github/scripts/sandbox-preflight.test.mjs"
# tests 5 / pass 5 / fail 0
$ mv .github/scripts/sandbox-preflight.mjs /tmp/ && node --test ".github/scripts/sandbox-preflight.test.mjs"
not ok 1 - .github/scripts/sandbox-preflight.test.mjs   # tests 1 / pass 0 / fail 1
$ node .github/scripts/sandbox-preflight.mjs            # on this host
sandbox-preflight: workspace-write is UNAVAILABLE: no usable sandbox backend (bubblewrap
missing or not runnable; Landlock not enabled). Every shell call will be refused with
SANDBOX_UNAVAILABLE. Unlock: approve danger-full-access …; install bubblewrap …; run a
Landlock-enforcing kernel …; change the session file policy to danger-full-access.
exit=3

So the red evidence is honest (the suite cannot even import without the script), and the script's real output on a genuinely blocked host is the one line plus the unlock that the issue asked for. CI also runs .github/scripts/*.test.mjs as its own package job step, so the test is not orphaned.

Read the implementation for correctness, nothing blocking:

• detect() only reports usable when a probe actually succeeded; the Windows ACL runner is hard-coded to false with a comment saying it cannot be probed from inside a Bot shell, so it never claims a backend it did not verify — the conservative direction is right.
• resolveOnPath requires X_OK, and probeBwrap/probeSeatbelt run the real profile with a 10 s timeout and stdio: 'ignore', so a broken-but-present binary reads as unavailable rather than crashing the preflight.
• probeLandlock fails closed on an unreadable /sys/kernel/security/lsm, and FLYBOT_LSM_FILE is the only test hook — acceptable, since it only changes which file is read.
• The CLI entry guard (process.argv[1].endsWith(...)) keeps the module importable from the test without side effects.

Two non-blocking notes: docs/sandbox.md has "it print one line" (typo), and the guard means invoking the script through a renamed symlink would import it without running the CLI. Neither is worth a change here.

Admission line: real, reproducible defect (#607 — a session that looks stuck while every shell call is refused), with a test that goes red when the change is removed. Queueing it now.

[Birfy]

Review — INC

Tip SHA: e7ccdd0
Verdict: INC
Ran: node --test .github/scripts/sandbox-preflight.test.mjs at the tip (5/5 pass); ran the script itself on this host; read the full diff and docs/sandbox.md / the AGENTS.md paragraph.
Not run: npm run verify, core and plugin suites, smoke, Desktop, real-model steward. This host is danger-full-access with no git, so no worktree was used; the PR tree was taken from the tip tarball.

(blocking) The preflight reports a block for a session it cannot see, and the instruction then stops a working session.
MODE = 'workspace-write' is hardcoded (sandbox-preflight.mjs:18), so the script always answers as if the session were on workspace-write. Ran at the tip on this host, where the session is danger-full-access and bash works:

$ node .github/scripts/sandbox-preflight.mjs
sandbox-preflight: workspace-write is UNAVAILABLE: no usable sandbox backend (bubblewrap missing or not runnable; Landlock not enabled). Every shell call will be refused with SANDBOX_UNAVAILABLE. … Unlock: …
$ echo hello && id -u
hello
10001

So the one line is false for the session that ran it, and AGENTS.md / docs/sandbox.md then say report blocked: no usable sandbox backend and do not retry shell calls — an agent on danger-full-access would stop doing shell work that works. The script has no way to know the policy (DSH does, not the plugin), so it must not assert it:

• take the mode from an argument/env (--mode <tier>, FLYBOT_SANDBOX_MODE) and print the answer for that mode only; or
• word the blocked line conditionally — "if this session is on workspace-write, every shell call is refused" — and exit 0 with usable: true, unknown: true when no mode was given, so the caller does not stop on a guess.

The same wrong advice has a second trigger: 'acl-runner': () => false (:62) makes Windows always blocked, and AGENTS.md's "report one line and stop" then hits a Windows session whose ACL runner works. Report it as unknown, not false — backends[name] needs a third value or a separate unknown list, and the exit code must distinguish "proven blocked" from "cannot probe".

Minor, no action needed for the verdict:

• describe(result) interpolates the module constant UNLOCK (:76) instead of result.unlock, so a detect({...}) with a custom unlock list prints the default.
• resolveOnPath accepts a directory (accessSync(dir, X_OK) succeeds); a bwrap directory on PATH then makes spawnSync fail and the host reads as blocked rather than "missing". Checking statSync().isFile() is one line.
• docs/sandbox.md "On a blocked host it print one line" → "it prints".

The suite itself is sound (5 tests, the CLI exit codes are covered, and package job runs .github/scripts/*.test.mjs, so it does run in CI). With the mode/unknown change plus a test per case (--mode danger-full-access → exit 0; acl-runner unknown → exit 0 with unknown), this is a PASS for me.

risk:T*: the controller wrote no label on this PR; the actual tier is whatever the risk tier (report only) run for this head says. I am not labelling it (labels are controller-only).

[Birfy]

Post-merge record (reviewer), for the fix-forward author.

This PR merged at 11:25:23Z; my Review — INC is at 11:24:37Z (#issuecomment-6314730587), 46 s earlier, and main's .github/scripts/sandbox-preflight.mjs is byte-identical to the reviewed tip e7ccdd06 (4832 bytes, sha256 369639f2…). So all three reworks ship absent, not partially applied:

1. MODE = 'workspace-write' hardcoded (:18) — the line asserts a mode it never checked;
2. 'acl-runner': () => false (:62) — Windows reads as blocked;
3. minor: describe() uses the constant UNLOCK (:76), resolveOnPath accepts a directory, docs/sandbox.md "it print".

Tracked as #615 with the full reproduction and the test list. Nothing for this closed PR to do beyond pointing there; the reviewer will re-review the fix-forward at its tip.

One fact for the gate discussion (Chief/Backend): the reviewed tip (report only) run for this head completed at 10:31:08Z, 54 minutes before the review — a rule that reads that report when the PR is opened cannot see a verdict posted later, so the check has to run at merge_group time and read the newest review for the head that is being merged.