Skip to content

fix(crewmate): tell each crewmate's user what the upgrade did to it - #23602

Merged
buluoray merged 2 commits into
mainfrom
fix/crewmate-upgrade-notice-skips
Oct 24, 2026
Merged

buluoray merged 2 commits into
mainfrom
fix/crewmate-upgrade-notice-skips

Conversation

@buluoray

@buluoray buluoray commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: After the Crewmate 2.0 upgrade, every crewmate's user learns what happened to it: a moved one says where its worker's kit is changed, and one the migration left behind says why.

Two gaps from the #23010 review (CrysisDeu, minor items):

  • The one-time upgrade notice tells the user to see what the worker can do in Edit mate > Built From. That pane only shows the kit. It is changed in the same editor under Advanced, Worker's extra kit, which the notice never names.
  • A crewmate the startup migration leaves where it was (its worker would differ, its agent could not be read, its file or its repoint failed) gets one WARNING in the gateway log and nothing else. Its user sees no change and no reason.

Why it matters

A user told where to look but not where to act has to hunt for the control that changes their crewmate's worker. A user whose crewmate silently stayed on the old setup thinks the upgrade happened to it, and has no way to learn what to fix so it moves at the next start.

Not a goal

  • Changing what the migration moves or how it decides.
  • A crew-page or roster indicator for a crewmate left behind.
  • Retelling a crewmate still left behind at a later start, or telling it again when its reason changes.
  • The record-less conductor worker store (another feat(crew): give each crewmate its own config, a conductor and a worker #23010 minor item); it edits session_create.py, which other open pull requests change, and follows them.

What changed (motivation → approach → change)

Both are fixed in the crewmate's own thread, through the one-time notice path #23010 built (mate_upgrade_notice, delivered by dashboard/mate_thread_wakes.py with an O_EXCL claim), so there is no new surface.

  • Commit 1: the upgrade_notice text in src/kiro_crew/crewmate_prompts.json now also names where the kit is changed ("in the same window under Advanced, Worker's extra kit"). Only that sentence changes; test/fixtures/crewmate_prompts/all-met.golden.txt gets the same one-line edit (the rest of that golden already differs on main and is left alone).
  • Commit 2: mate_config_migration._tell_kept runs at the end of a pass and owes each crewmate it left behind one notice (src/kiro_crew/mate_upgrade_notice.py:mark_kept_owed, members/<slug>/worker_kept_owed.json). The reason is the dry run's own reader-facing text, else a plain cause ("the agent it runs on could not be read" and so on). offer_upgrade_notice claims it once (claim_kept_notice, worker_kept_claimed.json) when no moved notice is owed, and the flush delivers it as one hidden [Worker upgrade] turn from the new upgrade_notice_kept piece. The claim code is shared (_claim); claim_notice keeps its signature. A crewmate that moves at a later start drops its unclaimed kept record (clear_kept_owed, beside mark_notice_owed), and claim_kept_notice answers nothing once a moved notice is owed or claimed, so a moved crewmate never says it was left behind. A kept notice claimed while the thread is busy is flushed at the thread's next turn end, as a pending report is (note_turn_end).

docs/system-specs/modules/crew-mode.md (the "tells its user once" paragraph) records both.

Backwards compatibility

Compatible: a moved crewmate's notice is claimed and delivered as before; the kept notice uses its own two files, so it never blocks or replaces the moved one.

The diff changes the migration module (a take-away shape), though it removes nothing: it adds one step at the end of a pass. Readers of what it touches, from origin/main:

Reader: src/kiro_crew/dashboard/server.py:start_dashboard -- release -- calls migrate_existing_crewmates as before; the new _tell_kept step only writes notice records and never raises; test_the_migration_owes_the_notice_only_for_crewmates_it_moved
Reader: src/kiro_crew/dashboard/mate_thread_wakes.py:offer_upgrade_notice -- chat -- claim_notice keeps its signature and result, and a moved crewmate's notice is claimed first, as before; test_a_moved_crewmate_tells_its_user_once_and_never_on_a_later_start

Tests

Proof: PROVEN test/test_mate_upgrade_notice.py::test_the_notice_names_the_path_to_the_worker_tabs_as_the_dashboard_shows_it (head d951911)

  • test/test_mate_upgrade_notice.py:
    • test_the_notice_names_the_path_to_the_worker_tabs_as_the_dashboard_shows_it: the notice names Advanced, Worker's extra kit.
    • test_the_notice_names_the_editor_labels_the_dashboard_shows: those words are the English labels the editor renders (crewWorkerKit in en.manual.json).
    • test_a_crewmate_the_migration_left_behind_tells_its_user_why_once: a crewmate whose worker would gain execute_bash stays put, and its thread gets one notice naming that reason, not again on a later start; the moved crewmate owes none.
    • test_a_left_behind_crewmate_that_moves_later_never_says_it_was_left: left behind at one start with its thread unopened, moved at the next; its thread gets the moved notice only.
    • test_a_kept_record_left_beside_a_claimed_moved_notice_is_not_delivered: a stale kept record beside a claimed moved notice is never claimed.
    • test_a_kept_notice_claimed_while_the_thread_is_busy_follows_its_next_turn_end: claimed while a message is queued, delivered at the next turn end.
    • test_the_migration_owes_the_notice_only_for_crewmates_it_moved: unchanged behaviour, now on a shared setup helper.
  • Ran locally: test_mate_upgrade_notice.py, test_mate_thread_wakes.py, test_mate_config_migration.py and every test reading crewmate_prompts (54 passed), lint, mypy, semgrep, docs-lint, and scripts/local-gate.py --base origin/main: backend passed (178); frontend failed the same 14 tests in the same 8 files as on fix(crewmate): fail closed on a cron whose crewmate file is gone #23529, none touched here, because this host serves website/node_modules from a symlink vite refuses (Denied ID .../node_modules/...); CI runs them.

Manual verification

N/A — unit coverage sufficient: the notice is driven through the real claim and flush with the hidden-turn dispatch recorded; the model's wording of the reply is not tested here, as for the existing notice.

Related Issues

Follow-up to #23010.

Sibling sweep

Swept: git grep -n "logger.warning("crewmate migration" -- src/kiro_crew/mate_config_migration.py
Sibling: src/kiro_crew/mate_config_migration.py -- changed here
Sibling: src/kiro_crew/dashboard/server.py -- not affected -- it logs a failed pass as a whole; a pass that raised moved nobody and is retried at the next start

Pattern harvest

Not generalizable: the migration is the one boot pass that changes how a user's crewmate behaves; other boot passes change nothing a user sees.

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

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners October 24, 2026 00:45
@buluoray
buluoray requested a review from iamwhatever October 24, 2026 00:45
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 24, 2026
@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of d951911150c2923d7f85aff33260dcb3b26be98e — 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 does not.

First-Principles-Verdict: PASS

Both items come straight from #23010 review findings and reuse its one-time notice path. No existing code tells a user why their crewmate was left behind: the migration report's failure fields are read only inside mate_config_migration.py (1 file).

What this change ships

Inventory (6 items) — 6 justified

Intent: a FIX. After the Crewmate 2.0 upgrade, each crewmate's user learns what happened to it: where to change a moved crewmate's worker kit, or why it was left behind.

  1. The moved-crewmate upgrade notice now also says where to change the worker's kit (Advanced, Worker's extra kit). — justified
  2. A crewmate the migration left behind now tells its user once, in its own thread, why it stayed. — justified
  3. Failures other than the dry run get a plain-language reason in that notice instead of the raw log text. — justified
  4. A left-behind crewmate that moves at a later start says only that it moved, never that it was left behind. — justified
  5. A left-behind notice claimed while the thread is busy is delivered at the thread's next turn end. — justified
  6. Two new per-member state files (worker_kept_owed.json, worker_kept_claimed.json) are persisted. — justified

[FIRST-PRINCIPLES-REVIEWED] d951911

Description read

[DESCRIPTION-READ] e7f40dd46351704dc345a27cc77b3a15c1cfceeae9a1a66ad98475487dea26dd

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 commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision d951911150c2923d7f85aff33260dcb3b26be98e touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of d951911150c2923d7f85aff33260dcb3b26be98e — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the left-behind notice reuses the existing one-time claim-and-flush path, uses its own owed/claimed files, and adds nothing a revert can't undo.

Notes

  • _tell_kept turns every copy_failed entry into a "left as it was" notice. That includes the conductor-bound crewmate (source == MATE_CONDUCTOR_AGENT, put in unchanged and owing no notice), even though it already runs on the conductor. Its user would be told "you still work as before" about a setup that never changed. Skip names in unchanged when building kept.

[DESIGN-REVIEWED] d951911

Description read

[DESCRIPTION-READ] 363e8b0867d1ba62e6267982d6b5765a6b66cf93395deae2425b01c630536c10

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 Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] d951911

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable d951911150c2923d7f85aff33260dcb3b26be98e false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings (all downgraded on adjudication)

GPT 6.1 flagged blocking issues on d951911150c2923d7f85aff33260dcb3b26be98e; Opus 5.5 adjudication downgraded every one of them. Downgraded: the remedy each one needs is disproportionate to the harm it prevents. Adjudication downgraded all 1 blocking finding(s): the remedy each one requires is disproportionate to the harm it prevents.

This comment is updated in place on each push.

Review details

BLOCKING -- src/kiro_crew/dashboard/mate_thread_wakes.py:326 -- Unreadable-agent notices require the unreadable agent to start

dispatch_hidden_turn(state, slot, _kept_notices(state).pop(key), human_seen=False)
Trigger: A KAS crewmate’s source spec contains invalid JSON at startup. Migration records skipped_no_source; the restored thread claims its kept notice, then dispatch_hidden_turn → _run_chat → KasHarness.session_extras reads the unchanged source spec and raises before receiving the prompt.
Outcome: The migration explanation is never delivered. The pending notice has been popped, and worker_kept_claimed.json permanently prevents another delivery attempt.
Anchor: defect
Fix: Post unreadable-source explanations as gateway-authored messages in the existing mate thread, without requiring the source agent to run.
[BLOCK-MERGE-DOWNGRADED] d951911
[GPT-REVIEWED] d951911

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

F1 is downgraded: blocking on it would cost more than the harm it prevents.

F1 — LOW. The failure needs three things, all confirmed:

  • The crewmate's source spec can't be read, so it lands in skipped_no_source (src/kiro_crew/mate_config_migration.py:760-762) and is given the "could not be read" reason (src/kiro_crew/mate_config_migration.py:843).
  • The one-time claim marker is written before delivery (src/kiro_crew/mate_upgrade_notice.py:93), and the notice is popped (src/kiro_crew/dashboard/mate_thread_wakes.py:326).
  • The hidden turn runs through _run_chat (src/kiro_crew/dashboard/mate_welcome.py:343), where the agent's session setup fails.

What's lost is only an explanatory notice. The crewmate's own agent can't start, so every message the user sends it fails loudly. Once the spec is fixed, the next start moves the crewmate, clears the stale record and sends the "moved" notice instead (src/kiro_crew/mate_config_migration.py:810-812). The real fix is a new way to post into the mate thread without running the agent, built for this one rare case, and that costs more than this harm.

[ADJUDICATION] d951911150c2923d7f85aff33260dcb3b26be98e total=1 uphold=0 downgrade=1
DOWNGRADE F1 src/kiro_crew/dashboard/mate_thread_wakes.py:326 reason=disproportionate-remedy
[GPT-ADJUDICATED] d951911150c2923d7f85aff33260dcb3b26be98e

False positive or not applicable? A repository writer can comment:
/ai-review override gpt d951911150c2923d7f85aff33260dcb3b26be98e false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Oct 24, 2026
@buluoray
buluoray force-pushed the fix/crewmate-upgrade-notice-skips branch from c75656c to ca6c45c Compare October 24, 2026 01:16
@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 Oct 24, 2026
…nged

The one-time upgrade notice sent the user to Edit mate > Built From to
see what the worker can do. That pane only shows the kit; it is changed
in the same editor under Advanced, Worker's extra kit. The notice now
names both.
The startup migration left a crewmate where it was (its worker would
differ, its agent could not be read, its file or its repoint failed)
with only a log line, so its user never learned it had not moved. The
pass now owes that crewmate one notice naming why, delivered once in
its own thread through the same O_EXCL claim as the moved notice.
@buluoray
buluoray force-pushed the fix/crewmate-upgrade-notice-skips branch from ca6c45c to d951911 Compare October 24, 2026 01:26
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 24, 2026
@buluoray
buluoray merged commit d6bdae3 into main Oct 24, 2026
107 checks passed
@buluoray
buluoray deleted the fix/crewmate-upgrade-notice-skips branch October 24, 2026 05:21
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 24, 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