@dougharness/cli 1.1.1 → 1.3.0

package/node_modules/@dougharness/flow/hooks/register.tsx

@@ -0,0 +1,94 @@
+// The live autopilot pane (card autopilot-live-queue). It opens itself when a run starts (card autopilot-pane-auto-open); /doug-autopilot reopens it. It polls
+// .doug/.state/autopilot.json (written by scripts/autopilot.mjs) and shows the same lines the board's panel shows.
+// It also refreshes on prompt submit, turn end, and after a Bash call, because a reload drops the session.start timer (card autopilot-pane-current).
+import { atom, read, update } from 'claude-code'
+import type { Register } from 'claude-code'
+
+import { AUTOPILOT_FILE, autopilotLines, autopilotView, parseAutopilot, shouldOpenPane } from '../lib/autopilot-core.mjs'
+
+const PANE = 'doug-autopilot'
+const POLL_MS = 5000
+const lines = atom({ plugin: 'doug-flow', key: 'autopilot' } as const, [] as string[])
+// The startedAt of the run the pane was last opened for, so a pane the user closed stays closed for that run.
+const opened = atom({ plugin: 'doug-flow', key: 'autopilot-opened' } as const, null as string | null)
+
+const refresh = async ($: any) => {
+  try {
+    const root = await $.session.root()
+    let text = ''
+    try {
+      text = await $.fs.read(`${root}/${AUTOPILOT_FILE}`)
+    } catch {
+      // no file: no run
+    }
+    const state = parseAutopilot(text)
+    const fresh = autopilotLines(autopilotView(state, new Date()))
+    await update($, lines, old => (JSON.stringify(old) === JSON.stringify(fresh) ? old : fresh))
+    // Only `autopilot.autoOpenPane: false` in .doug/config.json turns the auto-open off.
+    let autoOpen = true
+    try {
+      autoOpen = JSON.parse(await $.fs.read(`${root}/.doug/config.json`))?.autopilot?.autoOpenPane !== false
+    } catch {
+      // missing or unparsable config: flag on
+    }
+    const last = await read($, opened)
+    if (state && shouldOpenPane(state, last, autoOpen, new Date())) {
+      await update($, opened, () => state.startedAt as string)
+      await $.ui.open({ id: PANE, title: 'Autopilot' })
+    }
+  } catch {
+    // a failed poll keeps the last drawing
+  }
+}
+
+export const register: Register = on => {
+  on('session.start', async ($, e, next) => {
+    await $.command.register({
+      name: 'doug-autopilot',
+      description: 'Show the autopilot queue live in a pane',
+    })
+
+    // The timer starts only in an interactive session; the event hooks run in any session (two small reads per prompt, turn end, and Bash call).
+    if (e.isInteractive) {
+      await refresh($)
+      $.clock.every(POLL_MS, () => refresh($))
+    }
+
+    return next(e)
+  })
+
+  // A reload drops the session.start timer, so these hooks also refresh the pane (card autopilot-pane-current).
+  on('prompt.submit', async ($, e, next) => {
+    await refresh($)
+    return next(e)
+  })
+
+  on('turn.complete', async ($, e, next) => {
+    await refresh($)
+    return next(e)
+  })
+
+  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
+    const ran = await next(e)
+    await refresh($)
+    return ran
+  })
+
+  on('command.run', { command: 'doug-autopilot' }, async $ => {
+    await $.ui.open({ id: PANE, title: 'Autopilot' })
+    return { text: 'Autopilot pane opened.' }
+  })
+
+  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
+    const { Box, Text } = $.ui.resolve(e)
+    const shown = await read($, lines)
+    return (
+      <Box flexDirection="column">
+        {shown.length === 0 && <Text dimColor>No autopilot run.</Text>}
+        {shown.map(line => (
+          <Text>{line}</Text>
+        ))}
+      </Box>
+    )
+  })
+}

package/node_modules/@dougharness/flow/lib/autopilot-core.mjs

@@ -0,0 +1,117 @@
+// The pure half of the autopilot view (card autopilot-live-queue): no Node imports, so the live pane's hooks module
+// (which may import only its own files) can use it. lib/autopilot-view.mjs re-exports it and adds the file read.
+export const AUTOPILOT_FILE = ".doug/.state/autopilot.json";
+export const STEPS = ["research", "tester", "coder", "reviewer", "gate", "commit", "record"];
+// A running file untouched for this long is no longer a live run (the lead died or the session closed). The lead's
+// conservative choice where the card is silent.
+export const INACTIVE_MS = 2 * 60 * 60 * 1000;
+
+// The state parsed from file text, or null for invalid JSON, a wrong version, or a non-object. Never throws.
+export function parseAutopilot(text) {
+  try {
+    const s = JSON.parse(text);
+    if (!s || typeof s !== "object" || Array.isArray(s) || s.version !== 1) return null;
+    if (s.cards !== undefined && !Array.isArray(s.cards)) return null;
+    return s;
+  } catch {
+    return null;
+  }
+}
+
+const hhmm = (iso) => {
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return "";
+  const d = new Date(t);
+  return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+};
+
+const usd = (n) => (typeof n === "number" ? `$${n.toFixed(2)}` : "-");
+const num = (n, suffix = "") => (typeof n === "number" ? `${n}${suffix}` : "-");
+
+// The view of a state at `now` (a Date or a millisecond count), or null for a null state.
+export function autopilotView(state, now = new Date()) {
+  if (!state || typeof state !== "object") return null;
+  const nowMs = new Date(now).getTime();
+  const ended = state.status === "ended";
+  const updated = Date.parse(state.updatedAt);
+  const stale = !ended && !(nowMs - updated <= INACTIVE_MS);
+  const mode = ended ? "ended" : stale ? "inactive" : "running";
+  const live = mode === "running";
+
+  const cards = (Array.isArray(state.cards) ? state.cards : [])
+    .filter((c) => c && typeof c === "object")
+    .map((c) => {
+      let cardState = c.state;
+      let detail = "";
+      if (cardState === "running" && !live) {
+        cardState = "interrupted";
+        detail = "interrupted";
+      } else if (cardState === "running") {
+        detail = c.step ? `${c.step} since ${hhmm(c.stepStartedAt)}`.trim() : "started";
+      } else if (cardState === "landed") {
+        detail = c.commit ? String(c.commit) : "";
+      } else if (cardState === "stopped") {
+        detail = c.reason ? String(c.reason) : "";
+      }
+      return { id: c.id, title: c.title ?? "", size: c.size ?? "", class: c.class ?? "", state: cardState, detail };
+    });
+
+  const runningCard = live ? (Array.isArray(state.cards) ? state.cards : []).find((c) => c && c.state === "running") : null;
+  const running = live
+    ? (Array.isArray(state.cards) ? state.cards : []).filter((c) => c && c.state === "running").map((c) => ({ id: c.id, runId: c.runId ?? null }))
+    : [];
+  const current = runningCard ? { id: runningCard.id, step: runningCard.step ?? null, since: runningCard.step ? hhmm(runningCard.stepStartedAt) : null } : null;
+
+  const landed = cards.filter((c) => c.state === "landed").length;
+  const stopped = cards.filter((c) => c.state === "stopped").length;
+  const header =
+    mode === "ended"
+      ? `Autopilot ended ${hhmm(state.endedAt ?? state.updatedAt)}: ${landed} landed, ${stopped} stopped`.replace(/\s+:/, ":")
+      : mode === "inactive"
+        ? `Autopilot inactive since ${hhmm(state.updatedAt)}`
+        : `Autopilot running since ${hhmm(state.startedAt)}`;
+
+  const caps = state.caps && typeof state.caps === "object" ? state.caps : {};
+  const used = state.used && typeof state.used === "object" ? state.used : {};
+  return {
+    mode,
+    header,
+    cards,
+    current,
+    running,
+    caps: {
+      usd: `${usd(used.usd)} / ${usd(caps.usd)}`,
+      wall: `${num(used.wallMin)} / ${num(caps.wallMin)} min`,
+      context: `${num(used.contextPct, "%")} / ${num(caps.contextPct, "%")}`,
+    },
+    filed: (Array.isArray(state.filed) ? state.filed : []).filter((f) => f && typeof f === "object").map((f) => ({ ...f })),
+  };
+}
+
+// Whether the live pane should open on its own: a running, still-active run whose startedAt is not the one already
+// opened for (a closed pane is not reopened for the same run). `autoOpen` false (autopilot.autoOpenPane) turns it off.
+export function shouldOpenPane(state, lastOpenedStartedAt, autoOpen = true, now = new Date()) {
+  if (autoOpen === false) return false;
+  if (!state || typeof state !== "object") return false;
+  if (state.status !== "running") return false;
+  if (typeof state.startedAt !== "string" || state.startedAt === "") return false;
+  if (state.startedAt === lastOpenedStartedAt) return false;
+  return autopilotView(state, now)?.mode === "running";
+}
+
+const MARKS = { landed: "✓", running: "▶", stopped: "✗", queued: "·", interrupted: "!" };
+
+// The view as text lines for a text surface: the header, one line per card, a caps line, one line per filed card.
+export function autopilotLines(view) {
+  if (!view) return [];
+  const lines = [view.header];
+  for (const c of view.cards) {
+    const shape = [c.size, c.class].filter(Boolean).join("/");
+    lines.push(`${MARKS[c.state] ?? "?"} ${c.id}${c.title ? ` ${c.title}` : ""}${shape ? ` (${shape})` : ""}${c.detail ? ` ${c.detail}` : ""}`);
+  }
+  lines.push(`caps: usd ${view.caps.usd}, wall ${view.caps.wall}, context ${view.caps.context}`);
+  for (const f of view.filed) {
+    lines.push(`+ ${f.id} (${f.kind}${f.from ? ` from ${f.from}` : ""}) ${f.position ?? ""}`.trimEnd());
+  }
+  return lines;
+}

package/node_modules/@dougharness/flow/lib/autopilot-view.mjs

@@ -0,0 +1,17 @@
+// The autopilot state file (.doug/.state/autopilot.json, card autopilot-live-queue) as the pane and the served board
+// page show it. The pure view lives in autopilot-core.mjs (no Node imports, so the pane can use it); this module adds
+// the file read. Neither throws on a missing, unreadable, or malformed file; a view of "no run" is null.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { AUTOPILOT_FILE, parseAutopilot } from "./autopilot-core.mjs";
+
+export { AUTOPILOT_FILE, STEPS, INACTIVE_MS, parseAutopilot, autopilotView, autopilotLines, shouldOpenPane } from "./autopilot-core.mjs";
+
+// The parsed state, or null for a missing or unreadable file, invalid JSON, a wrong version, or a non-object.
+export function readAutopilot(dir) {
+  try {
+    return parseAutopilot(readFileSync(join(dir, AUTOPILOT_FILE), "utf8"));
+  } catch {
+    return null;
+  }
+}

package/node_modules/@dougharness/flow/lib/board.mjs

@@ -62,7 +62,9 @@ export function readyCapWarning(board) {
 // autopilot-wall-cap-by-size, wall-budget-size-class). Each size has `all`; a class key is present only when its
 // cell had WALL_BUDGET_MIN_N or more landings. `board.mjs budgets --from docs/live-runs.md` recomputes it.
 export const WALL_BUDGET_MIN_N = 5;
-export const WALL_BUDGET_MIN = {"S":{"all":57,"code":53,"docs":29,"gate-script":116,"prose":50,"tests-only":66},"M":{"all":102,"code":112,"gate-script":289},"L":{"all":274}};
+// Source: `board.mjs budgets --from docs/live-runs.md` on 2026-10-12 over 373 cards with a Wall clock row (S 274, M 83, L 16;
+// rehearsal entries skipped, repeated ids summed).
+export const WALL_BUDGET_MIN = {"S":{"all":52,"code":46,"docs":29,"gate-script":112,"prose":41,"tests-only":66},"M":{"all":106,"code":90,"gate-script":157},"L":{"all":170}};
 
 // A card's budget: its size's class cell when it has one, else the size's `all`. No or an unknown size counts as M.
 export function cardBudgetMinutes(card, table = WALL_BUDGET_MIN) {
@@ -78,8 +80,9 @@ export function wallCapMinutes(cards, table = WALL_BUDGET_MIN) {
 
 // The landings in a docs/live-runs.md text: one { id, minutes } per `## <date>, <id>: <title>` section that has a
 // `| Wall clock | <n> min |` row (text after min is allowed; a decimal n is skipped) (the first such row). Older multi-column tables have no such row and are skipped.
+// Rehearsal entries are skipped, and a card with several entries is one sample, their sum.
 export function parseLiveRunWalls(text) {
-  const out = [];
+  const byId = new Map();
   let id = null;
   let seen = false;
   for (const line of String(text).split("\n")) {
@@ -90,13 +93,18 @@ export function parseLiveRunWalls(text) {
       continue;
     }
     if (id === null || seen) continue;
+    // A rehearsal entry (the fixture's run, not this repository's) is no landing of the card.
+    if (/^Rehearsal /.test(line)) {
+      id = null;
+      continue;
+    }
     const w = /^\| Wall clock \| (\d+) min(?:\s[^|]*)? \|\s*$/.exec(line);
     if (w) {
-      out.push({ id, minutes: Number(w[1]) });
+      byId.set(id, (byId.get(id) ?? 0) + Number(w[1]));
       seen = true;
     }
   }
-  return out;
+  return [...byId].map(([k, minutes]) => ({ id: k, minutes }));
 }
 
 // The table recomputed from samples joined to their cards: p80 (sorted ascending, index min(floor(0.8 n), n - 1)) per size and per size/class cell. A
@@ -126,6 +134,71 @@ export function wallBudgetTable(samples, board, { minN = WALL_BUDGET_MIN_N, fall
   return { table, cells };
 }
 
+// USD budget per card in dollars, a size x class table at p80 of measured cost over flow and hand landings (card
+// usd-budget-size-class), shaped like WALL_BUDGET_MIN. Each size has `all`; a class key is present only when its cell
+// had USD_BUDGET_MIN_N or more landings with a Cost row. `board.mjs budgets --usd --from docs/live-runs.md`
+// recomputes it. There is no floor: the autopilot USD cap is the sum of these over the queue.
+export const USD_BUDGET_MIN_N = 5;
+// Source: `board.mjs budgets --usd --from docs/live-runs.md` on 2026-10-11 over 19 cards with a measured Cost (rehearsal entries
+// skipped, repeated ids summed): S 5, M 10, L 4, so no class cell reached USD_BUDGET_MIN_N and each size is its all-class p80.
+// Every row so far is a flow entry, since hand entries only gain a Cost row with this card. L rests on 4 cards.
+export const USD_BUDGET = {"S":{"all":3.32},"M":{"all":15.79},"L":{"all":14.51}};
+
+// A card's USD budget: its size's class cell when it has one, else the size's `all`. No or an unknown size counts as M.
+export function cardBudgetDollars(card, table = USD_BUDGET) {
+  const size = card && (card.size === "S" || card.size === "M" || card.size === "L") ? card.size : "M";
+  const row = table[size];
+  const cls = card && card.class;
+  return typeof cls === "string" && Object.prototype.hasOwnProperty.call(row, cls) && cls !== "all" ? row[cls] : row.all;
+}
+
+export function usdCapDollars(cards, table = USD_BUDGET) {
+  return cards.reduce((sum, c) => sum + cardBudgetDollars(c, table), 0);
+}
+
+// The measured costs in a docs/live-runs.md text: one { id, usd } per `## <date>, <id>: <title>` section that has a
+// `| Cost | $<n> |` row (text after the amount is allowed; the first such row; `not measured` is skipped). Flow and hand
+// entries share the row. Rehearsal entries are skipped, and a card with several entries is one sample, their sum.
+export function parseLiveRunCosts(text) {
+  const byId = new Map();
+  let id = null;
+  let seen = false;
+  let tableSeen = false;
+  for (const line of String(text).split("\n")) {
+    if (line.startsWith("## ")) {
+      const m = /^## \d{4}-\d{2}-\d{2}, ([^:\s]+): /.exec(line);
+      id = m ? m[1] : null;
+      seen = false;
+      tableSeen = false;
+      continue;
+    }
+    if (id === null || seen) continue;
+    // A rehearsal entry (the fixture's run, not this repository's) is no landing of the card.
+    if (/^Rehearsal /.test(line)) {
+      id = null;
+      continue;
+    }
+    if (line.trim() !== "" && !line.startsWith("|") && tableSeen) {
+      // prose after the section's table ends the landing: a later Cost row belongs to no landing
+      id = null;
+      continue;
+    }
+    if (line.startsWith("|")) tableSeen = true;
+    const c = /^\| Cost \| \$(\d+(?:\.\d+)?)(?:\s[^|]*)? \|\s*$/.exec(line);
+    if (c) {
+      byId.set(id, Math.round(((byId.get(id) ?? 0) + Number(c[1])) * 100) / 100);
+      seen = true;
+    }
+  }
+  return [...byId].map(([k, usd]) => ({ id: k, usd }));
+}
+
+// usdBudgetTable is wallBudgetTable's twin over { id, usd } samples: p80 per size and per size/class cell, a class
+// cell under minN left out, an empty size keeping the fallback's `all`.
+export function usdBudgetTable(samples, board, { minN = USD_BUDGET_MIN_N, fallback = USD_BUDGET } = {}) {
+  return wallBudgetTable(samples.map((s) => ({ id: s.id, minutes: s.usd })), board, { minN, fallback });
+}
+
 function today() {
   return new Date().toISOString().slice(0, 10);
 }
@@ -707,7 +780,14 @@ function wallRow(wall, flags) {
   return `within budget (${wall.wallMinutes ?? wallMin(longest)} min a task)${unverified}`;
 }
 
-export function runEntry({ card, report, cost = null, codexCost = null, wallClock = null, wall = null, mergeCommit = null, record = null, adversary = [], date = new Date().toISOString().slice(0, 10), batch = null, sharedCost = null, taskIds = [], note = null, rehearsal = null }) {
+// The first prose line of a rehearsal entry. The start scenario runs in an empty git repo; every other scenario
+// (start-feature included) on the ts-basic fixture, the rule rehearse-lib's rehearsalNote uses.
+function rehearsalLine(rehearsal, cardId) {
+  const where = rehearsal === "start" ? "an empty git repo" : "the ts-basic fixture";
+  return `Rehearsal ${rehearsal} for card \`${cardId}\` on ${where} (scripts/rehearse.mjs); the commit and gate below are the fixture's, not this repository's.`;
+}
+
+export function runEntry({ card, report, cost = null, codexCost = null, wallClock = null, wall = null, mergeCommit = null, record = null, adversary = [], date = new Date().toISOString().slice(0, 10), batch = null, sharedCost = null, taskIds = [], note = null, rehearsal = null, rehearsalOutcome = null }) {
   const inBatch = Array.isArray(batch) && batch.length > 1;
   if (inBatch) report = filterReportForCard(report, card.id, taskIds);
   const lines = [];
@@ -716,13 +796,13 @@ export function runEntry({ card, report, cost = null, codexCost = null, wallCloc
   const batchNote = inBatch ? `, in one plan with ${listOthers(batch, card.id)} (one approval, one run, one landing)` : "";
   lines.push(
     rehearsal
-      ? `Rehearsal ${rehearsal} for card \`${card.id}\` on the ts-basic fixture (scripts/rehearse.mjs); the commit and gate below are the fixture's, not this repository's.`
+      ? rehearsalLine(rehearsal, card.id)
       : `Ran through /doug-next on this repo from card \`${card.id}\`${record ? ` in \`${record}\`` : ""}${batchNote}. Plan "${report.plan}", integration branch \`${report.integrationBranch}\`${report.modelsSource ? `, models from ${report.modelsSource}` : ""}.`,
   );
   lines.push("");
   lines.push("| Measure | Value |");
   lines.push("|---|---|");
-  lines.push(`| Outcome | ${outcomeOf(report)}${pausedAt(report) ? `; next: ${listNext(report)}` : ""} |`);
+  lines.push(`| Outcome | ${rehearsal ? `rehearsal ${rehearsal} ${rehearsalOutcome}` : outcomeOf(report)}${!rehearsal && pausedAt(report) ? `; next: ${listNext(report)}` : ""} |`);
   lines.push(`| Cost | ${cost === null ? "not measured" : `$${Number(cost).toFixed(2)}${inBatch ? " for this card's tasks" : ""}`} |`);
   if (!inBatch || batch[0] === card.id) {
     lines.push(
@@ -794,22 +874,23 @@ export function handWallVerdict(card, wallClock, table = WALL_BUDGET_MIN) {
 
 // The live-runs entry for a hand-track card (decision 0005): no workflow report and no levels, so it records what
 // doug-hand can measure: the landing commit, the wall clock, and the gate result, plus an optional note.
-export function handEntry({ card, commit = null, wallClock = null, gate = null, note = null, record = null, date = new Date().toISOString().slice(0, 10), rehearsal = null, table = WALL_BUDGET_MIN }) {
+export function handEntry({ card, commit = null, wallClock = null, gate = null, note = null, record = null, date = new Date().toISOString().slice(0, 10), rehearsal = null, rehearsalOutcome = null, table = WALL_BUDGET_MIN, cost = null }) {
   const lines = [];
   lines.push(`## ${date}, ${card.id}: ${card.title}`);
   lines.push("");
   lines.push(
     rehearsal
-      ? `Rehearsal ${rehearsal} for card \`${card.id}\` on the ts-basic fixture (scripts/rehearse.mjs); the commit and gate below are the fixture's, not this repository's.`
+      ? rehearsalLine(rehearsal, card.id)
       : `Built by hand through doug-hand from card \`${card.id}\`${record ? ` in \`${record}\`` : ""} (hand track: a gated by-hand change); no workflow run.`,
   );
   lines.push("");
   lines.push("| Measure | Value |");
   lines.push("|---|---|");
-  lines.push(`| Outcome | ${commit ? "landed" : "not landed"} |`);
+  lines.push(`| Outcome | ${rehearsal ? `rehearsal ${rehearsal} ${rehearsalOutcome}` : commit ? "landed" : "not landed"} |`);
   const shownCommit = rehearsal && commit ? String(commit).slice(0, 7) : commit;
   lines.push(`| Commit | ${shownCommit ? `\`${shownCommit}\`` : "none"} |`);
   lines.push(`| Wall clock | ${wallClock === null ? "not measured" : wallClock} |`);
+  if (cost !== null && cost !== undefined) lines.push(`| Cost | $${Number(cost).toFixed(2)} |`);
   if (!rehearsal) lines.push(`| Wall budget | ${handWallVerdict(card, wallClock, table).text} |`);
   lines.push(`| Gate | ${gate === null ? "not recorded" : gate} |`);
   lines.push("");

package/node_modules/@dougharness/flow/lib/card-land.mjs

@@ -0,0 +1,115 @@
+// landCard: land a hand card's branch (card parallel-card-queens B6, ADR 0015). The card's worktree is rebased on the
+// base branch, the rebased tree is gated through the vendored verify.mjs (--json; its gate.lock is shared by every
+// card), main fast-forwards to the branch, and only the card's own worktree is removed. A refusal returns
+// { ok: false, reason } with main untouched; it never throws (landPlan's contract, lib/land.mjs).
+//
+//   1. the base branch is the one checked out in dir, and no tracked file outside .doug/ is modified
+//   2. no commit on the branch since the base carries a Co-Authored-By or Claude-Session line
+//   3. git rebase <base> in the worktree; a conflict is aborted and refused as "rebase-conflict: <files>", any
+//      other rebase failure is refused under its own reason
+//   4. gate: .doug/hooks/scripts/verify.mjs --json with its cwd at the worktree; red refuses, nothing merges
+//   5. git merge --ff-only <branch> in dir
+//   6. removeFinishedWorktrees(dir, { branches: [branch] }) only, never mergedInto
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { commandEnv, trailerCommits, vendoredVerifySpawnTimeoutMs } from "./land.mjs";
+import { removeFinishedWorktrees } from "./worktrees.mjs";
+
+function git(dir, args) {
+  return execFileSync("git", args, { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 60000 }).trim();
+}
+
+function tryGit(dir, args) {
+  try {
+    return git(dir, args);
+  } catch {
+    return null;
+  }
+}
+
+function tail(text, lines = 30) {
+  return String(text || "").trimEnd().split("\n").slice(-lines).join("\n");
+}
+
+const GATE_TIMEOUT_MS = 600000;
+
+// Returns { ok: true, commit, gateLine, lockWaitMs, removed, kept } or { ok: false, reason }.
+export function landCard(dir, { id, branch, worktree, base = "main" } = {}) {
+  try {
+    return land(dir, { id, branch, worktree, base });
+  } catch (err) {
+    return { ok: false, reason: `land-card failed: ${tail((err && (err.stderr || err.message)) || err, 5)}` };
+  }
+}
+
+function land(dir, { id, branch, worktree, base }) {
+  if (!branch || !worktree) return { ok: false, reason: "land-card needs a branch and a worktree" };
+  if (tryGit(dir, ["rev-parse", "--verify", "-q", `refs/heads/${branch}`]) === null) return { ok: false, reason: `branch ${branch} does not exist; nothing to land` };
+  if (!existsSync(worktree)) return { ok: false, reason: `worktree ${worktree} does not exist` };
+  if (tryGit(worktree, ["symbolic-ref", "--short", "-q", "HEAD"]) !== branch) return { ok: false, reason: `worktree ${worktree} does not have ${branch} checked out` };
+
+  const current = tryGit(dir, ["symbolic-ref", "--short", "-q", "HEAD"]);
+  if (!current) return { ok: false, reason: "detached HEAD; check out the base branch first" };
+  if (current !== base) return { ok: false, reason: `base branch is ${base} but ${current} is checked out; check out ${base} first (land never switches your branch)` };
+
+  // Not through git(): its trim() would eat the leading status column of the first line.
+  const dirty = execFileSync("git", ["status", "--porcelain", "--untracked-files=no"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => l.slice(3).replace(/^"|"$/g, ""))
+    .filter((p) => !p.startsWith(".doug/"));
+  if (dirty.length) return { ok: false, reason: `tracked files are modified: ${dirty.join(", ")}; commit or stash them first` };
+
+  const trailered = trailerCommits(dir, base, branch);
+  if (trailered.length) return { ok: false, reason: `commits on ${branch} carry attribution trailers (Co-Authored-By or Claude-Session), which this repository does not record; rewrite them first:\n${trailered.map((c) => `  ${c.sha} ${c.subject} (${c.trailers.join(", ")})`).join("\n")}` };
+
+  try {
+    git(worktree, ["rebase", base]);
+  } catch (err) {
+    const files = (tryGit(worktree, ["diff", "--name-only", "--diff-filter=U"]) || "").split("\n").filter(Boolean);
+    if (files.length) {
+      tryGit(worktree, ["rebase", "--abort"]);
+      return { ok: false, reason: `rebase-conflict: ${files.join(", ")}` };
+    }
+    tryGit(worktree, ["rebase", "--abort"]);
+    return { ok: false, reason: `rebase-failed: ${tail(err.stderr || err.message, 3)}` };
+  }
+
+  const vendored = join(dir, ".doug/hooks/scripts/verify.mjs");
+  if (!existsSync(vendored)) return { ok: false, reason: `gate not run: ${vendored} does not exist` };
+  const r = spawnSync(process.execPath, [vendored, "--json", "--by", "land-card", "--cwd", worktree, "--record-dir", dir, "--timeout-ms", String(GATE_TIMEOUT_MS)], {
+    cwd: worktree,
+    encoding: "utf8",
+    timeout: vendoredVerifySpawnTimeoutMs(GATE_TIMEOUT_MS, 2),
+    maxBuffer: 64 * 1024 * 1024,
+    env: commandEnv(),
+  });
+  let out = null;
+  try {
+    out = JSON.parse(String(r.stdout || "").trim().split("\n").pop());
+  } catch {
+    out = null;
+  }
+  if (!out || !Array.isArray(out.results) || out.results.length === 0) {
+    const why = r.error && r.error.code === "ETIMEDOUT" ? "timed out" : "gave no readable result";
+    return { ok: false, reason: `gate failed on ${branch}: the vendored verify.mjs ${why}` };
+  }
+  const gateLine = "gate: " + out.results.map((x) => `${x.name || x.command} ${x.ok === true ? "ok" : `exit ${x.status}`}`).join("; ");
+  const lockWaitMs = typeof out.lockWaitMs === "number" ? out.lockWaitMs : 0;
+  if (out.ok !== true) {
+    const bad = out.results.find((x) => x.ok !== true) || out.results[0];
+    return { ok: false, reason: `gate red on ${branch}: \`${bad.command}\` (${bad.timedOut ? "timed out" : `exit ${bad.status}`})\n${bad.outputTail || ""}`, gateLine, lockWaitMs };
+  }
+
+  try {
+    git(dir, ["merge", "--ff-only", branch]);
+  } catch (err) {
+    tryGit(dir, ["merge", "--abort"]);
+    return { ok: false, reason: `fast-forward of ${base} to ${branch} failed:\n${tail((err.stdout || "") + "\n" + (err.stderr || ""), 10)}`, gateLine, lockWaitMs };
+  }
+  const commit = git(dir, ["rev-parse", "--short", "HEAD"]);
+  const wt = removeFinishedWorktrees(dir, { branches: [branch] });
+  return { ok: true, id, commit, gateLine, lockWaitMs, removed: wt.removed, kept: wt.kept };
+}