feat: add bounded read-only operator acceptance preflight

[BunsDev]

Outcome and scope

Implements the actionable operator setup preflight requirement in #199, transferred from #239. References #199 and #239; neither broader issue is closed by this slice.

Adds pnpm acceptance:preflight / node scripts/operator-preflight.mjs: bounded read-only PATH availability checks for Node, pnpm, Git, and tmux; shared architecture normalization; optional --artifact-arch operator declaration; explicit unknown permission and unverified disposable context; separate setup blockers and all 14 not-observed product scenarios.

No permission probes that might prompt, context creation, product/GUI launch, destructive recovery, release download/mount, file inspection, or acceptance claim. Artifact architecture is declared, not observed. Host architecture describes the Node process, not proof of physical hardware under translation. Output includes no personal paths, environment dumps, raw subprocess output, or versions.

Exact subject and validation

Head: ea1dae4fa7c6ee5a451ea93e9e649a7ca590e4bd.

Commands run from the reused implementation worktree:

pnpm vitest --run __tests__/operatorPreflight.test.ts __tests__/operatorAcceptanceManifest.test.ts
node scripts/operator-preflight.mjs --artifact-arch arm64
bash ./scripts/agent-check full
git diff --check

Source-first focused run failed because the preflight module did not yet exist (existing validator: 27 passed). After implementation: 33 focused tests passed. Full gate passed on the exact source subsequently committed at the head above: 5,411 unit/contract tests passed, 11 skipped; separate Beads render suite 221 passed; docs contract/build, TypeScript checks, source smoke, package smoke, deterministic desktop bundles, Rust formatting, 471 Rust tests, and Rust check passed. iOS opt-in gate was not run and is not asserted. No toolchain or dependency pin changes or dependency installation.

Independent read-only code-review agent reviewed the complete implementation delta including new files and reported no significant issues. Maintainer/parent independent review and terminal required exact-head CI remain prerequisites to protected merge. Do not merge as part of this task.

Bounded live observation

The safe CLI exited 0 and produced only the fixed schema. Sanitized result:

{
  "host": {"platform": "macos", "architecture": "aarch64"},
  "artifact": {"architecture": "aarch64", "source": "operator_declared", "compatibility": "matches"},
  "tools": {"node": "available", "pnpm": "available", "git": "available", "tmux": "available"},
  "uiAutomationPermission": "unknown",
  "disposableContext": "unverified",
  "setupBlockers": [],
  "acceptance": "not_observed"
}

All 14 product scenarios in the full report remain not_observed. Limits: four non-login shell lookups, 1,000 ms per tool with SIGKILL timeout, 1,024-byte subprocess buffer ceiling and ignored output, zero retained subprocess bytes, zero file-read bytes, PATH limited to 32,768 characters before passing it to subprocesses. No discovered tool is executed. Only PATH is passed to the lookup shell; no environment is retained in the report.

Exit 0 means no observed setup blockers, not permission, isolation, or acceptance readiness. Exit 1 means observed setup blockers; exit 64 rejects invalid input with a fixed error and no report.

Proof gaps and rollback

Permissions remain unknown; disposable user/repository isolation remains unverified. Artifact identity/digest/actual binary architecture, tool runtime health/versions, GUI behavior, packaged fault injection, iOS, and physical hardware architecture remain unproved. Operator verification is still required under the runbook. No product acceptance is inferred from source gates.

Rollback: revert this commit through a separately reviewed PR; no persistent product state, permission, or migration rollback is needed. No Beads mutations. Existing root Beads dirt and separate iPad UI test dirt were left untouched; the previous GPU branch ref is preserved. Implementation worktree is clean after commit.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
psyche-build-docs	Ready	Preview	Sep 12, 2026 1:12am UTC

[Copilot]

🔵 Needs a closer look

Maintainer review and exact-head CI remain necessary for final approval.

Pull request overview

Adds a bounded, read-only operator acceptance preflight for tool availability, architecture compatibility, and explicit proof gaps.

Changes:

• Adds the acceptance:preflight CLI and package script.
• Shares architecture normalization with acceptance validation.
• Documents limits, blockers, and operator verification requirements.
• Adds focused tests and type declarations.

File summaries

File	Reviewed change
scripts/validate-operator-acceptance.mjs	Exposes shared observations and architecture normalization.
scripts/validate-operator-acceptance.d.mts	Updates validator type declarations.
scripts/operator-preflight.mjs	Implements bounded preflight checks and reporting.
scripts/operator-preflight.d.mts	Declares the preflight API and report schema.
package.json	Adds the acceptance:preflight command.
docs/OPERATOR-ACCEPTANCE-SLICE.md	Documents usage, limits, and proof boundaries.
__tests__/operatorPreflight.test.ts	Tests normalization, bounds, blockers, and invalid input.

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[BunsDev]

Independent final review on exact head ea1dae4fa7c6ee5a451ea93e9e649a7ca590e4bd: no findings. Terminal exact-head checks completed successfully and no unresolved review threads exist. The report deliberately distinguishes declared artifact architecture, unknown UI permission and unverified disposable context from observed tool/setup state; it does not claim runtime/operator acceptance. Proceeding via ordinary protected merge without bypass.