Skip to content

fix(agents): crew delete removes the crew's private template copy - #11222

Merged
chenmingwei23 merged 1 commit into
mainfrom
fix/crew-delete-prunes-private-fork-8540
Sep 16, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
fix/crew-delete-prunes-private-fork-8540

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

What

DELETE /api/agents/{name} (crew delete) now removes the crew's private template copy and prunes the copy's fork lineage record from the agent_state sidecar — when, and only when, both sides corroborate that the copy was this crew's alone.

Why

The fork-on-first-edit flow gives a crew a private copy of its template, named after the crew, with forked_from / private_to recorded in the sidecar. Deleting the crew never consulted that lineage, so the copy file and its record survived and a template named after a dead crew kept surfacing in the Agent Templates tab (Design Review finding on #8307, tracked as #8540).

How

  • New _prune_private_copy_of_deleted_crew(crew, bound_template) in dashboard/handlers/agents.py, called from api_kirocrew_agent_delete right after the avatar cleanup, inside the same config lock (so a same-name recreation cannot fork a fresh copy that this cleanup then removes).
  • Corroboration, both required: the sidecar's private_to == crew, AND the crew's persisted kiro_agent binding — captured inside the config mutate critical section at delete time — names that copy. Lineage alone or binding alone leaves the file untouched.
  • Reuses the reset endpoint's helpers: _load_template_specs resolves the copy's ACTUAL file (a stem/name divergence is not missed; an ambiguous name is refused), _spec_path_is_safe path-confines it, and _unlink_copy_unless_referenced does the foreign-binding check and unlink as one critical section under the config advisory lock and agents_spec_lock. agent_state.prune runs only after the file is actually gone.
  • Lineage is keyed by the copy's declared name while a binding may resolve the same file by its stem, so the record is looked up under every name that resolves the file (bound name, declared name, stem).
  • Best-effort: an unreadable sidecar, an ambiguous name, a foreign binding still resolving the copy, or a file that will not unlink all keep the copy AND its lineage (private content never lists as shared), and the crew's removal still succeeds. A copy that does not resolve to a readable spec (malformed JSON, or already gone) keeps its lineage: an unresolved name is never proof the file is absent — with a divergent stem its real filename cannot even be named — and pruning on a guess would surface private content as shared once the file is repaired. A stale record for a file that truly is gone is inert (nothing lists a template without a spec). A removed file clears the list_agents cache and pushes an agents refresh.
  • _unlink_copy_unless_referenced (shared with reset and publish cleanup) now reads crew bindings from BOTH config layers: the locked config.json document and the user-owned config.local.json overlay, which deep-merges over it at load and can hold a crew's effective kiro_agent on its own. The overlay is read inside a nested hold of its own sidecar lock (config set --local writes under that lock, not the base's) and the unlink runs while both are held, so an overlay binding cannot land between the check and the unlink. An unreadable overlay fails closed (file kept), like an unreadable base.

Tests

test/test_agent_delete_prunes_private_copy.py (11 tests, all call the handler directly against an isolated KIROCREW_HOME):

  • corroborated copy → file and lineage gone, shared origin untouched (fails on main: the file survives);
  • private_to names another crew → left alone;
  • crew was bound elsewhere → left alone;
  • another crew still bound to the copy (in config.json, or only in the config.local.json overlay) → left alone;
  • overlay unreadable → left alone (fail closed);
  • unlink refused (PermissionError) → crew still deleted, file and lineage kept, refusal logged (asserted via caplog);
  • crew bound by file stem while lineage is under the declared name → found and removed;
  • copy present but malformed (same stem, or a divergent stem no name here can locate) → file and lineage kept; copy file already gone → lineage kept (inert).
  • the happy path also pins that the overlay's sidecar lockfile was taken and the overlay itself was not written.

Run: python -m pytest -n0 test/test_agent_delete_prunes_private_copy.py -q. Sibling suites test_agent_reset_endpoint.py, test_agent_fork_endpoint.py, test_agent_publish_endpoint.py, test_config_overlay.py, test_crew_memory_store_binding.py, test_agent_avatar.py, test_config_api.py, test_crew_reasoning_effort.py pass (365 tests). isort, flake8, mypy, black (baselined gate), comment-history and subprocess-encoding gates pass on the changed files.

Other

Backend-only change with no UI surface; labeled no-screenshots. No new endpoints, no generalized cleanup of orphaned copies — only the deleted crew's own corroborated copy, as scoped in #8540.

Pattern harvest

Rule candidate: Design Review
Pattern: when a feature introduces a per-entity derived artifact (private copy + lineage), the entity's DELETE handler must be listed among the writers that consult that artifact's record.

Closes #8540

@CrysisDeu
CrysisDeu requested review from a team and cixuuz September 16, 2026 06:27
@CrysisDeu CrysisDeu added the no-screenshots PR has no visual delta; screenshot gate exempt label Sep 16, 2026
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 16, 2026
@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify #8540 accepted leaving already-orphaned copies in place — this stops new leaks but ships no sweep, so existing dead-crew templates keep surfacing.

Suggestions

  • If pre-existing orphans turn out to matter, a one-off corroborated sweep (same dual-source check, iterated over the sidecar) is a natural follow-up PR reusing _prune_private_copy_of_deleted_crew's logic — not needed here.

[DESIGN-REVIEWED] e6db862

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] e6db862

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

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of e6db862afdca152f29df38c6d5014c1fbdce112c — 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/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

Fix stops at the dashboard handler: CLI agent delete and agents-sync prune (2 counted siblings) still orphan the same dead-crew template copy.

Not justified as shipped

  • Item 1 — symptom-level (point patch): pruning runs only in api_kirocrew_agent_delete; grep del agents\[ finds 2 other crew-removal sites — cli_commands.py:1284 and _do_agents_sync (agents.py:4213) — that leave the copy and lineage behind; the description's "as scoped in Crew delete leaves the crew's private template copy and lineage behind #8540" never names them.
    Clears when: the two sibling sites call _prune_private_copy_of_deleted_crew, or Crew delete leaves the crew's private template copy and lineage behind #8540 is shown to deliberately exclude the CLI and sync paths.
  • Item 4 — rides along: fixing shared _unlink_copy_unless_referenced also changes fork/publish/reset cleanup behavior; declared, premise verified (loader.py:3995 deep-merges the overlay), and the smaller form than a delete-only variant.

What this change ships

Inventory (5 items) — 3 justified

Intent: deleting a crew should also remove the private template copy that existed only for it — a FIX (issue #8540; new test fails on base).

  1. Dashboard crew delete now removes the crew's corroborated private template copy — symptom-level: 2 sibling crew-removal paths unfixed
  2. The copy's fork-lineage record is pruned with the file — justified
  3. Agent Templates tab refreshes immediately after the delete — justified
  4. Fork/publish/reset cleanup now also honors bindings held only in config.local.json — rides along: declared, verified, smaller than a fork of the helper
  5. Any doubt (foreign binding, malformed file, failed unlink) keeps file and lineage; the delete still succeeds — justified

[FIRST-PRINCIPLES-REVIEWED] e6db862

@github-actions

github-actions Bot commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] e6db862

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

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

@CrysisDeu
CrysisDeu force-pushed the fix/crew-delete-prunes-private-fork-8540 branch from 247d6b1 to 04c9eda Compare September 16, 2026 06:48
@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 16, 2026
@CrysisDeu
CrysisDeu force-pushed the fix/crew-delete-prunes-private-fork-8540 branch from 04c9eda to 95b7e74 Compare September 16, 2026 07:03
@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 16, 2026
@CrysisDeu
CrysisDeu force-pushed the fix/crew-delete-prunes-private-fork-8540 branch from 95b7e74 to 9037d0f Compare September 16, 2026 07:20
@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 16, 2026
Deleting a crew left the private copy the fork-on-edit flow created for
it, plus the copy's fork lineage in the agent_state sidecar, so a
template named after a dead crew kept listing in the Agent Templates
tab. The delete handler now removes the copy when both sides agree it
was the crew's alone: the sidecar names the crew as private_to AND the
crew's persisted binding pointed at it. The check, unlink and lineage
prune reuse the reset endpoint's helpers and run inside the same config
lock as the rest of the delete. Removal is best-effort: an ambiguous
name, a foreign binding, or a file that will not unlink leaves the copy
and its lineage in place, and the crew is still deleted.

Closes #8540
@CrysisDeu
CrysisDeu force-pushed the fix/crew-delete-prunes-private-fork-8540 branch from 9037d0f to e6db862 Compare September 16, 2026 07:36
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 16, 2026
@CrysisDeu

Copy link
Copy Markdown
Contributor Author
  • Item 1 — pruning runs only in api_kirocrew_agent_delete; CLI agent delete and _do_agents_sync still orphan the copy (span=c3e38ba93e05) — Scoped as filed, with the two siblings checked rather than assumed. Crew delete leaves the crew's private template copy and lineage behind #8540 names api_kirocrew_agent_delete as the handler that "does not consult fork info"; it is the Design Review finding on feat(agents): template selector becomes the definition panel's header with private fork-on-edit #8307, whose fork-on-edit flow is a dashboard-panel feature. The two del agents[...] sites differ in kind: _do_agents_sync (agents.py prune_candidates) removes only source in ("package", "aim") crews whose kiro_agent spec is no longer on disk — a copy file that has already vanished cannot be pruned, and the fork-on-edit panel never produces a package-sourced private copy, so there is no orphan there to sweep; the CLI agent delete is already the narrower delete (it also skips the avatar cleanup this handler runs) and cli_commands.py does not import dashboard.handlers.agents, so lifting _prune_private_copy_of_deleted_crew into a shared module for one CLI caller is a separate refactor, not a rider on this fix. Kept out deliberately; the issue text is the scope line.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author
  • Item 4 — fixing shared _unlink_copy_unless_referenced also changes fork/publish/reset cleanup (span=247b979dea46) — Accepted as the intended shape. The overlay gap was a GPT security-class finding on the new call site, and the same gap existed at the three pre-existing call sites because they share the helper; fixing the helper once (nested hold of config.local.json's own sidecar lock, unreadable overlay fails closed) is the smaller and safer form versus a delete-only variant that would leave reset/publish with the known TOCTOU. The behavior change for those callers is strictly "keep the file when an overlay binding references it" — the fail-safe direction — and the sibling suites (test_agent_reset_endpoint.py, test_agent_fork_endpoint.py, test_agent_publish_endpoint.py, test_config_overlay.py, 103 tests) pass unchanged. Declared in the PR body's How section.

@CrysisDeu

Copy link
Copy Markdown
Contributor Author
  • One-off corroborated sweep of pre-existing orphans as a follow-up PR (span=051be26de6e2) — Agreed it is not needed here, and deliberately not shipped: Crew delete leaves the crew's private template copy and lineage behind #8540 asks for the delete path to stop leaking ("on crew delete, remove the crew's corroborated private copy"), and the worker brief for it excludes generalized cleanup. A sweep over the sidecar would have to decide what "corroborated" means for a copy whose crew no longer exists (the binding half of the check is gone), which is a design question for its own issue rather than a rider. _prune_private_copy_of_deleted_crew is written so such a sweep could reuse the resolve/reference/unlink/prune sequence per name.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 16, 2026
@chenmingwei23
chenmingwei23 enabled auto-merge (squash) September 16, 2026 09:04

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

Tier 1 auto-approve: fix (2 files): crew delete left an orphaned private template copy that surfaced under a dead crew name; fix prunes it, corroborated by private_to and the persisted binding, best-effort. Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, SAST annotations clean, security checklist all-NO, AI reviewers green.

@chenmingwei23
chenmingwei23 merged commit b521294 into main Sep 16, 2026
84 of 90 checks passed
@chenmingwei23
chenmingwei23 deleted the fix/crew-delete-prunes-private-fork-8540 branch September 16, 2026 09:04
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 16, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…rodotdev#11222)

Deleting a crew left the private copy the fork-on-edit flow created for
it, plus the copy's fork lineage in the agent_state sidecar, so a
template named after a dead crew kept listing in the Agent Templates
tab. The delete handler now removes the copy when both sides agree it
was the crew's alone: the sidecar names the crew as private_to AND the
crew's persisted binding pointed at it. The check, unlink and lineage
prune reuse the reset endpoint's helpers and run inside the same config
lock as the rest of the delete. Removal is best-effort: an ambiguous
name, a foreign binding, or a file that will not unlink leaves the copy
and its lineage in place, and the crew is still deleted.

Closes kirodotdev#8540
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no-screenshots PR has no visual delta; screenshot gate exempt

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Crew delete leaves the crew's private template copy and lineage behind

2 participants