@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/scripts/pr-request.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * @file pr-request.mjs  -  write and validate the PR request an unattended
+ * Phase 4 leaves for the autopilot runner.
+ *
+ * Under MULTI_AGENT_UNATTENDED=1 the run does not push and does not open a PR:
+ * agent-guard blocks both. Phase 4 calls `write` instead, and the runner, after
+ * the run exits, calls `validate`, checks the branch it can see, pushes it and
+ * opens the PR as a draft. The run never hand-writes the JSON, so the file is
+ * always well-formed and always passed the outbound gate.
+ *
+ * Rules beyond pr-request.schema.json:
+ *   - branch and base are ref names that do not start with `-` and hold no
+ *     `..`, so neither can be read as an option or a range where it is passed
+ *     on;
+ *   - the branch is not main, master or develop, and is not the base;
+ *   - which base is acceptable is the runner's decision, not the request's:
+ *     autopilot-publish.mjs accepts the configured `baseBranch`, else the
+ *     remote's default branch, plus any base listed in `allowedBases`;
+ *   - no auto-close keyword (Closes / Fixes / Resolves #N) in title or body,
+ *     because issues are closed by people;
+ *   - title and body pass lib/outbound-gate.mjs: a certain finding (a token
+ *     shape) exits 7 and nothing is written. Findings are reported by rule and
+ *     line, never by value.
+ *
+ * Usage:
+ *   node pr-request.mjs write --branch <b> --base <b> --title <t> --body-file <f> --repo <owner/name> [--out <path>]
+ *   node pr-request.mjs validate --file <path>
+ *
+ * `write` puts the file at lib/pr-request-location.mjs prRequestPath(), named
+ * for MULTI_AGENT_SESSION_ID, unless --out is given. Mode 0600 in a 0700
+ * directory, written through a temp file and a rename.
+ *
+ * Output: one JSON object on stdout. Exit: 0 ok, 1 invalid, 2 usage, 7 secret.
+ *
+ * @module pipeline/scripts/pr-request
+ */
+
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { scan } from "../lib/outbound-gate.mjs";
+import { prRequestPath } from "../lib/pr-request-location.mjs";
+
+export const FIELDS = ["branch", "base", "title", "body", "draft", "repo"];
+export const PROTECTED_BRANCHES = ["main", "master", "develop"];
+const REF = /^[A-Za-z0-9._/-]+$/;
+const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const AUTO_CLOSE = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s*:?\s+(?:[\w.-]+\/[\w.-]+)?#\d+/i;
+
+/**
+ * The request object `write` produces. draft is always true.
+ *
+ * @param {{branch:string, base:string, title:string, body:string, repo:string}} f
+ */
+export function buildPrRequest(f) {
+  return {
+    branch: f.branch,
+    base: f.base,
+    title: f.title,
+    body: f.body,
+    draft: true,
+    repo: f.repo,
+  };
+}
+
+const str = (v, min, max) => typeof v === "string" && v.length >= min && v.length <= max;
+
+/** A branch name that cannot be read as an option (`-x`) or a range (`a..b`). */
+const isRef = (v) => str(v, 1, 255) && REF.test(v) && !v.startsWith("-") && !v.includes("..");
+
+/**
+ * @param {unknown} req
+ * @returns {{errors: string[], secrets: {rule:string, line:number, field:string}[]}}
+ */
+export function validatePrRequest(req) {
+  const errors = [];
+  if (!req || typeof req !== "object" || Array.isArray(req)) {
+    return { errors: ["the request is not a JSON object"], secrets: [] };
+  }
+  for (const k of Object.keys(req)) if (!FIELDS.includes(k)) errors.push(`unknown field: ${k}`);
+  for (const k of FIELDS) if (!(k in req)) errors.push(`missing field: ${k}`);
+  if ("branch" in req && !isRef(req.branch)) errors.push("branch is not a ref name");
+  if ("base" in req && !isRef(req.base)) errors.push("base is not a ref name");
+  if ("title" in req && !str(req.title, 1, 256)) errors.push("title must be 1-256 characters");
+  if ("body" in req && !str(req.body, 1, 65536)) errors.push("body must be 1-65536 characters");
+  if ("draft" in req && req.draft !== true) errors.push("draft must be true");
+  if ("repo" in req && !(typeof req.repo === "string" && REPO.test(req.repo)))
+    errors.push("repo must be owner/name");
+  if (typeof req.branch === "string" && PROTECTED_BRANCHES.includes(req.branch))
+    errors.push(`branch ${req.branch} is protected; the run's work belongs on its own branch`);
+  if (typeof req.branch === "string" && req.branch === req.base)
+    errors.push("branch and base are the same");
+  for (const k of ["title", "body"]) {
+    if (typeof req[k] === "string" && AUTO_CLOSE.test(req[k]))
+      errors.push(`${k} carries an auto-close keyword; use Ref: #N`);
+  }
+  const secrets = [];
+  for (const k of ["title", "body"]) {
+    if (typeof req[k] !== "string") continue;
+    for (const f of scan(req[k])) {
+      if (f.certain) secrets.push({ rule: f.rule, line: f.line, field: k });
+    }
+  }
+  return { errors, secrets };
+}
+
+function arg(args, name) {
+  const i = args.indexOf(name);
+  return i === -1 ? undefined : args[i + 1];
+}
+
+function emit(obj, code) {
+  process.stdout.write(`${JSON.stringify(obj)}\n`);
+  process.exitCode = code;
+}
+
+function writeAtomic(path, text) {
+  const dir = dirname(path);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, text, { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, path);
+}
+
+function cmdWrite(args) {
+  const need = ["--branch", "--base", "--title", "--body-file", "--repo"];
+  const missing = need.filter((n) => !arg(args, n));
+  if (missing.length) return emit({ ok: false, usage: `missing ${missing.join(", ")}` }, 2);
+  let body;
+  try {
+    body = readFileSync(arg(args, "--body-file"), "utf8");
+  } catch (err) {
+    return emit({ ok: false, usage: `cannot read --body-file: ${err.code || err.message}` }, 2);
+  }
+  let out = arg(args, "--out");
+  if (!out) {
+    try {
+      out = prRequestPath(process.env.MULTI_AGENT_SESSION_ID || "");
+    } catch {
+      return emit(
+        { ok: false, usage: "MULTI_AGENT_SESSION_ID is not a session id and no --out was given" },
+        2,
+      );
+    }
+  }
+  const req = buildPrRequest({
+    branch: arg(args, "--branch"),
+    base: arg(args, "--base"),
+    title: arg(args, "--title"),
+    body,
+    repo: arg(args, "--repo"),
+  });
+  const { errors, secrets } = validatePrRequest(req);
+  if (secrets.length) return emit({ ok: false, written: false, secrets }, 7);
+  if (errors.length) return emit({ ok: false, written: false, errors }, 1);
+  writeAtomic(out, `${JSON.stringify(req, null, 2)}\n`);
+  return emit({ ok: true, written: true, path: out }, 0);
+}
+
+function cmdValidate(args) {
+  const file = arg(args, "--file");
+  if (!file) return emit({ ok: false, usage: "validate needs --file" }, 2);
+  let req;
+  try {
+    req = JSON.parse(readFileSync(file, "utf8"));
+  } catch (err) {
+    return emit({ ok: false, errors: [`unreadable: ${err.code || "not JSON"}`] }, 1);
+  }
+  const { errors, secrets } = validatePrRequest(req);
+  if (secrets.length) return emit({ ok: false, errors, secrets }, 7);
+  return emit({ ok: errors.length === 0, errors }, errors.length ? 1 : 0);
+}
+
+function main() {
+  const [sub, ...args] = process.argv.slice(2);
+  if (sub === "write") return cmdWrite(args);
+  if (sub === "validate") return cmdValidate(args);
+  process.stderr.write(
+    "usage: pr-request.mjs write --branch <b> --base <b> --title <t> --body-file <f> --repo <owner/name> [--out <path>]\n" +
+      "       pr-request.mjs validate --file <path>\n",
+  );
+  process.exitCode = 2;
+}
+
+if (invokedDirectly(import.meta.url)) main();

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

@@ -14,6 +14,11 @@
 
 set -uo pipefail
 
+PRE_COMMIT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=../lib/unattended.sh
+if [ -f "$PRE_COMMIT_DIR/../lib/unattended.sh" ]; then . "$PRE_COMMIT_DIR/../lib/unattended.sh"; fi
+command -v ma_unattended >/dev/null 2>&1 || ma_unattended() { [ "${MULTI_AGENT_UNATTENDED:-}" = "1" ]; }
+
 # Hook-mode fast exit. The Claude Code PreToolUse matcher is the tool name
 # ("Bash"), so this script now fires for EVERY Bash call and receives JSON on
 # stdin: {"tool_name":"Bash","tool_input":{"command":"..."}}. Extract the
@@ -22,6 +27,9 @@ set -uo pipefail
 # fall through to the full scan. Extraction failure also falls through - the
 # only cost is an unnecessary scan, never a skipped one on a real commit.
 SCAN_UNSTAGED=0
+# Set only when this is the hook firing on a real `git commit`. A direct run
+# (Phase 2 Gate 4, the smokes) is the secret scan and nothing else.
+IS_COMMIT_HOOK=0
 # --scan-file <path>: run the detectors over ONE file that git knows nothing
 # about, then exit on the result. It exists so callers outside the commit path
 # can reuse these patterns instead of copying them - learn-from-transcripts.mjs
@@ -40,8 +48,21 @@ if [ "${1:-}" = "--scan-file" ]; then
   SCAN_FILE_TARGET="${2:-}"
   [ -f "$SCAN_FILE_TARGET" ] || { echo "ERR: --scan-file needs an existing path" >&2; exit 1; }
 fi
+# --scan-range <base>..<head>: run the detectors over the lines each commit in
+# the range added, file by file, the way a commit of the whole range would have
+# been scanned. The autopilot runner calls it on a branch before it pushes,
+# outside the run that made the commits (autopilot-publish.mjs), so a commit
+# that reached the branch without passing through this hook is still scanned.
+SCAN_RANGE=""
+if [ "${1:-}" = "--scan-range" ]; then
+  SCAN_RANGE="${2:-}"
+  case "$SCAN_RANGE" in
+    ?*..?*) ;;
+    *) echo "ERR: --scan-range needs <base>..<head>" >&2; exit 1 ;;
+  esac
+fi
 
-if [ -z "$SCAN_FILE_TARGET" ] && [ ! -t 0 ]; then
+if [ -z "$SCAN_FILE_TARGET" ] && [ -z "$SCAN_RANGE" ] && [ ! -t 0 ]; then
   HOOK_INPUT="$(cat 2>/dev/null || true)"
   if [ -n "$HOOK_INPUT" ]; then
     HOOK_COMMAND=""
@@ -65,10 +86,30 @@ process.stdin.on("end", () => {
 ' 2>/dev/null || true)"
     fi
     if [ -n "$HOOK_COMMAND" ]; then
-      if ! printf '%s\n' "$HOOK_COMMAND" \
+      # Commit detection is a tokenizer, not a regex: agent-guard.py shares its
+      # shell parser through `--git-subcommand`, so an absolute git path, a
+      # quoted or case-folded name, an alias and the other commands that write a
+      # commit (commit-tree, merge, cherry-pick, revert, am) are all seen the
+      # same way the guard sees them. A regex over the raw string missed every
+      # one of those. If the helper is unavailable the scan runs anyway.
+      GUARD_PY="$PRE_COMMIT_DIR/agent-guard.py"
+      GIT_SUBS=""
+      HELPER_RAN=0
+      if command -v python3 >/dev/null 2>&1 && [ -f "$GUARD_PY" ]; then
+        if GIT_SUBS="$(printf '%s' "$HOOK_INPUT" | python3 "$GUARD_PY" --git-subcommand 2>/dev/null)"; then
+          HELPER_RAN=1
+        fi
+      fi
+      if [ "$HELPER_RAN" = "1" ]; then
+        if ! printf '%s\n' "$GIT_SUBS" \
+          | grep -qxE 'commit|commit-tree|merge|cherry-pick|revert|am'; then
+          exit 0
+        fi
+      elif ! printf '%s\n' "$HOOK_COMMAND" \
         | grep -qE '(^|[^[:alnum:]_./-])git[[:space:]]+([^|&;]*[[:space:]])?commit([^[:alnum:]_-]|$)'; then
         exit 0
       fi
+      IS_COMMIT_HOOK=1
       # PreToolUse fires BEFORE the tool runs, so a compound command like
       # `git add -A && git commit -m ...` reaches this point with NOTHING
       # staged yet from either half - `git diff --cached` alone sees an
@@ -76,8 +117,9 @@ process.stdin.on("end", () => {
       # it exists to gate. When the same command also runs `git add`, widen
       # the scan to the working tree (tracked-unstaged + untracked), not
       # just the index, so that case is still caught.
-      if printf '%s\n' "$HOOK_COMMAND" \
-        | grep -qE '(^|[^[:alnum:]_./-])git[[:space:]]+add([^[:alnum:]_-]|$)'; then
+      if printf '%s\n' "$GIT_SUBS" | grep -qxF 'add' \
+        || printf '%s\n' "$HOOK_COMMAND" \
+          | grep -qE '(^|[^[:alnum:]_./-])git[[:space:]]+add([^[:alnum:]_-]|$)'; then
         SCAN_UNSTAGED=1
       fi
     fi
@@ -87,6 +129,14 @@ fi
 # Staged paths from `git diff --cached --name-only` are repo-root-relative, so
 # the `-f` tests below only see them from the repo root. Hooks fire with the
 # caller's cwd, which is often a subdirectory.
+# A `cd <dir>` or `git -C <dir>` earlier on the line moves the commit into
+# another checkout; that checkout is the one scanned.
+if [ "$IS_COMMIT_HOOK" = "1" ] && command -v python3 >/dev/null 2>&1 && [ -f "${GUARD_PY:-}" ]; then
+  COMMIT_DIR="$(printf '%s' "$HOOK_INPUT" | python3 "$GUARD_PY" --commit-dir 2>/dev/null || true)"
+  if [ -n "$COMMIT_DIR" ] && [ -d "$COMMIT_DIR" ]; then
+    cd "$COMMIT_DIR" || exit 0
+  fi
+fi
 REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
 if [ -n "$REPO_ROOT" ]; then
   cd "$REPO_ROOT" || exit 0
@@ -275,6 +325,52 @@ if [ -n "$SCAN_FILE_TARGET" ]; then
   exit 0
 fi
 
+if [ -n "$SCAN_RANGE" ]; then
+  git rev-parse --verify --quiet "${SCAN_RANGE%%..*}^{commit}" >/dev/null \
+    && git rev-parse --verify --quiet "${SCAN_RANGE##*..}^{commit}" >/dev/null \
+    || { echo "ERR: --scan-range: $SCAN_RANGE does not name two commits" >&2; exit 1; }
+  # Every commit in the range is pushed, so each one is scanned on its own,
+  # from the commit object rather than the working tree: a key added in one
+  # commit and removed in a later one is still in the pushed history.
+  range_commits=$(git rev-list --reverse "$SCAN_RANGE" 2>/dev/null) \
+    || { echo "ERR: --scan-range: cannot list commits in $SCAN_RANGE" >&2; exit 1; }
+  # The repository's own .gitattributes can mark any path `-diff` or `binary`,
+  # which would make the diff say "Binary files differ" and hide added lines
+  # from the scan. Neutralise it: GIT_ATTR_NOSYSTEM drops the system file,
+  # core.attributesFile=/dev/null drops the user file, and --attr-source with an
+  # empty tree (the empty-tree hash) drops the in-tree .gitattributes. --text
+  # forces a textual diff, and numstat's binary marker ('-') is scanned from the
+  # blob rather than skipped. GIT_LITERAL_PATHSPECS stops a crafted filename
+  # from being read as a pathspec magic prefix.
+  EMPTY_TREE=$(git hash-object -t tree /dev/null 2>/dev/null)
+  gitscan() {
+    GIT_ATTR_NOSYSTEM=1 GIT_LITERAL_PATHSPECS=1 \
+      git -c core.attributesFile=/dev/null -c core.quotePath=false \
+      ${EMPTY_TREE:+-c "diff.attributesSource=$EMPTY_TREE"} "$@"
+  }
+  for commit in $range_commits; do
+    while IFS= read -r -d '' file; do
+      [ -z "$file" ] && continue
+      content=$(gitscan diff-tree --no-commit-id -p --root -m --first-parent \
+        --no-ext-diff --no-textconv --text ${EMPTY_TREE:+--attr-source="$EMPTY_TREE"} \
+        "$commit" -- "$file" 2>/dev/null | grep "^+" | grep -v "^+++" || true)
+      if [ -z "$content" ]; then
+        # A file git still treats as binary yields no +lines; scan the whole
+        # blob at this commit so a NUL-laden file cannot hide a key.
+        content=$(gitscan show --text --no-textconv "${commit}:${file}" 2>/dev/null || true)
+      fi
+      scan_file "$file" "$content"
+    done < <(gitscan diff-tree --no-commit-id -r --root -m --first-parent \
+      --name-only -z --diff-filter=d "$commit" 2>/dev/null)
+  done
+  if [ "$FOUND" -eq 1 ]; then
+    echo "" >&2
+    echo "Secret check failed on $SCAN_RANGE." >&2
+    exit 2
+  fi
+  exit 0
+fi
+
 # NUL-delimited so filenames with spaces are scanned (a space-split loop would
 # silently skip them - a secret false-negative).
 
@@ -316,4 +412,19 @@ if [ $FOUND -eq 1 ]; then
   exit 2
 fi
 
+# Unattended commit: the verification gates must have passed for this HEAD.
+# The environment is the hook's own, inherited from the process the launcher
+# started, so the run cannot talk its way past it by editing its state. An
+# attended commit skips this entirely.
+if [ "$IS_COMMIT_HOOK" = "1" ] && ma_unattended; then
+  if ! command -v node >/dev/null 2>&1; then
+    echo "BLOCKED: unattended commit, and node is not available to check the gate ledger." >&2
+    exit 2
+  fi
+  if ! node "$PRE_COMMIT_DIR/gate-ledger.mjs" check --repo "${REPO_ROOT:-$PWD}" >/dev/null; then
+    echo "BLOCKED: unattended commit without a passing gate ledger for HEAD (see above)." >&2
+    exit 2
+  fi
+fi
+
 exit 0

package/pipeline/scripts/probe-evidence-capability.sh

@@ -22,9 +22,16 @@
 #      second copy is a second place for the answer to drift.
 #
 # Usage:
-#   probe-evidence-capability.sh --platform <ios|android|web> [--repo <path>]
-#                                [--changed <f>[,<f>...]] [--json]
-#                                [--json-out <path>] [--only all|device]
+#   probe-evidence-capability.sh --platform <ios|android|web|auto> [--repo <path>]
+#                                [--stack-root <path>] [--changed <f>[,<f>...]]
+#                                [--json] [--json-out <path>] [--only all|device]
+#
+# --platform auto reads the repo's stacks with lib/stack-detect.sh (from
+# --stack-root, default --repo) and probes the first of ios, android, web. A repo
+# with none of them has no device to probe: the output is platform `other` with
+# a skippedReason ("no device platform in stacks [backend]") and exit 0, the
+# outcome visual-evidence.md section 1a records. Phase 0 calls it this way so the
+# choice is one command, not a shell `case` the unattended guard refuses.
 #
 # Output: KEY='VALUE' lines (eval-able; every value is shell-quoted), or a JSON object with --json (shaped for
 # state.evidenceCapability). --json-out writes that JSON to a file while stdout
@@ -40,12 +47,13 @@
 set -uo pipefail
 
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PLATFORM=""; REPO="$PWD"; CHANGED=""; AS_JSON=0; JSON_OUT=""; ONLY="all"
+PLATFORM=""; REPO="$PWD"; CHANGED=""; AS_JSON=0; JSON_OUT=""; ONLY="all"; STACK_ROOT=""
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --platform) PLATFORM="${2:-}"; shift 2 ;;
     --repo) REPO="${2:-}"; shift 2 ;;
+    --stack-root) STACK_ROOT="${2:-}"; shift 2 ;;
     --changed) CHANGED="${CHANGED:+$CHANGED,}${2:-}"; shift 2 ;;
     --json) AS_JSON=1; shift ;;
     --json-out) JSON_OUT="${2:-}"; shift 2 ;;
@@ -57,8 +65,39 @@ case "$ONLY" in all | device) ;; *)
   echo "probe-evidence-capability: --only takes 'all' or 'device'" >&2; exit 2 ;;
 esac
 
+if [ "$PLATFORM" = "auto" ]; then
+  STACK_DETECT="$HERE/../lib/stack-detect.sh"
+  [ -f "$STACK_DETECT" ] || { echo "probe-evidence-capability: stack-detect.sh not found at $STACK_DETECT" >&2; exit 2; }
+  # shellcheck source=../lib/stack-detect.sh
+  . "$STACK_DETECT"
+  ma_stack_detect "${STACK_ROOT:-$REPO}" || true
+  PLATFORM=""
+  case " $MA_STACKS " in
+    *" ios "*) PLATFORM=ios ;;
+    *" android "*) PLATFORM=android ;;
+    *" web "*) PLATFORM=web ;;
+  esac
+  if [ -z "$PLATFORM" ]; then
+    SKIPPED="no device platform in stacks [$MA_STACKS]"
+    SKIP_JSON=$(SKIPPED="$SKIPPED" node -e '
+      process.stdout.write(JSON.stringify({ platform: "other", skippedReason: process.env.SKIPPED }, null, 2) + "\n");
+    ')
+    if [ -n "$JSON_OUT" ]; then
+      mkdir -p "$(dirname "$JSON_OUT")" 2>/dev/null || true
+      printf '%s\n' "$SKIP_JSON" > "$JSON_OUT" || { echo "probe-evidence-capability: could not write $JSON_OUT" >&2; exit 2; }
+    fi
+    if [ "$AS_JSON" -eq 1 ]; then
+      printf '%s\n' "$SKIP_JSON"
+    else
+      printf "EVIDENCE_PLATFORM='other'\n"
+      printf "EVIDENCE_SKIPPED_REASON='%s'\n" "$(printf '%s' "$SKIPPED" | sed "s/'/'\\\\''/g")"
+    fi
+    exit 0
+  fi
+fi
+
 case "$PLATFORM" in ios | android | web) ;; *)
-  echo "usage: probe-evidence-capability.sh --platform <ios|android|web> [--repo <path>] [--changed <f>] [--json]" >&2
+  echo "usage: probe-evidence-capability.sh --platform <ios|android|web|auto> [--repo <path>] [--changed <f>] [--json]" >&2
   exit 2 ;;
 esac
 [ -d "$REPO" ] || { echo "probe-evidence-capability: no such repo directory: $REPO" >&2; exit 2; }

package/pipeline/scripts/record-phase.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * record-phase.mjs  -  move `state.currentPhase` to a phase that just completed.
+ *
+ * `currentPhase` is the last completed phase, and resume re-enters at
+ * `currentPhase + 1`. The tracker records every phase transition in its own
+ * file, so phase-tracker.sh calls this on each `update <id> completed` to keep
+ * the run state in step. The value only moves forward: a review loop that
+ * completes Phase 2 again after Phase 3 leaves it at 3.
+ *
+ * A non-numeric phase id (a sub-phase such as `3a`) or a run with no state
+ * file is a quiet no-op, because the tracker runs in contexts with no run.
+ *
+ * Usage:
+ *   node record-phase.mjs --task-id <id> --phase <n>
+ *
+ * Exit: 0 recorded or nothing to do · 2 usage
+ *
+ * @module pipeline/scripts/record-phase
+ */
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { resolveRunFile } from "./_run-paths.mjs";
+import { updateState } from "./gate-ledger.mjs";
+
+/**
+ * @param {string} taskId
+ * @param {string} phase
+ * @returns {Promise<boolean>} true when the state was changed
+ */
+export async function recordPhase(taskId, phase) {
+  if (!/^\d+$/.test(String(phase))) return false;
+  const path = resolveRunFile(taskId, "agent-state.json");
+  if (!path) return false;
+  const n = Number(phase);
+  let changed = false;
+  await updateState(path, (s) => {
+    const current = Number.isInteger(s.currentPhase) ? s.currentPhase : -1;
+    if (n <= current) return s;
+    changed = true;
+    return { ...s, currentPhase: n };
+  });
+  return changed;
+}
+
+async function main(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--task-id" || argv[i] === "--phase") {
+      if (argv[i + 1] === undefined) return 2;
+      opts[argv[i].slice(2)] = argv[++i];
+    } else {
+      process.stderr.write(`record-phase: unexpected argument ${argv[i]}\n`);
+      return 2;
+    }
+  }
+  if (!opts["task-id"] || opts.phase === undefined) {
+    process.stderr.write("record-phase: --task-id and --phase are required\n");
+    return 2;
+  }
+  try {
+    await recordPhase(opts["task-id"], opts.phase);
+  } catch (err) {
+    process.stderr.write(`record-phase: ${err.message}\n`);
+  }
+  return 0;
+}
+
+if (invokedDirectly(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/pipeline/scripts/render-agent-log-cost.sh

@@ -11,7 +11,12 @@
 # via prefs.global.reportContent.costSummary.
 #
 # Usage:
-#   render-agent-log-cost.sh <task-id> [--otel-spans <path>]
+#   render-agent-log-cost.sh <task-id> [--otel-spans <path>] [--append <agent-log.md>]
+#
+# --append adds the rendered section to the end of that file, after a blank
+# line, and prints nothing; with no data (exit 2) the file is left alone. Phase 5
+# runs it this way so the step is one command, not a substitution plus a shell
+# redirect into a path the unattended guard cannot check.
 #
 # Exit codes:
 #   0  -  section rendered (empty section still prints with placeholder row)
@@ -23,22 +28,32 @@ set -euo pipefail
 # (nested <root>/<project>/<id>/ and flat <root>/<id>/) and every id spelling.
 _MA_RP_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
-. "$_MA_RP_HERE/../lib/run-paths.sh" 2>/dev/null || . "$HOME/.claude/lib/run-paths.sh"
+if [ -f "$_MA_RP_HERE/../lib/run-paths.sh" ]; then . "$_MA_RP_HERE/../lib/run-paths.sh"; else . "$HOME/.claude/lib/run-paths.sh"; fi
 
 
 TASK_ID="${1:?usage: render-agent-log-cost.sh <task-id> [--otel-spans <path>]}"
 shift || true
 
 SPANS_FILE=""
+APPEND_TO=""
 while [ $# -gt 0 ]; do
   case "$1" in
     --otel-spans)
       [ $# -ge 2 ] || { echo "render-agent-log-cost: --otel-spans needs a path" >&2; exit 1; }
       SPANS_FILE="$2"; shift 2 ;;
+    --append)
+      [ $# -ge 2 ] || { echo "render-agent-log-cost: --append needs a path" >&2; exit 1; }
+      APPEND_TO="$2"; shift 2 ;;
     *) shift ;;
   esac
 done
 
+if [ -n "$APPEND_TO" ]; then
+  block=$(bash "${BASH_SOURCE[0]}" "$TASK_ID" ${SPANS_FILE:+--otel-spans "$SPANS_FILE"}) || exit $?
+  printf '\n%s\n' "$block" >> "$APPEND_TO"
+  exit 0
+fi
+
 # cost-table.json/cost-lib.sh ship as siblings of this script both in the
 # repo (pipeline/scripts/) and once installed (~/.claude/scripts/) - a
 # repo-root-relative path (../../pipeline/scripts/...) only resolves in the

package/pipeline/scripts/render-cost-summary.sh

@@ -17,7 +17,7 @@ set -euo pipefail
 # (nested <root>/<project>/<id>/ and flat <root>/<id>/) and every id spelling.
 _MA_RP_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
-. "$_MA_RP_HERE/../lib/run-paths.sh" 2>/dev/null || . "$HOME/.claude/lib/run-paths.sh"
+if [ -f "$_MA_RP_HERE/../lib/run-paths.sh" ]; then . "$_MA_RP_HERE/../lib/run-paths.sh"; else . "$HOME/.claude/lib/run-paths.sh"; fi
 
 
 TASK_ID="${1:?usage: render-cost-summary.sh <task-id> [--otel-spans <path>]}"

package/pipeline/scripts/render-work-summary.sh

@@ -44,7 +44,7 @@ set -euo pipefail
 # (nested <root>/<project>/<id>/ and flat <root>/<id>/) and every id spelling.
 _MA_RP_HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=/dev/null
-. "$_MA_RP_HERE/../lib/run-paths.sh" 2>/dev/null || . "$HOME/.claude/lib/run-paths.sh"
+if [ -f "$_MA_RP_HERE/../lib/run-paths.sh" ]; then . "$_MA_RP_HERE/../lib/run-paths.sh"; else . "$HOME/.claude/lib/run-paths.sh"; fi
 
 
 TASK_ID="${1:?usage: render-work-summary.sh <task-id>}"

package/pipeline/scripts/require-supported-version.sh

@@ -39,6 +39,9 @@ CHECK="$HERE/update-check.sh"
 [ -f "$CHECK" ] || CHECK="$HOME/.claude/scripts/update-check.sh"
 [ -f "$CHECK" ] || exit 0  # no checker installed -> nothing to enforce
 
+# shellcheck source=/dev/null
+if [ -f "$HERE/../lib/user-facing.sh" ]; then . "$HERE/../lib/user-facing.sh"; else . "$HOME/.claude/lib/user-facing.sh"; fi
+
 out=$(bash "$CHECK" "$@" 2>/dev/null) || exit 0
 case "$out" in
   *"|force") ;;
@@ -64,7 +67,7 @@ cat >&2 <<MSG
   This release line is required, not optional.
   Installed: v${local_v}   Required: v${required_v} or newer   Latest: v${latest_v}
 
-  Run /multi-agent:update, then start this command again.
+  Run $(ma_command update), then start this command again.
 
 MSG
 exit 3