Skip to content

fix: stop the sandbox hiding the directory a child execs out of - #11941

Merged
chenmingwei23 merged 2 commits into
mainfrom
fix/pi-command-registry-readback
Sep 20, 2026
Merged

chenmingwei23 merged 2 commits into
mainfrom
fix/pi-command-registry-readback

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Every pi session was refused before the first prompt. The operator saw:

Pi tool calls would not reach Kiro Crew's security gate (the harness's command
registry could not be read back (exit 126)), so the bundled denied-command rules,
the sensitive-path block and the governance ceiling would not be consulted for them.

The install was fine. Crew hid the gate from itself.

Why it matters

The pi backend is unusable on any host that has a sandbox backend, which is every
supported host. The message also blamed the user's install, so the real cause was
unreachable by following it.

Crew does fail closed here, so nothing ran un-gated. That is the one thing that was
already right.

What changed (motivation → approach → change)

Part Before After
pi gate launcher + sealed extension <data home>/run <data home>/pi-gate
<data home>/run in an enforced harness's mask masked masked
<data home>/pi-gate in the pi child's mask — excluded, so the child can exec
<data home>/pi-gate in any other child's mask — masked
<data home>/pi-gate write access — sealed read-only in every sandbox
<data home>/pi-gate leaf name — precreated and no-follow pinned on the shared walk, and re-checked by pi's own resolver
a squat at <data home>/pi-gate — refuses the spawn, as a squat at any other ceiling does
<data home>/pi-gate for the agent's own file tools — on the is_sensitive_path floor
File Its part
src/kiro_crew/acp/client.py resolves and validates the new artifact directory
src/kiro_crew/agent_sdk/tool_gate.py the per-backend exclusion, through the floor's own exclude_leaves
src/kiro_crew/sandbox.py the read-only seal, the no-follow seal, the pre-create list, the pinned-descriptor sweep
src/kiro_crew/security/paths.py the new leaf on the agent file-tool floor
docs/system-specs/modules/ three specs that described the old location

pi has no permission gate of its own, so Crew loads its own gate extension into the
harness. It seals that extension and writes a small launcher, then asks the harness's own
command registry whether the gate loaded.

An enforced harness is handed the whole agent file-tool floor as an extra OS mask. The
mask builders append that floor after the tier has deliberately kept <data home>/run
visible, so the launcher bind-mounted an empty directory over it moments before
execvp. The gate artifacts lived there, so the child had nothing to exec.

<data home>/run cannot simply be unmasked: run_marker.secret_path keeps the
per-listener bearer credential for the gateway's internal API at
run/gateway-<port>.secret, and read_local_secret prefers it over the shared
.local_secret. So the artifacts move to their own leaf instead, which holds nothing but
what Crew's gate sealer writes.

The exclusion goes through the floor's own vocabulary. sandbox_credential_targets takes
exclude_leaves for exactly this shape — the leaf an adapter must still read while the
read gate keeps fencing the agent's file tools — and adapter_hidden_credential_dirs
already passes that argument for a harness's own credential store. A per-backend table
adds the gate-artifact leaf beside it, so only the pi child's mask uncovers it and the
data-home spellings are derived from crew_home_prefixes() rather than written out.

The new leaf is read-only inside every sandbox, because the launcher cache accepts an
existing path on an isfile check without re-reading its bytes — a writable window would
let one session's child plant the launcher a later session execs. The leaf is
materialized and no-follow pinned on the shared sealable-ceiling walk like
playwright-cli, because mount(2) cannot seal an absent path: off that walk the name
stays WRITABLE in-sandbox until pi first runs.

The walk carries no per-adapter branch: an unsafe state here refuses the spawn as it does
at any other ceiling. _pi_gate_artifact_dir re-checks the same states before the sandbox
is built, so a pi session refuses naming the directory it resolves. Stated residual: a
squat at the leaf refuses any backend's spawn, not only pi's. Conditioning the walk on the
spawning backend was tried and reverted — the adjudicator judged weakening a shared seam
worse than this residual. The resolver
refuses a symlink or a Windows junction at the leaf through
platform_compat.is_link_or_junction, because stat.S_ISLNK answers False for a junction
and a reparse point there would redirect the seal into a directory an agent chose.

Two readers act on that path, so both refuse a link at it. The stale-artifact sweep pins
the directory with O_DIRECTORY | O_NOFOLLOW and unlinks relative to that descriptor, so a
link planted at either artifact directory cannot redirect a delete outside the data home.
Windows has no such primitive through os, so that arm checks for a link and declines to
sweep, and the remaining window is stated rather than hidden. It is pre-created, so the Linux seal has something to mount on before the
first pi session rather than skipping an absent target. The stale-artifact sweep covers
the new directory.

Backwards compatibility

Compatible: the pi gate artifacts move to a path only Crew writes and only Crew reads,
resolved fresh on every spawn. No caller names the old location, and nothing that works
today stops working. <data home>/run keeps exactly the mask it has on main.

Tests

test/test_acp_pi_backend.py pins both halves, so re-broadening the exclusion and
removing it fail in different places:

  • <data home>/run stays bind-masked at standard, cc and strict, and the Seatbelt
    profile still denies reads on it.
  • The directory holding the gateway credential is inside a masked target, asserted
    through run_marker.secret_path rather than a hardcoded name.
  • <data home>/pi-gate is absent from the pi child's mask while still on the floor, and
    still present in another enforced backend's mask, so the exclusion is per backend.
  • The leaf is in _CREW_READONLY_LEAVES, _CREW_PRECREATE_READONLY_DIR_LEAVES and
    _CREW_NOFOLLOW_READONLY_DIR_LEAVES, so it is created and sealed before any sandbox
    starts.
  • A dangling symlink at the leaf raises SandboxCeilingUnsealable out of
    _materialize_sealable_ceilings, parametrized over pi-gate and playwright-cli so a
    later per-leaf exemption for either has to change the test rather than pass quietly.
    Adding a pi-gate skip to the loop fails it.
  • The resolver refuses each squat on the pi spawn path: a dangling symlink, a symlink to a
    real directory, and a regular file. A loose pre-existing directory is tightened to 0700
    rather than refused.
  • One launcher-script test and one Seatbelt test carry the end-to-end mask shape, both
    skipped off POSIX because those builders need os.getuid.
  • A link at the leaf refuses the session and leaves the pointed-at directory empty, and
    neither writer touches it. Both run on Windows too, through conftest.make_dir_link,
    which plants a junction where a symlink would need a privilege.
  • A link planted at either artifact directory makes the sweep remove nothing and leaves the
    pointed-at file on disk. Dropping O_NOFOLLOW fails both, because the sweep then deletes
    through the link.
  • Both gate artifacts resolve through the one strict resolver, which returns
    <config dir>/pi-gate at mode 0700.
  • run/voice-runtime keeps its own mask, and stale artifacts are swept from the new
    directory.
  • The read-back still refuses a session it cannot read the registry from: a fake harness
    that exits 126, one that answers a shape this gateway cannot read, and one that answers
    with the probe from Crew's file.

Mutation-verified twice: emptying the per-backend exclusion table fails 3 tests including
the mask-and-floor assertion, and removing pi-gate from the no-follow set fails the seal
assertion.

Manual verification

The read-back was run by hand against a real pi (mise-installed, 24.20.0) outside the
sandbox: exit 0, and the registry lists kiro-crew-gate sourced from the sealed copy.
That rules out the install and the rpc protocol as causes. The masked-directory half is
proved by reading the generated launcher's own SENSITIVE_DIRS and READONLY_DIRS and
the generated Seatbelt rules, because this host cannot create a user namespace. The
exclusion was also checked against a relocated KIROCREW_HOME: pi-gate excluded there
too, run still masked.

Related Issues

no linked issue: reported directly as an operator-facing refusal message, not through the
tracker.

Pattern harvest

Rule candidate: review-prompt
Pattern: a caller-supplied deny list appended after a deliberate allow decision cancels
it, and the invariant lives only in a comment on the allow list.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|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

@iamwhatever
iamwhatever requested review from a team and CrysisDeu September 19, 2026 05:03
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Intent: Make a pi session able to start, by stopping Crew's own sandbox mask from hiding the directory it seals the pi gate extension and gate launcher into, and give a silent exec failure a cause instead of a bare exit number.

Not a goal: Changing what the read-gate floor protects, relaxing any write seal, reworking the gate-extension routing, or touching any other harness's mask.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 19, 2026
@github-actions

github-actions Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 4d3419a1307407a3f0fba260176fdb6d5aa6146d and found no blocking issues.

This comment is updated in place on each push.

Review details

FINDING -- src/kiro_crew/agent_sdk/tool_gate.py:269 -- "ceilings and consent records are excluded" contradicts _CREW_CHILD_WITHHELD_LEAVES, which keeps them masked -> Fix: Correct this and the changed runtime-leaf descriptions to name only the actually readable leaves.
[GPT-REVIEWED] 4d3419a

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

@github-actions

github-actions Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 4d3419a1307407a3f0fba260176fdb6d5aa6146d — 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

Verify the roster-wide rider: unmasking playwright-cli for every enforced harness's child. The description as fetched declares only the pi fix.

Not justified as shipped

  • Item 5 — rides along: enforced children (codex, opencode, goose) also gain read/exec of playwright-cli; the fix's stated scope is "the pi backend is unusable" — same mask-collision cause, and test_named_child_reachable_leaves_stay_out_of_every_enforced_mask fails on base.
  • Item 6 — rides along: the withheld/readable classification pair, crew_host_runtime_leaves() (one production consumer, adapter_hidden_credential_dirs) and its completeness pin — the cause-level invariant fix, but beyond the declared pi job.
  • Item 8 — rides along: the O_NOFOLLOW sweep restructuring also changes the pre-existing run sweep's behavior on a linked directory; declared, harm named (delete-through-link outside the data home).

What this change ships

Inventory (9 items) — 6 justified

Intent: unbreak the pi backend, which every sandboxed host refused at session start because Crew's own enforced-harness mask hid the directory holding its gate launcher — a FIX.

  1. pi sessions start instead of refusing with "registry could not be read back (exit 126)" — justified
  2. Gate launcher and sealed extension move from <data home>/run to <data home>/pi-gate, since run holds gateway-<port>.secret — justified
  3. pi-gate is precreated, read-only sealed and no-follow pinned on every install — justified
  4. pi-gate fenced from the agent's own file tools (is_sensitive_path floor) — justified
  5. Every enforced harness's child can now exec playwright-cli — rides along; pinned by a test failing on base
  6. New child-readable/withheld leaf classification, crew_host_runtime_leaves(), and a mandatory-classification pin — rides along; cause-level fix for the collision class
  7. A squat or symlink at pi-gate refuses any backend's spawn — stated residual, adjudicated shape — justified
  8. Stale-artifact sweep pins both artifact directories O_NOFOLLOW and declines linked ones (Windows: declines, window stated) — rides along; declared
  9. AGENTS.md and three specs updated to the new location and the enforced-harness exception, same commit — justified

[FIRST-PRINCIPLES-REVIEWED] 4d3419a

@github-actions

github-actions Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — 🟡 CONCERNS

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

Design-Verdict: CONCERNS

The contract doc and crew_host_runtime_leaves docstring say enforced children can read the governance ceilings; _CREW_CHILD_WITHHELD_LEAVES masks them.

Watch

  • Doc/code contradiction on a security boundary, shipped in the spec named as source of truth. sandbox.py:802-804 enumerates the child-readable half as "the governance ceilings, the opt-out and consent records…", and the updated agent-host-contract.md row repeats it ("the governance ceilings, the consent records, playwright-cli") — but _CREW_CHILD_READABLE_LEAVES contains neither, and the withheld list's own comment argues the opposite direction ("costs it CLOSED… a session refuses rather than proceeding ungoverned"). The prose reads like a pre-adjudication draft in which ceilings were unmasked. The next harness author follows the contract row, expects in-sandbox ceiling resolution to work, and either ships a harness that refuses on governed hosts or "corrects" the lists to match the doc — unmasking authorization inputs to a foreign child without a decision. The new AGENTS.md sentence matches the code, so only the function docstring and the contract parenthetical are wrong.
    Clears when: the docstring's enumeration and the agent-host-contract parenthetical name the actual readable set (playwright-cli + authorization sidecars) and state that ceilings/consents are withheld.
  • Description → diff gap: the every-enforced-backend crew_host_runtime_leaves() subtraction — whose one effective change is unmasking playwright-cli for codex/opencode/goose children (the commit title says so; the PR description never does) — is a mask-posture change for harnesses the stated pi problem doesn't touch.
    Clears when: the description states the all-backend subtraction and the playwright-cli unmask, or that half moves to its own PR.

[DESIGN-REVIEWED] 4d3419a

@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 Sep 19, 2026
Comment thread src/kiro_crew/sandbox.py Fixed
@github-actions

github-actions Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 4d3419a1307407a3f0fba260176fdb6d5aa6146d — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 4d3419a

Verdict parsed from the review's SHA-scoped output markers for commit 4d3419a1307407a3f0fba260176fdb6d5aa6146d.

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

@iamwhatever
iamwhatever force-pushed the fix/pi-command-registry-readback branch from 3e95864 to 71cfda5 Compare September 19, 2026 05:37
@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: the pi gate artifacts move to their own <data home>/pi-gate leaf, so the mask exclusion names a directory that holds no credential.

  • Runtime credential directory is removed from the adapter mask (span=fa7ab943e399) — fixed in 71cfda5

Confirmed, not rebutted. instances/run_marker.py secret_path() puts the per-listener bearer credential at run/gateway-<port>.secret, and config/loader.py read_local_secret() prefers it over the shared .local_secret. Dropping the whole run directory handed that credential to a harness whose passive reads never reach the gate.
The exclusion no longer names run. run keeps the mask it has on main at every tier, on both backends. The gate artifacts move to <data home>/pi-gate, a leaf written only by Crew's gate sealer, and that one directory is what the mask drops.
The new leaf is sealed read-only inside every sandbox, because _pi_gate_launcher_cache accepts an existing path on an isfile check without re-reading its bytes, so a writable window would let one session's child plant the launcher a later session execs. It is in _CREW_PRECREATE_READONLY_DIR_LEAVES so the Linux seal does not skip an absent target before the first pi session, and on the is_sensitive_path floor so the agent's own file tools stay fenced.
Regression coverage asserts the credential's own parent through run_marker.secret_path, not a hardcoded name. Retargeting the exclusion back to run fails 13 tests; removing it fails 7.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: none added; the read-back diagnosis vocabulary is removed.

  • Rides along: the exit-126/127 phrasing is diagnosis, not the fix (span=60698232cfb3) — fixed in 71cfda5

Accepted and subtracted. _READBACK_LAUNCH_FAILURE_PHRASES is gone, _readback_detail_with_diagnosis is back to its two-argument shape, both call sites pass two arguments, and the test asserting a bare (exit 126) is restored.
The reasoning it was added on still holds — a silent child at an exec status leaves the operator a number with no cause — but that is a separate diagnosis improvement to the shared vocabulary two harnesses read, not the change that lets a pi session start. Shipping it here widened the diff for a reader of a message this PR makes unreachable for its own cause.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: none added; the read-back diagnosis vocabulary is removed.

  • Rides along: the exit-126/127 phrasing is diagnosis, not the fix (span=60698232cfb3) — fixed in 71cfda5

Accepted and subtracted on the same reasoning the design lane raised it: the premise this PR rests on is that a pi session cannot start, and a clearer refusal message is not a step toward that. Removed rather than defended, so the diff carries one change.
_READBACK_LAUNCH_FAILURE_PHRASES is gone and the shared helper both the pi and opencode read-backs call is back to the shape it has on main.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: the rationale lands on the new pi-gate leaf in security/paths.py, _CREW_READONLY_LEAVES and docs/system-specs/modules/security.md.

  • Add the exec-visibility rationale beside the leaf a future author will read (span=6596d38ff75e) — fixed in 71cfda5

Implemented on the leaf the premise now applies to rather than the one named. run stops being exec-visible to an enforced harness in this change, so a note there would send the next author the wrong way; pi-gate is the directory that is deliberately exposed.
security/paths.py states the asymmetry at the new entry: the OS mask excludes it so the harness's child can exec the launcher and read the sealed extension, while this floor still keeps the agent's own file tools out, and the two controls cover different readers rather than cancelling. _CREW_READONLY_LEAVES carries the concrete risk the seal closes. docs/system-specs/modules/security.md records the leaf's READONLY disposition and that run/gateway-<port>.secret is why run stays masked.
The instruction a future author needs is the one the finding asked for, worded for the leaf that now holds the artifacts: a secret must not be placed under it, and one that must live there needs its own masked leaf the way run/voice-runtime does.

@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 Sep 19, 2026
@github-actions

github-actions Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

Security Scope Review -- 🟡 CONCERNS

Which legitimate operations does 4d3419a1307407a3f0fba260176fdb6d5aa6146d newly refuse? Updated in place on each push. A script-confirmed regression blocks; the model proposes candidates and never decides a refusal.

Verdict basis: the reviewer's own judgement; no confirmed regression.

Security scope review -- adjudicated candidates

  • macos-latest (platform posix): 9 classified, 0 newly refused, 9 still allowed.
  • ubuntu-latest (platform posix): 9 classified, 0 newly refused, 9 still allowed.
  • windows-latest (platform windows): 5 classified, 0 newly refused, 5 still allowed.

No candidate flipped from allowed to refused.

Scope-Verdict: CONCERNS

TIGHTENING: The read+write path fence (_CREW_SECRET_LEAVES in src/kiro_crew/security/paths.py) gains one leaf — the threat it refuses is the agent's own file tools rewriting the pi gate artifacts, per the hunk: + # Pi gate artifacts have asymmetric readers. ... This floor still keeps the agent's + # own file tools out; the controls cover different readers rather than cancelling. + "pi-gate",, and the sandbox seal hunk names the same threat: "the agent could plant the launcher a later pi session execs out of".

ADJUDICATED: 14 candidates, 0 confirmed newly-refused
No verdicts were handed to this review; the candidates in candidates.json probe the fence's boundary (the fenced leaf's own read-only diagnostics, the remediation the new refusal text itself directs, the sibling and parent reads the fence must not smear onto, the leaf's literal spelling in command text, and the anchored-versus-anywhere match), and the adjudication legs will classify them against base and head.

PLATFORM COVERAGE: posix and windows, plus no any rows because every candidate carries a path or an executable name. Posix rows cover the fence entries' own /-separated, home-anchored spelling under both crew data-home prefixes (.kiro/crew and .kirocrew), the chmod 700 remediation the refusal text directs, and a /tmp pytest-fixture path that tests whether the match is anchored or leaf-name-anywhere. Windows rows cover the same operations in the other tokenizer's spelling — \ separators, %USERPROFILE%, icacls/dir/type/certutil, and the .venv\Scripts\python.exe test lane — which matters because the diff carries Windows-only arms (junction detection, the POSIX mode-bit check skipped on IS_WINDOWS, the check-then-act sweep window) whose spellings a /-authored fence entry could either miss or over-match. One assumed configuration I could not write a shell candidate for: a relocated data home (KIROCREW_HOME), because the classifier settles a command line, not the environment it resolves under; the fence re-anchors under that override and no shell row can vary the anchor. The per-leg verdicts are the deterministic fold's to report, not mine.

UNADJUDICATED: Most of this change's tightening lives in guards the shell-command classifier never reaches, so no verdict exists for them and PASS cannot be claimed:

  • acp.client._pi_gate_artifact_dir — a validator on the pi spawn path (reached from _seal_pi_gate_extension and _ensure_pi_gate_launcher before any child starts). It newly refuses a symlinked or junction pi-gate, a regular file at that name, and (posix) any unresolvable state; it silently re-chmods a loose pre-existing directory to 0700. Candidate legitimate inputs I would have submitted: a pi-gate directory restored from a backup with group-readable mode (the tests say it is narrowed, not refused — worth confirming on a live host); a data home on a filesystem without POSIX mode semantics (FAT/exFAT or some network mounts), where os.chmod succeeds but stat never reports 0o700, which would refuse every pi session on that host; a home directory that is itself a symlink (the code compares realpath-to-realpath, but only a live run proves it).
  • sandbox._materialize_sealable_ceilings plus the precreate/no-follow lists — pi-gate joins the shared walk that runs on every Linux spawn for every backend. The diff itself states the residual: "a squat at the leaf refuses any backend's spawn, not only pi's." Candidate legitimate input: an install where an operator or an older artifact left pi-gate as a symlink or file — every sandboxed session on that host (kiro-cli sessions that never touch pi included) now refuses until the leaf is removed by hand.
  • cleanup_stale_sandbox_profiles — the sweep now refuses a linked run or pi-gate directory (O_NOFOLLOW on posix, is_link_or_junction on Windows). Candidate legitimate input: an operator who relocated ~/.kiro/crew/run to scratch storage via symlink; their stale launchers are now never reclaimed, silently, with only a log warning.
  • adapter_hidden_credential_dirs and the _CREW_CHILD_WITHHELD_LEAVES / _CREW_CHILD_READABLE_LEAVES pair — an OS bind-mask, not a command matcher. The direction of this change there is mostly a loosening (un-hiding crew_host_runtime_leaves() from enforced children), but pi-gate is newly masked for every non-pi enforced child; I found no legitimate reader of that leaf in a non-pi child, and no verdict is available either way.

[SCOPE-REVIEWED] 4d3419a

@iamwhatever
iamwhatever force-pushed the fix/pi-command-registry-readback branch from 71cfda5 to e9588b4 Compare September 19, 2026 06:04
@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: pi-gate joins _CREW_NOFOLLOW_READONLY_DIR_LEAVES, so the seal validates the leaf name instead of following a referent.

  • Treat pi-gate as a no-follow executable directory (span=fa7ab943e399) — fixed in e9588b4

Confirmed, not rebutted. That set's own docstring states the invariant: a read-only directory leaf must keep its lexical name as the mounted name, because a resolving symlink lets the mount follow its target and leaves the name replaceable, "which would let an agent choose the executable the gateway runs." An earlier round of this PR made pi-gate exactly such a leaf and left the entry out, so this is an incomplete fix, not new scope.
With the entry present, pi-gate takes the strict branch in _materialize_absent_ceilings: _refuse_if_symlink_leaf runs before the leaf is followed, and _require_real_dir_nofollow validates an existing or race-created directory. Neither ran for it before.
The same chain is what playwright-cli carries the entry for, and the subset assert between the no-follow and pre-create sets still holds. Removing the entry fails test_gate_artifact_leaf_is_precreated_read_only_and_nofollow.

@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 Sep 19, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: none added; a sandbox-side filter is deleted and the exclusion moves into the floor's existing exclude_leaves argument.

  • The floor's existing exclusion vocabulary was not used (span=534ec5b29cba) — fixed in e9588b4

Accepted. sandbox_credential_targets's docstring states this job, including the same two-readers asymmetry the change had hand-written a fresh comment for, and adapter_hidden_credential_dirs already passed exclude_leaves for a harness's own credential store. A per-backend gate-artifact table now sits beside that one and both are unioned into the same argument.
Net subtraction: _maskable_extra_hidden_dirs, _pi_gate_artifact_paths, the _PI_GATE_LEAF constant, a widened cache tuple and its type annotation, both mask-builder call sites and a test fixture change are all deleted. sandbox.py's remaining diff is leaf-list entries and the artifact sweep.
The clearing condition's second half is answered rather than argued: a non-pi caller's mask does NOT need to expose the leaf, and now does not. The exclusion is keyed on the pi backend, and a test asserts another enforced backend's mask still covers pi-gate. Data-home spellings derive from crew_home_prefixes(), so a relocated KIROCREW_HOME is covered — verified by hand.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: none added; a sandbox-side filter is deleted and the exclusion moves into the floor's existing exclude_leaves argument.

  • The floor's existing exclusion vocabulary was not used (span=534ec5b29cba) — fixed in e9588b4

Accepted on the same reading. The duplicate the item names is real: a second mechanism for dropping a leaf from a sandbox mask was added in sandbox.py while security/paths.py already owned one, and the new one was broader, since it applied to every caller rather than to the backend that needs it.
The added mechanism is removed, not kept alongside. The exclusion is now one per-backend table read through sandbox_credential_targets(exclude_leaves), and the diff is smaller than the round it replaces.

@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 readiness: action required A blocking check or review needs attention labels Sep 19, 2026
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Sep 19, 2026
@iamwhatever
iamwhatever force-pushed the fix/pi-command-registry-readback branch from a7d4d60 to 69fd34d Compare September 19, 2026 18:44
@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 Sep 19, 2026
@iamwhatever
iamwhatever force-pushed the fix/pi-command-registry-readback branch from 69fd34d to 93eacfe Compare September 19, 2026 19:03
@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 Sep 19, 2026
@iamwhatever
iamwhatever force-pushed the fix/pi-command-registry-readback branch from 93eacfe to 9cc26ff Compare September 19, 2026 19:22
@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 Sep 19, 2026
@iamwhatever
iamwhatever force-pushed the fix/pi-command-registry-readback branch from 9cc26ff to 8687e58 Compare September 19, 2026 19:50
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Sep 19, 2026
@iamwhatever

iamwhatever commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: none; the finding is accurate and the correction is deferred, not applied.

  • Docstring contradicts the shipped shape (span=a63bd9ceeb00) — accepted as accurate. _pi_gate_artifact_dir's docstring still says the leaf is materialized and no-follow checked here "rather than on sandbox's shared sealable-ceiling lists", which describes the reverted round-5 shape; pi-gate is on both shared lists in this head. It is stale prose in a security-relevant function, not a behaviour defect: the code the docstring sits on is unchanged and correct, and sandbox.py's own rationale comment and docs/system-specs/modules/security.md both describe the shipped shape. Held rather than pushed because this head is the first with every review lane green, and the standing instruction is no further pushes; the correction is a one-paragraph docstring edit whenever a push is next authorized.

bolichen97
bolichen97 previously approved these changes Sep 20, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approved: fix-class, readiness:passed, no conflict.

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ⏭️ skipped

Revision 4d3419a1307407a3f0fba260176fdb6d5aa6146d touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

buluoray
buluoray previously approved these changes Sep 20, 2026

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approving at bb579044. No blocking findings — nothing unsafe ships. But there is one ask below that I would want closed before this becomes the reference for the next harness author, and it is on this PR's own seam.

All six bots cite this head: GPT, First Principles, Opus and UX PASS; Design and Security-Scope CONCERNS (advisory). Design independently found the same contradiction I did.

The load-bearing thing I checked first, because AGENTS.md makes it the pin that keeps the ceiling un-disableable. test_sandbox_governance_mask.py is 48 insertions, 0 deletions. The existing reconciliation and disjointness pins were not edited to accommodate this change — two methods were added beside them. A sandbox PR that had to loosen that test to pass would be a different conversation entirely, so it is worth stating plainly that this one did not.

How much the visible surface actually grew: one leaf. Of the newly readable entries, playwright-cli is the only one that was genuinely on the mask floor (security/paths.py:179 _CREW_SECRET_LEAVES feeding _SENSITIVE_HOME_DIRS at :759). The rest — apps/.dev-grants.json, settings_seeds.json, agent_model_state.json, subagents, decisions — were never in _SENSITIVE_HOME_DIRS at all (subagents and decisions are write-protected, read-allowed), so reclassifying them changes nothing a child could already open. That is a much smaller delta than the diff size suggests.

This is an OS-level rule change, not a matcher. Bind-mask plus a read-only seal plus a completeness pin, which is the direction AGENTS.md asks for when it calls a regex spelling-chase a review smell. Symlinks are resolved before the decision, not after: acp/client.py::_pi_gate_artifact_dir refuses on is_link_or_junction, then requires realpath == canonical and mode 0o700. pi-gate is a sibling leaf of the still-masked run, precreated so it is a read-only mountpoint before any sandbox starts — so this is not a parent unmask that transitively exposes siblings, which was my main worry going in.

Every credential and authorization leaf stays withheld: run (the gateway port secret), trust, sel_hmac.key, .local_secret, crons.json, member-memory-bindings, the security event log, the admission stores, memory_stores, and pi-gate itself for every backend other than pi.

The one ask

tool_gate.py:269-271 and the crew_host_runtime_leaves docstring state the opposite of what ships. Both say Crew's own ceilings and consent records are excluded from the mask — that is, child-readable — "because an in-sandbox Crew reader needs them and they hold no credential". I read both tuples in full to be sure, because the grep I tried first was inconclusive:

  • _CREW_CHILD_WITHHELD_LEAVES contains security_policy.json, profiles, admission_policy.json, computer_use.json, denied_commands.json, and all four consent records (decisions_consent.json, file_delivery_consent.json, ssh_auth_sock_consent.json, aws_service_consent.json).
  • _CREW_CHILD_READABLE_LEAVES contains none of them.

So the code withholds what the documentation says it exposes. The code is the tighter of the two, which is why this is not blocking and why no exposure ships.

It still matters more than an ordinary doc nit, for a specific reason: harness-onboarding.md directs the next harness author to reason from exactly these two places. Someone reading them will conclude the ceilings are meant to be child-readable and may "correct" the code toward the doc — and AGENTS.md is explicit that this area is where masking and exposing have counterintuitive consequences, since hiding a policy file can make it resolve to the permissive standalone default rather than protecting it. A doc that describes a wider exposure than the code is the one artifact that could license widening it later, on this PR's own seam.

I am not claiming which side is correct. Whether an in-sandbox Crew reader in the child needs those leaves is your call, and it decides whether the fix is to the prose or to the tuples. What should not persist is the two disagreeing.

Smaller: _pi_gate_artifact_dir's refusal string says "not a real owner-only leaf" — "leaf" is internal vocabulary in an operator-facing message. And three residuals are stated rather than hidden: a symlink-relocated pi-gate refuses every pi session, a squat at pi-gate refuses any backend's spawn, and a symlinked run/pi-gate is silently skipped by cleanup_stale_sandbox_profiles.

I did not execute the pin test, and I take on trust that no credential-bearing file exists under run beyond the relocated artifacts, which the OS mask enforces per spec.

Not merging; that is Ray's call.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Re-synced onto current main.

  • Base: abedd2ed15 -> 1fbffb1c7a. Head: bb5790445c -> 6617d24755. Two commits kept, not squashed.
  • Textual conflict, src/kiro_crew/sandbox.py: main's feat(cloud): a configuration home for the Fargate lane, and register it when set #11556 and this branch both appended to the read-only crew-leaf list right after playwright-cli. Resolved by keeping both sides' entries — main's cloud.json / cloud_launch_state.json, then this branch's pi-gate. _materialize_sealable_ceilings still carries no pi-specific conditional, and pi-gate stays on the shared precreate and no-follow lists.
  • Two semantic conflicts main introduced, each fixed by adding the row the new invariant asks for, with no shape change:
  • Diff equivalence: the pre-rebase and post-rebase -U0 line sets are identical apart from the 4 wording lines and the 9 classification lines above (1190 added / 142 removed before; same sets after, plus those 13).
  • Tests: test_acp_pi_backend.py, test_acp_tool_gate.py, test_sandbox_governance_mask.py, test_sandbox_argv.py, test_sandbox_crew_home_carveout_spellings.py — 1184 passed, 4 skipped. Gates: black, isort, flake8 on the 7 changed Python files; mypy on the 4 changed src/ files; docs-lint; comment-history; agent-sdk-boundary; harness-parity.
  • One thing this branch cannot fix: clean origin/main at 1fbffb1c7a fails sandbox.py's own _DELEGATED_OVERLAP_LEAF_REASONS assert at import, because feat(cloud): a configuration home for the Fargate lane, and register it when set #11556 shipped wording for two leaves while the no-follow list had five. Every test job on any PR is red until fix(sandbox): cover 3 sealed dir leaves in delegated-overlap wording (#12182) #12193 lands that wording. The local run above was done with fix(sandbox): cover 3 sealed dir leaves in delegated-overlap wording (#12182) #12193's hunk applied as an uncommitted local patch and reverted before commit.

zejiangg and others added 2 commits September 20, 2026 05:43
An enforced ACP harness is handed the agent file-tool floor as an extra OS mask,
and pi seals its gate extension and writes its gate launcher into a directory on
that floor. The launcher bind-mounts an empty directory over it moments before it
execvp's the child, so the child could not start, the command registry could not
be read back, and every pi session was refused before the first prompt.

The artifacts move to <data home>/pi-gate, a leaf that holds nothing but what
Crew's gate sealer writes, and the pi backend excludes it from its own mask
through the floor's existing exclude_leaves vocabulary -- the same mechanism that
lets an adapter read its own OAuth token. The exclusion names one backend, so
every other child's mask still covers the leaf, and the floor still fences the
agent's own file tools, so the two controls cover different readers.

<data home>/run keeps its mask, because run_marker.secret_path stores the
per-listener bearer credential for the gateway's internal API under it.

Materializing the leaf and checking it is not a link belongs to the one backend
that has it, not to the shared sealable-ceiling walk that every Linux spawn
performs whatever the backend is: an entry there lets this adapter's directory
refuse an unrelated session's construction. _pi_gate_artifact_dir creates the leaf
0700 and refuses a dangling symlink, a symlink, a junction, a non-directory and a
wrong mode, and it runs before the sandbox is built on every pi spawn, so the
read-only seal still finds a directory to bind. A spawn on any other backend finds
the name absent and the seal skips it.

The leaf stays read-only inside every sandbox, because the launcher cache accepts
an existing path after isfile without re-reading its bytes, and stays on the
file-tool floor. The stale-artifact sweep pins its directory with
O_DIRECTORY | O_NOFOLLOW and unlinks relative to that descriptor, so a link
planted at either artifact directory cannot redirect a delete outside the data
home; Windows has no such primitive through os, so that arm checks for a link and
declines to sweep, which is stated as the accepted residual.
…right-cli (#11977)

A pi session died because the sandbox hid the directory the child had to exec
out of. That was not a pi bug. The credential mask an ENFORCED harness is
confined by projects the whole read-gate floor, and the floor covers a Crew
runtime file to keep the AGENT'S FILE TOOLS out of it, not to keep the CHILD
out. Used as a sandbox deny list, the same entry hides the file from the child
too. This is the audit of that class across every backend.

All eight were swept. The four unenforced ones get no mask and were never
affected. The four enforced ones (codex, opencode, goose, pi) each hid files
sandbox.py itself declares the child must reach. No fail-open anywhere: every
arm refuses the session rather than running unconfined.

What ships is the classification, not a wider mask. Every crew leaf a sandboxed
process may read is now declared either child-readable or withheld, in two
paired lists rather than one derived as the complement of the other, because a
complement makes classification optional: a credential leaf added later would
default to readable and reach a foreign child with nothing reading as wrong.
Written out, a new leaf lands in neither list and a pin fails until someone
decides. That pin caught four upstream leaves across three rebases.

Only playwright-cli leaves the mask. It is the one readable leaf the read gate
also fences, so the one whose exclusion changes what an enforced child can
open; the browser launcher is what an agent browser command execs. Every
governance, policy and consent document stays masked, and so does every
credential leaf, because each is an input to an authorization decision and a
foreign child reads it through a channel that reaches no gate.

So the governed-host boot break is NOT fixed here. An in-sandbox
boot_platform() under those four harnesses still gets an empty ceiling document
and raises, which is fail-closed and therefore safe. Closing it needs a
gateway-brokered read rather than a mask exclusion, and that is tracked in
#11988 along with every other feature these leaves cost.

Three ratchets, all over the production roster: no child-required path may be
masked, a withheld leaf leaves the mask only by a narrower per-backend grant
(asserted in both directions), and every non-hidden crew leaf must be
classified, pinned complete and disjoint. The owning specs and the AGENTS.md
residual note are updated to describe the mask's two exemptions rather than
one.

Co-authored-by: zejiangg <zejiangg@amazon.com>
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Re-synced again, now that #12193 is on main.

  • Base: 1fbffb1c7a -> 7e8f2c459f. Head: 6617d24755 -> 4d3419a130. Two commits kept, not squashed.
  • One conflict, src/kiro_crew/sandbox.py: fix(sandbox): cover 3 sealed dir leaves in delegated-overlap wording (#12182) #12193 added three wording rows to _DELEGATED_OVERLAP_LEAF_REASONS at the same place this branch added its pi-gate row. Resolved by keeping all four — main's subagents, member-memory-bindings, decisions, then pi-gate. Nothing else in the dict changed, and the cloud.json / cloud_launch_state.json classification from the previous re-sync carried over untouched.
  • Diff equivalence: the -U0 added and removed line sets are byte-identical to the previous head's (1203 added / 142 removed both sides, comm empty in both directions). This rebase changed no line of this branch's own diff.
  • Tests: test_acp_pi_backend.py, test_acp_tool_gate.py, test_sandbox_governance_mask.py, test_sandbox_argv.py, test_sandbox_crew_home_carveout_spellings.py — 1184 passed, 4 skipped, with no local patch this time; main imports on its own now. Gates: black, isort, flake8 on the 7 changed Python files; mypy on the 4 changed src/ files; docs-lint; comment-history; agent-sdk-boundary; harness-parity.
  • The 37 red shards on 6617d24755 were main's import assert, which fix(sandbox): cover 3 sealed dir leaves in delegated-overlap wording (#12182) #12193 fixed. They are not expected on this head.

@bolichen97

Copy link
Copy Markdown
Contributor

Found this while reviewing the merged change. The code is correct — three prose passages describe the opposite of what it does. Fix is up as #12251 (wording only, no list or predicate touched).

@buluoray had already flagged the same contradiction in a review comment on bb579044; the push to 4d3419a1 after that review did not address it, so it merged.

What disagrees with what

crew_host_runtime_leaves()'s docstring says the readable half is

the governance ceilings, the opt-out and consent records, the browser launcher, the authorization sidecars

Read from the loaded module on main, _CREW_CHILD_READABLE_LEAVES is nine leaves and contains no ceiling and no consent record:

playwright-cli, apps/.dev-grants.json, settings_seeds.json,
agent_model_state.json(+.lock), subagents, decisions,
cloud.json, cloud_launch_state.json

All five ceilings and all four consent records are in _CREW_CHILD_WITHHELD_LEAVES, forty lines above, under the comment that withholds them as one family because each is an input to an authorization decision. tool_gate.adapter_hidden_credential_dirs repeats the same wrong claim, and agent-host-contract.md's bucket-4 row repeats it a third time (its withheld enumeration also lists 8 of the 21 withheld leaves).

The part that matters more than the inventory

The docstring does not just mis-list the set — it builds an argument on the mis-listing, and reaches the opposite conclusion from the withhold list about the same consequence:

passage what it says about boot_platform() raising
crew_host_runtime_leaves() docstring "Hiding a ceiling is the sharpest case, because it is not merely lost" — presented as the reason the ceiling must be subtracted from the mask
_CREW_CHILD_WITHHELD_LEAVES governance comment "it costs it CLOSED … so a session refuses rather than proceeding ungoverned" — presented as the accepted cost of withholding it

One file, one consequence, two opposite verdicts. The second is the shipped behaviour.

This is load-bearing because harness-onboarding.md Stage 5 sends the next harness author to exactly these two docstrings to learn which leaves a child must reach, right beside "never widen the second". Read as written, they read as licence to move a ceiling into the readable set to make a new harness boot — which is what AGENTS.md now forbids outright after #12200.

Not drift — wrong on arrival

Neither crew_host_runtime_leaves nor either constant exists at 9dea438cfa~1, so both lists and the prose landed in this commit, and the prose described a set the commit never built. The OS mask over the governance tree is older: security_policy.json has been masked since #7439. So the withheld disposition is the only one that has ever shipped, and there is no earlier behaviour the docstring could have been describing — the same shape as #11556, where an import-time assert required five wording entries and shipped with two.

Deliberately not changed

_CREW_READONLY_LEAVES' docstring says the ceiling is "readable by sandboxed code, never writable by it" — that one is correct and untouched. The ceiling is readable in the ordinary sandbox (a script cron's boot_platform() resolves it); the withhold applies only to an ENFORCED harness's child through adapter_hidden_credential_dirs. #12251 says so explicitly so the two docstrings stop looking like a contradiction.

harness-onboarding.md:289 is also correct as written and untouched.

What I did not decide

Whether an in-sandbox Crew reader in an enforced-harness child should be able to resolve a ceiling is your call, not mine — #12251 only makes the prose match what the code does today. If the answer is that it should, the fix is a list change with its own review, not a docstring edit. Verified with the 831 tests in test_sandbox_governance_mask.py + test_acp_tool_gate.py, which pin the pair complete and disjoint and would fail if #12251 were a behaviour change wearing a docs label.

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.

5 participants