feat(cluster): reap orphaned dev clusters on worktree removal

[daryllimyt]

Problem

Removing a git worktree left its Docker Compose stack running indefinitely. The
containers keep their ports and volumes, and nothing ever cleans them up — a
stack was recently found still running 23h after its worktree had been pruned,
alongside ~80 orphaned volumes from long-dead worktrees.

Worse, an orphan cannot be traced back to an owner. WORKTREE_ID is derived from
the branch name, and git rev-parse --abbrev-ref HEAD returns HEAD in a
detached worktree, which lowercases to head. Every detached checkout therefore
collapses into a shared head namespace:

tracecat-head-1 … tracecat-head-5   # five different worktrees, indistinguishable

Worktrees for this repo are created by several tools, so a hook on any single one
of them cannot cover every removal path.

What changed

Ownership registry. cluster up records the owning worktree's absolute path
under the shared git common dir, so the entry outlives the worktree it describes.
TRACECAT_CLUSTER_REGISTRY_DIR overrides the location for tests.

cluster reap [--dry-run]. Tears down any cluster whose recorded worktree is
gone, including volumes left behind by an earlier down, unregisters the
portless alias, and clears the entry. It runs quietly at the start of up so
freed cluster numbers get reused.

cluster rm --all. Non-interactive teardown of every cluster owned by the
current checkout, wired to a worktrunk pre-remove hook. The plain rm path
could not be used: with more than one cluster it falls through to an interactive
selector that reads from /dev/tty, which has no TTY during hook execution, and
it would only ever have removed one of them.

cluster list now resolves clusters by project root and prints the owning
worktree, which addresses the "tracecat-head-1 tells you nothing" problem
directly.

Safety properties

• Only a project whose registered worktree path is missing is ever destroyed.
• Running clusters with no registry entry are reported and left alone, so
  stacks started before this lands are never touched.
• No docker volume prune, system prune, or any unfiltered bulk removal.
• The long-lived shared tracecat-infra stack is explicitly excluded.
• The hook exits 0 when nothing is running, so it can never block removal.

Verification

• 9/9 in tests/unit/test_cluster_script.py, shellcheck -S warning clean,
  bash -n clean, ruff and basedpyright clean.
• Confirmed against a live Docker daemon with two unrelated clusters running:
  reap --dry-run correctly refused to touch them (unregistered → warn only).
• Isolation checked in both directions behind a fake docker binary that logs
  instead of destroying: rm --all from one checkout performed zero
  mutations while foreign clusters were running, and correctly targeted only the
  cluster whose config files pointed at the current checkout.
• Confirmed empirically that worktrunk runs hooks with cwd set to the worktree
  being removed, so the relative ./scripts/cluster path resolves.

Review guide

• scripts/cluster — start at reap_clusters, then the rm --all handler and
  the registry read/write helpers. The bulk of the remaining diff is the
  cluster-resolution refactor that makes list/auto-select key off project root
  instead of the branch-derived id; that is the part most worth a careful look.
• One set -u subtlety: on macOS bash 3.2, "${arr[@]}" on an empty array is an
  unbound-variable error, so array expansions are guarded on ${#arr[@]}.

Notes

• .config/wt.toml is tracked, so existing worktrees only pick up the
  pre-remove hook once their branch includes this commit. The reaper is the
  load-bearing half and works regardless.
• The registry only covers clusters started after this lands; clusters already
  running stay unregistered (and safely skipped) until they are restarted.

---

Summary by cubic

Prevents orphaned dev clusters by recording their owning worktree and adding an automatic reaper. Also adds a non-interactive cleanup on worktree removal and safer cluster selection across worktrees.

• New Features

  • Ownership registry: up records WORKTREE_PATH, WORKTREE_ID, and cluster number under the shared git common dir (override with TRACECAT_CLUSTER_REGISTRY_DIR).
  • cluster reap [--dry-run]: Removes clusters whose recorded worktree is gone, deletes labelled volumes, unregisters any portless alias, and clears the registry entry. Runs quietly before up. Skips unregistered stacks and excludes tracecat-infra.
  • cluster rm --all: Non-interactive teardown of all clusters owned by the current checkout; used by the worktrunk pre-remove hook.
  • Safer selection/listing: A bare ./cluster lists all Tracecat clusters across worktrees and marks “this worktree.” Status commands (e.g. ports, ps) resolve across worktrees; mutating commands stay in this worktree unless you pass an explicit cluster number. Explicit numbers target the owning worktree.

• Migration

  • No action required. Existing clusters without a registry entry are reported and left alone until restarted.
  • To clean old orphans once, run: ./scripts/cluster reap --dry-run then ./scripts/cluster reap.
  • The worktrunk pre-remove hook now calls ./scripts/cluster rm --all; it applies to worktrees once they include this change.

^{Written for commit 5711062. Summary will update on new commits.}

[zeropath-ai]

✅ No security or compliance issues detected. Reviewed everything up to 5711062.

Security Overview

• 🔎 Scanned files: 3 changed file(s)
• 🔗 Scan Link: https://zeropath.com/app/repositories/00dffd6c-8834-4dc9-b6d8-b44cd1622986?scanId=5b6a9f29-14a9-4749-b857-1f66cb571fa2&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type	Relevant files
Enhancement	► .config/wt.toml Add pre-remove hook to tear down clusters via cluster script
Enhancement	► scripts/cluster Major rewrite with extensive new functionality for cluster lifecycle, registry, port management, and cross-worktree behavior
Enhancement	► tests/unit/test_cluster_script.py Add unit tests for cluster script behavior and registry interactions

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 57110629cd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Do not delete volumes from the pre-remove hook

Whenever a developer removes a worktree with wt, this hook invokes rm --all, whose implementation runs docker compose ... down --volumes without asking whether the worktree's database and other persisted state may be destroyed. Worktree removal is not explicit confirmation of volume data loss, so keep the hook non-destructive or require a separate confirmed cleanup action.

AGENTS.md reference: AGENTS.md:L65-L67

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Make startup orphan reaping opt-in

Every cluster up now silently calls the non-dry reaper, which executes down --volumes and explicit docker volume rm operations for registered clusters whose worktree is missing. Thus starting an unrelated development cluster can permanently erase an orphan's PostgreSQL and other persisted data without the user requesting cleanup or confirming data loss; restrict destructive reaping to an explicit, confirmed command.

AGENTS.md reference: AGENTS.md:L65-L67

Useful? React with 👍 / 👎.