@dougharness/cli 1.1.0 → 1.2.0

package/node_modules/@dougharness/gates/scripts/stop-gate.mjs

@@ -73,11 +73,11 @@
 // Fails closed exactly like subagentsInFlight: with trace.enabled false, or the trace file missing or
 // unreadable, there is no evidence either way, so the gate runs as today.
 
-import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync, unlinkSync, openSync, closeSync, readSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync, unlinkSync, openSync, closeSync, readSync } from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { join, dirname, isAbsolute, relative, resolve, sep } from "node:path";
-import { runHook, allow, blockStop, systemMessage } from "../lib/io.mjs";
+import { runHook, allow as allowRaw, blockStop, systemMessage as systemMessageRaw } from "../lib/io.mjs";
 import { loadConfig, projectDir } from "../lib/config.mjs";
 import { loadState, saveState } from "../lib/state.mjs";
 import { matchAny } from "../lib/glob.mjs";
@@ -88,11 +88,12 @@ import { verificationEvidence, describeMissingEvidence } from "../lib/evidence.m
 import { changedFiles, captureBaseline, sinceBaseline, headAt, committedSince, walkProposalPathFiles, fileIdentity, treeFingerprint, sameTree, readAgentStart, readTurnStart, turnTreeStatus, onlyNoTestPathsChanged, movedSinceVerified } from "../lib/baseline.mjs";
 import { tracePath, readTrace, traceLine, appendTrace, agentLabel } from "../lib/trace.mjs";
 import { isAppliedContent } from "../lib/proposals.mjs";
-import { gitHead, mergeSnapshot, readDecisions, readPlanSummary, snapshotSection } from "../lib/anchor.mjs";
+import { gitHead, mergeSnapshot, readDecisions, readPlanSummary, readPlanSummaries, snapshotSection } from "../lib/anchor.mjs";
 import { contextReading, recordAgentContext } from "../lib/agent-context.mjs";
 import { parseTotals, readSummaries, sumTotals, compareTotals, deltaTotals, waiverCovers } from "../lib/test-totals.mjs";
 import { failingTestFilesFrom, nonTestTscPathsFrom, classifyFinalBlock, appendBlockLine } from "../lib/block-ledger.mjs";
 import { docsGateDecision } from "../lib/docs-gate.mjs";
+import { gateLockPath, readGateLock, pidIsLive, writeGateLock, takeOverGateLock, resolveHookTimeoutSec, lockStaleByAge, normalizedTimeoutMs, lockWaitBoundMs } from "../lib/gate-lock.mjs";
 import { resolveCommands, computeTree, readRecord, writeRecord as writeTreeRecord, removeRecord as removeTreeRecord, creditable } from "../lib/verified-tree.mjs";
 
 // Only the last this many characters of last_assistant_message are ever scanned for a partial claim
@@ -491,7 +492,24 @@ function agentMadeNoChanges(dir, cfg, sessionId, subagent) {
 // readAgentStart) and it equals the current one (same HEAD, same dirty set, same identities), and the agent's
 // final message carries no tests_red_by_design claim, and its trace shows no successful Edit-type call. Catches read-only agents that run Bash, which
 // agentMadeNoChanges counts as a change. No record, no git, any failure -> false (run the gate).
-function treeUnchangedSinceStart(dir, cfg, sessionId, subagent, input, currentFingerprint) {
+// card stop-gate-worktree-agent-fingerprint: the start record is a fingerprint of the main checkout (the trace
+// hook runs there), so for a worktree verification dir it is compared like with like instead: unchanged only if
+// the record exists, every verification dir has no changed files, and every one's HEAD carries no commit of its
+// own: it equals or is an ancestor of the record's HEAD, or of the main checkout's refs/remotes/origin/HEAD (Claude
+// Code branches a fresh isolation worktree from the remote default branch, which local main may be ahead of or
+// behind). Any git failure reads as changed. A verification set that mixes a worktree with `dir` reads as
+// changed. A main-checkout agent keeps the fingerprint comparison.
+function isAncestorIn(dir, a, b) {
+  try {
+    if (!/^[0-9a-f]{7,64}$/.test(String(a)) || !/^[0-9a-f]{7,64}$/.test(String(b))) return false;
+    execFileSync("git", ["merge-base", "--is-ancestor", a, b], { cwd: dir, stdio: "ignore", timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function treeUnchangedSinceStart(dir, cfg, sessionId, subagent, input, currentFingerprint, vdir = dir, forced = null) {
   try {
     if (!subagent || !currentFingerprint) return false;
     if (redByDesignClaim(input.last_assistant_message) ?? redByDesignClaim(lastHandbackMessage(input.agent_transcript_path))) return false;
@@ -502,6 +520,24 @@ function treeUnchangedSinceStart(dir, cfg, sessionId, subagent, input, currentFi
       if (existsSync(file) && readTrace(file).some((l) => l.agent === subagent.id && l.event === "PostToolUse" && CHANGE_TOOLS.has(l.tool) && l.ok !== false)) return false;
     }
     const start = readAgentStart(dir, sessionId, subagent.id);
+    if (vdir !== dir) {
+      if (!start || typeof start !== "object" || !start.head) return false;
+      const dirs = forced ? [vdir] : verifyDirs(dir, cfg, sessionId, input, subagent);
+      if (!dirs.includes(vdir) || dirs.includes(dir)) return false;
+      let remoteHead;
+      try {
+        remoteHead = execFileSync("git", ["rev-parse", "--verify", "-q", "refs/remotes/origin/HEAD^{commit}"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 }).trim() || null;
+      } catch {
+        remoteHead = null;
+      }
+      return dirs.every((d) => {
+        const h = headAt(d);
+        if (!h) return false;
+        if (!isAncestorIn(dir, h, start.head) && !(remoteHead && isAncestorIn(dir, h, remoteHead))) return false;
+        const c = changedFiles(d);
+        return Array.isArray(c) && c.length === 0;
+      });
+    }
     return sameTree(start, currentFingerprint);
   } catch {
     return false;
@@ -511,7 +547,8 @@ function treeUnchangedSinceStart(dir, cfg, sessionId, subagent, input, currentFi
 // card worktree-agent-gate, card worktree-gate-mixed-tree-agent: the trees a SubagentStop verifies, in
 // first-touched order. A worktree-isolated subagent edits under <dir>/.claude/worktrees/<wt>/ (input.cwd inside
 // it, or its own successful Edit-type trace lines carry absolute paths there); a path inside <dir> but outside
-// .claude/worktrees names the main checkout; any other path names nothing. The set is the cwd's worktree plus
+// .claude/worktrees names the main checkout, except <dir>/.doug/.state and anything under it (untracked state,
+// never project code) which names nothing; any other path names nothing. The set is the cwd's worktree plus
 // every tree its trace paths name (a worktree that no longer exists as a directory is skipped). Empty, a main
 // Stop, or any failure resolves to [dir]. Only the verification target varies per tree: state, trace,
 // gate.lock, the ledger, and evidence stay under `dir`. Never throws.
@@ -527,8 +564,11 @@ function verifyDirs(dir, cfg, sessionId, input, subagent) {
     };
     const inMain = (p) => {
       if (typeof p !== "string" || !isAbsolute(p)) return false;
-      const rel = relative(dir, resolve(p));
-      return !!rel && !rel.startsWith("..") && !isAbsolute(rel);
+      const abs = resolve(p);
+      const rel = relative(dir, abs);
+      if (!rel || rel.startsWith("..") || isAbsolute(rel)) return false;
+      const st = relative(join(dir, ".doug/.state"), abs);
+      return !(st === "" || (!st.startsWith("..") && !isAbsolute(st)));
     };
     const trees = [];
     const add = (t) => {
@@ -716,6 +756,7 @@ function contextNotice(dir, cfg, state, sessionId, boundary) {
     const anchorFile = join(dir, ".doug/anchor.md");
     const section = snapshotSection({
       plan: readPlanSummary(dir),
+      plans: readPlanSummaries(dir),
       decisions: readDecisions(dir),
       state,
       now: new Date(),
@@ -967,70 +1008,6 @@ function verifiedUnchangedAllow(dir, cfg, state, input, subagent, capNote) {
   return notice ? systemMessage(notice) : allow();
 }
 
-// Single-runner lock (card stop-gate-process-storm, goal 3): only one gate runs the verification commands
-// at a time per project, so concurrent SubagentStops share one suite instead of each starting its own (the
-// 2026-09-16 process storm). `.doug/.state/gate.lock` holds `{ pid, session, at }` while a gate's commands
-// run.
-const GATE_LOCK_RELPATH = ".doug/.state/gate.lock";
-function gateLockPath(dir) {
-  return join(dir, GATE_LOCK_RELPATH);
-}
-
-// Reads gate.lock, tolerating garbage (a hook reader must never throw): a missing file, unreadable file, or
-// content that fails to parse or carries no numeric pid all read as null — the same as "no lock", which the
-// caller treats exactly like a stale one.
-function readGateLock(dir) {
-  try {
-    const o = JSON.parse(readFileSync(gateLockPath(dir), "utf8"));
-    // A pid only counts when it is a positive integer (reviewer-found gap): 0 means "this process's own
-    // group" and -1 broadcasts to every process the caller may signal, so process.kill(pid, 0) does not
-    // throw for either and a liveness check that hands them straight to it reads a garbage lock as live.
-    return o && typeof o === "object" && Number.isInteger(o.pid) && o.pid > 0 ? o : null;
-  } catch {
-    return null;
-  }
-}
-
-function pidIsLive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    // EPERM means the pid exists but is owned by another user (permission denied, not "no such process") —
-    // that holder is still alive, just not signallable by us. Every other error (ESRCH: no such process, or
-    // anything else) reads as dead.
-    return err && err.code === "EPERM";
-  }
-}
-
-// Creates gate.lock exclusively (throws EEXIST when one is already there, or any other fs error). The
-// caller decides what a failure means.
-function writeGateLock(dir, sessionId) {
-  mkdirSync(join(dir, ".doug/.state"), { recursive: true });
-  writeFileSync(gateLockPath(dir), JSON.stringify({ pid: process.pid, session: sessionId, at: Date.now() }), { flag: "wx" });
-}
-
-// Overwrites gate.lock with this gate's own pid/session, whether it was stale (a dead pid) or its holder
-// simply never let go inside the wait bound — either way, never lets a lock the gate cannot even write hang
-// it (best-effort; a failure here just leaves lockOwned false to the caller, which never releases a lock it
-// does not hold).
-function takeOverGateLock(dir, sessionId) {
-  try {
-    mkdirSync(join(dir, ".doug/.state"), { recursive: true });
-    writeFileSync(gateLockPath(dir), JSON.stringify({ pid: process.pid, session: sessionId, at: Date.now() }));
-  } catch {
-    // best-effort takeover only
-  }
-}
-
-// Card stop-gate-budget-under-hook-timeout: cfg.stopGate.hookTimeoutSec must equal the platform's own
-// Stop/SubagentStop hook `timeout` (hooks.json/settings.json), but a hook reader never throws (F6), so a
-// missing, non-number, or non-positive value reads as the platform's own default, 600.
-function resolveHookTimeoutSec(cfg) {
-  const sec = cfg && cfg.stopGate && cfg.stopGate.hookTimeoutSec;
-  return typeof sec === "number" && Number.isFinite(sec) && sec > 0 ? sec : 600;
-}
-
 // Computed once per gate run: the wall-clock instant past which the platform itself would cancel this
 // hook (F1 — a timed-out hook is killed, fails open, and its output, including a block message, is
 // discarded), less a margin so the gate's own block reaches Claude Code before that happens. gateStart
@@ -1049,26 +1026,8 @@ function gateBudget(cfg, inherited) {
   return { hookTimeoutSec, hookTimeoutMs, deadline };
 }
 
-// A lock whose numeric `at` is older than the hook-timeout budget is stale regardless of a live pid: no
-// legitimate holder can still be running that long, since the platform itself would have killed its hook
-// by then (F1). A missing or non-numeric `at` changes nothing here; the pid liveness check still decides.
-function lockStaleByAge(lock, hookTimeoutMs) {
-  return !!lock && typeof lock.at === "number" && Number.isFinite(lock.at) && Date.now() - lock.at > hookTimeoutMs;
-}
-
-// Card stop-gate-timeout-normalise: cfg.stopGate.timeoutMs normalised once, shared by the per-command timeout
-// and the wait bound below, so the two never disagree on what a garbage or fractional value means. A finite
-// number above 0 floors to an integer, clamped up to at least 1ms (0.5 must not floor to 0 — spawnSync reads a
-// timeout of 0 as none at all, letting a command run past the budget unclamped; 2.5 must not reach spawnSync
-// un-floored — it throws ERR_OUT_OF_RANGE there, and a hook reader must never throw, F6). Anything else
-// (non-number, NaN, Infinity, 0, negative, null) is "unset" (null), read by each call site as its own default.
-function normalizedTimeoutMs(cfg) {
-  const t = cfg.stopGate.timeoutMs;
-  return typeof t === "number" && Number.isFinite(t) && t > 0 ? Math.max(1, Math.floor(t)) : null;
-}
-
 // Card stop-gate-deferral-cap (R2): cfg.stopGate.maxDeferrals normalised the same shape as
-// normalizedTimeoutMs above — a hook reader must never throw (F6/F10), so a finite number >= 1 is floored
+// normalizedTimeoutMs (lib/gate-lock.mjs) — a hook reader must never throw (F6/F10), so a finite number >= 1 is floored
 // and used; anything else (missing, 0, negative, NaN, a string, null, an object) reads as the default, 10.
 function normalizedMaxDeferrals(cfg) {
   const m = cfg && cfg.stopGate && cfg.stopGate.maxDeferrals;
@@ -1085,10 +1044,99 @@ function normalizedDeferrals(state) {
   return typeof d === "number" && Number.isFinite(d) && d >= 0 ? Math.floor(d) : 0;
 }
 
+// Card landing-block-enforced: board.mjs record/summary leave .doug/.state/reports/<id>/landing-block.txt and an
+// empty landing-block.pending (move <id> done re-arms it). A main Stop that would otherwise allow checks each
+// pending block against the lead's final message and blocks, once, until every line of it is there verbatim. The
+// marker is deleted the first time it is checked, so the block happens at most once per landing. Every exit that
+// lets a main Stop end plainly goes through allow() below. The systemMessage exits (the block-cap and turn-budget
+// stand-downs, the deferral notice, the repeat-deferral exit) return their text unchanged and never block (card
+// landing-block-shown-on-deferral): systemMessage() below first sweeps quietly, deleting a marker whose lines are
+// all in the final message and leaving any other, so a block printed on a deferral stop is not demanded again at
+// a later plain stop. A red gate (blockStop) keeps its own reason. A marker holds the session that landed (empty =
+// any); another session's marker is left untouched. Fails open: any throw, an unreadable block
+// file, or a final message that is not a string allows with one stderr line.
+let landingInput = null;
+// The pending markers this session owns, as [id, root] pairs; null when there is no reports directory.
+function ownedLandingMarkers(input) {
+  const root = join(projectDir(input), ".doug/.state/reports");
+  if (!existsSync(root)) return { root, pending: [] };
+  const mine = (id) => {
+    try {
+      const owner = readFileSync(join(root, id, "landing-block.pending"), "utf8").trim();
+      return owner === "" || owner === input.session_id;
+    } catch {
+      return false;
+    }
+  };
+  return { root, pending: readdirSync(root).filter((id) => existsSync(join(root, id, "landing-block.pending")) && mine(id)).sort() };
+}
+function landingBlockLines(root, id) {
+  return readFileSync(join(root, id, "landing-block.txt"), "utf8").split("\n").map((l) => l.trim()).filter(Boolean);
+}
+function landingBlockReason(input) {
+  try {
+    const { root, pending } = ownedLandingMarkers(input);
+    if (!pending.length) return null;
+    const message = input.last_assistant_message;
+    if (typeof message !== "string") {
+      // The markers stay, so a later Stop with a readable final message still checks them.
+      process.stderr.write("[doug] landing-block check skipped: the final message is unreadable\n");
+      return null;
+    }
+    const missing = [];
+    for (const id of pending) {
+      const marker = join(root, id, "landing-block.pending");
+      try {
+        const lines = landingBlockLines(root, id);
+        if (lines.length && !lines.every((l) => message.includes(l))) missing.push({ id, lines });
+      } catch (e) {
+        process.stderr.write(`[doug] landing-block check skipped: ${id}: ${e && e.message ? e.message : String(e)}\n`);
+      }
+      try {
+        unlinkSync(marker);
+      } catch {}
+    }
+    if (!missing.length) return null;
+    return missing.map((m) => `Landing block missing from your final message for ${m.id}. Paste these lines verbatim:\n${m.lines.join("\n")}`).join("\n\n");
+  } catch (e) {
+    process.stderr.write(`[doug] landing-block check skipped: ${e && e.message ? e.message : String(e)}\n`);
+    return null;
+  }
+}
+// Quiet sweep for the systemMessage exits: delete each owned marker whose lines are all in the final message,
+// keep the rest. Never blocks, never changes the exit's text.
+function sweepLandingMarkers(input) {
+  try {
+    const message = input.last_assistant_message;
+    if (typeof message !== "string") return;
+    const { root, pending } = ownedLandingMarkers(input);
+    for (const id of pending) {
+      try {
+        const lines = landingBlockLines(root, id);
+        if (lines.length && lines.every((l) => message.includes(l))) unlinkSync(join(root, id, "landing-block.pending"));
+      } catch (e) {
+        process.stderr.write(`[doug] landing-block check skipped: ${id}: ${e && e.message ? e.message : String(e)}\n`);
+      }
+    }
+  } catch (e) {
+    process.stderr.write(`[doug] landing-block check skipped: ${e && e.message ? e.message : String(e)}\n`);
+  }
+}
+function systemMessage(message) {
+  if (landingInput) sweepLandingMarkers(landingInput);
+  return systemMessageRaw(message);
+}
+function allow() {
+  const reason = landingInput ? landingBlockReason(landingInput) : null;
+  if (reason) return blockStop(reason);
+  return allowRaw();
+}
+
 const READ_ONLY_LINE = "[doug] Read-only turn: verification skipped; the working tree holds unverified changes from other agents.";
 
 runHook("stop-gate", async (input) => {
-  if (input.stop_hook_active) return allow();
+  if (input.stop_hook_active) return allowRaw();
+  if (input.hook_event_name !== "SubagentStop") landingInput = input;
   const dir = projectDir(input);
   const cfg = loadConfig(dir);
   let state = loadState(dir, input.session_id);
@@ -1471,8 +1519,8 @@ runHook("stop-gate", async (input) => {
     // Draft and rejected plans are not contracts yet, so they are ignored.
     let scope = null;
     if (Array.isArray(changed) && cfg.stopGate.planScope !== false) {
-      const { plan, reason, error } = loadScopePlan(dir);
-      if (reason === "unreadable") process.stderr.write(`[doug] ${PLAN_RELPATH} is unreadable (${error}); scope not checked\n`);
+      const { plan, reason, error, file } = loadScopePlan(dir);
+      if (reason === "unreadable") process.stderr.write(`[doug] ${file || PLAN_RELPATH} is unreadable (${error}); scope not checked\n`);
       if (plan) {
         const violations = scopeViolations(changed, plan, { ignore: cfg.stopGate.ignoreChangedPaths || [] });
         scope = { plan: plan.title, status: plan.status, outOfScope: violations.map((v) => v.file) };
@@ -1526,7 +1574,10 @@ runHook("stop-gate", async (input) => {
         state.deferrals = n;
         state.lastDeferral = { ids, fingerprint: currentFingerprint };
         saveState(dir, input.session_id, state);
-        if (repeat) return allow();
+        if (repeat) {
+          if (landingInput) sweepLandingMarkers(landingInput);
+          return allowRaw();
+        }
         return systemMessage(
           `[doug] Verification deferred: waits for ${names} to stop; the full gate runs at the first Stop after they stop.`,
         );
@@ -1575,7 +1626,7 @@ runHook("stop-gate", async (input) => {
   };
   const skipReason = subagent && agentMadeNoChanges(dir, cfg, input.session_id, subagent)
     ? "no-agent-changes"
-    : subagent && treeUnchangedSinceStart(dir, cfg, input.session_id, subagent, input, currentFingerprint)
+    : subagent && treeUnchangedSinceStart(dir, cfg, input.session_id, subagent, input, currentFingerprint, vdir, forced)
       ? "tree-unchanged"
       : readOnlyTurn
         ? "read-only-turn"
@@ -1665,7 +1716,7 @@ runHook("stop-gate", async (input) => {
 
   // card stop-gate-process-storm, case 3: only one gate runs the verification commands at a time per
   // project (the 2026-09-16 process storm: four concurrent SubagentStops each ran the full suite, each
-  // 300s timeout orphaning ten vitest workers). A gate holds .doug/.state/gate.lock while its commands run;
+  // 300s timeout orphaning ten vitest workers). A gate holds gate.lock (gateLockPath: under the git common dir) while its commands run;
   // a second gate that finds a live lock waits for it, bounded by stopGate.timeoutMs, then reloads state and
   // reapplies the skip above — the holder's own green run may have just recorded the very `verified` tree
   // this gate needs, letting it skip instead of also running the full suite.
@@ -1709,7 +1760,7 @@ runHook("stop-gate", async (input) => {
           // timeoutMs no longer defaults to a flat 300000ms here — the budget deadline below is the real bound
           // either way, so an unset value waits only for what remains of it, unmultiplied.
           const normalizedTimeout = normalizedTimeoutMs(cfg);
-          const waitBoundMs = normalizedTimeout !== null ? normalizedTimeout * Math.max(1, resolveCommands(cfg).length) : budgetDeadline - Date.now();
+          const waitBoundMs = normalizedTimeout !== null ? lockWaitBoundMs(normalizedTimeout, resolveCommands(cfg).length) : budgetDeadline - Date.now();
           const waitDeadline = Date.now() + waitBoundMs;
           // Card stop-gate-budget-under-hook-timeout: waitDeadline alone can outrun the platform's own hook
           // timeout (F1), so a waiter also stops at budgetDeadline — but there it refuses the stop instead of

package/node_modules/@dougharness/gates/scripts/verify.mjs

@@ -4,11 +4,13 @@
 //   node .doug/hooks/scripts/verify.mjs [--no-credit] [--json] [--dir <project>] [--cwd <tree dir>] [--timeout-ms <n>]
 //     [--record-dir <dir>] [--credit-dir <dir>]... [--by <writer>] [--command <cmd>]...
 // Exit: 0 all green or credited; 1 any command failed or timed out; 2 usage error or no commands.
-// No count ratchet and no scans here (no session baseline); the Stop gate does those. Takes no gate.lock.
+// No count ratchet and no scans here (no session baseline); the Stop gate does those. Takes the Stop gate's gate.lock (under the git common dir, shared by every worktree) around the commands (card verify-takes-gate-lock).
 
 import { spawnSync } from "node:child_process";
+import { unlinkSync } from "node:fs";
 import { resolve } from "node:path";
 import { loadConfig } from "../lib/config.mjs";
+import { gateLockPath, readGateLock, pidIsLive, writeGateLock, takeOverGateLock, resolveHookTimeoutSec, lockStaleByAge, normalizedTimeoutMs, lockWaitBoundMs } from "../lib/gate-lock.mjs";
 import { runCommand, tail } from "../lib/run.mjs";
 import { parseTotals, readSummaries, sumTotals } from "../lib/test-totals.mjs";
 import { computeTree, readRecord, writeRecord, removeRecord, creditable, resolveCommands } from "../lib/verified-tree.mjs";
@@ -75,8 +77,11 @@ function main() {
     process.stderr.write("[doug] verify: no commands (stopGate.commands is empty and no --command given)\n");
     return 2;
   }
-  const treeBefore = computeTree(cwd);
+  let treeBefore = computeTree(cwd);
+  let lockWaitMs = 0;
 
+  // Credits a verified-tree record of the same tree when one exists; returns the exit code, or null.
+  const tryCredit = () => {
   if (!o.noCredit && treeBefore) {
     const wanted = commands.map((c) => c.command);
     let record = null;
@@ -94,7 +99,7 @@ function main() {
       const entries = record.commands.map((c) => ({ name: c.name, exit: c.exit, passed: passed(record.totals[c.command]) }));
       if (o.json) {
         const results = record.commands.map((c) => ({ name: c.name, command: c.command, ok: true, status: c.exit, timedOut: false, durationMs: c.durationMs, outputTail: "" }));
-        process.stdout.write(JSON.stringify({ ok: true, credited: "verified-tree", tree: treeBefore, record, results }) + "\n");
+        process.stdout.write(JSON.stringify({ ok: true, credited: "verified-tree", tree: treeBefore, record, results, lockWaitMs }) + "\n");
       } else {
         process.stdout.write(`[doug] verify: credited verified-tree record (tree ${treeBefore.slice(0, 7)}, by ${record.by || "unknown"}, ${record.at}, node ${record.node}); commands not re-run. --no-credit runs them.\n`);
         process.stdout.write(gateLine(entries) + "\n");
@@ -102,8 +107,62 @@ function main() {
       return 0;
     }
   }
+  return null;
+  };
+  const first = tryCredit();
+  if (first !== null) return first;
 
-  const timeoutMs = o.timeoutMs ? o.timeoutMs : Number.isInteger(cfg.stopGate && cfg.stopGate.timeoutMs) && cfg.stopGate.timeoutMs > 0 ? cfg.stopGate.timeoutMs : 600000;
+  const timeoutMs = o.timeoutMs ? o.timeoutMs : (cfg.stopGate && normalizedTimeoutMs(cfg)) ?? 600000;
+  const waitBoundMs = lockWaitBoundMs(timeoutMs, commands.length);
+
+  // Card verify-takes-gate-lock: one full suite at a time per checkout, the same gate.lock the Stop gate takes
+  // (lib/gate-lock.mjs). A live holder is waited on for up to timeoutMs x command count (the Stop gate's bound), then the record is re-checked (the
+  // holder's green run may have just written it); a lock still held after the bound is taken over and the
+  // commands run. Released only by the exit handler below, so every return path (green, red, throw) frees it.
+  let lockOwned = false;
+  process.on("exit", () => {
+    try {
+      if (!lockOwned) return;
+      const lock = readGateLock(dir);
+      if (lock && lock.pid === process.pid) unlinkSync(gateLockPath(dir));
+    } catch {
+      // never throw from an exit handler
+    }
+  });
+  try {
+    writeGateLock(dir, o.by || "verify");
+    lockOwned = true;
+  } catch (err) {
+    if (!err || err.code !== "EEXIST") {
+      lockOwned = false; // an unwritable .doug/.state: run unlocked rather than hang
+    } else {
+      const hookTimeoutMs = resolveHookTimeoutSec(cfg) * 1000;
+      const stale = (l) => !l || !pidIsLive(l.pid) || lockStaleByAge(l, hookTimeoutMs);
+      const held = readGateLock(dir);
+      if (stale(held)) {
+        takeOverGateLock(dir, o.by || "verify");
+        lockOwned = true;
+      } else {
+        const waitStart = Date.now();
+        const deadline = waitStart + waitBoundMs;
+        let live = held;
+        const nap = new Int32Array(new SharedArrayBuffer(4));
+        while (true) {
+          live = readGateLock(dir);
+          if (stale(live) || Date.now() >= deadline) break;
+          Atomics.wait(nap, 0, 0, 200);
+        }
+        lockWaitMs = Date.now() - waitStart;
+        if (!o.json && lockWaitMs > 0) process.stdout.write(`[doug] verify: waited ${lockWaitMs} ms on gate.lock\n`);
+        treeBefore = computeTree(cwd);
+        const again = tryCredit();
+        if (again !== null) return again;
+        if (!stale(live)) process.stderr.write(`[doug] verify: gate.lock still held by pid ${live.pid} after ${waitBoundMs} ms; running the commands anyway.\n`);
+        takeOverGateLock(dir, o.by || "verify");
+        lockOwned = true;
+      }
+    }
+  }
   const results = [];
   const recCommands = [];
   const totals = {};
@@ -131,7 +190,7 @@ function main() {
   } else {
     removeRecord(recordDir);
   }
-  if (o.json) process.stdout.write(JSON.stringify({ ok, credited: null, tree: treeBefore, record: null, results }) + "\n");
+  if (o.json) process.stdout.write(JSON.stringify({ ok, credited: null, tree: treeBefore, record: null, results, lockWaitMs }) + "\n");
   else process.stdout.write(gateLine(entries) + "\n");
   return ok ? 0 : 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dougharness/cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "doug: tailored, approval-gated harness install for Claude Code.",
   "type": "module",
   "license": "MIT",
@@ -13,7 +13,7 @@
     "access": "public"
   },
   "bin": {
-    "doug": "./dist/bin.js"
+    "doug": "dist/bin.js"
   },
   "files": [
     "dist",
@@ -23,8 +23,8 @@
     "node": ">=22.16"
   },
   "dependencies": {
-    "@dougharness/flow": "1.1.0",
-    "@dougharness/gates": "1.1.0"
+    "@dougharness/flow": "1.2.0",
+    "@dougharness/gates": "1.2.0"
   },
   "bundleDependencies": [
     "@dougharness/flow",

package/templates/board-app.js

@@ -45,6 +45,15 @@ details{margin-top:6px}summary{font-size:12px;color:var(--accent);cursor:pointer
 .move{margin-top:8px;display:flex;gap:6px;align-items:center}.move select{font-size:12px;padding:3px 6px}
 .ro .card{cursor:default}.ro .move{display:none}
 footer{padding:0 24px 24px;font-size:12px;color:var(--ink-soft)}
+#autopilot{margin:14px 24px 0;padding:10px 14px;background:var(--surface);border:1px solid var(--rule-strong)}
+#autopilot[hidden]{display:none}
+#autopilot h2{font-family:"IBM Plex Mono",Menlo,monospace;font-size:12px;letter-spacing:.06em;text-transform:uppercase;font-weight:500;margin:0 0 6px}
+#autopilot ul{list-style:none;margin:4px 0;padding:0;font-size:13px}
+#autopilot li{display:flex;gap:8px;flex-wrap:wrap;align-items:baseline}
+#autopilot .st{font-family:"IBM Plex Mono",Menlo,monospace;font-size:11px;text-transform:uppercase;color:var(--ink-soft);min-width:5.5em}
+#autopilot .st.running{color:var(--accent);font-weight:600}
+#autopilot .st.stopped,#autopilot .st.interrupted{color:var(--c-decision)}
+#autopilot .caps,#autopilot .filed{font-size:12px;color:var(--ink-soft);margin-top:4px}
 @media (max-width:720px){.board{grid-auto-columns:minmax(85vw,1fr)}}
 `;
 
@@ -163,6 +172,12 @@ function connectLive(opts) {
       if (source !== es) return;
       opts.onBoard(JSON.parse(e.data));
     });
+    es.addEventListener("autopilot", (e) => {
+      if (source !== es || !opts.onAutopilot) return;
+      let view = null;
+      try { view = JSON.parse(e.data); } catch (_) {}
+      opts.onAutopilot(view);
+    });
   }
   open();
 
@@ -246,6 +261,33 @@ function cardMatches(card, filters) {
   return true;
 }
 
+// The autopilot panel's inner HTML for a view from GET /api/autopilot (lib/autopilot-view.mjs autopilotView);
+// "" for no view, which leaves the panel hidden.
+function autopilotHtml(view) {
+  if (!view || typeof view !== "object") return "";
+  const cards = Array.isArray(view.cards) ? view.cards : [];
+  const filed = Array.isArray(view.filed) ? view.filed : [];
+  const caps = view.caps || {};
+  const items = cards.map((c) => {
+    const shape = [c.size, c.class].filter(Boolean).join("/");
+    return `<li><span class="st ${esc(c.state)}">${esc(c.state)}</span><code>${esc(c.id)}</code>${c.title ? `<span>${esc(c.title)}</span>` : ""}${shape ? `<span class="meta">${esc(shape)}</span>` : ""}${c.detail ? `<span class="meta">${esc(c.detail)}</span>` : ""}</li>`;
+  }).join("");
+  const filedHtml = filed.length
+    ? `<div class="filed">filed: ${filed.map((f) => `<code>${esc(f.id)}</code> (${esc(f.kind)}${f.from ? " from " + esc(f.from) : ""}) ${esc(f.position || "")}`).join("; ")}</div>`
+    : "";
+  return `<h2>${esc(view.header || "Autopilot")}</h2><ul>${items}</ul><div class="caps">usd ${esc(caps.usd || "")} · wall ${esc(caps.wall || "")} · context ${esc(caps.context || "")}</div>${filedHtml}`;
+}
+
+// Shows a view in the #autopilot container, or hides the container for none.
+function applyAutopilot(view, doc) {
+  doc = doc !== undefined ? doc : (typeof document !== "undefined" ? document : null);
+  const el = doc && doc.getElementById("autopilot");
+  if (!el) return;
+  const html = autopilotHtml(view);
+  el.innerHTML = html;
+  el.hidden = html === "";
+}
+
 // The complete document for a given board state; `doug board serve` renders it from the record on
 // every request.
 function renderDoc(board, appSource, config) {
@@ -265,6 +307,7 @@ ${tagFilter ? tagFilter + "\n" : ""}<span class="status" id="filter-note"></span
 <span class="status" id="status"></span>
 </div>
 </header>
+<section id="autopilot" aria-label="Autopilot" hidden></section>
 <main class="board" id="board">
 ${board.columns.map((col) => columnHtml(col, board.cards, board.columns)).join("\n")}
 </main>
@@ -339,7 +382,8 @@ function app() {
       });
       if (res.status === 200) {
         board = await res.json();
-        say("Saved to " + config.record + ".");
+        const warning = res.headers.get("x-doug-warning");
+        say("Saved to " + config.record + "." + (warning ? " " + warning : ""));
       } else {
         let message = "The move was rejected (" + res.status + ").";
         try { const body = await res.json(); if (body && body.error) message = body.error; } catch (_) {}
@@ -508,6 +552,8 @@ function app() {
       readOnly = false;
       document.body.classList.remove("ro");
       say("");
+      // The autopilot panel: the run's view now, then live over the same event stream.
+      fetch("/api/autopilot").then((r) => (r && r.status === 200 ? r.json() : null)).then((view) => applyAutopilot(view)).catch(() => {});
       // Once served, follow the record live: another writer's move (or this tab's own, echoed
       // back) re-renders in place, or reloads when the columns or filters themselves changed.
       connectLive({
@@ -515,6 +561,7 @@ function app() {
         url: "/api/events",
         setTimeout: window.setTimeout.bind(window),
         clearTimeout: window.clearTimeout.bind(window),
+        onAutopilot: (view) => applyAutopilot(view),
         onBoard: (next) => {
           const updated = applyLiveBoard(board, next, config);
           if (updated) {