Repository navigation
Conversation
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>
UX Review (Fable 5, fork) — ✅ PASSUX-level review of 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 |
Opus 4.8 Review (fork) — ✅ no blocking findingsReviewed |
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Design Review (Fable 5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing to check. Suggestions
[DESIGN-REVIEWED] e71d8ba |
First Principles Review (Fable 5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS The shipped comment says the MCP install is the only What this change shipsInventory (3 items) — 3 justifiedIntent: FIX — a crewmate enrolled from the Agent templates tab must appear on the crew rosters it was just added to.
Verified against base: [FIRST-PRINCIPLES-REVIEWED] e71d8ba |
|
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 ( 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. |
|
@leonlaiyc quick follow-up: your work here landed on |
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'sown create makes — and then invalidates one key:
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.tsxrenderscrewsandtemplatesoff oneSidePanelLayout),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.tssetsstaleTime: Infinity— "queries never go stale ontheir own. Freshness is driven exclusively by WebSocket push" — so switching
back to Crews serves the cached roster rather than asking again.
POST /api/agentspushes nothing. The onlypush_refresh("agents")in thebackend 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_takenfrom the server fora 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
gcTimeon['kirocrew-agents'](the library default — this repo overridesstaleTimeonly). 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:
roster.
The other readers of the same write are reached by key, and their key was not
named.
['kirocrew-agents']is invalidated as a prefix, which is how the membersroster comes along —
MEMBERS_ROSTER_QUERY_KEYis['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 inthis 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) rendersObject.entries(cfg.agents)as a table and offersObject.keys(cfg.agents)asthe
session.pool_agentoptions, both off['kirocrewConfig'], so a stalesnapshot 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_storesrecord, and this enroll passesmemory_store: 'default', so itcreates no store key and does not reproduce that particular message.
refetchAgentsonKiroCrewAgentsPagealready does both. #12740 reasoned "everycaller of
refetchAgentsis a config.json write", which was true — but the realsite list is every caller of
createKirocrewAgent, and #12481 added one onanother page that does not route through
refetchAgentsat 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
refreshframe anyway(
useWebSocket.invalidateRefreshQueries), so this makes the write do promptlywhat a later unrelated event already did eventually.
Tests
One case added to
AgentTemplatesTab.test.tsx, RED against87553ba86and GREENafter:
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(), spelledas
KiroCrewAgentsPage.tsx:810-813spells it — resolves the pre-write rosterfirst 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: Infinitydeliberately. The suite's per-testQueryClient is
{ retry: false }, i.e. the library defaultstaleTime: 0, underwhich 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.
Adjacent, unchanged:
CrewEditorSelect.test.tsx(#12740's own test),CapabilitiesPage.tabLanguage,CrewCapabilitiesPane,KiroCrewAgentsPage.templateRequired— 4 files, 61 passed.Gates:
tsc --noEmitclean ·eslintclean 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
staleTimerather thanthe 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.tsxandAgentTemplatesTab.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
enrollmutation and appends a newdescribeat the end of the test file, so there is no hunk overlap in eitherdirection. Flagging it so whoever merges second is not surprised.
Pattern harvest
Rule candidate:
review-promptPattern: a fix that enumerates its site list by the helper rather than by the
backend write. #12740 paired
['kirocrewConfig']with the registry prefixinside
refetchAgentsand reasoned "every caller ofrefetchAgentsis aconfig.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 siteeither routes through the helper or repeats its invalidations.
Second, narrower tell in this codebase: with
staleTime: Infinityas the globaldefault, 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
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
🤖 Generated with Claude Code