@mmerterden/multi-agent-pipeline 20.28.0 → 20.29.0

package/pipeline/scripts/run-stop-guard.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * run-stop-guard.mjs  -  a session driving a pipeline run does not end its turn
+ * mid-phase without saying why.
+ *
+ * Claude Code Stop hook. When the session that is driving an active run tries
+ * to stop while the run is `in_progress`, below its mode's last phase, with no
+ * `haltReason` and no `waitingFor`, it answers
+ * `{"decision":"block","reason":...}`. The reason names the phase to finish
+ * and the two legal ways out: finish it, or record a halt (operations.md,
+ * "Halt visibility").
+ *
+ * Which run: _active-run.mjs findActiveRun, and only a run bound to this
+ * session by `sessionId` (MULTI_AGENT_SESSION_ID) or `hostSessionId`. A run
+ * found only because its worktree is the session's cwd never holds a stop: an
+ * old local-mode run has the project root as its worktree and would trap
+ * every later session opened there. No bound run: exit 0, no output.
+ *
+ * The stop is let through, with no output, whenever the session has a reason
+ * to stop that the state does not record:
+ *   - the turn ends waiting for the user: `last_assistant_message` ends in a
+ *     question or asks for a reply (the pipeline's plain-text waits: plan
+ *     approval, commit, PR, a local-test handoff);
+ *   - background tasks or scheduled crons are running, so the run is driven
+ *     elsewhere and this session is waiting;
+ *   - prefs.global.stopGuard.enabled is false.
+ *
+ * SubagentStop is never held: a subagent finishes its piece and the session
+ * that dispatched it decides what comes next.
+ *
+ * Repeat ceiling: the host sets `stop_hook_active` while it continues because
+ * of a Stop hook, and overrides a hook that blocks too many times in a row.
+ * This hook counts its own consecutive blocks per run in `.stop-guard.json`
+ * next to the state. After REPEAT_LIMIT blocks it stops blocking, writes the
+ * halt record itself (`status: paused`, `haltReason: "<phase>:stop-guard: ..."`)
+ * and tells the user through `systemMessage`. write-state.mjs clears that
+ * halt the moment the run advances a phase, so it never outlives the run
+ * moving on. A stop with `stop_hook_active` false is a new turn and starts the
+ * count again.
+ *
+ * This is a completion aid, not a security gate: any error (unparseable
+ * payload, unreadable state, a failed write) exits 0 with no decision and a
+ * line in <log root>/hook-failures.log.
+ *
+ * @module pipeline/scripts/run-stop-guard
+ */
+
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { globalPref } from "../lib/prefs-value.mjs";
+import {
+  finalPhaseOf,
+  findActiveRun,
+  logHookFailure,
+  modeOf,
+  phaseName,
+  runDirOf,
+} from "./_active-run.mjs";
+
+export const REPEAT_LIMIT = 3;
+export const STOP_GUARD_HALT = "stop-guard:";
+const COUNTER_FILE = ".stop-guard.json";
+const HOOK = "run-stop-guard";
+const SESSION_BOUND = new Set(["session", "host-session"]);
+
+// A reply the turn asks for, in the closing text: a question mark (ASCII or
+// full-width) at the end of a line, or a request addressed to the user. A
+// request is an imperative that opens a sentence ("Confirm the plan.") or a
+// second-person phrase ("can you", "tell me"); a reply verb inside a
+// statement ("Next I will confirm the build") is the model's own plan and
+// does not count, nor does one used as a label ("Answer: the cache was stale").
+const QUESTION_END = /[?？]\s*(?:\(.{0,40}\))?\s*$/;
+const REPLY_VERB =
+  "(?:reply|respond|answer|confirm|choose|pick|approve|send|write your|tell me|let me know)";
+const ASKS_FOR_REPLY = new RegExp(
+  [
+    `(?:^|[.!:;]\\s+)(?:please\\s+)?${REPLY_VERB}\\b(?!\\s*:)`,
+    `\\bplease\\s+${REPLY_VERB}\\b(?!\\s*:)`,
+    "\\b(?:can|could|would|will) you\\b",
+    "\\b(?:do|would) you (?:want|like|prefer)\\b",
+    "\\b(?:let me know|tell me)\\b",
+    "\\b(?:reply|respond|answer) with\\b",
+    "\\(\\s*(?:yes|y)\\s*\\/\\s*(?:no|n)\\s*\\)",
+  ].join("|"),
+  "im",
+);
+
+/**
+ * True when the closing assistant text waits for the user.
+ *
+ * @param {unknown} message  last_assistant_message
+ */
+export function asksTheUser(message) {
+  if (typeof message !== "string" || !message.trim()) return false;
+  const lines = message
+    .trim()
+    .split("\n")
+    .map((l) => l.replace(/[*_`>#]+/g, "").trim())
+    .filter(Boolean);
+  const tail = lines.slice(-3);
+  if (tail.some((l) => QUESTION_END.test(l))) return true;
+  return ASKS_FOR_REPLY.test(tail.join("\n"));
+}
+
+/**
+ * Why the run may stop now, or null when it is mid-phase and must not.
+ *
+ * @param {object} state
+ * @returns {string|null}
+ */
+export function stopAllowedBecause(state) {
+  if (!state || typeof state !== "object") return "no state";
+  if (state.status !== "in_progress") return `status is ${state.status ?? "unset"}`;
+  if (state.haltReason) return "a halt is recorded";
+  if (state.waitingFor) return `waiting for ${state.waitingFor}`;
+  const final = finalPhaseOf(state);
+  if (final === null) return `mode ${modeOf(state)} is not declared in phases.json`;
+  const cur = Number(state.currentPhase);
+  if (!Number.isInteger(cur)) return "currentPhase is not recorded";
+  if (cur >= final) return "the final phase is reached";
+  return null;
+}
+
+/** The block reason: where the run is and the two ways out. */
+export function blockReason(state, statePath) {
+  const cur = Number(state.currentPhase);
+  const final = finalPhaseOf(state);
+  const id = state.taskId || "this run";
+  return [
+    `Pipeline run ${id} (mode ${modeOf(state)}) is at Phase ${cur} (${phaseName(cur)}) of ${final}, status in_progress, and no halt or wait is recorded.`,
+    `Now finish Phase ${cur} (${phaseName(cur)}) and go on as its document says.`,
+    `If you are waiting for the user, ask the question so the turn ends on it, or record the wait: printf '{"waitingFor":"attended-reply"}' | node "$HOME/.claude/scripts/write-state.mjs" "${statePath}".`,
+    `If the run cannot go on, record the halt before stopping: printf '{"status":"paused","haltReason":"${cur}:<cause>"}' | node "$HOME/.claude/scripts/write-state.mjs" "${statePath}" (operations.md, Halt visibility).`,
+  ].join(" ");
+}
+
+function readCounter(dir) {
+  try {
+    const doc = JSON.parse(readFileSync(join(dir, COUNTER_FILE), "utf8"));
+    return Number.isInteger(doc?.count) ? doc.count : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function writeCounter(dir, count) {
+  writeFileSync(
+    join(dir, COUNTER_FILE),
+    `${JSON.stringify({ count, at: new Date().toISOString() })}\n`,
+  );
+}
+
+function clearCounter(dir) {
+  rmSync(join(dir, COUNTER_FILE), { force: true });
+}
+
+async function recordHalt(statePath, state, blocks) {
+  const { updateState } = await import("./gate-ledger.mjs");
+  const cur = Number(state.currentPhase);
+  const cause = `${STOP_GUARD_HALT} the guard blocked ${blocks} consecutive stops before Phase ${cur} (${phaseName(cur)}) finished`;
+  await updateState(statePath, (s) => ({
+    ...s,
+    status: "paused",
+    haltReason: `${cur}:${cause}`,
+  }));
+  return cause;
+}
+
+const nonEmpty = (v) => Array.isArray(v) && v.length > 0;
+
+/**
+ * The hook's answer for one payload.
+ *
+ * @param {object} payload
+ * @param {Record<string,string|undefined>} [env]
+ * @returns {Promise<object|null>} the JSON to print, or null for no output
+ */
+export async function decide(payload, env = process.env) {
+  if (globalPref("stopGuard.enabled", true, env) === false) return null;
+  if (!payload || typeof payload !== "object") return null;
+  const event = payload.hook_event_name || "Stop";
+  if (event !== "Stop") return null;
+  if (nonEmpty(payload.background_tasks) || nonEmpty(payload.session_crons)) return null;
+  if (asksTheUser(payload.last_assistant_message)) return null;
+  const run = findActiveRun({
+    sessionId: typeof payload.session_id === "string" ? payload.session_id : null,
+    cwd: typeof payload.cwd === "string" ? payload.cwd : null,
+    env,
+  });
+  if (!run || !SESSION_BOUND.has(run.matchedBy)) {
+    if (!run && findActiveRun.lastUnreadable > 0) {
+      logHookFailure(
+        HOOK,
+        `${findActiveRun.lastUnreadable} run state file(s) did not parse; allowed the stop`,
+        env,
+      );
+    }
+    return null;
+  }
+  const dir = runDirOf(run.statePath);
+  if (stopAllowedBecause(run.state) !== null) {
+    if (existsSync(join(dir, COUNTER_FILE))) clearCounter(dir);
+    return null;
+  }
+
+  const prior = payload.stop_hook_active === true ? readCounter(dir) : 0;
+  if (prior >= REPEAT_LIMIT) {
+    const cause = await recordHalt(run.statePath, run.state, prior);
+    clearCounter(dir);
+    return {
+      systemMessage: `run-stop-guard: recorded a halt on ${run.state.taskId || run.statePath} (${cause}). Resume it with /multi-agent:resume.`,
+    };
+  }
+  writeCounter(dir, prior + 1);
+  return { decision: "block", reason: blockReason(run.state, run.statePath) };
+}
+
+async function main() {
+  let raw;
+  try {
+    raw = readFileSync(0, "utf8");
+  } catch {
+    raw = "";
+  }
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    logHookFailure(HOOK, "the hook payload is not JSON; allowed the stop");
+    return;
+  }
+  try {
+    const out = await decide(payload);
+    if (out) process.stdout.write(`${JSON.stringify(out)}\n`);
+  } catch (err) {
+    logHookFailure(HOOK, `${err?.message || err}; allowed the stop`);
+  }
+}
+
+const onFatal = (err) => logHookFailure(HOOK, `${err?.message || err}; allowed the stop`);
+
+// Exit 0 on every path: nothing above sets a non-zero code, and a failure
+// is logged and allowed.
+if (invokedDirectly(import.meta.url)) main().catch(onFatal);

package/pipeline/scripts/run-stop-guard.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# run-stop-guard.sh  -  Stop hook for the multi-agent pipeline.
+#
+# A session driving a pipeline run that tries to end its turn mid-run, with no
+# halt recorded, is told to continue or record the halt. The decision is in
+# run-stop-guard.mjs; this wrapper exists because every hook the pipeline
+# registers is a `bash "$HOME/.<host>/scripts/<name>"` command.
+#
+# Contract (Claude Code Stop hook):
+#   - Reads the hook JSON on stdin.
+#   - Prints {"decision":"block","reason":...} to keep the session going, or
+#     {"systemMessage":...} when it gives up and records the halt itself, or
+#     nothing.
+#   - Exits 0 on every path. A missing node or any internal error means no
+#     output: this is a completion aid, not a security gate.
+
+set -u
+
+HERE="$(cd "$(dirname "$0")" 2>/dev/null && pwd || true)"
+CORE="$HERE/run-stop-guard.mjs"
+[ -f "$CORE" ] || exit 0
+command -v node >/dev/null 2>&1 || exit 0
+
+node "$CORE" 2>/dev/null || true
+exit 0

package/pipeline/scripts/uninstall.mjs

@@ -1009,6 +1009,7 @@ export async function main() {
       );
     }
     rmIfExists(join(CLAUDE, ".pipeline-version"));
+    rmIfExists(join(CLAUDE, "multi-agent-hook-manifest.json"));
     // NOTE: ~/.claude/rules/ is USER-OWNED. install lays baseline rules down
     // write-if-missing and NEVER overwrites them (install/claude.mjs
     // installRules, skipExisting) so users can evolve their global rules

package/pipeline/scripts/validate-state.mjs

@@ -16,6 +16,7 @@
 //   - root is not an object
 //   - currentPhase is missing or out of the 0..5 range (resume keys on it)
 //   - phases is present but not an object, or an entry is not an object
+//   - waitingFor names a step resume cannot re-enter
 // Phase status strings are NOT enum-checked: real writers use "completed"
 // alongside the schema's "done", and an odd status does not make a resume
 // unsafe (resume keys on currentPhase, not phase status). Zero deps, same
@@ -32,6 +33,14 @@
 
 import { readFileSync } from "node:fs";
 
+const WAITING_FOR = new Set([
+  "maturity",
+  "user-channels-choice",
+  "local-test",
+  "attended-reply",
+  "question",
+]);
+
 function readInput() {
   const arg = process.argv[2];
   if (!arg) {
@@ -129,6 +138,23 @@ async function main() {
     }
   }
 
+  // waitingFor is the first field resume reads: a value it has no row for, or
+  // a question with nothing to re-ask, leaves the run unable to re-enter.
+  if (s.waitingFor !== undefined && s.waitingFor !== null) {
+    if (!WAITING_FOR.has(s.waitingFor)) {
+      errors.push(
+        `waitingFor must be one of ${[...WAITING_FOR].join(", ")} or null, got ${JSON.stringify(s.waitingFor)}`,
+      );
+    } else if (
+      s.waitingFor === "question" &&
+      (typeof s.pendingQuestion?.stepId !== "string" || !s.pendingQuestion.stepId)
+    ) {
+      errors.push(
+        'waitingFor "question" needs a pendingQuestion with a stepId; a typed wait records "attended-reply"',
+      );
+    }
+  }
+
   if (errors.length > 0) {
     emit({ ok: false, code: 1, errors });
     process.exit(1);

package/pipeline/scripts/write-state.mjs

@@ -32,6 +32,9 @@
  *   4  -  the lock was taken from us mid-write; nothing was written, retry
  *   3  -  I/O error (disk full, permission denied, parent dir missing)
  *   5  -  --if-rev did not match; the record moved, nothing was written
+ *   6  -  the write moves the run into `status: complete` without the evidence
+ *         lib/run-completion.mjs requires (last phase of the mode, Phase 4
+ *         evidence, a plan-coverage verdict); nothing was written
  *
  * Tunables (env):
  *   WRITE_STATE_LOCK_TIMEOUT_MS  acquire window before exit 2 (default 15000)
@@ -67,6 +70,7 @@ import { dirname, basename } from "path";
 import { Buffer } from "node:buffer";
 import { runMain } from "../lib/fatal.mjs";
 import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { completionGaps } from "../lib/run-completion.mjs";
 
 /**
  * @typedef {{ replace: boolean, path: string, ifRev: number|null }} ParsedArgs
@@ -320,6 +324,104 @@ function undeclaredKeys(payload, current) {
   );
 }
 
+const COMPLETE = new Set(["complete", "completed"]);
+const STOP_GUARD_HALT = /^\d+:stop-guard:/;
+
+/**
+ * Lift the halt run-stop-guard.mjs records after its repeat ceiling once the
+ * run advances a phase. That halt says only "the session kept stopping"; a
+ * later phase transition is the run going on, and leaving the halt in place
+ * would show a moving run as paused and make every later Stop let it through.
+ * A halt any other step recorded, or a write that sets status or haltReason
+ * itself, is left alone.
+ *
+ * @param {object} next
+ * @param {object} current
+ * @param {unknown} payload
+ */
+export function clearStopGuardHalt(next, current, payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return;
+  if (Object.hasOwn(payload, "status") || Object.hasOwn(payload, "haltReason")) return;
+  if (typeof current?.haltReason !== "string" || !STOP_GUARD_HALT.test(current.haltReason)) return;
+  const was = Number(current.currentPhase);
+  const now = Number(payload.currentPhase);
+  if (!Number.isInteger(now) || !(now > (Number.isInteger(was) ? was : -1))) return;
+  next.haltReason = null;
+  next.status = "in_progress";
+}
+
+/**
+ * Clear a wait the run has moved past. A write that advances `currentPhase`
+ * without setting `waitingFor` itself ends any wait recorded in the earlier
+ * phase, so a clear the step forgot cannot keep the run marked as waiting
+ * (and the stop guard off) for the rest of the run. `question` is left to
+ * answer-question.mjs, which clears it together with its pendingQuestion.
+ *
+ * @param {object} next
+ * @param {object} current
+ * @param {unknown} payload
+ */
+export function clearPassedWait(next, current, payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return;
+  if (Object.hasOwn(payload, "waitingFor")) return;
+  if (typeof current?.waitingFor !== "string" || current.waitingFor === "question") return;
+  const was = Number(current.currentPhase);
+  const now = Number(payload.currentPhase);
+  if (!Number.isInteger(now) || !(now > (Number.isInteger(was) ? was : -1))) return;
+  next.waitingFor = null;
+}
+
+/**
+ * The refusal message for a write that moves the run into `complete` without
+ * the evidence lib/run-completion.mjs asks for, or null.
+ *
+ * Only the transition is judged: a merge that sets `status: complete`, or a
+ * replace whose document is complete over one that was not. A later write to
+ * an already complete run that does not touch `status` goes through, so the
+ * report steps after the transition keep working.
+ *
+ * @param {object} next
+ * @param {unknown} payload
+ * @param {boolean} replace
+ * @param {string|null} diskStatus
+ * @returns {string|null}
+ */
+export function completionRefusal(next, payload, replace, diskStatus) {
+  if (!COMPLETE.has(next?.status)) return null;
+  const entering = replace
+    ? !COMPLETE.has(diskStatus)
+    : Boolean(payload && typeof payload === "object" && COMPLETE.has(payload.status));
+  if (!entering) return null;
+  const gaps = completionGaps(next);
+  if (!gaps.length) return null;
+  return `write-state: refusing status "${next.status}": ${gaps.join("; ")}. Nothing was written. Finish the missing step, or record a halt (status "paused" with a haltReason).`;
+}
+
+/**
+ * Bind the run to the host session that drives it.
+ *
+ * `hostSessionId` is the Claude Code session (CLAUDE_CODE_SESSION_ID in the
+ * Bash environment) that made the run's last phase transition. The Stop hook
+ * (run-stop-guard.mjs) and the run-scoped PreToolUse guards read it to find
+ * the run a hook call belongs to. Stamped only when the write creates the
+ * document or sets `currentPhase`: those are the driver's writes, while a
+ * second session editing a running task (`/multi-agent:steer`) sets neither
+ * and so does not take the run over.
+ *
+ * @param {object} next
+ * @param {unknown} payload
+ * @param {boolean} existed
+ * @param {Record<string,string|undefined>} [env]
+ */
+export function stampHostSession(next, payload, existed, env = process.env) {
+  const sid = env.CLAUDE_CODE_SESSION_ID;
+  if (typeof sid !== "string" || !sid.trim()) return;
+  const transition =
+    payload && typeof payload === "object" && Object.hasOwn(payload, "currentPhase");
+  if (existed && !transition) return;
+  next.hostSessionId = sid.trim();
+}
+
 /**
  * @param {object} base
  * @param {object} patch
@@ -397,6 +499,8 @@ async function main() {
         }
       }
       next = deepMerge(current, payload);
+      clearStopGuardHalt(next, current, payload);
+      clearPassedWait(next, current, payload);
     }
 
     // A state document is an object. Anything else cannot carry `rev`, and
@@ -415,9 +519,11 @@ async function main() {
     // would tell the next reader that nothing changed.
     let priorRev = Number.isInteger(next.rev) ? next.rev : 0;
     let diskRev = null;
+    let diskStatus = null;
     if (existsSync(path)) {
       try {
         const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        diskStatus = parsed?.status ?? null;
         if (Number.isInteger(parsed?.rev)) {
           diskRev = parsed.rev;
           priorRev = Math.max(priorRev, parsed.rev);
@@ -448,7 +554,15 @@ async function main() {
       }
     }
 
+    const refusal = completionRefusal(next, payload, replace, diskStatus);
+    if (refusal) {
+      console.error(refusal);
+      releaseLock(path);
+      process.exit(6);
+    }
+
     next.rev = priorRev + 1;
+    stampHostSession(next, payload, fileExistedBefore);
 
     const unknown = undeclaredKeys(payload, replace ? {} : current);
     if (unknown.length) {

package/pipeline/skills/.skill-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-10-24T11:39:37Z",
+  "generatedAt": "2026-10-24T14:34:39Z",
   "skillCount": 234,
   "entries": [
     {