@mmerterden/multi-agent-pipeline 20.23.2 → 20.25.0

package/pipeline/scripts/gate-ledger.mjs

@@ -52,6 +52,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, realpathSync, renameSync, 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 { attendedVerdict, gatesActive } from "../lib/unattended.mjs";
@@ -316,6 +317,9 @@ export async function recordQuietly(gate, verdict, detail, opts) {
  * Park an unattended run for a person. The runner reads `waitingFor` as
  * awaiting-answer and `verificationFailed` as verification-failed.
  *
+ * Parking is the run deciding not to go on, so the same write appends the
+ * entry to `decisions[]` that the Phase 5 report and the PR body list.
+ *
  * @param {string} path
  * @param {{outcome: "awaiting-answer"|"verification-failed", waitingFor?: string,
  *          gate?: string, reason?: string}} opts
@@ -327,26 +331,55 @@ export async function park(path, { outcome, waitingFor, gate, reason = "", pendi
     if (waitingFor === "question" && !pendingQuestion) {
       throw new LedgerError("usage", "waitingFor question needs a pendingQuestion to answer");
     }
-    return updateState(path, (s) => ({
-      ...s,
-      waitingFor,
-      ...(pendingQuestion ? { pendingQuestion } : {}),
-      status: "awaiting_input",
-      haltReason: reason || `waiting for ${waitingFor}`,
-    }));
+    return updateState(path, (s) =>
+      withDecision(
+        {
+          ...s,
+          waitingFor,
+          ...(pendingQuestion ? { pendingQuestion } : {}),
+          status: "awaiting_input",
+          haltReason: reason || `waiting for ${waitingFor}`,
+        },
+        decisionEntry({
+          what: `Parked the run to wait for ${waitingFor}`,
+          why: reason || `waiting for ${waitingFor}`,
+          costIfWrong:
+            "the run stops until someone answers, even if the default would have been fine",
+          phase: phaseOf(s),
+          at,
+        }),
+      ),
+    );
   }
   if (outcome === "verification-failed") {
     if (!gate) throw new LedgerError("usage", "verification-failed needs --gate");
-    return updateState(path, (s) => ({
-      ...s,
-      status: "failed",
-      verificationFailed: { gate, reason, at },
-      haltReason: `verification failed at ${gate}: ${reason}`,
-    }));
+    return updateState(path, (s) =>
+      withDecision(
+        {
+          ...s,
+          status: "failed",
+          verificationFailed: { gate, reason, at },
+          haltReason: `verification failed at ${gate}: ${reason}`,
+        },
+        decisionEntry({
+          what: `Parked the run: ${gate} rejected the work`,
+          why: reason || `${gate} failed`,
+          costIfWrong: "work that would have passed is held back until someone resumes it",
+          phase: phaseOf(s),
+          at,
+        }),
+      ),
+    );
   }
   throw new LedgerError("usage", `unknown outcome ${outcome}`);
 }
 
+/** The run's current phase, held to the 0..5 range a decision entry takes. */
+function phaseOf(state) {
+  const n = Number(state?.currentPhase);
+  return Number.isInteger(n) ? Math.min(5, Math.max(0, n)) : 0;
+}
+
 /**
  * Latest entry per gate for one sha. "Latest" is by `at`, then by position.
  */

package/pipeline/scripts/gc-abandoned.sh

@@ -388,8 +388,8 @@ $d"
       # Rule 1 again: landed work is not residue, whichever pass finds it. Order
       # matters here - the waiting-phase test is a proxy for "still waiting", and
       # a run whose status already says it FINISHED is not waiting for anyone. A
-      # complete run sitting at the report phase was read as waiting and never
-      # reaped, which is how three finished worktrees held 5.1 GB indefinitely.
+      # complete run sitting at the report phase would otherwise read as waiting
+      # and never be reaped, holding its worktree indefinitely.
       case "$st" in
         complete | completed | failed) ;;
         awaiting_input)

package/pipeline/scripts/gen-mode-dispatch.mjs

@@ -33,9 +33,9 @@ const args = Object.fromEntries(
 
 const MODE = args.mode;
 
-// The phase list has one owner: schemas/phases.json. This file used to restate
-// it, which is how eight independent copies came to exist. smoke-phase-contract.sh
-// holds every remaining copy to the same file.
+// The phase list has one owner: schemas/phases.json. This file reads it rather
+// than restating it, and smoke-phase-contract.sh holds every remaining copy to
+// the same file.
 const CONTRACT = JSON.parse(
   readFileSync(new URL("../schemas/phases.json", import.meta.url), "utf8"),
 );

package/pipeline/scripts/git-path.mjs

@@ -8,8 +8,7 @@
  * `diff --name-only` as `"G\303\266r\303\274n\303\274m.swift"`, quotes and all.
  * A consumer that treats that string as a path sees a name that matches no
  * glob, resolves to no file, and simply DISAPPEARS from whatever it was
- * feeding - which is how every non-ASCII-named file was once silently dropped
- * from risk scoring.
+ * feeding: a non-ASCII-named file silently drops out of risk scoring.
  *
  * Shared rather than copied because the failure is silent on every axis that
  * uses it: a dropped file is not an error anywhere, it is an absence.

package/pipeline/scripts/host-hooks.mjs

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+/**
+ * @file host-hooks.mjs  -  register the pipeline's hooks on Codex.
+ *
+ * Claude Code's hooks are merged into ~/.claude/settings.json by
+ * /multi-agent:setup Step 8 from install/templates/claude-hooks.json. Codex
+ * reads hooks from <CODEX_HOME|~/.codex>/hooks.json, shared with the user's
+ * own hooks, so this does the same merge there from the template the
+ * installer copied into ~/.codex/templates (~/.codex whether or not
+ * CODEX_HOME is set): a template group is added only
+ * when its full commands are not already registered, and remove takes out
+ * only the handlers whose full command is one the template registers
+ * (refusing when the template is missing). A file that does not parse or is
+ * not shaped like a hooks file is left untouched and the call fails.
+ *
+ * Copilot CLI is not managed: as of 1.0.45 it loads ~/.copilot/hooks/*.json
+ * but discards a postToolUse hook's output and applies no matcher, so the
+ * syntax gate would cost a spawn per tool call and tell the model nothing.
+ *
+ * Codex runs a user hook only after it has been reviewed and trusted in its
+ * /hooks view, so install says so.
+ *
+ * Usage: host-hooks.mjs <install|remove|status> --host codex [--dry-run]
+ * Exit codes: 0 done | 1 a file could not be read or written | 2 usage
+ *
+ * @module pipeline/scripts/host-hooks
+ */
+
+import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { writeJsonAtomicSync } from "../lib/json-file-lock.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+const PIPELINE_SCRIPT = /\/scripts\/([A-Za-z0-9_.-]+\.(?:sh|mjs))\b/;
+
+/**
+ * Where `host` keeps its hooks and where the installer put the template.
+ * Null for a host this does not manage.
+ */
+export function hostPaths(host, env = process.env) {
+  const home = env.HOME || homedir();
+  if (host !== "codex") return null;
+  // install/codex.mjs always installs under ~/.codex, while Codex reads its
+  // hooks from $CODEX_HOME when that is set.
+  const installDir = join(home, ".codex");
+  return {
+    template: join(installDir, "templates", "codex-hooks.json"),
+    hooksFile: join(env.CODEX_HOME || installDir, "hooks.json"),
+    home,
+  };
+}
+
+/** The command strings a hook group runs (`command`, or a flat handler's `bash`). */
+function commandsOf(group) {
+  const handlers = Array.isArray(group?.hooks) ? group.hooks : [group];
+  return handlers.flatMap((h) => [h?.command, h?.bash]).filter((c) => typeof c === "string");
+}
+
+const normalize = (command) => command.trim().replace(/\s+/g, " ");
+
+/**
+ * The full command strings `template` registers, each also with `$HOME`
+ * expanded to `home`, normalised for whitespace. A hook is the pipeline's
+ * only when its command is one of these: matching on a script name alone
+ * would take a user hook that runs some other `scripts/<name>.sh`.
+ */
+export function templateCommands(template, home = null) {
+  const out = new Set();
+  for (const group of Object.values(template?.hooks || {}).flat()) {
+    for (const command of commandsOf(group)) {
+      out.add(normalize(command));
+      if (home) out.add(normalize(command.replace(/\$\{HOME\}|\$HOME\b/g, home)));
+    }
+  }
+  return out;
+}
+
+const isPlainObject = (v) =>
+  v !== null && typeof v === "object" && Object.getPrototypeOf(v) === Object.prototype;
+
+/**
+ * Throws unless `doc` has the shape a hooks file has: a plain-object root, a
+ * plain-object `hooks` when present, and an array for every event in it.
+ * Anything else is a file this does not understand, and rewriting it would
+ * lose what is there.
+ */
+function assertHooksShape(doc) {
+  if (!isPlainObject(doc)) throw new Error("the hooks file's root is not a JSON object");
+  if (doc.hooks === undefined) return;
+  if (!isPlainObject(doc.hooks)) throw new Error("the hooks file's `hooks` is not a JSON object");
+  for (const [event, groups] of Object.entries(doc.hooks)) {
+    if (!Array.isArray(groups)) throw new Error(`the hooks file's \`${event}\` is not an array`);
+  }
+}
+
+/**
+ * `existing` with every template group added whose commands are not all
+ * already registered for the same event (compared as full commands, also
+ * with `$HOME` expanded to `home`). Never edits a group. Throws on a document
+ * that is not shaped like a hooks file.
+ */
+export function mergeHooks(existing, template, home = null) {
+  const doc = structuredClone(existing ?? {});
+  assertHooksShape(doc);
+  if (!doc.hooks) doc.hooks = {};
+  let added = 0;
+  for (const [event, groups] of Object.entries(template?.hooks || {})) {
+    const current = doc.hooks[event] || [];
+    const present = new Set(current.flatMap(commandsOf).map(normalize));
+    for (const group of Array.isArray(groups) ? groups : []) {
+      const commands = [...templateCommands({ hooks: { [event]: [group] } })];
+      const known = (c) =>
+        present.has(c) || (home && present.has(normalize(c.replace(/\$\{HOME\}|\$HOME\b/g, home))));
+      if (commands.length && commands.every(known)) continue;
+      current.push(structuredClone(group));
+      commands.forEach((c) => present.add(c));
+      added++;
+    }
+    doc.hooks[event] = current;
+  }
+  return { doc, added };
+}
+
+/**
+ * `doc` without the handlers whose full command is in `commands` (from
+ * templateCommands). A group left with no handler is dropped, then an event
+ * left with no group. Throws when `commands` is empty: without the template
+ * there is no way to tell the pipeline's hooks from the user's.
+ */
+export function removeHooks(doc, commands) {
+  if (!(commands instanceof Set) || !commands.size)
+    throw new Error("no hook template to identify the pipeline's hooks");
+  const out = structuredClone(doc ?? {});
+  assertHooksShape(out);
+  let removed = 0;
+  if (!out.hooks) return { doc: out, removed };
+  const ours = (handler) =>
+    [handler?.command, handler?.bash].some(
+      (c) => typeof c === "string" && commands.has(normalize(c)),
+    );
+  for (const [event, groups] of Object.entries(out.hooks)) {
+    if (!Array.isArray(groups)) continue;
+    const kept = [];
+    for (const group of groups) {
+      if (!Array.isArray(group?.hooks)) {
+        if (ours(group)) removed++;
+        else kept.push(group);
+        continue;
+      }
+      const handlers = group.hooks.filter((h) => !ours(h));
+      removed += group.hooks.length - handlers.length;
+      if (handlers.length === group.hooks.length) kept.push(group);
+      else if (handlers.length) kept.push({ ...group, hooks: handlers });
+    }
+    if (kept.length) out.hooks[event] = kept;
+    else delete out.hooks[event];
+  }
+  if (!Object.keys(out.hooks).length) delete out.hooks;
+  return { doc: out, removed };
+}
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+/**
+ * Write `doc` to `path` atomically. A symlinked file (a dotfiles repo) is
+ * written through to its target, and an existing file keeps its mode.
+ */
+function writeHooksFile(path, doc) {
+  let mode = 0o644;
+  try {
+    mode = statSync(path).mode & 0o777;
+  } catch {
+    // A new file gets the default mode.
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeJsonAtomicSync(path, doc, { mode, followSymlink: true });
+}
+
+function install(paths, dryRun, log) {
+  const template = readJson(paths.template);
+  const existing = existsSync(paths.hooksFile) ? readJson(paths.hooksFile) : {};
+  const { doc, added } = mergeHooks(existing, template, paths.home);
+  if (added && !dryRun) writeHooksFile(paths.hooksFile, doc);
+  log(
+    added
+      ? `${dryRun ? "would add" : "added"} ${added} hook group(s) to ${paths.hooksFile}`
+      : `already registered in ${paths.hooksFile}`,
+  );
+  log("Codex runs a new user hook only once it is trusted: open /hooks in Codex and trust it.");
+}
+
+function remove(paths, dryRun, log) {
+  if (!existsSync(paths.hooksFile)) {
+    log(`nothing to remove: ${paths.hooksFile} does not exist`);
+    return;
+  }
+  if (!existsSync(paths.template))
+    throw new Error(`${paths.template} is missing, so the pipeline's hooks cannot be told apart`);
+  const commands = templateCommands(readJson(paths.template), paths.home);
+  const { doc, removed } = removeHooks(readJson(paths.hooksFile), commands);
+  if (removed && !dryRun) writeHooksFile(paths.hooksFile, doc);
+  log(
+    removed
+      ? `${dryRun ? "would remove" : "removed"} ${removed} hook group(s) from ${paths.hooksFile}`
+      : `no pipeline hook in ${paths.hooksFile}`,
+  );
+}
+
+function status(paths, log) {
+  if (!existsSync(paths.hooksFile)) {
+    log(`not installed (${paths.hooksFile} does not exist)`);
+    return;
+  }
+  if (!existsSync(paths.template)) {
+    log(`unknown: ${paths.template} is missing, so the pipeline's hooks cannot be told apart`);
+    return;
+  }
+  const commands = templateCommands(readJson(paths.template), paths.home);
+  const doc = readJson(paths.hooksFile);
+  assertHooksShape(doc);
+  const found = Object.values(doc.hooks || {})
+    .flat()
+    .flatMap(commandsOf)
+    .filter((c) => commands.has(normalize(c)))
+    .map((c) => (c.match(PIPELINE_SCRIPT) || [])[1] || c);
+  log(
+    found.length
+      ? `installed: ${[...new Set(found)].join(", ")} in ${paths.hooksFile}`
+      : `not installed in ${paths.hooksFile}`,
+  );
+}
+
+const ACTIONS = new Set(["install", "remove", "status"]);
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const action = argv[0];
+  const hostAt = argv.indexOf("--host");
+  const host = hostAt >= 0 ? argv[hostAt + 1] : null;
+  const dryRun = argv.includes("--dry-run");
+  const paths = hostPaths(host);
+  if (!ACTIONS.has(action) || !paths) {
+    process.stderr.write(
+      "usage: host-hooks.mjs <install|remove|status> --host codex [--dry-run]\n",
+    );
+    process.exitCode = 2;
+    return;
+  }
+  const log = (line) => process.stdout.write(`${line}\n`);
+  try {
+    if (action === "install") install(paths, dryRun, log);
+    else if (action === "remove") remove(paths, dryRun, log);
+    else status(paths, log);
+  } catch (err) {
+    process.stderr.write(`host-hooks: ${err.message}; nothing was changed\n`);
+    process.exitCode = 1;
+  }
+}
+
+if (invokedDirectly(import.meta.url)) runMain("host-hooks", main, { code: 1 });

package/pipeline/scripts/jira-attach.sh

@@ -3,7 +3,7 @@
 # jira-attach.sh  -  upload one or more files as Jira issue attachments and print
 # the filename plus the URL of each, one per line, tab-separated.
 #
-# Two callers need this and they used to carry their own curl: the issue
+# Two callers need this, and they share it rather than each carrying a curl: the issue
 # generator (`generate-issue.md` step 12) and visual evidence (Phase 3 / Phase 5
 # captures rendered into the Phase 5 Jira comment). Two copies of an upload is
 # two places for the `X-Atlassian-Token: no-check` header to go missing, which

package/pipeline/scripts/keychain.py

@@ -218,9 +218,9 @@ def set_(label: str, value: str, account: Optional[str] = None) -> None:
 
     # The secret goes in as `-X <hex>`, not `-w "<text>"`. `security -i`
     # tokenizes ONE command per line, so a newline inside the value ends the
-    # command and the remainder is read as further commands - which is how a
-    # service-account JSON turned into "security: unknown command" instead of
-    # a stored credential. Hex is single-line by construction and byte-exact,
+    # command and the remainder is read as further commands, so a multi-line
+    # service-account JSON becomes "security: unknown command" instead of a
+    # stored credential. Hex is single-line by construction and byte-exact,
     # and it stays on stdin, so the argv exposure this branch exists to avoid
     # is still avoided.
     target = "".join(f' "{quote(k)}"' for k in _keychain())