Repository navigation
refactor(acp): one launch record per self-served harness - #11428
Conversation
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify the fixture predates the change: run The record values were checked against the deleted constants in the diff (binary, argv tail, override var, install command, protocol version, error text) and all match byte-for-byte, so launch parity is corroborated independently of the fixture's origin. New surface ( Not justified as shipped
What this change shipsInventory (9 items) — 8 justifiedIntent: ADDITION of one shared launch record so a fifth self-served harness edits 11 sites instead of 30 — a consolidation that deletes three duplicated copies, provenance measured from four merged onboardings.
[FIRST-PRINCIPLES-REVIEWED] 9e77a06 |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Run [DESIGN-REVIEWED] 9e77a06 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 4.8 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
c6bc62d to
45bc3b1
Compare
45bc3b1 to
284d9d9
Compare
|
Disposition: both items fixed — item 9 (launch-constant aliases with no reader) and item 8 (the squash erased the base-capture proof). Item 9 — fixed, ten constants deleted. With the record in place these had no reader outside their own tests: Verified before deleting, counting only consumers outside their own definition block:
The tests that spelled the deleted names now read Item 8 — fixed, two-commit shape restored. The finding is right that prose is not proof, and the squash destroyed the only structural evidence for the H13 byte-identical claim. The branch is now: Commit 1 adds only the capture, the script and the fixture — 4 files, 691 insertions, zero source changes — on this branch's base Commit 1 is green on base source, which is what makes it proof rather than decoration. Verified in a separate worktree checked out at the base commit, with only those four files added: The second command is the sentence from the PR body made mechanical: running the writer against unmodified base source reproduces the committed fixture byte-for-byte. Making commit 1 green on base needed one thing worth naming, because it is a constraint the finding implies but does not state: the capture resolves the spawn resolvers by name, taking |
|
Disposition: inherited from The failing spec is All 19 changed files are Python, under Not claimed as flaky on this evidence — one observation is not two. The claim here is narrower and checkable: the diff cannot reach the failing spec. Whether the red is a |
284d9d9 to
8f66dd3
Compare
|
Disposition: one red was mine and is fixed; the rest are inherited — Mine — The diagnosis that it was a platform-dependent argv (separators, and for Neither remedy applies, then: there is no platform-dependent field to normalise (a) and nothing structural to key by platform (b). The defect is different and worse.
So Fixed by pinning the parent environment ( Tested in both directions on one backend: capture once with those variables absent from the ambient environment, once with them present and set to the values Re-recording changed exactly one thing, which is the diagnosis confirmed: The two-commit proof shape survives: commit 1 still carries only the capture, script and fixture on base Not mine.
Not claiming flaky on any of them — that needs two observations, and I have one each. |
8f66dd3 to
7e597e5
Compare
|
Disposition: fixed — the onboarding recipe named symbols this change deletes, so it would walk a fifth-harness author into re-adding what the record collapses. The finding is right and it is the one that mattered most in this PR: a refactor that leaves the spec describing the old shape has not reduced the onboarding cost, it has only moved the cost into a wrong instruction. Wider than the four names cited. The review named Both are now updated. Re-run of the same grep over What the recipe says now. Stage 3 leads with the question that decides the whole stage: does this harness serve ACP from its own binary? If yes, add a row to It also says plainly what NOT to do: a harness that is not of that shape must not add a row. A record whose fields do not describe the launch is worse than no record, because the shared resolver would spawn the wrong binary instead of failing. Stage 6 records that a member needs no probe and no Gates and tests now names the launch golden: what it records, that a new id fails until the fixture carries a row, that the test is read-only, and that regeneration is The three worked examples' Stage-6 rows now read "no probe of its own", and DeepSeek's says why its command names the host binary rather than the ACP package — that package is a plugin with no executable, so advice naming it would not produce a runnable harness. That is the concrete case for the command being data in the record. Gates. The doc change is in commit 2, with the code it describes. |
7e597e5 to
957b539
Compare
51d7a84 to
c79f933
Compare
|
Disposition: inherited — Why it is not this PR's: the failures are in the private-memory delegation path of session creation. This PR touches 21 files, none of them Also note the same-round Evidence: https://github.com/kirodotdev/KiroCrew/actions/runs/35273330027/job/105384305384 (this PR), https://github.com/kirodotdev/KiroCrew/actions/runs/35268389217 , https://github.com/kirodotdev/KiroCrew/actions/runs/35268352128 , https://github.com/kirodotdev/KiroCrew/actions/runs/35267642060 , https://github.com/kirodotdev/KiroCrew/actions/runs/35266827438 , https://github.com/kirodotdev/KiroCrew/actions/runs/35266401833 . |
|
Disposition: inherited — Same family as the Evidence: https://github.com/kirodotdev/KiroCrew/actions/runs/35273330027/job/105384305280 (this PR), https://github.com/kirodotdev/KiroCrew/actions/runs/35268389217 , https://github.com/kirodotdev/KiroCrew/actions/runs/35268352128 , https://github.com/kirodotdev/KiroCrew/actions/runs/35267642060 , https://github.com/kirodotdev/KiroCrew/actions/runs/35266827438 . |
Three harnesses serve ACP from their own binary, and each carried its own copy of the same six facts: a binary name, an argv tail, an override variable, an install command, a protocol version and a display name. So the same code existed three times -- three resolvers walking the same three rungs, three install probes of the same shape, three sets of driver seams, three not-found messages assembled the same way. Now there is one record per harness. ACP_BACKEND_LAUNCH in agent_sdk/backends.py holds those six facts plus one prose hint, and everything shared reads it: one resolver, one cache keyed by backend, one install probe bound to each id by membership, the protocol-version table, the tool-gate label, and provider_label as a mapping lookup rather than a branch per harness. Each harness's own ROUTING does not move. OpenCode's config read-back, goose's mode seed, DeepSeek's absence of either and pi's gate extension are decisions, not values, and stay where they were. Kiro-cli is not a member and never reaches the new code, so its construction path gains no step and no conditional. Measured, not estimated: adding a fake eighth harness of this shape costs 11 sites in 5 files, against 30 sites in 11 files on this branch's base. acp/client.py goes from 7 sites to none. The proof that nothing moved is test/fixtures/acp_launch_goldens.json, whose bytes were CAPTURED ON THE UNMODIFIED BASE and are carried into this commit unchanged. It records, for each id in ACP_BACKENDS_KNOWN, the argv AcpClient._spawn hands the process factory, the label the spawn is logged under, the label stderr is drained under, and the environment variables the spawn adds to the ones it inherited. A snapshot taken after a refactor proves the refactor agrees with itself; taken before, it proves the refactor moved nothing. All seven known harnesses launch byte-identically, kiro-cli and KAS included -- kiro-cli above all, whose construction path harness-parity H13 keeps free of work added for an adapter. Two things make the recording a property of the CODE rather than of the machine. The environment delta is measured against a FIXED parent environment, not the ambient one: Crew sets KIROCREW_SPAWNED in every agent it spawns, so a capture taken from inside an agent would record _spawn setting it as no change at all, and a clean runner would then disagree with the fixture. The parent is pinned, and an allowlist carries through only variables _spawn never writes -- a test asserts that allowlist cannot overlap what _spawn contributes. The default data home is pinned to the run's temp directory, because the fixed parent no longer carries whatever KIROCREW_HOME the host had, and an unpinned resolution would create the operator's real ~/.kiro/crew. The test is strictly read-only, and scripts/update_acp_launch_goldens.py is the only writer: a test that rewrites a tracked fixture leaves checkout state behind, and the thing meant to catch a change must not also be able to bless it. Same split as test/acp_frame_replay_harness.py and scripts/update_acp_frame_snapshots.py. The capture also restores every resolver cache it disturbs, because it clears them so each backend resolves afresh and the stubbed resolvers then write synthetic paths into process-wide state; left there, a later test in the same worker would read this file's fiction. The launch constants those three harnesses exported are gone with them: with the record in place they had no reader outside their own tests, and the tests now read the record. OPENCODE_BIN and OPENCODE_INSTALL_COMMAND stay, because the routing remedy in this module names both in prose. The onboarding recipe moves with the code, which matters more than it looks: a spec that still named the deleted per-harness probes and seams would walk a fifth-harness author into re-adding exactly what this collapses. Stage 3 now asks first whether the harness serves ACP from its own binary and points at the record; Stage 6 records that a member needs no probe and no registry row; the gates section names the launch golden and its writer, and says to commit the regenerated fixture with the change. The host contract's readiness-probe and primary-binary rows name the shared seams. Every deleted symbol is gone from docs/ -- checked by grep over the full set, not only the names a review cited. Also records the accepted risk on host_auth's adapter_own_leaves: the leaf is the harness's own provider credential, the model already holds its use-power through the harness, and what the exclusion adds is exfiltration by a spawned shell.
c79f933 to
9e77a06
Compare
|
Disposition: inherited — Why it is not this PR's: those cases size the pytest-xdist worker budget from host memory and cores. This PR touches 21 files, none of them the xdist budget — The Windows Evidence: https://github.com/kirodotdev/KiroCrew/actions/runs/35280983316/job/105405716819 (this PR), https://github.com/kirodotdev/KiroCrew/actions/runs/35280316247 , https://github.com/kirodotdev/KiroCrew/actions/runs/35280217475 , https://github.com/kirodotdev/KiroCrew/actions/runs/35280161676 , https://github.com/kirodotdev/KiroCrew/actions/runs/35280085608 . |
|
Disposition: accepted as a declared rider — span=982046973f36 (Item 9: the accepted-risk comment on The finding is correct on the facts: It was asked for as part of this round's brief, not discovered mid-refactor. The instruction was to state the accepted risk on Its subject is the same three harnesses. The risk carried is the exclusion re-opening a harness's own provider credential, and the harnesses carrying it include exactly the self-served ones whose launch facts this PR collapses; a reader who arrives at the record and then at the declaration meets both in one place. The blast radius is zero. It adds thirteen The description declares it, so it is not a silent rider. If a reviewer would rather see it split, I will lift it into its own PR on request; I have not done so pre-emptively because splitting a comment costs a second full CI round for no behavioural gain. |
|
Disposition: accepted as a declared rider — span=982046973f36 (Item 9: the accepted-risk comment on The finding is correct on the facts: It was asked for as part of this round's brief, not discovered mid-refactor. The instruction was to state the accepted risk on Its subject is the same three harnesses. The risk carried is the exclusion re-opening a harness's own provider credential, and the harnesses carrying it include exactly the self-served ones whose launch facts this PR collapses; a reader who arrives at the record and then at the declaration meets both in one place. The blast radius is zero. It adds thirteen The description declares it, so it is not a silent rider. If a reviewer would rather see it split, I will lift it into its own PR on request; I have not done so pre-emptively because splitting a comment costs a second full CI round for no behavioural gain. |
Two PRs merged five seconds apart and neither saw the other: #11428 added the ACP_BACKENDS_SELF_SERVED_ACP set to backends.py, and #11431 added test_every_capability_set_is_classified_by_the_card, which fails for any ACP_BACKENDS_* set that reaches no bucket. main has been red on that test since (Backend Tests shard 2 on every PR). The set is driver-internal by its own docstring: it answers whether a harness's whole launch is a row of ACP_BACKEND_LAUNCH, which only the spawn path, the install probe and the driver seams ask. The session starts either way, and a wrong membership is a launch that fails -- a defect, not a capability a reader would pick a harness for. So it goes in OFF_CARD_SETS with that reason, the bucket the module documents for exactly this case. No card changes: OFF_CARD_SETS entries render nothing.
…11428) Three harnesses serve ACP from their own binary, and each carried its own copy of the same six facts: a binary name, an argv tail, an override variable, an install command, a protocol version and a display name. So the same code existed three times -- three resolvers walking the same three rungs, three install probes of the same shape, three sets of driver seams, three not-found messages assembled the same way. Now there is one record per harness. ACP_BACKEND_LAUNCH in agent_sdk/backends.py holds those six facts plus one prose hint, and everything shared reads it: one resolver, one cache keyed by backend, one install probe bound to each id by membership, the protocol-version table, the tool-gate label, and provider_label as a mapping lookup rather than a branch per harness. Each harness's own ROUTING does not move. OpenCode's config read-back, goose's mode seed, DeepSeek's absence of either and pi's gate extension are decisions, not values, and stay where they were. Kiro-cli is not a member and never reaches the new code, so its construction path gains no step and no conditional. Measured, not estimated: adding a fake eighth harness of this shape costs 11 sites in 5 files, against 30 sites in 11 files on this branch's base. acp/client.py goes from 7 sites to none. The proof that nothing moved is test/fixtures/acp_launch_goldens.json, whose bytes were CAPTURED ON THE UNMODIFIED BASE and are carried into this commit unchanged. It records, for each id in ACP_BACKENDS_KNOWN, the argv AcpClient._spawn hands the process factory, the label the spawn is logged under, the label stderr is drained under, and the environment variables the spawn adds to the ones it inherited. A snapshot taken after a refactor proves the refactor agrees with itself; taken before, it proves the refactor moved nothing. All seven known harnesses launch byte-identically, kiro-cli and KAS included -- kiro-cli above all, whose construction path harness-parity H13 keeps free of work added for an adapter. Two things make the recording a property of the CODE rather than of the machine. The environment delta is measured against a FIXED parent environment, not the ambient one: Crew sets KIROCREW_SPAWNED in every agent it spawns, so a capture taken from inside an agent would record _spawn setting it as no change at all, and a clean runner would then disagree with the fixture. The parent is pinned, and an allowlist carries through only variables _spawn never writes -- a test asserts that allowlist cannot overlap what _spawn contributes. The default data home is pinned to the run's temp directory, because the fixed parent no longer carries whatever KIROCREW_HOME the host had, and an unpinned resolution would create the operator's real ~/.kiro/crew. The test is strictly read-only, and scripts/update_acp_launch_goldens.py is the only writer: a test that rewrites a tracked fixture leaves checkout state behind, and the thing meant to catch a change must not also be able to bless it. Same split as test/acp_frame_replay_harness.py and scripts/update_acp_frame_snapshots.py. The capture also restores every resolver cache it disturbs, because it clears them so each backend resolves afresh and the stubbed resolvers then write synthetic paths into process-wide state; left there, a later test in the same worker would read this file's fiction. The launch constants those three harnesses exported are gone with them: with the record in place they had no reader outside their own tests, and the tests now read the record. OPENCODE_BIN and OPENCODE_INSTALL_COMMAND stay, because the routing remedy in this module names both in prose. The onboarding recipe moves with the code, which matters more than it looks: a spec that still named the deleted per-harness probes and seams would walk a fifth-harness author into re-adding exactly what this collapses. Stage 3 now asks first whether the harness serves ACP from its own binary and points at the record; Stage 6 records that a member needs no probe and no registry row; the gates section names the launch golden and its writer, and says to commit the regenerated fixture with the change. The host contract's readiness-probe and primary-binary rows name the shared seams. Every deleted symbol is gone from docs/ -- checked by grep over the full set, not only the names a review cited. Also records the accepted risk on host_auth's adapter_own_leaves: the leaf is the harness's own provider credential, the model already holds its use-power through the harness, and what the exclusion adds is exfiltration by a spawned shell. Co-authored-by: zejiangg <zejiangg@amazon.com>
Two PRs merged five seconds apart and neither saw the other: kirodotdev#11428 added the ACP_BACKENDS_SELF_SERVED_ACP set to backends.py, and kirodotdev#11431 added test_every_capability_set_is_classified_by_the_card, which fails for any ACP_BACKENDS_* set that reaches no bucket. main has been red on that test since (Backend Tests shard 2 on every PR). The set is driver-internal by its own docstring: it answers whether a harness's whole launch is a row of ACP_BACKEND_LAUNCH, which only the spawn path, the install probe and the driver seams ask. The session starts either way, and a wrong membership is a launch that fails -- a defect, not a capability a reader would pick a harness for. So it goes in OFF_CARD_SETS with that reason, the bucket the module documents for exactly this case. No card changes: OFF_CARD_SETS entries render nothing.
Problem / Motivation
Four harnesses were onboarded as ACP backends in a row: OpenCode (#10006), Pi (#10334), DeepSeek Harness (#10373) and goose (#10939). Three of them are the same shape — one binary that serves ACP itself. Each one had to edit the same places again.
Counted from the four merged diffs, a harness of that shape had to touch 26 sites across 9 files outside a membership set. Most of those are values, not decisions: a binary name, an argv tail, an override variable, an install command, a protocol version, a display name.
Why it matters
The rule for this work: refactor only if it measurably reduces what a fifth harness must edit. If the number does not drop, document why and stop.
It drops from 30 sites in 11 files to 11 sites in 5 files.
acp/client.pygoes from 7 sites to none. The measurement is below.What changed (motivation → approach → change)
acp/client.pyACP_BACKEND_LAUNCHrow inagent_sdk/backends.py_resolve_self_served_bin(backend)+ one cache keyed by backend_spawnarm_resolve_self_served_launch()shared by every member_probe_<name>+ component constant +_PROBESrow per harness_probe_self_servedbound to every member by membershipdrivers/acp.pyif backend ==branch per harnessPROVIDER_LABEL_BY_BACKENDlookupThree harnesses served ACP from their own binary, and each carried its own copy of the same six facts. So the same code existed three times. The record holds those facts plus one prose hint for what an operator might otherwise try to install, and everything shared reads it. The ten per-harness launch constants those three exported are gone with them: with the record in place they had no reader outside their own tests, and the tests read the record.
OPENCODE_BINandOPENCODE_INSTALL_COMMANDstay, because the OpenCode routing remedy inacp/client.pynames both in prose.What does not move is each harness's own routing. OpenCode's config read-back, goose's mode seed, DeepSeek's absence of either and Pi's gate extension are decisions, not values, and stay exactly where they were. Kiro-cli is not a member and never reaches the new code, so its construction path gains no step and no conditional.
The onboarding recipe in
docs/system-specs/modules/harness-onboarding.mdmoves with the code, which matters more than it looks: a spec still naming the deleted probes and seams would walk a fifth-harness author into re-adding what this collapses. Stage 3 asks first whether the harness serves ACP from its own binary and points at the record; Stage 6 records that a member needs no probe and no registry row; the gates section names the launch golden and its writer.docs/system-specs/modules/agent-host-contract.mdnames the shared seams in its readiness-probe and primary-binary rows. Every deleted symbol is gone fromdocs/, checked by grep over the full set.agent_sdk/host_auth.pyrecords the accepted risk onadapter_own_leavesin prose: the leaf is the harness's own provider credential, the model already holds its use-power through the harness, and what the exclusion adds is exfiltration by a spawned shell.Tests
The launch golden is the proof, and it predates the change.
test/fixtures/acp_launch_goldens.jsonwas captured byscripts/update_acp_launch_goldens.pyon the unmodified base — before a single source line moved — and is carried into this commit byte-for-byte unchanged. The refactor is then asserted against those bytes, so a snapshot that agrees is a snapshot that predates what it judges. All seven known harnesses launch identically before and after, kiro-cli and KAS included. That is the answer to harness-parity H13 as evidence, not a sentence. (Earlier revisions of this PR kept the capture as its own commit on the base; the history is in the PR's revision list, and the fixture bytes are the same ones.)The capture drives
AcpClient._spawnfor every id inACP_BACKENDS_KNOWNand records the argv handed to the process factory, the spawn label, the stderr label, and the environment variables the spawn adds. Three properties make the fixture a property of the code rather than of the machine, and each has a test: the capture resolves the spawn resolvers by name, so it reads the same on both sides of the shape change; the environment delta is measured against a fixed parent, so a variable the recording host already exported (KIROCREW_SPAWNED, which Crew sets in every agent it spawns) still appears — tested in both directions, ambient-absent and ambient-present; and every resolver cache the capture disturbs is restored, so a later test in the same worker never reads the capture's synthetic paths.The test is strictly read-only.
scripts/update_acp_launch_goldens.pyis the only writer, and running it against unmodified base source printsalready matches. The install-probe cases are parameterized over launch-table membership, and the provider-label ratchet reads the production mapping and drives the real function over every known id.788 tests green across 15 files locally. mypy clean. flake8, isort and black clean. Gates green: harness-parity, comment-history, agent-sdk-boundary, docs_lint, black baseline.
Manual verification
The go/no-go measurement. A fake eighth harness of the self-served shape, added twice — once on the base commit, once on this branch — and driven to the same test bar.
src/kiro_crew/acp/client.pysrc/kiro_crew/agent_sdk/backend_install.pysrc/kiro_crew/providers/acp.pysrc/kiro_crew/agent_sdk/tool_gate.pysrc/kiro_crew/agent_sdk/drivers/acp.pysrc/kiro_crew/agent_sdk/backends.pysrc/kiro_crew/acp_backends.pysrc/kiro_crew/acp/types.pytest/test_harness_parity.pytest/test_agent_sdk_backend_install.pytest/test_acp_backend_kas.pyThe after side also runs
python3 scripts/update_acp_launch_goldens.pyonce to admit the new harness to the fixture — a command, not an edit. Both sides finish on the same residual failures from three sites outside the delta: the auth declaration inhost_auth.py, a pinned known-set literal and a pinned payload literal.Screenshots / video
N/A — no user-visible surface changes.
Related Issues
No linked issue: this is a refactor with no filed issue behind it. The four onboardings above are cited as the source of the measurement, not as work this closes — all are already merged, so no closing keyword applies.
Remaining site, deliberately not collapsed
AcpProvider'sis_<harness>_backendproperties have zero production readers; their only reader is the exactly-one ratchet intest_acp_backend_kas.py. They are whyproviders/acp.pyand that test still cost 3 of the 11 remaining sites. A record-driven ratchet would reach only the 3 member ids of 8 known, which is strictly weaker than what the test pins today, so the properties stay.Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)