Skip to content

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

Merged
bolichen97 merged 2 commits into
mainfrom
replace/19825
Oct 18, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
replace/19825

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Replaces #19825 by @leonlaiyc, carried to a same-repo branch so CI runs with full credentials. Both commits are cherry-picked with -x and keep Leon's authorship. Thank you, Leon.

Rebased onto current main. Three conflicts, all "keep both": crew_removal.py (the new _remove_goal_check_ins sits beside _reclaim_deleted_member_dashboard_lock), the handlers/agents.py re-export list, and the typing import in dashboard_templates/instance.py (Callable + Iterable). No behavior was changed from the fork.

One change folded into the first commit: instance.py was at 1,999 lines on main, and the fork took it to 2,029, over the 2,000-line cap. remove_structure_lock now lives in a new sibling module, dashboard_templates/structure_lock_removal.py, which reuses instance's lock path, guard suffix and _locked. Same code, new home.

Local run on the new head: test_crew_delete_dashboard_lock.py, test_dashboard_structure_lock.py, test_dashboard_instance_crew_log.py plus the facade/composition guards: 2380 passed.

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/structure_lock_removal.py (new module): 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

@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision b4a754c108116b95052ac061a36966e97c0dbf7d 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 17, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] b4a754c

Description read

[DESCRIPTION-READ] adcdeee26a1f030a0026d40ff0f590ff32198477290c70b03c5ffe55f12743bd

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 added the readiness: checking Automated validation is still running label Oct 17, 2026
@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of b4a754c108116b95052ac061a36966e97c0dbf7d — 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: PASS

Nothing to check.

What this change ships

Inventory (6 items) — 6 justified

Intent: when a person deletes a crewmate, its dashboard structure lock goes too, so a later crewmate with the same slug does not start out locked to the deleted one's page. This is a FIX.

  1. Deleting a crewmate now removes its crew-panels/<slug>.dashboard-lock file — justified
  2. The lock is kept while any crewmate in the roster on disk still derives that slug (checked under the guard and the namespace lock) — justified
  3. Deleting a crewmate that never locked creates nothing in crew-panels — justified
  4. New structure_lock_removal.remove_structure_lock beside instance.py (1 consumer; instance.py is at the 2,000-line cap) — justified
  5. _reclaim_deleted_member_dashboard_lock re-exported from handlers/agents.py for the facade composition contract — justified
  6. Spec section and set_structure_lock docstring now name the delete route as the lock's second remover — justified

[FIRST-PRINCIPLES-REVIEWED] b4a754c

Description read

[DESCRIPTION-READ] 765ad753a20ab5080604580ba61b4d1bf8fd7b0148d5e9ef8f71f4199936a893

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] b4a754c

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

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

@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] b4a754c

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

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 17, 2026
@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 Oct 18, 2026
leonlaiyc and others added 2 commits October 18, 2026 07:45
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 #19365

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit de67cc2)
…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>
(cherry picked from commit 225f2d1)
@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 Oct 18, 2026
@iamwhatever
iamwhatever marked this pull request as ready for review October 18, 2026 08:37
@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners October 18, 2026 08:37
@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 Oct 18, 2026

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

Good to ship. No blocking issues and no should-fix notes.

Head reviewed: b4a754c.

What I checked on this head:

  • remove_structure_lock takes the same <slug>.dashboard-lock.guard that set_structure_lock holds, and asks the claim predicate under it. A live or recreated namesake keeps its lock.
  • The slug comes from the config captured before the record was dropped, so a crewmate with an explicit member_id loses the right file. This matches _reclaim_deleted_member_crew_log.
  • The call runs inside _drop_from_team, under memory_store_namespace_lock, and on a worker thread through _drained_to_thread. The bounded guard poll does not block the event loop.
  • A guard timeout or an aliased store raises inside the step, and the step logs it and returns. A delete never fails because of the lock.
  • The fast path returns before the guard when no lock exists, so a crewmate that never locked leaves nothing in crew-panels.
  • instance.py stays at 1,999 lines. The spec and the set_structure_lock docstring name the delete route as the second remover.
  • The 12 tests cover removal, the member_id slug, a sibling, a namesake, an unreadable roster, the predicate under the guard, unsafe names, and the real DELETE route under the namespace lock.
  • The linked issue is tier T2. No path is on the security denylist. All required checks on this head are green.

@bolichen97
bolichen97 merged commit 63cf7aa into main Oct 18, 2026
106 checks passed
@bolichen97
bolichen97 deleted the replace/19825 branch October 18, 2026 09:05
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 18, 2026
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.

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

3 participants