daemon stability phase 4: the destructive engine earns its paranoia

commands/__tests__/endpoint.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { parseEndpointReleaseArgs } from "../endpoint.ts";
+
+describe("parseEndpointReleaseArgs", () => {
+ test("worktree first, no role", () => {
+ expect(parseEndpointReleaseArgs(["/path/wt"])).toEqual({ worktree: "/path/wt", role: undefined, roleInvalid: false });
+ });
+
+ test("--json before the worktree, no role", () => {
+ expect(parseEndpointReleaseArgs(["--json", "/path/wt"])).toEqual({ worktree: "/path/wt", role: undefined, roleInvalid: false });
+ });
+
+ test("worktree then --role", () => {
+ expect(parseEndpointReleaseArgs(["/path/wt", "--role", "web"])).toEqual({ worktree: "/path/wt", role: "web", roleInvalid: false });
+ });
+
+ test("--role before the worktree", () => {
+ expect(parseEndpointReleaseArgs(["--role", "web", "/path/wt"])).toEqual({ worktree: "/path/wt", role: "web", roleInvalid: false });
+ });
+
+ test("--role with no following value is flagged invalid, not treated as omitted", () => {
+ expect(parseEndpointReleaseArgs(["/path/wt", "--role"])).toEqual({
+ worktree: "/path/wt",
+ role: undefined,
+ roleInvalid: true,
+ });
+ });
+
+ test("--role followed by --json (option-like) is flagged invalid, not treated as a role value", () => {
+ expect(parseEndpointReleaseArgs(["/path/wt", "--role", "--json"])).toEqual({
+ worktree: "/path/wt",
+ role: undefined,
+ roleInvalid: true,
+ });
+ });
+});

commands/daemon.ts

@@ -456,6 +456,12 @@ export async function showStatus(args: string[] = []): Promise<void> {
  if (identity) {
  printFlavorInfo({ flavor: identity.flavor, version: identity.version, sourceRev: identity.sourceRev, pid: verdict.data.pid ?? null });
  }
+ // S077: a declared pool this machine has never opted into (unowned default
+ // is now disabled) would otherwise build nothing with no visible reason.
+ const worktreePool = verdict.data.worktreePool as { dormant: boolean; message?: string } | undefined;
+ if (worktreePool?.dormant) {
+ console.log(` ${dim}${worktreePool.message}${reset}`);
+ }
  } else if (verdict.state === "degraded") {
  // `status` timed out or errored, but the daemon proved it's alive — the
  // flavor cross-check matters most right here, so it earns its own ping.

commands/endpoint.ts

@@ -1,9 +1,12 @@
 #!/usr/bin/env bun
 
 /**
- * rt endpoint — read-only surface over dev-endpoint claims (RT-28 Task 7).
+ * rt endpoint: surface over dev-endpoint claims (RT-28 Task 7; `release`
+ * added in S068 as the manual escape hatch for a claim liveness can't clear
+ * on its own).
  *
- * rt endpoint lookup <role> [--json] does this worktree hold a claim?
+ * rt endpoint lookup <role> [--json] does this worktree hold a claim?
+ * rt endpoint release <worktree> [--role] free a claim by hand
  *
  * Repo identification mirrors the pattern already used by `rt worktree each`
  * (commands/worktree.ts): derive the repo identity from the cwd's git
@@ -124,3 +127,97 @@ export async function endpointLookup(args: string[]): Promise<void> {
  const statusColor = data.running ? green : yellow;
  console.log(`\n ${statusColor}${data.url}${reset} ${dim}(${data.running ? "running" : "claimed, not running"})${reset}\n`);
 }
+
+interface ReleaseData {
+ released: number;
+}
+
+/** Lists the worktrees this repo currently has claims for, over the daemon's own `endpoint:status` (a picker source, not a state read). */
+async function pickWorktree(identity: string): Promise<string | null> {
+ const res = await daemonQuery("endpoint:status", { repo: identity }, 10_000);
+ if (!res?.ok) return null;
+ const data = res.data as { repos: Record<string, Array<{ worktree: string }>> };
+ const worktrees = [...new Set((data.repos[identity] ?? []).map((c) => c.worktree))];
+ if (worktrees.length === 0) fail("no claims to release");
+ const { filterableSelect } = await import("../lib/rt-render.tsx");
+ return filterableSelect({
+ message: "worktree to release",
+ options: worktrees.map((w) => ({ value: w, label: w })),
+ });
+}
+
+export interface ParsedEndpointReleaseArgs {
+ worktree: string | undefined;
+ role: string | undefined;
+ /** `--role` was present but its value was missing or itself another flag (e.g. `--role --json`): a real role must never be silently treated as omitted. */
+ roleInvalid: boolean;
+}
+
+/**
+ * Pure arg parse for `rt endpoint release`, split out so the --role-absent
+ * case (roleFlagIdx === -1) is unit-testable without a git repo or daemon.
+ * roleFlagIdx + 1 must only be excluded from worktreeArgs when --role is
+ * actually present, or index 0 (the worktree itself) gets filtered out.
+ */
+export function parseEndpointReleaseArgs(args: string[]): ParsedEndpointReleaseArgs {
+ const roleFlagIdx = args.indexOf("--role");
+ const roleValueIdx = roleFlagIdx === -1 ? -1 : roleFlagIdx + 1;
+ const roleValue = roleFlagIdx !== -1 ? args[roleValueIdx] : undefined;
+ const roleInvalid = roleFlagIdx !== -1 && (roleValue === undefined || roleValue.startsWith("--"));
+ const role = roleInvalid ? undefined : roleValue;
+ const worktreeArgs = args.filter((a, i) => i !== roleFlagIdx && i !== roleValueIdx && !a.startsWith("--"));
+ return { worktree: worktreeArgs[0], role, roleInvalid };
+}
+
+/**
+ * Manual escape hatch (S068): frees a worktree's endpoint claim(s) directly,
+ * for the case a recycled pid or a wedged process leaves a claim liveness
+ * can't clear on its own. Repo identity is always the cwd's; `<worktree>` is
+ * the claim to drop and need not be the cwd itself (that is the whole point
+ * of a manual release).
+ */
+export async function endpointRelease(args: string[]): Promise<void> {
+ const json = args.includes("--json");
+ const parsed = parseEndpointReleaseArgs(args);
+ if (parsed.roleInvalid) fail("--role needs a value (usage: rt endpoint release <worktree> --role <role>)");
+ const role = parsed.role;
+ let worktree = parsed.worktree;
+
+ const cwd = process.cwd();
+ const toplevel = await gitToplevel(cwd);
+ if (!toplevel) fail("not in a git repo");
+
+ const remote = await gitRemote(toplevel);
+ const repoName = remote ? deriveRepoName(remote) : basename(toplevel);
+ const identity = serializeIdentity(await deriveRepoIdentity(toplevel));
+
+ if ((await resolveIndexPathForIdentity(identity)) === null) {
+ fail(`repo "${repoName}" is not registered... visit it with rt first (repos.json is a derived mirror, not the source of truth)`);
+ }
+
+ if (!worktree) {
+ if (process.stdin.isTTY && !json && !process.env.RT_BATCH) {
+ worktree = (await pickWorktree(identity)) ?? undefined;
+ if (!worktree) process.exit(0);
+ } else {
+ fail("usage: rt endpoint release <worktree> [--role <role>] [--json]");
+ }
+ }
+
+ const res = await daemonQuery("endpoint:release", { repo: identity, worktree, role }, 10_000);
+ if (!res) fail("daemon unavailable... rt endpoint release needs the rt daemon (rt daemon start)");
+ if (!res.ok) fail(res.error ?? "release failed");
+
+ const data = res.data as ReleaseData;
+
+ if (json) {
+ console.log(JSON.stringify({ ok: true, ...data }));
+ return;
+ }
+
+ if (data.released === 0) {
+ console.log(`\n ${dim}no claim(s) to release for ${worktree}${role ? ` (role "${role}")` : ""} in ${repoName}${reset}\n`);
+ return;
+ }
+ console.log(`\n ${green}released ${data.released} claim${data.released === 1 ? "" : "s"}${reset} ${dim}for ${worktree} in ${repoName}${reset}\n`);
+}

commands/worktree.ts

@@ -44,6 +44,9 @@ const PROVISION_TIMEOUT_MS = 6 * 60_000;
 const DISPOSE_TIMEOUT_MS = 2 * 60_000;
 const FRESHEN_TIMEOUT_MS = 10 * 60_000;
 const ADOPT_TIMEOUT_MS = 2 * 60_000;
+// Restore recreates the worktree AND re-runs ready steps (an install), so it
+// gets provision's budget rather than dispose's.
+const RESTORE_TIMEOUT_MS = 6 * 60_000;
 
 // ─── Arg parsing (pure — unit tested in lib/__tests__/worktree-cli-args.test.ts) ──
 
@@ -128,6 +131,22 @@ export function parseDisposeArgs(args: string[]): DisposeArgs {
  return { tree, owner: owner.value, repoName: repo.value, force: force.present, json: json.present };
 }
 
+export interface RestoreArgs {
+ tree?: string;
+ repoName?: string;
+ list: boolean;
+ json: boolean;
+}
+
+export function parseRestoreArgs(args: string[]): RestoreArgs {
+ let rest = args;
+ const json = takeBoolFlag(rest, "--json"); rest = json.rest;
+ const list = takeBoolFlag(rest, "--list"); rest = list.rest;
+ const repo = takeFlag(rest, "--repo"); rest = repo.rest;
+ const tree = rest.find((a) => !a.startsWith("--"));
+ return { tree, repoName: repo.value, list: list.present, json: json.present };
+}
+
 export interface ListArgs {
  repoName?: string;
  json: boolean;
@@ -157,13 +176,15 @@ export function parseFreshenArgs(args: string[]): FreshenArgs {
 export interface AdoptArgs {
  repoName?: string;
  json: boolean;
+ claim: boolean;
 }
 
 export function parseAdoptArgs(args: string[]): AdoptArgs {
  let rest = args;
  const json = takeBoolFlag(rest, "--json"); rest = json.rest;
+ const claim = takeBoolFlag(rest, "--claim"); rest = claim.rest;
  const repo = takeFlag(rest, "--repo"); rest = repo.rest;
- return { repoName: repo.value, json: json.present };
+ return { repoName: repo.value, json: json.present, claim: claim.present };
 }
 
 // ─── Shared IO helpers ───────────────────────────────────────────────────────
@@ -202,6 +223,22 @@ function explainError(error: string): string {
  }
  if (error.startsWith("checkout-failed:")) return `checkout failed: ${error.slice("checkout-failed:".length)}`;
  if (error.startsWith("create-failed:")) return `worktree creation failed at step "${error.slice("create-failed:".length)}"`;
+ if (error === "not-found") return "no retained trash entry with that name";
+ if (error === "no-manifest") return "that entry has no disposal manifest (disposed before RT-51, or the write failed) and cannot be restored";
+ if (error === "branch-elsewhere") return "that branch already exists again... restore refuses to clobber it";
+ if (error === "no-head-sha") return "the disposal manifest has no recorded commit to restore from";
+ if (error === "path-exists") return "the pool root already has a tree at that name";
+ if (error === "worktree-add-failed") return "git worktree add failed while restoring";
+ if (error === "copy-failed") {
+ return "the worktree was recreated but copying the retained tree's gitignored content back failed... " +
+ "the checkout and the retained trash entry are both left in place; a plain retry will refuse " +
+ "with \"path-exists\", so recover by hand (copy the entry's content over yourself, or `rt worktree dispose --force` the half-restored tree and retry)";
+ }
+ if (error === "register-failed") {
+ return "the worktree was recreated but the registry write did not land, so rt does not know about it yet... " +
+ "the checkout and the retained trash entry are both left in place; a plain retry will refuse " +
+ "with \"branch-elsewhere\"/\"path-exists\", so recover by hand (`rt worktree adopt --repo <name>` picks up the checkout, or dispose it and retry)";
+ }
  return error;
 }
 
@@ -386,7 +423,7 @@ export async function worktreeDispose(args: string[], _ctx: unknown): Promise<vo
  repoName = picked.repoName;
  }
 
- const payload: Record<string, unknown> = { force: parsed.force };
+ const payload: Record<string, unknown> = { force: parsed.force, callerPid: process.pid };
  if (repoName) payload.repoName = repoName;
  if (parsed.owner) payload.owner = parsed.owner;
  if (treeName) payload.tree = treeName;
@@ -418,6 +455,79 @@ export async function worktreeDispose(args: string[], _ctx: unknown): Promise<vo
  console.log("");
 }
 
+// ─── restore ─────────────────────────────────────────────────────────────────
+
+/** Restorable trash entries for `repoName`, straight from disk (read-only, so like `each` this skips the daemon round trip). */
+async function fetchRestorableEntries(repoName: string, repoPath: string) {
+ const { listRestorableEntries } = await import("../lib/worktree/restore.ts");
+ return listRestorableEntries(repoName, repoPath);
+}
+
+function printRestorableEntries(entries: Awaited<ReturnType<typeof fetchRestorableEntries>>): void {
+ if (entries.length === 0) { console.log(`\n ${dim}nothing recoverable${reset}\n`); return; }
+ console.log("");
+ for (const e of entries) {
+ console.log(
+ ` ${bold}${e.name}${reset} ${cyan}${e.branch ?? "(detached)"}${reset} ${dim}disposed ${e.disposedAt.slice(0, 10)} (${e.reason}), kept until ${e.keptUntil.slice(0, 10)}${reset}`,
+ );
+ }
+ console.log("");
+}
+
+async function pickRestorableEntry(entries: Awaited<ReturnType<typeof fetchRestorableEntries>>): Promise<string | null> {
+ if (entries.length === 0) return null;
+ const { filterableSelect } = await import("../lib/rt-render.tsx");
+ const nameWidth = Math.max(...entries.map((e) => e.name.length));
+ const options = entries.map((e) => ({
+ value: e.name,
+ label: e.name.padEnd(nameWidth),
+ hint: `${e.branch ?? "(detached)"} disposed ${e.disposedAt.slice(0, 10)} (${e.reason}), kept until ${e.keptUntil.slice(0, 10)}`,
+ }));
+ return filterableSelect({ message: "Restore which worktree?", options, stderr: true });
+}
+
+export async function worktreeRestore(args: string[], _ctx: unknown): Promise<void> {
+ const parsed = parseRestoreArgs(args);
+ const repoName = parsed.repoName ? await resolveRepoArg(parsed.repoName, (m) => failText(parsed.json, m)) : currentRepoIdentity();
+ if (!repoName) failText(parsed.json, "no repo... pass --repo <name> or run from inside a registered repo");
+
+ const repoIndex = loadRepoIndex();
+ const repoPath = repoIndex[repoName];
+ if (!repoPath) failText(parsed.json, `repo "${repoName}" not registered in ~/.mattstack/rt/repos.json`);
+
+ if (parsed.list) {
+ const entries = await fetchRestorableEntries(repoName, repoPath);
+ if (parsed.json) { console.log(JSON.stringify({ entries }, null, 2)); return; }
+ printRestorableEntries(entries);
+ return;
+ }
+
+ let treeName = parsed.tree;
+ if (!treeName) {
+ if (process.stdin.isTTY && !parsed.json && !process.env.RT_BATCH) {
+ const entries = await fetchRestorableEntries(repoName, repoPath);
+ const picked = await pickRestorableEntry(entries);
+ if (!picked) { console.log(`\n ${dim}nothing selected${reset}\n`); return; }
+ treeName = picked;
+ } else {
+ failText(parsed.json, "no target... pass a tree name (no TTY for the picker)");
+ }
+ }
+
+ const res = await daemonQuery("worktree:restore", { repoName, tree: treeName }, RESTORE_TIMEOUT_MS);
+ const ok = requireQueryResult(parsed.json, res);
+
+ if (parsed.json) { console.log(JSON.stringify(ok.data, null, 2)); return; }
+
+ const d = ok.data as { restored: boolean; path: string; tree: string; readyFailed?: boolean; failedStep?: string };
+ console.log("");
+ console.log(` ${green}✓${reset} ${bold}${d.tree}${reset} restored ${dim}${d.path}${reset}`);
+ if (d.readyFailed) {
+ console.log(` ${yellow}⚠${reset} ready step "${d.failedStep}" failed... tree is usable but dependencies may be stale`);
+ }
+ console.log("");
+}
+
 // ─── list ────────────────────────────────────────────────────────────────────
 
 export async function worktreeList(args: string[], _ctx: unknown): Promise<void> {
@@ -493,14 +603,25 @@ export async function worktreeAdopt(args: string[], _ctx: unknown): Promise<void
  if (!parsed.repoName) failText(parsed.json, "--repo <name> is required for adopt");
  const repoName = await resolveRepoArg(parsed.repoName, (m) => failText(parsed.json, m));
 
- const res = await daemonQuery("worktree:adopt", { repoName }, ADOPT_TIMEOUT_MS);
+ const res = await daemonQuery("worktree:adopt", { repoName, claim: parsed.claim }, ADOPT_TIMEOUT_MS);
  const ok = requireQueryResult(parsed.json, res);
 
  if (parsed.json) { console.log(JSON.stringify(ok.data, null, 2)); return; }
 
- const d = ok.data as { main: string; claimed: string[]; disposed: string[]; refused: Array<{ tree: string; reason: string }> };
+ const d = ok.data as {
+ main: string;
+ claimed: string[];
+ unmanaged: string[];
+ disposed: string[];
+ refused: Array<{ tree: string; reason: string }>;
+ };
  console.log("");
- console.log(` ${green}✓${reset} adopted ${d.main ? `main=${d.main}, ` : ""}${d.claimed.length} claimed, ${d.disposed.length} disposed`);
+ console.log(
+ ` ${green}✓${reset} adopted ${d.main ? `main=${d.main}, ` : ""}${d.claimed.length} claimed, ` +
+ `${d.unmanaged.length} unmanaged, ${d.disposed.length} disposed`,
+ );
+ for (const name of d.claimed) console.log(` ${green}✓${reset} ${name} ${dim}(kind: ephemeral, claimed)${reset}`);
+ for (const name of d.unmanaged) console.log(` ${dim}·${reset} ${name} ${dim}(kind: unmanaged, untouched)${reset}`);
  for (const r of d.refused) console.log(` ${yellow}⚠${reset} ${r.tree} not disposed: ${r.reason}`);
  console.log("");
 }