@mmerterden/multi-agent-pipeline 20.27.2 → 20.29.0

package/pipeline/scripts/doctor.mjs

@@ -61,6 +61,7 @@ import {
 } from "../lib/unattended-settings-location.mjs";
 import { prefsHosts, profileGaps } from "../lib/unattended-profile-check.mjs";
 import { xcodeSkillsStatus } from "../lib/xcode-plugin.mjs";
+import { hookReport } from "../lib/hook-registration.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const HOME = homedir();
@@ -94,6 +95,7 @@ const CHECK_IDS = [
   "prefs-valid",
   "identity",
   "hook-coverage",
+  "hook-reachability",
   "credential-mapping",
   "credential-liveness",
   "store-reference",
@@ -104,6 +106,7 @@ const CHECK_IDS = [
   "disk-space",
   "worktree-residue",
   "usage-report",
+  "usage-register",
   "free-models",
   "xcode-skills",
 ];
@@ -514,6 +517,57 @@ function checkHookCoverage() {
   ok("hook-coverage");
 }
 
+// hook-coverage asks whether each template command appears in settings.json
+// at all. This asks what Claude Code will actually run: per event, a matcher
+// that covers the template's tool names, the script present under
+// ~/.claude/scripts, no disableAllHooks; and which preferences do nothing
+// because their hook is missing (lib/hook-registration.mjs).
+function checkHookReachability() {
+  const tpl = join(CLAUDE, "templates", "claude-hooks.json");
+  if (!existsSync(tpl)) {
+    skip("hook-reachability", "no hooks template installed to compare against");
+    return;
+  }
+  const r = hookReport({ templatePath: tpl, home: HOME });
+  if (r.error) {
+    skip("hook-reachability", r.error);
+    return;
+  }
+  if (r.ok) {
+    ok("hook-reachability");
+    return;
+  }
+  const parts = [];
+  if (r.disabled) parts.push(r.disabled);
+  else if (r.missing.length) {
+    const names = [
+      ...new Set(
+        r.missing.map(
+          (m) => `${m.script || m.command} on ${m.event}${m.matcher ? ` ${m.matcher}` : ""}`,
+        ),
+      ),
+    ];
+    parts.push(
+      `${r.missing.length} template hook(s) Claude Code will not run: ${names.slice(0, 4).join(", ")}${names.length > 4 ? ` and ${names.length - 4} more` : ""}`,
+    );
+  }
+  if (r.inert.length) {
+    parts.push(
+      `inert preference(s): ${r.inert.map((i) => `${i.pref} (needs ${i.script})`).join(", ")}`,
+    );
+  }
+  report(
+    "hook-reachability",
+    "WARN",
+    parts.join("; "),
+    `merge ${tpl} into ${join(CLAUDE, "settings.json")} (or run ${hostCommand("setup", HERE)})`,
+    [
+      ...r.missing.map((m) => `${m.event} ${m.matcher || "-"} ${m.command}: ${m.why}`),
+      ...r.inert.map((i) => `prefs.global.${i.pref} -> ${i.script}`),
+    ],
+  );
+}
+
 function credentialInventory() {
   const inv = join(CLAUDE, "lib", "credential-inventory.sh");
   if (!existsSync(inv)) return null;
@@ -936,6 +990,55 @@ function checkUsageReport() {
   );
 }
 
+// usage-register.mjs runs quietly from setup, update and Phase 0, so the record
+// of its last attempt, and of the failure report it may have sent, is where a
+// machine that never registers shows why.
+const REGISTER_FINE = new Set(["registered", "registered-feedback-only", "enabled"]);
+const REGISTER_QUIET = new Set([
+  "token in environment",
+  "token in prefs",
+  "token already onboarded",
+]);
+
+function beaconSummary(beacon) {
+  const last = beacon?.last;
+  if (!last || typeof last.outcome !== "string") return "no failure report was sent";
+  const when = last.t ? ` at ${last.t}` : "";
+  return last.outcome === "sent"
+    ? `the failure report (${last.reason}) reached the site${when}`
+    : `the failure report (${last.reason}) could not be delivered${when}`;
+}
+
+function checkUsageRegister() {
+  const prefs = readJson(join(CLAUDE, "multi-agent-preferences.json"));
+  if (prefs?.global?.usageLog?.optOut === true) {
+    skip("usage-register", "usage reporting is opted out");
+    return;
+  }
+  const logs = join(CLAUDE, "logs", "multi-agent");
+  const last = readJson(join(logs, "usage-last-register.json"));
+  if (!last || typeof last.status !== "string") {
+    skip("usage-register", "no registration has been attempted on this machine yet");
+    return;
+  }
+  if (
+    REGISTER_FINE.has(last.status) ||
+    (last.status === "skipped" && REGISTER_QUIET.has(last.detail))
+  ) {
+    ok("usage-register");
+    return;
+  }
+  const beacon = beaconSummary(readJson(join(logs, "usage-register-beacon.json")));
+  const when = last.t ? ` at ${last.t}` : "";
+  const detail = last.detail ? ` (${last.detail})` : "";
+  report(
+    "usage-register",
+    "WARN",
+    `the last usage registration${when} was ${last.status}${detail}; ${beacon}`,
+    `run node ${join(HERE, "usage-register.mjs")} --refresh`,
+  );
+}
+
 // route-on --free promises that simple tasks leave Claude. With no usable
 // provider every one of them silently escalates back, which costs nothing but
 // saves nothing either - the user believes a control is working that is not.
@@ -1353,6 +1456,7 @@ function main() {
   checkPrefsValid();
   checkIdentity();
   checkHookCoverage();
+  checkHookReachability();
   checkCredentials(credentialInventory());
   checkStoreReference();
   checkEmbeddedCredentials();
@@ -1362,6 +1466,7 @@ function main() {
   checkDiskSpace();
   checkWorktreeResidue();
   checkUsageReport();
+  checkUsageRegister();
   checkFreeModels();
   checkXcodeSkills();
   if (PROFILE === "server") checkServerProfile(resolved);

package/pipeline/scripts/evidence-gate.mjs

@@ -12,11 +12,23 @@
 //   node pipeline/scripts/evidence-gate.mjs --claim test  --status passed --evidence test.log \
 //        --success-pattern 'All tests passed' --failure-pattern 'FAILED'
 //   node pipeline/scripts/evidence-gate.mjs --claim manual --status passed --evidence manual-test.json
+//   node pipeline/scripts/evidence-gate.mjs --claim artefact --status passed --evidence gaps.json \
+//        --stage-start 2026-10-23T09:00:00Z
 //
 // Flags:
-//   --claim            build | test | review | manual
+//   --claim            build | test | review | manual | artefact
 //                      build/test/review select default success/failure markers;
-//                      manual is JSON-based (Phase 5 manual-test.json, see below)
+//                      manual is JSON-based (Phase 5 manual-test.json, see below);
+//                      artefact is a stage's own output file, judged only by
+//                      --stage-start (required with it)
+//   --stage-start <t>  ISO time or epoch (ms, or seconds) the stage started.
+//                      The evidence must be this stage's own file, written
+//                      during it and whole: an mtime earlier than the start
+//                      less 2s of clock slack is another stage's (or an old
+//                      run's) file. A .json file is whole when it parses; any
+//                      other file under 400 bytes, or ending in a letter or
+//                      digit with no trailing newline, is partial, cut off
+//                      mid-write. Applies to every claim when given.
 //   --status           the claimed status (only "passed" is gated; others pass through)
 //   --evidence <path>  the log / artifact that must substantiate a "passed" claim
 //   --require-screenshot  manual claim only: every "pass" criterion must name a
@@ -63,7 +75,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
-import { gateContext } from "./gate-ledger.mjs";
+import { ATTENDED_RECORDED, gateContext } from "./gate-ledger.mjs";
 
 const LEDGER = fileURLToPath(new URL("./gate-ledger.mjs", import.meta.url));
 
@@ -93,7 +105,54 @@ const DEFAULT_MARKERS = {
 };
 
 const JSON_CLAIMS = new Set(["manual"]);
-const CLAIMS = [...Object.keys(DEFAULT_MARKERS), ...JSON_CLAIMS];
+const ARTEFACT_CLAIM = "artefact";
+const CLAIMS = [...Object.keys(DEFAULT_MARKERS), ...JSON_CLAIMS, ARTEFACT_CLAIM];
+
+const STAGE_SLACK_MS = 2000;
+const PARTIAL_UNDER_BYTES = 400;
+
+/** --stage-start as epoch ms: ISO, epoch ms, or epoch seconds. */
+function stageStartMs(value) {
+  if (value === undefined) return null;
+  const s = String(value).trim();
+  if (/^\d+(\.\d+)?$/.test(s)) {
+    const n = Number(s);
+    return n < 1e12 ? n * 1000 : n;
+  }
+  const t = Date.parse(s);
+  if (value === true || Number.isNaN(t)) usage(`--stage-start is not a time: ${value}`);
+  return t;
+}
+
+/**
+ * Is this the stage's own, whole file? Returns the reason it is not, or null.
+ *
+ * @param {string} path
+ * @param {Buffer} raw
+ * @param {number} startMs
+ */
+function stageArtefactProblem(path, raw, startMs) {
+  const mtime = statSync(path).mtimeMs;
+  if (mtime < startMs - STAGE_SLACK_MS) {
+    return `written ${new Date(mtime).toISOString()}, before the stage started (${new Date(startMs).toISOString()}); not this stage's output`;
+  }
+  if (/\.json$/i.test(path)) {
+    try {
+      JSON.parse(raw.toString("utf8"));
+      return null;
+    } catch (err) {
+      return `partial: not valid JSON (${err.message})`;
+    }
+  }
+  if (raw.length < PARTIAL_UNDER_BYTES) {
+    return `partial: ${raw.length} bytes, under ${PARTIAL_UNDER_BYTES}`;
+  }
+  const last = raw.toString("utf8").slice(-1);
+  if (/[A-Za-z0-9]/.test(last)) {
+    return "partial: ends mid-token, with no trailing newline";
+  }
+  return null;
+}
 const MANUAL_VERDICTS = new Set(["pass", "fail", "not-tested"]);
 
 const MAX_PATTERN_LEN = 200;
@@ -144,15 +203,19 @@ function parseArgs(argv) {
 // the bytes are gone. The verdict is short today; the verdict is also the only
 // thing a caller reads, so losing half of it is the one failure that matters.
 let verdictExtra = {};
-// Only while the quality gates are active (lib/unattended.mjs, gatesActive):
-// one synchronous append, so the verdict and its ledger entry
+// While the quality gates are active (lib/unattended.mjs, gatesActive), and
+// for the build and test claims of an attended run: one synchronous append, so the verdict and its ledger entry
 // cannot come apart. A ledger problem is reported and never changes the verdict.
 let ledgerClaim = null;
 let ledgerState = null;
 function ledger(verdict, reason, extra) {
   if (!ledgerClaim) return;
   const ctx = gateContext({ statePath: ledgerState });
-  if (!ctx.active) return;
+  // Attended, only the build and test claims are recorded (marked attended):
+  // the attended commit check reads them. Without a run state there is
+  // nothing to record into.
+  if (!ctx.active && !(ctx.statePath && ATTENDED_RECORDED.has(`evidence-gate/${ledgerClaim}`)))
+    return;
   const detail = { reason, ...(extra.summary ? { summary: extra.summary } : {}) };
   if (verdictExtra.stack) detail.stack = verdictExtra.stack;
   const argv = [LEDGER, "append", "--gate", `evidence-gate/${ledgerClaim}`, "--verdict", verdict];
@@ -291,6 +354,10 @@ if (typeof status !== "string") {
 }
 ledgerClaim = claim;
 ledgerState = typeof args.state === "string" ? args.state : null;
+const stageStart = stageStartMs(args["stage-start"]);
+if (claim === ARTEFACT_CLAIM && stageStart === null) {
+  usage("--claim artefact needs --stage-start");
+}
 
 // Only a "passed" claim needs proof. failed / pending / anything else is honest
 // about not succeeding, so it passes through untouched.
@@ -336,6 +403,14 @@ if (body.trim().length === 0) {
   fail(`${claim} claims passed but evidence file is blank: ${evidence} (default-FAIL)`);
 }
 
+if (stageStart !== null) {
+  const problem = stageArtefactProblem(evidence, readFileSync(evidence), stageStart);
+  if (problem) fail(`${claim} evidence ${evidence}: ${problem} (default-FAIL)`);
+  if (claim === ARTEFACT_CLAIM) {
+    ok(`${claim} ${evidence} is this stage's own output and whole`);
+  }
+}
+
 if (JSON_CLAIMS.has(claim)) {
   gateManual(claim, evidence, body, args["require-screenshot"] === true);
 }

package/pipeline/scripts/gate-ledger.mjs

@@ -15,7 +15,8 @@
  *
  * Entries are written while the quality gates are active (lib/unattended.mjs,
  * gatesActive): MULTI_AGENT_UNATTENDED=1, or a run in autopilot mode. A run
- * that is neither writes nothing and state.gates[] stays absent. The commit
+ * that is neither writes only the gates in ATTENDED_RECORDED, each entry marked
+ * `attended: true`, and checkCommit never counts those. The commit
  * hook's REQUIREMENT is narrower: it applies only with the variable set, since
  * it is security enforcement and a terminal autopilot run has a person at it.
  *
@@ -32,6 +33,9 @@
  *   gate-ledger.mjs append --gate <id> --verdict pass|fail|not-applicable
  *                  [--detail '<json>'] [--state <path>] [--repo <dir>]
  *   gate-ledger.mjs check  [--state <path>] [--repo <dir>] [--sha <sha>] [--json]
+ *   gate-ledger.mjs evidence [--state <path>] [--repo <dir>] [--sha <sha>] [--json]
+ *     the attended commit check: build/test evidence for HEAD, per
+ *     prefs.global.attendedCommitGate.mode (exit 0 fine, 1 warn, 4 block)
  *   gate-ledger.mjs park   --outcome awaiting-answer|verification-failed
  *                  [--waiting-for <step>] [--gate <id>] [--reason <text>] [--state <path>]
  *
@@ -49,12 +53,21 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { basename, dirname } from "node:path";
 
 import { decisionEntry, withDecision } from "../lib/decisions.mjs";
 import { invokedDirectly } from "../lib/invoked-directly.mjs";
 import { readRegularFile, readRegularJson } from "../lib/regular-file.mjs";
+import { globalPref } from "../lib/prefs-value.mjs";
+import { modeEntry } from "../lib/run-completion.mjs";
 import { attendedVerdict, gatesActive } from "../lib/unattended.mjs";
 import { listRuns, resolveRunFile } from "./_run-paths.mjs";
 import { acquireLock, releaseLock, stillOurs } from "./write-state.mjs";
@@ -80,6 +93,41 @@ export const MANDATORY_AT_COMMIT = [
   "plan-coverage",
 ];
 
+/**
+ * Gates whose verdict is recorded in an attended run too, marked
+ * `attended: true`. `plan-coverage` is what lib/run-completion.mjs reads
+ * before a run may write `status: complete`. One locked append per verdict;
+ * every other gate writes nothing while the gates are off.
+ */
+export const ATTENDED_RECORDED = new Set([
+  "plan-coverage",
+  "evidence-gate/build",
+  "evidence-gate/test",
+]);
+
+/** What an attended commit is checked for (pre-commit-check.sh, `evidence`). */
+export const ATTENDED_COMMIT_EVIDENCE = ["evidence-gate/build", "evidence-gate/test"];
+
+/** prefs.global.attendedCommitGate.mode values; `warn` is the default. */
+export const ATTENDED_COMMIT_MODES = ["off", "warn", "block"];
+
+/**
+ * The build/test evidence an attended commit on `sha` lacks: every gate in
+ * ATTENDED_COMMIT_EVIDENCE whose latest entry for that sha, attended or not,
+ * is missing or not passing.
+ *
+ * @param {object} state
+ * @param {string} sha
+ * @returns {string[]}
+ */
+export function attendedEvidenceGaps(state, sha) {
+  const latest = latestByGate(state?.gates, sha);
+  return ATTENDED_COMMIT_EVIDENCE.filter((g) => {
+    const e = latest.get(g);
+    return !e || !PASSING.has(e.verdict);
+  });
+}
+
 const QUESTION_ID = /^[a-z][a-z0-9-]*$/;
 const OPTION_ID = /^[a-z0-9][a-z0-9+_-]*$/;
 const QUESTION_KEYS = ["id", "stepId", "text", "kind", "options"];
@@ -201,6 +249,59 @@ export function resolveStatePath({ statePath = null, repo = null, env = process.
   }
 }
 
+export const TREE_MATCH_MAX_AGE_MS = 6 * 60 * 60 * 1000;
+
+/**
+ * The in-progress run an attended commit in `repo` belongs to, or null.
+ *
+ * Only a run still in progress counts: a finished local-mode run keeps the
+ * project root as its worktree forever and would otherwise judge every later
+ * commit there. Of several, the one bound to the hook's session (`sessionId`
+ * = MULTI_AGENT_SESSION_ID, or `hostSessionId` = the payload's session_id)
+ * wins, then the most recently written. A run matched only by its worktree
+ * counts while its state was written in the last six hours.
+ *
+ * @param {{repo: string, session?: string, env?: Record<string,string|undefined>}} opts
+ * @returns {string|null}
+ */
+export function liveRunFor({ repo, session = "", env = process.env }) {
+  const prevRoot = process.env.LOGS_ROOT;
+  if (env.LOGS_ROOT !== undefined) process.env.LOGS_ROOT = env.LOGS_ROOT;
+  try {
+    const top = toplevel(repo);
+    const want = top ? real(top) : null;
+    const launched = env.MULTI_AGENT_SESSION_ID || "";
+    const hits = [];
+    for (const run of listRuns()) {
+      const p = resolveRunFile(run.taskId, "agent-state.json", run.project);
+      if (!p) continue;
+      const doc = readJson(p);
+      if (!doc || typeof doc !== "object" || doc.status !== "in_progress") continue;
+      const bound =
+        (launched && doc.sessionId === launched) || (session && doc.hostSessionId === session);
+      const onTree =
+        want && typeof doc.worktreePath === "string" && real(doc.worktreePath) === want;
+      if (!bound && !onTree) continue;
+      let t = 0;
+      try {
+        t = statSync(p).mtimeMs;
+      } catch {
+        t = 0;
+      }
+      // A run that crashed keeps status in_progress forever. Matched only by
+      // its worktree, it judges commits there while its state is still being
+      // written; once it has gone quiet the tree is the user's again.
+      if (!bound && Date.now() - t > TREE_MATCH_MAX_AGE_MS) continue;
+      hits.push({ p, bound: bound ? 1 : 0, t });
+    }
+    hits.sort((a, b) => b.bound - a.bound || b.t - a.t);
+    return hits.length ? hits[0].p : null;
+  } finally {
+    if (prevRoot === undefined) delete process.env.LOGS_ROOT;
+    else process.env.LOGS_ROOT = prevRoot;
+  }
+}
+
 /**
  * Do the quality gates run here, and against which state?
  *
@@ -274,9 +375,17 @@ export async function record(
     throw new LedgerError("usage", `verdict must be one of ${VERDICTS.join(", ")}, got ${verdict}`);
   }
   const ctx = gateContext({ statePath, repo, env });
-  if (!ctx.active) return { written: false, reason: attendedVerdict(gate).reason };
+  const attended = !ctx.active;
+  if (attended && !ATTENDED_RECORDED.has(gate)) {
+    return { written: false, reason: attendedVerdict(gate).reason };
+  }
   const path = ctx.statePath;
-  if (!path) return { written: false, reason: "no run state found for this repository" };
+  if (!path) {
+    // Attended with no run to write into is the ordinary case outside the
+    // pipeline, not a ledger problem worth a line on stderr.
+    if (attended) return { written: false, reason: attendedVerdict(gate).reason };
+    return { written: false, reason: "no run state found for this repository" };
+  }
   let shaRepo = repo;
   if (!shaRepo) {
     const wt = ctx.state?.worktreePath;
@@ -288,6 +397,7 @@ export async function record(
     at: new Date().toISOString(),
     sha: headSha(shaRepo),
     detail: detail && typeof detail === "object" ? detail : { value: detail },
+    ...(attended ? { attended: true } : {}),
   };
   await updateState(path, (s) => ({
     ...s,
@@ -403,7 +513,12 @@ export function latestByGate(gates, sha) {
  * @returns {{ok: boolean, missing: string[], failing: object[], sha: string}}
  */
 export function checkCommit(state, sha, { mandatory = MANDATORY_AT_COMMIT } = {}) {
-  const latest = latestByGate(state?.gates, sha);
+  // An entry written while the gates were off says what an attended run
+  // observed; it never stands in for a verdict the unattended contract requires.
+  const gated = (Array.isArray(state?.gates) ? state.gates : []).filter(
+    (e) => !(e && e.attended === true),
+  );
+  const latest = latestByGate(gated, sha);
   const missing = [];
   const failing = [];
   for (const g of mandatory) {
@@ -499,6 +614,47 @@ async function main(argv) {
       );
     return 0;
   }
+  if (mode === "evidence") {
+    // The attended commit check: exit 0 nothing to say (no run, mode off, a
+    // mode that commits nothing, evidence present), 1 warn, 4 block. Never 2
+    // or 3 for a missing run: outside the pipeline a commit is none of this
+    // hook's business.
+    const pref = globalPref("attendedCommitGate.mode", "warn");
+    const gateMode = ATTENDED_COMMIT_MODES.includes(pref) ? pref : "warn";
+    if (gateMode === "off") return 0;
+    let session = "";
+    if (opts["hook-input"] === "-") {
+      try {
+        session = String(JSON.parse(readFileSync(0, "utf8"))?.session_id || "");
+      } catch {
+        session = "";
+      }
+    }
+    const path = opts.state || liveRunFor({ repo, session });
+    if (!path) return 0;
+    const state = readJson(path);
+    if (!state || typeof state !== "object") return 0;
+    if (state.status !== "in_progress") return 0;
+    if (modeEntry(state)?.commits === false) return 0;
+    const sha = opts.sha || headSha(repo);
+    if (!sha) return 0;
+    const missing = attendedEvidenceGaps(state, sha);
+    if (opts.json)
+      writeFileSync(1, `${JSON.stringify({ statePath: path, sha, gateMode, missing })}\n`);
+    if (!missing.length) return 0;
+    const verb = gateMode === "block" ? "BLOCKED" : "warning";
+    writeFileSync(
+      2,
+      `${[
+        `pre-commit-check: ${verb}: the run's gate ledger (${path}) has no passing ${missing.join(" / ")} for HEAD ${sha.slice(0, 12)}.`,
+        "  Run the build and the tests through evidence-gate.mjs (Phase 2 Gate 1) so the commit rests on recorded evidence.",
+        gateMode === "block"
+          ? "  prefs.global.attendedCommitGate.mode is block; set it to warn to commit anyway."
+          : "  The commit goes ahead; prefs.global.attendedCommitGate.mode block refuses it instead.",
+      ].join("\n")}\n`,
+    );
+    return gateMode === "block" ? 4 : 1;
+  }
   if (mode === "park") {
     const path = resolveStatePath({ statePath: opts.state, repo });
     let pendingQuestion;
@@ -523,7 +679,7 @@ async function main(argv) {
     });
     return 0;
   }
-  throw new LedgerError("usage", "mode must be append, check or park");
+  throw new LedgerError("usage", "mode must be append, check, evidence or park");
 }
 
 if (invokedDirectly(import.meta.url)) {
@@ -533,7 +689,7 @@ if (invokedDirectly(import.meta.url)) {
       process.stderr.write(`gate-ledger: ${err.message}\n`);
       if (err.code === "usage") {
         process.stderr.write(
-          "usage: gate-ledger.mjs append|check|park [--gate g] [--verdict v] [--detail json] [--state p] [--repo d] [--sha s] [--json]\n",
+          "usage: gate-ledger.mjs append|check|evidence|park [--gate g] [--verdict v] [--detail json] [--state p] [--repo d] [--sha s] [--json]\n",
         );
         process.exit(2);
       }