faberun 0.3.0

package/src/notify/index.mjs

@@ -0,0 +1,359 @@
+/**
+ * Direct notification dispatcher (TECH-SPEC lean, rule 6). On `node.terminal`,
+ * `run.terminal` and `attention` the controller renders a one-line message
+ * from a fixed per-type template, calls `FABERUN_NOTIFY_BIN` with the
+ * event as JSON on stdin, and appends a receipt (`delivered`, `failed` or
+ * `no_transport`, with the timestamp) to `<run-dir>/notify.jsonl`. Delivery is
+ * lossy: an event is attempted once, a failure schedules no further attempt and
+ * is never requeued, and the controller never waits on a retry it will not
+ * make. The next read of the run's own artefacts carries the full state. With
+ * no transport bound (`FABERUN_NOTIFY_BIN` unset) nothing is spawned and
+ * a `no_transport` receipt is recorded instead — there is no implicit desktop
+ * fallback. The macOS notifier is reachable only by setting
+ * `FABERUN_NOTIFY_BIN=os-macos`, an explicit opt-in, never a default.
+ */
+
+import { spawn as defaultSpawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { createMacosNotifier } from "./os-macos.mjs";
+import { errorMessage } from "../util.mjs";
+
+export const NOTIFY_BIN_ENV = "FABERUN_NOTIFY_BIN";
+const MACOS_TRANSPORT = "os-macos";
+export const NOTIFY_LOG_FILE = "notify.jsonl";
+/**
+ * The bounded retry budget the dispatcher used to spend before giving up.
+ * `campaign/metrics.mjs` still reads it through `notifyReceiptRate`: a `failed`
+ * receipt at the final attempt counts as settled. Delivery is lossy now, so no
+ * receipt carries an attempt past the first and a failed delivery no longer
+ * satisfies that indicator — the metric is unchanged and reports the drop.
+ */
+export const MAX_ATTEMPTS = 3;
+
+const SUMMARY_CHARS = 200;
+
+/**
+ * The append-only, campaign-level record the managed `AGENTS.md` signal block
+ * summarises. It lives at `<runs-dir>/inbox.jsonl` so a notification that
+ * belongs to no single run — a campaign watcher line — has a durable home that
+ * is not a run directory.
+ *
+ * Schema, one JSON object per line:
+ * `{schemaVersion, eventId, at, type, campaignId, runId, nodeId, status,
+ * errorCode, dedupeKey, summary}`. `eventId` is the sha256 hex of `dedupeKey`,
+ * and an entry is appended only when no existing entry carries the same
+ * `dedupeKey` (first write wins). Concurrent writers append whole lines with a
+ * single `O_APPEND` write each, so lines never interleave; the check-then-append
+ * is not atomic, so two writers racing on the same key may both append, and
+ * readers collapse repeated keys. A torn trailing line from a crash is skipped
+ * by `readInbox`.
+ */
+export const INBOX_FILE = "inbox.jsonl";
+export const INBOX_SCHEMA_VERSION = 1;
+
+/**
+ * The named warning `doctor`, `preflight` and the foreground launch command
+ * emit when no human transport is bound. It is a warning, not an error: the
+ * opt-in is intentional and no default exists on any platform.
+ */
+export const NOTIFY_NO_TRANSPORT_WARNING = "no human notification transport is configured (FABERUN_NOTIFY_BIN unset): terminal events reach only .runs/inbox.jsonl and the AGENTS.md managed block";
+
+/** @typedef {Record<string, unknown>} JsonObject */
+/** @typedef {{schemaVersion: number, eventId: string, at: string, type: string, campaignId: string|null, runId: string|null, nodeId: string|null, status: string|null, errorCode: string|null, dedupeKey: string, summary: string}} InboxEntry */
+/** @typedef {{type: string, dedupeKey: string, summary: string, at?: string, campaignId?: string|null, runId?: string|null, nodeId?: string|null, status?: string|null, errorCode?: string|null}} InboxEvent */
+/** @typedef {{type: "node.terminal"|"run.terminal"|"attention", runId: string|null, campaignId?: string|null, nodeId?: string|null, status?: string|null, attempt?: number|null, errorCode?: string|null, done?: number|null, total?: number|null, dedupeKey?: string|null, runDir?: string|null, costUsd?: number|null, summary?: string|null, eventId?: string}} NotifyEvent */
+/** @typedef {{ok: boolean, error?: string, noTransport?: boolean}} DeliveryResult */
+
+/**
+ * Render the fixed one-line message for an event, from counters and
+ * identifiers only (node id, run id or directory, state, attempt, error
+ * code, done/total, cost), never from model text:
+ *   `node <id> failed · run <id> · attempt 2 · verification_failed · resume <run-dir>`
+ *   `run <id> done · 3/3 nodes · $4.21`
+ *   `node <id> needs you · run <id> · <error code>`
+ * `runDir` and `costUsd`, when present on the event, come from the run's own
+ * `status.json` (`NotifyQueue.enqueue` reads it) — never from the model.
+ *
+ * @param {NotifyEvent} event
+ * @returns {string}
+ */
+export function renderNotification(event) {
+  const runId = event.runId ?? "-";
+  switch (event.type) {
+    case "node.terminal": {
+      const ok = event.status === "done" || event.status === "no-op";
+      const errorPart = event.errorCode ? ` · ${event.errorCode}` : "";
+      const resumePart = !ok && event.runDir ? ` · resume ${event.runDir}` : "";
+      return truncate(`node ${event.nodeId ?? "-"} ${event.status ?? "-"} · run ${runId} · attempt ${event.attempt ?? 0}${errorPart}${resumePart}`);
+    }
+    case "run.terminal": {
+      const done = event.done ?? 0;
+      const total = event.total ?? 0;
+      const state = total > done ? "attention" : "done";
+      const costPart = typeof event.costUsd === "number" ? ` · $${event.costUsd.toFixed(2)}` : "";
+      return truncate(`run ${runId} ${state} · ${done}/${total} nodes${costPart}`);
+    }
+    case "attention": {
+      const subject = event.nodeId ? `node ${event.nodeId} needs you · run ${runId}` : `run ${runId} needs you`;
+      const errorPart = event.errorCode ? ` · ${event.errorCode}` : "";
+      return truncate(`${subject}${errorPart}`);
+    }
+    default:
+      throw new TypeError(`renderNotification: unknown event type ${String(event.type)}`);
+  }
+}
+
+/**
+ * The run's total cost so far, read from its own `status.json` (the single
+ * source `writeStatusArtifacts` refreshes every tick). Missing or unreadable
+ * is `null`: a notification never blocks or fails on this being unavailable.
+ *
+ * @param {string} runDir
+ * @returns {number|null}
+ */
+function readRunCostUsd(runDir) {
+  try {
+    const payload = JSON.parse(readFileSync(join(runDir, "status.json"), "utf8"));
+    const costUsd = payload?.usage?.costUsd;
+    return typeof costUsd === "number" ? costUsd : null;
+  } catch {
+    return null;
+  }
+}
+
+/** @param {string} value @returns {string} */
+function truncate(value) {
+  return value.length <= SUMMARY_CHARS ? value : `${value.slice(0, SUMMARY_CHARS - 1)}…`;
+}
+
+/**
+ * The named no-transport warning, or null when a transport is bound. The empty
+ * string counts as unset, exactly as `deliverNotification` reads it.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string|null}
+ */
+export function noTransportWarning(env = process.env) {
+  return env[NOTIFY_BIN_ENV] ? null : NOTIFY_NO_TRANSPORT_WARNING;
+}
+
+/**
+ * What `campaign watch --wake` must say about waking. No adapter declares
+ * `canWake: true` (`os-macos` is `canWake: false`), so the wake verb records
+ * to the inbox and the managed block and never implies a session was woken.
+ *
+ * @param {string|undefined} [bin]
+ * @returns {string}
+ */
+export function wakeCapabilityNotice(bin = process.env[NOTIFY_BIN_ENV]) {
+  if (!bin) {
+    return "no notify transport is configured; --wake records to .runs/inbox.jsonl and the AGENTS.md managed block; no session is woken";
+  }
+  if (bin === MACOS_TRANSPORT) {
+    return "os-macos cannot wake a session (canWake: false); --wake records to .runs/inbox.jsonl and the AGENTS.md managed block";
+  }
+  return `notify transport ${bin} declares canWake: false; --wake records to .runs/inbox.jsonl and the AGENTS.md managed block; no session is woken`;
+}
+
+/** @param {string} runsDir @returns {string} */
+export function inboxPath(runsDir) {
+  return join(runsDir, INBOX_FILE);
+}
+
+/**
+ * Read every committed inbox entry. A missing file is `[]`; a torn or
+ * unparsable line is skipped, exactly as `alreadyNotified` treats one.
+ *
+ * @param {string} runsDir
+ * @returns {InboxEntry[]}
+ */
+export function readInbox(runsDir) {
+  let text;
+  try {
+    text = readFileSync(inboxPath(runsDir), "utf8");
+  } catch {
+    return [];
+  }
+  /** @type {InboxEntry[]} */
+  const entries = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed && typeof parsed === "object") entries.push(/** @type {InboxEntry} */ (parsed));
+    } catch {
+      // A torn trailing line was never a committed entry.
+    }
+  }
+  return entries;
+}
+
+/**
+ * Append one entry unless its `dedupeKey` is already present. `eventId` is the
+ * hash of the key, so the identity is stable across processes and restarts.
+ *
+ * @param {string} runsDir
+ * @param {InboxEvent} event
+ * @returns {{appended: boolean, eventId: string, entry?: InboxEntry}}
+ */
+export function appendInbox(runsDir, event) {
+  if (typeof event.dedupeKey !== "string" || !event.dedupeKey) {
+    throw new TypeError("appendInbox: an entry requires a non-empty dedupeKey");
+  }
+  const eventId = createHash("sha256").update(event.dedupeKey).digest("hex");
+  if (readInbox(runsDir).some((entry) => entry.dedupeKey === event.dedupeKey)) {
+    return { appended: false, eventId };
+  }
+  /** @type {InboxEntry} */
+  const entry = {
+    schemaVersion: INBOX_SCHEMA_VERSION,
+    eventId,
+    at: event.at ?? new Date().toISOString(),
+    type: event.type,
+    campaignId: event.campaignId ?? null,
+    runId: event.runId ?? null,
+    nodeId: event.nodeId ?? null,
+    status: event.status ?? null,
+    errorCode: event.errorCode ?? null,
+    dedupeKey: event.dedupeKey,
+    summary: event.summary,
+  };
+  mkdirSync(runsDir, { recursive: true });
+  const fd = openSync(inboxPath(runsDir), "a", 0o600);
+  try {
+    writeSync(fd, Buffer.from(`${JSON.stringify(entry)}\n`, "utf8"));
+  } finally {
+    closeSync(fd);
+  }
+  return { appended: true, eventId, entry };
+}
+
+/**
+ * Deliver one event through the bound transport. No transport bound resolves
+ * `{ok: false, noTransport: true}` without spawning anything.
+ *
+ * @param {{type: string, summary: string, campaignId?: string|null, [key: string]: unknown}} event
+ * @param {{bin?: string, spawn?: typeof defaultSpawn, timeoutMs?: number}} [options]
+ * @returns {Promise<DeliveryResult>}
+ */
+function deliverNotification(event, options = {}) {
+  const bin = options.bin ?? process.env[NOTIFY_BIN_ENV];
+  if (!bin) return Promise.resolve({ ok: false, noTransport: true });
+  if (bin === MACOS_TRANSPORT) {
+    return createMacosNotifier({ spawn: options.spawn }).deliver(/** @type {any} */ (event));
+  }
+  return spawnDeliver(bin, event, options);
+}
+
+/**
+ * @param {string} bin
+ * @param {JsonObject} event
+ * @param {{spawn?: typeof defaultSpawn, timeoutMs?: number}} options
+ * @returns {Promise<DeliveryResult>}
+ */
+function spawnDeliver(bin, event, { spawn = defaultSpawn, timeoutMs = 5_000 } = {}) {
+  return new Promise((resolveDelivery) => {
+    let child;
+    try {
+      child = spawn(bin, [], { stdio: ["pipe", "ignore", "pipe"], env: process.env });
+    } catch (error) {
+      resolveDelivery({ ok: false, error: errorMessage(error) });
+      return;
+    }
+    let settled = false;
+    /** @param {DeliveryResult} result */
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolveDelivery(result);
+    };
+    let stderr = "";
+    child.stderr?.on("data", (chunk) => {
+      stderr = `${stderr}${chunk}`.slice(-1024);
+    });
+    child.once("error", (error) => finish({ ok: false, error: errorMessage(error) }));
+    child.once("close", (code) => finish(code === 0 ? { ok: true } : { ok: false, error: stderr || `notification exited ${code}` }));
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGTERM");
+      } catch {
+        // ESRCH: the child already exited before the timeout kill; finish still resolves.
+      }
+      finish({ ok: false, error: `notification timed out after ${timeoutMs}ms` });
+    }, timeoutMs);
+    child.stdin.end(`${JSON.stringify(event)}\n`);
+  });
+}
+
+/**
+ * Per-run notification dispatcher. `enqueue` renders the message, attempts
+ * delivery once, and appends one receipt to `<runDir>/notify.jsonl` whatever
+ * the outcome. There is no pending queue to hold a failure and no scheduled
+ * retry: a failed delivery is recorded and dropped. A resume or an audit reads
+ * the receipt log for what happened and `status.json` for the state, which the
+ * next controller re-derives from disk instead of replaying a notify backup.
+ */
+export class NotifyQueue {
+  /**
+   * @param {{runDir: string, deliver?: typeof deliverNotification, now?: () => number}} options
+   */
+  constructor({ runDir, deliver = deliverNotification, now = () => Date.now() }) {
+    this.runDir = runDir;
+    this.deliver = deliver;
+    this.now = now;
+  }
+
+  /**
+   * Enrich the event with `runDir` and the run's current `costUsd` (from its
+   * own `status.json`, never the model) before rendering its summary, so
+   * `resume <run-dir>` and the run-terminal cost are counters and
+   * identifiers the templates can use without the caller supplying them.
+   * Delivery is awaited exactly once; a failure is recorded, not rescheduled.
+   *
+   * @param {NotifyEvent} event
+   * @returns {Promise<void>}
+   */
+  async enqueue(event) {
+    const enriched = { ...event, runDir: this.runDir, costUsd: readRunCostUsd(this.runDir) };
+    // A campaign-level line arrives already rendered; a run-level event is
+    // rendered from its counters here. Either way the stored summary is the
+    // one that reaches the transport and the receipt.
+    const summary = typeof enriched.summary === "string" && enriched.summary
+      ? enriched.summary
+      : renderNotification(enriched);
+    // Consumers deduplicate by eventId (the Ford adapter rejects an event without
+    // one), so every delivery carries a stable id derived from the dedupe key.
+    const eventId = enriched.eventId
+      ?? createHash("sha256").update(enriched.dedupeKey ?? JSON.stringify(enriched)).digest("hex");
+    /** @type {DeliveryResult} */
+    let result;
+    try {
+      result = await this.deliver({ ...enriched, summary, eventId });
+    } catch (error) {
+      // A transport that rejects is a failed delivery, not a controller fault:
+      // the receipt is still appended and the failure is dropped like any other.
+      result = { ok: false, error: errorMessage(error) };
+    }
+    /** @type {JsonObject} */
+    const receipt = {
+      eventId,
+      type: enriched.type,
+      runId: enriched.runId ?? null,
+      nodeId: enriched.nodeId ?? null,
+      nodeStatus: enriched.status ?? null,
+      errorCode: enriched.errorCode ?? null,
+      done: enriched.done ?? null,
+      total: enriched.total ?? null,
+      dedupeKey: enriched.dedupeKey ?? null,
+      summary,
+      attempt: 1,
+      status: result.ok ? "delivered" : result.noTransport ? "no_transport" : "failed",
+      at: new Date(this.now()).toISOString(),
+    };
+    if (!result.ok && !result.noTransport) receipt.error = result.error ?? null;
+    appendFileSync(join(this.runDir, NOTIFY_LOG_FILE), `${JSON.stringify(receipt)}\n`);
+  }
+}

package/src/notify/os-macos.mjs

@@ -0,0 +1,81 @@
+import { spawn as defaultSpawn } from "node:child_process";
+import { errorMessage, truncateChars } from "../util.mjs";
+
+const TITLE = "faberun";
+const BODY_CHARS = 200;
+const SUBTITLE_CHARS = 80;
+
+/** @typedef {Record<string, unknown>} JsonObject */
+/** @typedef {{type: string, campaignId?: string, summary?: string, eventId?: string, at?: string, data?: JsonObject}} NotificationEvent */
+/** @typedef {{id: string, capabilities: {canPush: boolean, canWake: boolean, canRenderAmbient: boolean}, deliver(event: NotificationEvent): Promise<{ok: boolean, error?: string}>}} NotifyAdapter */
+/** @typedef {{once(event: string, listener: (...args: any[]) => void): unknown, kill(signal?: any): unknown, stderr?: {on(event: string, listener: (chunk: string|Buffer) => void): void}|null}} SpawnedChild */
+/** @typedef {(command: string, args?: any, options?: any) => SpawnedChild} SpawnFunction */
+
+/**
+ * Create the macOS notification adapter. On a non-darwin platform deliver
+ * resolves { ok: false, error: "unsupported platform" } without spawning.
+ *
+ * @param {{spawn?: SpawnFunction, platform?: string, timeoutMs?: number}} [options]
+ * @returns {NotifyAdapter}
+ */
+export function createMacosNotifier({ spawn = defaultSpawn, platform = process.platform, timeoutMs = 5000 } = {}) {
+  return {
+    id: "os-macos",
+    capabilities: { canPush: true, canWake: false, canRenderAmbient: false },
+    deliver(event) {
+      return new Promise((resolve) => {
+        if (platform !== "darwin") {
+          resolve({ ok: false, error: "unsupported platform" });
+          return;
+        }
+        const summary = typeof event.summary === "string" ? event.summary : "";
+        const body = escapeAppleScript(truncateChars(summary, BODY_CHARS));
+        const campaignLabel = typeof event.campaignId === "string" ? event.campaignId : "campaign";
+        const subtitle = escapeAppleScript(truncateChars(`${campaignLabel} · ${event.type}`, SUBTITLE_CHARS));
+        const script = `display notification "${body}" with title "${TITLE}" subtitle "${subtitle}"`;
+        let child;
+        try {
+          child = spawn("osascript", ["-e", script]);
+        } catch (error) {
+          resolve({ ok: false, error: errorMessage(error) });
+          return;
+        }
+        let settled = false;
+        let stderr = "";
+        /** @type {ReturnType<typeof setTimeout>|undefined} */
+        let timer;
+        /** @param {{ok: boolean, error?: string}} result */
+        const finish = (result) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          resolve(result);
+        };
+        child.once("error", (error) => finish({ ok: false, error: errorMessage(error) }));
+        child.once("close", (code) => {
+          finish(code === 0 ? { ok: true } : { ok: false, error: stderr.trim() || `osascript exited ${code}` });
+        });
+        child.stderr?.on("data", (chunk) => {
+          stderr = `${stderr}${String(chunk)}`.slice(-2048);
+        });
+        timer = setTimeout(() => {
+          try {
+            child.kill("SIGTERM");
+          } catch {
+            // ESRCH: the child already exited before the timeout kill; finish still resolves.
+          }
+          finish({ ok: false, error: `osascript timed out after ${timeoutMs}ms` });
+        }, timeoutMs);
+      });
+    },
+  };
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeAppleScript(value) {
+  return value.replace(/\\/gu, "\\\\").replace(/"/gu, '\\"');
+}
+

package/src/repo/declared-paths.mjs

@@ -0,0 +1,220 @@
+/**
+ * Whether the paths a packet declared are paths the controller can actually
+ * observe, and whether its verification commands cover what it writes.
+ *
+ * Both answers come from git: a declared write inside an ignored directory
+ * leaves no diff to inspect, so the node would pass on evidence that cannot
+ * exist. These are warnings, not refusals -- the author may mean it -- but they
+ * are the warnings worth reading.
+ *
+ * It lived in `contract/index.mjs` and it runs `git check-ignore`: repository
+ * knowledge validating a contract, which is why it now sits in `repo/`.
+ */
+import { errorCode, exitStatus } from "../util.mjs";
+import { execFileSync } from "node:child_process";
+import { join, resolve } from "node:path";
+import { lstatSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+
+/** @typedef {import("../contract/index.mjs").ValidatedNode} ValidatedNode */
+
+const ALWAYS_UNOBSERVABLE_ROOTS = new Set([".runs", ".git"]);
+/**
+ * @param {ValidatedNode} node
+ * @param {number} index
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+export function unsnapshottedWriteWarnings(node, index, cwd) {
+  const declarations = /** @type {{kind: "writeFiles"|"writeRoots", path: string}[]} */ ([
+    ...(node.taskPacket.writeFiles ?? []).map((path) => ({ kind: "writeFiles", path })),
+    ...(node.taskPacket.writeRoots ?? []).map((path) => ({ kind: "writeRoots", path })),
+  ]);
+  const hidden = new Map();
+  for (const declaration of declarations) {
+    if (!isUnobservableDeclaredPath(cwd, declaration.path, declaration.kind)) continue;
+    const path = process.platform === "win32" ? String(declaration.path).replaceAll("\\", "/") : String(declaration.path);
+    const root = path.split("/")[0];
+    const key = `${declaration.kind}:${root}`;
+    hidden.set(key, { kind: declaration.kind, root, path });
+  }
+  return [...hidden.values()].map(({ kind, root, path }) =>
+    `nodes[${index}] (${node.id}): ${path.includes("/") ? `${kind} under ${root}/` : `${kind} ${path}`} are outside the workspace snapshot, so the closed-scope gate cannot observe them`,
+  );
+}
+/**
+ * @param {string|undefined} cwd
+ * @param {string} declaredPath
+ * @param {"writeFiles"|"writeRoots"} kind
+ * @returns {boolean}
+ */
+function isUnobservableDeclaredPath(cwd, declaredPath, kind) {
+  if (!cwd) return false;
+  const path = process.platform === "win32" ? String(declaredPath).replaceAll("\\", "/") : String(declaredPath);
+  const root = path.split("/")[0];
+  if (ALWAYS_UNOBSERVABLE_ROOTS.has(root)) return true;
+  return gitDeclaredPathState(cwd, path, kind) === "ignored";
+}
+/**
+ * @param {string} cwd
+ * @param {string} path
+ * @param {"writeFiles"|"writeRoots"} kind
+ * @returns {"tracked"|"ignored"|"visible"|"unknown"}
+ */
+function gitDeclaredPathState(cwd, path, kind) {
+  const literals = kind === "writeRoots" ? [path, `${path}/`] : [path];
+  try {
+    execFileSync("git", ["-C", cwd, "ls-files", "--cached", "--error-unmatch", "--", path], {
+      stdio: ["ignore", "ignore", "ignore"],
+    });
+    return "tracked";
+  } catch (error) {
+    if (exitStatus(error) !== 1) return "unknown";
+  }
+
+  let hasFaberunIgnore = false;
+  try {
+    hasFaberunIgnore = lstatSync(resolve(cwd, ".faberunignore")).isFile();
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") return "unknown";
+  }
+  const faberunIgnore = hasFaberunIgnore ? resolve(cwd, ".faberunignore") : undefined;
+  for (const literal of literals) {
+    const combined = checkCombinedGitIgnore(cwd, literal, faberunIgnore);
+    if (combined === "unknown") return "unknown";
+    if (combined === false) return "visible";
+  }
+  return "ignored";
+}
+/**
+ * Use the same combined Git enumeration as workspace snapshots for paths
+ * that already exist. Missing declarations fall through to check-ignore so
+ * validation can still warn about future paths hidden by a rule.
+ *
+ * @param {string} cwd
+ * @param {string} path
+ * @param {string|undefined} extraExclude
+ * @returns {boolean|"unknown"|undefined}
+ */
+function checkCombinedGitIgnore(cwd, path, extraExclude) {
+  let exists = true;
+  try {
+    lstatSync(resolve(cwd, path));
+  } catch (error) {
+    if (errorCode(error) === "ENOENT") exists = false;
+    else return "unknown";
+  }
+  if (!exists) {
+    return checkMissingCombinedGitIgnore(cwd, path, extraExclude);
+  }
+
+  try {
+    const args = ["-C", cwd, "ls-files", "--others", "--exclude-standard"];
+    if (extraExclude) args.push(`--exclude-from=${extraExclude}`);
+    args.push("-z", "--", path);
+    const output = execFileSync("git", args, { encoding: "buffer", stdio: ["ignore", "pipe", "ignore"] });
+    return output.length === 0;
+  } catch {
+    return "unknown";
+  }
+}
+/**
+ * A missing path cannot be checked with the snapshot enumeration. Ask Git for
+ * the standard result in the real repository, then ask Git whether the extra
+ * source matched in an isolated context so repository `.gitignore` files
+ * cannot outrank it.
+ *
+ * @param {string} cwd
+ * @param {string} path
+ * @param {string|undefined} extraExclude
+ * @returns {boolean|"unknown"}
+ */
+function checkMissingCombinedGitIgnore(cwd, path, extraExclude) {
+  const standard = checkGitIgnore(cwd, path);
+  if (!extraExclude || standard === "unknown") return standard;
+  const temporaryWorktree = mkdtempSync(join(tmpdir(), "faberun-ignore-check-"));
+  try {
+    execFileSync("git", ["init", "-q", temporaryWorktree], { stdio: ["ignore", "ignore", "ignore"] });
+    const temporaryGit = resolve(temporaryWorktree, ".git");
+    writeFileSync(resolve(temporaryGit, "info", "exclude"), readFileSync(extraExclude), { mode: 0o600 });
+    const args = ["--git-dir", temporaryGit, "--work-tree", temporaryWorktree, "-c", `core.excludesFile=${process.platform === "win32" ? "NUL" : "/dev/null"}`, "check-ignore", "--no-index", "--verbose", "--", path];
+    let customMatched;
+    try {
+      execFileSync("git", args, { stdio: ["ignore", "ignore", "ignore"] });
+      customMatched = true;
+    } catch (error) {
+      if (exitStatus(error) !== 1) return "unknown";
+      customMatched = false;
+    }
+
+    if (!customMatched) return standard;
+    try {
+      execFileSync("git", args.toSpliced(-3, 1, "--quiet"), { stdio: ["ignore", "ignore", "ignore"] });
+      return true;
+    } catch (error) {
+      return exitStatus(error) === 1 ? false : "unknown";
+    }
+  } catch {
+    return "unknown";
+  } finally {
+    rmSync(temporaryWorktree, { recursive: true, force: true });
+  }
+}
+/**
+ * Ask Git to classify a path even when it does not exist yet. For the
+ * optional runner ignore file, temporarily use Git's configured global
+ * exclude slot so Git remains the pattern parser.
+ *
+ * @param {string} cwd
+ * @param {string} path
+ * @param {string|undefined} [extraExclude]
+ * @returns {boolean|"unknown"}
+ */
+function checkGitIgnore(cwd, path, extraExclude) {
+  const args = ["-C", cwd];
+  if (extraExclude) args.push("-c", `core.excludesFile=${extraExclude}`);
+  args.push("check-ignore", "--no-index", "--quiet", "--", path);
+  try {
+    execFileSync("git", args, { stdio: ["ignore", "ignore", "ignore"] });
+    return true;
+  } catch (error) {
+    return exitStatus(error) === 1 ? false : "unknown";
+  }
+}
+/**
+ * @param {ValidatedNode} node
+ * @param {number} index
+ * @returns {string[]}
+ */
+export function commandCoverageWarnings(node, index) {
+  if (!Array.isArray(node.definitionOfDone) || node.definitionOfDone.length === 0) return [];
+  const dodText = node.definitionOfDone.map((item) => item.text).join("\n");
+  const warnings = [];
+  const lines = node.taskPacket.verification.map((command) => command.argv.join(" "));
+  for (const line of lines) {
+    const target = extractCommandTarget(line);
+    if (target && !dodText.includes(target)) {
+      warnings.push(`nodes[${index}] (${node.id}): command target "${target}" is not mentioned in any Definition of Done item`);
+    }
+  }
+  return warnings;
+}
+/**
+ * @param {string} line
+ * @returns {string|null}
+ */
+function extractCommandTarget(line) {
+  const trimmed = line.trim();
+  const patterns = [
+    [/^cargo test\b/u, /cargo test(?:\s+\S+)*\s+([a-z_]+::[a-z_:]+)/u],
+    [/^pnpm exec vitest run\b/u, /vitest run\s+(\S+)/u],
+    [/^(?:pnpm exec )?playwright test\b/u, /playwright test\s+(\S+)/u],
+    [/^node\s+/u, /^node\s+(\S+\.(?:mjs|js))/u],
+    [/^(?:pnpm|npm) run\s+/u, /^(?:pnpm|npm) run\s+(\S+)/u],
+  ];
+  for (const [trigger, extract] of patterns) {
+    if (!trigger.test(trimmed)) continue;
+    return extract.exec(trimmed)?.[1] ?? null;
+  }
+  return null;
+}