@dougharness/cli 1.1.0 → 1.2.0

package/node_modules/@dougharness/gates/lib/gate-lock.mjs

@@ -0,0 +1,126 @@
+// The gate.lock helpers shared by the Stop gate (scripts/stop-gate.mjs) and verify.mjs (card
+// verify-takes-gate-lock). Moved verbatim from stop-gate.mjs; the Stop gate's behaviour is unchanged.
+
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+
+// 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). gate.lock holds `{ pid, session, at }` while a gate's commands run. Card
+// gate-lock-shared (ADR 0015): it lives at `<git common dir>/doug/gate.lock`, a path every worktree of the
+// repo shares, so gates in parallel worktrees queue instead of running full suites concurrently. It falls
+// back to the per-checkout `.doug/.state/gate.lock` when git is unavailable, `dir` is not in a repo, or the
+// common dir is not writable; resolution never throws.
+const GATE_LOCK_RELPATH = ".doug/.state/gate.lock";
+// Memoized per dir for the life of the process (a fallback result too): one gate run must see one path,
+// or a poll that fell back under load would read no lock and take over a live holder's shared lock.
+const lockPathMemo = new Map();
+export function gateLockPath(dir) {
+  if (lockPathMemo.has(dir)) return lockPathMemo.get(dir);
+  const p = resolveGateLockPath(dir);
+  lockPathMemo.set(dir, p);
+  return p;
+}
+function resolveGateLockPath(dir) {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
+      cwd: dir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    }).trim();
+    if (out) {
+      const common = resolve(dir, out);
+      const lockDir = join(common, "doug");
+      accessSync(common, constants.W_OK);
+      if (existsSync(lockDir)) accessSync(lockDir, constants.W_OK);
+      return join(lockDir, "gate.lock");
+    }
+  } catch {
+    // fall through to the per-checkout path
+  }
+  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.
+export 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;
+  }
+}
+
+export 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.
+export function writeGateLock(dir, sessionId) {
+  const p = gateLockPath(dir);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, 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).
+export function takeOverGateLock(dir, sessionId) {
+  try {
+    const p = gateLockPath(dir);
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, 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.
+export function resolveHookTimeoutSec(cfg) {
+  const sec = cfg && cfg.stopGate && cfg.stopGate.hookTimeoutSec;
+  return typeof sec === "number" && Number.isFinite(sec) && sec > 0 ? sec : 600;
+}
+
+// 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.
+export function lockStaleByAge(lock, hookTimeoutMs) {
+  return !!lock && typeof lock.at === "number" && Number.isFinite(lock.at) && Date.now() - lock.at > hookTimeoutMs;
+}
+
+// Card stop-gate-timeout-normalise (moved here by card verify-lock-wait-bound so verify.mjs shares it):
+// cfg.stopGate.timeoutMs normalised once, shared by the per-command timeout and the wait bound, 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.
+export function normalizedTimeoutMs(cfg) {
+  const t = cfg.stopGate.timeoutMs;
+  return typeof t === "number" && Number.isFinite(t) && t > 0 ? Math.max(1, Math.floor(t)) : null;
+}
+
+// How long a gate waits on a live gate.lock: the per-command timeout times the command count, the longest a
+// holder legitimately runs.
+export function lockWaitBoundMs(perCommandMs, commandCount) {
+  return perCommandMs * Math.max(1, commandCount);
+}

package/node_modules/@dougharness/gates/lib/proposals.mjs

@@ -37,6 +37,11 @@ const MAX_VERIFIED_ROWS = 20;
 // Every spawned git call gets a hard ceiling (ms) so a hung or adversarially slow git invocation cannot itself
 // become the way to blow the Stop-gate timeout (review MINOR 7).
 const GIT_TIMEOUT_MS = 5000;
+// Most commits (newest first) that touched a target since the session baseline whose parent is tried as a
+// re-derivation ref (card ledger-two-committed-applies): a bound, so a long session cannot make the walk costly.
+const MAX_PARENT_REFS = 10;
+// A git commit sha, abbreviated or full (same shape lib/baseline.mjs accepts for baselineHead).
+const GIT_SHA_RE = /^[0-9a-f]{7,64}$/;
 
 // Every well-formed line, tolerant of a missing file or a torn line (a crashed process mid-write) - never fatal.
 export function readAppliedLedger(dir) {
@@ -139,18 +144,48 @@ function diffAppliesAtRef(dir, relPath, diffAbsPath, currentSha, ref) {
   }
 }
 
+// The parents of the commits since `base` that touched relPath, newest first, capped at MAX_PARENT_REFS: each
+// `<commit>^` holds relPath as it was just before that commit, which is where an in-session apply's preimage
+// lives once a later apply is also committed (card ledger-two-committed-applies). Empty when `base` is not a
+// usable sha, or the git call fails or times out (GIT_TIMEOUT_MS); never throws.
+function parentRefsSince(dir, relPath, base) {
+  try {
+    const listed = spawnSync("git", ["rev-list", `--max-count=${MAX_PARENT_REFS}`, `${base}..HEAD`, "--", relPath], {
+      cwd: dir,
+      timeout: GIT_TIMEOUT_MS,
+      encoding: "utf8",
+    });
+    if (listed.status !== 0 || typeof listed.stdout !== "string") return [];
+    return listed.stdout
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => /^[0-9a-f]{7,64}$/.test(line))
+      .map((sha) => `${sha}^`);
+  } catch {
+    return [];
+  }
+}
+
 // `base` (card stop-scan-committed-changes) is the session's baseline HEAD when known, tried first: a diff
 // that created `relPath` after that baseline still applies onto "absent" even once the session has since
 // committed `relPath` itself (HEAD would otherwise already equal the current bytes, and git apply refuses to
 // create a file that already exists there). M1 fix: when the base attempt fails, HEAD is also tried before
 // giving up, not only when `base` is null/omitted - a second approved apply on the same target, committed
 // in-session after the first (so its preimage is the first version, not the pre-session base), re-derives
-// correctly onto HEAD even though it cannot re-derive onto the pre-session base at all. Every other check
+// correctly onto HEAD even though it cannot re-derive onto the pre-session base at all. Card
+// ledger-two-committed-applies: once two or more applies on one target are committed in-session, the earlier
+// ones' preimage is neither the base nor HEAD; when both fail and `base` is known, the parent of each commit
+// since `base` that touched `relPath` (parentRefsSince, newest first, capped) is tried too. Every other check
 // (row shape, containment, diffSha256, diffNamesOnly) is unchanged; this only widens which ref the content
 // re-derivation itself is allowed to succeed against.
 function diffReproducesCurrentContent(dir, relPath, diffAbsPath, currentSha, base) {
-  const refs = typeof base === "string" && base && base !== "HEAD" ? [base, "HEAD"] : ["HEAD"];
-  return refs.some((ref) => diffAppliesAtRef(dir, relPath, diffAbsPath, currentSha, ref));
+  // `base` is agent-writable state (state.baselineHead): only a hex sha ever reaches git, so a value such as
+  // "--output=<path>" is dropped here and can neither be read as an option nor name a revision.
+  const hasBase = typeof base === "string" && GIT_SHA_RE.test(base);
+  const refs = hasBase ? [base, "HEAD"] : ["HEAD"];
+  if (refs.some((ref) => diffAppliesAtRef(dir, relPath, diffAbsPath, currentSha, ref))) return true;
+  if (!hasBase) return false;
+  return parentRefsSince(dir, relPath, base).some((ref) => diffAppliesAtRef(dir, relPath, diffAbsPath, currentSha, ref));
 }
 
 // One row's full verification, wrapped so that no exception - a malformed field of any type, an unreadable
@@ -182,8 +217,9 @@ function rowIsGenuine(dir, relPath, sha, learnDirAbs, row, base) {
 // before the session started, not only against HEAD (which, once the target is committed, already equals the
 // current bytes and would make a new-file diff fail to apply there). HEAD is always tried too (M1 review
 // fix) - a second approved apply on the same target, committed in-session after the first, has the first
-// version as its preimage and can only re-derive onto HEAD, not onto the pre-session base. With `base` null
-// or omitted, only HEAD is tried, exactly as before this card.
+// version as its preimage and can only re-derive onto HEAD, not onto the pre-session base. With several applies
+// committed in-session (card ledger-two-committed-applies), the parent of each commit since `base` that touched
+// the target is tried as well. With `base` null or omitted, only HEAD is tried, exactly as before this card.
 export function isAppliedContent(dir, relPath, { base = null } = {}) {
   const sha = currentSha256(dir, relPath);
   const learnDirAbs = resolve(dir, LEARN_STATE_RELPATH);

package/node_modules/@dougharness/gates/lib/scope.mjs

@@ -2,7 +2,7 @@
 // the files its tasks own is the only thing a session may change.
 // Pure functions plus one reader; the stop gate decides, this file only computes.
 
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { globToRegExp, matchAny, normalizePath } from "./glob.mjs";
 
@@ -10,18 +10,56 @@ export const PLAN_RELPATH = ".doug/plan.json";
 export const ENFORCED_STATUSES = ["approved", "done"];
 // The flow's own files change during a run and are never out of scope. Per-session hook state too.
 // board.json moves uncommitted with the live board server; it lands in the card's landing commit.
-export const ALWAYS_ALLOWED = [".doug/plan.json", ".doug/anchor.md", ".doug/.state/**", ".doug/board.json"];
+export const ALWAYS_ALLOWED = [".doug/plan.json", ".doug/plans/**", ".doug/anchor.md", ".doug/.state/**", ".doug/board.json"];
 
 // Returns { plan, reason }. plan is set only when the file exists, parses, has tasks, and is in an
 // enforced status; reason says why not otherwise ("no-plan", "unreadable", "status:draft", "invalid").
 export function loadScopePlan(dir) {
+  const single = loadSinglePlan(dir);
+  if (single.plan) return single;
+  // card parallel-card-queens: with no enforced .doug/plan.json, the enforced, not-landed per-card plans
+  // under .doug/plans/ hold scope together.
+  const cards = loadCardPlans(dir);
+  if (cards.plan || cards.reason === "unreadable") return cards;
+  return single;
+}
+
+// Union of every approved/done, not-landed .doug/plans/*.json. Never throws: an unreadable file is skipped,
+// and reported as reason "unreadable" only when it leaves no plan holding scope.
+function loadCardPlans(dir) {
+  let names = [];
+  try {
+    names = readdirSync(join(dir, ".doug/plans")).filter((f) => f.endsWith(".json")).sort();
+  } catch {
+    return { plan: null, reason: "no-plan" };
+  }
+  const plans = [];
+  for (const name of names) {
+    try {
+      const p = JSON.parse(readFileSync(join(dir, ".doug/plans", name), "utf8"));
+      if (!p || typeof p !== "object" || !Array.isArray(p.tasks)) continue;
+      if (!ENFORCED_STATUSES.includes(p.status) || p.landed) continue;
+      plans.push(p);
+    } catch (err) {
+      // fail open: any unreadable per-card file means the union is unknown, so scope is not checked
+      return { plan: null, reason: "unreadable", error: String(err && err.message), file: `.doug/plans/${name}` };
+    }
+  }
+  if (!plans.length) return { plan: null, reason: "no-plan" };
+  const status = plans.some((p) => p.status === "approved") ? "approved" : "done";
+  const cards = plans.map((p) => p.card || p.title || "?");
+  const title = `per-card plans (${cards.join(", ")})`;
+  return { plan: { version: 1, title, status, perCard: cards, tasks: plans.flatMap((p) => p.tasks) }, reason: null };
+}
+
+function loadSinglePlan(dir) {
   const file = join(dir, PLAN_RELPATH);
   if (!existsSync(file)) return { plan: null, reason: "no-plan" };
   let plan;
   try {
     plan = JSON.parse(readFileSync(file, "utf8"));
   } catch (err) {
-    return { plan: null, reason: "unreadable", error: String(err.message) };
+    return { plan: null, reason: "unreadable", error: String(err.message), file: PLAN_RELPATH };
   }
   if (!plan || typeof plan !== "object" || !Array.isArray(plan.tasks)) return { plan: null, reason: "invalid" };
   if (!ENFORCED_STATUSES.includes(plan.status)) return { plan: null, reason: `status:${plan.status}` };
@@ -104,7 +142,8 @@ export function scopeViolations(changed, plan, { ignore = [] } = {}) {
 }
 
 export function describeViolations(violations, plan) {
-  const lines = [`Files changed outside the ${plan.status} plan "${plan.title}" (${PLAN_RELPATH}):`];
+  const source = Array.isArray(plan.perCard) ? `per-card plans ${plan.perCard.join(", ")} (.doug/plans/)` : `plan "${plan.title}" (${PLAN_RELPATH})`;
+  const lines = [`Files changed outside the ${plan.status} ${source}:`];
   for (const v of violations) {
     const near = v.nearest.length ? `nearest task${v.nearest.length > 1 ? "s" : ""}: ${v.nearest.map((n) => `${n.id} (owns ${n.via})`).join(", ")}` : "no task owns anything near it";
     lines.push(`  ${v.file}  ${near}`);

package/node_modules/@dougharness/gates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dougharness/gates",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "private": true,
   "description": "Deterministic Claude Code hooks: protected paths, bash guard, secret scan on edits and commands, format on edit, edit-loop detection, stop gate, re-anchor after compaction.",
   "type": "module",

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

@@ -19,7 +19,7 @@ import { join } from "node:path";
 import { runHook, allow, addContext, systemMessage } from "../lib/io.mjs";
 import { loadConfig, projectDir } from "../lib/config.mjs";
 import { loadState, saveState } from "../lib/state.mjs";
-import { gitHead, mergeSnapshot, readDecisions, readPlanSummary, snapshotSection, splitSnapshot } from "../lib/anchor.mjs";
+import { gitHead, mergeSnapshot, readDecisions, readPlanSummary, readPlanSummaries, snapshotSection, splitSnapshot } from "../lib/anchor.mjs";
 
 runHook("reanchor", async (input) => {
   const dir = projectDir(input);
@@ -30,6 +30,7 @@ runHook("reanchor", async (input) => {
     const state = loadState(dir, input.session_id);
     const section = snapshotSection({
       plan: readPlanSummary(dir),
+      plans: readPlanSummaries(dir),
       decisions: readDecisions(dir),
       state,
       now: new Date(),