Skip to content

feat(crews): key new crews by an id and keep the typed name as label - #14865

Merged
bolichen97 merged 2 commits into
mainfrom
feat/crew-id-display-name
Sep 29, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
feat/crew-id-display-name

Conversation

@buluoray

@buluoray buluoray commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: New crews are keyed by a stable id while the name the user typed is shown as their display name, without breaking any crew or client that exists today.

A crew's config.agents key is its identity: /api/agents/{name}, crons, teams, spawn_run(crew=), slot metadata and the member directory all address it. Since #11121 the key itself accepts free-form text (spaces, CJK), so a label became the identity. That identity then needs a lossy slug for paths (with 409 briefing_slug_ambiguous on collisions) and NFC/redaction guards on every read. #13561 already added a presentational display_name, but nothing routes a typed name into it.

Why it matters

Every new crew named in a user's own words gets a free-form identity that every addressing surface has to defend, and two labels that slug alike collide on disk. Keying by an id and showing the label keeps renames and labels cheap and the identity boring.

Not a goal

  • Migrating crews already stored under a free-form key to an id. They stay readable, dispatchable and addressable exactly as today.
  • A rename operation for crew ids.
  • Relaxing the Meet CrewMates flow's client-side id-grammar hint.

What changed (motivation → approach → change)

  • Approach: decide the key at the one place a crew is born. members.key_new_crew makes that decision for both create surfaces (POST /api/agents inside the config lock, and kirocrew agent create). An id-shaped name (validation._AGENT_NAME_RE) is kept as the key, as before. A free-form name becomes the label (unless a display_name is sent) of a derived id. This keeps old clients that send only name working, instead of refusing them.
  • Derivation (members.crew_id_for_display_name): slug of the name, -2, -3... past a taken id, crew-<hash> for a name with no slug characters.
  • Refusal: 409 agent_exists when the key is taken, or when the name the new crew would show (explicit display_name, else the typed free-form name, else the key) is exactly what another crew already shows. Editing an existing crew's label is unchanged and unchecked.
  • The create answer's name is the id.
  • CLI: --display-name; the success line names the id and the label.
  • New crewmate dialog: opens the crewmate by the id the server answered with, refuses a name another crewmate shows before any request (it checked keys only), and greets the new crewmate by the name it shows rather than its id.
  • Spec: learn-cron-dashboard.md members paragraph.

Backwards compatibility

Compatible: every name POST /api/agents and kirocrew agent create accept today is still accepted, and id-shaped names are keyed exactly as before. A free-form name now lands as the label of a derived id instead of as the key, and the answer's name says which id. Existing free-form keys are untouched by every read path.

Tests

  • test/test_crew_display_name.py: free-form name → derived id + label; explicit display_name wins; id-shaped name unchanged; derived id skips a taken id; a name another crew shows is 409 with nothing persisted, whether it arrives as a free-form name, as an explicit label on an id-shaped name, or as an explicit label on a free-form name; a typed name another crew shows is fine when this crew's explicit label differs; derivation unit tests (slug, truncation, CJK hash, suffixing, is_crew_id). Mutation-checked: dropping the shown-label comparison fails 4 of them.
  • test/test_cli_agent.py: free-form --name keys a derived id with the label; --display-name labels an id.
  • test/test_config_api.py: the create round-trip property asserts against the id the answer names and the label the roster serves.
  • MembersPage.test.tsx: a free-form name opens under the answered id and the seeded greeting names the label, not the id; a name another crewmate shows is refused with no request. Mutation-checked: reverting either change fails its test.

Manual verification

Built this worktree and ran kirocrew gateway --test-mode on a throwaway home, then drove the real SPA with Playwright: New crewmate → "Launch Notes" opens /members?member=launch-notes with the label in the header and the id beside it; /api/agents returns ["launch-notes","Launch Notes"]; a second "Launch Notes" is refused inline before any request; the Agents page shows the label with its id. The greeting fix landed after these shots and is covered by the vitest above. The test gateway has no kiro-cli, so a chat turn cannot run there.

Backend Tests shard 4 (Linux and Windows) and the Coverage Gate that aggregates it are red on test_pid_reader_ratchet (161 pid-reader sites vs 160 recorded). The same test fails on origin/main and on this PR's base; this diff adds no pid reads.

Screenshots / video

Free-form name in New crewmate:

New crewmate dialog with the name Launch Notes

Opened under its derived id, label shown:

Crewmate header showing Launch Notes with id launch-notes

The same name again is refused before any request:

Inline hint: A crewmate named Launch Notes already exists

Agents page: label with the id beside it:

Agents page card Launch Notes with id launch-notes

Related Issues

Follows #13561 and #11121.

Checklist

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

Contribution License Agreement

@buluoray
buluoray requested a review from a team September 28, 2026 23:37
@buluoray
buluoray requested a review from a team as a code owner September 28, 2026 23:37
@buluoray
buluoray requested a review from kyleseaman September 28, 2026 23:37
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 28, 2026
@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

FINDING -- src/kiro_crew/members.py:442 -- "return slug_hash_fallback(name, \"crew\")" may return a taken ID after suffix exhaustion, causing a valid free-form create to be refused -> Fix: suffix the hash fallback until an unused ID is found.
FINDING -- src/kiro_crew/members.py:476 -- whitespace-only display_name bypasses the shown-name collision check although UI surfaces fall back to the key -> Fix: strip the existing label before falling back to other_key.
[GPT-REVIEWED] 4e8cb30

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

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify that automation creating a free-form --name then addressing it by that typed text is acceptable breakage — the key is now a derived id, so follow-up update/delete calls miss.

[DESIGN-REVIEWED] 4e8cb30

Description read

[DESCRIPTION-READ] eb84bf0489dfb32fc003b4092cd9a0e4170f117d30bd30d167b3cf30603c79d3

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 29, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ human override accepted

@buluoray overrode this lane for 4e8cb301882ead22e12c448a157d92ef8fc8b43c via /ai-review override (this commit only).

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — 🟡 CONCERNS

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

UX-Verdict: CONCERNS

On the refused-name state, the still-enabled Create crewmate button leaves users unsure whether re-clicking would duplicate — the blind reader "would not dare" press it.

Watch

  • Shot-03: the name is refused inline yet "Create crewmate" looks fully pressable; the blind reader was "hesitant — I don't know if it would make a duplicate or just refuse" and listed re-pressing it under things they would not dare to use. The code is safe (NewCrewmateDialog.tsx:468 re-shows the hint, no request), but the pixels don't say so, and this PR widens when the state appears (display-name collisions too). Low frequency (collisions only) × friction/anxiety, not failure × every collision. Smallest fix: disable submit while the typed name is in existingNames, or end the hint with the way forward ("Pick a different name.").

[UX-REVIEWED] 4e8cb30

Description read

[DESCRIPTION-READ] 1263b353b6ccd5350c0fd7ef6b21c91ff112bfa0428c90d914bc3f82f958f34b

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

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

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

Review details

No blocking defect; the derived crew id now reaches three places that must show the crew's label.

FINDING — website/src/pages/members/NewCrewmateDialog.tsx:399 — after a create whose answer is lost, the reconcile matches the typed name against the roster's key (r.members.some((m) => m.name === body.name)), but a free-form "Launch Notes" is now keyed launch-notes with the typed text in display_name, so present === false and the dialog says create_failed ("Nothing was created — try again.") for a crewmate that was created, without invalidating the roster → Fix: also match the label — m.name === body.name || m.display_name?.trim() === body.name — the same duality existingNames was just taught.

FINDING — website/src/pages/members/MembersPage.tsx:2358 — { name: postCreateError.created.name } (and created.name/followUp.name at 913-916) now interpolates the server-answered id, so create_roster_failed, create_greeting_failed, add_member_pending* and add_member_settling read "launch-notes was created, but the list didn't refresh." — a name the user never typed and that no roster row shows, since memberLabel renders display_name → Fix: carry the shown label on CreatedCrewmate (e.g. onCreated({ name: r?.name || body.name, label: body.name, job })) and interpolate it in those strings, keeping name as the routing key.

FINDING — src/kiro_crew/members.py:473 — key, label = crew_id_for_display_name(name, agents), display_name or name makes the config key the id, and the member identity layer mints f"[MEMBER IDENTITY]\nYou are {member}." from that key (context.py:3692, member = the cfg.agents alias via member_config_for_id), so a crewmate the UI and this PR's own seeded greeting call "Launch Notes" is told it is launch-notes → Fix: pass the crew's display_name (falling back to the key) into _build_member_section's layer 1 — an edit to untouched context.py, so it cannot land inside this diff.

[OPUS-REVIEWED] 4e8cb30

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

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

@buluoray

Copy link
Copy Markdown
Contributor Author

Disposition for the reviews of 8284ebc4fc, addressed in 18743e7582:

UX Review (BLOCK: no legible evidence). Fixed. The GIF is replaced by four stills in the description: the dialog with a free-form name, the crewmate opened under its derived id with the label shown, the duplicate refusal, and the Agents roster.

  • Instant taken-check checked keys only: fixed. existingNames now carries each crewmate's key and its shown label (MembersPage.tsx), so "Launch Notes" is refused before any request. A vitest covers it.
  • Near-identical label beside an id (Release Writer / release-writer): accepted as is. Those are two different crews, and the roster shows each one's id beside its label, so they can be told apart.
  • Explicit display_name bypassing the check: fixed (see Design).
  • CLI help wording: now "Agent id, or any name: shown as typed, stored under a URL-safe id".

While capturing the evidence I found that the seeded first message greeted a new crewmate by its id ("Hi launch-notes"). It now uses the label, with a vitest.

Design Review (CONCERNS). Fixed on create. members.key_new_crew is now the one helper both create surfaces call. It refuses when the key is taken, or when the name the new crew would show (explicit display_name, else the typed name, else the key) is exactly what another crew shows. Tests cover an explicit label on an id-shaped name and on a free-form name. Mutation-checked: dropping the comparison fails 4 tests.

Editing an existing crew's label (PUT /api/agents/{name}) stays unchecked. That path predates this PR, and the spec now says so explicitly.

First Principles (CONCERNS).

  • Item 3, display_name in the create answer had no readers: removed.
  • Item 1, reversing the fix(members): accept free-form display names #11121 keying without an RFC: this needs a maintainer decision, either the /ai-review override first-principles or an RFC. I am leaving it to the owner rather than deciding it here.

Backend Tests shard 4 and Coverage Gate. Inherited from main. test_pid_reader_ratchet counts 161 pid-reader sites against 160 recorded, and it fails the same way on origin/main (99b25d845d) and on this PR's base (22284b7557). This diff adds no pid reads. The Coverage Gate fails only because it aggregates that shard.

@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 29, 2026
A crew's config key is its identity: routes, crons, teams, spawn and
the member directory all address it. Since free-form names were
accepted, a label with spaces or CJK text became that identity too,
leaning on lossy slugs and name-collision guards everywhere.

POST /api/agents and `kirocrew agent create` now keep an id-shaped
name as the key and turn a free-form one into the display_name of a
derived id (slug, -2 past a taken id, crew-<hash> for a name with no
slug characters). The create answer's name is that id, so the New
crewmate dialog opens what it made. A free-form name another crew
already shows is 409 agent_exists. Crews stored under a free-form key
stay readable and are never renamed. The CLI gains --display-name.
The taken check only guarded a free-form name, so an explicit
display_name on create could still mint a label another crew shows.
members.key_new_crew now decides key, label and refusal for both
create surfaces, checking the name the crew will show (explicit
label, else the typed name, else the key).

The New crewmate dialog refuses a shown label up front, not only a
taken key, and greets a new crewmate by the name it shows rather than
its derived id. The create answer no longer carries display_name,
which nothing read.
@buluoray
buluoray force-pushed the feat/crew-id-display-name branch from 18743e7 to 4e8cb30 Compare September 29, 2026 01:50
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 29, 2026
@buluoray

Copy link
Copy Markdown
Contributor Author

UX Review (CONCERNS) on 4e8cb30188: accepted as a follow-up, not addressed in this PR. Pressing Create crewmate on a refused name is safe: NewCrewmateDialog.tsx shows the hint again and sends no request, and the button stayed enabled for a taken id before this PR too. Disabling it, or ending the hint with 'Pick a different name.', would touch the i18n catalogue in every locale and restart every review lane. The finding is advisory, so I'm leaving it for a separate small PR.

@buluoray

Copy link
Copy Markdown
Contributor Author

/ai-review override first-principles 4e8cb30: Owner decision: a new crew is keyed by an immutable id (_AGENT_NAME_RE grammar) and the typed name is stored as display_name (added in #13561); free-form keys already stored stay readable and dispatchable and are never renamed. This supersedes the write-side keying #11121 introduced.

Why: a key is referenced by crons.json agent, teams.json, slot meta, dm.json, the event log and spawn_run(crew=), so it should be a stable id. The label is display-only and can change freely. Free-form keys forced lossy slugify() mapping for member dirs (409 briefing_slug_ambiguous) plus NFC/NFD and redaction guards, and #13561's display_name already covers "a name with spaces".

Scope: create paths only (POST /api/agents, kirocrew agent create), both through members.key_new_crew. Reads, dispatch and existing keys are unchanged. Migrating old keys is out of scope.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@buluoray marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for 4e8cb301882ead22e12c448a157d92ef8fc8b43c.

Owner decision: a new crew is keyed by an immutable id (_AGENT_NAME_RE grammar) and the typed name is stored as display_name (added in #13561); free-form keys already stored stay readable and dispatchable and are never renamed. This supersedes the write-side keying #11121 introduced.

This decision applies only to this commit. A new push requires a new judgment.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Sep 29, 2026
@buluoray
buluoray enabled auto-merge (squash) September 29, 2026 03:34

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

Reviewed on behalf of the maintainers (readiness sweep 2026-09-29): readiness passed, the required PR Readiness check is green on this head, no live CHANGES_REQUESTED, no open blocking review threads; where the PR's files also moved on main since its merge-base, the PR's own tests were run on the main+PR merge tree and passed. Approving and squash-merging.

@bolichen97
bolichen97 merged commit 2e6ce15 into main Sep 29, 2026
141 of 144 checks passed
@bolichen97
bolichen97 deleted the feat/crew-id-display-name branch September 29, 2026 04:29
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants