Repository navigation
fix(skill-view): backport recording a view's source agent before its sidecar is deleted to release/0.8.0 - #16074
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Parent #16073 is still OPEN — verify it merges first, since the release branch must not land ahead of the main-branch original. [DESIGN-REVIEWED] 16f184a |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS The description's own constraint — "#16073 is not merged yet, so this PR must not merge ahead of it" — is the one thing to verify before merging. What this change shipsInventory (8 items) — 8 justifiedIntent: FIX — a chat stored under a generated
Counts run: ownership-sidecar deletion sites ( [FIRST-PRINCIPLES-REVIEWED] 16f184a |
73c5881 to
dfb6151
Compare
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 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: |
|
Impact, traced against the core the internal 0.8.0.1/0.8.0.2 builds shipped (0.8.0-rc.1, which predates #15202 and 74cefff): this fix is defensive. At that core, no real code path persists a
So users of that build saw failed session starts or failed switches, not stored view names. The pod repro in the description wrote its session record by hand. This PR still closes a real hole. Any stored view name, whether from a hand edit, an older record, or a future path, stays resolvable after the boot drain retires its sidecar. The refusal for a name nothing records now gives the remedy that works. It is not a P0, so please merge it on the normal schedule. |
Opus 5 Review — ✅ no blocking findingsReviewed Review detailsNo findings that block. FINDING — src/kiro_crew/acp/skill_projection.py:434 — once the ledger sits at FINDING — src/kiro_crew/acp/skill_projection.py:449 — [OPUS-REVIEWED] 16f184a Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
dfb6151 to
52d969e
Compare
52d969e to
bfeced8
Compare
bfeced8 to
6a94910
Compare
|
Review findings on
Each new rule has a test, and reverting it fails that test. All added lines are covered. |
…eleted A conversation stored under a kirocrew-skill-view-<digest> name maps back to its agent through the view's ownership sidecar, then the view ledger. The ledger is written only at publication, for the aliases that run publishes, so a view a pre-ledger build published is resolvable through its sidecar alone. The boot drain deletes exactly that record: the orphan-sidecar sweep retires a sidecar whose alias an outside cleanup or an operator already removed, and the prune retires the alias and sidecar together. The stored chat is then refused as "unavailable" although its agent is installed. Every sidecar deletion now records the view's alias -> agent pair in the view ledger first, under the publication lock the deletion already holds, through the one bounded, atomic ledger writer. The sweep records its whole batch in one write; the prune records a window of upcoming candidates the first time a pair needs it, so a drain of thousands of pairs costs one write per window. A sidecar the ledger cannot take is kept; the prune still removes its alias, since the sidecar then answers for the view on its own. Both sweep halves stay inside the time budget. Each write makes the whole batch the newest entries; past the ledger's bound, entries a sidecar still answers for go first, then the oldest retired names (counted in a warning), so a full ledger never stops the sweep. A write the filesystem refuses is not retried per candidate. The tests run the real drain over a real published view with no ledger, in each of the three deletion paths, and resume the stored name through resolve_session_agent_bindings. The RetiredSkillView text the ACP spawn path raises for a view nothing records also names "or start a new chat" as a remedy. (cherry picked from commit 221aa85)
… view A resumed chat whose recorded skill-view name nothing maps back was refused as "Crew Member 'kirocrew-skill-view-...' is unavailable; restore it or choose a member". A generated view is not a member anyone can restore, and the view name is a one-way digest, so the agent cannot be recovered. Say what works instead: pick the agent for this chat again, or start a new chat. (cherry picked from commit 9816ff6)
6a94910 to
16f184a
Compare
|
The GPT 5.6 finding on Before this fix, a ledger entry counted as redundant whenever a file existed at its sidecar path. It now counts only when
|
Problem / Motivation
Goal: On the 0.8 line, a chat stored under a generated
kirocrew-skill-view-<digest>agent name keeps resuming after the boot drain retires that view's alias and ownership sidecar.A conversation recorded while the native skill projection was on can carry a view name as its agent.
source_agent_namemaps it back through the view's ownership sidecar, then the view ledger (view-sources.json). The ledger is written only at publication, and only for the aliases that run publishes, so a view published before the ledger existed has the sidecar as its only record. The boot drain deletes exactly that record:_sweep_orphan_sidecars) retires a sidecar whose alias a cleanup outside the core, or an operator, already removed;_reclaim_prune_candidate) retires the alias and its sidecar together, both for an intact pair and for a re-serialized one.None of the three paths writes the ledger first. After the next boot the stored chat is refused with
Crew Member 'kirocrew-skill-view-…' is unavailable; restore it or choose a member, even though the agent it was built from is installed. A pod smoke test reproduced this on a real tree: alias removed, thendrain_stale_aliases(), then the resume refused.Why it matters
Every conversation recorded under a view name before the ledger existed stops resuming at the first boot that drains it. The refusal points at a "Crew Member" the user never created and cannot restore, so there is no way forward from the message.
Not a goal
_VIEW_SOURCES_MAX), its format, or what the drain deletes.What changed (motivation → approach → change)
Symptom: a stored view name stops resolving once the drain runs. Root cause: every sidecar deletion drops the last record of the view's source agent without copying it into the ledger. Change: record the mapping before deleting.
_record_view_ledger_entries(metadata_dir, views)is now the single ledger writer. It takes alias → agent, because a retired backlog holds many views of one agent. It reuses the existing rules: the same admission, an atomic owner-only write, and no rewrite when nothing changed. Each write makes its whole batch the newest entries, including pairs the ledger already holds, so the same write cannot evict a pair whose sidecar is about to go. Past the bound (_VIEW_SOURCES_MAX), entries a sidecar still answers for go first, oldest first. After that the oldest retired names go; they stop resolving, and the loss is counted in a warning. A full ledger therefore never stops the sweep from retiring sidecars. A batch larger than the bound cannot all be held, so none of its sidecars go._record_view_ledger(agent → alias, for a publication) delegates to it._ViewLedgerWriteskeeps the ledger for the duration of one locked prune or sweep. Every path that deletes a sidecar calls it before unlinking:retain()runs before_unlink_alias_if_unchanged. The first pair that needs recording also records the next 64 candidates' sidecars (this home only) in the same write. A drain over thousands of pairs therefore costs one write per window instead of one per pair, and a walk that reclaims nothing does no extra reads. If the ledger refuses, the alias still goes. The sidecar stays and answers for the view on its own, so a full disk or a read-only metadata directory does not stop alias reclamation. After one refused write, the rest of that prune or sweep keeps sidecars without retrying the write for each candidate._reclaim_prune_candidatenow takes the ledger as a required argument.chat_runner.unavailable_agent_message()reads "This chat was recorded under a generated skill view from an earlier version (…), and the agent it was built from is not recorded. Pick the agent for this chat again, or start a new chat." TheRetiredSkillViewtext that the ACP spawn path raises gets the same "or start a new chat".Backwards compatibility
Compatible. The ledger file keeps its format and its bound, and older builds read it unchanged. A deletion that would previously have happened is deferred only when the ledger write fails.
_record_view_ledgerkeeps its signature. The only other change is the message text for a non-view name, which is identical.Tests
test_resume_retired_agent_names.py::test_a_view_the_real_boot_drain_retired_still_resumes[alias-removed|pair-kept|alias-rewritten]: publishes a real view and deletes the ledger, as a pre-ledger tree would look. It then runs the realdrain_stale_aliases(), asserts that the alias and the sidecar are really gone, and resumes the stored name throughresolve_session_agent_bindings. Each parametrization drives one of the three deletion paths. All three FAIL on main.test_skill_view_mode_recovery.py::test_the_boot_drain_records_a_backlog_in_one_ledger_write: a backlog of 7 views of one agent, half with their alias already removed. The drain retires them all with exactly 2 ledger writes (one for the prune, one for the sweep), and every name still resolves.test_skill_view_mode_recovery.py::test_a_sidecar_the_ledger_cannot_take_is_kept_and_its_alias_goes[True|False]andtest_a_reserialized_pair_the_ledger_cannot_take_keeps_its_sidecar: when a ledger write raises, the sidecar is kept and the alias is removed, and the name still resolves through the sidecar.test_the_bound_drops_redundant_entries_then_the_oldest_retired_ones: redundant entries go first, then the oldest retired name (with a warning), new pairs are always held, and an over-bound file is trimmed.test_a_batch_rewrites_its_held_pairs_so_the_bound_cannot_evict_them: a held pair in a batch is not evicted by that batch's own write, and a batch larger than the bound is refused.test_a_refused_write_is_not_retried_for_every_candidate.test_the_orphan_sweep_unlinks_nothing_past_its_deadline: a deadline that runs out during the ledger write stops the unlinks; the batch stays recorded.test_resume_retired_agent_names.py::test_an_unrecoverable_view_tells_the_user_to_pick_again_or_start_new.test_skill_view_mode_recovery.py::test_the_look_ahead_records_only_this_homes_views: one look-ahead write covers its window, and another home's view takes no ledger slot.test_skill_view_mode_recovery.py::test_a_ledger_that_already_holds_the_views_is_not_rewritten: views the ledger already holds, and records with no admissible agent, cause no write.Regression proof, with each site disabled in turn:
Gate on release/0.8.0: flake8 and black are clean on the touched files, and
mypy src/kiro_crewreports 0 issues in 1863 files. The projection, recovery, resume, agent-selection and session-control suites pass (515 passed). The full backend lane ran on #16073.Manual verification
kirocrew podtree. I published 11 real views and deleted the ledger, so the tree looked like it predated the ledger. A distribution's boot cleanup then removed only the aliases (11 aliases, 11 sidecars left), and the realdrain_stale_aliases()ran after it. On the base: 0 sidecars and 0 ledger entries remained, and 0 of 11 stored names resolved throughresolve_session_agent_bindings. With this branch: 0 sidecars, 11 ledger entries, and 11 of 11 resolved to their source agent.template_idandselection_nameboth hold the view name. kiro-cli'ssessions/cli/<sid>.jsonstores onlysession_state.agent_name, which is the alias. Lease records hold alias names only. The digest covers the agent, the home, the source path and the full view, including MCP env values that changed on every launch at the time, so it cannot be recomputed from installed agents.Related Issues
Part of #16545
Follows #16024 and #16033, which map a stored view name back through
source_agent_name. The deleting sweep came from #15150 (via #15295).Pattern harvest
Rule candidate: review-prompt
Pattern: "deleting a record that a fallback resolver reads, without first writing the fallback": every path that unlinks a file which a lookup reads must write the lookup's durable fallback first, in the same locked section.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement