🤖 feat: cross-process quiescence for renaming and deleting sub-agent task checkouts

[ThomasK33]

Summary

Let sub-agent task checkouts be renamed and deleted safely while several Xum processes share one XUM_ROOT. This is the missing prerequisite for the paused checkout-preparation stack (#4364 and its stack). Maintainer requirements: renames must work, and sub-agents must be cleaned up on archive and delete.

Why it is needed

The preparation stack refused every structural change to a task checkout: rename, remove, archive-delete/snapshot, restore. Two problems motivated that:

1. Late clean-up hits a successor. One process rotated a task's attempt in config after another process's owner check but before its deleteWorkspace. The late delete destroyed the successor's checkout and session.
2. Work may still be running elsewhere. Local "finished" state cannot prove that another cooperating process has no admitted work, tool child or MCP server still running in the checkout.

Required sequence

1. Close new admission for the footprint.
2. Establish quiescence, or return a truthful "busy" refusal. Never wait while holding a lock that completion or use-release needs.
3. Revalidate exclusively and mutate.
4. Reopen admission against the resulting state.

Proposed shape (design pass, 2026-09-25; not implemented)

• Use records per footprint key (canonical checkout realpath), under XUM_ROOT/checkout-uses/<key>/: {useId, workspaceId, attemptId?, kind, owner: process identity, groups: [{pgid, leader birth}]}.
  • Created before each effect, deleted when it ends.
  • Written at: turn admission to release, LocalBaseRuntime.exec process groups, MCP server lifetime, init hooks, terminal PTYs, devcontainer execs.
  • Judged with the death rule in src/node/utils/concurrency/processLiveness.ts (🤖 fix: never take a cross-process lock from a live holder #4461, 🤖 fix: never break the config file lock of a live holder #4464). A process group is dead when kill(-pgid, 0) returns ESRCH.
• Mutation gate (gate.json): write the gate, then scan uses. Admission writes its use, then reads the gate, so one side always sees the other.
• Busy refusal: a live owner, or a dead owner with a live group, means busy. Name the kind in the error, for example "MCP server in pid N".
• Attempt-bound mutation: re-read the row with compare-and-swap on taskAttemptId and materializationId captured at decision time. Check the nonce before deleting. 🤖 feat(tasks): fence sub-agent attempts before durable workflow recovery #4308's auto-clean-up of finished leaves must bind expectedAttemptId.
• Rename and preparation proof: capture identity and nonce before git worktree move. Re-capture after it: dev/ino, the .git pointer and the nonce must be unchanged, with only the path changed. Publish a re-signed proof in the same config edit as the name/path change. This amends the contract's "proof is immutable" rule for that one transition.
• Crash recovery:
  • Delete: a pendingRemoval {removalId, materializationId, owner} marker set by compare-and-swap before deleting.
  • Rename: an intent journal {from, to, materializationId, phase, owner}. Roll back if only the old path exists; roll forward if only the new path exists with a matching nonce; otherwise refuse.

Estimate: about 1.2k production and 2–2.5k test lines, including multi-process SIGKILL harnesses. A smaller variant (about 600 lines, no journal) leaves the gate after an interrupted operation and refuses with an index.lock-style recovery message. That brings back a lockout, which the maintainer rejected.

Open design gaps (must be solved before implementation)

• Spawn-to-record crash window: a child can start before its pgid is recorded. It needs a pre-exec handshake (for example sh -c 'read _ && exec …' released only after the record is durable).
• Lifetimes that can't be proven: container-side processes of devcontainer execs, and escaped daemons (setsid, double fork). These must be declared out of contract explicitly, or covered some other way.
• Linearization proof for admission versus mutation across publication, incomplete records, aliases and rename.
• Clean-up versus successor creation: every relevant writer must take part in exclusion through the destructive effect.
• Idle foreign MCP servers: they would make an idle workspace "busy". The owning process could stop its own servers first. Today stopServers runs after the checkout is deleted (workspaceService.ts remove path).

Delivery

• Registry, gate, busy refusal and attempt-bound removal are useful on main on their own (see the linked issue on main's rename/delete gaps). They could land first.
• The proof re-sign has to land with the preparation stack.
• The stack then swaps its blanket refusal (workspaceStructuralMutationGuard.ts and its call sites) for the gate.

References

• Paused stack: 🤖 fix(tasks): sanitize a direct task's forked checkout before publishing its record #4362, 🤖 feat(tasks): prove task checkout preparation before publication; refuse structural mutations of task checkouts #4364, 🤖 fix: refuse ambiguous structural targets; verify prepared publications persisted #4371, 🤖 feat: preparation proof v2 binds every multi-project checkout #4373, 🤖 fix: protect devcontainer task worktrees from structural mutations #4374.
• Integrated local stack on current main, all gates green: branch park/checkout-preparation-integration (f52e6a1). It includes behavior tests for today's refusals and a killed-coordinator writer test.
• Lock prerequisites (landed): 🤖 fix(mcp): clear host override documents in-process #4443, 🤖 fix: never take a cross-process lock from a live holder #4461, 🤖 fix: never break the config file lock of a live holder #4464. Deployment contract: every cooperating process sharing one XUM_ROOT runs in one PID domain.

---

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high

[linear-code]

MUX-209

[ThomasK33]

Related follow-ups: #4477 (sub-agent clean-up on archive/delete, depends on this), #4478 (in-process-only rename/delete checks on main), #4480 (lock hardening follow-ups), #4481 (devcontainer override shell writers).

---

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high

[ThomasK33]

Two more cross-process windows, from Codex's security review of #4798 (#4746). Both need a second backend on the same root, so they are recorded here instead of fixed there:

1. WorktreeArchiveSnapshotService.clearSnapshotState now clears the snapshot pointer, then deletes archive-state. Another backend can archive the unarchived workspace and recapture into the same fixed-name directory before the delete runs, and the delete then removes the new snapshot. In-process this is serialized by the task-tree lifecycle lock. The old order had the mirror race (the new pointer was lost instead).
2. ProjectService.remove deletes secrets after the config edit (sub-project path now, top-level path before). Another backend can re-register the same path and save secrets before the delete, which erases them. Secrets are keyed only by path.

A fix needs either cross-process exclusion around these steps or per-generation names (snapshot dir, secrets bucket).

---

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high

[ThomasK33]

Requirement note from #4446 (closed): peer admission and instance discovery still honor another backend's delegated workspace turn only as a process-local courtesy (delegatedRootUnavailable and listInstanceWorkspaces read this backend's memory; documented in the CONCURRENT BACKENDS contract, #4802). The airtight version needs the same cross-process use-record / gate registry sketched here, applied to workspaces: a durable, lock-serialized record of "workspace W has an admitted delegated turn owned by live backend B", read by every backend's admission path under the same lock, with dead-owner reclaim through the shared death rule (as #4772's workspace-turn live-owner locks do for handle liveness). Tracked with the other remaining gaps in #4801.

---

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high

[ThomasK33]

Picking this up (Option A from the rename/delete plan, after the user's decision that two backends may keep using one workspace concurrently). Only structural mutations will refuse, fail closed and without waiting, while another live backend uses the workspace or its task checkouts.

Delivery, one PR at a time, each merged before the next:

1. PR 3: a read-only inspectCrossProcessLock probe in the lock kit (reusing its record parser, the shared death rule and the blocker text) plus WorkspaceUseLeases: one lock file per backend, per workspace and per activity kind, refcounted in-process.
2. PR 4: the per-workspace mutation gate (no call sites yet).
3. PR 5a: use leases for turns and terminals.
4. PR 6: rename, remove, archive with delete/snapshot, unarchive restore and deleteWorktree go through the gate; the concurrent-backends contract (🤖 docs: contract for two backends sharing one Xum root #4802) gains the structural-mutation guarantee. This closes 🤖 feat: cross-process quiescence for renaming and deleting sub-agent task checkouts #4476 and 🤖 bug: workspace rename and delete rely on in-process checks only #4478.

Not in this run: MCP, init and executeBash leases (a follow-up issue unless PR 5a converges early), rename crash recovery, and #4477. #4772 has no read-only probe (it try-acquires, which reclaims a dead owner's file), so the probe is added to the kit rather than duplicated.

---

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high