Repository navigation
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — 🔴 BLOCKPremise-level review of 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 shipsInventory (7 items) — 3 justifiedIntent: stop a finished install from paying for the crewmate migration at every start. This is a FIX.
BlockersVersion stamp re-gates checks the pass already makes — duplicate of [FIRST-PRINCIPLES-REVIEWED] 1fcdb31 Description read[DESCRIPTION-READ] 4527329d50f459253e4b5d93e8394cd922b8f5c328ab754d791ded4957571c54 That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of 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
[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 |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
7343297 to
23917e0
Compare
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.
23917e0 to
1fcdb31
Compare
|
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. |
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
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_pendingis the new startup entry (dashboard/server.py). It reads<data home>/crewmate-migration.jsonand runs the pass only while itsversionis notMIGRATION_VERSION(1). A missing or damaged stamp means pending.migrate_existing_crewmatesstamps 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_failedall empty), and owes no thread pass (_threads_owed: a ledgerthreadsentry with afromand nodone, or an unreadable ledger). Anything else stays unstamped, so the next start tries again, exactly as today.MIGRATION_VERSION.migrate_crewmates_if_pendingstill runs the pass when any binding is one (_candidatesover the config already loaded and the ledger) or the ledger owes a thread pass (_threads_owed, an entry with afromand nodone). 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_backendhelp (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), andsession_createrefuses the hand-off elsewhere (worker_kit_harness_unsupported). The help now says so;config-baseline.jsonis regenerated (scripts/generate_config_baseline.py).docs/system-specs/modules/crew-mode.mdgets 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_pendingReader: 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_overrideReader: 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_passReader: 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 signatureTests
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 bumpedMIGRATION_VERSIONis 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 owedthreadsentry 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 damagedmigrated.json(fix(crewmate): lock crewmate owners; key the migration ledger by id #23542'sLedgerUnreadable) 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 returnsNone.test/test_dashboard_server_composition_contract_reach.py: the boot chain namesmigrate_crewmates_if_pending.test/test_config_baseline.py: the committed baseline matches the new help text.test_mate_config_migration.py, the composition test and both ratchets (165 passed),test_mate_*.py, lint, mypy, semgrep, andscripts/local-gate.py --base origin/main: backend batch 1 passed (30542); batch 2 failed 8 tests intest_pi_gate_extension_mcp.pyandtest_remote_session_launch.py(anodesubprocess timeout and a guest-python error), which fail the same way on cleanorigin/main41c6bb8c50on 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
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.