[kixelated]

First slice of Worktree process ownership, following kixelated/quest#127. Commands in a quest worktree checkout can now run supervised, and the checkout is released automatically once they stop.

What changed

• quest worktree run <id> -- <command> runs a job in the checkout inside a systemd user scope. Each run gets its own scope name (quest-worktree-<uuid>.scope), never reused, which avoids the slot-reuse races kixelated/quest#128 kept hitting. A short shell handshake checks that it runs in that scope's v2 cgroup, then waits for the supervisor to acknowledge before it execs the command. A supervisor that dies never acknowledges, so the command never starts.
• When the command exits, any descendants left in the scope are killed through cgroup.kill, and the supervisor waits for cgroup.events to report the scope empty. Once no other run remains in the checkout, the scratch declared at create is pruned. If the checkout was released, run restores it first, through admission. The first signal goes to the command, and a second one kills the whole scope.
• Crash reconciliation: each run is recorded, along with its owner (PID plus Linux start time), before its scope exists. Every registry operation drops runs whose owner has exited and whose scope is empty, then releases the checkout. A crashed supervisor's orphans keep the scratch until they stop (status lists the scope, which systemctl --user stop ends). A run that can't be inspected or confirmed stopped stays recorded, and the checkout stays reserved, with the reason in failure. If an automatic release fails, it is recorded the same way, and a successful command exits 1.
• release refuses while supervised runs are live.
• Scratch is declared at create (--scratch), so release needs no caller. release no longer takes --scratch.
• Stale registry lock: the lock directory holds a single file named after its owner and is created with an atomic rename. If that owner has exited on this host, its lock is reclaimed by unlinking that exact file, so a later owner's lock is never removed. Live locks are never stolen, and neither are locks held from another host.
• Folded in from kixelated/quest#127: a scratch symlink that points to another worktree is unlinked rather than refused (lstat on the final component).
• Hosts without the backend fail explicitly: non-Linux hosts, and hosts without Linux 5.14+ (cgroup.kill in the caller's unified cgroup, checked before any restore), a systemd 254+ user manager, or unified cgroup v2. kill() treats a missing cgroup.kill as success only once the cgroup itself is gone, so a populated scope is never waited on forever.
• CI starts a systemd user manager (linger) so the real-scope fixtures run.
• The quest file now covers only what remains: quest worktree remove (maintainer request), quest worktree stop, and clearing a stale inspection failure. Own-PC runner and Agent lifecycle integration move it from Required to Related, since the supervision they needed has landed.

Measurements

On this repository, a fresh checkout is 2.9 MB. It grows to 394 MB after bun install (root and cloudflare/) and bun run build inside run, and is back to 2.9 MB once run releases it. A suspended job keeps that same released footprint until it is restored.

Validation

• nix develop -c just check and nix develop -c just test pass locally: 354 CLI tests, 306 Worker tests, and the lifecycle checks.
• Unit tests, with fake scopes, cover these cases. Concurrent runs keep scratch until the last one stops, and a released checkout is restored by run. A crashed owner with a live scope is retained, then released once the scope empties. An uninspectable run and a run that can't be confirmed stopped are both treated as live. A failed automatic release is reported and keeps the checkout reserved. A command that never started keeps its scratch. A live, foreign-host, dead, or empty registry lock is each handled correctly, and a symlink to another worktree is unlinked. On non-Linux hosts, run fails explicitly. A cgroup without cgroup.kill, or a hybrid hierarchy, is refused, and kill() throws on a live group without cgroup.kill but not on a removed one (Codex P1 r4342588607).
• Real systemd fixtures (test/worktree.run.test.ts, Linux only, which fail if no user manager is present) check that run forwards argument and status values (including a literal $b) and kills a detached orphan, that SIGTERM cancellation with a live descendant exits 143 and releases, and that after the supervisor is SIGKILLed the run is retained until systemctl --user stop empties the scope, then released. All three passed 5 of 5 repeated runs, with no leftover scopes.
• Merged main (kixelated/quest#175, kixelated/quest#177, kixelated/quest#179), dropping the links to the deleted local-gate.md quest; just check and just test pass again on the merge.
• I dispatched the Check workflow on this draft. On c5efae0, all five jobs pass, including the systemd fixtures under linger in check and the explicit non-Linux refusal on Windows: run 39679519210. The first dispatch found that . passed childPath on Windows, where resolve("/", ".") is a drive root. That was pre-existing from kixelated/quest#127, and only the tracked-file check stopped it; it is fixed in c5efae0.

Decisions

Settled on the orchestrator's recommendation under the maintainer's standing instruction to apply its recommendations (2026-10-21); each is what's implemented.

1. ✅ Automatic release trigger: scratch is pruned when the last supervised run in a checkout stops, so a whole job belongs in one run.
2. ✅ Leftover descendants: SIGKILLed through the scope (cgroup.kill) as soon as the command exits.
3. ✅ Runner and agent-lifecycle quests: list /quest/m0/worktree.md under Related, not Required, since remove doesn't block them.
4. ✅ CI user manager: linger is enabled in the Check job so the real-scope fixtures run in CI.

Suggested follow-ups

• Added to the quest's remaining scope, alongside quest worktree remove: a quest worktree stop <id> to end a crashed supervisor's leftover processes, and clearing a stale inspection-failure reason on the next successful inspection.
• Terminal Ctrl-C reaches the command twice, once from the terminal and once forwarded. It is shared with quest gate and planned in kixelated/quest#180, not fixed here.

🤖 Generated with Claude Code

(Written by Claude Opus 5.5)

[kixelated]

/quest-start outcome

This lands the first slice of process ownership: quest worktree run supervises each job in its own systemd user scope, kills orphans when the command exits, and prunes the scratch declared at create once the checkout's last run stops. Crashed supervisors are reconciled once their scope is empty, and the registry lock of an exited process is reclaimed. The #127 symlink follow-up is folded in. quest worktree remove (maintainer request) is recorded as the quest's remaining scope.

Local just check and just test pass. A dispatched Check run passes on c5efae0 across all five jobs: https://github.com/kixelated/quest/actions/runs/39679519210

This PR stays a draft. Four decisions are listed under Decisions needed in the description, each with a recommendation already implemented: what triggers a release, killing leftover descendants, unblocking the runner and agent quests, and the CI user manager.

(Written by Claude Opus 5.5)

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-21T22:30:53.153820Z	6fc0924	New commits
🔒 Security Review	✅ Completed 2026-10-21T22:31:26.133880Z	6fc0924	New commits

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bfcac77340

ℹ️ 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".