Skip to content

refactor(acp): one launch record per self-served harness - #11428

Merged
bolichen97 merged 1 commit into
mainfrom
refactor/acp-per-backend-table
Sep 18, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
refactor/acp-per-backend-table

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

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.py goes from 7 sites to none. The measurement is below.

What changed (motivation → approach → change)

moving part before after
launch facts per self-served harness 4 constants + a protocol constant + a table row in acp/client.py one ACP_BACKEND_LAUNCH row in agent_sdk/backends.py
binary resolution one resolver + one cache global per harness _resolve_self_served_bin(backend) + one cache keyed by backend
_spawn arm a prologue per harness (cache, not-found message, argv, two labels) _resolve_self_served_launch() shared by every member
install probe _probe_<name> + component constant + _PROBES row per harness _probe_self_served bound to every member by membership
driver seams three functions per harness in drivers/acp.py three functions total, taking a backend id
provider label an if backend == branch per harness PROVIDER_LABEL_BY_BACKEND lookup
tool-gate label a row per harness read from the record
onboarding recipe names the per-harness probes and seams names the record and the membership-derived probe

Three 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_BIN and OPENCODE_INSTALL_COMMAND stay, because the OpenCode routing remedy in acp/client.py names 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.md moves 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.md names the shared seams in its readiness-probe and primary-binary rows. Every deleted symbol is gone from docs/, checked by grep over the full set. agent_sdk/host_auth.py records the accepted risk on adapter_own_leaves in 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.json was captured by scripts/update_acp_launch_goldens.py on 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._spawn for every id in ACP_BACKENDS_KNOWN and 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.py is the only writer, and running it against unmodified base source prints already 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.

file before after
src/kiro_crew/acp/client.py 7 0
src/kiro_crew/agent_sdk/backend_install.py 4 0
src/kiro_crew/providers/acp.py 4 2
src/kiro_crew/agent_sdk/tool_gate.py 2 0
src/kiro_crew/agent_sdk/drivers/acp.py 1 (3 functions) 0
src/kiro_crew/agent_sdk/backends.py 2 3
src/kiro_crew/acp_backends.py 2 2
src/kiro_crew/acp/types.py 2 3
test/test_harness_parity.py 3 0
test/test_agent_sdk_backend_install.py 2 0
test/test_acp_backend_kas.py 1 1
files 11 5
sites 30 11

The after side also runs python3 scripts/update_acp_launch_goldens.py once 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 in host_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's is_<harness>_backend properties have zero production readers; their only reader is the exactly-one ratchet in test_acp_backend_kas.py. They are why providers/acp.py and 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

  • 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 patrigao September 17, 2026 02:00
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 17, 2026
@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 9e77a06cec4df771e1099488847a3dbd56cdc6bb — 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 fixture predates the change: run scripts/update_acp_launch_goldens.py on the base commit and confirm it prints already matches — the golden's parity evidence rests on that claim.

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 (ACP_BACKEND_LAUNCH, launch_for, ACP_BACKENDS_SELF_SERVED_ACP) counted 5 production consumer files beyond the defining module (grep ACP_BACKEND_LAUNCH|launch_for|ACP_BACKENDS_SELF_SERVED_ACP in src/); the retained OPENCODE_BIN/OPENCODE_INSTALL_COMMAND have a live prose reader at acp/client.py:964-966 as the description claims. No default moves, no capability is removed, so lens 9 does not apply.

Not justified as shipped

  • Item 9 — rides along: the 13-line accepted-risk comment on adapter_own_leaves in host_auth.py is unrelated to launch-record consolidation, though declared in the description.

What this change ships

Inventory (9 items) — 8 justified

Intent: 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.

  1. One ACP_BACKEND_LAUNCH row per self-served harness replaces per-harness launch constants — justified
  2. One shared spawn resolution and one backend-keyed cache replace three per-harness spawn prologues and cache globals — justified
  3. One membership-bound install probe replaces three per-harness probes — justified
  4. Three driver seams taking a backend id replace nine per-harness seam functions — justified
  5. New launch golden (fixture, capture module, writer script) pins every known harness's argv, labels and env delta — justified
  6. Session provider label resolves through a PROVIDER_LABEL_BY_BACKEND table instead of an if-chain — justified
  7. Tool-gate refusal labels for members read from the launch record — justified
  8. Onboarding and host-contract docs rewritten to name the record, membership and golden — justified
  9. Accepted-risk prose comment added on adapter_own_leaves in host_auth.py — rides along (declared, comment-only)

[FIRST-PRINCIPLES-REVIEWED] 9e77a06

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

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Run scripts/update_acp_launch_goldens.py at the base commit once, confirming the fixture's captured-before-the-change claim — the parity proof rests on it.

[DESIGN-REVIEWED] 9e77a06

@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 9e77a06cec4df771e1099488847a3dbd56cdc6bb and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 9e77a06

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

@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 9e77a06cec4df771e1099488847a3dbd56cdc6bb — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 9e77a06

Verdict parsed from the review's SHA-scoped output markers for commit 9e77a06cec4df771e1099488847a3dbd56cdc6bb.

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

@iamwhatever
iamwhatever force-pushed the refactor/acp-per-backend-table branch from c6bc62d to 45bc3b1 Compare September 17, 2026 02:17
@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 17, 2026
@iamwhatever
iamwhatever force-pushed the refactor/acp-per-backend-table branch from 45bc3b1 to 284d9d9 Compare September 17, 2026 02:37
@iamwhatever

Copy link
Copy Markdown
Contributor Author

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:

OPENCODE_ACP_SUBCMD  _ENV_OPENCODE_BIN
GOOSE_BIN  GOOSE_ACP_SUBCMD  _ENV_GOOSE_BIN  GOOSE_INSTALL_COMMAND
DEEPSEEK_BIN  DEEPSEEK_ACP_PROFILE_ARGS  _ENV_DEEPSEEK_BIN  DEEPSEEK_INSTALL_COMMAND

Verified before deleting, counting only consumers outside their own definition block:

$ for n in OPENCODE_ACP_SUBCMD _ENV_OPENCODE_BIN GOOSE_BIN GOOSE_ACP_SUBCMD \
           _ENV_GOOSE_BIN GOOSE_INSTALL_COMMAND DEEPSEEK_BIN \
           DEEPSEEK_ACP_PROFILE_ARGS _ENV_DEEPSEEK_BIN DEEPSEEK_INSTALL_COMMAND; do
    echo "$n src=$(grep -rn "\b$n\b" src/ --include='*.py' \
      | grep -vE '^src/kiro_crew/acp/client.py:3[0-9][0-9]:' | wc -l)"
  done
# every line: src=0

GOOSE_BIN's only apparent hit was the string literal "GOOSE_BIN" in the record's own bin_env_var field, not the constant.

OPENCODE_BIN and OPENCODE_INSTALL_COMMAND are kept, and that is the one place the ruling does not apply: _opencode_readback_remedy reads both to build the operator-facing sentence for a failed config read-back. Two named readers, so they are not aliases with no consumer. They are now asserted equal to the record's fields, so they cannot drift from the row they are read out of.

The tests that spelled the deleted names now read launch_for(<backend>). That is a better assertion than before: it pins the record, which is what the spawn arm actually consumes.

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:

30e9fdc25a  test(acp): snapshot what every known harness is launched as
284d9d9015  refactor(acp): one launch record per self-served harness

Commit 1 adds only the capture, the script and the fixture — 4 files, 691 insertions, zero source changes — on this branch's base 814da82c3e. So the fixture provably predates the refactor rather than being asserted to.

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:

$ cd <worktree at 814da82c3e>
$ pytest test/test_acp_launch_goldens.py
12 passed
$ python3 scripts/update_acp_launch_goldens.py
test/fixtures/acp_launch_goldens.json already matches

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 _resolve_self_served_bin when it exists and the three per-harness resolvers when it does not. Their shape is exactly what commit 2 moves, so a capture hard-coded to either side would be comparing two different measurements rather than the same one twice. Commit 2 drops the base-shape branch, since that is the shape it removes — so the final tree carries no dead code for it.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Disposition: inherited from main, not this change — Frontend Tests (2).

The failing spec is DrivePage.test.tsx, in the aws_control builtin's website tree. This PR touches no website file at all:

$ git diff --name-only 814da82c3e..HEAD | grep -c '^website/'
0
$ git diff --name-only 814da82c3e..HEAD | grep -ci 'aws_control'
0

All 19 changed files are Python, under src/kiro_crew/{acp,agent_sdk,providers}, test/ and scripts/. There is no import path from a launch record for an ACP backend to a React page test, and no shared fixture between them.

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 main breakage or a genuine flake is the rerun's question, not this PR's.

@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 17, 2026
@iamwhatever
iamwhatever force-pushed the refactor/acp-per-backend-table branch from 284d9d9 to 8f66dd3 Compare September 17, 2026 03:27
@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 17, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Disposition: one red was mine and is fixed; the rest are inherited — Backend Tests (Windows) (1) mine; (3), (4), (6), Build Windows Installer (x64) not.

Mine — Backend Tests (Windows) (1), test_the_launch_of_every_known_harness_matches_the_golden, all 8 backends.

The diagnosis that it was a platform-dependent argv (separators, .cmd/.exe shims) is not what the wire shows. Every diff line in the whole shard log is one key:

$ grep -E "^\S+ E\s+[-+]" shard1.log | sed 's/^[^ ]* E *//' | sort | uniq -c
      8 +         'KIROCREW_SPAWNED': '1',

and for kiro pytest reports Omitting 3 identical items — argv, spawn_label and stderr_label all matched — with one differing item, env_added. So argv is byte-identical across POSIX and Windows for all eight, which makes the H13 claim stronger than stated rather than weaker. It holds because every path in the capture is a synthetic literal from a stubbed resolver; the real ladders, where casing normalisation and shim suffixes live, are not exercised here and are covered by their own tests.

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.

env_added is a DELTA, and it was measured against the ambient os.environ. That made the fixture a property of the recording process. Crew exports KIROCREW_SPAWNED=1 into every agent it spawns, and I recorded from inside an agent — verified:

KIROCREW_SPAWNED in recording env: '1'
value _spawn would set:            '1'
so it is filtered out of the delta here: True

So _spawn setting that variable was invisible to my capture, and any host without it disagrees. My test_no_golden_entry_carries_a_host_path guard could not catch this: it looks for host values present, and this defect is a key absent.

Fixed by pinning the parent environment (patch.dict(os.environ, fixed, clear=True)) so env_added is what _spawn contributes, on every host. An allowlist carries through only OS/interpreter variables _spawn never writes, and a new test asserts that allowlist cannot overlap the contributed set — otherwise a carried-through value could mask a contribution exactly as the ambient environment did. Pinning the parent also removed the host's KIROCREW_HOME, so the capture now pins config.paths._resolve_default_home to the run's temp dir rather than relying on an exported variable; without it the spawn path resolves and creates the operator's real ~/.kiro/crew.

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 _spawn writes, and assert the two answers are equal. Mutation-verified — revert the parent to dict(os.environ) and that test fails with "the capture reads the ambient environment".

Re-recording changed exactly one thing, which is the diagnosis confirmed:

$ git diff test/fixtures/acp_launch_goldens.json | grep '^[-+]' | grep -v '^[-+][-+]' | sort | uniq -c
      8 +      "KIROCREW_SPAWNED": "1",

The two-commit proof shape survives: commit 1 still carries only the capture, script and fixture on base 814da82c3e, and re-verified there it is 14 passed with the writer printing already matches.

Not mine. git diff --name-only 814da82c3e..HEAD is 19 Python files under src/kiro_crew/{acp,agent_sdk,providers}, test/ and scripts/; it touches nothing under kiro_crew/ledger, nothing fargate, no website file.

  • Backend Tests (Windows) (4) and (6) — LedgerError: data.agent: is required and absent, in test_ledger_retention.py and test_remove_slot_for_history_key.py. Two-point probe on the whole file: 149 passed on base 814da82c3e, 149 passed on this head — the change does not move it.
  • Backend Tests (Windows) (3) — test_fargate_launch_engine, begin_signin: [...] != [..., 'login_target']. A protocol-member mismatch in a subsystem this diff does not touch.
  • Build Windows Installer (x64) — .github/scripts/test-windows-installer.ps1:221, Start-Process … WaitForExit(120s): a stopwatch on NSIS install time. The wheel is where = src with exclude = test, and repo-root scripts/ is not a package, so none of the four files this PR adds ship in the installer; src/ is +317 −392, net −75 lines, so the payload is smaller than base.

Not claiming flaky on any of them — that needs two observations, and I have one each.

@iamwhatever
iamwhatever force-pushed the refactor/acp-per-backend-table branch from 8f66dd3 to 7e597e5 Compare September 17, 2026 03:37
@iamwhatever

Copy link
Copy Markdown
Contributor Author

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 _probe_opencode, _probe_goose, _probe_deepseek and opencode_cached_negative() in harness-onboarding.md. I grepped the full set of symbols this diff deletes — 30 names, including the ten launch constants, the three resolvers, the three cache globals, the nine driver seams, the three component constants and self_served_backends — across docs/, the root *.md and .github/. That found a second stale doc the review did not cite:

docs/system-specs/modules/agent-host-contract.md
  :164  opencode_cached_negative()  goose_cached_negative()  deepseek_cached_negative()
  :308  _resolve_deepseek_bin

Both are now updated. Re-run of the same grep over docs/, *.md and .github/ returns nothing.

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 ACP_BACKEND_LAUNCH and the shared paths resolve you from it — _resolve_self_served_bin, the per-backend cache, _resolve_self_served_launch (binary, argv, spawn label, stderr label), the dialect table, the probe, the tool-gate label. Membership is ACP_BACKENDS_SELF_SERVED_ACP, derived from the table's keys, so there is nothing else to register. What stays yours is only your routing, because that is a decision rather than a value.

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 _PROBES row at all — _probe_self_served is bound to every member and reads the component and command from the record — while a non-member still writes both, because its install shape is a decision (the adapters and Pi have two components, and which half is absent changes the remedy).

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 python3 scripts/update_acp_launch_goldens.py with the rewritten fixture committed in the same commit as the change, because the fixture diff is what shows a reviewer which harness moved. It also states the two things never to do: regenerate to turn a red green without saying in review why the launch moved, and regenerate to clear a kiro-cli row, which is the row H13 protects.

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. docs_lint passes and check_comment_history passes. The two advisories docs_lint prints (dead-identifier SessionStart, line-ref acp/client.py:3313) are pre-existing — the same two appear on base 814da82c3e in a clean worktree. 421 tests green including test_agent_host_contract_parity.py, which reads both edited docs.

The doc change is in commit 2, with the code it describes.

@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 17, 2026
@iamwhatever
iamwhatever force-pushed the refactor/acp-per-backend-table branch from 7e597e5 to 957b539 Compare September 17, 2026 06:29
@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 17, 2026
@github-actions github-actions Bot added the readiness: passed Eligible automated validation passed for the current revision label Sep 17, 2026
@iamwhatever
iamwhatever force-pushed the refactor/acp-per-backend-table branch from 51d7a84 to c79f933 Compare September 17, 2026 20:51
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Sep 17, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Disposition: inherited — Backend Tests (Windows) (7) on head c79f93345b fails four cases in test/test_session_control.py: test_create_refuses_unreadable_delegation_identity[OSError] (OSError: /private/identity/path), test_create_refuses_unreadable_delegation_identity[ValueError] (assert 400 == 403), and test_private_creator_cannot_change_memory[public-worker-canonical] / [writer-canonical] (both assert 'agent_store_mismatch' == 'memory_delegation_denied'). Nothing else in the shard fails.

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 session_control — git diff --name-only origin/main...HEAD | grep session_control → 0 — and it adds no session-creation, member-binding or memory-store code. The same four cases fail identically on the current Windows suite of five unrelated branches: run 35268389217 (feat/perpetual-mode-ui), 35268352128 (fix/project-picker-listing-failure-ux), 35267642060 (fix/pinned-prompt-scroll), 35266827438 (feat/ledger-session-parent), 35266401833 (fix/recover-provider-group-after-leader-reap). Five independent observations with the same failing set → deterministic breakage inherited from main, not flake.

Also note the same-round macOS Tests shard failing six test/test_pid_lifecycle.py::TestSyncKillProviderTree cases, disposed as inherited earlier in this PR on the evidence of three unrelated branches; it is unchanged here and unrelated to this diff.

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 .

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Disposition: inherited — Backend Tests (Windows) (5) on head c79f93345b fails two cases in test/test_member_session_control.py::TestMemberChildPrivateBinding: test_a_v1_child_writes_no_private_binding and test_global_caller_cannot_grant_a_child_private_authority. Nothing else in the shard fails.

Same family as the Backend Tests (Windows) (7) red disposed above: both are the private-memory binding path of session creation. This PR touches 21 files, none of them member_session_control — git diff --name-only origin/main...HEAD | grep member_session_control → 0 — and it adds no session-creation or memory-store code. The same two cases fail on the current Windows suite of four unrelated branches: run 35268389217 (feat/perpetual-mode-ui), 35268352128 (fix/project-picker-listing-failure-ux), 35267642060 (fix/pinned-prompt-scroll), 35266827438 (feat/ledger-session-parent). Four independent observations → deterministic breakage inherited from main, not flake.

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.
@iamwhatever
iamwhatever force-pushed the refactor/acp-per-backend-table branch from c79f933 to 9e77a06 Compare September 17, 2026 22:14
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Disposition: inherited — macOS Tests / Backend Tests (macOS) (3) on head 9e77a06cec fails seven cases in test/test_xdist_host_budget.py: test_alone_gets_the_whole_machine, test_an_unusable_xdist_env_var_is_inert, test_env_cap_lowers_the_ceiling, test_garbage_env_cap_falls_back_to_default, test_memory_binds_before_cores, test_second_run_takes_what_is_left, test_the_xdist_env_var_is_honoured_as_a_ceiling. Nothing else in the shard fails.

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 — git diff --name-only origin/main...HEAD | grep xdist → 0 — and it adds no test-runner or host-sizing code. The same file fails on the current macOS suite of four unrelated branches: run 35280316247 (feat/ledger-resolver), 35280217475 (fix/pod-mint-token-unix-socket), 35280161676 (fix/ledger-main-reds), 35280085608 (refactor/crew-log-rename). Four independent observations → deterministic breakage inherited from main, not flake.

The Windows test_session_control.py / test_member_session_control.py reds disposed on the previous head are gone here: this head sits on main 2627b0407c, which carries their fix (#11593).

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 .

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

Copy link
Copy Markdown
Contributor Author

Disposition: accepted as a declared rider — span=982046973f36 (Item 9: the accepted-risk comment on adapter_own_leaves in host_auth.py rides along).

The finding is correct on the facts: src/kiro_crew/agent_sdk/host_auth.py is a comment-only change, it does not participate in the launch-record consolidation, and on the strict one-change-one-PR rule it would ship separately. It is kept here for three reasons.

It was asked for as part of this round's brief, not discovered mid-refactor. The instruction was to state the accepted risk on adapter_own_leaves in the maintainer's own words while the self-served harness declarations were being read end to end — this PR is the pass that read all of them.

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 #: lines to a docstring attribute, changes no code path, no test, no gate, and cannot alter behaviour — the launch goldens are byte-identical with it in place.

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.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Disposition: accepted as a declared rider — span=982046973f36 (Item 9: the accepted-risk comment on adapter_own_leaves in host_auth.py rides along).

The finding is correct on the facts: src/kiro_crew/agent_sdk/host_auth.py is a comment-only change, it does not participate in the launch-record consolidation, and on the strict one-change-one-PR rule it would ship separately. It is kept here for three reasons.

It was asked for as part of this round's brief, not discovered mid-refactor. The instruction was to state the accepted risk on adapter_own_leaves in the maintainer's own words while the self-served harness declarations were being read end to end — this PR is the pass that read all of them.

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 #: lines to a docstring attribute, changes no code path, no test, no gate, and cannot alter behaviour — the launch goldens are byte-identical with it in place.

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.

@bolichen97
bolichen97 merged commit abb8ee4 into main Sep 18, 2026
90 of 92 checks passed
@bolichen97
bolichen97 deleted the refactor/acp-per-backend-table branch September 18, 2026 00:28
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 18, 2026
bolichen97 pushed a commit that referenced this pull request Sep 18, 2026
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.
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…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>
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
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.
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