Skip to content

refactor(members): key config.agents by member_id - #14423

Closed
CrysisDeu wants to merge 1 commit into
mainfrom
feat/agents-keyed-by-member-id
Closed

CrysisDeu wants to merge 1 commit into
mainfrom
feat/agents-keyed-by-member-id

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A crew member's display name is just a label: you can rename it freely and nothing the member owns moves.

Today config.agents is keyed by the member's display name, and the stable identifier (member_id) lives inside the record. That is backwards. #11121 made display names free-form (spaces, ., non-ASCII), so the key is now presentation text: every rename is a key rewrite, and every lookup path has to re-validate presentation text before it can find the record. The Design Review on #11121 flagged the consequence: a name later judged non-dispatchable strands the member's thread with no non-lossy repair.

Why it matters

member_id is already minted once at create time and already binds the durable things: members/<id>/, the DM slot key, the DM thread binding, cron member_id, and the memory store's owner_member_id. Leaving the name as the key means a plain rename can orphan all of them, and every one of the ~30 config.agents[name] sites is one bad name away from resolving the wrong crew or none.

Not a goal

  • Governance, the spawn allowlist and MCP identity stay keyed on the kiro_agent TEMPLATE name; nothing there changes.
  • The kiro_agent grammar is untouched.
  • Dropping the name alias from API responses (kept for one release).
  • A frontend re-key: routes keep resolving name; the pickers built on AgentSelector (Schedule, Channels, Projects) now store member_id, and the surfaces that render a stored value resolve it back to the display name through the roster (utils/agentLabel). The chat agent pop-up (AgentDropdownList) is untouched.

What changed (motivation → approach → change)

Before After
"agents": {"Crew Program Manager": {"member_id": "crew-program-manager", ...}} "agents": {"crew-program-manager": {"member_id": "crew-program-manager", "display_name": "Crew Program Manager", ...}}
Rename = re-key the record Rename = edit display_name; identity never moves
Lookups by name index the map directly Lookups go through one resolver that answers a key OR a display name

The key is the id the allocator already mints; _allocate_member_id also reserves every existing agents key and display name, so a fresh id never equals another member's handle. Create allocates the id first and inserts under it.

KiroCrewConfig.load is read-only for identity: it serves every entry whose member_id differs from its key under the id (old key kept in legacy_keys, and as display_name when the record had none; default_agent follows) and writes nothing. migrate_member_identity is the one writer: once, under the config lock, it re-keys the document, moves the fork-sidecar private_to owners onto the id (only on the template the record is bound to) and every member's picture from its old key onto its member_id, never overwriting; a failed sidecar rewrite is retried on every boot from legacy_keys. It runs off-loop in the gateway's post-readiness memory worker and in the CLI prologue; idempotent, never raises. A contested id is left as stored and logged. merge_config_documents folds overlay agents entries and both sides' default_agent onto the member's id (a remembered legacy_keys entry included), so an overlay-patched member stays one member; an unresolvable default is logged.

Migration boundary: load() = read-only view; migrate_member_identity() = the only identity writer (boot, off-loop, before member handlers; CLI); every other writer patches the raw document where the record is stored (raw_agent_key).

Where each piece lives:

Area Change
src/kiro_crew/members.py avatars_root / avatar_stem (digest of the member_id) / rekey_avatar_files; resolve_member, resolve_member_id, member_record, member_display_name, same_member; member_slug answers either handle
src/kiro_crew/agent_state.py rekey_private_owners / claim_private_owner: sidecar private_to follows the member id
src/kiro_crew/config/loader.py, config/migration.py, config/sections.py plan_member_rekeys, migrate_member_identity (the one-shot writer), raw_agent_key, legacy_key_aliases, in-memory re-key on load, _resolve_agent_selection / resolve_crew_identity resolve handles; the default_agent write-back canonicalizes a display-name spelling to the key; display_name field docs
src/kiro_crew/memory_stores.py allocator reserves keys; owner_member = display name; legacy owner checks accept the label
src/kiro_crew/execution_context.py, subagent_manager/admission/gate.py, session_capabilities.py, member_essential_context.py, context.py, acp/session_handle.py, mcp_core.py member lookups by handle go through the resolver
src/kiro_crew/agent_capabilities.py, dashboard/handlers/agent_capabilities.py the capabilities route and service resolve the handle to the key once; snapshot, sidecar private_to, spec and config-binding writes all index by it, and the binding write patches the raw document under every key the record is stored under (raw_agent_keys: the id and any legacy-label alias an overlay still carries, so a later-wins merge can neither shadow the write nor keep a stale binding)
src/kiro_crew/crew_teams.py, dashboard/handlers/teams.py team members are stored by key: submitted and stored handles are canonicalized before validation and the one-team detachment, answered by the roster handle; create AND rename purge the published label from stale entries inside the locked mutation
src/kiro_crew/dashboard/handlers/agents.py, handlers/members.py, handlers/messaging.py, handlers/memory_admin.py, chat_handlers.py, chat_persistence.py, openai_compat.py routes resolve handles; rosters carry member_id / display_name / name; rename validation; avatar files keyed by member_id; the sync prune judges staleness on binding fields
src/kiro_crew/cli.py, cli_commands.py, doctor_checks/agents.py, slack/gateway.py, apps/builtins/auto_improvement/backend/crew.py the CLI prologue and the gateway memory worker run migrate_member_identity; kirocrew agent create/update/delete/list and the Auto-Improvement role members on the keyed shape (a role adopts the member labelled with its name, and ensure_team refuses a role name a retired record still holds as its key or a legacy key, naming the record to delete, because key-first resolution would otherwise shadow the replacement); doctor vets BOTH the key it prints and the display name dispatch would use, so a credential-shaped key behind a benign label is counted without being printed
config-baseline.json regenerated for the display_name and legacy_keys help text
website/src/utils/agentLabel.ts (new helpers), components/AgentSelector.tsx, pages/SchedulePage.tsx, pages/ChannelPage.tsx, pages/settings/ChatPanel.tsx, api/client.ts, api/defaultAgentQuery.ts, website/src/i18n/locales/*.json (one new string, pages.channelPage.roster_names_failed = "Couldn't load agent names — showing roles only.") the picker stores crewHandle(row) (= member_id, or name for a project row) and matches either handle (isHandleOf); every surface that renders a stored value resolves it to the display name through its roster (agentDisplayLabel / agentOrDefaultLabel(agent, default, agents)); KiroCrewAgent / MemberRosterRow gain optional member_id; defaultAgentQuery reads the response's name (label). The channel rail's AgentControlRow is re-laid out as part of this: the role title and the resolved crew name each take the row's full width and wrap, and no line carries more than two controls -- the title line holds the title and ✕ (remove) alone, so a medium name is never squeezed or fractured mid-word; the line below holds the state badge, the listen-mode trigger and ↺ (clear context), and WRAPS so a wide badge pair never pushes ↺ past the 256px rail. This answers the UX review on this PR, which read the 256px rail with the name beside the state badge as "Cr…" (round 20-21) and, once the name had its own line, the role beside the badge and the two buttons as "R…" (round 22) -- anonymous rows with a live destructive ✕

members.resolve_member(handle, config) is the one lookup helper: the key wins, then the unique record whose display_name equals the handle, then the unique record whose legacy_keys holds it; anything else is None. Every user-facing handle goes through it or its wrappers (resolve_member_id, member_record, same_member, member_display_name): the /api/agents/{name} routes, /api/members/{slug}?member=, /api/config/default-agent, teams, capabilities, the DM-thread pin check, chat and OpenAI-compatible member slots, select_crew / route_crew, resolve_crew_identity / _resolve_agent_selection (every crew=), the CLI agent update/delete, and the essential-context, admission and watchdog lookups.

Responses from GET /api/agents, GET /api/members, select_crew and the create/update routes carry member_id and display_name; name stays an alias of display_name for one release, and GET /api/agents and the catalog spell default_agent like their rows. A label that would be masked falls back to the key in name. Create and rename validate the label and refuse credential-shaped text or another member's handle. A rename moves no files: the picture is filed under the immutable member_id; a failed sidecar repair or config write leaves the label unchanged. The picker (AgentSelector) dispatches member_id, so a slot stores the identity and survives a rename; an older slot holding the label still matches. Surfaces rendering a stored id resolve it through the roster and wait for settled from hooks/useAgents.ts, so the id never flashes. Private-copy (private_to) and memory-store ownership (store_owned_by_member: owner_member_id first, the label only for an id-less record) are decided on the id, so a member taking a retired label inherits nothing. Identity text, roster bindings, event-log ownership, team purges and capability overlay reads go by the key, showing the label; docs/system-specs/modules/config.md describes the rule.

Identity namespace: who may collide with whom, and the guard. T = test/test_agents_keyed_by_member_id.py.

Pair Guard Test
key × key (migration) plan_member_rekeys: only a SURVIVING move vacates its key; a refused move (duplicate id, target key stays) re-occupies it and refuses its mover, to a fixed point; rekey_agents_document never writes two entries to one key T::TestPlan::test_refused_move_does_not_vacate_its_key, test_refusal_cascades_along_a_chain_onto_a_staying_key, test_document_rekey_never_drops_an_entry, TestIdentityNamespaceProperty::test_arbitrary_documents_migrate_without_loss_and_idempotently
allocated id × key _allocate_member_id reserves every agents key (own key exempt) T::TestResolver::test_allocator_reserves_every_key
allocated id × display_name _allocate_member_id reserves every other entry's display_name, spelled exactly as resolve_member compares T::TestResolver::test_allocator_reserves_every_display_name, TestCreateAndDeleteEdges::test_create_never_mints_a_key_that_is_a_live_label, property (b)
allocated id × retired store owner _allocate_member_id reserves every memory_stores[*].owner_member_id test_member_memory_ownership.py::test_deleted_member_identity_stays_reserved_by_retained_store
display_name × key, display_name × display_name (create) POST /api/agents refuses when resolve_member(name) or resolve_member(display_name) answers (409 agent_exists) T::TestCreateAndDeleteEdges::test_create_refuses_a_handle_that_is_another_members_label, test_config_api.py::test_create_duplicate_returns_409
create keying × #14865 (main keys NEW crews by a derived id) this PR supersedes #14865's create-time key_new_crew on both create surfaces and keeps its user-facing rules where they fit the id model: a typed name that already IS a member-id slug is the key as sent with no label of its own (the roster shows the key) -- unless that id is reserved (a retired store, a legacy key), in which case the id is suffixed and the typed name stays the label so the crew still answers to what the user typed (test_crew_memory_store_binding.py::test_delete_then_same_name_create_keeps_old_store_and_starts_fresh), any other name -- free-form, or agent-id grammar such as Scribe_2 that is not slug grammar -- seeds the slug and stays the label; the derived id is suffixed -2, -3... deterministically past every reserved identity before the random tail; an explicit display_name (--display-name on the CLI) wins as the label; and the collision check is on the handles the crew will CARRY (its shown label and, for a slug-shaped name, the key), so a free-form name another crew shows is free when this crew shows a different label. key_new_crew / NewCrewKey / crew_id_for_display_name are removed with their tests (no consumer left); is_crew_id stays and backs is_member_id_shaped test_crew_display_name.py::TestCreateEndpoint (10, adapted: the answer's member_id is the id, name echoes the label), test_cli_agent.py::TestAgentCreate (unchanged), test_config_api.py::test_crud_create_round_trip
display_name × key, display_name × display_name (rename) PUT /api/agents/{name} refuses a label resolve_member answers with another member (409) T::TestRename::test_rename_to_another_members_handle_is_refused
create/rename handle × concurrent writer handle uniqueness is decided INSIDE persist_member_config's locked mutation, not by the caller's pre-lock snapshot: a created key and label, and a renamed member's new label, are rechecked with member_handle_holders against the document under the lock (own keys exempt) and a taken handle raises MemberAlreadyExists, which the create and rename routes answer 409 agent_exists; two writers racing for one spelling (a CLI create beside a dashboard rename, an app's ensure_team) leave one record, never a shadowed duplicate T::TestHandleUniquenessIsDecidedUnderTheLock (6)
legacy key × key (migration) legacy key becomes display_name; id occupied by a staying entry is refused, not guessed T::TestPlan::test_id_already_used_as_a_key_is_refused, TestLoadMigration::test_colliding_id_stays_where_stored
legacy key × display_name (two records end with one label) resolve_member answers a shared label with None: refused, never guessed T::TestResolver::test_shared_display_name_is_refused
overlay key/label × key merge_config_documents / canonicalize_overlay_agents fold the overlay entry onto the base member's id; _canonical_overlay_agents in the capability service resolves against the UNMERGED base document, exactly as the merge does -- against the merged view an overlay entry that renames the very label it is keyed by looks like nobody's, and the binding write would land in config.json underneath the shadowing overlay T::TestOverlayStaysOneMember (3), TestLabelledMemberSurfaces::test_capabilities_see_an_overlay_entry_filed_under_the_legacy_key, ::test_capabilities_resolve_the_overlay_against_the_unmerged_base, test_agent_capabilities.py::test_overlay_entry_that_renames_its_own_label_still_saves_in_the_overlay
legacy key × overlay key after the disk moved (explicit label) a moved record remembers its old key in legacy_keys (record field, written once by the migration, travels with config.json); legacy_key_aliases feeds canonicalize_overlay_agents, canonical_agent_key and resolve_member rule 3; a live key or label beats a remembered key and a key two records remember answers nobody T::TestOverlayStaysOneMember::test_overlay_under_the_legacy_key_of_an_explicitly_labelled_member_stays_attached, test_a_live_handle_beats_a_remembered_legacy_key
allocated id / new label × legacy key _allocate_member_id reserves every legacy_keys entry; create and rename refuse a handle resolve_member answers T::TestOverlayStaysOneMember::test_allocator_and_create_reserve_a_remembered_legacy_key
load-time mutation × request path load() writes nothing for identity; migrate_member_identity is the only writer, one-shot, under the config lock, off-loop at gateway boot and in the CLI prologue T::TestLoadMigration::test_load_is_read_only_and_the_migration_lands_once
sidecar private_to × key/label ownership is the key (members.member_owns_private_copy, one predicate behind the fork/publish/reset routes and the capability seams; a legacy spelling counts only for the template the record is bound to); the migration moves the sidecar's owners INSIDE the config transaction from that run's plan alone -- a sidecar that cannot be written abandons the config write, so the next boot derives the same plan from the still-unkeyed document and retries -- and NOTHING is ever derived from a record's persisted legacy_keys, an agent-writable field a record could spell an orphaned owner into to be handed that private copy T::TestPrivateCopyOwnershipIsById (incl. test_a_sidecar_write_that_fails_abandons_the_config_write_and_the_next_boot_retries, test_legacy_keys_never_drive_a_sidecar_owner_move)
team entry × key/label canonicalize_teams + handler _Registry store the key once; create purges an entry left under the label; a rename purges its NEW label the same way (a deleted crew's label whose drop failed would otherwise be inherited by whoever takes it); delete drops both spellings T::TestTeamsHoldOneIdentityPerMember (2), TestLabelledMemberSurfaces::test_create_purges_a_team_entry_left_under_the_label, test_member_memory_publication.py::test_a_rename_purges_the_new_label_inside_the_locked_mutation
canonical key × teams document bounds _validate_names bounds the value a write RETAINS (the canonical key) by MEMBER_NAME_MAX_CHARS / UTF-8, not the handle submitted, so a short label addressing an agent-authored oversize key cannot persist a document read_teams then refuses whole; the read view (canonicalize_teams) keeps the stored spelling over an unbounded key and prune_unknown hides it T::TestTeamsBoundTheRetainedIdentity (2)
store owner label × key owner_member_id is authoritative; owner_member (the KEY an earlier layout stamped, when labels were the keys) is read only for an id-less record and as an owner SPELLING through member_owns_private_copy -- the member's key or its own unambiguous legacy key, never a display name (a deleted crew's store does not follow its label to whoever wears it next); one predicate memory_stores.store_owned_by_member shared by member_store_ownership_holds, _store_is_member_owned, the sync prune and the delete route T::TestLabelledMemberSurfaces::test_labelled_members_store_is_recognised_as_owned, test_legacy_owner_label_is_an_owner_spelling_not_a_display_name, test_members_dm_thread.py::...[store_owner]
raw-document patch × unmigrated disk a writer patching one member into a document read from disk files it under the key the record IS stored under (raw_agent_key: the planned mover for a base document, the LAST folding entry for an overlay, since canonicalize_overlay_agents merges later-wins; raw_agent_keys lists every folding alias and the capability binding write patches all of them), never beside it under the id; used by the capability binding write, persist_member_config, and every update_config_locked mutate that starts from a member id (DELETE /api/agents/{name}, _rebind_crew_locked, the fork's binding write), and kirocrew agent delete, which otherwise answer 500 / a spurious 409 / a misleading not found on an install whose disk has not migrated yet test_session_capabilities.py::test_capability_write_lands_on_the_legacy_record_when_the_rekey_has_not_persisted, T::TestHandleRoutes::test_delete_before_the_disk_migration_removes_the_legacy_entry, test_rebind_before_the_disk_migration_finds_the_legacy_entry, T::TestOverlayStaysOneMember::test_raw_agent_key_files_a_patch_where_the_record_is, test_raw_agent_key_patches_the_effective_overlay_alias, test_merge_without_a_plan_honours_remembered_legacy_keys, TestLoadMigration::test_member_update_patches_the_legacy_record_before_the_migration, T::TestCliDeleteFindsTheStoredRecord (2)
agent-authored key × roster redaction an entry an agent wrote straight into config.json with no member_id keeps its authored key, so the roster's member_id is agent-writable text like every other record value and goes through _roster_mask (a credential- or URL-shaped key arrives EMPTY, never raw and never the sentinel -- see "masked key × picker dispatch"); GET /api/members applies the same rule, so a pre-existing credential-shaped key behind a benign display_name (legal while labels were unvalidated) passes the row's handle gate without shipping the key T::TestRosters::test_agent_authored_key_is_masked_like_every_other_row_value, T::TestRosters::test_members_row_never_ships_a_key_the_mask_would_alter
DM slot pinned under the label × post-assignment recheck every one of the three slot-identity comparisons in api_member_thread (entry, running-path revalidation, the recheck after the namespaced assignment) is same_member, never an exact key compare: a thread rehydrated from history under the crew's old label opens instead of answering 409 member_slot_conflict on every open with nothing left to re-pin it. The entry check then ADOPTS the canonical key onto slot.agent (the same adoption an empty pin gets): the send path compares the binding's member, a key, to slot.agent by exact equality, so a legacy spelling merely accepted would 409 the very next turn test_members_dm_thread.py::test_private_thread_reopen_accepts_an_idle_slot_pinned_under_the_label
undispatchable stored label × every roster ONE rule spells a crew's name -- member_roster_handle (showable by _roster_mask, dispatchable, held alone) -- behind /api/agents, /api/members, the team responses and the default marker, so a label the mask leaves alone but that cannot be dispatched (trailing whitespace predating the rename validation) is the key everywhere and a crew is never listed under two names T::TestSharedLabelsFallBackToTheKey::test_an_undispatchable_label_ships_the_key_on_every_roster
slot handle × alias snapshot (resolve_effective_agent) publish_agent_alias_snapshot publishes every handle a slot may hold for a member -- the key, its display_name, each legacy_keys entry -- so a pre-upgrade session still pinned under a member's old key reads as that member, never as a substitution that never happened test_dashboard_state_ws.py::TestSlotEffectiveAgent::test_a_slot_under_a_members_old_key_is_not_a_substitution
slot handle × chat surfaces (sidebar rows, history rows, composer chip, pane chip, model-pin row) every place that turns a slot's stored agent into a label or a roster row goes through the roster (agentOrDefaultLabel(agent, default, installedAgents) / isHandleOf), so a member slot storing the id shows the display name with its source tint and session colour, and the model-pin row finds the member's record; the sidebar rows and the composer / pane chips HOLD the label (blank) until the roster has answered, the same hold the Schedule column and the channel rail apply, so the stored id never flashes before its name ChatSidebar.defaultAgentMarker.test.tsx (member slot named and tinted from the stored id; held blank until the roster settles)
taken label × concurrent config.local.json writer while a create/rename takes a label another record remembers, the overlay's OWN lock is held from the overlay read to the base document's commit (taken inside the base lock -- the order the template writer already uses), so a config set --local cannot file an entry under that label in the window and find it re-homed onto the new member. The check runs for EVERY contested handle, not only one another record remembers: an overlay entry orphaned by a member delete (delete removes the base record, never the user-owned overlay) would otherwise fold onto the new member at the next load and merge its fields in; the create refuses and names the entry. A handle this record already answers to (its key, label, legacy keys) is its own and is exempt T::TestHandleUniquenessIsDecidedUnderTheLock::test_the_overlay_is_locked_from_the_check_to_the_commit, ::test_an_orphaned_overlay_entry_is_never_reassigned_to_a_new_member
member deleted during capability reconcile × workspace re-read prepare_runtime re-reads the record after reconcile_member_capabilities; a record that is gone by then refuses with the closed capability_member_missing, the same code the pre-check gives, never an attribute error out of .workspace test_session_pool.py::TestGetOrCreatePoolIntegration::test_member_deleted_during_reconcile_refuses_with_the_closed_code
governance task bind × re-keyed member a task bind resolves by EXACT id only -- never through a record's display_name or legacy_keys, which are agent-writable config fields a record could spell itself as to select a task profile (which outranks the surface profile). And profiles/ is never WRITTEN from the migration either: it is the sandbox-read-only governance keystone while config.json is agent-writable, so a bind rewrite derived from a key move or legacy_keys would be a write primitive from the writable file onto the read-only one (a record spelling a bound id as its own earlier key would have the administrator's profile moved onto its id at the next boot). Fail-secure instead: the re-key REFUSES to move a record whose current key a task profile binds (plan_member_rekeys reads governance_profiles.task_bound_snapshot -- the profile store's in-memory snapshot, no filesystem walk on the event loop -- in memory and on disk alike), so the record keeps its key and the ceiling keeps applying; and it refuses EVERY move while that snapshot cannot be trusted (store not yet loaded, or a profile file present but unrecoverable), because a bind it could not read might name the key a record would leave; the refusal names the profile and the exact re-point (profile X binds task:'Old'; re-point it to task:'member-id' and the next boot moves the record). A bind authored against a key the record already left cannot be protected by refusing a done move; stale_task_binds reports it with the same re-point every boot (summary key stale_task_binds) and says when the report is incomplete. Neither path writes profiles/ test_governance_profiles.py::test_task_binding_never_resolves_through_agent_writable_aliases, ::test_stale_task_binds_reports_and_writes_nothing, T::TestLoadMigration::test_a_record_whose_key_a_task_profile_binds_keeps_its_key_until_re_pointed (in-memory and on-disk refusal, then the move once re-pointed), ::test_an_unreadable_profile_refuses_every_re_key_until_it_is_fixed, ::test_a_profile_bound_after_the_move_is_reported_every_boot
shared display name × roster handle two records sharing a label (legal while labels were presentation-only) each ship their KEY as name (member_roster_handle / _agent_roster_row require the label to address the record alone), so every row's handle is one PUT/DELETE /api/agents/{name} and the team routes answer instead of a label resolve_member refuses to pick between T::TestSharedLabelsFallBackToTheKey (3)
event-log header × label after rename the write-once header is compared against _log_owner_handles (key, current label, recorded legacy keys), never the label alone; the reconcile and the rename hook write the key test_members_eventlog_wiring.py::test_a_renamed_member_keeps_its_projection_and_write_through
avatar stem × label / legacy key stem = digest(member_id), immutable and unique by construction: a rename moves no file; upload, serve, promote, reap and delete all address the id whichever handle the URL carried T::TestAvatarFilesAreKeyedByMemberId (5), test_agent_avatar.py::test_crew_delete_removes_avatar_files
legacy avatar file × id stem (migration) migrate_member_identity sweeps every member on every boot: files under the old key or any legacy_keys entry move onto the id stem -- never a file under a display name, which no earlier build used as a stem (labels were presentation-only), so such a file belongs to whichever identity once had that spelling as its key -- and only a handle the record owns UNIQUELY: a live key is never a source, the key this run moved a record from is that record's alone, and a legacy key two records remember moves nothing; a variant already present under the id is never overwritten and the legacy source stays in place (logged), as does one that cannot be moved, so nothing is lost and the next boot retries T::TestLabelledMemberSurfaces::test_picture_filed_under_a_label_is_never_adopted, test_rekey_moves_pictures_filed_under_the_old_key_onto_the_id, test_avatar_rekey_never_overwrites_and_retries_the_source_next_boot, test_avatar_rekey_leaves_an_unmovable_source_in_place, test_avatar_sweep_never_moves_a_live_members_picture, test_avatar_sweep_leaves_a_contested_handle_in_place
chat slot × label after rename the picker dispatches member_id (AgentSelector.crewHandle), so the slot stores the identity; an older slot holding the label still matches its row, the server resolves either handle, and the roster's most-used-first sort takes the best agent_usage tuple across every spelling a session may have pinned (member_id, name, each legacy_keys entry), so history recorded before the upgrade still orders the picker website/src/test/AgentSelector.test.tsx (3: dispatches the id, shows the label for an id slot, matches an older label slot), T::TestUsageSortIsKeyedByMemberId (2)
stored member_id × rendered label every surface that renders a STORED agent value resolves it through the roster it holds -- Schedule's Agent column (agentOrDefaultLabel(agent, default, agents)), the channel agent rail (label and title), the Settings › Chat pinned default (isHandleOf) -- via utils/agentLabel (agentDisplayLabel, isHandleOf, crewHandle); a value the roster does not list renders verbatim website/src/test/agentLabel.storedHandle.test.ts (4)
masked key × picker dispatch a member_id _roster_mask would alter is shipped EMPTY, not as the sentinel: the picker prefers member_id over name, and a sentinel there would pin the slot to a handle no member has, while the global row's name was left unmasked to stay reachable T::TestRosters::test_agent_authored_key_is_masked_like_every_other_row_value
default_agent spelling × delete both delete paths (route, CLI) re-check the default INSIDE the lock through document_default_names_member: the top-level and migration-era agent.default_agent, expanded by member_handle_holders against the raw agents map, so a default kirocrew config set default_agent <display-name> wrote verbatim still refuses the delete (the route maps the in-lock refusal to 409, not 500) T::TestDeleteGuardReadsEveryDefaultSpelling (3)
create lineage × stored key POST /api/agents allocates member_key BEFORE the foreign-private-copy check and asks about that key -- the one every later ownership question (reset, publish, rebind, capability seams) asks with -- not the requested label T::TestCreateChecksLineageForTheStoredKey
one member × two teams (two spellings) canonicalize_teams applies the cross-team first-wins rule (_parse_teams's) while mapping, so a write never persists one identity in two teams for the next read to drop silently T::TestCrossTeamDedupeOnCanonicalize
shared label × the agent's own identity text the member identity block tells the model its display name only when member_handle_holders(label) == [key], else the key -- the roster's own chooser -- so the agent is never told a name no route resolves (context.py; existing test_member_essential_context.py / test_member_turn_context.py green)
package-agent prune × fields added since the entry was written the sync prune compares the in-lock entry with the discovery snapshot on EVERY field both carry (an operator edit to any field between the snapshot and the lock is newer evidence and the row survives), ignoring fields only one side has, so a dataclass field added by an upgrade cannot silently disable the prune; the concurrent-ownership check accepts owner_member_id or the key aname, never the row's reusable display_name test_agent_sync_prune.py::test_prune_deletes_an_entry_written_by_an_earlier_build, test_prune_entry_unchanged_judges_every_field_both_entries_carry, T::TestPruneOwnershipIgnoresDisplayNames
shared label × the picker catalog GET /api/agents/catalog builds its member rows with the whole agents map, so two records sharing a display_name both ship their KEY as name (the roster's rule) instead of one label the picker's fold-by-name would collapse into a single row, dropping a member from the schedule form and channel pages test_agent_execution_catalog.py::test_catalog_falls_back_to_the_key_for_a_shared_label
package-agent name × member handle _do_agents_sync refuses a discovered agent whose name any Crew Member already holds -- as key, display_name or a legacy_keys entry (members.member_handle_holders) -- on the snapshot AND again inside the config lock, so a member renamed to writer is never shadowed by a package row writer that the resolver would prefer (key beats label) and that carries no private memory; the refusal is logged test_agent_sync_prune.py::TestAgentSyncRefusesMemberHandles (4: display name, legacy key, a free name still registers, a rename landing between scan and lock)
default_agent × key/label canonical_agent_key on both documents; unresolvable default logged; a base default spelled as a key the document still holds (a legacy key this load re-keyed in memory only) pends no write-back -- the spelling is right for the disk and migrate_member_identity moves it with the record -- so no cache-miss load re-takes the lock to make no progress T::TestDefaultAgentFollowsTheMember (5), T::TestLegacyKeyDefaultIsNotWrittenBackByTheLoad
rename × label-keyed overlay / default_agent a rename records the label it leaves behind in the record's legacy_keys (and drops a label that becomes live again), so an overlay entry or a default_agent still spelled with the prior label folds onto the same member instead of surfacing as a second partial member or a substituted default; a no-op rename writes nothing test_rename_keeps_the_prior_label_as_an_alias, test_rename_to_the_same_label_records_no_alias
pre-re-key sidecars × id-keyed readers a rules payload or a dm.json written while the record had no member_id names the member by its label; read_member_rules attributes such a payload when the recorded label still answers to THIS member (its display_name or a legacy key; a label another member now holds live does not -- the live namespace wins), and read_dm_binding canonicalizes the label onto the key on the way in, so the permanent rules keep binding after the upgrade and the bound DM thread keeps its slot key T::TestLabelledMemberSurfaces (rules under the pre-publication label, under a renamed-from label, under a label another member holds; the context builder reads them; a legacy binding still binds; a binding naming another member's live label is not rewritten)
a label another member only remembers × create/rename a legacy_keys entry is a forwarding address the live namespace beats in every resolver, so a create or rename may publish it as a LABEL (the write retires the alias in the same mutate) while a KEY is still refused when any spelling holds it; the one closed case: an overlay (config.local.json) entry still filed under that label would follow it onto the new member, so the label is refused with a message naming the entry to re-file T::TestHandleUniquenessIsDecidedUnderTheLock (publishes and retires the alias; overlay entry refuses; the rename route accepts), test_reused_label_does_not_inherit_the_renamed_members_copy
masked member_id × the roster's own lookups /api/members keys its binding match, projection and header attribution on the record's real key carried beside the row, and ships the masked member_id only in the payload, so a record whose key the redactors would alter still reports its bound thread test_a_masked_key_row_still_reports_its_live_binding
unreadable overlay × label take-over the overlay guard treats only a MISSING config.local.json as "no entry"; a file that cannot be read or is not JSON refuses the create/rename (409 member_memory_unavailable, nothing written, the message names the file), so a repaired overlay never wakes up filed under a member that took the label while the guard could not see it T::TestHandleUniquenessIsDecidedUnderTheLock (malformed overlay refuses; unreadable overlay refuses; rename route 409, nothing written)
stored member_id × every rendering surface the catalog's default_agent is spelled like its rows' name (the display name, masked for an app token), so the inherited-default chip and the row match read the label; the Schedule Agent column resolves a stored id through the roster and waits for the roster to settle (as the channel rail does) so the id never flashes, and the Schedule filter's haystack carries that resolved label beside the stored handle, so typing the name shown in the column matches the row; Webhooks is left untouched -- a token pins a template, never a crew handle (see Manual verification) test_catalog_default_agent_is_spelled_like_the_default_row, SchedulePage.agentColumnSettled.test (2: settles, filters by the shown name)
a deleted member's orphaned private copy × a namesake the migration's sidecar rewrite (rekey_private_owners) and the legacy-key read (member_owns_private_copy(..., template=)) both accept a plan key / legacy key as an owner spelling only on the template the record is BOUND to (kiro_agent; a receipt also on the copy it was published from), so a retired member's copy that the delete-time cleanup could not prove safe to drop -- still spelling the label a newcomer was later keyed by -- neither moves onto the newcomer nor reads as theirs at the bind gate; the rename path's claim_private_owner already applied this one-template rule T::TestPrivateCopyOwnershipIsById::test_migration_leaves_an_orphaned_copy_under_a_reused_label, ::test_namesake_cannot_bind_a_deleted_members_orphaned_copy, ::test_a_published_templates_receipt_moves_by_the_public_name
one crew's old key × another crew's new key (pictures) the migration stages every moved-from picture onto a per-member staging stem before landing any on its id, so Alice -> alice while alice -> alice-7f3 lands both instead of refusing the first (destination stem occupied) and never attempting the second (source now a live key); staged files a crashed run left are landed on the next boot T::TestAvatarFilesAreKeyedByMemberId::test_avatar_rekey_lands_when_one_crews_old_key_is_anothers_new_key
base-document default_agent × a retired legacy key with no overlay, a default spelled with a label the crew was later renamed away from resolves through the record's legacy_keys (the parsed-map twin of legacy_key_aliases) before the existence check, so it names that crew as every other resolver does instead of being substituted and written back; the Schedule Agent column likewise treats a REJECTED catalog fetch as "no roster" and keeps holding the label T::TestDefaultAgentFollowsTheMember::test_base_default_by_a_retired_legacy_key_still_names_that_member, SchedulePage.agentColumnSettled.test.tsx
any sequence of create/rename/delete/migrate property test over colliding labels: (a) no two live members share a key, (b) no label equals another member's key, (c) every handle resolves to its member or None, (d) migration recovers the state and is idempotent T::TestIdentityNamespaceProperty::test_namespace_stays_consistent (hypothesis, 300 examples)

Backwards compatibility

Compatible: an old-shape config.json loads unchanged in behaviour (dual-read) and is written back once in the new shape; every handle a client or slot already holds (a display name) still resolves through the resolver; name remains in every response as the display name. The one tightening is on writes, not reads: a display_name that fails the create-time name validator or collides with another member's handle is now refused with the same 400/409 the create route already returns.

Downgrade (new shape read by a release before this PR): the older loader keys agents by what it finds, so each member appears under its member_id (crew-program-manager) instead of its label, display_name and legacy_keys are carried as unknown fields, and a lookup by the old label misses until the user re-upgrades (the dual-read resolver then serves both spellings again) or renames the key by hand. Nothing is lost: no record, store or picture is removed by the rewrite, and the fork sidecar's private_to under the id is simply foreign to the older code, so the private copy is hidden, not deleted, until the upgrade. The rewrite runs once and is idempotent, so a downgrade-upgrade cycle leaves the document as this PR wrote it. Governance profiles: profiles/ is never rewritten. A record whose key a task profile binds is NOT re-keyed until the operator re-points the bind to the member_id (the boot log names the file and the exact edit), so the administrator's ceiling never detaches as an upgrade side effect; a bind authored after a move is reported the same way every boot.

Tests

test/test_agents_keyed_by_member_id.py (new; also TestDeleteGuardReadsEveryDefaultSpelling, TestCreateChecksLineageForTheStoredKey, TestCrossTeamDedupeOnCanonicalize, TestPruneOwnershipIgnoresDisplayNames, a second usage-sort case, and the avatar sweep re-specified so a display-name-stemmed file is never adopted): a load writes nothing and the one-shot migration lands once; raw_agent_key files a patch where the record is and a plan-less merge honours remembered legacy keys; an overlay under the legacy key of an explicitly labelled member stays attached across loads, a live handle beats a remembered key, the allocator reserves remembered keys; a labelled member's store is recognised as owned by the reopen and admission checks and a legacy owner label resolves through the member it names; a picture filed under the label or the old key moves onto the id, never overwriting and leaving an unmovable source in place; a failing sidecar repair during rename leaves the label unchanged; a sidecar write that failed once is retried from legacy_keys on the next boot; raw_agent_key names the effective (last) overlay alias; a labelled crew's roster row reports its DM binding; identity text says the display name; create purges a team entry left under the label; the capability service reads an overlay entry filed under a legacy key; the re-key moves a picture filed under the old key onto the label; a legacy label private_to is rewritten to the id on load, a label owner is foreign to everyone, and a member taking a renamed member's old label cannot bind its private copy; an overlay default_agent by legacy key or display name selects the migrated member, a base default by display name is written back as the key, an unresolvable default is logged, and /api/config/default-agent accepts either handle while /api/agents spells the default like its rows; a rename moves no avatar file and keeps serving the committed pin, and a failed config write keeps the picture; create refuses a credential-shaped display_name; delete reaps a private copy still owned by label; overlay entries under a legacy key or display name fold onto the member with the overlay left unwritten and merge_config_documents canonical on both sides; a team naming a member by id and by display name stores it once, moves it across teams under either spelling, and a legacy display-name document reads as the key; planner (re-key, id-less keeps key, id already a key refused, duplicate id refused, a refused move keeps its key so its mover is refused too, refusals cascade along a chain, the document rewrite never drops an entry); allocator reserves display names and create never mints a key equal to a live label, create refuses a handle held as another member's label; identity-namespace property tests (random create/rename/delete over colliding labels, arbitrary tangled documents); load migration (old shape → keyed by id with old key as display_name, default_agent follows, write-back lands once and is idempotent, new shape not rewritten, collision stays where stored); resolver (by key and by display name, key beats a display-name spelling, shared display name refused, member_slug for either handle, allocator reserves keys with own-key exemption); rosters carry member_id + display_name + name alias on both endpoints; rename keeps member_id, memory store, slug and DM binding while refusing a taken handle or an invalid name; update by id and by display name hit one record; unknown handle → 404; delete by display name; dispatch identity resolves either handle; a team write refuses a canonical key the reader would not read back and the read view keeps the stored spelling over one; two records sharing a label ship their keys as name and the shared label is 404 while each key is answered; the usage sort ranks a labelled crew by the key sessions pin; kirocrew agent delete by id finds the record under its legacy key and still refuses the default under either spelling; a base default_agent spelled as a still-stored legacy key pends no write-back and is moved by the one-shot migration; a created or renamed handle taken between the snapshot and the lock is refused inside the lock (409), never written twice; an owner recorded under an unambiguous legacy key still owns their private copy while a live key or a contested spelling owns nothing; the capability service's lineage and receipt checks accept that same unambiguous legacy-key owner and fail closed on a contested one; a fork's publish receipt member follows the re-key; /api/members ships an empty member_id for a credential-shaped key behind a benign label. Rules and DM bindings recorded under the pre-re-key label still attribute to the member (and not to a member who now holds that label live); a create or rename takes a label another member only remembers as a legacy key and retires the alias, refuses it while an overlay entry is still filed under it; the masked-key row still reports its live binding. test_cli_doctor_member_memory.py: a credential-shaped key behind a clean label is counted and never printed. test_agent_execution_catalog.py: two members sharing a label ship their keys as name.

Updated: test_governance_profiles.py (a record spelling itself as a bound task id via display_name/legacy_keys selects nothing; the stale-bind report names a task:<old key> bind on a moved record and writes nothing), AgentSelector.test.tsx (the id chip beside a covering label shows the member_id, the handle agent= addresses -- never the roster's name, which is the label), SchedulePage.agentColumnSettled.test.tsx (a failed catalog fetch leaves the kind cell's tooltip as the model alone, never a bare separator), test_session_capabilities.py (a binding write lands on the legacy record while the re-key has not persisted), test_members_eventlog_wiring.py (a renamed member keeps its projection and config write-through; a label header still proves ownership), test_members_dm_thread.py (the concurrent-ownership fault flips owner_member_id, the authoritative field), test_session_capabilities.py (members seeded under their ids; a capabilities save through the display name lands under the key and reads back by either handle), test_auto_improvement_members.py (rename is a display_name edit and a legacy re-keyed document loads the same way; the Scout adopted under a distinct id stays governed under that id, not its template; a replacement role member is found by its label; recovering a role whose name a retired record still holds as its key is refused with the config unchanged until that record is deleted), test_crew_memory_store_binding.py / test_member_memory_ownership.py (a recreated member is reached by its name, keyed by a suffixed id), test_member_essential_context.py (a display-name handle selects the member labelled with it), test_crew_routing_and_delegation.py (crew is the key, display_name alongside), test_config_api.py / test_agent_publish_endpoint.py (mocks accept the alias keyword), test_agents_roster_contract.py (member_id joins the pinned row key set and is identity, not masked content; legacy_keys is classified withheld; fixtures' member_id equals their key), test_crew_display_name.py (rows located by member_id; masked label falls back to the key in name), test_members_roster_redaction.py (rows keyed by member_id), test_select_crew.py (crew is the key, display_name rides along), test_agent_sync_prune.py (package sync refuses a name a Crew Member holds by key, display name or legacy key, on the snapshot and inside the lock; a field only the live entry carries keeps the row from a stale prune), the ChannelPage suites (the agent rail's roster fetch is mocked).

Manual verification

Isolated worktree gateway (dev-backend.sh, own KIROCREW_HOME, port 6789, --no-crons; the live gateway untouched), built SPA from this head. Seeded through the real API: POST /api/agents {"name": "Crew Program Manager"} → member_id: crew-program-manager; POST /api/crons with agent: "crew-program-manager" (what the Schedule form's picker now stores); POST /api/channels with a role whose agent is that id. Then, in headless Chromium against that gateway: the Schedule table's Agent column and the channel agent rail both read Crew Program Manager; a getByText('crew-program-manager', {exact: true}) probe on each page counts 0; no role=dialog was open when either frame was taken. The Webhooks page is untouched by this PR: a webhook token pins a TEMPLATE (GET /api/agents/installed, rows without member_id) and the create route refuses any other destination -- POST /api/webhooks/tokens {"agent": "crew-program-manager"} against the same gateway answered 400 destination_agent_unavailable -- so no crew handle can ever be stored there and there is nothing to resolve. Old-shape boot, same gateway: config.json rewritten by hand to the pre-PR document (agents keyed by the label Crew Program Manager carrying member_id: crew-program-manager, no display_name, default_agent: "Crew Program Manager", the cron's stored agent left as the label), gateway restarted: after boot the document is keyed crew-program-manager with display_name: Crew Program Manager, legacy_keys: ["Crew Program Manager"] and default_agent: crew-program-manager; a second migrate_member_identity() call reports rekeyed: 0; the Schedule row and its picker still read Crew Program Manager for the label-valued slot. A record with no member_id (a legacy template-style agent) is deliberately left under its key -- it has no identity to key by. Gateway torn down afterwards.

Screenshots / video

The picker stores member_id for a crew; both surfaces that render the stored value show the crew's display name, not the id. Dark theme, 1280×800 @2x, captured against the isolated gateway described under Manual verification.

Schedule — a job created with the crew picked as "Crew Program Manager" (stored agent: crew-program-manager) shows agent · Crew Program Manager in the Agent column:

Schedule table: the Weekly status digest row's Agent column reads "agent · Crew Program Manager" for a job whose stored agent is the member id crew-program-manager

Schedule -- the edit form of the second id-stored job ("Weekly program digest", agent: crew-program-manager) with the crew picker open, the control this PR rewires: the trigger reads Crew Program Manager, and the marked-current row is that crew with its id crew-program-manager as the small chip beside the label -- the handle agent= in spawn params, crons and the CLI address, kept readable exactly because the label now covers it (a template row such as kirocrew has one handle and no chip). Captured against the repo's dist fixture harness (website/scripts/lib/serve-dist.mjs + stub-dashboard-api.mjs) with a migrated roster; dark theme, 1440×900 @2x:

Schedule job form with the agent picker open: the trigger reads "Crew Program Manager" and the highlighted current row reads "Crew Program Manager" with the id chip "crew-program-manager" beside it; the kirocrew row above it has no chip

Schedule -- the same table while the roster fetch (GET /api/agents/catalog) fails: the Agent column shows the kind (agent, the separator belongs to the name line and is withheld with it) with the crew name withheld, no stored id is printed, and the cell's tooltip is the model alone (sonnet) rather than a bare separator; the toolbar's ErrorNotice with Retry (the form's own recovery, unchanged here) is the one report. Same fixture harness, catalog route answering 500:

Schedule table while the crew roster failed to load: three jobs whose Agent column reads "agent" with no crew name and no member id, and an inline notice with a Retry button

Channels -- the agent rail, first with the roster fetch (GET /api/agents/catalog) failing, then after Retry. Each row is the role title (wrapping at word boundaries, never truncated) with the ✕ remove button on one line, the resolved crew name on its own line beneath, and the state badge, the listen-mode badge and the ↺ clear-context button on a third line -- two controls per line at most. While the names are unavailable the standard ErrorNotice reads "Couldn't load agent names — showing roles only." -- the vocabulary every sibling surface uses (Schedule's column is "Agent"), saying what still shows: the role names beneath it are the channel's own -- with Retry as its one action beneath it, and the crew line is not rendered (so no stored id is). A Retry that lands resolves the name. This is a failure state, so it is captured against the repo's dist fixture harness (website/scripts/lib/serve-dist.mjs + stub-dashboard-api.mjs) with the catalog route answering 500, then 200 on Retry; dark theme, 1280×820 @2x:

Channel "Gamma rollout" with the agents rail open while the agent names failed to load: an inline notice "Couldn't load agent names — showing roles only." with a Retry button beneath it sits above the Researcher and Reviewer rows, whose role titles read in full, and no member id is shown

The same rail after Retry: the notice is gone, the Researcher row reads "Crew Program Manager" in full on its own line under the role title, the remove button sits top-right beside the title, and the state badge, listen-mode badge and clear-context button share the line below

Chat -- the sidebar session rows and the composer's agent chip for a session pinned to the member (stored agent: crew-program-manager): both read Crew Program Manager, the template-pinned sibling reads kirocrew, and no stored id is on the page. Held blank until the roster answers, so the id never flashes. Same fixture harness, 1440×900 @2x:

Chat page with the sidebar open: the "Release readiness digest" session row reads "Crew Program Manager" beneath its title, the sibling "Refactor the cron parser" reads "kirocrew", and the composer's agent chip reads "Crew Program Manager"

No motion or element replacement is introduced, so stills suffice.

Related Issues

Predecessor: #11121 (free-form display names, merged).

Fixes #13688

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

@CrysisDeu
CrysisDeu requested a review from a team September 27, 2026 08:35
@CrysisDeu
CrysisDeu requested a review from a team as a code owner September 27, 2026 08:35
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

Intent: Make member_id the key of config.agents and the display name a plain field, so a rename never moves anything a crew member owns and every lookup resolves either handle through one resolver.
Not a goal: touching governance / spawn allowlist / MCP identity (they stay on the kiro_agent template name), changing the kiro_agent grammar, or dropping the name response alias this release.

@github-actions

github-actions Bot commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] a99af92

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

@CrysisDeu
CrysisDeu force-pushed the feat/agents-keyed-by-member-id branch from 1d36e3a to 125c0c1 Compare September 27, 2026 08:42
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 27, 2026
@github-actions

github-actions Bot commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — 🟡 CONCERNS

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

UX-Verdict: CONCERNS

Icon-only ↺ "Clear Context" in the re-laid-out agent rail is unreadable: the blind reader called it "restart or refresh that helper? no idea."

Watch

  • Clear-context misread as refresh — the diff re-lays out AgentControlRow and keeps onClearContext as an icon-only RotateCcw button (shot-04/05); RotateCcw conventionally means reset/refresh, so a user trying to unstick an agent can wipe its conversation context, while a user wanting the feature can't find it. Every channel visit × destructive outcome × persistent → CONCERNS. Fix: pair the icon with a visible "Clear context" text label, or fold it into the listen-mode row's menu as a named item.

Suggestions

  • AgentSelector row (shot-02): the label and new id chip truncate to near-identical text side by side ("Crew Program Ma…" / "crew-program-ma…"), reading as a stutter; raise the chip's max-w-[9rem] or let the display name render in full so at least one handle is legible.

[UX-REVIEWED] a99af92

Description read

[DESCRIPTION-READ] 520d17541e4639d8171f2a4ff421b8f8f547dc9092eacd5d6422b652138227a6

That sha256 names everything this verdict read: the PR description, plus the 9 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 Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify one real upgrade: a pre-upgrade config.json plus a display-name-keyed config.local.json overlay, through gateway boot, rename, and binding write.

Suggestions

  • The refused-move / stale task: bind warnings live only in gateway logs; since doctor_checks/agents.py is already in this PR, a doctor line naming the exact task:<old> -> task:<id> re-point would reach the operator who must act.
  • The name alias is "kept for one release" in three places (roster, KiroCrewAgent, config.md) — record the removal as a tracked follow-up now so the deprecation doesn't silently become permanent surface.

[DESIGN-REVIEWED] a99af92

Description read

[DESCRIPTION-READ] 0efd8e1869e9cc91659b5f63cdd894f57424ff8762298605c80d8bd3bcb6e70e

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 Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of a99af92b0eb1fdc2e918c43bac5f55b6f5a0d077 — 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: CONCERNS

The create-collision check now lives in two divergent copies (CLI vs dashboard), and a channel-rail control re-layout rides along with no named failing user.

Not justified as shipped

  • Item 7 — duplicate of src/kiro_crew/dashboard/handlers/agents.py:5316: the carried = [display_name or name] collision check is inlined twice (grep: 2 sites, cli_commands.py:1470 and agents.py:5316) with different predicates — CLI's resolve_member counts a legacy-alias name as taken, dashboard's member_live_holders frees it — under a comment claiming "Same keying as POST /api/agents"; the deleted key_new_crew docstring pinned this as "the one decision both create surfaces share".
    Subtraction: replace both inline copies with one shared predicate in members.py (the successor to key_new_crew), so the CLI stops refusing a create the shared in-lock authority (persist_member_config) would accept.
    Clears when: one predicate at one site, or evidence the CLI's stricter legacy-alias refusal is intended.
  • Item 8 — rides along, unjustified move: AgentControlRow in ChannelPage.tsx reflows to two lines, moving ✕ to top-right and clear-context to a second row; the diff's own rationale ("a medium name is never squeezed") names no report, misclick or complaint, and the zero option — the pre-existing truncate treatment every other surface still uses — costs nobody anything named.
    Subtraction: keep the prior single-line row with the resolved name truncated; defer the re-layout.
    Clears when: the re-layout is dropped, or a named report of the squeezed/unreachable control.

What this change ships

Inventory (10 items, capped — the change has more) — 8 justified

Intent: make a crew member's display name a pure label — rename freely, nothing the member owns moves — by keying config.agents on the already-minted member_id. A FIX of a structural cause (the key was presentation text), grounded in the Design Review finding on #11121.

  1. config.agents keyed by member_id, with a one-shot boot/CLI migration of the document, fork-sidecar owners and avatar files — justified
  2. Renaming edits display_name only; key, DM slot, crons, memory never move — justified
  3. Every handle route and lookup answers the id or the display name through one resolver, refusing ambiguity — justified
  4. New persisted agents.*.legacy_keys field recording pre-migration keys as aliases — justified
  5. Rosters ship member_id; name becomes the display name (alias kept one release); default_agent echoed as the label — justified
  6. Pickers (Schedule, Channels, Chat settings) store member_id; surfaces resolve stored values to display names and hold labels until the roster settles, with a retry notice on failure — justified
  7. Create keying re-implemented inline on both create surfaces after deleting the shared key_new_crew — duplicate of src/kiro_crew/dashboard/handlers/agents.py:5316 (divergent predicates)
  8. Channel-rail agent row re-laid out (✕ moved to top-right, badges/clear-context to a second line) — rides along, unjustified move
  9. Re-key refused and reported (never rewritten) for keys a governance task: profile binds — justified
  10. Agent sync and Auto-Improvement ensure_team refuse a name a crew member already answers to, naming the holder — justified

[FIRST-PRINCIPLES-REVIEWED] a99af92

Description read

[DESCRIPTION-READ] c7386bec27ac5476a5ce4566adf4b2601e45ce568f54dffe8afd2e597ccfd687

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 added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 27, 2026
@github-actions

github-actions Bot commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] a99af92

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

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

@CrysisDeu
CrysisDeu force-pushed the feat/agents-keyed-by-member-id branch from 125c0c1 to 926d188 Compare September 27, 2026 09:41
@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 27, 2026
@CrysisDeu

CrysisDeu commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor Author
  • overlay entries split into duplicate members span=9ec07ed2ded9 -- fixed in 926d188

The base document's agents are re-keyed BEFORE config.local.json merges in, and the overlay's entries are folded onto the base member they name: by the base entry's legacy key, else by its unique display_name (canonicalize_overlay_agents / merge_config_documents, config/loader.py).
Only the base migration is persisted; the user-owned overlay is never written back and is re-canonicalized on every load, so no phantom partial member can exist and the display-name handle resolves to the one member.
The capability service's raw base+overlay merges (snapshot and _write_bindings) go through the same merge_config_documents.
Tests: TestOverlayStaysOneMember (legacy-key overlay, display-name overlay after migration, merge helper canonical on both sides, overlay bytes unchanged).

@CrysisDeu

CrysisDeu commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor Author
  • display-name capability writes index the wrong key span=4a1a32f49c7b -- fixed in 926d188

CapabilityService._snapshot resolves the handle to the config.agents key once (_canonical_member) and every derived value -- snap["member"], accepted members in _plans, sidecar private_to, the config binding index in put/publish/reset -- carries the key; prepare_member_capabilities / reconcile_member_capabilities and the HTTP route (handlers/agent_capabilities.py) canonicalize the same way, so the runtime view keys match.
A sidecar whose private_to still records the display name is accepted as the same member (_owned_by).
Test: test_capabilities_saved_through_the_display_name_land_under_the_key (save via the display name -> binding and sidecar under the key, read back identical by either handle), plus test_session_capabilities re-seeded on id keys.

@CrysisDeu

CrysisDeu commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor Author
  • aliases bypass the one-team membership invariant span=5fbedb0d76dc -- fixed in 926d188

Team members are stored by ONE identity, the config.agents key: the known set holds keys only, and every submitted handle (members, add, remove) plus every stored entry is mapped through resolve_member_id before validation, de-duplication and the one-team detachment (crew_teams.canonicalize_teams, Canonical callback; handlers/teams.py::_Registry).
Responses map the key back to the roster handle, so the dialog contract (m.name) is unchanged.
Test: test_id_and_display_name_alias_store_one_member (id + alias submitted together stores once; naming the alias on a second team detaches the first; remove by alias; legacy display-name document reads as the key).

@CrysisDeu

CrysisDeu commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor Author
  • function-local resolve_member_id imports lack the circular-import rationale span=15137de977ab -- fixed in 926d188

Both function-local imports in config/loader.py (_resolve_agent_selection, resolve_crew_identity) now carry the rationale: kiro_crew.members imports config.paths and config.loader imports select_provider_backend from members at call time, so a module-scope import closes the config.loader -> members -> config cycle. The imports stay local because the cycle is real.

@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 27, 2026
@CrysisDeu
CrysisDeu force-pushed the feat/agents-keyed-by-member-id branch from 926d188 to 96113de Compare September 27, 2026 10:30
@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 27, 2026
@CrysisDeu

Copy link
Copy Markdown
Contributor Author
  • Reused display names inherit another member's private copy span=d77e9c4049d0 -- fixed in 96113de

Ownership of a private copy is decided on the member id only: the alias acceptance path in _foreign_private_copy_owner, _rebind_crew_locked and the fork/publish/reset and capability checks is gone; a private_to recorded by label reads as foreign to everyone, the labelled member included.
The load-time re-key that keys the agents map also rewrites the fork sidecar's legacy label owners to ids (agent_state.rekey_private_owners, same plan, same lock order); the rename route repairs its own member's copy (claim_private_owner, exact template + exact old owner only) before the label changes hands.
Tests: legacy label owner rewritten on load; label owner never this member; rename then a new member taking the old label -> _foreign_private_copy_owner names the original, PUT kiro_agent -> 409 foreign_private_copy.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author
  • Overlay default agent breaks after migration span=9ec07ed2ded9 -- fixed in 96113de

merge_config_documents maps default_agent on BOTH sides through the same key / legacy-key / display-name mapping the overlay's agents entries use (canonical_agent_key); the base's label default is written back as the key via MIGRATE_DEFAULT_AGENT, the overlay is never rewritten and resolves on every load.
A default that still names no member is logged with the remedy instead of being silently replaced.
Tests: overlay default by legacy key selects the migrated member across the migration reload and by display name; base default by display name written back as the key; merge helper maps both sides; unresolvable default logged.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author
  • Failed avatar move commits a rename that hides the avatar span=d77e9c4049d0 -- fixed in 96113de

The rename is one transaction with the files: _rename_avatar_files moves every variant first and is all-or-nothing (a failing move puts the moved ones back and raises); a failed move answers 503 avatar_move_failed with the label, pin and files untouched; a config write that then fails runs _unrename_avatar_files so the files return under the old stem.
Tests: a monkeypatched failing replace_with_retry -> 503, display_name and pin unchanged, picture still served; a failing persist_member_config -> files back under the old label, picture still served; a successful rename moves the picture with the label.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author
  • returning display text as name makes the default selector submit a label span=583f63beb6ea -- fixed in 96113de

Chosen: keep name as the display-name alias (the dashboard addresses rows by name in a dozen places and shows it) and make the server accept it: PUT /api/config/default-agent resolves either handle through resolve_member_id and stores the key; GET /api/agents spells default_agent as the rows' name (default_member_id beside it) so row.name === default_agent marks the default; the GET/PUT responses carry both spellings.
Audited every write route taking a member handle (agents routes, capabilities, members, teams, default-agent, chat/cron/messaging crew=): each resolves id and display name.
Test: PUT default-agent by display name stores the key; roster default_agent equals a row's name; unknown handle -> 400.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author
  • create vets only name with _name_would_be_masked while display_name gets only validate_member_name span=c3f437d06514 -- fixed in 96113de

POST /api/agents now runs _name_would_be_masked on an explicit display_name and answers the same 400 credential_shaped_name the rename branch does, so no unchattable record is stored.
Test: credential-shaped display_name -> 400, nothing persisted.

@CrysisDeu
CrysisDeu force-pushed the feat/agents-keyed-by-member-id branch from 8c3e478 to cd8cf82 Compare September 28, 2026 06:10
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Sep 28, 2026
@CrysisDeu
CrysisDeu force-pushed the feat/agents-keyed-by-member-id branch from cd8cf82 to 0c6b439 Compare September 28, 2026 06:54
@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge 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 28, 2026
@CrysisDeu
CrysisDeu force-pushed the feat/agents-keyed-by-member-id branch from 0c6b439 to b270cd6 Compare September 28, 2026 08:17
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 28, 2026
@CrysisDeu
CrysisDeu force-pushed the feat/agents-keyed-by-member-id branch from b270cd6 to b89c7e2 Compare September 28, 2026 09:37
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Sep 28, 2026
…field

config.agents is keyed by the crew's immutable member_id; the free-form name
becomes the display_name field. member_id keeps the allocation
_allocate_member_id already does (now also reserving every agents key,
display name and remembered legacy key), and a rename edits display_name
only -- key, members/<id>/, DM slot key, cron member_id, owner_member_id and
the avatar files (stemmed by the id) never move.

Migration: KiroCrewConfig.load serves the id-keyed view and writes nothing;
migrate_member_identity is the one writer -- once, under the config lock,
off-loop at gateway boot and in the CLI prologue -- re-keying the document
(old key kept in legacy_keys and as display_name when the record had none,
default_agent following), moving fork-sidecar private_to owners onto the id
(re-derived from legacy_keys on every boot, so a failed sidecar write is
retried) and moving every member's picture from any legacy handle onto its
id without ever overwriting. Collisions are refused and logged; id-less
entries keep their key.

Every user-facing handle (API path params, chat/spawn crew=, cron member_id,
slot pins, select_crew) resolves through members.resolve_member(handle):
key first, then the unique display_name, then a remembered legacy key;
unknown -> 404. Roster responses carry member_id + display_name and keep
name as an alias of display_name for one release; the picker dispatches
member_id so a chat slot survives a rename. Overlay patches land on every
alias an overlay still carries; a rename purges its new label from stale
team entries; the sync prune judges staleness on binding fields only.

Fixes #13688. Predecessor: #11121.
@dwu96

dwu96 commented Oct 5, 2026

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: dwu96#8c08bee0]: This PR has been inactive for 7+ days. All 89 checks are green and readiness passed, so the only thing standing between it and merge is the conflict — but I measured it before offering to drive it, and the resolution needs your hand rather than mine:

  • The conflict is a re-homing job, not a guided resolution. main is 889 commits ahead of the merge base (3a770911e). A test merge yields 13 conflicting files / 28 hunks / ~6,600 conflicted lines, and only one of the 13 is a test file. The dominant hunks are add/add placements where HEAD's side is empty and this branch contributes a block that lost its anchor: dashboard/handlers/agents.py alone has five such blocks of 1225, 1741, 1282, 479 and 311 lines (5393 of its 7142 lines sit inside conflict markers), plus one of 599 lines in dashboard/handlers/messaging.py. Choosing where each of those ~5,600 lines belongs inside main's restructured handlers is a design decision I'd be guessing at.
  • Why that guess is unusually expensive here. The invariants you proved red-first across ~20 dispositions — the refused-move fixed-point cascade in plan_member_rekeys, _allocate_member_id reserving every display_name, legacy_keys / member_key_aliases.json overlay folding, the all-or-nothing avatar rename with claim_private_owner inside its rollback scope, store_owned_by_member as the single ownership predicate — are exactly the kind of thing a mis-placed block drops silently. And they'd have no CI signal on the new base until the placement is already right, so a wrong resolution looks green.
  • readiness: passed is stale evidence. Those 89 green checks were measured against the 889-commit-old base, not against what this will actually merge into.
  • First-Principles item 7 — your call on the predicate. The carried = [display_name or name] collision check is inlined at both cli_commands.py:1470 and agents.py:5316 with divergent predicates (CLI's resolve_member counts a legacy-alias name as taken; dashboard's member_live_holders frees it) under a comment claiming "Same keying as POST /api/agents". Clears when it's one predicate at one site in members.py, or you confirm the CLI's stricter legacy-alias refusal is intended. I can't pick which.
  • First-Principles item 8 — scope decision. The AgentControlRow re-layout in ChannelPage.tsx rides along with no named failing user; clears when it's dropped or a report is named. Worth settling before the rebase, since three of the conflicting frontend files (ChatPage.tsx, ChatSidebar.tsx, settings/ChatPanel.tsx) are in that neighbourhood — and dropping it would also retire the UX CONCERNS below.
  • UX CONCERNS (advisory, still open). onClearContext stays an icon-only RotateCcw, which reads as reset/refresh — a user trying to unstick an agent can wipe its context instead. Fix is a visible "Clear context" label or a named item in the listen-mode row's menu.

For reference, these conflicts are mechanical and not what I'm asking you for — config/loader.py (17 lines, the member-rekey plan vars vs HEAD's base_unreadable, keep both), mcp_core.py (66), slack/gateway.py (76), chat_persistence.py (21), subagent_manager/admission/gate.py (15), ChatSidebar.tsx (14), execution_context.py (5), settings/ChatPanel.tsx (5) and test/test_agent_execution_catalog.py (59).

When you've rebased and settled items 7 and 8, the pipeline will re-assess on its next cycle. Add pr-no-autofix if you'd prefer no automated involvement at all.

@bolichen97 bolichen97 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.

PR triage (automated, against origin/main 5edf2feecb): requesting changes for a breaking change that isn't declared, plus a required rebase

I read the full diff (head a99af92b, merge base 3a770911) and compared it against current main.

  1. This is a breaking change for anyone with an existing config, but the PR doesn't say so. migrate_member_identity (config/loader.py) rewrites the user's config.json once, so agents is keyed by member_id. The ## Backwards compatibility section itself admits a downgraded release then shows every member under its id, and lookups by the old label miss until the user upgrades again or edits the file. A one-way rewrite of persisted user data is a take-away change under docs/system-specs/common/take-away-changes.md. The body has zero Reader: lines and no Breaking: line. Please list each reader of the old key shape (chat resume, cron agent, subagent spawn, app bundles, profiles/ task binds, Slack channel bindings, crews_wearing in dashboard/appearances.py, handlers/files.py workspace refs) with a test for each, and add a Breaking: line for the downgrade behaviour.
  2. A public helper is removed while main still calls it. The PR deletes members.key_new_crew, NewCrewKey and crew_id_for_display_name. Since the merge base, #16786 (d167e192b8) moved create into src/kiro_crew/dashboard/agent_admin/crew_records.py, which calls key_new_crew at L343. This branch never touches that file. Open PRs #15326 (Captain) and #16200 also import key_new_crew. The rebase has to re-home the create keying into crew_records.py. Please also settle First-Principles item 7 there: use one shared create-collision predicate instead of the two divergent copies in cli_commands.py and agents.py.
  3. The branch is stale. It is 1,037 commits behind main and mergeable_state=dirty (see the operator comment above for the conflict breakdown). The readiness: passed result was measured against the old base.

I found no P0 bug in the diff as written. The relationship to merged #14865 is overlap/replacement: this PR deliberately replaces #14865's create-time keying. It is not a duplicate.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author

@bolichen97 thanks for the review. Where this stands against current main:

Before that rework, a maintainer needs to pick one approach:

  1. One-way config.json rewrite to the new keys. This is a breaking (take-away) change and would ship with Breaking: and Reader: lines plus a test per reader, as you asked.
  2. Keep the old keys and add a display-name alias in the resolver. No rewrite of user config. Main's current docstring ("a crew already stored under a free-form name stays readable and is never renamed") fits this one.

Which one should the new PR take? Marking this PR parked until that is decided.

@CrysisDeu

CrysisDeu commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor Author

Superseded by #25805, a fresh branch off current main. Closing this one (branch kept).

@bolichen97, on your review:

  1. Breaking one-way rewrite. fix(members): resolve a crew named as a crew by its member_id without re-keying config.agents #25805 takes the non-breaking route: config.json is never rewritten and no key is renamed. Old display-name keys stay as stored. A lookup from a crew's member_id to its stored key is added instead (canonical_member_key, resolve_crew_identity, _resolve_agent_selection), so there is no downgrade behaviour to declare. display_name stays a presentation label and never resolves a crew, as crew-mode.md records.
  2. Removed helpers still called on main. Nothing is removed. key_new_crew, NewCrewKey and crew_id_for_display_name stay, and dashboard/agent_admin/crew_records.py is untouched.
  3. Stale branch. The new PR is 1 commit on current main.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge needs-author-decision PR blocked on author input parked Kept open as a request; not on the current plan

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Key config.agents by member_id and store display_name as a field

5 participants