Skip to content

fix(crewmate): gate the boot migration on a version stamp - #23598

Closed
buluoray wants to merge 2 commits into
mainfrom
fix/crewmate-migration-stamp
Closed

buluoray wants to merge 2 commits into
mainfrom
fix/crewmate-migration-stamp

Conversation

@buluoray

@buluoray buluoray commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A Kiro Crew start after the crewmate migration has finished reads one small file instead of running the whole migration again.

The Crewmate 2.0 migration (#23010) runs at every dashboard start (start_dashboard → migrate_existing_crewmates). Each start loads the config, reads and parses every crewmate file (repair_partial_platform_servers), reads the migration ledger, and checks every binding. On an install whose crewmates all moved long ago, every start still pays for that.

Why it matters

The pass runs on every launch for the life of the install, and its cost grows with the number of crewmates and transcripts. It also re-reads files a finished install never needs again, so a damaged file in that set can log warnings at every start for no reason.

Not a goal

  • Any change to what the migration moves or how it decides.
  • Cleaning up or deleting the ledger, the stamp, or old agent files.
  • The other feat(crew): give each crewmate its own config, a conductor and a worker #23010 minor items (record-less conductor worker store, skipped-crewmate visibility, the upgrade notice's pane) and the other follow-ups (owner lock and ledger keys, approval race, skill lookup key, worker-kit localisation). Each has its own pull request.

What changed (motivation → approach → change)

Goal → approach → change: a version stamp per data home, written only when a pass left nothing to retry.

  • src/kiro_crew/mate_config_migration.py: migrate_crewmates_if_pending is the new startup entry (dashboard/server.py). It reads <data home>/crewmate-migration.json and runs the pass only while its version is not MIGRATION_VERSION (1). A missing or damaged stamp means pending.
  • migrate_existing_crewmates stamps the version (_mark_finished) only when the pass read the crewmates and the worker base (MigrationReport.read), left no crewmate unmoved (skipped_no_source, copy_failed, dry_run_failed, repoint_failed all empty), and owes no thread pass (_threads_owed: a ledger threads entry with a from and no done, or an unreadable ledger). Anything else stays unstamped, so the next start tries again, exactly as today.
  • A later step that a finished install still owes bumps MIGRATION_VERSION.
  • The stamp never hides a candidate or an owed thread pass. With it in place, migrate_crewmates_if_pending still runs the pass when any binding is one (_candidates over the config already loaded and the ledger) or the ledger owes a thread pass (_threads_owed, an entry with a from and no done). So a crewmate that lands on a template after the stamp is moved at the next start: the first crewmate created on the conductor (agent_materialization/first_crewmate.py:create_first_crewmate_once), an eager copy that failed or was refused (mate_config.adopt_own_file), or any path that creates a crewmate without the copy. A finished install with every crewmate on its own file reads the stamp, the config and the ledger, and skips the rest: the crewmate-file repair scan and the thread pass.

Per data home, not per Kiro home: the crewmates a pass moves are that instance's config.

The second commit is a help-text fix from the #23010 review (CrysisDeu, minor items). The agent.member_acp_backend help (src/kiro_crew/config/sections_agent.py) named claude, codex, opencode and goose as dispatch-capable, but a crewmate's worker runs only where its per-session kit can be applied (ACP_BACKENDS_MATE_WORKER_KIT, today KAS), and session_create refuses the hand-off elsewhere (worker_kit_harness_unsupported). The help now says so; config-baseline.json is regenerated (scripts/generate_config_baseline.py).

docs/system-specs/modules/crew-mode.md gets one new paragraph for the stamp, inserted between the migration and thread-pass paragraphs.

Backwards compatibility

Compatible: an install with no stamp runs the pass as before, and a pass that leaves anything to retry is not stamped.

What it takes away: after a finished pass, startup no longer runs the migration's steps on every boot. Readers of those steps, from origin/main:

Reader: src/kiro_crew/agent_materialization/first_crewmate.py:create_first_crewmate_once -- release -- a first crewmate created on the conductor after the stamp is a candidate, so the next start runs the pass and gives it its file; test_a_crewmate_left_on_a_template_after_the_stamp_is_moved_at_the_next_start[kirocrew-mate-conductor]
Reader: src/kiro_crew/dashboard/agent_admin/crew_records.py:_eager_copy_mate_config -- crew page -- a create whose copy failed or was refused leaves a candidate, moved at the next start; test_a_crewmate_left_on_a_template_after_the_stamp_is_moved_at_the_next_start[builder]

Reader: src/kiro_crew/dashboard/server.py:start_dashboard -- release -- calls migrate_crewmates_if_pending, which runs the full pass on every boot until a pass stamps; test/test_dashboard_server_composition_contract_reach.py, test_boot_runs_the_pass_only_while_it_is_pending
Reader: src/kiro_crew/mate_config_migration.py:repair_partial_platform_servers -- release -- skipped once stamped; a platform server with no transport is still dropped where a crewmate file is written (mate_config.write_mate_spec) and where it is projected (acp/harness/kas.py:resolve_projected_spec), so a file that still holds one launches nothing; test/test_mate_platform_server_override.py::test_a_template_carrying_the_bare_override_is_copied_without_it, test_reading_a_crewmate_file_never_hands_on_the_bare_override
Reader: src/kiro_crew/mate_config_migration.py:repoint_moved_threads -- chat -- a pass that still owes a thread pass is never stamped, and an owed pass runs even under an earlier stamp; test_a_pass_that_still_owes_a_thread_pass_stays_pending, test_a_stamped_install_still_finishes_an_owed_thread_pass
Reader: src/kiro_crew/mate_config_migration.py:migrate_existing_crewmates -- crew page -- a crewmate created after the stamp gets its own file at creation (mate_config.adopt_own_file), so it owes no pass; one pointed back by hand stays put, as before; test_a_crewmate_pointed_back_by_hand_stays_put, and the function keeps its signature

Tests

Proof: PROVEN test/test_dashboard_server_composition_contract_reach.py::test_the_dashboard_boot_keeps_its_chain_hooks_and_order (head 1fcdb31)

  • test/test_mate_config_migration.py:
    • test_a_finished_pass_stamps_the_version_so_boot_stops_scanning: a pass that moves its one crewmate stamps; a bumped MIGRATION_VERSION is pending again.
    • test_a_pass_that_left_a_crewmate_behind_stays_pending: a crewmate whose source agent is gone keeps it pending.
    • test_a_pass_that_still_owes_a_thread_pass_stays_pending: an owed threads entry keeps it pending.
    • test_a_pass_that_could_not_read_the_crewmates_stays_pending: an unreadable config keeps it pending.
    • test_a_pass_that_met_an_unreadable_ledger_stays_pending: a damaged migrated.json (fix(crewmate): lock crewmate owners; key the migration ledger by id #23542's LedgerUnreadable) keeps it pending.
    • test_a_crewmate_left_on_a_template_after_the_stamp_is_moved_at_the_next_start (on a shared template, and the first crewmate on the conductor): stamped, then a crewmate appears on a template; the next start moves it.
    • test_a_stamped_install_still_finishes_an_owed_thread_pass: an earlier stamp and a ledger owing a thread pass; the next start repoints that thread.
    • test_boot_runs_the_pass_only_while_it_is_pending: the wrapper runs once, then returns None.
  • test/test_dashboard_server_composition_contract_reach.py: the boot chain names migrate_crewmates_if_pending.
  • test/test_config_baseline.py: the committed baseline matches the new help text.
  • Ran locally: test_mate_config_migration.py, the composition test and both ratchets (165 passed), test_mate_*.py, lint, mypy, semgrep, and scripts/local-gate.py --base origin/main: backend batch 1 passed (30542); batch 2 failed 8 tests in test_pi_gate_extension_mcp.py and test_remote_session_launch.py (a node subprocess timeout and a guest-python error), which fail the same way on clean origin/main 41c6bb8c50 on this host and touch nothing in this diff.

Manual verification

N/A — unit coverage sufficient: the stamp's write and read are driven through real files under a temporary data home.

Related Issues

Follow-up to #23010.

Sibling sweep

Swept: git grep -n "migrate_existing_crewmates|prune_synced_crewmates|_migrated.json" -- src/
Sibling: src/kiro_crew/crewmate_prune_migration.py -- not affected -- it already writes its own marker and returns at once once it exists

Pattern harvest

Not generalizable: the crewmate prune already gates on a marker; this brings the crewmate migration to the same shape.

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:18
@buluoray
buluoray requested a review from mbriones98 October 24, 2026 00:18
@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 1fcdb310498f8fbaccd30b935e1503868ddff908 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 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) — 🔴 BLOCK

Premise-level review of 1fcdb310498f8fbaccd30b935e1503868ddff908 — 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: BLOCK

The stamp, a new file on disk and a version contract, only gates the crewmate-file repair scan. The PR's own description says that scan is redundant, so deleting it removes the boot cost with nothing added.

What this change ships

Inventory (7 items) — 3 justified

Intent: stop a finished install from paying for the crewmate migration at every start. This is a FIX.

  1. A boot after a finished pass skips the crewmate-file repair scan — duplicate of _migrate's own no-candidate early return
  2. A new crewmate-migration.json is written in every data home — oversized
  3. A stamped boot still runs the pass for a new candidate or an owed thread pass — justified
  4. A MIGRATION_VERSION bump rule for future steps — oversized, written "so we can later"
  5. The member_acp_backend help now says a crewmate's worker runs on KAS only — rides along
  6. config-baseline.json regenerated for that help text — justified
  7. crew-mode spec paragraph — justified

Blockers

Version stamp re-gates checks the pass already makes — duplicate of mate_config_migration._migrate
Trigger: under a stamp, migrate_crewmates_if_pending still runs _candidates(...) and _threads_owed(). _migrate already returns early when there are no candidates, and repoint_moved_threads returns early when no threads entry is pending. So the stamp skips only repair_partial_platform_servers() (1 call site, grepped). Two existing sites drop a platform server with no transport: mate_config.py:198 when a crewmate file is written, kas.py:215 when it is projected.
Outcome: every install carries a permanent persisted file and a bump-the-version contract that buys one redundant scan. The stamped boot also still reads the ledger twice, not "one small file".
Subtraction: delete the repair_partial_platform_servers() call from _migrate. Then delete migration_pending, _mark_finished, _stamp_path, MIGRATION_VERSION and MigrationReport.read, and keep migrate_existing_crewmates as the boot entry.
Clears when: the stamp is removed and the repair scan no longer runs at boot, or the author names a cost the stamp removes that this deletion leaves in place.

[FIRST-PRINCIPLES-REVIEWED] 1fcdb31

Description read

[DESCRIPTION-READ] 4527329d50f459253e4b5d93e8394cd922b8f5c328ab754d791ded4957571c54

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

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the stamp only skips the crewmate-file repair scan, and boot still checks for candidates and owed thread passes, so a crewmate left on a template after the stamp is still moved.

Notes

  • The second commit, the member_acp_backend help text, has nothing to do with the stamp goal. It is documented, but it belongs in its own pull request.
  • Once stamped, every boot still loads the config and the ledger through _candidates and _threads_owed. So "reads one small file" in the Goal line overstates the saving. The real gain is skipping repair_partial_platform_servers and the per-crewmate work.

[DESIGN-REVIEWED] 1fcdb31

Description read

[DESCRIPTION-READ] 248319f5465f1318642713e21ba62f4af0fa3d71d786e1d2b32a2fde1cd9db44

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 1fcdb310498f8fbaccd30b935e1503868ddff908 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 1fcdb31

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 1fcdb310498f8fbaccd30b935e1503868ddff908 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

GPT 6.1 completed its review of 1fcdb310498f8fbaccd30b935e1503868ddff908 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 1fcdb31

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

@buluoray
buluoray force-pushed the fix/crewmate-migration-stamp branch 2 times, most recently from 7343297 to 23917e0 Compare October 24, 2026 01:10
Every boot ran the whole crewmate migration: read every binding, the
ledger and the worker base, and scanned DM transcripts for owed thread
passes. A pass that read everything, moved every candidate and owes no
thread pass now stamps <data home>/crewmate-migration.json with
MIGRATION_VERSION, and boot (migrate_crewmates_if_pending) skips the
pass while the stamp matches. Anything left to retry keeps it unstamped.
The member_acp_backend help named claude, codex, opencode and goose as
dispatch-capable backends, but a crewmate's worker runs only where its
per-session kit can be applied (ACP_BACKENDS_MATE_WORKER_KIT, today KAS);
elsewhere session_create refuses the hand-off. The help now says so.
config-baseline.json regenerated.
@buluoray
buluoray force-pushed the fix/crewmate-migration-stamp branch from 23917e0 to 1fcdb31 Compare October 24, 2026 01:31
@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 Oct 24, 2026
@buluoray

Copy link
Copy Markdown
Contributor Author

Closing (maintainer decision, buluoray). As the First Principles review found, the stamp only skips repair_partial_platform_servers() at boot, since _migrate already returns early with no candidates and the thread pass returns early with nothing owed. That saving is too small to justify a persisted file and a version contract, and removing the stamp would no longer match this PR's goal. Branch kept; a separate small PR can drop the boot repair scan if startup cost ever shows up.

@buluoray buluoray closed this Oct 25, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 25, 2026
@bolichen97
bolichen97 deleted the fix/crewmate-migration-stamp branch November 6, 2026 07:21
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.

1 participant