Skip to content

fix(agents): let an enrolled crewmate reach the crew roster - #12831

Closed
leonlaiyc wants to merge 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/enroll-invalidates-registry
Closed

leonlaiyc wants to merge 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/enroll-invalidates-registry

Conversation

@leonlaiyc

@leonlaiyc leonlaiyc commented Sep 22, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

"Enroll as crewmate" on the Agent templates tab creates a crewmate, says so, and
the crewmate is missing from the list it was added to.

The mutation POSTs /api/agents — the same crew registry write the Crews tab's
own create makes — and then invalidates one key:

const enroll = useMutation({
  mutationFn: (row) => api.createKirocrewAgent({ name: row.name, kiro_agent: row.name, memory_store: 'default' }),
  onSuccess: (r, row) => {
    ...
    invalidate()        // ['agent-templates'] only
  },
})

The registry's own readers are left holding the pre-write roster: the Crews
tab
, which is the sibling of this one on the same rail
(CapabilitiesPage.tsx renders crews and templates off one SidePanelLayout),
and the Crew Members roster, which lives under the same ['kirocrew-agents']
prefix by design (api/membersQuery.ts).

Nothing else refreshes them while that cache entry is live:

  • api/queryClient.ts sets staleTime: Infinity — "queries never go stale on
    their own. Freshness is driven exclusively by WebSocket push"
    — so switching
    back to Crews serves the cached roster rather than asking again.
  • POST /api/agents pushes nothing. The only push_refresh("agents") in the
    backend is the MCP capability install (handlers/agents.py:1571).

So the user flow the page invites — open Agent Capabilities (which lands on
Crews), switch to Agent templates, enroll, switch back to check — is
inside that entry's gcTime, and the new crewmate is not there.

Why it matters

The action reports success and the roster contradicts it on the next click, on
the same page. The user's reasonable reading is that the enroll silently failed,
and the obvious recovery — enroll again — hits name_taken from the server for
a crewmate the UI is refusing to show them. There is no affordance on either tab
that forces the refetch; a full reload is the only way out.

Scope, stated honestly: the window is bounded by React Query's gcTime on
['kirocrew-agents'] (the library default — this repo overrides staleTime
only). Beyond it the entry is evicted and a later mount fetches correctly. It is
not a permanent wrong state; it is a wrong state for exactly as long as the user
is likely to still be looking.

What changed (motivation → approach → change)

Symptom → cause → change:

  • Symptom: an enrolled crewmate is absent from the Crews tab and the members
    roster.
  • Cause: a crew registry write invalidated only the templates read model.
    The other readers of the same write are reached by key, and their key was not
    named.
  • Change: name them.
invalidate()
void queryClient.invalidateQueries({ queryKey: ['kirocrew-agents'] })
void queryClient.invalidateQueries({ queryKey: ['kirocrewConfig'] })

['kirocrew-agents'] is invalidated as a prefix, which is how the members
roster comes along — MEMBERS_ROSTER_QUERY_KEY is
['kirocrew-agents', 'members-roster'], placed under that prefix precisely so
"a crew created, renamed or starred anywhere reaches this cache without the page
knowing who wrote".

['kirocrewConfig'] is the pairing #12740 established one commit earlier in
this same window, for the same backend write: the write lands in config.json,
and that query's masked read (_masked_config_dict) ships the agent records.
It has its own reader — KiroCrewCfgTab (Developer > Config) renders
Object.entries(cfg.agents) as a table and offers Object.keys(cfg.agents) as
the session.pool_agent options, both off ['kirocrewConfig'], so a stale
snapshot omits the new crewmate from that table and that dropdown too.

To be precise about what is not claimed: #12740's own observable was a
memory_stores record, and this enroll passes memory_store: 'default', so it
creates no store key and does not reproduce that particular message.

refetchAgents on KiroCrewAgentsPage already does both. #12740 reasoned "every
caller of refetchAgents is a config.json write", which was true — but the real
site list is every caller of createKirocrewAgent, and #12481 added one on
another page that does not route through refetchAgents at all.

Backwards compatibility

Compatible: no signature, prop, config key or wire field changes. Two additional
cache invalidations on a success path that already invalidated one key. Both keys
are invalidated by the existing refresh frame anyway
(useWebSocket.invalidateRefreshQueries), so this makes the write do promptly
what a later unrelated event already did eventually.

Tests

One case added to AgentTemplatesTab.test.tsx, RED against 87553ba86 and GREEN
after: shows the enrolled crewmate on the Crews roster.

It mounts the Crews tab's own query beside the tab —
queryKey: ['kirocrew-agents'], queryFn: () => api.kirocrewAgents(), spelled
as KiroCrewAgentsPage.tsx:810-813 spells it — resolves the pre-write roster
first and the post-write roster afterwards (#12740's own idiom, so only a second
read can reach the crewmate), enrolls, and asserts the roster shows it.

The test sets staleTime: Infinity deliberately. The suite's per-test
QueryClient is { retry: false }, i.e. the library default staleTime: 0, under
which a remount refetches and this defect cannot be observed at all. Pinning the
production value is what makes the test exercise the lifecycle the fix is about;
without it the test would pass on the unfixed code.

RED   expected element to have text content reviewer
      (roster still showed only the pre-write member)
GREEN 26 passed

Adjacent, unchanged: CrewEditorSelect.test.tsx (#12740's own test),
CapabilitiesPage.tabLanguage, CrewCapabilitiesPane,
KiroCrewAgentsPage.templateRequired — 4 files, 61 passed.
Gates: tsc --noEmit clean · eslint clean on both touched files ·
npm run pretest (jscpd) 0 clones.

Manual verification

N/A — unit coverage sufficient: the defect is a cache-invalidation contract, and
the test asserts the rendered roster under the production staleTime rather than
the mechanism, which is the same thing a human would check by switching tabs.

Related Issues

None — found by auditing #12740's fix for other callers of the same registry
write.

Note on overlap: open PR #12806 also touches
AgentTemplatesTab.tsx and AgentTemplatesTab.test.tsx (an "Agent Capabilities"
→ "Customize" vocabulary rename). Its hunks on the component are at ~5, 72, 148,
595 and 873; this change is inside the enroll mutation and appends a new
describe at the end of the test file, so there is no hunk overlap in either
direction. Flagging it so whoever merges second is not surprised.

Pattern harvest

Rule candidate: review-prompt

Pattern: a fix that enumerates its site list by the helper rather than by the
backend write. #12740 paired ['kirocrewConfig'] with the registry prefix
inside refetchAgents and reasoned "every caller of refetchAgents is a
config.json write" — sound, but it answers "did I cover this helper's callers?"
when the question is "did I cover this write's callers?". A sibling page calling
the same API function directly is outside the helper's reach and inherits
nothing.

The check that catches it: grep for the API client method the fix's helper
wraps (createKirocrewAgent), not for the helper, and confirm every call site
either routes through the helper or repeats its invalidations.

Second, narrower tell in this codebase: with staleTime: Infinity as the global
default, a missing invalidation is never healed by a remount — the usual "it
refetches when you navigate back" intuition is false here, and the only other
healer is an explicit server push, which most mutations do not emit.

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

🤖 Generated with Claude Code

Enrolling a template POSTs /api/agents -- the same crew registry write the
Crews tab's own create makes -- but the mutation invalidated only
['agent-templates']. The registry's own readers were left holding the
pre-write roster: the Crews tab beside this one on the same rail, and the
Crew Members roster that lives under the ['kirocrew-agents'] prefix.

Nothing else refreshes them while that cache entry is live. The dashboard's
QueryClient sets staleTime: Infinity ("queries never go stale on their own.
Freshness is driven exclusively by WebSocket push"), so a remount serves the
cached roster instead of asking again, and POST /api/agents pushes no refresh
frame -- the only push_refresh("agents") in the backend is the MCP capability
install. Opening Agent Capabilities on Crews, switching here, enrolling and
going back is inside that entry's gcTime, so the crewmate this tab has just
reported as enrolled is absent from the list it was added to.

The enroll now invalidates the registry prefix, which carries the members
roster with it, and ['kirocrewConfig'] alongside it -- the pairing kirodotdev#12740
established for a member write, because the same write lands in config.json
and its masked read ships the agent records.

The regression test mounts the Crews tab's own query beside the tab and runs
it under the production staleTime, because the suite's per-test QueryClient
uses the library default, where a remount would refetch and hide this.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@leonlaiyc
leonlaiyc requested review from a team and patrigao September 22, 2026 14:43
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Sep 22, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Fable 5, fork) — ✅ PASS

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

UX-Verdict: PASS

Verify by hand once: enroll from Agent templates, switch back to Crews, and confirm the new crewmate appears without a reload.

[UX-REVIEWED] e71d8ba

@github-actions

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] e71d8ba

@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] e71d8ba

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

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

Design-Verdict: PASS

Nothing to check.

Suggestions

  • The registry write is invisible to any other open dashboard until gcTime eviction; a backend push_refresh("agents") on POST /api/agents (and a shared client-side "registry write" invalidation helper) would fix all write sites at the source — worth a follow-up, not this PR.

[DESIGN-REVIEWED] e71d8ba

@github-actions

Copy link
Copy Markdown
Contributor

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

Premise-level review of e71d8ba757885748e56a4d1863443efbcc6271dd 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.

First-Principles-Verdict: PASS

The shipped comment says the MCP install is the only push_refresh("agents"); grep finds 17 sites. The create handler truly pushes none — fix only the parenthetical.

What this change ships

Inventory (3 items) — 3 justified

Intent: FIX — a crewmate enrolled from the Agent templates tab must appear on the crew rosters it was just added to.

  1. An enrolled crewmate now appears on the Crews tab and Crew Members roster immediately — justified
  2. Enrolling also refreshes the Developer > Config agents table and pool-agent dropdown — justified
  3. A regression test pins the roster under the production staleTime: Infinity — justified

Verified against base: api_kirocrew_agents_create (handlers/agents.py:4609–4859) calls no push_refresh; staleTime: Infinity in queryClient.ts:67; MEMBERS_ROSTER_QUERY_KEY under the ['kirocrew-agents'] prefix (membersQuery.ts:23); KiroCrewCfgTab.tsx:131 reads ['kirocrewConfig']. Grep createKirocrewAgent: 2 production callers; the other (KiroCrewAgentsPage.tsx:1222) already invalidates both keys via refetchAgents — 0 unfixed siblings. Fix shape matches the recorded #12740 decision for this defect class.

[FIRST-PRINCIPLES-REVIEWED] e71d8ba

@iamwhatever

Copy link
Copy Markdown
Contributor

Thank you for this fix, @leonlaiyc — the diagnosis is spot on: enrolling is a crew registry write, so it has to invalidate the registry prefix (['kirocrew-agents'], which carries the members roster) and ['kirocrewConfig'] alongside ['agent-templates'], especially under staleTime: Infinity where nothing else refetches.

To get it through the fork-only CI gates (Screenshot Evidence can't attach from a fork, plus a Windows-shard timing flake), I've carried your commit verbatim into an in-repo replacement PR, with your authorship preserved: #15920. It's all-green including PR Readiness. Closing this one in favor of that; full credit to you.

@iamwhatever iamwhatever closed this Oct 1, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 1, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

@leonlaiyc quick follow-up: your work here landed on main via #15920 (merged). Your commit was kept with your authorship, so your name is on the change in the git history, and you're listed in the README Contributors section. Thanks again for the contribution!

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.

2 participants