Skip to content

fix(llm): fallback chain walk honors namespace-qualified model ids - #8896

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
javenciu:fix/fallback-chain-namespaced-ids
Sep 13, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
javenciu:fix/fallback-chain-namespaced-ids

Conversation

@javenciu

@javenciu javenciu commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

A persisted agent.fallback_model chain entry that carries a
<namespace>::<bare-id> qualifier (the #8521 mismatch class — stored when a
catalog advertised the qualified spelling) is silently skipped by the
throttle-fallback walk when the session advertises the bare id.
next_fallback_candidate (src/kiro_crew/llm_helpers.py) filters the chain
by literal membership:

if adv and low not in adv:
    logger.debug("model fallback: skipping %r (not advertised)", cand)
    continue

so a chain entry the backend fully serves is treated as unadvertised, and the
walk falls through toward "auto"/chain exhaustion. On a partition that does
not serve "auto", the chain exhausts and the original throttle error
surfaces — the configured fallback never fires. Issue #8740 identified this as
the one literal-membership site left outside the #8616/#8737 fold.

Why it matters

Users who pinned a fallback while a catalog advertised qualified spellings get
no fallback at all at exactly the moment it exists for: sustained throttling
on the primary. The failure is silent (a debug-level skip log), so it reads as
"fallback feature does not work". The same stale-qualifier pins were already
judged worth folding at the substitute-send and picker sites (#8616, #8737);
the fallback walk was the remaining consumer of persisted model values still
comparing literally.

What changed (motivation → approach → change)

Observed symptom: a served-but-qualified chain entry is skipped as
unadvertised (reproducer below — the walk returns None on a chain whose only
entry the backend serves under its bare spelling).

Root cause: next_fallback_candidate judges membership with a literal set
lookup, and the issue's own analysis explains why the fold could not be a
one-line predicate swap: the walk's return value feeds two consumers with
conflicting spelling needs. FallbackState.next_candidate locates the applied
candidate with remaining.index(cand), so it needs the CHAIN's own spelling —
but the wire and every later served-model comparison (the
AcpClient.set_model explicit-pick guard, the silent no-op witness, the
TURN_FALLBACK_ATTR marker that probe_fallback_restore compares against the
served model, and fb_state.active/walked) need the ADVERTISED spelling. A
qualified spelling in the marker would make the restore probe read the session
as having moved off the fallback, clear the sticky state, and skip the slot
heal.

The change, keeping the two spellings from ever disagreeing:

  • next_fallback_candidate judges membership and the active-model skip
    through resolve_pin_spelling (the shared fold from Namespace-qualified model ids: sibling comparison sites not covered by #8615 #8616/fix(models): fold namespaced pins at substitute and picker sites (#8616) #8737): full id
    first, one leading <namespace>:: peel on a miss. An entry absent under
    both spellings is still skipped (deny-parity), a verbatim-advertised
    qualified id is never peeled, and a qualified entry that resolves to the
    currently-failing model is skipped post-fold. The function still returns the
    chain's own spelling, preserving the remaining.index bookkeeping contract
    and all ten existing behavior pins.
  • New module-private _fallback_wire_spelling is the single home of the
    chain→wire
    translation: advance_fallback_candidate computes it once per candidate and
    uses it for the in-loop active skip, the set_model call, the no-op
    witness, fb_state.active/walked, the published marker, the swap log, and
    the return value. Empty/unknown advertised set falls back to the entry's own
    spelling, matching the walk's existing fail-open stance.
  • docs/system-specs/modules/model-fallback.md candidate-walk section synced
    in the same commit.

Alternative rejected: returning a (chain_entry, wire_spelling) tuple from
next_fallback_candidate. It changes the function's contract and every
existing pin for the same information the shared fold can recompute
deterministically at the one wire consumer; the smaller surface keeps the fold
authoritative in one place.

Tests

Reproducer, before the fix (tests-only tree at base 235d36a62):

FAILED test/test_llm_helpers.py::TestAdvanceFallbackCandidateNamespacedChain::test_qualified_entry_applies_under_advertised_spelling - AssertionError: assert None == 'z-ai/glm-5.3-flash'
FAILED test/test_llm_helpers.py::TestNextFallbackCandidate::test_namespace_qualified_entry_folds_to_advertised_bare_id - AssertionError: assert None == 'openrouter::z-ai/glm-5.3-flash'
=================== 2 failed, 4 passed, 37 warnings in 4.61s ===================

After the fix: 6 passed, and the full targeted file 142 passed.

New pins and what each locks in:

  • test_namespace_qualified_entry_folds_to_advertised_bare_id — a qualified
    entry the backend serves under its bare id is selected, and the CHAIN
    spelling is returned (bookkeeping contract).
  • test_qualified_entry_peeling_to_active_model_is_skipped — post-fold active
    skip: a qualified entry resolving to the failing model cannot help.
  • test_entry_absent_under_both_spellings_still_skipped — deny-parity: the
    fold does not weaken the advertised filter.
  • test_verbatim_advertised_qualified_id_not_peeled — a full-id match wins;
    peeling never rewrites it.
  • TestAdvanceFallbackCandidateNamespacedChain::test_qualified_entry_applies_under_advertised_spelling
    — end to end: set_model awaited with the bare spelling, marker
    (primary, bare), fb_state.active/walked carry the bare spelling, and
    pos advanced past the chain entry itself.
  • TestAdvanceFallbackCandidateNamespacedChain::test_qualified_entry_peeling_to_failing_model_is_skipped
    — the walk exhausts rather than announcing a no-op swap when the chain names
    the failing model under a qualifier.

Neighboring suites green locally: test_subagent_turn_resilience.py +
test_model_selection_scenarios.py + test_api_models_entitlement.py
(84 passed), test_dashboard_chat.py -k fallback (16 passed). mypy, flake8,
isort, the black baseline gate, and docs-lint.sh all pass on the changed
files.

Manual verification

N/A — unit coverage sufficient: the walk, the wire call, the witness, and the
marker are all exercised through the same provider-double shape the existing
fallback tests use, and the seam has no UI or external-service surface.

Related Issues

Fixes #8740

Pattern harvest

Rule candidate: review-prompt
Pattern: "persisted model ids must be compared through the shared spelling
fold, never by literal membership; any value later compared against a SERVED
model must carry the advertised spelling". #8616 → #8737 → this PR closed the
enumeration one site at a time; a review prompt on new in advertised-style
membership tests over persisted model values stops the class from re-growing.

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

Contribution License Agreement

Per the template placeholder (CLA text pending): offered under the same terms as my prior merged contributions to this repository (#8835).

@javenciu
javenciu requested review from a team and dwu96 September 6, 2026 05:49
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 6, 2026
@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 140a34dd4352b6a3668fab684b7056ab415d6a9d via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

The design analysis holds end-to-end. The wire-spelling split is genuinely required by probe_fallback_restore (llm_helpers.py:779 compares the served model against the marker's candidate spelling — a qualified marker would falsely read as "moved off the fallback"), the chain-spelling return preserves the remaining.index contract in FallbackState.next_candidate (llm_helpers.py:495), and routing the import through agent_sdk.drivers.acp is the RFC-aligned direction under the shrink-only agent-sdk-boundary ratchet rather than a layering detour. The rejected tuple-return alternative is defensible, the spec doc is synced in the same commit, no existing pin is weakened, and the "Manual verification: N/A" claim covers a pure-Python path CI fully exercises. No design-level findings survive.

Design-Verdict: PASS

Root-cause fold at the last literal-membership site, with the chain/wire spelling split correctly derived from real consumer contracts.

[DESIGN-REVIEWED] 140a34d

@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed 140a34dd4352b6a3668fab684b7056ab415d6a9d via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 140a34d

@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of 140a34dd4352b6a3668fab684b7056ab415d6a9d via the fork AI-review pipeline — 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.

All verification is done. The description's mechanism claims each check out against the base tree, the return value's spelling change is safe (all three callers use it only as a None-check/notice), and my sibling grep (not in adv|in advertised across src/) found no remaining literal-membership site of this class besides model_is_unusable itself, which is the base predicate the fold deliberately layers on.

First-Principles-Verdict: PASS

fb_state.walked now records the advertised spelling, so exhaustion stories and swap notices rename the user's configured pin — confirm that rewording is intended.

What this change ships

Inventory (5 items) — 5 justified

Intent: a pinned fallback carrying a stale <namespace>:: qualifier never fires under throttling; make the walk recognize it via the existing shared fold. FIX.

  1. A qualified fallback chain entry now applies under throttling instead of silently skipping to exhaustion — justified
  2. The applied fallback is sent, marked, recorded and logged under its advertised spelling — justified
  3. New module-private _fallback_wire_spelling helper hosting the chain→wire translation — justified
  4. model-fallback.md candidate-walk section updated in the same commit — justified
  5. Six new test pins (fold, deny-parity, no-peel, post-fold active skip, end-to-end spelling) — justified

Provenance verified against base: the literal skip exists (llm_helpers.py:462), remaining.index forces the chain-spelling return (llm_helpers.py:495), a qualified wire id would raise AcpModelUnavailable (acp/client.py:5076), and a qualified marker desyncs the restore probe (llm_helpers.py:779). Reuses resolve_pin_spelling (acp/client.py:2467) — not a second spelling. Sibling grep (not in adv|in advertised, src/): 0 unfixed sites of this class remain.

[FIRST-PRINCIPLES-REVIEWED] 140a34d

@github-actions

github-actions Bot commented Sep 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

Reviewed 140a34dd4352b6a3668fab684b7056ab415d6a9d via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 140a34d

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 6, 2026
@javenciu

javenciu commented Sep 6, 2026

Copy link
Copy Markdown
Contributor Author

Re: Opus 4.8 suggestion — import resolve_pin_spelling from kiro_crew.acp.client directly

Commit 1 (0a830e7) had exactly that shape and failed Backend Lint & Type Check (3.12) on scripts/check_agent_sdk_boundary.py: adding a new symbol to the kiro_crew.acp.client import line is an added ACP edge on added lines, and the gate's baseline only covers pre-existing lines.

Per docs/request-for-change/rfc-crew-agent-sdk-boundary.md, kiro_crew.agent_sdk is the single import surface for application code, with kiro_crew.acp private to the driver behind it. Commit 2 (5c645c8) therefore reaches the helper through kiro_crew.agent_sdk.drivers.acp, matching the in-tree precedent at src/kiro_crew/session.py:114. The pre-existing direct acp imports in llm_helpers.py stay byte-identical to the baseline.

Happy to reroute if maintainers prefer a different shape, but as the gate stands, the suggested import is the one it rejects.

@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 6, 2026
@javenciu

javenciu commented Sep 6, 2026

Copy link
Copy Markdown
Contributor Author

Backend Tests (3.12, 4) failure — the #8893 flake, third occurrence, not this diff

test_a_FRESH_gateway_still_orders_the_copy_against_a_delivery failed on shard 4 (run 34017247801). This is the exact test/assertion tracked in #8893, which already records its second occurrence on this PR's previous round (run 34014923783). This PR's diff is confined to llm_helpers.py model-fallback spelling and touches nothing in the snapshot/notification path; the test passes 5/5 locally at this exact head (5c645c8). The Coverage Gate failure is downstream of the same shard: the failed shard never staged/uploaded its coverage data.

Root cause is confirmed at source (details in #8893): both ordering tests patch os.open process-wide and fire their delivery trigger on the first O_CREAT open observed anywhere; on a loaded shard that first open can be a foreign thread's while the notification worker is still free, so the append runs immediately and the assertion reads scheduler noise as a broken ordering guarantee. A deterministic fix (destination-scoped triggers, no retry/sleep, plus a test that keeps the loaded-shard condition permanently reproduced) is built and heading into review.

No changes to this PR; requesting a rerun of the failed shard once maintainers deem it appropriate.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 6, 2026
@javenciu
javenciu force-pushed the fix/fallback-chain-namespaced-ids branch from 5c645c8 to 35f0e8d Compare September 6, 2026 10:22
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Sep 6, 2026
@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 6, 2026
@javenciu

javenciu commented Sep 6, 2026

Copy link
Copy Markdown
Contributor Author

CI note: the Backend Tests (3.12, 1) failure on this board is the known shard-runtime issue tracked in #8968 (test_channel_slots.py fails deterministically on any shard running >30 minutes; the frozen NOW diverges from the live-clock cutoff). This run's shard 1 ran 37 minutes (10:27:36Z to 11:04:46Z) and failed with the exact signature from that issue (assert 0 == 1 in TestReconcilePass). test_channel_slots.py is not part of this PR's diff (docs + llm_helpers.py + test_llm_helpers.py). Re-running the failed jobs.

@javenciu
javenciu force-pushed the fix/fallback-chain-namespaced-ids branch from 35f0e8d to 7582844 Compare September 6, 2026 13:23
@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 6, 2026
@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 6, 2026
@javenciu

javenciu commented Sep 6, 2026

Copy link
Copy Markdown
Contributor Author

The Backend Tests (3.12, 4) failure on this PR (run 34035940758) is the known flaky ordering assert tracked in #8893 (TestNotificationCopyWhenNoLiveFileExists racing on loaded CI shards), not a regression from this change. Evidence:

  • This PR touches only src/kiro_crew/llm_helpers.py, its test file, and a docs page. The failing module test/test_snapshot.py has zero references to llm_helpers, and snapshot.py / jsonl_util.py (the code under test) import nothing from it in either direction.
  • Local reproduction at this PR head (7582844): test_a_FRESH_gateway_still_orders_the_copy_against_a_delivery passes 5/5 consecutive runs.
  • The Coverage Gate failure is a cascade of the failed shard (combine cannot complete), not an independent signal.

This is the 4th occurrence of the #8893 signature across recent CI runs on unrelated PRs. No code change is needed here; happy to have the shard re-run whenever convenient.

@iamwhatever

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: iamwhatever#241cc860]: This PR has been inactive for 7+ days with failing CI. I've assessed the blockers and they appear resolvable — I'll push fixes directly to this branch as a co-author. Assessment: the only failing shard is the #8893 flake, since fixed on main; plan is a rebase onto current main, the First-Principles rename of fallback_wire_spelling to a private helper, and a fresh CI run. If you'd prefer I don't touch this PR, add the pr-no-autofix label.

…irodotdev#8740)

The throttle-fallback walk filtered persisted agent.fallback_model chain
entries by literal membership in the advertised set, so a chain entry
carrying a stale <namespace>::<bare-id> qualifier was skipped as
unadvertised even when the backend serves the bare id, and the walk fell
through toward "auto"/chain exhaustion. On a partition that does not
serve "auto" the chain exhausts and the original throttle error
resurfaces, so the configured fallback never fires.

next_fallback_candidate now judges membership and the active-model skip
through resolve_pin_spelling (the shared fold from kirodotdev#8616/kirodotdev#8737); an entry
absent under BOTH spellings is still skipped, and a verbatim-advertised
qualified id is never peeled. The walk still returns the CHAIN's own
spelling because FallbackState.next_candidate locates the applied
candidate with remaining.index.

advance_fallback_candidate re-folds that entry once through
_fallback_wire_spelling and uses the ADVERTISED spelling for everything
later compared against a served model: the substitute set_model call, the
silent no-op witness, fb_state.active/walked, the TURN_FALLBACK_ATTR
marker probe_fallback_restore reads, the swap log, and the return value. A
qualified spelling in the marker would make the restore probe read the
session as having moved off the fallback, clear the sticky state, and skip
the slot heal.

resolve_pin_spelling is reached through kiro_crew.agent_sdk.drivers.acp,
the delegation that exists for the agent-sdk-boundary gate; a direct
kiro_crew.acp.client import both adds an ACP edge and rewrites a
baselined import line, which the gate refuses.

Six behavior pins added; docs/system-specs/modules/model-fallback.md
candidate-walk section synced in the same commit.

Fixes kirodotdev#8740

Co-authored-by: Joe Guo <zejiangg@amazon.com>
@iamwhatever
iamwhatever force-pushed the fix/fallback-chain-namespaced-ids branch from 7582844 to 140a34d Compare September 13, 2026 10:25
@iamwhatever

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: iamwhatever#241cc860]: confirming the First Principles PASS headline on 140a34dd4352b6a3668fab684b7056ab415d6a9d — the fb_state.walked rewording is intended, and the advertised spelling is the more honest one.

walked has exactly one display consumer, FallbackState.exhaustion_story, and its sentence is "…; fallbacks X, Y also unavailable" — a list of the candidates that were actually sent and actually throttled. That is the advertised spelling by construction: the qualified config spelling is never put on the wire (AcpClient.set_model's explicit-pick guard rejects an id the backend never advertised), so naming it there would report an attempt that did not happen.

There is also no spelling that regresses for a user. Before this change a qualified chain entry never reached walked at all — it was skipped as unadvertised, walked stayed empty, and exhaustion_story returned None. So the story does not rename an existing entry; it gains a line it previously never produced, spelled as the model that was tried.

The alternative — keep the config spelling in walked for display while the marker, active, the witness and the wire keep the advertised one — reintroduces exactly the two-spellings-in-flight condition this fix exists to remove, for a cosmetic gain. Not taken.

No code change; recording the confirmation rather than a fix. Local gates are green on this head (mypy 1470 files, isort, flake8, black baseline, comment-history, agent-sdk-boundary, docs-lint, test/test_llm_helpers.py 142/142).

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 13, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: iamwhatever#241cc860]: this is green and ready for maintainer review — readiness: passed on head 140a34dd4352b6a3668fab684b7056ab415d6a9d, MERGEABLE, non-draft, 0 failing checks, 0 unresolved threads. The only thing left is a human review (reviewDecision: REVIEW_REQUIRED, zero reviews so far). I am not merging and have not armed auto-merge.

What I changed on @javenciu's behalf, as a co-author — the approach, the design and the tests are unchanged from what was submitted:

  • Rebased onto current main (fc7980060068) and squashed to one commit, keeping @javenciu as the commit author.
  • Applied the First Principles Subtraction from the previous round: fallback_wire_spelling is now module-private _fallback_wire_spelling, since advance_fallback_candidate in the same module is its only consumer. Renamed in src/kiro_crew/llm_helpers.py, test/test_llm_helpers.py and the spec doc. The fresh review now lists that helper as justified.
  • Removed the #8521 issue citation from the new docstring and the new test comment. main gained a Comment History Gate since this PR was written, and it rejects a PR/issue number on an added comment line; both spots now state the behavior in present tense ("the catalog/session spelling-mismatch class"). No logic touched.
  • Corrected two things in the PR description that no longer matched the diff: the helper name, and a reference to docs/system-specs/features/model-fallback.md — the synced doc is docs/system-specs/modules/model-fallback.md.

Verdicts on the current head: Design Review PASS, First Principles Review PASS, GPT 5.6 no findings, Opus 4.8 no findings, Security Scope Review pass, Internal Content Scan pass. The First Principles PASS headline asked whether the fb_state.walked rewording was intended; confirmed above with no code change — exhaustion_story is walked's only display consumer and it names candidates actually sent and throttled, which is the advertised spelling by construction.

Two CI reds that were not this diff, both resolved without touching the PR's code:

  • Backend Tests (macOS) (2) failed test_platform_compat.py::TestResourceShims::test_proc_rss_bytes_falls_back_down_when_memory_is_released — the runner accounted only 55.7MB of a 128MB faulted mmap, so while_held - baseline > chunk // 2 missed. Passed on re-run.
  • PR Readiness held at action required with every individual check green. Its log named failed=[Code Review (cancelled)]: two Code Review runs existed on this head 32 seconds apart, the newer was cancelled by concurrency while the older succeeded, and readiness binds the newest. Re-ran the superseded run; it went green and readiness flipped to passed.

Fixes #8740 verified resolving via closingIssuesReferences. Local gates green on this head, including mypy over 1470 files, test/test_llm_helpers.py 142/142, the agent-sdk-boundary gate (the agent_sdk.drivers.acp import path is preserved — a direct kiro_crew.acp.client import fails that gate, as @javenciu documented), docs-lint and every diff-scoped gate.

Leaving the drive-to-green label on. Over to a maintainer.

@iamwhatever
iamwhatever enabled auto-merge (squash) September 13, 2026 13:07

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Tier 1 auto-approve: fix (3 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, SAST annotations clean, security checklist all-NO, AI reviewers green. Category: a persisted fallback-chain entry carrying a stale :: qualifier was compared literally against the session's advertised ids, so it was skipped as unadvertised; the fix judges membership through the shared resolve_pin_spelling fold and records/sends the advertised spelling so the restore probe stays in sync. 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/model-fallback.md. CodeQL is not applicable on this fork PR (default-setup emits no check-run); SAST coverage is Semgrep only, latest run success with 0 annotations.

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Read the full diff. The chain/wire spelling split is correct: next_fallback_candidate still returns the CHAIN spelling because FallbackState.next_candidate locates it with remaining.index, while _fallback_wire_spelling folds to the ADVERTISED spelling for the set_model call, the no-op witness, fb_state.active/walked and the TURN_FALLBACK_ATTR marker the restore probe compares against. resolve_pin_spelling tries the full id first and peels only one leading namespace qualifier, so deny-parity holds (absent under both spellings stays skipped) and the post-fold active skip covers a qualified entry that resolves to the failing model. Tests pin all four cases.

@bolichen97
bolichen97 merged commit 8a68f34 into kirodotdev:main Sep 13, 2026
124 of 131 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 13, 2026
@NicholasRBowers NicholasRBowers removed the drive-to-green PR claimed by drive-to-green pipeline label Sep 13, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…irodotdev#8740) (kirodotdev#8896)

The throttle-fallback walk filtered persisted agent.fallback_model chain
entries by literal membership in the advertised set, so a chain entry
carrying a stale <namespace>::<bare-id> qualifier was skipped as
unadvertised even when the backend serves the bare id, and the walk fell
through toward "auto"/chain exhaustion. On a partition that does not
serve "auto" the chain exhausts and the original throttle error
resurfaces, so the configured fallback never fires.

next_fallback_candidate now judges membership and the active-model skip
through resolve_pin_spelling (the shared fold from kirodotdev#8616/kirodotdev#8737); an entry
absent under BOTH spellings is still skipped, and a verbatim-advertised
qualified id is never peeled. The walk still returns the CHAIN's own
spelling because FallbackState.next_candidate locates the applied
candidate with remaining.index.

advance_fallback_candidate re-folds that entry once through
_fallback_wire_spelling and uses the ADVERTISED spelling for everything
later compared against a served model: the substitute set_model call, the
silent no-op witness, fb_state.active/walked, the TURN_FALLBACK_ATTR
marker probe_fallback_restore reads, the swap log, and the return value. A
qualified spelling in the marker would make the restore probe read the
session as having moved off the fallback, clear the sticky state, and skip
the slot heal.

resolve_pin_spelling is reached through kiro_crew.agent_sdk.drivers.acp,
the delegation that exists for the agent-sdk-boundary gate; a direct
kiro_crew.acp.client import both adds an ACP edge and rewrites a
baselined import line, which the gate refuses.

Six behavior pins added; docs/system-specs/modules/model-fallback.md
candidate-walk section synced in the same commit.

Fixes kirodotdev#8740

Co-authored-by: Joe Guo <zejiangg@amazon.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Namespace-qualified model ids: fallback-chain walk still compares literally (post-#8616 remainder)

4 participants