Skip to content

fix(sandbox): keep the scratch window when the host empties the stand-in roots - #31730

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/sandbox-private-stand-in-stage
Nov 7, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/sandbox-private-stand-in-stage

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A sandboxed agent on Linux keeps its scratch directory and $TMPDIR for its whole run, even when the host cleans up the user's shared temp roots.

On a host where the user has no logind session or linger, every running sandbox can lose its scratch window at the same moment. From then on every shell command fails. On the Claude Code backend it reads task output swap refused (tasks dir moved or linked), and the gateway log shows ENOENT ... mkdir '<scratch>/<session>/claude-<uid>'.

Why it matters

Every sandboxed session on such a host breaks mid-task, dashboard chats and background runtimes alike, and keeps breaking every few minutes when a cron session opens and closes. The agent's work in progress is cut off, and nothing in the product says why.

Not a goal

  • Does not change which paths are hidden, sealed or exposed in the sandbox, or any refusal.
  • Does not change the order of the stand-in root candidates (/run/user/$UID, then /dev/shm).
  • Does not change the janitor that reclaims stale bind sources.

What changed (motivation → approach → change)

The launcher creates the empty stand-ins it binds over hidden directories under a host-shared root (/run/user/$UID, else /dev/shm). The scratch root is one of those masks, and the spawn's scratch directory is mounted back inside its stand-in as a private window. With RemoveIPC=yes (the default), systemd-logind deletes the uid's /dev/shm entries when the user's last session closes, directories included. Deleting the stand-in removes the window's mount point, which detaches the window inside the running sandbox.

Step What the launcher does now
Before the masks stage_stand_ins_privately mounts a tmpfs on one stage directory in its own mount namespace and creates every stand-in through a descriptor on that tmpfs root
After the masks retire_stand_in_stage detaches the stage and removes its empty host directory; the masks keep the tmpfs alive
tmpfs refused the stand-ins stay on the host root, as before, with a warning

The host never sees a stand-in, so nothing it deletes can reach a window. The new real-sandbox test runs in the namespace-sandbox CI job (ci.yml), and docs/system-specs/modules/security.md describes the stage.

Backwards compatibility

Compatible: every mask, seal and window is placed exactly as before, from the same plan; only where the empty stand-ins live changes, and a host that refuses the tmpfs keeps the old location.

Removes nothing: no path, record, key or function is taken away; the stand-ins move off the host, which only stops leaving kirocrew_sb_* entries there.

Tests

  • test/test_stand_in_stage_real_sandbox.py: under the real sandbox (every tier), the test deletes every entry the launcher could have left on the host roots for the child's pid, children first, the way logind does. The child must still create a directory in its window and read back what it wrote before. The test also asserts that no such host entries exist.
  • test/test_sandbox_stand_in_private_stage.py: the stage mounts a nosuid,nodev tmpfs and stand-ins land in it; retire detaches it and removes the host directory; a refused tmpfs, a stage that is not a fresh mount, and a host root that vanishes after the mount all keep the host root without ending the launch; a stage that will not detach stays with a warning.
  • test/test_sandbox_launcher_program.py, test/test_sandbox_mount_checked.py: the stage order, the stand-in and mount counts, and the stage's checked raw tmpfs mount. test/test_sandbox_launcher_symlinked_protected_name.py counts the stage's two opens as launcher-created directories, not protected names.

Proof: PROVEN test/test_sandbox_launcher_program.py::test_the_mount_count_covers_every_site, test/test_sandbox_launcher_program.py::test_the_stand_in_count_covers_every_create, test/test_sandbox_launcher_program.py::test_a_replaced_stand_in_root_moves_the_stand_ins_and_keeps_every_mask[create-1], test/test_sandbox_launcher_program.py::test_a_replaced_stand_in_root_moves_the_stand_ins_and_keeps_every_mask[create-2], test/test_sandbox_launcher_program.py::test_a_replaced_stand_in_root_moves_the_stand_ins_and_keeps_every_mask[create-3] (head 661c438)

Manual verification

The real-sandbox test is the end-to-end check. It runs only where unprivileged user namespaces are allowed, so it runs in the namespace-sandbox CI job and not on the author's host.

Related Issues

Closes #31716

Sibling sweep

Swept: git grep -n "stand_in_roots|tempfile.mkdtemp(dir=root" -- src/
Siblings: none -- every stand-in is created through _on_stand_in_root in src/kiro_crew/sandbox_launcher_program.py, which this PR stages

Pattern harvest

Not generalizable: the only host-shared mount source in the product is the launcher's stand-in root, which this PR moves into the sandbox's own namespace.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 6, 2026 19:45
@bolichen97
bolichen97 requested a review from Zedmor November 6, 2026 19:45
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/sandbox_launcher_program.py

  • No reasoning template for 2afccdb yet.

How to clear this check:

  1. The PR author posts the template below as a PR comment, with
    every field filled (N/A needs a reason). Keep the
    Head commit line: it must name the current head SHA.
  2. The check turns green within a minute, with no push.
  3. A new push resets this check: post it again for the new head.

Only the author's comment counts this way. A reviewer can instead
paste the filled template into an "Approve" review on this head.
Merging still needs a reviewer's approval.

## Sensitive change review
- Head commit: 2afccdb30cf1980cf01ba8956f1d0d7aeb2ce3d8
- What rule changed:
- Before -> after (what was allowed/blocked, now):
- Worst case if wrong (breaks commands / leaks secret / locks user out):
- Evidence checked (which sandbox result proves it):
- No regression:
  - Tools still work (which tools/commands were run, result):
  - Backward compatible (old config / old data / old callers still work, how checked):
  - Existing tests (which suites passed on this head):
- How to undo:

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 6, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 20:13
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 661c438beebe6787dc29237d614db46d8bb5e677 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

No design-level concerns. Each mask's bind keeps the tmpfs alive on its own, and the windows sit inside stand-ins the host cannot see, so logind removing an entry on the host can no longer detach a window. A refused tmpfs falls back to the old host root.

[DESIGN-REVIEWED] 661c438

Description read

[DESCRIPTION-READ] bc86fd9077f0a4d0198e3d1487ba5155099ac75c97b618a82410daaaae2be8a8

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 661c438beebe6787dc29237d614db46d8bb5e677 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 661c438beebe6787dc29237d614db46d8bb5e677 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Every item addresses the scratch-window loss reported in #31716. The fix removes the cause, which is stand-ins living on host-shared roots, and every stand-in create goes through the one staged path.

What this change ships

Inventory (6 items) — 6 justified

Intent: a sandboxed Linux agent keeps its scratch directory and $TMPDIR for its whole run, even when logind empties /run/user/$UID or /dev/shm. This is a FIX.

  1. Stand-ins are now created on a tmpfs that exists only in the sandbox's own namespace, so the host cannot delete them. — justified
  2. Once the masks are placed, the stage is detached and its empty host directory removed, so no kirocrew_sb_* entry is left behind. — justified
  3. A host that refuses the tmpfs keeps the old host-root location and prints a stderr warning. — justified
  4. A real-sandbox test is added to the namespace-sandbox CI job. — justified
  5. The security spec gains a paragraph describing the stage. — justified
  6. Two new launcher stage functions are added to the facade inventory, each with one consumer, run_child. — justified

Sibling count: _stand_in_mkdtemp( has 6 call sites under sandbox_launcher_parts/mask_stages.py, and all of them now resolve through the staged tmpfs_src. I found no other way a stand-in reaches a host root.

[FIRST-PRINCIPLES-REVIEWED] 661c438

Description read

[DESCRIPTION-READ] 586ac6a8173e17c64b32541a835406a495256e6f314b429a9cb878a878bc2804

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 661c438beebe6787dc29237d614db46d8bb5e677 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 661c438

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 661c438beebe6787dc29237d614db46d8bb5e677 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 661c438beebe6787dc29237d614db46d8bb5e677 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 661c438

Verdict parsed from the review's SHA-scoped output markers for commit 661c438beebe6787dc29237d614db46d8bb5e677.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 661c438beebe6787dc29237d614db46d8bb5e677 false-positive: <reason, 20 to 500 characters>

@bolichen97

Copy link
Copy Markdown
Contributor Author

Both backend reds on this head are main's, not this PR's: test_security_gate_liveness.py::test_the_package_stays_within_its_line_budget (fix in #31625) and test_pull_request_target_allowlist.py::test_only_the_allowed_workflows_use_pull_request_target (tracked in #31771, from f60c0ea). This PR touches neither file; it will rebase once those land.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 6, 2026
@bolichen97
bolichen97 force-pushed the fix/sandbox-private-stand-in-stage branch from 014d0b0 to 691d093 Compare November 6, 2026 21:38
@bolichen97

Copy link
Copy Markdown
Contributor Author

macOS Backend Tests (5, 7) on 014d0b0 were this PR's: the new stage opened its pin with os.O_PATH, which macOS lacks, and tests that drive run_child there hit it. Fixed in 691d093 by using the module's _O_PATH fallback; the two node ids pass with os.O_PATH removed. Rebased onto main, which now carries #31625. The pull_request_target red is main's (#31771).

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 6, 2026
@bolichen97
bolichen97 force-pushed the fix/sandbox-private-stand-in-stage branch from 691d093 to 2afccdb Compare November 6, 2026 22:25
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 6, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Backend Tests (Windows) (7) on 691d093 was this PR's: test_sandbox_launcher_symlinked_protected_name.py::test_every_protected_name_resolution_takes_a_no_follow_first_look flagged the stage's two _O_PATH opens. Both open the stage directory the launcher has just created, not a protected name. Fixed in 2afccdb by naming that site in the scan's exemptions. The AI review lanes on 691d093 failed on an installation API rate limit before reviewing, and re-run on this head.

…-in roots

The namespace launcher created every mask stand-in directly under a
host-shared root (/run/user/$UID or /dev/shm). On a host where the user
has no login session, systemd-logind's RemoveIPC=yes deletes the uid's
/dev/shm entries at the next session close, directories included.
Deleting a stand-in removed the private-window mount points inside it,
which detached the scratch window in the running sandbox, so $TMPDIR
vanished and every create under it failed with ENOENT.

The launcher now mounts a tmpfs on one stage directory in its own mount
namespace and creates every stand-in inside it through a descriptor on
the tmpfs root. Once the masks are placed it detaches the stage and
removes the empty host directory. A refused tmpfs mount keeps the old
host-root behaviour with a warning.
@bolichen97
bolichen97 force-pushed the fix/sandbox-private-stand-in-stage branch from 2afccdb to 661c438 Compare November 7, 2026 01:01
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in .github/workflows/, docs/system-specs/modules/ and src/kiro_crew/ (same-directory overlap only, no shared file) since this head's CI ran (7c364bc -> current origin/main). The previous head's CI run was cancelled after two Windows shards sat queued on their runner for over two hours. Head is now 661c438; the sandbox-related tests pass locally and CI is re-running.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 7, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved for the on-call. Review lanes pass on 661c438, no conflict, no open change request.

@KiroCrewCaptain
KiroCrewCaptain merged commit 782fcbd into main Nov 7, 2026
102 of 105 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/sandbox-private-stand-in-stage branch November 7, 2026 01:55
buluoray added a commit that referenced this pull request Nov 8, 2026
…-in roots (#31730)

The namespace launcher created every mask stand-in directly under a
host-shared root (/run/user/$UID or /dev/shm). On a host where the user
has no login session, systemd-logind's RemoveIPC=yes deletes the uid's
/dev/shm entries at the next session close, directories included.
Deleting a stand-in removed the private-window mount points inside it,
which detached the scratch window in the running sandbox, so $TMPDIR
vanished and every create under it failed with ENOENT.

The launcher now mounts a tmpfs on one stage directory in its own mount
namespace and creates every stand-in inside it through a descriptor on
the tmpfs root. Once the masks are placed it detaches the stage and
removes the empty host directory. A refused tmpfs mount keeps the old
host-root behaviour with a warning.

Co-authored-by: w <w@k.local>
(cherry picked from commit 782fcbd)

Originally authored on main by Bolin Chen (bolichen97); authored here with the public identity because the commit guard refuses the original address.
buluoray added a commit that referenced this pull request Nov 8, 2026
…-in roots (#31730)

The namespace launcher created every mask stand-in directly under a
host-shared root (/run/user/$UID or /dev/shm). On a host where the user
has no login session, systemd-logind's RemoveIPC=yes deletes the uid's
/dev/shm entries at the next session close, directories included.
Deleting a stand-in removed the private-window mount points inside it,
which detached the scratch window in the running sandbox, so $TMPDIR
vanished and every create under it failed with ENOENT.

The launcher now mounts a tmpfs on one stage directory in its own mount
namespace and creates every stand-in inside it through a descriptor on
the tmpfs root. Once the masks are placed it detaches the stage and
removes the empty host directory. A refused tmpfs mount keeps the old
host-root behaviour with a warning.

Co-authored-by: w <w@k.local>
(cherry picked from commit 782fcbd)

Originally authored on main by Bolin Chen (bolichen97); authored here with the public identity because the commit guard refuses the original address.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Sandbox: a running agent loses its scratch window when logind empties /dev/shm

2 participants