Skip to content

fix(sandbox): hand the launcher one name per crew directory on a symlinked home - #15729

Merged
chenmingwei23 merged 1 commit into
mainfrom
fix/sandbox-ancestor-mask-by-identity
Oct 1, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
fix/sandbox-ancestor-mask-by-identity

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A gateway on a host whose home directory is a symlink verifies Kiro CLI again, so the model list and the account balance load after a restart, and the launcher stops being handed two names for one crew directory.

Since #15252 landed, every Kiro CLI readiness probe on such a host (/home/u -> /mnt/home/u) is refused by the sandbox launcher:

sandbox: BLOCKED -- cannot pin /mnt/home/u/.kirocrew/diag to mask it: the object a pass established at this name has vanished (it is absent) ...

The gateway logs this every 30 s, /api/models and the balance endpoint come back empty, and the dashboard shows "Failed to load" in both places.

Why it matters

Any developer host with a symlinked home loses model selection and account display entirely on the first gateway restart after upgrading. There is no workaround short of lowering the sandbox level. The same shape -- two names for one directory, records kept per name -- is what broke every agent spawn in #13715 and what #15252 patched one branch of; without removing the duplicate at the source, the next per-name record added to the launcher breaks these hosts again.

Not a goal

  • The macOS seatbelt builder: /Users is not conventionally a link, and that builder is left as it is.
  • The .kiro/crew -> .kirocrew alias layout on a host whose home is NOT a link: both prefixes then reach the data home and the fold collapses them too, but no new test pins that layout.
  • Any change to the file loop, the window loop, or _covered_by_own_mask's contract.

What changed (motivation → approach → change)

Symptom: the probe refuses as above. Root cause: the launcher keeps every record per NAME -- the occupant a pre-spawn pass saw (MASK_OCCUPANTS), the stand-in a loop placed (_MASKED_NAMES), the window it opened (_BOUND_WINDOWS) -- and compares each against the filesystem by identity. The tier lists spell every crew leaf under $HOME/<prefix>; the passes spell it under config_dir(), which is resolved. Under a symlinked home those are two names for one directory. Here the directory loop masked the data home once per spelling, the second bind moved the resolved name onto a stand-in the record for it did not name, the file loop found diag absent beneath it, and _covered_by_own_mask read the disagreement as a vanished object.

One change, at the source. namespace_argv decides once per crew root, beside the passes that already stat those roots, which $HOME-joined roots are another NAME for the data home (_crew_home_alias_roots, one path resolution per root: the root's components resolve to the canonical path -- resolution rather than (st_dev, st_ino) identity, because a bind mount of the data home at the alias shares the identity yet is a second mount on which a mask placed at the canonical path does not appear, so it keeps its own entry; GPT F1 on ad1c2d9896), and _build_launcher_script folds every path under such a root onto the resolved spelling before emitting any list -- hidden, read-only, files, carve-outs, windows, writable, exposures, required targets and the occupant map (_fold_crew_home_alias). Pure string work in the builder, so it still makes no filesystem call (test_the_builder_does_not_stat_the_hidden_paths holds). A tier entry with no relocated twin (.vault) is respelled rather than dropped, so no rule is lost; a root string-equal to the data home is no alias and is left alone; a genuinely relocated home (KIROCREW_HOME=/srv/crew) keeps its own rule. The fold is decided in the producer and acted on in the child, and the home link that makes the two spellings one directory is a name a writer could re-aim in between: each alias travels with the (st_dev, st_ino) it rested on (CREW_HOME_ALIASES), and the launcher checks every alias ahead of the first hiding mount: the canonical spelling must still hold the recorded (st_dev, st_ino) (a fresh directory swapped in under the canonical name would take the folded masks while the original sat unmasked wherever it went), and the alias must still RESOLVE to where the canonical path resolves (both sides resolved: the canonical is the passes' spelling and on a default data home is itself the ~/.kiro/crew -> ~/.kirocrew link; against the raw string every spawn on that layout would be refused, GPT/Opus/FP on 51cbc2ed58) -- resolution, not identity, at both launcher gates (GPT F1 on 58bf81f0c5), because a second mount of the data home shares the identity under another name and carries none of the masks placed on the canonical entries, so identity would pass an alias re-aimed at such a mount. That read runs before the mounts, and a link re-aimed right after it holds until the masks land (GPT F1 on 3c81a4fbb4), so once every hiding mount is placed the launcher resolves each alias once more and refuses unless it still names the canonical path -- an alias whose components lead there reads the masks exactly as the canonical does; a re-aimed alias leads somewhere unmasked.

The launcher gains no skip for a second spelling. An earlier revision of this PR let _pin_mount_path accept a name with no carried expectation whose object was a directory stand-in in _OWN_STAND_INS; a stand-in reached at a name no pass vouched for is not evidence that the name is another spelling of anything, and accepting it by membership alone would let a writer who can reach the shared-temp fallback park a registered stand-in on a later credential path and have its mask skipped (GPT F1 on 67c2bfaef0). Handed two spellings, the launcher refuses exactly as before this PR; the fold is what makes that input unreachable.

Tests: _run in test_sandbox_mount_pinned_target.py takes list and libc overrides; _CoveringLibc emulates a directory bind by hiding its target (rename-over on one filesystem), which is what makes the absent branches reachable in a test at all -- the recording stand-in leaves every leaf visible, which is why #15252's gap was not caught. test_a_data_home_handed_to_the_launcher_under_two_spellings_is_refused drives the loops with the duplicate lists the builder used to emit and pins the refusal those lists produce, so the reproduction stays on record. New test_sandbox_symlinked_home_launcher.py drives the real pass and builder under a symlinked home and pins the fold: one spelling per directory in SENSITIVE_DIRS, the probe's three spellings folded to one, the carried leaf identity under a listed name, a relocated home still listed, a bind-mounted data home sharing the identity but not folded, the whole hiding region running to the end against the script those producers write for such a host, the alias carried with its identity, a plain home folding nothing, a home link re-aimed after the fold refusing the spawn with nothing mounted, a data home swapped under a still-true alias refusing on the canonical spelling, an alias re-aimed between the first read and the mounts refusing on the post-mount read, an alias re-aimed at a second mount sharing the data home's identity refusing at both gates, the legacy-link canonical under a symlinked home passing both gates on an untouched filesystem and refusing once the alias is re-aimed, and the post-mount read pinned after the last hiding mount.

Backwards compatibility

Compatible: a host whose $HOME crew roots are not the data home gets byte-identical lists (_crew_home_alias_roots returns nothing, the fold is the identity). On a symlinked home the lists shrink to one spelling per directory; every directory masked before is masked after, under the spelling the pre-spawn passes already use, and a carve-out or window named under the alias spelling is folded the same way so it still lifts or re-opens what it asked for.

Tests

  • test_a_data_home_listed_under_two_spellings_is_masked_once: red on main (has vanished (it is absent)), green with commit 1; red again when only the pin branch is knocked out.
  • test_sandbox_symlinked_home_launcher.py: test_the_probes_home_spellings_fold_onto_the_data_home and test_the_launcher_is_handed_one_spelling_per_directory are red with commit 1 alone, green with commit 2.
  • All 41 test/test_sandbox*.py files + test_kiro_prerequisite*.py + test_cron_apps_secret_mask.py: 2495 passed, 7 skipped. The 13 other test files that touch the builder or namespace_argv: 1614 passed, 9 skipped.
  • black, isort, flake8, mypy (Success: no issues found), comment-history gate: clean.

Manual verification

The probe launcher the affected host actually generates (symlinked home, 177 SENSITIVE_DIRS before the fold, occupant recorded for diag under the resolved spelling) was rebuilt from this branch and its hiding loops replayed with the covering bind: the unfixed script refuses with the live message; with commit 1 it runs to the end with both home spellings recorded against one stand-in; with commit 2 the data home and diag each appear once, under the resolved spelling, and it runs to the end.

Screenshots / video

N/A — no UI change.

Related Issues

Follow-up to #15252 and #13715.

Pattern harvest

Rule candidate: review-prompt
Pattern: "a producer that lists filesystem objects by path for a consumer that keeps per-name records must emit one name per object; two spellings of one directory make every identity check read the second as a swap"

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • 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

Contribution License Agreement

@chenmingwei23
chenmingwei23 requested a review from a team as a code owner October 1, 2026 05:44
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 1, 2026
@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 6fe2b20e165084846e58cdf2590a568695bfcff4 — 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/CONCERNS are advisory.

First-Principles-Verdict: PASS

Spawn once on a plain home with the legacy .kiro/crew → .kirocrew link: the fold rewrites those lists too and no test pins that layout.

What this change ships

Inventory (8 items) — 8 justified

Intent: FIX — a gateway on a symlinked home verifies Kiro CLI again (models and balance load) by handing the launcher one name per crew directory. Provenance checked: reproduction in the description, red-on-main test, prior incidents #15252/#13715.

  1. Symlinked-home hosts verify Kiro CLI again after restart — justified
  2. Launcher refuses a spawn when a folded alias is re-aimed before any mask lands — justified
  3. Launcher refuses when a fresh directory is swapped under the canonical data-home name — justified
  4. Launcher re-reads each alias after the last hiding mount and refuses a mid-build re-aim — justified
  5. Every generated launcher script carries a CREW_HOME_ALIASES record — justified
  6. Legacy-alias homes (.kiro/crew → .kirocrew, home not a link) now also fold to one spelling, declared untested — justified
  7. The "never realpath" pin on _relocated_crew_targets is rewritten — justified
  8. The launcher still refuses two spellings outright; the old failure is pinned as a reproduction — justified

Checks run: no existing mechanism folds directory spellings (the "alias pass" / ALIAS_CREDENTIAL_IDS cover hard-linked credential files only; _masked_crew_home_roots dedups its own pass, not the builder's lists). crew_home_aliases: 1 producer consumer, CREW_HOME_ALIASES: 2 launcher-gate consumers. The rewritten pin's premise ("a redundant rule … covered either way, never a missing one") is falsified by the reported defect itself, and its real constraint — no filesystem call in the builder — is preserved and still pinned by test_the_builder_does_not_stat_the_hidden_paths; the one realpath per root runs in namespace_argv beside existing pre-spawn stats/lstats. Unfixed siblings (macOS seatbelt builder; the legacy-alias layout) are declared in ## Not a goal. Gates 2–4 are the condition the fold creates (folded-away rules must not stand for a moved name), so their zero option costs a sandbox boundary; not riders.

[FIRST-PRINCIPLES-REVIEWED] 6fe2b20

Description read

[DESCRIPTION-READ] 7971642653667a31e596aa868380dd166dd761e9937af4c2225d1548f5131bf0

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 Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — 🟡 CONCERNS

Design-level review of 6fe2b20e165084846e58cdf2590a568695bfcff4 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

The fold also fires on plain homes with the legacy .kiro/crew -> .kirocrew link — a common layout this PR changes but deliberately leaves unpinned.

Watch

The description concedes it: "both prefixes then reach the data home and the fold collapses them too, but no new test pins that layout." On a non-symlinked home with the migration link, _crew_home_alias_roots now pairs $HOME/.kirocrew with the .kiro/crew canonical, so the fold and both launcher refusal gates run on hosts that were working before this PR — the spawn path, every spawn. The symlinked-home variant of that layout is pinned (test_a_legacy_link_canonical_under_a_symlinked_home_spawns), and the both-sides-resolved comparison exists precisely because that class false-refused once (the 51cbc2ed58 FP), so the nearest known regression on the unpinned layout is a blanket spawn refusal, not a silent hole.
Clears when: a test drives _crew_home_alias_roots and both lifted gates under a plain (non-link) home whose data home is .kiro/crew -> .kirocrew, pinning the fold and a passing gate on an untouched filesystem.

[DESIGN-REVIEWED] 6fe2b20

Description read

[DESCRIPTION-READ] ce6a709981e2d88700d8517a315ba581e644afb412be6233f3ac7d5205961c78

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 Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ human override accepted

Human judgment by @chenmingwei23 overrides the GPT 5.6 finding for 6fe2b20e165084846e58cdf2590a568695bfcff4; the recorded reason is authoritative for this commit.

[GPT-OVERRIDE] 6fe2b20

This comment is updated in place on each push.

The model was not re-run because an authorized human decision supersedes it.

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 6fe2b20e165084846e58cdf2590a568695bfcff4: <one-sentence reason>

@chenmingwei23
chenmingwei23 force-pushed the fix/sandbox-ancestor-mask-by-identity branch 2 times, most recently from b9fa8c7 to 8aef089 Compare October 1, 2026 06:12
@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 Oct 1, 2026
@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 6fe2b20e165084846e58cdf2590a568695bfcff4 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 6fe2b20

Verdict parsed from the review's SHA-scoped output markers for commit 6fe2b20e165084846e58cdf2590a568695bfcff4.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 6fe2b20e165084846e58cdf2590a568695bfcff4: <one-sentence reason>

@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 Oct 1, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/sandbox-ancestor-mask-by-identity branch from 3af904e to 7409611 Compare October 1, 2026 07:10
@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention labels Oct 1, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/sandbox-ancestor-mask-by-identity branch from 7409611 to c384a08 Compare October 1, 2026 07:28
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 1, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/sandbox-ancestor-mask-by-identity branch from c384a08 to 67c2bfa Compare October 1, 2026 07:49
@chenmingwei23 chenmingwei23 changed the title fix(sandbox): do not mask a stand-in this launcher already bound fix(sandbox): hand the launcher one name per crew directory on a symlinked home Oct 1, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/sandbox-ancestor-mask-by-identity branch from 67c2bfa to 3c81a4f Compare October 1, 2026 08:05
@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 Oct 1, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/sandbox-ancestor-mask-by-identity branch from 3c81a4f to 3674249 Compare October 1, 2026 08:12
@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 Oct 1, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/sandbox-ancestor-mask-by-identity branch from 3674249 to 547180f Compare October 1, 2026 08:29
@chenmingwei23
chenmingwei23 force-pushed the fix/sandbox-ancestor-mask-by-identity branch from ad1c2d9 to 58bf81f Compare October 1, 2026 09:13
@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 Oct 1, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/sandbox-ancestor-mask-by-identity branch from 58bf81f to 51cbc2e Compare October 1, 2026 09:34
…inked home

The launcher keeps every record per NAME -- the occupant a pre-spawn
pass saw (MASK_OCCUPANTS), the stand-in a loop placed (_MASKED_NAMES),
the window it opened (_BOUND_WINDOWS) -- and compares each against the
filesystem by identity. The tier lists spell every crew leaf under
$HOME/<prefix> and the passes spell it under config_dir(), which is
resolved, so on a host whose home is a link (/home/u -> /mnt/home/u)
the launcher is handed two names for one directory and the records
disagree with what either name reaches. #13715, #15252 and this PR's
own symptom are all that one shape.

namespace_argv now decides, once per crew root and beside the passes
that already stat those roots, which $HOME-joined roots are another
NAME for the data home (_crew_home_alias_roots: the root's components
resolve to the canonical path -- resolution, not identity, since a bind
mount of the data home at the alias shares its (st_dev, st_ino) but is
a second mount on which a mask placed at the canonical path does not
appear, so it keeps its own entry), and _build_launcher_script folds every
path under such a root onto the resolved spelling before it emits a
list -- hidden, read-only, files, carve-outs, windows, writable,
exposures, required targets and the occupant map alike. Pure string
work in the builder, so it still makes no filesystem call. A tier entry
with no relocated twin (.vault) is respelled rather than dropped, so no
rule is lost; a root string-equal to the data home is no alias and is
left alone.

The launcher itself gains no skip for a second spelling: a stand-in
reached at a name no pass vouched for is not evidence that the name is
another spelling of anything, and accepting it by membership in
_OWN_STAND_INS alone would let a writer who can reach the shared-temp
fallback park a registered stand-in on a later credential path and have
its mask skipped. Handed two spellings, the launcher still refuses, and
test_sandbox_mount_pinned_target.py keeps that refusal pinned as the
reproduction the fold makes unreachable. The test harness there gains a
_CoveringLibc whose directory bind hides its target, which is what makes
the absent branches reachable in a test at all.

test_sandbox_symlinked_home_launcher.py drives the real pass and
builder under a symlinked home and asserts one spelling per directory,
the carried leaf identity under a listed name, and the whole hiding
region running to the end against the script those producers write,
with a bind that hides its target.

The fold is a decision made in the producer and acted on in the child,
and the home link that makes the two spellings one directory is a name
a writer could re-aim in between. Each alias therefore travels with the
(st_dev, st_ino) it rested on, and the launcher re-reads every alias
ahead of the first hiding mount and refuses the spawn unless it still
reaches that directory -- under BOTH spellings, since the alias alone
would pass a swap that puts a fresh directory under the canonical name
and re-aims the alias at the original -- so the folded rules never stand
for an alias that has moved or a data home that has been replaced.
Both launcher gates test the alias by RESOLUTION, as the producer does,
not by (st_dev, st_ino): a second mount of the data home shares the
identity under another name and carries none of the masks placed on
the canonical entries, so identity would pass an alias re-aimed at such
a mount. The canonical spelling is held to the recorded identity, a
question about an object rather than a name. The first read runs before
the mounts, so a link re-aimed right after it would hold until the masks
land; once every hiding mount is placed the launcher resolves each
alias once more and refuses unless it still names the canonical path.
Both sides are resolved before they are compared: the canonical is the
spelling the passes record under, and on a default data home it is
itself a link (~/.kiro/crew -> ~/.kirocrew), so comparing against the
raw string would refuse every spawn on that layout.
@chenmingwei23
chenmingwei23 force-pushed the fix/sandbox-ancestor-mask-by-identity branch from 51cbc2e to 6fe2b20 Compare October 1, 2026 10:28
@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 Oct 1, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

/ai-review override gpt 6fe2b20: The bypass requires a pre-existing second mount of the data home that only a root-privileged host actor can create (the payload cannot: caps dropped at sandbox.py:10317, mount seccomp-denied per sandbox.py:10330), and in exactly that configuration the unmasked second mount is already directly readable at its own path, so pinning the alias prevents no exposure the deployment has not already granted.

@github-actions

github-actions Bot commented Oct 1, 2026

Copy link
Copy Markdown
Contributor

Human judgment recorded

@chenmingwei23 marked the gpt AI finding as false positive, not applicable, or explicitly accepted for 6fe2b20e165084846e58cdf2590a568695bfcff4.

The bypass requires a pre-existing second mount of the data home that only a root-privileged host actor can create (the payload cannot: caps dropped at sandbox.py:10317, mount seccomp-denied per sandbox.py:10330), and in exactly that configuration the unmasked second mount is already directly readable at its own path, so pinning the alias prevents no exposure the deployment has not already granted.

This decision applies only to this commit. A new push requires a new judgment.

@chenmingwei23 chenmingwei23 changed the title fix(sandbox): hand the launcher one name per crew directory on a symlinked home fix(sandbox): hand the launcher one name per crew directory on a symlinked home Oct 1, 2026
@chenmingwei23 chenmingwei23 changed the title fix(sandbox): hand the launcher one name per crew directory on a symlinked home fix(sandbox): hand the launcher one name per crew directory on a symlinked home Oct 1, 2026
@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 Oct 1, 2026
@chenmingwei23 chenmingwei23 changed the title fix(sandbox): hand the launcher one name per crew directory on a symlinked home fix(sandbox): hand the launcher one name per crew directory on a symlinked home Oct 1, 2026
@chenmingwei23 chenmingwei23 changed the title fix(sandbox): hand the launcher one name per crew directory on a symlinked home fix(sandbox): hand the launcher one name per crew directory on a symlinked home Oct 1, 2026
@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 Oct 1, 2026
@chenmingwei23
chenmingwei23 merged commit 8ae5dff into main Oct 1, 2026
119 of 145 checks passed
@chenmingwei23
chenmingwei23 deleted the fix/sandbox-ancestor-mask-by-identity branch October 1, 2026 12:09
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant