Skip to content

docs: the governance ceiling stays masked from an enforced child - #12251

Merged
bolichen97 merged 1 commit into
mainfrom
docs/child-readable-leaves-wording
Sep 20, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
docs/child-readable-leaves-wording

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

What changed

Three passages describe sandbox.crew_host_runtime_leaves() — the set an
enforced harness's child may read — as carrying the governance ceilings and the
consent records. It carries neither.

The real set is nine leaves: playwright-cli, the authorization sidecars
(apps/.dev-grants.json, settings_seeds.json, the agent_model_state.json
pair), the gateway-owned subagents and decisions records, and the operator's
cloud.json / cloud_launch_state.json. Every ceiling, policy and consent
document sits in _CREW_CHILD_WITHHELD_LEAVES forty lines above, withheld as
one family because each is an input to an authorization decision a foreign
harness's child would read through a channel that reaches no gate and leaves no
record.

The code is right and is not touched here. No list, no predicate and no
behaviour changes. Only prose.

File Correction
src/kiro_crew/sandbox.py the accessor's docstring now names the set it returns, and states that the ceiling's absence is deliberate
src/kiro_crew/agent_sdk/tool_gate.py adapter_hidden_credential_dirs no longer says ceilings and consent records are excluded from the mask
docs/system-specs/modules/agent-host-contract.md bucket-4 row corrected, and its withheld enumeration completed — it listed eight of the twenty-one withheld leaves

Why it is worth a PR of its own

The dangerous half is not the inventory but the argument built on it. The
accessor's docstring presented the boot_platform() raise as a reason the
ceiling MUST be subtracted from the mask:

Hiding a ceiling is the sharpest case, because it is not merely lost: an empty
bind over security_policy.json makes boot_platform() raise, so every
in-sandbox Crew process under an enforced harness stops booting

while the withhold list presents the same raise as the accepted cost of
withholding it:

Hiding them costs in-sandbox governance resolution, and it costs it CLOSED:
[...] so a session refuses rather than proceeding ungoverned.

Two statements in one file reach opposite conclusions from one consequence. The
withhold list is the shipped behaviour, so the docstring now says the raise is
accepted because it lands in the safe direction, and says outright that the
paragraph above it is not licence to move a ceiling into the readable set to
make a harness boot.

That last sentence is the point. harness-onboarding.md sends the next harness
author to these two docstrings to learn which leaves a child must reach. Read as
written, they invite exactly the change AGENTS.md now forbids — widening the
sandbox so a new harness starts.

Note that the ceiling IS readable in the ordinary sandbox: _CREW_READONLY_LEAVES
keeps it readable-not-writable for a script cron, and that docstring is correct
and unchanged. The withhold applies only to an ENFORCED harness's child, through
adapter_hidden_credential_dirs.

Provenance

Not drift. Both lists were introduced together in #11941 — neither
crew_host_runtime_leaves nor either constant exists at its parent — and the
prose landed in that same commit describing a set the commit never built. The OS
mask over the governance tree predates it: security_policy.json has been masked
since #7439. So the withheld disposition is the only disposition that has ever
shipped, and there is no earlier behaviour the prose could have been describing.

Found while reviewing #11941, where @buluoray had already flagged the same
contradiction in an unresolved review comment; the push after that review did not
address it.

Verification

  • test_sandbox_governance_mask.py + test_acp_tool_gate.py: 831 passed.
    These are the files that pin the pair complete and disjoint, and that assert
    crew_host_runtime_leaves() equals the readable list and never intersects the
    withheld one — so they are the tests that would notice if this were a code
    change wearing a docs label.
  • Inventory read from the loaded module rather than from the source: 9 readable,
    21 withheld, and the spec row's completed enumeration accounts for all 21.
  • black (pinned 26.3.1), isort, flake8, mypy --platform linux (1654 files),
    docs-lint, comment-history with COMMENT_HISTORY_BASE_REF=origin/main: all
    green.

Pattern harvest

The shape is a doc and a data structure landing in one commit and disagreeing
about the same consequence, with the prose stating the safer-sounding option and
the code stating the safe one. Same class as #11556's import-time assert, which
required five wording entries and shipped with two — an invariant that was
unsatisfiable in the commit that created it.

Both are caught by reading the constant instead of its docstring. The repo's
existing completeness pin already forces a NEW leaf to be classified; what it
cannot see is prose that misdescribes the classification of the leaves already
there. No mechanism is proposed for that here — the observation is that a
docstring is the wrong place to carry a security inventory when the list is forty
lines away and machine-readable.

@bolichen97
bolichen97 requested review from a team and CrysisDeu September 20, 2026 08:58
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 20, 2026
@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 4b7cbc78e606f514927578ff869e0455e75a7251 — 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: CONCERNS

The spec row hand-copies all 21 withheld leaves — the same unpinned prose duplicate of a machine-readable list that produced the defect this PR corrects.

Not justified as shipped

  • Item 4 — oversized: the harm (the row misstated the withheld set, listing 8 of 21) is removed by the corrected characterization plus a pointer; the full 21-name copy in agent-host-contract.md is delta with no consumer that cannot read sandbox._CREW_CHILD_WITHHELD_LEAVES, and no pin guards this copy the way test_sandbox_governance_mask guards the constant — the author's own description says a prose inventory "is the wrong place" when "the list is forty lines away and machine-readable".
    Subtraction: shrink the bucket-4 row's leaf enumeration to the constant's name plus the governance-family characterization; delete the per-leaf copy.
    Clears when: the enumeration is replaced by the pointer, or a reader of the spec who cannot open the constant is named.

What this change ships

Inventory (4 items) — 3 justified

Intent: make the docs stop telling the next harness author that an enforced child can read the governance ceiling — a FIX (docs contradicted shipped code; verified by reading sandbox.py:662-796: 9 readable, 21 withheld).

  1. Accessor docstring now names the nine actually-readable leaves, not "ceilings and consent records" — justified
  2. The boot-raise paragraph now reads as an accepted fail-closed cost with an explicit do-not-widen warning — justified
  3. Mask docstring no longer claims ceilings and consent records are excluded from the mask — justified
  4. Spec bucket-4 row corrected, withheld enumeration hand-expanded from 8 to 21 leaves — oversized: pointer to the pinned constant removes the same harm without an unpinned copy

[FIRST-PRINCIPLES-REVIEWED] 4b7cbc7

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify the spec row's completed 21-leaf enumeration against the loaded constants, since prose-vs-constant drift is exactly the defect this PR fixes.

[DESIGN-REVIEWED] 4b7cbc7

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

FINDING -- src/kiro_crew/sandbox.py:803 -- "is no input to an authorization decision" contradicts returned authorization sidecars such as .dev-grants.json and model state -> Fix: remove that classification.
[GPT-REVIEWED] 4b7cbc7

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

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

This PR is documentation-only: markdown prose in agent-host-contract.md and Python docstrings in tool_gate.py and sandbox.py. No executable line changed — no code path, no runtime behavior, so there is no concrete input, call path, or observable wrong outcome to ground any finding. The discovery pass correctly found no candidates, and I found no grounded runtime defect in the changed lines.

No findings.

[OPUS-REVIEWED] 4b7cbc7

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

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

@bolichen97

Copy link
Copy Markdown
Contributor Author

Blocked on base debt, not on this diff

Backend Tests (Windows) (1) is red here and cannot pass on any PR whose base is current main. Tracked as #12247, with my mechanism correction in this comment.

Four test/test_acp_runtime.py kill-summary tests fail because _kill_inner's Windows branch returns at runtime.py:2967, 63 lines before the single call site of _note_reaped_after_kill at :3030 — so the reap amendment is unreachable on Windows for every returncode. #12188 supplied the assertions; #12005 supplied the early return; each was green on its own base and they are red together, 7 minutes apart.

This PR is the control that shows it is base debt: it changes three prose passages in sandbox.py, tool_gate.py and one spec table, with no Python behaviour at all, and 831 tests over the two files that pin the leaf lists pass unchanged. Every other lane here is green.

Not folding that fix in — it is a behaviour change in the ACP runtime and belongs in its own review.

@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 20, 2026
Three passages describe `sandbox.crew_host_runtime_leaves()` as carrying
the governance ceilings and the consent records. It carries neither. The
set is `playwright-cli`, the authorization sidecars, the gateway-owned
run and decision records, and the operator's cloud configuration; every
ceiling, policy and consent document is in `_CREW_CHILD_WITHHELD_LEAVES`
forty lines above, under a comment that withholds them as one family
because each is an input to an authorization decision.

The code is right and has only ever had this one behaviour: both lists
were introduced together and the ceiling has been masked at the OS gate
since #7439. The prose was written in the same commit as the lists and
described a set that commit never built, so this is a wording defect
from the start rather than drift.

The dangerous half is not the inventory but the argument built on it.
The accessor's docstring presented the `boot_platform()` raise as a
reason the ceiling MUST be subtracted from the mask, while the withhold
list presents the same raise as the accepted cost of withholding it --
two statements in one file reaching opposite conclusions from one
consequence. The withhold list is the shipped behaviour, so the
docstring now states that the raise is accepted because it lands in the
safe direction, and says outright that the paragraph above it is not
licence to move a ceiling into the readable set to make a harness boot.

This matters because `harness-onboarding.md` sends the next harness
author to these two docstrings to learn which leaves a child may reach.
Read as written, they invite exactly the change `AGENTS.md` now forbids:
widening the sandbox so a new harness starts. The spec table is
corrected the same way, and its withheld enumeration is completed -- it
listed eight leaves of the twenty-one that are actually withheld.

Wording only. No list, no predicate and no behaviour changes; 831 tests
over the two files that pin the pair complete and disjoint pass
unchanged.
@bolichen97
bolichen97 force-pushed the docs/child-readable-leaves-wording branch from b82c8d6 to 4b7cbc7 Compare September 20, 2026 11:12
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved to 954fb69185 (carrying #12269, which fixed the shared Backend Tests (Windows) (1) blocker from #12247); CI re-running. Content unchanged -- still 3 files, +23/-12, wording only, patch-id ceee46e765e0. No main commit since the previous head touched src/kiro_crew/sandbox.py, src/kiro_crew/agent_sdk/tool_gate.py or docs/system-specs/modules/agent-host-contract.md.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 20, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) September 20, 2026 16:47
@bolichen97
bolichen97 merged commit b6d2c82 into main Sep 20, 2026
95 checks passed
@bolichen97
bolichen97 deleted the docs/child-readable-leaves-wording branch September 20, 2026 16:51
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 20, 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.

2 participants