@mmerterden/multi-agent-pipeline 20.24.0 → 20.25.0

package/pipeline/scripts/edit-syntax-gate.mjs

@@ -2,10 +2,23 @@
 /**
  * edit-syntax-gate.mjs  -  parse the file an edit just wrote, report a syntax error.
  *
- * Called by edit-syntax-gate.sh as a PostToolUse hook on Edit / Write /
- * MultiEdit. Picks one parser by extension, runs it under a short deadline and,
- * when the file does not parse, prints the Claude Code PostToolUse context
- * object so the model sees the error before its next step:
+ * Called by edit-syntax-gate.sh as a PostToolUse hook. Three hosts' payloads
+ * are read (editedFiles):
+ *
+ *   Claude Code   tool_name Edit / Write / MultiEdit, tool_input.file_path
+ *   Copilot CLI   toolName edit / create, toolArgs.path (toolArgs arrives as a
+ *                 JSON string); the VS Code-compatible snake_case form carries
+ *                 tool_name and tool_input.path instead. Read and answered,
+ *                 but not registered by the pipeline: as of 1.0.45 Copilot
+ *                 CLI discards postToolUse output and applies no matcher
+ *   Codex         tool_name apply_patch, tool_input.command holding the patch
+ *                 text; every file it adds, updates or moves to is checked
+ *
+ * For each edited file it picks one parser by extension, runs it under a short
+ * deadline and, when the file does not parse, prints the context object that
+ * host reads back (hookSpecificOutput.additionalContext on Claude Code and
+ * Codex, a top-level additionalContext on Copilot CLI) so the model sees the
+ * error before its next step:
  *
  *   .swift              swiftc -parse (when swiftc is on PATH)
  *   .js .mjs .cjs       node --check (a file that looks like JSX: skipped)
@@ -25,6 +38,10 @@
  * the edit's fault, and a false alarm costs more than a missed one: the build
  * still catches what this lets through.
  *
+ * One hook call checks at most 8 files within about 8 s overall (the hook is
+ * killed at 10 s); files past either limit are not checked, and their count
+ * is added to a message that reports an error.
+ *
  * Exit 0 always.
  *
  * @module pipeline/scripts/edit-syntax-gate
@@ -37,8 +54,12 @@ import { basename, extname, join, resolve, sep } from "node:path";
 
 import { invokedDirectly } from "../lib/invoked-directly.mjs";
 
-const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit"]);
+const CLAUDE_EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit"]);
+const COPILOT_EDIT_TOOLS = new Set(["edit", "create"]);
+const CODEX_PATCH_TOOL = "apply_patch";
 const DEADLINE_MS = 2000;
+const BUDGET_MS = 8000;
+const MAX_FILES = 8;
 const MAX_BYTES = 5 * 1024 * 1024;
 const MAX_LINES = 6;
 const MAX_CHARS = 800;
@@ -196,15 +217,128 @@ function brief(output) {
   return text.length > MAX_CHARS ? `${text.slice(0, MAX_CHARS)}...` : text;
 }
 
-/** The PostToolUse context object for a syntax error, or null. */
-export function message(file, result) {
+const PATCH_TARGET = /^\*\*\* (?:Add File|Update File|Move to): (.+)$/;
+const PATCH_MOVE = /^\*\*\* Move to: /;
+
+/**
+ * The files an apply_patch leaves on disk, in patch order: every added and
+ * updated file, with a moved file named by its new path. Deleted files are
+ * gone, so they are not listed.
+ */
+export function patchFiles(patch) {
+  if (typeof patch !== "string") return [];
+  const out = [];
+  for (const line of patch.split(/\r?\n/)) {
+    const m = line.match(PATCH_TARGET);
+    if (!m) continue;
+    const path = m[1].trim();
+    if (!path) continue;
+    if (PATCH_MOVE.test(line) && out.length) out[out.length - 1] = path;
+    else out.push(path);
+  }
+  return [...new Set(out)];
+}
+
+function argsObject(raw) {
+  if (raw && typeof raw === "object") return raw;
+  if (typeof raw !== "string") return null;
+  try {
+    const v = JSON.parse(raw);
+    return v && typeof v === "object" ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Which host sent `payload` and the absolute paths it edited, or null for a
+ * call that wrote no file. Relative paths resolve against the payload's cwd,
+ * else the process cwd: the checkers run in a scratch directory.
+ *
+ * @returns {{host: "claude"|"copilot"|"copilot-vscode"|"codex", files: string[]} | null}
+ */
+export function editedFiles(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  const base = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
+  const abs = (paths) =>
+    paths.filter((p) => typeof p === "string" && p).map((p) => resolve(base, p));
+  let host;
+  let paths;
+  if (typeof payload.toolName === "string") {
+    if (!COPILOT_EDIT_TOOLS.has(payload.toolName)) return null;
+    host = "copilot";
+    paths = [argsObject(payload.toolArgs)?.path];
+  } else if (payload.tool_name === CODEX_PATCH_TOOL) {
+    host = "codex";
+    paths = patchFiles(payload.tool_input?.command);
+  } else if (CLAUDE_EDIT_TOOLS.has(payload.tool_name)) {
+    host = "claude";
+    paths = [payload.tool_input?.file_path];
+  } else if (COPILOT_EDIT_TOOLS.has(payload.tool_name)) {
+    host = "copilot-vscode";
+    const input = argsObject(payload.tool_input);
+    paths = [input?.path ?? input?.file_path];
+  } else {
+    return null;
+  }
+  const files = abs(paths);
+  return files.length ? { host, files } : null;
+}
+
+function report(file, result) {
+  return `edit-syntax-gate: ${file} no longer parses (${result.checker}). Fix it before going on:\n${brief(result.output)}`;
+}
+
+function contextFor(text, host) {
+  if (host === "copilot") return { additionalContext: text };
+  return { hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: text } };
+}
+
+/** The PostToolUse context object `host` reads for a syntax error, or null. */
+export function message(file, result, host = "claude") {
   if (!result || result.ok) return null;
-  return {
-    hookSpecificOutput: {
-      hookEventName: "PostToolUse",
-      additionalContext: `edit-syntax-gate: ${file} no longer parses (${result.checker}). Fix it before going on:\n${brief(result.output)}`,
-    },
-  };
+  return contextFor(report(file, result), host);
+}
+
+/**
+ * Check `files` in order within the hook's time: at most `maxFiles` of them,
+ * and none started once a further parser deadline would overrun `budgetMs`
+ * (the hook itself is killed at 10 s). Files left over are not checked, and
+ * their count is always reported: appended to the error message, or as a note
+ * of its own when every checked file parsed, so a skipped file that may be
+ * broken is not passed off as clean.
+ *
+ * @returns {{reports: string[], skipped: number, text: string|null}}
+ */
+export function checkEdited(
+  files,
+  { budgetMs = BUDGET_MS, maxFiles = MAX_FILES, now = Date.now } = {},
+) {
+  const start = now();
+  const reports = [];
+  let checked = 0;
+  let i = 0;
+  for (; i < files.length; i++) {
+    if (checked >= maxFiles || now() - start + DEADLINE_MS > budgetMs) break;
+    const file = files[i];
+    let st;
+    try {
+      st = statSync(file);
+    } catch {
+      continue;
+    }
+    if (!st.isFile() || st.size > MAX_BYTES) continue;
+    checked++;
+    const result = checkFile(file);
+    if (result && !result.ok) reports.push(report(file, result));
+  }
+  const skipped = files.length - i;
+  let text = reports.length ? reports.join("\n\n") : null;
+  if (text && skipped)
+    text += `\n\n(${skipped} more file(s) not checked: time or file-count limit)`;
+  else if (skipped)
+    text = `edit-syntax-gate: the checked files parse; ${skipped} file(s) not checked (time or file-count limit), so their syntax is unknown.`;
+  return { reports, skipped, text };
 }
 
 async function main() {
@@ -214,23 +348,11 @@ async function main() {
   } catch {
     return;
   }
-  if (!EDIT_TOOLS.has(payload?.tool_name)) return;
-  const raw = payload?.tool_input?.file_path;
-  if (typeof raw !== "string" || !raw) return;
-  // The checkers run in a scratch directory, so a relative path is made
-  // absolute here, against the session's cwd when the payload names one.
-  const base = typeof payload.cwd === "string" && payload.cwd ? payload.cwd : process.cwd();
-  const file = resolve(base, raw);
+  const edit = editedFiles(payload);
+  if (!edit) return;
   if (!gateEnabled()) return;
-  let st;
-  try {
-    st = statSync(file);
-  } catch {
-    return;
-  }
-  if (!st.isFile() || st.size > MAX_BYTES) return;
-  const out = message(file, checkFile(file));
-  if (out) process.stdout.write(`${JSON.stringify(out)}\n`);
+  const { text } = checkEdited(edit.files);
+  if (text) process.stdout.write(`${JSON.stringify(contextFor(text, edit.host))}\n`);
 }
 
 // Fail open: a gate bug must not surface as a hook error on every edit.

package/pipeline/scripts/edit-syntax-gate.sh

@@ -1,17 +1,20 @@
 #!/usr/bin/env bash
 # edit-syntax-gate.sh  -  PostToolUse syntax check for the multi-agent pipeline.
 #
-# Runs after an Edit / Write / MultiEdit and parses the edited file with the
+# Runs after a file edit (Claude Code Edit / Write / MultiEdit, Codex
+# apply_patch) and parses the edited file with the
 # fastest parser its extension has, so a broken file is reported in the turn
 # that broke it instead of at the next build. The parsing is in
 # edit-syntax-gate.mjs; this wrapper exists because every hook the pipeline
-# registers is a `bash "$HOME/.claude/scripts/<name>"` command.
+# registers is a `bash "$HOME/.<host>/scripts/<name>"` command.
 #
-# Contract (Claude Code PostToolUse hook):
+# Contract (PostToolUse hook on each host):
 #   - Reads the tool-call JSON on stdin.
-#   - On a parse error prints {"hookSpecificOutput": {"hookEventName":
-#     "PostToolUse", "additionalContext": "..."}} on stdout, which the model
-#     reads as context for its next step.
+#   - On a parse error prints the context object the host reads back on
+#     stdout ({"hookSpecificOutput": {"hookEventName": "PostToolUse",
+#     "additionalContext": "..."}}), which the model reads as context for its
+#     next step. Copilot CLI's payload is read too, but the pipeline does not
+#     register the hook there: as of 1.0.45 Copilot discards its output.
 #   - Exits 0 on every path: the edit has already happened, so blocking would
 #     only hide the message.
 #

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())

package/pipeline/scripts/output-quality-check.sh

@@ -121,7 +121,7 @@ try:
 except Exception:
     sys.exit(0)
 # named, decimal and hex - a pattern covering only the named forms would miss
-# exactly the two spellings the first version of the decoder missed.
+# the decimal and hex spellings.
 pat = re.compile(r'&(amp|lt|gt|quot|apos|nbsp|mdash|ndash|hellip|#[0-9]+|#[xX][0-9a-fA-F]+);')
 for p in d.get('phases', []):
     n = p.get('name', '')

package/pipeline/scripts/phase-tracker.sh

@@ -230,8 +230,8 @@ usage_live_ping() {
 #
 # The program is fed through a QUOTED heredoc, not `node -e '...'`. Inside a
 # single-quoted shell string every apostrophe in the JS (and in its comments)
-# terminates the string early; shellcheck flags it as SC2140 and the first version
-# here worked only by accident of where the quotes happened to fall. A quoted
+# terminates the string early; shellcheck flags it as SC2140, and such code works
+# only by accident of where the quotes happen to fall. A quoted
 # heredoc passes the body through verbatim, so the JS can use any quote it likes.
 decode_entities() {
   local raw="$1" out
@@ -561,7 +561,7 @@ release_state_lock() {
 trap release_state_lock EXIT
 
 # The cost table is keyed by family ("opus", "sonnet", "gpt-5.6"), but the name
-# an agent has at hand is the full id ("claude-opus-5"). Storing the id verbatim
+# an agent has at hand is the full id ("claude-opus-5-5"). Storing the id verbatim
 # priced every phase at "-" while the tracker looked perfectly healthy, so the
 # family is resolved here, once, and an unresolvable name is said out loud
 # instead of quietly costing nothing.
@@ -1183,9 +1183,8 @@ case "$ACTION" in
     esac
     # Accounting gate. A phase that ran LLM work and recorded nothing produces a
     # completion line with nothing to say and a cost breakdown that reads as
-    # unavailable - which is exactly how per-phase token reporting went missing
-    # for months while every gate stayed green, because the gates lint the docs
-    # for the CALL and nothing checks that the call happened. Refusing the
+    # unavailable. The gates lint the docs for the CALL; only this point can
+    # check that the call happened. Refusing the
     # completion is recoverable (record, then re-run) and loses no work; a
     # phase that genuinely made no LLM call says so with --no-llm.
     if [ "$STATUS" = "completed" ] && [ "$NO_LLM" -eq 0 ]; then

package/pipeline/scripts/phase0-exit-gate.mjs

@@ -146,9 +146,9 @@ export function evaluate(state, extraInput = "", { env = process.env } = {}) {
     );
   }
 
-  // Step 3 picks the base branch and Step 8 creates the worktree. A run that skipped
-  // both develops on whatever the checkout happened to have, which is how a Jira task
-  // got implemented on a stale local branch with no picker ever shown. The state file
+  // Step 3 picks the base branch and Step 8 creates the worktree. A run that skips
+  // both develops on whatever the checkout happens to have: a Jira task implemented
+  // on a stale local branch with no picker ever shown. The state file
   // is the only durable evidence those steps ran, so it has to carry their output.
   //
   // `local` provider runs still choose a base branch; what they skip is push and PR.

package/pipeline/scripts/pre-push-check.sh

@@ -11,12 +11,9 @@
 #   broken commit and npm.
 #
 #   It therefore runs the CANONICAL chain, `npm test`, rather than a hand-picked
-#   subset. The subset it used to run was missing eight of the eleven steps
-#   (lint-skills, lint-mcp-refs, three of the four evals, validate-prefs,
-#   scorecard) and drove the smoke suites through the bare
-#   `for f in smoke-*.sh` loop that run-smokes.mjs was written to replace,
-#   because that loop cannot tell a passing suite from one that exited 0 having
-#   asserted nothing. A safety net with holes in it is worse than a known gap:
+#   subset. A subset drifts from the chain as steps are added, and a bare
+#   `for f in smoke-*.sh` loop cannot tell a passing suite from one that exited 0
+#   having asserted nothing; run-smokes.mjs can. A safety net with holes in it is worse than a known gap:
 #   it is trusted.
 #
 # Two modes, because a gate that runs INSIDE the push is a gate that breaks