@mmerterden/multi-agent-pipeline 17.5.1 → 18.0.0

package/pipeline/scripts/package-manager.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+/**
+ * package-manager.mjs  -  which package manager does THIS repo use.
+ *
+ * WHY THIS EXISTS
+ *
+ * Phase 3 and Phase 5 shelled `npm test` and `npm run build` for the node-shaped
+ * stacks, hardcoded. A repo on pnpm, yarn or bun then gets one of two outcomes,
+ * both bad: the command fails outright, or npm quietly installs against a lock
+ * file it does not own and the run continues on a tree the repo's own tooling
+ * would not have produced. Either way it happens in Phase 3, after a worktree
+ * and a branch already exist - the same failure shape ADR-0012 rejected for
+ * platforms ("it fails partway through, having already created a worktree and a
+ * branch").
+ *
+ * The iOS and Android paths are untouched; this is only about the stacks where
+ * a node package manager is the build tool.
+ *
+ * NODE CORE ONLY (ADR-0004). No corepack call, no spawn, no network: the answer
+ * is derivable from files that are already on disk, and a resolver that shells
+ * out would need a working install of the very tool it is trying to identify.
+ *
+ * RESOLUTION ORDER, strongest evidence first:
+ *   1. $MA_PACKAGE_MANAGER          an explicit override always wins
+ *   2. package.json "packageManager" the repo's own declaration (corepack's field)
+ *   3. a lock file                   what the repo actually committed
+ *   4. npm                           the default, reported AS a default
+ *
+ * The order is "what the repo said" before "what the repo left behind", because
+ * a stale lock file outlives a migration and the declaration does not.
+ *
+ * Usage:
+ *   node package-manager.mjs detect --dir <d>                 -> JSON
+ *   node package-manager.mjs test   --dir <d> [--pattern <p>] -> the command line
+ *   node package-manager.mjs run    --dir <d> --script build  -> the command line
+ *   node package-manager.mjs install --dir <d>                -> the command line
+ *
+ * Exit: 0 ok · 2 usage · 3 the requested script is not declared (run/test)
+ *
+ * @module pipeline/scripts/package-manager
+ */
+
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** Lock file -> package manager. Ordered only for a stable tie-break message. */
+export const LOCKFILES = [
+  ["bun.lockb", "bun"],
+  ["bun.lock", "bun"],
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["package-lock.json", "npm"],
+  ["npm-shrinkwrap.json", "npm"],
+];
+
+export const KNOWN = ["npm", "pnpm", "yarn", "bun"];
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `"pnpm@9.1.0"` -> `pnpm`. A field naming something we do not know about is
+ * returned as-is by name so the caller can say WHICH unknown manager it saw;
+ * garbage (empty, a version with no name) resolves to null and falls through.
+ */
+export function parseManagerField(value) {
+  if (typeof value !== "string") return null;
+  const name = value.trim().split("@")[0].trim().toLowerCase();
+  return /^[a-z][a-z0-9-]*$/.test(name) ? name : null;
+}
+
+/**
+ * Walk up from `dir` looking for the evidence. A monorepo keeps its lock file at
+ * the root while the task edits a package three levels down, so stopping at the
+ * starting directory would resolve to the default for most real repos.
+ *
+ * The walk stops AFTER the directory that holds `.git` - that is the repo, and
+ * anything above it belongs to somebody else (a home directory with a stray
+ * yarn.lock has misrouted builds before).
+ */
+export function* ancestors(dir) {
+  let cur = resolvePath(dir);
+  for (;;) {
+    yield cur;
+    if (existsSync(join(cur, ".git"))) return;
+    const up = dirname(cur);
+    if (up === cur) return;
+    cur = up;
+  }
+}
+
+function locksIn(dir) {
+  const found = [];
+  for (const [file, pm] of LOCKFILES) {
+    const full = join(dir, file);
+    if (existsSync(full)) {
+      let mtime = 0;
+      try {
+        mtime = statSync(full).mtimeMs;
+      } catch {
+        /* unreadable is the same as absent for a tie-break */
+      }
+      found.push({ file, pm, mtime });
+    }
+  }
+  return found;
+}
+
+/**
+ * Resolve the package manager for a directory.
+ *
+ * @param {string} dir
+ * @param {object} [opts]
+ * @param {Record<string,string|undefined>} [opts.env]
+ * @returns {{pm: string, source: string, evidence: string, root: string|null,
+ *            known: boolean, ambiguous?: string[]}}
+ */
+export function detect(dir = process.cwd(), { env = process.env } = {}) {
+  const raw = (env.MA_PACKAGE_MANAGER || "").trim().toLowerCase();
+  // The output of this module is pasted into a shell line, so the name is held to
+  // the same shape a manager's binary actually has. Anything else is dropped and
+  // the resolution continues from the repo - an override is not worth executing
+  // whatever a stray environment variable happens to contain.
+  const override = /^[a-z][a-z0-9-]*$/.test(raw) ? raw : "";
+  if (override) {
+    return {
+      pm: override,
+      source: "env",
+      evidence: "MA_PACKAGE_MANAGER",
+      root: null,
+      known: KNOWN.includes(override),
+    };
+  }
+  if (raw) {
+    process.emitWarning(
+      `MA_PACKAGE_MANAGER=${JSON.stringify(raw)} is not a package manager name - ignored`,
+    );
+  }
+
+  for (const cur of ancestors(dir)) {
+    const pkgPath = join(cur, "package.json");
+    if (existsSync(pkgPath)) {
+      const declared = parseManagerField(readJson(pkgPath)?.packageManager);
+      if (declared) {
+        return {
+          pm: declared,
+          source: "packageManager-field",
+          evidence: `${pkgPath}#packageManager`,
+          root: cur,
+          known: KNOWN.includes(declared),
+        };
+      }
+    }
+
+    const locks = locksIn(cur);
+    if (locks.length === 1) {
+      return {
+        pm: locks[0].pm,
+        source: "lockfile",
+        evidence: join(cur, locks[0].file),
+        root: cur,
+        known: true,
+      };
+    }
+    if (locks.length > 1) {
+      // Two lock files almost always means a migration that left one behind.
+      // Newest wins, and every candidate is reported: a resolver that silently
+      // picks one of two committed lock files is how a repo ends up building
+      // with the manager it migrated AWAY from.
+      const sorted = [...locks].sort((a, b) => b.mtime - a.mtime);
+      return {
+        pm: sorted[0].pm,
+        source: "lockfile-newest",
+        evidence: join(cur, sorted[0].file),
+        root: cur,
+        known: true,
+        ambiguous: sorted.map((l) => l.file),
+      };
+    }
+  }
+
+  return {
+    pm: "npm",
+    source: "default",
+    evidence: "no lock file, no declaration",
+    root: null,
+    known: true,
+  };
+}
+
+/** Does the resolved root declare this script? */
+export function hasScript(dir, script) {
+  for (const cur of ancestors(dir)) {
+    const pkgPath = join(cur, "package.json");
+    if (!existsSync(pkgPath)) continue;
+    const scripts = readJson(pkgPath)?.scripts;
+    if (scripts && typeof scripts === "object") return Object.hasOwn(scripts, script);
+  }
+  return false;
+}
+
+/**
+ * `npm run build` for every manager, deliberately.
+ *
+ * `pnpm build` and `yarn build` also work, but only until a script shares a name
+ * with a builtin (`pnpm test`, `yarn add`, `bun install`): then the builtin wins
+ * and the repo's own script never runs. The explicit `run` form has no such
+ * collision on any of the four.
+ */
+export function runCommand(pm, script, args = []) {
+  const extra = args.length ? ` ${args.join(" ")}` : "";
+  return `${pm} run ${script}${extra}`;
+}
+
+/**
+ * The test command, with pass-through arguments.
+ *
+ * npm is the odd one: it needs `--` to stop eating the arguments itself. The
+ * other three forward them to the script as written, and an extra `--` becomes a
+ * literal argument the test runner then has to ignore.
+ */
+export function testCommand(pm, args = []) {
+  if (!args.length) return pm === "bun" ? "bun run test" : `${pm} run test`;
+  const sep = pm === "npm" ? " -- " : " ";
+  return `${pm === "bun" ? "bun run test" : `${pm} run test`}${sep}${args.join(" ")}`;
+}
+
+/** The install command. `--frozen-lockfile` is NOT added: that is a CI decision. */
+export function installCommand(pm) {
+  return pm === "yarn" ? "yarn install" : `${pm} install`;
+}
+
+// ---------------------------------------------------------------------------
+
+function usage(msg) {
+  if (msg) process.stderr.write(`package-manager: ${msg}\n`);
+  process.stderr.write(
+    "usage: package-manager.mjs detect|test|run|install --dir <d> [--script <s>] [--pattern <p>]\n",
+  );
+  process.exit(2);
+}
+
+function main(argv) {
+  const mode = argv[0];
+  if (!mode || mode.startsWith("-")) usage("a mode is required");
+  const opts = {};
+  for (let i = 1; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--dir") opts.dir = argv[++i];
+    else if (a === "--script") opts.script = argv[++i];
+    else if (a === "--pattern") opts.pattern = argv[++i];
+    else if (a === "-h" || a === "--help") usage();
+    else usage(`unexpected argument ${a}`);
+  }
+  const dir = opts.dir || process.cwd();
+  const d = detect(dir);
+
+  if (mode === "detect") {
+    process.stdout.write(`${JSON.stringify(d)}\n`);
+    return 0;
+  }
+  if (mode === "install") {
+    process.stdout.write(`${installCommand(d.pm)}\n`);
+    return 0;
+  }
+  if (mode === "test") {
+    if (!hasScript(dir, "test")) {
+      process.stderr.write("package-manager: no test script declared in package.json\n");
+      return 3;
+    }
+    const args = opts.pattern ? [opts.pattern] : [];
+    process.stdout.write(`${testCommand(d.pm, args)}\n`);
+    return 0;
+  }
+  if (mode === "run") {
+    if (!opts.script) usage("run needs --script");
+    if (!hasScript(dir, opts.script)) {
+      process.stderr.write(`package-manager: no ${opts.script} script declared in package.json\n`);
+      return 3;
+    }
+    process.stdout.write(`${runCommand(d.pm, opts.script)}\n`);
+    return 0;
+  }
+  usage(`unknown mode ${mode}`);
+  return 2;
+}
+
+// Not `file://${process.argv[1]}`: a path with a space or a non-ASCII character
+// percent-encodes in import.meta.url, and on macOS /tmp is a symlink to
+// /private/tmp so argv[1] and the resolved module URL disagree. Either one
+// silently turns this file into a library that prints nothing and exits 0.
+function isEntrypoint() {
+  const arg = process.argv[1];
+  if (!arg) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(arg)).href;
+  } catch {
+    return import.meta.url === pathToFileURL(arg).href;
+  }
+}
+
+if (isEntrypoint()) {
+  process.exit(main(process.argv.slice(2)));
+}

package/pipeline/scripts/phase-banner.sh

@@ -23,7 +23,8 @@
 #   Turkish. The `auto` sentinel in place of [name] triggers a table lookup.
 #   Canonical label set mirrors pipeline/multi-agent-refs/phases.md.
 #
-# Output is colored when stdout is a TTY (TERM != dumb). Plain otherwise so
+# Output is colored when stdout is a TTY (TERM != dumb) and the run is not
+# marked unattended. Plain otherwise so
 # logs and CI artifacts stay readable. Always written to stdout  -  log
 # capture is the caller's responsibility.
 
@@ -88,7 +89,10 @@ fi
 PHASE_WORD="$(phase_word "$PHASE_LANG")"
 
 # Color helpers (skip if not a TTY or TERM=dumb).
-if [ -t 1 ] && [ "${TERM:-}" != "dumb" ]; then
+# Sunucuda terminal olabilir ve renk kimseye gitmez; log dosyasına ANSI
+# kaçışları yazmak onu greplenemez yapar. MULTI_AGENT_UNATTENDED=1 bunu da
+# kapatır; tanımsızken karar bugünküyle aynı.
+if [ -t 1 ] && [ "${TERM:-}" != "dumb" ] && [ "${MULTI_AGENT_UNATTENDED:-}" != "1" ]; then
   C_RESET=$'\033[0m'
   C_DIM=$'\033[2m'
   C_BOLD=$'\033[1m'

package/pipeline/scripts/phase-tracker.sh

@@ -12,6 +12,10 @@
 #   $HOME/.claude/logs/multi-agent/<task_id>/tracker-state.json
 # (override with $TRACKER_FILE env var)
 #
+# `init` writes that flat path. READS go through pipeline/lib/run-paths.sh,
+# which also finds a tracker nested under <project>/<task_id>/ - the multi-repo
+# path writes there, and a hard-coded flat lookup used to miss those runs.
+#
 # Commands:
 #   init   <task_id>                                  Reset tracker for this task
 #   add    <phase_id> "<name>"                        Register a phase (status=pending); idempotent - existing id is a no-op
@@ -52,6 +56,12 @@
 
 set -uo pipefail
 
+# Run-state path resolution: pipeline/lib/run-paths.sh owns both layouts.
+_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 [ "$#" -lt 1 ]; then
   cat >&2 <<USAGE
 usage:
@@ -110,7 +120,13 @@ if [ -z "$TRACKER_FILE" ]; then
       exit 64
     fi
   else
-    TRACKER_FILE="$HOME/.claude/logs/multi-agent/${TASK_ID_FROM_ENV}/tracker-state.json"
+    # Resolve through run-paths.sh: this script writes flat, but 13 of the
+    # trackers on a real machine sit nested under a project directory (written
+    # by the multi-repo path), and the hard-coded flat path could not see them.
+    # A run that does not exist yet resolves to the flat path, which is exactly
+    # where `init` will create it - so new-run behaviour is unchanged.
+    TRACKER_FILE="$(ma_resolve_run_file "$TASK_ID_FROM_ENV" tracker-state.json 2>/dev/null \
+      || echo "$HOME/.claude/logs/multi-agent/${TASK_ID_FROM_ENV}/tracker-state.json")"
   fi
 fi
 TRACKER_DIR="$(dirname "$TRACKER_FILE")"
@@ -430,7 +446,16 @@ save_state() {
   # corrupt document (render exits 65). $$ keeps each writer's temp private; the
   # rename is still atomic, so the last full write wins instead of a torn one.
   local tmp="${TRACKER_FILE}.tmp.$$"
-  printf '%s\n' "$1" > "$tmp"
+  local doc="$1"
+  # Stamp the unlocked-write count, if there were any. jq is guarded because a
+  # machine without it must still get its state written - losing the annotation
+  # is acceptable, losing the write is not.
+  if [ "${TRACKER_LOCK_LOST:-0}" -gt 0 ] && command -v jq >/dev/null 2>&1; then
+    doc=$(printf '%s' "$doc" | jq --argjson n "$TRACKER_LOCK_LOST" \
+      '.unlockedWrites = ((.unlockedWrites // 0) + $n)' 2>/dev/null || printf '%s' "$doc")
+    TRACKER_LOCK_LOST=0
+  fi
+  printf '%s\n' "$doc" > "$tmp"
   mv "$tmp" "$TRACKER_FILE"
 }
 
@@ -444,6 +469,9 @@ save_state() {
 # reclaimed.
 TRACKER_LOCK_DIR=""
 TRACKER_LOCK_HELD=0
+# How many writes went through WITHOUT the lock in this process. Stamped into
+# the state so a run's own record says its counts may be low.
+TRACKER_LOCK_LOST=0
 
 state_lock_stale() {
   local pid mtime now age
@@ -482,7 +510,17 @@ acquire_state_lock() {
     fi
     tries=$((tries + 1))
     if [ "$tries" -ge 50 ]; then
-      echo "phase-tracker: WARN  -  state lock busy ($TRACKER_LOCK_DIR); proceeding without lock" >&2
+      # STILL fails open, and that is the right call: a lost tracker write is
+      # worse than a lost lock, and a hung pipeline is worse than both.
+      #
+      # What changes is that it stops being invisible. Two writers in the
+      # critical section means one of their token deltas is dropped, and the
+      # only trace was a warning on stderr inside a background run nobody
+      # reads. The count now lands in the state file, so the run CARRIES the
+      # evidence that its numbers are low - which is the difference between an
+      # undercount and an undercount you can see.
+      TRACKER_LOCK_LOST=$((TRACKER_LOCK_LOST + 1))
+      echo "phase-tracker: WARN  -  state lock busy ($TRACKER_LOCK_DIR); proceeding without it. Token counts for this write may be low; recorded as unlockedWrites in the state." >&2
       return 0
     fi
     sleep 0.1

package/pipeline/scripts/plan-coverage-gate.mjs

@@ -29,7 +29,7 @@
 //
 // Exit codes: 0 clean, 1 coverage gap, 2 usage / parse error.
 
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, writeFileSync } from "node:fs";
 import { join, isAbsolute } from "node:path";
 import { pathToFileURL } from "node:url";
 
@@ -157,8 +157,12 @@ if (isMain) {
     const msg = Array.isArray(todos)
       ? "the plan has zero steps - that is an unusable plan, not a clean one; skip this gate explicitly for modes with no Phase 2"
       : "no plan todos found - if this mode has no Phase 2, skip this gate explicitly";
+    // fd 1 synchronously, then exit. This sits in `if (isMain)` at module scope,
+    // not in a function, so there is nothing to return from - and a
+    // process.stdout.write followed by process.exit() loses the verdict when
+    // stdout is a pipe.
     if (asJson)
-      process.stdout.write(`${JSON.stringify({ verdict: "unusable", reason: msg }, null, 2)}\n`);
+      writeFileSync(1, `${JSON.stringify({ verdict: "unusable", reason: msg }, null, 2)}\n`);
     else process.stderr.write(`plan-coverage-gate: ${msg}\n`);
     process.exit(2);
   }

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

@@ -4,6 +4,13 @@
 # Exit 0 = clean, Exit 2 = secrets found. The PreToolUse hook contract
 # (install/templates/claude-hooks.json, agent-guard.sh) blocks the tool call
 # only on exit 2, with the reason on stderr.
+#
+# No `-e` here either, and for a sharper reason than in pre-push-check.sh: this
+# file is a PreToolUse hook that fires on every Bash call, and it is built out
+# of greps that are SUPPOSED to find nothing. Under `-e` the first clean
+# detector would end the scan, and a hook that exits early reports "no secrets"
+# for a file it never finished reading - a scanner failing open, on the path
+# that exists to keep secrets out of commits.
 
 set -uo pipefail
 

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

@@ -43,6 +43,13 @@
 #   0  -  all gates passed, safe to push
 #   1  -  a gate failed (test, lint, schema, or personal-data leak)
 #   2  -  environment problem (node missing, npm missing, wrong cwd)
+#
+# No `-e`, and that is a decision rather than an omission. This file RUNS the
+# gates and counts how many failed; `-e` would abort at the first one, so a
+# tree with three problems would report one, get fixed, report the next, and
+# take three full runs to learn what one run already knew. The four destructive
+# scripts in this directory DO use `-e`, because there the next command deletes
+# something. Here the next command is another question.
 
 set -uo pipefail
 

package/pipeline/scripts/purge.sh

@@ -33,7 +33,7 @@
 # Exit: 0 on success (including "nothing to do"), 2 on usage error or refused
 # repo.
 
-set -uo pipefail
+set -euo pipefail
 
 REPO="$PWD"
 DELETE=0
@@ -66,7 +66,11 @@ fi
 # Anchor everything on the MAIN worktree (first porcelain entry), so running
 # purge from inside a linked worktree still targets <repo>/.worktrees/.
 MAIN_WT="$(git -C "$REPO" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p' | head -1)"
-MAIN_WT="$(cd "$MAIN_WT" 2>/dev/null && pwd -P)"
+# `|| true` on the resolve, not on the cd: an assignment takes the exit status
+# of its command substitution, so under `set -e` a MAIN_WT that no longer exists
+# would kill the script HERE - three lines before the guard whose whole job is
+# to report exactly that, with a message, as exit 2.
+MAIN_WT="$(cd "$MAIN_WT" 2>/dev/null && pwd -P || true)"
 HOME_REAL="$(cd "$HOME" 2>/dev/null && pwd -P || printf '%s' "$HOME")"
 if [ -z "$MAIN_WT" ] || [ "$MAIN_WT" = "/" ] || [ "$MAIN_WT" = "$HOME_REAL" ]; then
   echo "purge: refusing to operate on repo root '$MAIN_WT'" >&2
@@ -96,7 +100,11 @@ cur_branch=""
 flush_block() {
   [ -z "$cur_path" ] && { cur_branch=""; return 0; }
   local resolved
-  resolved="$(resolve_dir "$cur_path")"
+  # A registered worktree whose directory is GONE is the ordinary case this
+  # function exists to handle - `git worktree list` still lists it, and purge is
+  # what cleans it up. resolve_dir fails there, and an unforgiven assignment
+  # would end the teardown with exit 1 and no output at all.
+  resolved="$(resolve_dir "$cur_path" || true)"
   case "$resolved" in
     "$WT_ROOT"/*)
       wt_paths+=("$resolved")
@@ -184,7 +192,12 @@ while [ "$i" -lt "${#wt_paths[@]}" ]; do
     case "$p" in
       "$WT_ROOT"/*)
         rm -rf "$p" 2>/dev/null && wt_gone=1
-        git -C "$MAIN_WT" worktree prune >/dev/null 2>&1
+        # `|| true` because this branch only runs when `worktree remove --force`
+        # ALREADY failed - a locked or damaged worktree - which is exactly when
+        # the follow-up prune is likeliest to fail too. Under `set -e` that would
+        # abort the teardown mid-loop, leaving the remaining worktrees, the
+        # branches, the counter reset and the exclude-block removal undone.
+        git -C "$MAIN_WT" worktree prune >/dev/null 2>&1 || true
         ;;
       *) echo "purge: skipping worktree outside $WT_ROOT: $p" >&2 ;;
     esac
@@ -228,8 +241,12 @@ if [ -n "$COUNTER" ]; then
   rm -f "$COUNTER" 2>/dev/null && echo "→ reset task counter $COUNTER"
 fi
 
-# Drop the now-empty .worktrees/ shell (only when truly empty).
-[ -d "$WT_ROOT" ] && rmdir "$WT_ROOT" 2>/dev/null
+# Drop the now-empty .worktrees/ shell (only when truly empty). The `|| true`
+# is the point of the line, not noise on it: a symlink pointing out of the tree
+# is deliberately NOT followed and NOT deleted, so the directory is routinely
+# non-empty here, rmdir routinely fails, and under `set -e` that ordinary
+# outcome would abort the teardown before the exclude block came out.
+[ -d "$WT_ROOT" ] && { rmdir "$WT_ROOT" 2>/dev/null || true; }
 
 # purge is the whole-repo teardown, so it is the one place the managed exclude
 # block should come back out - a per-task finalize must not, because other tasks

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

@@ -19,6 +19,13 @@
 
 set -euo pipefail
 
+# Run-state path resolution: pipeline/lib/run-paths.sh owns the two layouts
+# (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"
+
+
 TASK_ID="${1:?usage: render-agent-log-cost.sh <task-id> [--otel-spans <path>]}"
 shift || true
 
@@ -50,8 +57,8 @@ for candidate in \
   "$PWD/.worktrees/$TASK_ID/phase-tracker.json" \
   "$PWD/.worktrees/$task_id_bare/phase-tracker.json" \
   "$PWD/.worktrees/task-$task_id_bare/phase-tracker.json" \
-  "$HOME/.claude/logs/multi-agent/$TASK_ID/tracker-state.json" \
-  "$HOME/.claude/logs/multi-agent/$task_id_bare/tracker-state.json"
+  "$(ma_resolve_run_file "$TASK_ID" tracker-state.json 2>/dev/null || echo /nonexistent)" \
+  "$(ma_resolve_run_file "$task_id_bare" tracker-state.json 2>/dev/null || echo /nonexistent)"
 do
   [ -f "$candidate" ] && { tracker_file="$candidate"; break; }
 done

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

@@ -13,6 +13,13 @@
 
 set -euo pipefail
 
+# Run-state path resolution: pipeline/lib/run-paths.sh owns the two layouts
+# (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"
+
+
 TASK_ID="${1:?usage: render-cost-summary.sh <task-id> [--otel-spans <path>]}"
 shift || true
 
@@ -50,8 +57,8 @@ for candidate in \
   "$PWD/.worktrees/$TASK_ID/phase-tracker.json" \
   "$PWD/.worktrees/$task_id_bare/phase-tracker.json" \
   "$PWD/.worktrees/task-$task_id_bare/phase-tracker.json" \
-  "$HOME/.claude/logs/multi-agent/$TASK_ID/tracker-state.json" \
-  "$HOME/.claude/logs/multi-agent/$task_id_bare/tracker-state.json"
+  "$(ma_resolve_run_file "$TASK_ID" tracker-state.json 2>/dev/null || echo /nonexistent)" \
+  "$(ma_resolve_run_file "$task_id_bare" tracker-state.json 2>/dev/null || echo /nonexistent)"
 do
   [ -f "$candidate" ] && { tracker_file="$candidate"; break; }
 done

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

@@ -40,6 +40,13 @@
 
 set -euo pipefail
 
+# Run-state path resolution: pipeline/lib/run-paths.sh owns the two layouts
+# (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"
+
+
 TASK_ID="${1:?usage: render-work-summary.sh <task-id>}"
 shift || true
 
@@ -85,11 +92,11 @@ fi
 # had a log-dir fallback all along; this is the same list.
 if [ -z "$STATE_FILE" ] || [ -z "$TRACKER_FILE" ]; then
   task_bare="${TASK_ID##*-}"
+  # The `*/` glob here saw only the nested layout, and an unmatched glob is a
+  # literal path in bash - so a flat-layout run fell through silently.
   for base in \
-    "$HOME/.claude/logs/multi-agent/$TASK_ID/artifacts" \
-    "$HOME/.claude/logs/multi-agent/$task_bare/artifacts" \
-    "$HOME"/.claude/logs/multi-agent/*/"$TASK_ID"/artifacts \
-    "$HOME"/.claude/logs/multi-agent/*/"$task_bare"/artifacts
+    "$(ma_resolve_run_dir_any "$TASK_ID" 2>/dev/null || echo /nonexistent)/artifacts" \
+    "$(ma_resolve_run_dir_any "$task_bare" 2>/dev/null || echo /nonexistent)/artifacts"
   do
     [ -d "$base" ] || continue
     [ -z "$STATE_FILE" ]   && [ -f "$base/agent-state.json" ]    && STATE_FILE="$base/agent-state.json"

package/pipeline/scripts/review-file-filter.mjs

@@ -44,6 +44,8 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { globToRegExp } from "./glob-match.mjs";
 import { unquotePathIfNeeded } from "./git-path.mjs";
+import { runMain } from "../lib/fatal.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
 
 const DEFAULT_PATTERNS = join(import.meta.dirname, "..", "schemas", "review-file-exclusions.json");
 
@@ -175,6 +177,6 @@ function main() {
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
-  main();
+if (invokedDirectly(import.meta.url)) {
+  runMain("review-file-filter", main);
 }

package/pipeline/scripts/review-scope.mjs

@@ -26,6 +26,7 @@
  * Exit 0 always. Invalid/empty input → fail SAFE to "full" (never under-review).
  */
 import { readFileSync } from "node:fs";
+import { runMain } from "../lib/fatal.mjs";
 
 const args = process.argv.slice(2);
 const num = (flag, dflt) => {
@@ -97,4 +98,4 @@ function main() {
   emit({ scope: trivial ? "single" : "full", reason, churn, maxScore, blockers });
 }
 
-main();
+runMain("review-scope", main);

package/pipeline/scripts/routine-registry.mjs

@@ -27,6 +27,7 @@
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, renameSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { runMain } from "../lib/fatal.mjs";
 
 const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 const MAX_NAME = 40;
@@ -218,4 +219,4 @@ function main() {
   }
 }
 
-main();
+runMain("routine-registry", main);