Skip to content

fix(dashboard): remove a deleted crewmate's dashboard structure lock - #19825

Closed
leonlaiyc wants to merge 2 commits into
kirodotdev:mainfrom
leonlaiyc:fix/19365-crew-panel-lock-cleanup
Closed

leonlaiyc wants to merge 2 commits into
kirodotdev:mainfrom
leonlaiyc:fix/19365-crew-panel-lock-cleanup

Conversation

@leonlaiyc

@leonlaiyc leonlaiyc commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Deleting a crewmate removes its dashboard structure lock, so a later crewmate that derives the same slug does not start out locked to the deleted one's page.

Deferred finding from #18687. The person's structure lock is the file crew-panels/<slug>.dashboard-lock. It sits outside members/<slug>/ on purpose, so the agent's shell cannot clear it, and for the same reason none of the existing delete teardown steps reach it. DELETE /api/agents/{name} removes the config record, the memory store, the crew log, the avatar and the private template copy, but it leaves the lock file on disk with no owner. Any later crewmate whose slug matches then opens with structure_locked: true and the old crewmate's snapshot served as its page.

Why it matters

The issue rates this low-risk: slugs come from UUID-derived member_ids, which are not reused. Still, a lock file with no owner is state that nothing ever collects. And if a slug does come back, for example a legacy crewmate whose slug derives from its name, the new crewmate cannot adopt, apply or roll back a page until the person finds the lock and clears it from the Profile card.

Not a goal

  • Removing the deleted crewmate's other crew-panels files (the published panel record <slug>.json and the lock's .guard file). The guard is deliberately kept, see below.
  • Changing who may set or clear the lock, or anything about how the lock is enforced (_commit's InstanceLocked, the owner-gated human_only route).
  • Reaping members/<slug>/ or any other per-member tree.
  • Closing the pre-existing window where a lock POST that resolved its member before a concurrent delete writes the lock afterward. That window is in the lock route's resolution, not in the delete path, and its outcome is the same orphaned file this PR otherwise collects.

What changed (motivation → approach → change)

Symptom → cause → change:

  • Cause. The lock is keyed by member slug and lives in crew-panels, which only the gateway writes. The delete route's teardown only ever touched the member's own tree and the crew-log store, so it never removed the lock.
  • Approach. Remove the lock under exactly the authorization the crew-log reclaim beside it already uses. The danger here is the reverse case: clearing a lock that a LIVE crewmate still has. The lock is the person's decision about what that crewmate's agent may change, so clearing it by mistake hands the agent the page. So the decision is not a new rule. It reuses _member_slug_is_claimed, the slug is resolved from the config captured while the record still existed, and the call runs inside memory_store_namespace_lock, the one seam every member-id allocator shares.
  • dashboard_templates/instance.py: new remove_structure_lock(slug, *, still_unclaimed).
    • It returns at once when no lock file exists, so deleting a crewmate that never locked creates nothing in crew-panels.
    • Otherwise it takes the same <slug>.dashboard-lock.guard lock that set_structure_lock holds, asks still_unclaimed() under it, and only then unlinks lock_path(slug) and fsyncs the directory.
    • Taking the guard means a person's concurrent unlock cannot race the delete into a FileNotFoundError.
    • It reuses lock_path, which reuses panel_dir(), so a session key and an aliased (symlink/junction) store are still refused before any I/O.
    • Only the lock file is removed. The guard file stays, because another writer may hold it, and deleting a lock file someone holds breaks their mutual exclusion.
  • agent_admin/crew_removal.py: new _reclaim_deleted_member_dashboard_lock(name, cfg). It is best-effort and never raises, like every other step of the teardown. _delete_member calls it right after _reclaim_deleted_member_crew_log, inside the namespace-lock hold. It is re-exported from handlers/agents.py so it runs on the facade globals, as the composition contract requires.
  • The other orphaned per-slug file, crew-panels/<slug>.json (the published panel record), is left in place on purpose, and here is why it does no harm.
    • A later crewmate on the same slug is never blocked by it: agent_panel.publish asks owner_is_live inside its lock and hands over a record whose owner the roster no longer holds (handlers/agent_panel.py:_owner_is_live).
    • A crewmate with a different crew name never sees it: the read side, api_member_panel, refuses a record owned by a different exact crew name.
    • The one case where it is visible is a recreate under the SAME legacy name with no member_id. That crewmate sees the old published panel until its first publish replaces it. The data is the same owner's, the route is owner-gated, and it is replaced rather than enforced.
    • That differs from the lock, which is enforced against the newcomer: every adopt, apply and rollback is refused until the person notices.
  • Spec. docs/system-specs/modules/dashboard-instances.md ("The structure lock is the person's, and only theirs") now says the delete route is the lock's second remover, and under what conditions.

Backwards compatibility

Compatible: no route, field, validator or API changes shape. The delete route answers exactly as before, and the new step is best-effort, so a lock that cannot be removed never fails a delete.

Reader: src/kiro_crew/dashboard_templates/instance.py:read / _lock_snapshot -- crew page -- reads per slug; only a slug no roster crewmate derives loses its file, and "missing" reads as unlocked, the intended state for a later crewmate (test_delete_removes_the_departed_crewmates_lock)
Reader: src/kiro_crew/dashboard_templates/instance.py:_commit / is_locked -- chat | subagent (dashboard MCP apply/rollback) -- same per-slug read; a live crewmate's lock is kept (test_a_recreated_namesake_keeps_its_lock, test_other_crewmates_locks_are_untouched)
Reader: src/kiro_crew/dashboard/handlers/member_dashboard.py:api_member_dashboard / api_member_dashboard_lock -- crew page -- _resolve answers member_not_found for a deleted crewmate before the lock is read, so nothing changes for it
Reader: src/kiro_crew/dashboard_agentic.py:LOCKED turn line -- chat -- built from read()'s structure_locked, so it follows the same per-slug answer as above

Tests

New test/test_crew_delete_dashboard_lock.py (12 tests):

  • test_delete_removes_the_departed_crewmates_lock: the delete teardown removes the lock and is_locked reads false afterward.
  • test_the_lock_is_found_by_the_persisted_member_id: a crewmate with an explicit member_id loses the lock under that id, and the lock under its folded name (a different slug) is kept.
  • test_other_crewmates_locks_are_untouched: a sibling's lock file is byte-identical afterward.
  • test_a_crewmate_that_never_locked_creates_nothing: no lock and no .guard file appear.
  • test_a_repeated_cleanup_is_a_no_op: a second removal is safe and returns False.
  • test_an_unreadable_lock_file_is_still_removed: a damaged lock, which reads LOCKED because the check fails closed, is still collected.
  • test_a_recreated_namesake_keeps_its_lock: the roster re-read under the guard decides, not the captured snapshot.
  • test_an_unreadable_roster_removes_nothing: a config that does not parse keeps the lock.
  • test_the_predicate_is_asked_under_the_guard_and_claimed_keeps_the_lock: while the predicate runs, a second non-blocking take of the guard fails, and a "claimed" answer removes nothing.
  • test_a_session_key_has_no_lock_to_remove, test_an_aliased_store_is_refused_and_the_lock_kept: the existing name refusals still hold.
  • test_the_delete_route_removes_the_lock_under_the_namespace_lock: the real DELETE route answers 200 and removes the departed crewmate's lock while holding the namespace lock. The live crewmate's lock is kept.

The second commit isolates these tests from the shared monkeypatch, to satisfy semgrep test-autouse-shared-monkeypatch and test-bare-monkeypatch-undo (SAST failed on the first head). The autouse home fixture now uses _floor_monkeypatch, and the aliased-store case scopes its patch with monkeypatch.context(). Semgrep 1.78 does not run natively on this Windows box, so that fix is verified by CI's SAST job, not locally.

Negative controls, run locally on the patched tree:

  • Removing the route's call turns the route test red (assert [] == [True]).
  • Replacing the claim predicate with lambda: True turns test_a_recreated_namesake_keeps_its_lock and test_an_unreadable_roster_removes_nothing red.

Local gates (Windows, Python 3.13):

  • New file: 12/12 passed.
  • Related suites (test_dashboard_structure_lock, test_crew_log_member_unit_reclaim, test_dashboard_agents_composition_contract, test_agent_delete_prunes_private_copy, test_agent_avatar, test_change_cards_identity, test_crew_memory_store_binding, test_members_dm_thread): 631 passed, 9 skipped. 4 failed, all WinError 1314 raised inside the tests' own symlink_to setup: this host does not grant the symlink privilege, so none of them reaches the changed code.
  • black, isort, flake8, check_black_formatting, check_subprocess_encoding, check_comment_history, check_brand_name and test_flake_pattern_ratchet all clean.
  • mypy --platform linux src/kiro_crew: Success, no issues found in 2301 source files.
  • scripts/local-gate.py did NOT complete locally. agents.py is a hub, so its related set is 941 backend test files, and collecting them did not finish within a 40-minute bound on this Windows box (killed by my timeout, rc=143, no test result either way). That run is left to CI. The suites that exercise the changed code directly are listed above.

Manual verification

N/A — unit coverage sufficient: the change is a backend teardown step with no UI, and the route test drives the real DELETE /api/agents/{name} handler against a real data home, real config and real lock files.

Related Issues

Fixes #19365

Deferred from #18687.

Pattern harvest

Not generalizable: the class this belongs to ("per-member state stored outside members/<slug>/ needs its own reclaim step") is already handled step by step in this teardown, through the crew log, avatar and private copy. The panel_dir() docstring already tells whoever adds a member-space reaper to clear crew-panels too. A rule cannot list per-member stores that do not exist yet.

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

🤖 Generated with Claude Code

The person's structure lock lives in crew-panels/<slug>.dashboard-lock,
outside members/<slug>/, so no step of the crew delete teardown reached
it. The file outlived the crewmate, and a later crewmate deriving the
same slug started out locked to the old one's page snapshot.

The delete route now removes it next to the crew-log reclaim and under
the same authorization: the slug resolved from the config captured
before the delete, the decision taken inside the memory-store
namespace lock, and the removal only while no crew on disk still
derives that slug. remove_structure_lock takes the lock's own guard,
re-asks the roster under it, and unlinks only the lock file; a slug a
live crewmate claims keeps its lock.

Fixes kirodotdev#19365

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@leonlaiyc
leonlaiyc requested review from a team and KiroCrewCaptain as code owners October 13, 2026 15:00
@leonlaiyc
leonlaiyc requested a review from mbriones98 October 13, 2026 15:00
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 13, 2026
@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 225f2d11f21ff710f22488cee8e05a26751b2587 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 225f2d11f21ff710f22488cee8e05a26751b2587 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check that the facade monkeypatch in the route test intercepts the call; if it doesn't, held == [True] can't pass and the route coverage isn't real.

[DESIGN-REVIEWED] 225f2d1

Description read

[DESCRIPTION-READ] 85d046bdf2faa38b4830c036ec6b7db22e9583964633f156469bb160e831fff5

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 13, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — 🟡 CONCERNS

Premise-level review of 225f2d11f21ff710f22488cee8e05a26751b2587 via the fork AI-review pipeline — 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

remove_structure_lock is a second way to unlock: set_structure_lock(slug, False) already unlinks the same file under the same guard.

Not justified as shipped

  • Item 3 — duplicate of src/kiro_crew/dashboard_templates/instance.py:set_structure_lock: the new hunk's core with _locked(path.parent, lock_file=f"{slug}{_LOCK_GUARD_SUFFIX}"): ... path.unlink(); fsync_dir(path.parent) matches the base's locked=False branch (else: path.unlink() then fsync_dir). The base branch also already removes an unreadable lock, because is_locked reads it as True. The new function adds two things. One is a predicate asked under the guard, but the caller already holds memory_store_namespace_lock, the seam every member-id allocator shares, so _member_slug_is_claimed gives the same answer outside the guard. The other is the lexists early return, which the caller can do itself.
    Subtraction: delete remove_structure_lock and its Callable import. In _reclaim_deleted_member_dashboard_lock, call set_structure_lock(slug, False) only when os.path.lexists(lock_path(slug)) and not _member_slug_is_claimed(slug).
    Clears when: the function is removed, or the PR names a writer that can claim the slug between the namespace-locked roster check and the unlink without holding memory_store_namespace_lock.

What this change ships

Inventory (5 items) — 4 justified

Intent: when a person deletes a crewmate, a later crewmate with the same slug should not start out locked to the old one's page. FIX (deferred finding from #18687; the tests fail on base).

  1. Deleting a crewmate removes its dashboard structure lock file — justified
  2. The lock stays when a crewmate still in the roster derives the same slug — justified
  3. New public remove_structure_lock(slug, *, still_unclaimed) in instance.py — duplicate of set_structure_lock(slug, False)
  4. The spec and the set_structure_lock docstring now name the delete route as a second remover — justified
  5. The new teardown step is re-exported from handlers/agents.py so it runs on the facade globals — justified

[FIRST-PRINCIPLES-REVIEWED] 225f2d1

Description read

[DESCRIPTION-READ] dd89925458d584ca54c632f0bf2bc29a0364df4726010a6e5930a365e73f7eaa

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 13, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 225f2d11f21ff710f22488cee8e05a26751b2587 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 225f2d1

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 225f2d11f21ff710f22488cee8e05a26751b2587 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 225f2d1

…atch

The autouse home fixture now patches through _floor_monkeypatch, and
the aliased-store case scopes its patch with monkeypatch.context()
instead of undoing the shared instance, so neither can lift the other's
patches (semgrep test-autouse-shared-monkeypatch and
test-bare-monkeypatch-undo).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 13, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Thank you, @leonlaiyc, for this fix and the careful write-up.

This branch fell behind main with merge conflicts, so we carried it to a same-repo branch where CI runs with full credentials: #21660. Both of your commits are cherry-picked with -x and keep your authorship. The only change: remove_structure_lock moved into a new sibling module, dashboard_templates/structure_lock_removal.py, because instance.py would otherwise go over the 2,000-line cap. The behavior is the same.

#21660 is green and ready for review, so I'm closing this one in favor of it. Your branch is left in place.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clean up crew-panels/<slug>.dashboard-lock when a crewmate is deleted

2 participants