@mmerterden/multi-agent-pipeline 17.6.0 → 18.0.0

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

package/pipeline/scripts/run-aggregator.mjs

@@ -38,6 +38,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { costUsd } from "./_cost.mjs";
+import { resolveRunFile, canonicalRunDir } from "./_run-paths.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -82,26 +83,24 @@ function die(msg) {
   process.exit(1);
 }
 
-// phase-tracker.sh writes tracker-state.json (never phase-tracker.json) at
-// $HOME/.claude/logs/multi-agent/<task-id>/ (no <project> segment) - the
-// same drift render-cost-summary.sh/render-agent-log-cost.sh already guard
-// against with a candidate list. Mirror that list here instead of assuming
-// one fixed filename/path.
+// Path resolution lives in _run-paths.mjs: tracker-state.json is written to
+// the flat <root>/<task-id>/ while agent-state.json documents the nested
+// <root>/<project>/<task-id>/, and both layouts are populated in practice.
+// This used to be a hand-rolled candidate list here, a second one in
+// render-cost-summary.sh and a third in render-agent-log-cost.sh.
 function resolveTrackerCandidates() {
   const candidates = [];
   if (flags["task-dir"]) {
     candidates.push(join(flags["task-dir"], "tracker-state.json"));
   }
   if (flags["task-id"]) {
-    const HOME = process.env.HOME || process.env.USERPROFILE;
-    if (!HOME) die("neither HOME nor USERPROFILE is set  -  pass --task-dir");
-    const taskId = String(flags["task-id"]);
-    if (flags.project) {
-      candidates.push(
-        join(HOME, ".claude", "logs", "multi-agent", flags.project, taskId, "tracker-state.json"),
-      );
-    }
-    candidates.push(join(HOME, ".claude", "logs", "multi-agent", taskId, "tracker-state.json"));
+    const found = resolveRunFile(flags["task-id"], "tracker-state.json", flags.project);
+    if (found) candidates.push(found);
+    // Keep the canonical path in the list even when nothing exists yet, so the
+    // "not found" message names a path instead of an empty candidate set.
+    candidates.push(
+      join(canonicalRunDir(String(flags["task-id"]), flags.project), "tracker-state.json"),
+    );
   }
   if (!candidates.length) die("either --task-dir or --task-id is required");
   return candidates;

package/pipeline/scripts/run-metrics.mjs

@@ -215,5 +215,7 @@ const metrics = {
   },
 };
 
+// No process.exit(0) here. Exit code 0 is already the default, and calling it
+// would terminate before this write drained - stdout to a pipe is asynchronous,
+// so `run-metrics.mjs | jq` would read a payload cut at a buffer boundary.
 console.log(JSON.stringify(metrics, null, 2));
-process.exit(0);