[mast-factory]

Summary

Document why bounded Grok lanes cannot run on Linux hosts lacking Landlock or bubblewrap, including affected Claude Code cloud sessions. Explain the existing child-failed / exit 70 receipt evidence and prohibit substituting devbox or off. Add the single-sentence setup cross-reference and an Unreleased entry.

Closes #56. Implements the approved documentation-only Option C (plan revision 20). No runner, permissions, status, receipt schema, or runtime changes.

Candidate and coordination

• Branch: factory/issue-56; base: main.
• Pushed phase/head: 3f66491e75c5b52a762c8b5c18fdd8f235f19614.
• Only CHANGES.md, plugins/pstack/skills/poteto-mode/references/provider-dispatch.md, and plugins/pstack/skills/setup-pstack/SKILL.md changed.
• Codex default sandbox blocks external pstack lanes; setup should detect and explain it #124 shares the Host and parent prerequisites section; whichever lands second must rebase and keep one list without duplicated notes.

Test plan and actual results

Bun 1.4.0 was installed locally so no CI-equivalent checks were skipped:

Check	Actual result
bun install --frozen-lockfile in scripts package	exit 0
bun run test	exit 0; 159 passed, 0 failed, 653 assertions across 11 files
bun run typecheck	exit 0; three strict TypeScript projects
Parse four Claude/Codex plugin and marketplace JSON manifests	exit 0
PSTACK_STATIC_ONLY=1 bash tests/skill-collision-repro.sh	exit 0
claude plugin validate ./plugins/pstack	exit 0
claude plugin validate ./.claude-plugin/marketplace.json	exit 0
No runner files changed; git diff --check	both exit 0
Install exact candidate with Claude Code 2.1.289 and Codex 0.160.0 plugin CLIs	both marketplace/install/list commands exit 0; version 1.5.0
Compare both installed document trees with candidate and resolve setup relative anchor	exit 0; exact bytes match and anchor resolves in both caches

Outstanding live gate — keep draft

Fresh installed-parent documentation probes were attempted, not skipped:

• Claude Code: exit 1, Not logged in · Please run /login.
• Codex: exit 1, HTTP 401 Unauthorized, missing authentication.

The installed-tree/anchor checks are not a substitute for successful live verification from both authenticated parent surfaces. Required parent transcripts and the exact-head live-gate success remain outstanding. No Landlock-less host or Grok model invocation is required for this docs-only change. Do not merge until both authenticated sessions verify the installed documentation and the exact-head live gate is recorded.

Logs are retained locally under .mastracode/evidence/issue-56/ and are not committed. No credentials or tooling artifacts are committed.

Findings

None

[mergify]

Merge Protections

🟢 All 2 merge protections satisfied — ready to merge.

Show 2 satisfied protections

🟢 Queue ready pull requests

Automatically queue non-draft pull requests targeting main after verify, Unfret, and live-gate pass on the head.

• -draft
• check-success=Unfret
• check-success=live-gate
• check-success=verify

🟢 🚦 Auto-queue

When all merge protections are satisfied and these conditions match, this pull request will be queued automatically.

• -files~=^\.github/
• base = main

[greptile-apps]

Confidence Score: 5/5

[Low risk] Documentation updates for Grok sandbox prerequisites.

No issue in the changed documentation was established; the PR appears safe to merge from this review.

What we checked:

• Setup might miss a sandbox failure: Yes. Setup uses the external runner for Grok's one-turn probe, and that runner passes a bounded sandbox setting.

Summary

This documentation-only PR explains why some Linux hosts, including affected Claude Code cloud sessions, cannot run bounded Grok lanes. It also connects setup failures to the shared guidance without changing runner behavior.

• Names Landlock and bubblewrap as host requirements.
• Explains the existing sandbox-refusal receipt and rules out devbox or off as substitutes.
• Links setup failures to the guidance and adds an Unreleased note.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A["Setup probes Grok"] --> B["grok models"]
  B --> C["Run with bounded sandbox"]
  C -->|Host refuses startup| D["Receipt: child-failed and error.evidence"]

Loading

_{Reviews (1) · Last reviewed commit: "docs(#56): explain why bounded Grok lane..."}

[unfret-eal]

✅ No blocking findings

Light review ran with 1 elected reviewer.

Walkthrough

This docs-only change explains that bounded Grok lanes can't run on Linux hosts missing Landlock or bubblewrap, including some Claude Code cloud sessions, even when `grok models` succeeds. It moves the existing sandbox note into a new "Host and parent prerequisites" section in the provider-dispatch reference. That section explains how such failures appear as `child-failed` (exit 70) with Grok's refusal text in the receipt, and states that Open Pstack never falls back to `devbox` or `off`. Setup's probe step now links to that section, and CHANGES.md gets an Unreleased entry. Runner behavior is unchanged. The author keeps it in draft pending authenticated live verification from both Claude Code and Codex. The author also notes a likely section overlap with #124.

Area	What changes
Provider dispatch docs	New Host and parent prerequisites section covering the parent-sandbox note plus Linux Landlock/bwrap requirements, exit-70 evidence, and the no-bypass rule.
Setup skill	Adds one sentence pointing failed Grok sandbox probes to the new section while keeping the active configuration unchanged.
Changelog	Adds an Unreleased entry for #56.

Details

Lane / stage	Model	Effort	Outcome	Duration
focal-gpt-6.1-sol-xhigh / review	openai/gpt-6.1-sol (reported model unavailable)	xhigh	succeeded	4 min 30 s
focal-gpt-6.1-sol-xhigh / reread	openai/gpt-6.1-sol (reported model unavailable)	xhigh	succeeded	3 min 40 s

First review of this pull request.
1 reviewer finished.
Commit 3f66491.
Check run.
Run: GET /unfret/run/panel:3f66491e75c5b52a762c8b5c18fdd8f235f19614:vGp9JRwnJJr:DMcxxz7ec5Q.

_{@unfret review · @unfret status · @unfret help}

[unfret-eal]

✅ No blocking findings
Check

[ericlitman]

Live test, Codex half (head 3f66491)

Result: the Codex half passes. The Claude half has not run yet, so I have not set the live-gate status.

• Installed version: Open Pstack 1.5.0 from ref 3f66491e75c5b52a762c8b5c18fdd8f235f19614. I installed it with codex plugin marketplace add … --ref <sha> and codex plugin add pstack@open-pstack into a separate, throwaway CODEX_HOME, with Codex CLI 0.160.0.
  • SHA-256 of the installed provider-dispatch.md and setup-pstack/SKILL.md matches the candidate commit.
• Surface: a fresh interactive Codex TUI session (GPT-6.1 Sol) in that CODEX_HOME.
• Action: I asked Codex to read the installed reference and setup skill from its plugin cache, not a source checkout, and to quote the new note and the cross-reference. I also asked whether the link target resolves. It ran no probes and wrote no configuration.
• Observed:
  • Codex reported plugin 1.5.0 and the installed paths.
  • It quoted the "Host and parent prerequisites" note. The note covers Linux Landlock plus bubblewrap, affected Claude Code cloud sessions, child-failed/70 with Grok's refusal text in error.evidence, and a refusal to substitute devbox or off.
  • It quoted setup step 5's cross-reference. It confirmed that ../poteto-mode/references/provider-dispatch.md#host-and-parent-prerequisites resolves to the installed ### Host and parent prerequisites heading at line 72.

Still pending: the same check from a Claude Code parent. It needs a logged-in Claude Code CLI.

[mast-factory]

Agent coordination for #124: PR #129 preserves this change’s Linux Grok Landlock/bubblewrap guidance in the single shared "Host and parent prerequisites" list, alongside Codex permission/setup guidance. Both PRs overlap provider-dispatch.md; whichever lands second must rebase on the first and preserve the combined list. #129’s candidate live matrix is explicitly pending operator execution after review; any rebase requires fresh exact-head evidence.

[ericlitman]

Live test, Claude Code half, and live-gate (head 3f66491)

Result: the Claude Code half passes. The Codex half passed earlier (evidence). Both harnesses have now passed on this exact head, so I set live-gate to success on 3f66491e75c5b52a762c8b5c18fdd8f235f19614.

• Installed version: Claude Code 2.1.289. The candidate plugin was loaded from a detached checkout of exactly 3f66491e75c5b52a762c8b5c18fdd8f235f19614 with claude --plugin-dir <checkout>/plugins/pstack. The installed pstack was turned off for the session with --settings.
• Surface: an interactive Claude Code session (Opus 5.5) in a fresh empty Git directory.
• Action: I asked Claude to read the candidate plugin's provider-dispatch.md and setup-pstack/SKILL.md, quote the new note and the cross-reference, and check that the link resolves. It ran no probes and wrote no configuration.
• Observed:
  • Claude quoted "Host and parent prerequisites" at provider-dispatch.md:72-75. The note covers Linux Landlock plus bubblewrap, affected Claude Code cloud sessions, child-failed (exit 70) with Grok's refusal text in error.evidence, and a refusal to substitute devbox or off.
  • It quoted the step-5 cross-reference at SKILL.md:54.
  • It confirmed that ../poteto-mode/references/provider-dispatch.md#host-and-parent-prerequisites resolves to the only heading with that slug.

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-10-04 11:06 UTC · Rule: default · triggered by merge protections
• ✅ Checks skipped · PR is already up-to-date
• ✅ Merged — 2026-10-04 11:11 UTC · at 7bcf56968e5ac20e61457d47ee415ae4bc20e077 · merge

This pull request spent 5 minutes 11 seconds in the queue, including 1 second running CI.

Required conditions to merge

• github-review-approved [🛡 GitHub repository ruleset rule Protect main]
  • docs: explain host prerequisites for bounded Grok lanes [#56] #125
• all of [🛡 Merge Protections rule Queue ready pull requests]:
  • -draft
    • docs: explain host prerequisites for bounded Grok lanes [#56] #125
  • check-success=Unfret
  • check-success=live-gate
  • check-success=verify
• any of [🛡 GitHub repository ruleset rule Protect main]:
  • check-success = @github-actions/verify
  • check-neutral = @github-actions/verify
  • check-skipped = @github-actions/verify
• any of [🛡 GitHub repository ruleset rule Protect main]:
  • check-success = live-gate
  • check-neutral = live-gate
  • check-skipped = live-gate
• any of [🛡 GitHub repository ruleset rule Review gate]:
  • check-success = @unfret-eal/Unfret
  • check-neutral = @unfret-eal/Unfret
  • check-skipped = @unfret-eal/Unfret