@dougharness/cli 1.0.1

package/node_modules/@dougharness/gates/scripts/format-on-edit.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// PostToolUse (Edit|Write|MultiEdit): run the configured formatter on the edited file(s).
+// Silent on success. On failure, tells Claude what the formatter said (usually a syntax error).
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { extname, join } from "node:path";
+import { runHook, allow, addContext } from "../lib/io.mjs";
+import { loadConfig, projectDir } from "../lib/config.mjs";
+import { toProjectRelative, filePathsFromToolInput } from "../lib/paths.mjs";
+import { tail, commandEnv } from "../lib/run.mjs";
+
+runHook("format-on-edit", async (input) => {
+  const dir = projectDir(input);
+  const cfg = loadConfig(dir);
+  const fmt = cfg.formatter;
+  if (!fmt || !Array.isArray(fmt.command) || fmt.command.length === 0) return allow();
+
+  const targets = [];
+  for (const p of filePathsFromToolInput(input.tool_input)) {
+    const rel = toProjectRelative(dir, p);
+    if (!rel) continue;
+    if (fmt.extensions && fmt.extensions.length && !fmt.extensions.includes(extname(rel))) continue;
+    if (!existsSync(join(dir, rel))) continue;
+    if (!targets.includes(rel)) targets.push(rel);
+  }
+  if (targets.length === 0) return allow();
+
+  const [bin, ...args] = fmt.command;
+  const res = spawnSync(bin, [...args, ...targets], {
+    cwd: dir,
+    encoding: "utf8",
+    timeout: fmt.timeoutMs || 20000,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: commandEnv(),
+  });
+  if (res.status === 0) return allow();
+
+  const output = tail((res.stderr || "") + "\n" + (res.stdout || ""), 20);
+  return addContext(
+    "PostToolUse",
+    `[doug] Formatter "${fmt.command.join(" ")}" failed on ${targets.join(", ")} (exit ${res.status ?? "timeout"}). ` +
+      `This usually means the file no longer parses. Output:\n${output}`,
+  );
+});

package/node_modules/@dougharness/gates/scripts/guard-bash.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// PreToolUse (Bash): deny --no-verify, force-push to protected branches, destructive commands,
+// and the wrong package manager. Rules live in lib/bash-rules.mjs and are unit-tested.
+
+import { execFileSync } from "node:child_process";
+import { runHook, allow, denyTool } from "../lib/io.mjs";
+import { loadConfig, projectDir } from "../lib/config.mjs";
+import { evaluateBash } from "../lib/bash-rules.mjs";
+import { recordCommand } from "../lib/state.mjs";
+
+function currentBranch(dir) {
+  // symbolic-ref works even before the first commit; rev-parse does not.
+  try {
+    return execFileSync("git", ["symbolic-ref", "--short", "HEAD"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 2000 }).trim();
+  } catch {
+    return null;
+  }
+}
+
+runHook("guard-bash", async (input) => {
+  const command = input.tool_input && input.tool_input.command;
+  if (!command) return allow();
+  const dir = projectDir(input);
+  const cfg = loadConfig(dir);
+  // Only resolve the branch when a push or a reset is involved; keeps the hot path at zero subprocesses.
+  const branch = /git\s+(push|reset)\b/.test(command) ? currentBranch(dir) : null;
+  const reasons = evaluateBash(command, { config: cfg, currentBranch: branch });
+  if (reasons.length) return denyTool(reasons.join(" "));
+  // An allowed command is about to run: the stop gate reads these as evidence that the session verified its work.
+  recordCommand(dir, input.session_id, command);
+  return allow();
+});

package/node_modules/@dougharness/gates/scripts/protect-paths.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// PreToolUse (Edit|Write|MultiEdit|NotebookEdit): deny edits to protected paths.
+// Protected patterns come from .doug/config.json `protectedPaths` (globs, ".gitignore"-like).
+// Bash writes are not intercepted here; the stop gate scans `git status` for protected changes.
+
+import { isAbsolute, resolve } from "node:path";
+import { runHook, allow, denyTool } from "../lib/io.mjs";
+import { loadConfig, projectDir } from "../lib/config.mjs";
+import { matchAny } from "../lib/glob.mjs";
+import { toProjectRelative, filePathsFromToolInput, isAllowedOutside, realpathDeepestExisting } from "../lib/paths.mjs";
+
+runHook("protect-paths", async (input) => {
+  const dir = projectDir(input);
+  const cfg = loadConfig(dir);
+  const realDir = realpathDeepestExisting(dir);
+  const paths = filePathsFromToolInput(input.tool_input);
+  if (paths.length === 0) return allow();
+
+  for (const p of paths) {
+    const abs = isAbsolute(p) ? p : resolve(dir, p);
+    const realAbs = realpathDeepestExisting(abs);
+    const rel = toProjectRelative(realDir, realAbs);
+    if (rel === null) {
+      // Outside the project even after resolving aliases: allowed only when an allowedOutsidePaths entry
+      // covers it.
+      if (isAllowedOutside(realAbs, cfg.allowedOutsidePaths)) continue;
+      return denyTool(
+        `Refusing to edit ${p}: it is outside the project directory ${dir}, and no allowedOutsidePaths entry in .doug/config.json covers it.`,
+      );
+    }
+    const hit = matchAny(cfg.protectedPaths, rel);
+    if (hit) {
+      return denyTool(
+        `Refusing to edit ${rel}: it matches protected path pattern "${hit}" in .doug/config.json. ` +
+          `If this file must change, ask the user to edit it or to adjust protectedPaths.`,
+      );
+    }
+    // Decisions/rules (card memory-decisions): written only through an approved proposal diff.
+    const proposalHit = matchAny(cfg.proposalPaths, rel);
+    if (proposalHit) {
+      return denyTool(
+        `Refusing to edit ${rel}: it matches proposal-only path "${proposalHit}" in .doug/config.json. ` +
+          `Decisions and rules are written only through an approved proposal: /doug-decide, or ` +
+          `memory.mjs decision|rule propose then learn.mjs apply.`,
+      );
+    }
+  }
+  return allow();
+});

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

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// SessionStart (compact|resume): re-inject the few facts that must survive compaction. Sources: `anchor` lines
+// and `commands` in .doug/config.json, plus .doug/anchor.md if the user or a workflow wrote a current-task
+// anchor; when that file holds a compaction snapshot (see below), the snapshot goes first so the 4000-character
+// cap never cuts it. Deterministic, no model calls.
+// PreCompact: before compaction, snapshot the plan, task ownership, decisions, this session's edited files and
+// recent commands, and (card precompact-keeps-handoff) a Handoff boundary block naming the compaction trigger,
+// the Stop gate's last result when one was recorded, the current HEAD, and the context percentage when one was
+// recorded, into .doug/anchor.md (lib/anchor.mjs); tell the user via a top-level systemMessage that the snapshot
+// was taken (this build's hook-output validator rejects hookSpecificOutput.hookEventName "PreCompact"/
+// "PostCompact", so no hookSpecificOutput is emitted for either event; the model-facing re-anchor rides on
+// SessionStart(compact)).
+// PostCompact: clears state.context (card context-window-handoff), so a context reading recorded before the cut
+// cannot produce a handoff notice after it, then allow() with no output. The payload's token estimates are
+// ignored: nothing here estimates tokens (decision 0002 #4).
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+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";
+
+runHook("reanchor", async (input) => {
+  const dir = projectDir(input);
+  const cfg = loadConfig(dir);
+  const anchorFile = join(dir, ".doug/anchor.md");
+
+  if (input.hook_event_name === "PreCompact") {
+    const state = loadState(dir, input.session_id);
+    const section = snapshotSection({
+      plan: readPlanSummary(dir),
+      decisions: readDecisions(dir),
+      state,
+      now: new Date(),
+      handoff: {
+        boundary: `compaction (${typeof input.trigger === "string" && input.trigger ? input.trigger : "auto"})`,
+        gate: state.lastGate ? { ok: state.lastGate.ok, at: state.lastGate.at } : null,
+        head: gitHead(dir),
+        contextPct: state.context && Number.isFinite(state.context.pct) ? state.context.pct : undefined,
+      },
+    });
+    mkdirSync(join(dir, ".doug"), { recursive: true });
+    const before = existsSync(anchorFile) ? readFileSync(anchorFile, "utf8") : "";
+    writeFileSync(anchorFile, mergeSnapshot(before, section));
+    return systemMessage(
+      "[doug] Compacting: .doug/anchor.md now holds a snapshot of the plan, task ownership, decisions, and this session's edited files and recent commands; the SessionStart hook re-injects it after compaction.",
+    );
+  }
+
+  if (input.hook_event_name === "PostCompact") {
+    // Clear the recorded context reading (card context-window-handoff) so a pre-compaction reading cannot
+    // produce a handoff notice after the cut.
+    const state = loadState(dir, input.session_id);
+    if (state.context !== undefined) {
+      delete state.context;
+      saveState(dir, input.session_id, state);
+    }
+    return allow();
+  }
+
+  const parts = [];
+  if (Array.isArray(cfg.anchor) && cfg.anchor.length) {
+    parts.push("Project facts that must hold:\n" + cfg.anchor.map((l) => `- ${l}`).join("\n"));
+  }
+  const cmds = Object.entries(cfg.commands || {}).filter(([, v]) => typeof v === "string" && v);
+  if (cmds.length) {
+    parts.push("Commands:\n" + cmds.map(([k, v]) => `- ${k}: ${v}`).join("\n"));
+  }
+  if (existsSync(anchorFile)) {
+    const text = readFileSync(anchorFile, "utf8").trim();
+    if (text) {
+      const { snapshot, rest } = splitSnapshot(text);
+      const ordered = snapshot ? (rest ? `${snapshot}\n\n${rest}` : snapshot) : text;
+      parts.push("Current task anchor (.doug/anchor.md):\n" + ordered.slice(0, 4000));
+    }
+  }
+  if (parts.length === 0) return allow();
+
+  return addContext("SessionStart", `[doug] Context was compacted or resumed. Re-anchoring.\n\n${parts.join("\n\n")}`);
+});

package/node_modules/@dougharness/gates/scripts/research-cap.mjs

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+// PreToolUse (WebFetch|WebSearch|Bash): card research-fetch-cap, extended by card research-cap-bash-fetch.
+// Researchers ran unbounded searches and fetches and took a computer down (four of five researchers burned all
+// 30 turns fetching and wrote nothing). This caps each subagent's combined WebSearch, WebFetch, and Bash
+// curl/wget calls at research.maxFetches (default 6, .doug/config.json), denying the call past the cap and
+// telling the agent to write its findings now instead.
+//
+// Counted from a per-agent counter file, not the run trace: trace.mjs runs as a separate PreToolUse hook on the
+// same event, in parallel with this one, so the current call's own trace line may or may not exist yet when
+// this hook reads it. A counter file this hook owns and appends to itself has no such race with another hook.
+//
+// Bash counting (card research-cap-bash-fetch): a Bash command is split into its top-level simple commands by
+// this script's own splitTopLevel (quote- and heredoc-aware; see its comment below, round 2) and each split
+// command's resolved forms (bash-rules commandForms, which walks past prefixes such as sudo, env, an env
+// assignment, and a shell's -c script) are checked for a first word whose basename, lower-cased, is curl or
+// wget. A split command counts as one fetch when any of its forms resolves that way; an ordinary Bash command
+// with no curl/wget form is never counted and never denied by this hook. This hook now spawns on every
+// subagent's and every main-session Bash call, not only its WebFetch/WebSearch calls.
+//
+// Known limits (round 2, major 2 - measured, not guessed): the cap is a budget nudge for researchers, not a
+// security boundary. Not counted at all: xargs curl; a for/while loop body (do curl ...); timeout 10 curl ...;
+// and any other wrapper resolveVerb does not skip (docker run ... curl, ssh host curl); other fetchers (gh api,
+// a node -e "fetch(...)" one-liner, python, etc.). Counted although no network call happens: curl --version,
+// curl --help. A shell -c script with several curls in it (bash -c 'curl a; curl b') counts once, since
+// commandForms reads the whole -c script as one form.
+//
+// Known limit: several calls issued in one message can each read the same count before any of them appends, so
+// a single burst can push an agent's count past the cap by the number of calls it issues at once.
+//
+// Known limits (round 2 reviewer, measured against this script): splitTopLevel tracks quotes and heredocs only,
+// so it still miscounts (a false count, and a false denial at the cap) text after an unquoted "#" comment that
+// contains a separator and the verb (`ls -la # see notes; curl https://x` counts one; `curl https://x # note;
+// wget y` counts two), an ANSI-C quoted string (`echo $'it\'s; curl x'`), and a backslash line-continuation
+// whose next line begins with the bare verb. A shell -c script is seen only when the fetch is its first
+// command: `bash -c 'curl a; curl b'` counts one, `bash -c "echo hi; curl https://x"` and
+// `sh -c 'cd /tmp && curl https://x'` count zero, and so does `if true; then curl https://x; fi`. Also not
+// counted at all: command substitution `$(curl ...)`, backticks, a `( ... )` subshell, process substitution
+// `<(curl ...)`, and a quoted or backslashed verb (`"curl"`, `\curl`). The count is read before the appends, so
+// one command with several fetches can push an agent's count past the cap by that command's own number of
+// fetches (five used plus a command with three fetches ends at eight of six) - the same shape as the several-
+// calls-in-one-message limit above.
+//
+// Fail-open, visibly (P3, card research-fetch-cap): this script has no local try/catch of its own. An I/O error
+// (e.g. the counter path is unreadable) propagates to runHook (lib/io.mjs), which allows the call but emits a
+// systemMessage naming this hook, so the failure is visible instead of silently swallowed here.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { runHook, allow, denyTool } from "../lib/io.mjs";
+import { loadConfig, projectDir } from "../lib/config.mjs";
+import { commandForms } from "../lib/bash-rules.mjs";
+
+const RESEARCH_CAP_DIR_RELPATH = ".doug/.state/research-cap";
+const FETCH_VERBS = new Set(["curl", "wget"]);
+
+function safeId(id) {
+  return String(id || "")
+    .replace(/[^A-Za-z0-9_.-]/g, "_")
+    .replace(/\.{2,}/g, "_")
+    .slice(0, 120);
+}
+
+function counterFile(dir, sessionId, agentId) {
+  // A missing or empty session id falls back to "no-session", like the trace hook's safeId (P5): the agent id
+  // is never empty at this point (the caller already returned early when it was).
+  return join(dir, RESEARCH_CAP_DIR_RELPATH, safeId(sessionId || "no-session"), `${safeId(agentId)}.log`);
+}
+
+function countCalls(file) {
+  if (!existsSync(file)) return 0;
+  return readFileSync(file, "utf8").split("\n").filter((l) => l.trim()).length;
+}
+
+// A form's first word, with its basename lower-cased (a path prefix stripped, matching bash-rules'
+// case-insensitive-filesystem reasoning): "sudo curl https://x" -> "sudo", "/usr/bin/curl https://x" -> "curl".
+function firstWordBasename(form) {
+  const first = String(form).trim().split(/\s+/)[0] || "";
+  return first.slice(first.lastIndexOf("/") + 1).toLowerCase();
+}
+
+// Round 2 (card research-cap-bash-fetch, major 1): splits a compound Bash command line into its top-level
+// simple commands, quote- and heredoc-aware, walking the string once. Unlike bash-rules' splitCommands (which
+// splits on ; && || | & and newline everywhere, quote-blind), this only splits on those outside single quotes,
+// outside double quotes (a backslash-escaped \" inside double quotes does not close them), and outside a
+// heredoc body - so quoted text that merely mentions ";" or "curl" is never miscounted as a separate command.
+//
+// A heredoc starts at <<WORD, <<-WORD, <<'WORD', or <<"WORD" (never <<<, a here-string: three or more "<" in a
+// row is never treated as a heredoc operator). Its body is every line after the operator's line up to the line
+// that is exactly WORD (a <<- terminator may be indented with leading tabs); that body is dropped from the
+// command text entirely, and the newline that closes the terminator line is treated like any other top-level
+// newline (it ends the command that carried the heredoc). An unterminated quote or heredoc has no closing
+// point, so it swallows the rest of the string into the current command - fewer splits than a real shell would
+// make, never more. Never throws: a malformed <<-with-no-word falls back to literal "<<" text; a non-string
+// command returns [].
+function splitTopLevel(command) {
+  if (typeof command !== "string") return [];
+  const results = [];
+  let current = "";
+  const push = () => {
+    const trimmed = current.trim();
+    if (trimmed) results.push(trimmed);
+    current = "";
+  };
+
+  let inSingle = false;
+  let inDouble = false;
+  let heredocWord = null; // trigger seen on the current line, body starts at the next newline
+  let heredocDash = false;
+  let inHeredocBody = false;
+  let heredocLine = ""; // buffers the body line currently being read, to compare against heredocWord
+
+  const n = command.length;
+  let i = 0;
+  while (i < n) {
+    const ch = command[i];
+
+    if (inHeredocBody) {
+      if (ch === "\n") {
+        const line = heredocDash ? heredocLine.replace(/^\t+/, "") : heredocLine;
+        heredocLine = "";
+        if (line === heredocWord) {
+          inHeredocBody = false;
+          heredocWord = null;
+          push(); // the terminator's newline ends the command that carried the heredoc, like any other newline
+        }
+        i += 1;
+        continue;
+      }
+      heredocLine += ch;
+      i += 1;
+      continue;
+    }
+
+    if (inSingle) {
+      current += ch;
+      if (ch === "'") inSingle = false;
+      i += 1;
+      continue;
+    }
+
+    if (inDouble) {
+      if (ch === "\\" && command[i + 1] === '"') {
+        current += ch + command[i + 1];
+        i += 2;
+        continue;
+      }
+      current += ch;
+      if (ch === '"') inDouble = false;
+      i += 1;
+      continue;
+    }
+
+    if (ch === "'") {
+      inSingle = true;
+      current += ch;
+      i += 1;
+      continue;
+    }
+    if (ch === '"') {
+      inDouble = true;
+      current += ch;
+      i += 1;
+      continue;
+    }
+
+    if (ch === "<") {
+      let j = i;
+      while (command[j] === "<") j += 1;
+      const run = j - i;
+      if (run !== 2) {
+        // one "<" (a plain redirect) or three-plus (a here-string, <<<, or longer): never a heredoc operator
+        current += command.slice(i, j);
+        i = j;
+        continue;
+      }
+      let k = j;
+      let dash = false;
+      if (command[k] === "-") {
+        dash = true;
+        k += 1;
+      }
+      while (command[k] === " " || command[k] === "\t") k += 1;
+      let word = "";
+      if (command[k] === "'" || command[k] === '"') {
+        const q = command[k];
+        k += 1;
+        while (k < n && command[k] !== q) {
+          word += command[k];
+          k += 1;
+        }
+        if (k < n) k += 1; // skip the closing quote
+      } else {
+        while (k < n && /[^\s;&|<>()]/.test(command[k])) {
+          word += command[k];
+          k += 1;
+        }
+      }
+      if (!word) {
+        // no word found after "<<": not a valid heredoc trigger, treat the two "<" as ordinary text
+        current += command.slice(i, j);
+        i = j;
+        continue;
+      }
+      current += command.slice(i, k); // the operator text itself is part of the command that carries it
+      heredocWord = word;
+      heredocDash = dash;
+      i = k;
+      continue;
+    }
+
+    if (ch === "\n") {
+      if (heredocWord !== null) {
+        inHeredocBody = true;
+        heredocLine = "";
+        i += 1;
+        continue;
+      }
+      push();
+      i += 1;
+      continue;
+    }
+    if (ch === "&" && command[i + 1] === "&") {
+      push();
+      i += 2;
+      continue;
+    }
+    if (ch === "|" && command[i + 1] === "|") {
+      push();
+      i += 2;
+      continue;
+    }
+    if (ch === ";" || ch === "|" || ch === "&") {
+      push();
+      i += 1;
+      continue;
+    }
+
+    current += ch;
+    i += 1;
+  }
+  push(); // an unterminated quote or heredoc body just folds whatever is left into this last command
+  return results;
+}
+
+// Returns one verb ("curl" or "wget") per split command of a Bash command line that resolves to a fetch;
+// non-fetch split commands contribute nothing. A non-string command (missing, or e.g. a number) is zero
+// fetches. commandForms runs on each split command's original text with its quotes intact (it does its own
+// quote parsing for a shell -c script), never on stripped or reconstructed text.
+function bashFetchVerbs(command) {
+  const verbs = [];
+  for (const cmd of splitTopLevel(command)) {
+    for (const form of commandForms(cmd)) {
+      const verb = firstWordBasename(form);
+      if (FETCH_VERBS.has(verb)) {
+        verbs.push(verb);
+        break;
+      }
+    }
+  }
+  return verbs;
+}
+
+runHook("research-cap", async (input) => {
+  const agentId = input.agent_id;
+  if (!agentId) return allow(); // the main session is never capped
+
+  const dir = projectDir(input);
+  const cfg = loadConfig(dir);
+  const max = cfg.research && cfg.research.maxFetches;
+  if (!Number.isInteger(max) || max <= 0) return allow(); // cap off
+
+  let entries;
+  if (input.tool_name === "Bash") {
+    const verbs = bashFetchVerbs(input.tool_input && input.tool_input.command);
+    if (verbs.length === 0) return allow(); // an ordinary Bash command is never counted or denied here
+    entries = verbs.map((verb) => ({ tool: "Bash", verb }));
+  } else {
+    entries = [{ tool: input.tool_name }];
+  }
+
+  const file = counterFile(dir, input.session_id, agentId);
+  const count = countCalls(file);
+  if (count >= max) {
+    return denyTool(
+      `[doug] Research budget reached: this agent has used ${count} of ${max} WebSearch/WebFetch/curl/wget ` +
+        `calls (research.maxFetches in .doug/config.json). Stop searching now: write your findings from what ` +
+        `you have, and mark anything unanswered unverified.`,
+    );
+  }
+  mkdirSync(join(dir, RESEARCH_CAP_DIR_RELPATH, safeId(input.session_id || "no-session")), { recursive: true });
+  for (const entry of entries) {
+    appendFileSync(file, JSON.stringify({ t: new Date().toISOString(), ...entry }) + "\n");
+  }
+  return allow();
+});

package/node_modules/@dougharness/gates/scripts/secret-scan.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// PreToolUse (Edit/Write/MultiEdit/NotebookEdit/Bash): deny text that carries a credential shape.
+// Rules live in lib/secret-rules.mjs and are unit-tested; this script only wires them to the hook I/O.
+
+import { runHook, allow, denyTool } from "../lib/io.mjs";
+import { loadConfig, projectDir } from "../lib/config.mjs";
+import { matchAny } from "../lib/glob.mjs";
+import { toProjectRelative } from "../lib/paths.mjs";
+import { scanText, candidateTexts, denyReason } from "../lib/secret-rules.mjs";
+
+runHook("secret-scan", async (input) => {
+  const dir = projectDir(input);
+  const cfg = loadConfig(dir);
+  if (cfg.secrets.enabled === false) return allow();
+  for (const { label, path, text } of candidateTexts(input.tool_input)) {
+    let effectiveLabel = label;
+    if (typeof path === "string") {
+      const rel = toProjectRelative(dir, path);
+      if (rel !== null && matchAny(cfg.secrets.ignorePaths, rel)) continue;
+      effectiveLabel = rel ?? path;
+    }
+    const hit = scanText(text, cfg.secrets);
+    if (hit) return denyTool(denyReason(hit, effectiveLabel));
+  }
+  return allow();
+});

package/node_modules/@dougharness/gates/scripts/session-start-baseline.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// SessionStart, every source (no matcher — startup, resume, clear, compact, fork all confirmed to fire this):
+// capture the dirty-tree baseline as early as this event allows, so a tree the session never touches can skip
+// verification entirely at Stop instead of waiting for the stop gate's own first-run fallback capture
+// (card stop-gate-session-start; see docs/research/stop-gate-session-start.md for what is and is not
+// confirmed about this event). Idempotent: only writes state.baseline when it is absent, so firing late,
+// firing again for a subagent sharing the parent session_id, or firing more than once, can never clobber a
+// baseline that is already there.
+//
+// The capture always happens on the first fire, but it is only labelled "session-start" (letting the stop
+// gate narrow anyChange to the baseline-relative set) when BOTH:
+//   - the session demonstrably has not acted yet (no recorded commands, edits, turns, or a prior gate) —
+//     a late fire (ordering is unverified, per the research note) can otherwise land after the session
+//     already changed something through Bash or Edit, and that must not be baselined as pre-existing; and
+//   - the source is "startup" — `clear` and `fork` hand a NEW session_id a state file that may carry a
+//     previous session's uncommitted, never-verified work, which must not be baselined away either.
+// Anything else is labelled "stop", the same as the stop gate's own fallback capture, so the stop gate's
+// narrowing never applies and it keeps reading the full changed set, exactly as if this had never fired.
+//
+// Never blocks: SessionStart cannot fail a session anyway. The happy path exits 0 with no stdout; an
+// unexpected error still exits 0, via runHook's fail-open path, which does write a systemMessage.
+import { runHook, allow, sessionStartReason } from "../lib/io.mjs";
+import { projectDir, loadConfig } from "../lib/config.mjs";
+import { loadState, saveState } from "../lib/state.mjs";
+import { changedFiles, captureBaseline, headAt, walkProposalPathFiles } from "../lib/baseline.mjs";
+
+runHook("session-start-baseline", async (input) => {
+  const dir = projectDir(input);
+  const state = loadState(dir, input.session_id);
+  if (state.baseline !== null) return allow(); // already captured; idempotent
+  const changed = changedFiles(dir);
+  if (!Array.isArray(changed)) return allow(); // not a git repo, or git unavailable
+  const cfg = loadConfig(dir);
+  // Proposal-path files a project's own .gitignore hides from `git status` entirely (card
+  // stop-scan-committed-changes) are folded into the same baseline capture as `changed`, so a pre-existing,
+  // untouched one is never later read as new by the stop gate's sinceBaseline check.
+  const walked = walkProposalPathFiles(dir, cfg.proposalPaths);
+  const baseline = captureBaseline(dir, [...new Set([...changed, ...walked])]);
+  const baselineHead = headAt(dir);
+  // Re-read immediately before writing: capturing the baseline above can take a while on a large dirty
+  // tree, and another hook (guard-bash's recordCommand, edit-loop's editedFiles) may have written state
+  // in that window. Writing back the state object read at the top of this function would silently discard
+  // that write, so merge only the baseline fields onto the freshest state instead.
+  const fresh = loadState(dir, input.session_id);
+  if (fresh.baseline !== null) return allow(); // captured by a concurrent fire meanwhile
+  const pristine = fresh.commands.length === 0 && fresh.editedFiles.length === 0 && fresh.turns === 0 && fresh.lastGate === null;
+  fresh.baseline = baseline;
+  fresh.baselineSource = pristine && sessionStartReason(input) === "startup" ? "session-start" : "stop";
+  // Never overwrite a non-null baselineHead (card stop-scan-committed-changes) - matches the baseline field's
+  // own idempotency above, for the same reasons (a late or repeated fire must never clobber it).
+  if (fresh.baselineHead === null) fresh.baselineHead = baselineHead;
+  // This capture always performs the proposalPaths walk above, so the baseline it just wrote can be trusted
+  // for the stop gate's walk-based check (state.baselineWalked; see its definition in lib/state.mjs).
+  fresh.baselineWalked = true;
+  saveState(dir, input.session_id, fresh);
+  return allow();
+});