@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/scripts/prune-logs.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# prune-logs.sh  -  delete per-task project logs under the multi-agent log root.
+#
+# Every run persists a task log dir at
+#   $HOME/.claude/logs/multi-agent/<project>/<task>/
+# holding agent-state.json, agent-log.md, tracker-state.json, otel-spans.jsonl.
+# These accumulate forever. This prunes whole task dirs, with optional age /
+# project / task filters.
+#
+# PRESERVED ALWAYS: the audit trail (audit.jsonl, audit.*.jsonl*) and the
+# metrics corpus (metrics.jsonl, metrics-summary.md) live at the log-root TOP
+# level, not inside task dirs - this only ever removes task dirs, so those are
+# never touched. .counter files (per-project task numbering) also survive.
+#
+# SAFE BY DEFAULT: dry-run. Lists what WOULD be removed + space freed; deletes
+# nothing until you pass --yes.
+#
+# Usage:
+#   prune-logs.sh                       # dry-run: every task dir
+#   prune-logs.sh --yes                 # delete every task dir
+#   prune-logs.sh --older-than=30       # only task dirs older than 30 days
+#   prune-logs.sh --project=my-ios-app  # only one project's task dirs
+#   prune-logs.sh --task=PROJ-123       # only one task dir
+#   prune-logs.sh --older-than=30 --yes
+#
+# Env:
+#   PRUNE_LOG_ROOT   override the log root (default $HOME/.claude/logs/multi-agent)
+#
+# Exit: 0 on success, 2 on usage error.
+
+set -uo pipefail
+
+LOG_ROOT="${PRUNE_LOG_ROOT:-$HOME/.claude/logs/multi-agent}"
+DELETE=0
+OLDER_DAYS=0
+PROJECT=""
+TASK=""
+
+usage() {
+  grep -E '^#( |$)' "$0" | sed -E 's/^# ?//'
+}
+
+for arg in "$@"; do
+  case "$arg" in
+    --yes | --force) DELETE=1 ;;
+    --older-than=*)
+      OLDER_DAYS="${arg#*=}"
+      if ! printf '%s' "$OLDER_DAYS" | grep -qE '^[0-9]+$'; then
+        echo "prune-logs: --older-than needs a whole number of days, got: $OLDER_DAYS" >&2
+        exit 2
+      fi
+      ;;
+    --project=*) PROJECT="${arg#*=}" ;;
+    --task=*) TASK="${arg#*=}" ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "prune-logs: unknown argument: $arg" >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [ ! -d "$LOG_ROOT" ]; then
+  echo "prune-logs: no log root at $LOG_ROOT  -  nothing to do"
+  exit 0
+fi
+
+# A task dir is any dir (depth 1-2 under the root) carrying a run marker.
+is_task_dir() {
+  local d="$1"
+  [ -f "$d/agent-state.json" ] || [ -f "$d/tracker-state.json" ] ||
+    [ -f "$d/agent-log.md" ] || [ -f "$d/otel-spans.jsonl" ]
+}
+
+MTIME_ARGS=()
+if [ "$OLDER_DAYS" -gt 0 ]; then
+  MTIME_ARGS=(-mtime "+$OLDER_DAYS")
+fi
+
+matches=()
+while IFS= read -r -d '' d; do
+  is_task_dir "$d" || continue
+  # --task: dir name must equal the task id
+  if [ -n "$TASK" ] && [ "$(basename "$d")" != "$TASK" ]; then continue; fi
+  # --project: the immediate parent dir name must equal the project
+  if [ -n "$PROJECT" ] && [ "$(basename "$(dirname "$d")")" != "$PROJECT" ]; then continue; fi
+  matches+=("$d")
+done < <(find "$LOG_ROOT" -mindepth 1 -maxdepth 2 -type d ${MTIME_ARGS[@]+"${MTIME_ARGS[@]}"} -print0 2>/dev/null)
+
+if [ "${#matches[@]}" -eq 0 ]; then
+  echo "prune-logs: no task logs matched under $LOG_ROOT  -  nothing to do"
+  exit 0
+fi
+
+total_kb=0
+for d in "${matches[@]}"; do
+  kb=$(du -sk "$d" 2>/dev/null | awk '{print $1}')
+  total_kb=$((total_kb + ${kb:-0}))
+done
+human="${total_kb} KB"
+[ "$total_kb" -ge 1024 ] && human="$((total_kb / 1024)) MB"
+
+if [ "$DELETE" -eq 0 ]; then
+  echo "DRY-RUN  -  would remove ${#matches[@]} task log dir(s) (frees ~${human}):"
+  for d in "${matches[@]}"; do echo "  ${d#"$LOG_ROOT"/}"; done
+  echo "Audit trail + metrics corpus are preserved. Re-run with --yes to delete."
+  exit 0
+fi
+
+removed=0
+for d in "${matches[@]}"; do
+  rm -rf "$d" 2>/dev/null && removed=$((removed + 1))
+done
+echo "══ prune-logs: removed ${removed}/${#matches[@]} task log dir(s), freed ~${human} (audit + metrics preserved) ══"
+exit 0

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# render-agent-log-cost.sh — v8.3.0
+# render-agent-log-cost.sh  -  v8.3.0
 #
 # Renders the agent-log.md "Cost Breakdown" section: one row per phase
 # with model, tokens in/out, and estimated USD. Reads phase-tracker.json
@@ -14,8 +14,8 @@
 #   render-agent-log-cost.sh <task-id> [--otel-spans <path>]
 #
 # Exit codes:
-#   0 — section rendered (empty section still prints with placeholder row)
-#   2 — tracker JSON missing AND spans file missing (caller should skip section)
+#   0  -  section rendered (empty section still prints with placeholder row)
+#   2  -  tracker JSON missing AND spans file missing (caller should skip section)
 
 set -euo pipefail
 
@@ -54,24 +54,26 @@ fi
 rows_json="[]"
 if [ -n "$tracker_file" ]; then
   # Tracker JSON ships in two shapes:
-  #   array shape  — phase-tracker.sh writes phases:[{id, name, model, tokens_in, ...}]
-  #   object shape — older fixture / hand-built variant phases:{ "1": {...}, ... }
+  #   array shape   -  phase-tracker.sh writes phases:[{id, name, model, tokens_in, ...}]
+  #   object shape  -  older fixture / hand-built variant phases:{ "1": {...}, ... }
   rows_json=$(jq '
     if (.phases | type) == "array" then
       [.phases[] | {
         phase: .id,
         phase_name: (.name // .id),
-        model: (.model // "—"),
+        model: (.model // " - "),
         tokens_in: (.tokens_in // 0),
-        tokens_out: (.tokens_out // 0)
+        tokens_out: (.tokens_out // 0),
+        tokens_cached: (.tokens_cached // 0)
       }]
     else
       [(.phases // {} | to_entries[]) | {
         phase: .key,
         phase_name: (.value.name // .key),
-        model: (.value.model // "—"),
+        model: (.value.model // " - "),
         tokens_in: (.value.tokens_in // 0),
-        tokens_out: (.value.tokens_out // 0)
+        tokens_out: (.value.tokens_out // 0),
+        tokens_cached: (.value.tokens_cached // 0)
       }]
     end
     | sort_by(.phase | tonumber? // 999)' "$tracker_file")
@@ -84,9 +86,10 @@ if [ "$rows_json" = "[]" ] && [ -n "$SPANS_FILE" ] && [ -f "$SPANS_FILE" ]; then
     map({
       phase: (.[0].attributes.phase_id // .[0].attributes.phase // "?"),
       phase_name: (.[0].attributes.phase_name // (.[0].attributes.phase_id // "?")),
-      model: (.[0].attributes.model // "—"),
+      model: (.[0].attributes.model // " - "),
       tokens_in: ([.[].attributes.tokens_in_delta // 0] | add),
-      tokens_out: ([.[].attributes.tokens_out_delta // 0] | add)
+      tokens_out: ([.[].attributes.tokens_out_delta // 0] | add),
+      tokens_cached: ([.[].attributes.tokens_cached_delta // 0] | add)
     }) | sort_by(.phase | tonumber? // 999)
   ' "$SPANS_FILE")
 fi
@@ -95,10 +98,20 @@ joined=$(jq -n --argjson rows "$rows_json" --slurpfile prices "$COST_TABLE" '
   $rows | map(
     . as $r |
     ($prices[0].prices[$r.model] // null) as $p |
+    # tokens_in is freshly-billed input (cache-exclusive, matching the host
+    # input_tokens field); tokens_cached is the separate prompt-cache-read
+    # count, billed at the discounted cacheReadPerMtok rate (default to
+    # inPerMtok when the field is absent so an old price table still prices it).
+    # The two counts are disjoint - never subtract one from the other - so this
+    # renderer and aggregate-metrics.mjs agree on what "total input" means.
+    $r.tokens_in as $fresh |
+    ($r.tokens_cached // 0) as $cached |
     . + {
+      tokens_cached: $cached,
       usd: (
         if $p == null then null
-        else ( ($r.tokens_in / 1000000) * $p.inPerMtok
+        else ( ($fresh / 1000000) * $p.inPerMtok
+             + ($cached / 1000000) * ($p.cacheReadPerMtok // $p.inPerMtok)
              + ($r.tokens_out / 1000000) * $p.outPerMtok )
         end
       )
@@ -107,11 +120,19 @@ joined=$(jq -n --argjson rows "$rows_json" --slurpfile prices "$COST_TABLE" '
 ')
 
 totals=$(jq -n --argjson rows "$joined" '
+  ($rows | map(select(.usd != null)) | sort_by(-.usd) | .[0]) as $top |
+  ($rows | map(select(.usd != null) | .usd) | add) as $sum |
   {
     tokens_in:  ($rows | map(.tokens_in)  | add // 0),
     tokens_out: ($rows | map(.tokens_out) | add // 0),
-    usd:        ($rows | map(select(.usd != null) | .usd) | add),
-    any_missing_usd: ($rows | map(.usd == null) | any)
+    tokens_cached: ($rows | map(.tokens_cached) | add // 0),
+    usd:        $sum,
+    any_missing_usd: ($rows | map(.usd == null) | any),
+    top_driver: (
+      if ($top == null or $sum == null or $sum <= 0) then null
+      else { name: ($top.phase_name // $top.phase), usd: $top.usd, pct: (($top.usd / $sum) * 100 | floor) }
+      end
+    )
   }
 ')
 
@@ -121,7 +142,7 @@ printf '|-------|-------|-----------|------------|----------|\n'
 
 n_rows=$(jq 'length' <<< "$joined")
 if [ "$n_rows" = "0" ]; then
-  printf '| *(no token data captured for %s)* | — | — | — | — |\n' "$TASK_ID"
+  printf '| *(no token data captured for %s)* |  -  |  -  |  -  |  -  |\n' "$TASK_ID"
   exit 0
 fi
 
@@ -131,19 +152,35 @@ jq -r '.[] |
     .model,
     (.tokens_in  | tostring | (if (length > 3) then [splits("(?=(\\d{3})+$)")] | map(select(. != "")) | join(",") else . end)),
     (.tokens_out | tostring | (if (length > 3) then [splits("(?=(\\d{3})+$)")] | map(select(. != "")) | join(",") else . end)),
-    (if .usd == null then "—" else "$" + ((.usd * 100 | floor) / 100 | tostring) end)
+    (if .usd == null then " - " else "$" + ((.usd * 100 | floor) / 100 | tostring) end)
   ] | "| " + join(" | ") + " |"
 ' <<< "$joined"
 
 ti=$(jq -r '.tokens_in  | tostring | (if (length > 3) then [splits("(?=(\\d{3})+$)")] | map(select(. != "")) | join(",") else . end)' <<< "$totals")
 to=$(jq -r '.tokens_out | tostring | (if (length > 3) then [splits("(?=(\\d{3})+$)")] | map(select(. != "")) | join(",") else . end)' <<< "$totals")
-usd_total=$(jq -r 'if .usd == null then "—" else "$" + ((.usd * 100 | floor) / 100 | tostring) end' <<< "$totals")
+usd_total=$(jq -r 'if .usd == null then " - " else "$" + ((.usd * 100 | floor) / 100 | tostring) end' <<< "$totals")
 missing=$(jq -r '.any_missing_usd' <<< "$totals")
 
 printf '| **Total** |  | **%s** | **%s** | **%s** |\n' "$ti" "$to" "$usd_total"
 
+# Top cost driver  -  answers "where did the tokens go", not just "how much".
+top_line=$(jq -r '
+  if .top_driver == null then empty
+  else "\n*Top cost driver: " + (.top_driver.name | tostring)
+     + "  -  $" + ((.top_driver.usd * 100 | floor) / 100 | tostring)
+     + " (" + (.top_driver.pct | tostring) + "% of total).*"
+  end' <<< "$totals")
+[ -n "$top_line" ] && printf '%b\n' "$top_line"
+
+# Cache-read visibility  -  only when the tracker recorded cache hits.
+cached_total=$(jq -r '.tokens_cached // 0' <<< "$totals")
+if [ "$cached_total" != "0" ] && [ "$cached_total" != "null" ]; then
+  cached_fmt=$(jq -r '.tokens_cached | tostring | (if (length > 3) then [splits("(?=(\\d{3})+$)")] | map(select(. != "")) | join(",") else . end)' <<< "$totals")
+  printf '*Cache reads: %s tokens billed at the discounted cache-read rate (resume / prompt-cache reuse).*\n' "$cached_fmt"
+fi
+
 if [ "$missing" = "true" ]; then
-  printf '\n*USD unavailable for one or more rows — add model id to `pipeline/scripts/cost-table.json`.*\n'
+  printf '\n*USD unavailable for one or more rows  -  add model id to `pipeline/scripts/cost-table.json`.*\n'
 fi
 
 exit 0

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# render-cost-summary.sh — v6.1.J
+# render-cost-summary.sh  -  v6.1.J
 #
 # Reads phase-tracker state + cost-table.json, prints the "### Cost Summary"
 # markdown section to stdout. Consumed by /multi-agent:channels when
@@ -8,8 +8,8 @@
 # Usage: render-cost-summary.sh <task-id> [--otel-spans <path>]
 #
 # Exit codes:
-#   0 — table rendered (empty table still prints with header + "no data" row)
-#   2 — tracker JSON missing AND spans file missing (caller should skip section)
+#   0  -  table rendered (empty table still prints with header + "no data" row)
+#   2  -  tracker JSON missing AND spans file missing (caller should skip section)
 
 set -euo pipefail
 
@@ -31,7 +31,7 @@ command -v jq >/dev/null 2>&1 || { echo "render-cost-summary: jq required" >&2;
 
 # Tracker JSON location convention: .worktrees/<TASK>/phase-tracker.json
 # Accept both the full key (e.g. "{JIRA_KEY}-1234") and the numeric-only
-# variant — the Jira-prefix is project-specific, so strip anything before
+# variant  -  the Jira-prefix is project-specific, so strip anything before
 # the first dash when trying the fallback.
 tracker_file=""
 task_id_bare="${TASK_ID##*-}"
@@ -47,7 +47,7 @@ if [ -z "$tracker_file" ] && [ -z "$SPANS_FILE" ]; then
   exit 2
 fi
 
-# Build rows — prefer tracker JSON, fall back to spans aggregation
+# Build rows  -  prefer tracker JSON, fall back to spans aggregation
 rows_json="[]"
 if [ -n "$tracker_file" ]; then
   rows_json=$(jq '[
@@ -109,7 +109,7 @@ printf '|-------|-------|-----------|------------|----------|\n'
 
 n_rows=$(jq 'length' <<< "$joined")
 if [ "$n_rows" = "0" ]; then
-  printf '| *(no tracker data for %s)* | — | — | — | — |\n' "$TASK_ID"
+  printf '| *(no tracker data for %s)* |  -  |  -  |  -  |  -  |\n' "$TASK_ID"
   exit 0
 fi
 
@@ -119,19 +119,19 @@ jq -r '.[] |
     .model,
     (.tokens_in  | tostring | (if (length > 3) then [splits("(?=(\\d{3})+$)")] | map(select(. != "")) | join(",") else . end)),
     (.tokens_out | tostring | (if (length > 3) then [splits("(?=(\\d{3})+$)")] | map(select(. != "")) | join(",") else . end)),
-    (if .usd == null then "—" else "$" + ((.usd * 100 | floor) / 100 | tostring) end)
+    (if .usd == null then " - " else "$" + ((.usd * 100 | floor) / 100 | tostring) end)
   ] | "| " + join(" | ") + " |"
 ' <<< "$joined"
 
 ti=$(jq -r '.tokens_in  | tostring | (if (length > 3) then [splits("(?=(\\d{3})+$)")] | map(select(. != "")) | join(",") else . end)' <<< "$totals")
 to=$(jq -r '.tokens_out | tostring | (if (length > 3) then [splits("(?=(\\d{3})+$)")] | map(select(. != "")) | join(",") else . end)' <<< "$totals")
-usd_total=$(jq -r 'if .usd == null then "—" else "$" + ((.usd * 100 | floor) / 100 | tostring) end' <<< "$totals")
+usd_total=$(jq -r 'if .usd == null then " - " else "$" + ((.usd * 100 | floor) / 100 | tostring) end' <<< "$totals")
 missing=$(jq -r '.any_missing_usd' <<< "$totals")
 
 printf '| **Total** |  | **%s** | **%s** | **%s** |\n' "$ti" "$to" "$usd_total"
 
 if [ "$missing" = "true" ]; then
-  printf '\n*USD unavailable for one or more rows — add model to `pipeline/scripts/cost-table.json`.*\n'
+  printf '\n*USD unavailable for one or more rows  -  add model to `pipeline/scripts/cost-table.json`.*\n'
 fi
 
 exit 0

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

@@ -1,10 +1,10 @@
 #!/usr/bin/env bash
-# render-work-summary.sh — v7.1.0
+# render-work-summary.sh  -  v7.1.0
 #
 # Reads agent-state.json + phase-tracker.json + git diff, emits a concise
 # "### Work Summary" markdown block for Phase 7 channels dispatch. Intended
 # as an executive-summary companion to the existing Normal Analysis /
-# Technical Details / Test Scenarios sections — gives Jira/Confluence
+# Technical Details / Test Scenarios sections  -  gives Jira/Confluence
 # readers and PR reviewers a single-screen answer to "what actually
 # changed?" without parsing the full pipeline log.
 #
@@ -24,7 +24,7 @@
 #   #### Scope delivered
 #   - ✅ T1 <title>
 #   - ✅ T2 <title>
-#   - ⏳ T3 <title> (deferred — rationale)
+#   - ⏳ T3 <title> (deferred  -  rationale)
 #
 #   #### Changed files (<N> files · +<ADD> / -<DEL>)
 #   - `path/a.ext`  (+12 / -4)
@@ -144,7 +144,7 @@ if [ -n "$WORKTREE" ] && [ -d "$WORKTREE/.git" -o -d "$WORKTREE" ]; then
   fi
 fi
 
-# Task list with ✅ / ⏳ marks — derived from triage if available
+# Task list with ✅ / ⏳ marks  -  derived from triage if available
 tasks_block=""
 if [ "$(jq 'length' <<< "$state_tasks")" != "0" ]; then
   tasks_block=$(jq -r '

package/pipeline/scripts/repo-map.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 //
-// repo-map.mjs — Aider-style token-budgeted repository map.
+// repo-map.mjs  -  Aider-style token-budgeted repository map.
 //
 // Pattern source: https://aider.chat/docs/repomap.html
 //   - Walks the repo, extracts top-level declarations per file via regex
@@ -22,9 +22,9 @@
 //                     [--exclude <glob,...>] [--verbose]
 //
 // Exit codes:
-//   0 — printed map (may be empty if no supported files found)
-//   2 — usage / arg error
-//   3 — root directory missing / not a repo
+//   0  -  printed map (may be empty if no supported files found)
+//   2  -  usage / arg error
+//   3  -  root directory missing / not a repo
 
 import { promises as fs } from 'node:fs';
 import { existsSync, statSync } from 'node:fs';
@@ -120,7 +120,7 @@ async function walk(root, args) {
       } else if (e.isFile()) {
         const ext = path.extname(e.name).toLowerCase();
         if (!LANG_EXT[ext]) continue;
-        // size cap — skip generated / mega files (>500KB) to stay deterministic
+        // size cap  -  skip generated / mega files (>500KB) to stay deterministic
         try {
           const st = statSync(full);
           if (st.size > 500_000) continue;
@@ -215,7 +215,7 @@ const EXTRACTORS = {
 
 function truncateSig(s, max = 100) {
   s = s.replace(/\s+/g, ' ').trim();
-  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+  return s.length > max ? s.slice(0, max - 1) + '...' : s;
 }
 
 // ---- Pipeline --------------------------------------------------------------
@@ -261,7 +261,7 @@ async function buildMap(args) {
   // TF-IDF-style scoring: an identifier defined in N files contributes
   // 1/N credit per match. This neutralises shared helper names (e.g. `pass`,
   // `fail`, `init`) that appear in dozens of files without signalling
-  // architectural importance — those split credit thin and don't dominate.
+  // architectural importance  -  those split credit thin and don't dominate.
   // Aider's repo map uses the same intuition (rare symbols rank higher).
 
   // Hard stop-list for sub-3-char + universally-shared shell helpers.
@@ -325,7 +325,7 @@ async function buildMap(args) {
     return;
   }
 
-  // Markdown — greedy fill within token budget. Token ≈ 4 chars heuristic.
+  // Markdown  -  greedy fill within token budget. Token ≈ 4 chars heuristic.
   const charBudget = args.budget * 4;
   const header = `# Repo Map (top ${args.top}, budget ${args.budget} tokens)\n`;
   let used = header.length;
@@ -362,6 +362,6 @@ function escapeRe(s) {
 
 const args = parseArgs(process.argv);
 buildMap(args).catch((err) => {
-  console.error('repo-map: fatal —', err.message);
+  console.error('repo-map: fatal  - ', err.message);
   process.exit(1);
 });

package/pipeline/scripts/run-aggregator.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * @file run-aggregator.mjs — v7.8.0 Paket C
+ * @file run-aggregator.mjs  -  v7.8.0 Paket C
  *
  * Unified telemetry aggregator. Reads three independent telemetry sources
  * for a single pipeline task and emits one normalized `pipeline-run.jsonl`
@@ -21,9 +21,9 @@
  *   - `tokens` (delta from phase-tracker)
  *   - `cost` (computed per-phase, attributed by model)
  *   - `span` (passthrough from otel-spans.jsonl)
- *   - `summary` (last event — totals)
+ *   - `summary` (last event  -  totals)
  *
- * Read-only — never modifies the source files.
+ * Read-only  -  never modifies the source files.
  *
  * Usage:
  *   node run-aggregator.mjs --task-dir <path>
@@ -85,6 +85,7 @@ function resolveTaskDir() {
   if (flags["task-dir"]) return flags["task-dir"];
   if (flags["task-id"] && flags.project) {
     const HOME = process.env.HOME || process.env.USERPROFILE;
+    if (!HOME) die("neither HOME nor USERPROFILE is set  -  pass --task-dir");
     return join(HOME, ".claude", "logs", "multi-agent", flags.project, String(flags["task-id"]));
   }
   die("either --task-dir or --task-id with --project is required");
@@ -107,7 +108,7 @@ function loadJsonl(path) {
     try {
       out.push(JSON.parse(line));
     } catch {
-      // Skip malformed lines silently — telemetry sources may be truncated
+      // Skip malformed lines silently  -  telemetry sources may be truncated
       // mid-write if the pipeline is killed during emission.
     }
   }
@@ -143,7 +144,7 @@ function computeCost(modelKey, tokensIn, tokensOut, costTable) {
 /**
  * Heuristic: phase 1/2 use Opus (per personas + dev-mode docs); phase 3 uses
  * Sonnet by default unless the run is a `--dev` mode (Opus). Phase 4 review
- * is multi-model — span events carry per-reviewer model when OTel is on.
+ * is multi-model  -  span events carry per-reviewer model when OTel is on.
  *
  * This is a fallback when phase-tracker doesn't record the model used. Live
  * runs that emit OTel spans get per-call model attribution from the spans.
@@ -241,7 +242,7 @@ for (const phase of tracker.phases || []) {
   }
 }
 
-// OTel spans — passthrough with task_id stamped
+// OTel spans  -  passthrough with task_id stamped
 for (const span of otelSpans) {
   events.push({
     kind: "span",

package/pipeline/scripts/run-metrics.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+/**
+ * @file run-metrics.mjs  -  outcome metrics for a completed pipeline run.
+ *
+ * Parses an agent-state.json and emits the numbers that actually answer "did
+ * this run go well" - the evidence the project needs to move from
+ * "well-designed" to "proven". Run it after each real task and accumulate the
+ * output; that corpus is the real-world validation a benchmark + golden tasks
+ * only approximate.
+ *
+ * Metrics:
+ *   status, currentPhase                  - did it finish
+ *   reviewIterations                      - rework loops (1 = first-pass clean)
+ *   firstPassClean                        - iteration 1 had 0 accepted BLOCKING
+ *   accepted/deferred/rejected (final)    - triage outcome
+ *   reviewFindingsRaw -> acceptedRatio    - signal-to-noise of the reviewers
+ *   consensusVerdict                      - unanimous-* / split / unverified
+ *   buildPassed                           - per-repo build outcome
+ *
+ * Usage:
+ *   node pipeline/scripts/run-metrics.mjs --state path/to/agent-state.json
+ *   node pipeline/scripts/run-metrics.mjs --state - < agent-state.json
+ *
+ * Exit 0 on success, 2 on usage/parse error. Output: JSON to stdout.
+ *
+ * @module pipeline/scripts/run-metrics
+ */
+
+import { readFileSync } from "node:fs";
+
+const argv = process.argv.slice(2);
+let statePath = null;
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === "--state") statePath = argv[i + 1];
+}
+if (!statePath) {
+  console.error("usage: run-metrics.mjs --state <agent-state.json | ->");
+  process.exit(2);
+}
+
+let raw;
+try {
+  raw = statePath === "-" ? readFileSync(0, "utf8") : readFileSync(statePath, "utf8");
+} catch (e) {
+  console.error(`run-metrics: cannot read state: ${e.message}`);
+  process.exit(2);
+}
+
+let state;
+try { state = JSON.parse(raw); } catch (e) {
+  console.error(`run-metrics: bad JSON: ${e.message}`);
+  process.exit(2);
+}
+
+// Drop null/non-object elements up front so a partially-written state file
+// (a stated use case) degrades instead of crashing on `.triage` / `.reviewers`.
+const iterations = Array.isArray(state.reviewIterations)
+  ? state.reviewIterations.filter((it) => it && typeof it === "object")
+  : [];
+const lastTriage = iterations.length ? (iterations[iterations.length - 1].triage || {}) : {};
+
+const accepted = Array.isArray(lastTriage.accepted) ? lastTriage.accepted : [];
+const deferred = Array.isArray(lastTriage.deferred) ? lastTriage.deferred : [];
+const rejected = Array.isArray(lastTriage.rejected) ? lastTriage.rejected : [];
+
+// First-pass clean = the FIRST review iteration accepted no blocking finding.
+let firstPassClean = null;
+if (iterations.length) {
+  const firstTriage = iterations[0].triage || {};
+  const firstAccepted = Array.isArray(firstTriage.accepted) ? firstTriage.accepted : [];
+  firstPassClean = !firstAccepted.some((f) => f && f.severity === "blocking");
+}
+
+// Reviewer signal-to-noise: across ALL iterations, how many raw reviewer
+// findings survived triage as accepted (vs deferred/rejected as noise).
+let rawFindings = 0;
+let acceptedAll = 0;
+let classifiedAll = 0;
+for (const it of iterations) {
+  for (const r of (Array.isArray(it.reviewers) ? it.reviewers : [])) {
+    rawFindings += Array.isArray(r?.findings) ? r.findings.length : 0;
+  }
+  const t = it.triage || {};
+  acceptedAll += Array.isArray(t.accepted) ? t.accepted.length : 0;
+  classifiedAll += (Array.isArray(t.accepted) ? t.accepted.length : 0)
+    + (Array.isArray(t.deferred) ? t.deferred.length : 0)
+    + (Array.isArray(t.rejected) ? t.rejected.length : 0);
+}
+
+// Build outcome across repos (multi-repo aware).
+const projects = Array.isArray(state.projects) ? state.projects.filter((p) => p && typeof p === "object") : [];
+let buildPassed = null;
+if (projects.length) {
+  buildPassed = projects.every((p) => {
+    const b = p.buildStatus;
+    if (typeof b === "string") return b === "passed";
+    if (b && typeof b === "object") return b.ok === true;
+    return false;
+  });
+} else if (state.buildStatus !== undefined) {
+  const b = state.buildStatus;
+  buildPassed = typeof b === "string" ? b === "passed" : (b && b.ok === true);
+}
+
+const metrics = {
+  taskId: state.taskId ?? null,
+  status: state.status ?? null,
+  currentPhase: state.currentPhase ?? null,
+  reviewIterations: iterations.length,
+  firstPassClean,
+  finalTriage: {
+    accepted: accepted.length,
+    deferred: deferred.length,
+    rejected: rejected.length,
+    approved: lastTriage.approved ?? null,
+  },
+  reviewSignal: {
+    rawFindings,
+    classified: classifiedAll,
+    acceptedAll,
+    acceptedRatio: rawFindings > 0 ? Math.round((acceptedAll / rawFindings) * 100) / 100 : null,
+  },
+  consensusVerdict: lastTriage.consensus ? lastTriage.consensus.verdict : null,
+  buildPassed,
+};
+
+console.log(JSON.stringify(metrics, null, 2));
+process.exit(0);