RT-232: hydrate on-deck worktrees from a golden donor instead of a cold create

CLAUDE.md

@@ -27,6 +27,29 @@ calling a repo-keyed daemon verb, or displaying a repo name, read
 applies, the derivation rules, the identity-only verb guards, and the legacy
 re-key/heal/prune behavior.
 
+## Worktree pool: the golden tree
+
+Every repo with `onDeck > 0` has one `kind: "golden"` worktree under
+`~/.mattstack/rt/golden/<segment>/`. New on-deck members are built by
+`clonefile(2)`-ing its git-ignored artifacts and inheriting its
+`readyStamp`; they never run `pnpm install` at birth. Before touching
+`lib/worktree/hydrate.ts`, `lib/worktree/clonefile.ts`, or replenish, read
+`docs/superpowers/specs/2026-09-21-golden-worktree-hydration-design.md`.
+
+Three traps, each of which cost a real debugging round:
+
+- **The golden and the pool root must share an APFS volume.** `clonefile(2)`
+  fails `EXDEV` across volumes, and replenish answers that by silently
+  cold-creating, so the symptom is slowness, not an error.
+- **Nothing on the replenish path may create the pool root.** The volume
+  probe stats the nearest EXISTING ancestor for exactly this reason: an
+  existing pool root is what tells `isHeldByUnreadableMount`
+  (`reconcile.ts`) that a vanished mount is live again, and that hold is
+  all that stops a mount outage from pruning live claim state.
+- **`pnpm install` on an already-current tree still reruns every lifecycle
+  script** (~3 min on a large pnpm monorepo), so a hydrated member must inherit the
+  golden's stamp rather than "verify" itself with an install.
+
 ## rt chat
 
 Group chat and presence for the agents in the estate, over the daemon. Before

commands/__tests__/worktree-hydrate-clone.test.ts

@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { worktreeHydrateClone } from "../worktree.ts";
+
+const realExit = process.exit;
+let exitCode: number | undefined;
+let stderr = "";
+const realErr = console.error;
+
+function arm() {
+  exitCode = undefined;
+  stderr = "";
+  process.exit = ((code?: number) => { exitCode = code ?? 0; throw new Error("__exit__"); }) as never;
+  console.error = (...a: unknown[]) => { stderr += a.join(" ") + "\n"; };
+}
+afterEach(() => { process.exit = realExit; console.error = realErr; });
+
+async function run(args: string[]): Promise<number | undefined> {
+  arm();
+  try { await worktreeHydrateClone(args, {}); } catch (e) { if ((e as Error).message !== "__exit__") throw e; }
+  return exitCode;
+}
+
+describe("worktreeHydrateClone", () => {
+  test("usage exit 2 on missing args or src === dst", async () => {
+    expect(await run([])).toBe(2);
+    expect(await run(["/a"])).toBe(2);
+    expect(await run(["/a", "/a"])).toBe(2);
+  });
+
+  test("clones and exits 0", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "rthc-"));
+    mkdirSync(join(dir, "src", "n"), { recursive: true });
+    writeFileSync(join(dir, "src", "n", "f"), "x");
+    expect(await run([join(dir, "src"), join(dir, "dst")])).toBe(0);
+    expect(existsSync(join(dir, "dst", "n", "f"))).toBe(true);
+  });
+
+  test("EEXIST exits 5 with a clonefile: line on stderr", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "rthc-"));
+    mkdirSync(join(dir, "src"));
+    mkdirSync(join(dir, "dst"));
+    expect(await run([join(dir, "src"), join(dir, "dst")])).toBe(5);
+    expect(stderr).toMatch(/^clonefile: /m);
+  });
+});

commands/__tests__/worktree.test.ts

@@ -9,7 +9,7 @@ import { execSync } from "child_process";
 import { mkdtempSync, realpathSync, rmSync } from "fs";
 import { tmpdir } from "os";
 import { basename, join } from "path";
-import { repoLabel, worktreeAwaitReady, worktreeDispose, worktreeList, worktreeProvision } from "../worktree.ts";
+import { repoLabel, worktreeAwaitReady, worktreeDispose, worktreeFreshen, worktreeList, worktreeProvision } from "../worktree.ts";
 import { getRepoIdentity } from "../../lib/repo.ts";
 import { closeStateDb } from "../../lib/state/index.ts";
 import { deriveRepoIdentity, serializeIdentity } from "../../lib/settings/identity.ts";
@@ -302,6 +302,58 @@ describe("worktree CLI identity plumbing", () => {
       l.includes("running run run-1 at implement; rt runs abandon run-1"),
     )).toBe(true);
   });
+
+  test("list labels the golden row by kind, not its on-deck state", async () => {
+    installFakeDaemon({
+      ok: true,
+      data: {
+        trees: [
+          { name: "golden", path: "/nonexistent/golden", kind: "golden", state: "on-deck", branch: null, repoName: "github.com/acme/app", createdAt: "2026-09-21T00:00:00.000Z" },
+        ],
+      },
+    });
+    const lines: string[] = [];
+    const origLog = console.log;
+    console.log = (...args: unknown[]) => { lines.push(args.join(" ")); };
+    try {
+      await worktreeList([], {});
+    } finally {
+      console.log = origLog;
+    }
+    const plain = lines.map((l) => l.replace(/\x1b\[[0-9;]*m/g, ""));
+    const row = plain.find((l) => l.includes("/golden "));
+    expect(row).toBeDefined();
+    expect(row).toMatch(/\/golden\s+golden\s+\(detached\)/);
+    expect(row).not.toContain("on-deck");
+  });
+
+  test("freshen's picker offers the golden alongside on-deck members", async () => {
+    const { installFakePick } = await import("../../lib/ui/pick-fake.ts");
+    const origIsTTY = process.stdin.isTTY;
+    Object.defineProperty(process.stdin, "isTTY", { value: true, configurable: true });
+    installFakeDaemon({
+      ok: true,
+      data: {
+        trees: [
+          { name: "golden", path: "/g", kind: "golden", state: "on-deck", branch: null, repoName: "r1", createdAt: "2026-09-21T00:00:00.000Z" },
+          { name: "lupin", path: "/l", kind: "ephemeral", state: "on-deck", branch: null, repoName: "r1", createdAt: "2026-09-21T00:00:00.000Z" },
+          { name: "hedwig", path: "/h", kind: "ephemeral", state: "claimed", branch: null, repoName: "r1", createdAt: "2026-09-21T00:00:00.000Z" },
+        ],
+      },
+    });
+    const fake = installFakePick([{ kind: "result", result: { action: "cancel", value: null, query: "" } }]);
+    try {
+      await worktreeFreshen([], {});
+    } finally {
+      fake.restore();
+      Object.defineProperty(process.stdin, "isTTY", { value: origIsTTY, configurable: true });
+    }
+    expect(fake.calls).toHaveLength(1);
+    const values = fake.calls[0]!.request.rows.map((r) => r.value);
+    expect(values).toContain("/g");
+    expect(values).toContain("/l");
+    expect(values).not.toContain("/h");
+  });
 });
 
 describe("repoLabel", () => {

commands/worktree.ts

@@ -26,6 +26,7 @@ import { maybeOfferClaudeHook } from "./worktree-hook.ts";
 import { writeReadyApproval } from "../lib/worktree/ready-approval.ts";
 import { daemonQuery, lastQueryTimedOut, type DaemonResponse } from "../lib/daemon-client.ts";
 import { listWorktrees } from "../lib/git-worktrees.ts";
+import { clonePath, cloneExitCode, CLONE_EXIT } from "../lib/worktree/clonefile.ts";
 import {
   parseEachArgs,
   filterTargets,
@@ -253,6 +254,11 @@ interface TreeRow {
   duplicateBranch?: boolean;
 }
 
+/** The golden's state is readiness bookkeeping; its kind is what a human needs to see. */
+function rowLabel(r: { kind: string; state?: string }): string {
+  return r.kind === "golden" ? "golden" : (r.state ?? r.kind);
+}
+
 async function fetchTreeRows(json: boolean, repoName?: string): Promise<TreeRow[]> {
   const res = await daemonQuery("worktree:list", repoName ? { repoName } : undefined);
   const ok = requireQueryResult(json, res);
@@ -311,7 +317,7 @@ async function pickOneTree(rows: TreeRow[], message: string, breadcrumb: string[
   const trailingByPath = await enrichTrailingByPath(rows);
   const nameWidth = Math.max(...rows.map((r) => r.name.length));
   const options = rows.map((r) => {
-    const state = r.state ?? r.kind;
+    const state = rowLabel(r);
     const base =
       state === "disposable"
         ? r.disposableReason
@@ -618,7 +624,7 @@ export async function worktreeList(args: string[], _ctx: unknown): Promise<void>
     const dupPart = r.duplicateBranch ? `  ${yellow}duplicate branch${reset}` : "";
     const ownerPart = r.owner ? `  ${dim}${r.owner}${reset}` : "";
     console.log(
-      `  ${bold}${repoLabel(r.repoName)}/${r.name}${reset}  ${dim}${r.state ?? r.kind}${reset}  ${cyan}${r.branch ?? "(detached)"}${reset}${ownerPart}${mrPart}${dupPart}`,
+      `  ${bold}${repoLabel(r.repoName)}/${r.name}${reset}  ${dim}${rowLabel(r)}${reset}  ${cyan}${r.branch ?? "(detached)"}${reset}${ownerPart}${mrPart}${dupPart}`,
     );
   }
   console.log("");
@@ -722,10 +728,11 @@ export async function worktreeFreshen(args: string[], _ctx: unknown): Promise<vo
 
   if (!treeName && process.stdin.isTTY) {
     // Mirrors freshenCandidate (lib/daemon/worktree-reconciler.ts): only
-    // on-deck ephemeral trees and the main clone are ever freshened — a
-    // claimed tree is someone's active work and always comes back ran:[].
+    // on-deck ephemeral or golden trees and the main clone are ever
+    // freshened... a claimed tree is someone's active work and always comes
+    // back ran:[].
     const rows = (await fetchTreeRows(parsed.json, repoName))
-      .filter((r) => (r.kind === "ephemeral" && r.state === "on-deck") || r.kind === "main")
+      .filter((r) => ((r.kind === "ephemeral" || r.kind === "golden") && r.state === "on-deck") || r.kind === "main")
       .sort((a, b) => a.name.localeCompare(b.name));
     const picked = await pickOneTree(rows, "Freshen which worktree?", ["rt", "worktree", "freshen"]);
     if (!picked) { console.log(`\n  ${dim}nothing selected${reset}\n`); return; }
@@ -799,7 +806,7 @@ async function bindingsFromDaemon(repoName: string): Promise<WorktreeBinding[] |
   const res = await daemonQuery("worktree:list", { repoName });
   if (res === null || !res.ok) return null;
   const rows = (res.data?.trees ?? []) as TreeRow[];
-  return rows.map((r) => ({ path: r.path, branch: r.branch, state: r.state }));
+  return rows.map((r) => ({ path: r.path, branch: r.branch, state: r.state, kind: r.kind }));
 }
 
 /** Read-only git fallback — each is the one lifecycle command allowed this, since it never mutates. */
@@ -829,8 +836,13 @@ export async function worktreeEach(args: string[], _ctx: unknown): Promise<void>
     if (!process.stdin.isTTY) {
       fail("no --all/--on-deck flag and no TTY for the picker — pass --all or --on-deck");
     }
-    const widest  = Math.max(...bindings.map(b => relWorktreeName(repoPath, b.path).length));
-    const options = bindings.map(b => ({
+    const pickable = filterTargets(bindings, "pick");
+    if (pickable.length === 0) {
+      console.log(`\n  ${dim}no worktrees to run in${reset}\n`);
+      return;
+    }
+    const widest  = Math.max(...pickable.map(b => relWorktreeName(repoPath, b.path).length));
+    const options = pickable.map(b => ({
       value: b.path,
       label: relWorktreeName(repoPath, b.path).padEnd(widest),
       hint:  b.branch ?? "(detached)",
@@ -845,7 +857,7 @@ export async function worktreeEach(args: string[], _ctx: unknown): Promise<void>
       return;
     }
     const set = new Set(selected);
-    targets = bindings.filter(b => set.has(b.path));
+    targets = pickable.filter(b => set.has(b.path));
   } else {
     targets = filterTargets(bindings, parsed.mode);
     if (targets.length === 0) {
@@ -880,3 +892,15 @@ export async function worktreeEach(args: string[], _ctx: unknown): Promise<void>
   console.log(`  ${hasFailures(results) ? red : green}${summary}${reset}\n`);
   if (hasFailures(results)) process.exit(1);
 }
+
+/** Child-process body for hydration: one clonefile(2) of <src> at <dst>. Exit codes are the daemon's contract; see lib/worktree/clonefile.ts. */
+export async function worktreeHydrateClone(args: string[], _ctx: unknown): Promise<void> {
+  const [src, dst] = args.filter((a) => !a.startsWith("--"));
+  if (!src || !dst || src === dst) {
+    console.error("usage: rt worktree hydrate-clone <src> <dst>");
+    process.exit(CLONE_EXIT.usage);
+  }
+  const r = clonePath(src, dst);
+  if (!r.ok) console.error(`clonefile: ${r.message}`);
+  process.exit(cloneExitCode(r));
+}