Skip to content

fix(kas): decide the engine switch from a bot's own harness pin - #31802

Merged
bolichen97 merged 1 commit into
mainfrom
fix/26629-kas-route-follows-pin
Nov 7, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/26629-kas-route-follows-pin

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A Bot that pins its own harness gets the KAS engine switch its own pin allows: a Kiro CLI pin stays on kiro-cli, a KAS pin may move onto Kiro Crew's own engine.

When kiro-cli's relay cannot run, a KAS spawn moves onto Kiro Crew's own engine, except for a stored Kiro CLI pick, which stays on kiro-cli. That exception read only the installation's agent.acp_backend, never the Bot's own agents.<name>.acp_backend:

  • a Bot pinned kiro under a global kas could be moved onto Kiro Crew's engine;
  • a Bot pinned kas under a global kiro could never switch, so it failed on a missing or signed-out kiro-cli.

Why it matters

A Bot's harness pin exists so the Bot runs where its owner put it. Today the installation's choice overrides the pin in exactly the case where the route matters: a Kiro CLI Bot quietly runs another engine with another sign-in, and a KAS Bot on a host without a working kiro-cli cannot start at all.

Not a goal

  • The second item deferred into KAS bundle-route switch reads only the global acp_backend, not a mate's own pin #26629: a kiro-cli without the v3 engine still takes the boot floor (KAS marked unservable, Kiro CLI selected). Doctor, kirocrew kas route, the setup gate and the glibc floor have to agree on that first, so the issue stays open for it.
  • Readers that describe the installation rather than one spawn (kirocrew doctor, kirocrew kas route, the install probe, /api/models?backend=) keep reading the installation's pick.
  • An unpinned Bot on the member route (agent.member_acp_backend) is still judged by agent.acp_backend. Whether a defaulted member route counts as choosing KAS is a separate call.
  • A per-spawn backend= override on a pinned Bot's worker is judged by the Bot's pin, not by the override.

What changed (motivation → approach → change)

A Bot pinned to a harness had its KAS route decided by the installation's harness choice instead of its own.

The route rule had no way to see the pin: SpawnContext did not carry it, and the KAS process is started far from where the pin is read. The pin that matters is the one the backend selection used, and an explicit backend= override outranks the pin there. So the provider factory works out the pin in the selection's order and the provider carries it to every process it starts. A pinned Bot's DM and worker sessions skip the warm pool, and a companion runtime is keyed to one parent session, so the pin can ride on the process.

Where Change
rule 2, acp/kas_route.py automatic_switch_allowed(pin): the session's pin decides when it has one, else the installation's pick
factory, crewmate_harness.py, config/loader_config.py route_pin: the stored Bot pin, or none when an explicit override chose the harness; passed to the provider
provider, agent_sdk/drivers/acp.py, providers/acp.py, providers/base.py carries it as harness_pin, declared on LLMProvider with an empty default
spawn seam, acp/harness/base.py, acp/runtime_class.py, acp/runtime_spawn_launch.py, providers/acp_runtime_start.py SpawnContext.harness_pin, from AcpRuntime(harness_pin=) on the first spawn and the resume respawn; the KAS harness passes it to the rule
companion runtime, session_allocation_parts/companions.py takes its parent provider's pin
docs the acp-client spec states the per-pin rule and why a per-process pin is sound; the shipped configuration.md says which pick a session is judged by

An explicit backend= override on a pinned Bot's worker now carries no pin, so that worker keeps the installation's pick, as on main (review finding on the first head).

Backwards compatibility

Compatible: a session with no Bot pin, or one started with an explicit backend= override, reads the installation's pick exactly as before; automatic_switch_allowed() with no argument is unchanged; the new SpawnContext, AcpRuntime, AcpProvider and build_acp_provider arguments and the LLMProvider.harness_pin property default to "".

Removes nothing: no key, record, path or function is removed; the only behaviour that changes is which stored pick the route rule reads for a session its Bot pin started.

Tests

  • test_kas_route.py::TestRuleTwoReadsTheSessionsPin replaces TestRuleTwoIsGlobalOnly, which pinned the old global-only rule for this issue: with no pin the installation's pick decides; with no kiro-cli, a kiro pin under a global kas gets kiro-cli's own missing error and never touches the bundle, and a kas pin under a global kiro spawns Kiro Crew's engine.
  • test_kas_route.py::TestThePinReachesTheSpawn: the factory hands a pinned Bot's pin to the provider, and no pin when the Bot is started with backend_override="kas"; the provider builds its runtime with its pin; the runtime hands the pin to the harness; a companion runtime takes its parent provider's.
  • The conftest floor and two test doubles of the rule take the new argument; test_runtime_bindings.py and test_acp_bindings.py pin the new constructor arguments and property; the test_session_coverage.py provider double declares the new capability.

Proof: PROVEN test/test_acp_bindings.py::test_the_member_set_is_the_frozen_inventory, test/test_acp_bindings.py::test_each_member_keeps_its_kind_shape_and_owner[init], test/test_runtime_bindings.py::test_each_member_keeps_its_kind_shape_and_owner[init], test/test_runtime_bindings.py::test_the_constructor_keeps_its_type_hints (head 0ce035c)

The factory test fails with either half of the fix removed (assert 'kiro' == '' without the override check, assert '' == 'kiro' when the factory or the driver passes no pin) and passes with it.

Determinism: TestThePinReachesTheSpawn passed 20 runs at -n0; all 731 tests of the four changed test files passed in a shuffled order (seed 26629).

Manual verification

N/A — unit coverage sufficient: the change is one config read and a value passed through the provider into the spawn, each hop tested; a live repro needs a host where kiro-cli's relay cannot run, which the harness tests stand in for.

Screenshots / video

N/A — no frontend change.

Related Issues

Part of #26629

Follow-up from #26393.

Sibling sweep

Swept: git grep -nE "automatic_switch_allowed|acp_backend_stored_as_kiro|kas_spawn_takes_bundle|crewmate_stored_pin\(" -- src/
Sibling: src/kiro_crew/acp/kas_route.py:233 -- not affected -- describes the installation for doctor and kas route, which have no session and so no pin
Sibling: src/kiro_crew/crewmate_harness.py:451 -- not affected -- a ?backend= query names a harness, not a session, so it cannot tell a Kiro CLI pick running on KAS from a KAS pin
Sibling: src/kiro_crew/agent_sdk/backend_install.py:218 -- not affected -- the install probe describes KAS for the installation
Sibling: src/kiro_crew/auth/whoami.py:90 -- not affected -- the sign-in owner answers for the installation's harness
Sibling: src/kiro_crew/kiro_on_kas_notice.py:52 -- not affected -- the once-only notice is about the installation's own Kiro CLI pick
Sibling: src/kiro_crew/agent_sdk/backends.py:903 -- not affected -- the v3 probe decides how the installation's stored pick loads, before any session
Sibling: src/kiro_crew/cli_doctor_parts/kas_relay.py:87 -- not affected -- doctor's engine row describes the installation
Sibling: src/kiro_crew/slack/gateway_runtime/process_entry.py:294 -- not affected -- the boot floor wait is for the installation's pick
Sibling: src/kiro_crew/dashboard/handlers/agent_catalog.py:294 -- not affected -- a display read of the pin, never a route input

Pattern harvest

Not generalizable: one rule shipped scoped to the installation's choice with the per-Bot case deferred to this issue; there is no shared code shape a lint could catch.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 6, 2026 20:58
@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 21:13
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 6be76fe387818bcc5e09b9909c4bee3267784c4f touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 6be76fe387818bcc5e09b9909c4bee3267784c4f — 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 does not.

First-Principles-Verdict: PASS

Nothing blocks. Each new field carries the pin from the factory to the spawn, and the pin this PR deletes had itself named #26629 as the change it was waiting for.

What this change ships

Inventory (7 items) — 7 justified

Intent: a Bot that pins its own harness gets the KAS engine switch its own pin allows, not the one the installation's pick allows. This is a FIX.

  1. A Bot pinned to KAS, under a global Kiro CLI pick, now moves onto Kiro Crew's own engine when kiro-cli is missing or signed out — justified
  2. A Bot pinned to Kiro CLI, under a global KAS pick, now stays on kiro-cli instead of moving to Kiro Crew's engine — justified
  3. A pinned Bot's worker started with an explicit backend= override is still judged by the installation's pick — justified
  4. A companion runtime takes its parent's pin — justified
  5. The pin travels through the factory, provider, runtime and spawn: route_pin, harness_pin on SpawnContext, AcpRuntime, AcpProvider, build_acp_provider and LLMProvider, and automatic_switch_allowed(pin); every new argument defaults to "" — justified
  6. The shipped configuration.md now says which pick a session is judged by — justified
  7. The acp-client spec states the per-pin rule and drops the "tracked in 26629" gap — justified

[FIRST-PRINCIPLES-REVIEWED] 6be76fe

Description read

[DESCRIPTION-READ] 64a6c91f9c388948caeee95528eb97bc3390b1ce952460d620639bbc28183cac

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 6be76fe387818bcc5e09b9909c4bee3267784c4f — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The pin comes from the same selection order the factory uses, so the override precedence holds. Pinned DM and worker sessions skip the warm pool (bypass_member), so carrying the pin per process is sound.

Notes

  • TestRuleTwoIsGlobalOnly pinned the global-only rule. The spec named that rule as a known gap tracked in KAS bundle-route switch reads only the global acp_backend, not a mate's own pin #26629, so replacing the test is a deliberate fix of a deferred gap, not a reversed decision.
  • The pin is a free string checked only by != "kiro". Any pin other than kiro lets the session switch engines, so a new Kiro CLI pick spelled another way would have to update rule 2.

[DESIGN-REVIEWED] 6be76fe

Description read

[DESCRIPTION-READ] 21774ba3938533b5208c81d62c9a37b2077445f753a519887acd81a35826ddb8

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 6be76fe387818bcc5e09b9909c4bee3267784c4f and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6be76fe

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 6be76fe387818bcc5e09b9909c4bee3267784c4f false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 6be76fe

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 6be76fe387818bcc5e09b9909c4bee3267784c4f false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 6, 2026
@bolichen97
bolichen97 force-pushed the fix/26629-kas-route-follows-pin branch from a49f48e to d85c89d Compare November 7, 2026 02:07
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=712b3afe843f an explicit backend= override is judged by the Bot pin it outranked

fixed in d85c89d: the factory now computes the pin in the selection's order (crewmate_harness.route_pin); an explicit backend_override carries no pin, so that worker keeps the installation's pick, as on main.
The provider carries the pin (AcpProvider.harness_pin, declared on LLMProvider) into both AcpRuntime constructions; the start path no longer reads config by key.
The companion takes its parent provider's pin instead of re-deriving it from the parent key.
Pinned by test_kas_route.py::TestThePinReachesTheSpawn::test_an_explicit_backend_carries_no_pin_to_the_runtime (red without the override check or the factory argument).
[operator: bolichen97]

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/acp-client.md, src/kiro_crew/acp/harness/base.py, src/kiro_crew/acp/harness/kas.py, src/kiro_crew/acp/runtime_class.py, src/kiro_crew/docs/configuration.md, src/kiro_crew/providers/acp.py since this head's CI ran (26c8238 -> a47c2d4); CI re-running.
[operator: bolichen97]

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] The fix for the review finding above changes one line of the frozen "Not a goal" section: a per-spawn backend= override on a pinned Bot's worker is no longer judged by the Bot's pin. It now carries no pin and keeps the installation's pick, exactly as on main. That section was left unedited as written when the PR opened; the "What changed" section describes the current behaviour.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=33f2b8a041aa one process-wide last-spawn route is read by sessions whose pins take different routes

Rebutted: disproportional, outside the frozen goal. Each spawn's route now follows its own pin, which is the goal. The route slot was never a session's route: it is the last KAS spawn in the process (acp-client spec: "keeps the last spawn's route in a process slot").
On main the slot already names another session's route whenever kiro-cli's install or sign-in changes between two spawns, because the rule is decided per spawn. The dashboard card and the once-per-change log line keep that same last-spawn meaning.
Where kiro-cli-chat is present the remedy is the same Kiro sign-in on both routes: with Crew's sign-in a pinned relay starts through the chat binary (kas.py host_auth branch), and only the one-line route prefix differs. A different remedy needs a launcher-only relay (no kiro-cli-chat).
Naming each session's own route means threading the pin or the route into every sign-in message builder: host_auth, the transport_errors formatter chain and its three session-handle raise sites, the session provider, the runtime start path and the dashboard thread turn. That is a new per-session surface, not this fix.
[operator: bolichen97]

@bolichen97
bolichen97 force-pushed the fix/26629-kas-route-follows-pin branch from d85c89d to 0ce035c Compare November 7, 2026 08:21
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/acp-client.md, src/kiro_crew/acp/harness/base.py, src/kiro_crew/acp/harness/kas.py, src/kiro_crew/providers/acp.py, test/conftest.py, test/test_acp_bindings.py since this head went green (a47c2d4 -> 0795ebc); CI re-running.

Also in this push: the factory test now checks the pinned case next to the override case, and one import in acp/kas_route.py moved to the module top. Nothing else changed.

[operator: bolichen97]

@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 Nov 7, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] The one red test on this head, test/test_security_gate_liveness.py::test_the_package_stays_within_its_line_budget (Backend Tests shard 2 on Linux and Windows, and the Coverage Gate that fails closed behind them), is red on main too: main's security package measures 34,855 lines against a budget of 34,845 since #30976, and this PR does not touch that package. #32183 restores the budget. This PR waits for it to merge, then re-syncs onto it.

The KAS route's rule 2 keeps a stored Kiro CLI pick on kiro-cli, but it
read only the installation's agent.acp_backend. A Bot pinned to "kiro"
under a global "kas" could be moved onto Kiro Crew's own engine, and a
Bot pinned to "kas" under a global "kiro" could never switch, so it
failed on a missing or signed-out kiro-cli.

The provider factory now computes the pin in the selection's order:
an explicit backend override outranks the Bot pin, so an overridden
session carries no pin and keeps the installation's pick.
The provider carries the pin into every runtime it builds, through
SpawnContext, and a companion runtime takes its parent provider's.
Rule 2 reads that pin when there is one and the global pick otherwise.

Part of #26629
@bolichen97
bolichen97 force-pushed the fix/26629-kas-route-follows-pin branch from 0ce035c to 6be76fe Compare November 7, 2026 14:35
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/acp-client.md, src/kiro_crew/acp/harness/kas.py, test/conftest.py since this head's CI ran (0795ebc -> d27a5fd); CI re-running.

The one red on the old head, test/test_security_gate_liveness.py::test_the_package_stays_within_its_line_budget, was main's: main has since raised the budget to its measured size, and the test passes on this base.

Also in this push: TestThePinReachesTheSpawn::test_the_factory_carries_the_pin_its_selection_used now stubs the provider class instead of the driver function, so dropping the driver's harness_pin= forward fails it too. No production code changed.

[operator: bolichen97]

@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 Nov 7, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Tier 1 auto-approve: fix (19 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: the KAS engine-switch rule reads the session's own Bot harness pin before the installation default; with tests. Spec files changed as a ride-along (a minority of the diff on both file count and changed lines), not reviewed as a design decision: docs/system-specs/modules/acp-client.md.

@bolichen97
bolichen97 merged commit 886f1d5 into main Nov 7, 2026
98 of 99 checks passed
@bolichen97
bolichen97 deleted the fix/26629-kas-route-follows-pin branch November 7, 2026 16:10
bolichen97 added a commit that referenced this pull request Nov 9, 2026
The KAS route's rule 2 keeps a stored Kiro CLI pick on kiro-cli, but it
read only the installation's agent.acp_backend. A Bot pinned to "kiro"
under a global "kas" could be moved onto Kiro Crew's own engine, and a
Bot pinned to "kas" under a global "kiro" could never switch, so it
failed on a missing or signed-out kiro-cli.

The provider factory now computes the pin in the selection's order:
an explicit backend override outranks the Bot pin, so an overridden
session carries no pin and keeps the installation's pick.
The provider carries the pin into every runtime it builds, through
SpawnContext, and a companion runtime takes its parent provider's.
Rule 2 reads that pin when there is one and the global pick otherwise.

Part of #26629

Backport note: acp-client.md and test_acp_bindings.py resolved onto
release's text; the AcpProvider.__init__ signature digest is recomputed
for release's constructor.

(cherry picked from commit 886f1d5)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants