@mmerterden/multi-agent-pipeline 17.5.1 → 18.0.0

package/pipeline/scripts/_run-paths.mjs

@@ -0,0 +1,372 @@
+/**
+ * @file _run-paths.mjs  -  the single resolver for pipeline run-state paths.
+ *
+ * A run's files live under the log root in ONE of two layouts:
+ *
+ *   nested   <root>/<project>/<taskId>/     documented canonical; what
+ *                                           agent-state.json, purge.sh's
+ *                                           per-project .counter and
+ *                                           prune-logs.sh reason about
+ *   flat     <root>/<taskId>/               what phase-tracker.sh has always
+ *                                           written tracker-state.json to
+ *
+ * Both are real and both are populated, so every reader has to accept both.
+ * Before this module three callers hand-rolled their own candidate list -
+ * run-aggregator.mjs, render-cost-summary.sh and render-agent-log-cost.sh -
+ * and the single-level `<root>/*\/` globs elsewhere saw only one layout, so a
+ * run could be counted twice or missed entirely depending on which glob ran.
+ *
+ * This module does NOT change where anything is written. Measured on a real
+ * install, 90 of 103 runs are flat and every tracker-state.json is, so moving
+ * the writers would relocate the majority layout to satisfy a document. READS
+ * accept both, newest wins, and a taskId present in both layouts is ONE run,
+ * not two. Relocation is opt-in and explicit: `migrate-state.mjs --relocate`.
+ *
+ * Zero runtime dependencies (ADR-0004). Shell twin: pipeline/lib/run-paths.sh -
+ * the two must agree, and smoke-run-path-canonical.sh asserts that they do.
+ *
+ * @module pipeline/scripts/_run-paths
+ */
+
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Files that mark a directory as a run directory rather than a project
+ * directory. A project directory holds run directories; a run directory holds
+ * at least one of these.
+ */
+export const RUN_MARKERS = ["agent-state.json", "tracker-state.json", "agent-log.md"];
+
+/**
+ * Depth-1 names under the log root that are namespaces, not runs and not
+ * projects. They are skipped by listRuns so a namespace never surfaces as a
+ * phantom run with no phase.
+ */
+export const RESERVED_DIRS = new Set([
+  "review-watch",
+  "jira-backups",
+  "shadow-git",
+  "_analysis-jira",
+  "prompts",
+]);
+
+/**
+ * The log root. LOGS_ROOT overrides it, which is what the smokes use so they
+ * never touch a real run.
+ *
+ * @returns {string}
+ */
+export function logsRoot() {
+  return process.env.LOGS_ROOT || join(homedir(), ".claude", "logs", "multi-agent");
+}
+
+/**
+ * The path a NEW run's files should be written to.
+ *
+ * @param {string} taskId
+ * @param {string|null|undefined} project  omitted only when the project is
+ *   genuinely unknown, which yields the flat path rather than inventing a slug
+ * @returns {string}
+ */
+export function canonicalRunDir(taskId, project) {
+  const root = logsRoot();
+  return project ? join(root, project, taskId) : join(root, taskId);
+}
+
+/**
+ * Phase 6 removes the worktree and salvages the run's files into an
+ * `artifacts/` subdirectory of the same run directory. A finished run therefore
+ * keeps its state one level deeper, and a reader that only looks at the top
+ * level reports a shipped task as having no state at all.
+ */
+export const ARTIFACTS_SUBDIR = "artifacts";
+
+function isRunDir(dir) {
+  if (RUN_MARKERS.some((m) => existsSync(join(dir, m)))) return true;
+  return RUN_MARKERS.some((m) => existsSync(join(dir, ARTIFACTS_SUBDIR, m)));
+}
+
+/**
+ * Newest marker mtime in WHOLE SECONDS.
+ *
+ * Seconds, not milliseconds, because the shell twin can only read seconds
+ * (`stat -c %Y` / `stat -f %m`). Comparing at different precisions made the two
+ * implementations pick different winners for a run written to both layouts
+ * within the same second - which is the common case, since both writes happen
+ * in one Phase 0.
+ */
+function newestMarkerMtime(dir) {
+  let newest = 0;
+  for (const base of [dir, join(dir, ARTIFACTS_SUBDIR)]) {
+    for (const m of RUN_MARKERS) {
+      try {
+        const t = Math.floor(statSync(join(base, m)).mtimeMs / 1000);
+        if (t > newest) newest = t;
+      } catch {
+        // Marker absent or unreadable - not every run has all three.
+      }
+    }
+  }
+  return newest;
+}
+
+/**
+ * Total order over candidate directories for one task id. Negative when `a`
+ * should win.
+ *
+ * mtime alone is not an order: two directories written in the same second tie,
+ * and both implementations then fell back to their own traversal order and
+ * disagreed. The tail of this comparator exists so the answer is defined:
+ * richer record first (agent-state.json is what every reader actually wants),
+ * then the documented nested layout, then the path itself.
+ */
+function compareCandidates(a, b) {
+  // A bridge and its target hold the same bytes, so neither is "newer". Prefer
+  // the real directory: a reader that reports a path should report the one the
+  // file actually lives in.
+  const aBridge = isBridgeDir(a) ? 1 : 0;
+  const bBridge = isBridgeDir(b) ? 1 : 0;
+  if (aBridge !== bBridge) return aBridge - bBridge;
+  const byTime = newestMarkerMtime(b) - newestMarkerMtime(a);
+  if (byTime !== 0) return byTime;
+  const aState = existsSync(join(a, "agent-state.json")) ? 1 : 0;
+  const bState = existsSync(join(b, "agent-state.json")) ? 1 : 0;
+  if (aState !== bState) return bState - aState;
+  const aNested = a.split("/").length;
+  const bNested = b.split("/").length;
+  if (aNested !== bNested) return bNested - aNested;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Every directory a run with this id could live in, most-specific first.
+ * Existence is NOT checked - this is the candidate list; resolveRunDir picks.
+ *
+ * @param {string} taskId
+ * @param {string|null|undefined} project
+ * @returns {string[]}
+ */
+export function runDirCandidates(taskId, project) {
+  const root = logsRoot();
+  const out = [];
+  if (project) out.push(join(root, project, taskId));
+  out.push(join(root, taskId));
+  if (!project) {
+    // No project given: the run may still be nested under one. Scan depth-1
+    // directories for a child with this id rather than failing the lookup.
+    let entries;
+    try {
+      entries = readdirSync(root, { withFileTypes: true });
+    } catch {
+      return out;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory() || RESERVED_DIRS.has(e.name) || e.name === taskId) continue;
+      const cand = join(root, e.name, taskId);
+      if (isRunDir(cand)) out.push(cand);
+    }
+  }
+  return out;
+}
+
+/**
+ * The directory holding this run's files, or null when the run is unknown.
+ * When a taskId exists in more than one layout the most recently written one
+ * wins, so a resumed run is not read from its stale twin.
+ *
+ * @param {string} taskId
+ * @param {string|null|undefined} [project]
+ * @returns {string|null}
+ */
+export function resolveRunDir(taskId, project) {
+  const present = runDirCandidates(taskId, project).filter(isRunDir);
+  if (!present.length) return null;
+  if (present.length === 1) return present[0];
+  return present.slice().sort(compareCandidates)[0];
+}
+
+/**
+ * The spellings one task id has been written under, in preference order.
+ *
+ * `#316` reaches the pipeline from a GitHub issue reference, `316` from the
+ * bare-number input class, and `task-316` from an older directory convention.
+ * Callers used to inline this list; centralising it is the point of this
+ * module, and dropping any spelling would silently stop resolving old runs.
+ *
+ * @param {string} id
+ * @returns {string[]} unique, order-preserving
+ */
+export function taskIdVariants(id) {
+  const raw = String(id);
+  const bare = raw.replace(/^#/, "");
+  return [...new Set([raw, bare, `task-${bare}`])];
+}
+
+/**
+ * resolveRunDir over every spelling of the id, first hit wins.
+ *
+ * @param {string} taskId
+ * @param {string|null|undefined} [project]
+ * @returns {string|null}
+ */
+export function resolveRunDirAny(taskId, project) {
+  for (const v of taskIdVariants(taskId)) {
+    const dir = resolveRunDir(v, project);
+    if (dir) return dir;
+  }
+  return null;
+}
+
+/**
+ * The full path to one of a run's files, or null when the run is unknown.
+ * Every spelling of the id is tried.
+ *
+ * @param {string} taskId
+ * @param {string} filename  e.g. "agent-state.json"
+ * @param {string|null|undefined} [project]
+ * @returns {string|null}
+ */
+export function resolveRunFile(taskId, filename, project) {
+  for (const v of taskIdVariants(taskId)) {
+    const dir = resolveRunDir(v, project);
+    if (!dir) continue;
+    // Top level first, then the salvaged copy Phase 6 leaves behind.
+    for (const base of [dir, join(dir, ARTIFACTS_SUBDIR)]) {
+      const p = join(base, filename);
+      if (existsSync(p)) return p;
+    }
+  }
+  return null;
+}
+
+/**
+ * True when two candidate directories are two views of ONE record rather than
+ * two copies of it.
+ *
+ * Some nested run directories are symlink bridges into the flat copy - a
+ * previous attempt to reconcile the two layouts. Counting those as duplicates
+ * overstates the drift (21 reported, 18 real on the install this was measured
+ * on) and makes "which one is newer" a question about a link's own mtime.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+function isSameRecord(a, b) {
+  for (const m of RUN_MARKERS) {
+    try {
+      if (realpathSync(join(a, m)) === realpathSync(join(b, m))) return true;
+    } catch {
+      // Marker missing on one side - try the next one.
+    }
+  }
+  return false;
+}
+
+/**
+ * True when any marker in this directory is itself a symlink.
+ *
+ * lstat on the LEAF, not a realpath comparison: realpath also resolves parent
+ * directories, and on macOS a temp tree under /var is reached through a symlink
+ * to /private/var, so realpath(x) !== x is true for every path there. That made
+ * both sides of a pair look like bridges, the rule collapsed, and the two
+ * implementations picked different winners. The shell twin tests `[ -L ]`, and
+ * this has to mean the same thing.
+ */
+function isBridgeDir(dir) {
+  for (const m of RUN_MARKERS) {
+    try {
+      if (lstatSync(join(dir, m)).isSymbolicLink()) return true;
+    } catch {
+      // Missing marker is not a bridge.
+    }
+  }
+  return false;
+}
+
+function readProjectHint(dir) {
+  // agent-state.json v2.1.0 mirrors projects[0] onto scalars; older revisions
+  // carry `project` as a string or an object with a name. Take whichever is a
+  // non-empty string and do not guess beyond that.
+  const statePath = existsSync(join(dir, "agent-state.json"))
+    ? join(dir, "agent-state.json")
+    : join(dir, ARTIFACTS_SUBDIR, "agent-state.json");
+  try {
+    const s = JSON.parse(readFileSync(statePath, "utf-8"));
+    const cands = [s.projectSlug, s.project?.name, s.project, s.projects?.[0]?.name];
+    for (const c of cands) if (typeof c === "string" && c.trim()) return c.trim();
+  } catch {
+    // No state file, or malformed - the layout still tells us what it can.
+  }
+  return null;
+}
+
+/**
+ * Every run under the log root, both layouts, deduplicated by task id.
+ *
+ * A task id present in both layouts collapses to one entry - chosen by
+ * compareCandidates - with `duplicateOf` naming the other so a caller can
+ * report the drift instead of silently hiding it.
+ *
+ * `project` is derived from the LAYOUT alone, so the shell twin can produce the
+ * same four columns without parsing JSON (it has no jq guarantee). Anything
+ * read out of the state file is `projectHint`, a JS-only enrichment that
+ * runs-index.mjs uses and the cross-implementation contract does not cover.
+ *
+ * Ordering is byte-wise, not locale-aware, for the same reason: `sort` in the
+ * twin is byte-wise, and a collation difference is a diff nobody can act on.
+ *
+ * @returns {{taskId:string,project:string|null,dir:string,layout:"nested"|"flat",duplicateOf:string|null,projectHint:string|null}[]}
+ */
+export function listRuns() {
+  const root = logsRoot();
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  /** @type {Map<string, {taskId:string,project:string|null,dir:string,layout:"nested"|"flat",duplicateOf:string|null}>} */
+  const byId = new Map();
+
+  const offer = (taskId, project, dir, layout) => {
+    const prev = byId.get(taskId);
+    if (!prev) {
+      byId.set(taskId, { taskId, project, dir, layout, duplicateOf: null });
+      return;
+    }
+    const keepNew = compareCandidates(dir, prev.dir) < 0;
+    const winner = keepNew ? { taskId, project, dir, layout } : prev;
+    const loserDir = keepNew ? prev.dir : dir;
+    // A symlink bridge is one record seen twice, not drift worth reporting.
+    const dup = isSameRecord(dir, prev.dir) ? (prev.duplicateOf ?? null) : loserDir;
+    byId.set(taskId, { ...winner, duplicateOf: dup });
+  };
+
+  for (const e of entries) {
+    if (!e.isDirectory() || RESERVED_DIRS.has(e.name)) continue;
+    const dir = join(root, e.name);
+    if (isRunDir(dir)) {
+      offer(e.name, null, dir, "flat");
+      continue;
+    }
+    let kids;
+    try {
+      kids = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const k of kids) {
+      if (!k.isDirectory()) continue;
+      const kd = join(dir, k.name);
+      if (isRunDir(kd)) offer(k.name, e.name, kd, "nested");
+    }
+  }
+
+  return [...byId.values()]
+    .map((r) => ({ ...r, projectHint: r.project ?? readProjectHint(r.dir) }))
+    .sort((a, b) => (a.taskId < b.taskId ? -1 : a.taskId > b.taskId ? 1 : 0));
+}

package/pipeline/scripts/aggregate-metrics.mjs

@@ -221,12 +221,13 @@ const summary = {
   events_by_type: byEvent,
 };
 
+// An if/else chain rather than three blocks each ending in process.exit(0).
+// stdout to a pipe is asynchronous and process.exit() discards what has not
+// drained, so `aggregate-metrics.mjs --json | jq` read a payload cut at a
+// buffer boundary. Choosing the renderer with `else` needs no exit at all.
 if (opts.json) {
   console.log(JSON.stringify(summary, null, 2));
-  process.exit(0);
-}
-
-if (opts.markdown) {
+} else if (opts.markdown) {
   const lines = [];
   lines.push(`# Pipeline Metrics Summary`);
   lines.push(``);
@@ -288,74 +289,73 @@ if (opts.markdown) {
     );
   }
   console.log(lines.join("\n"));
-  process.exit(0);
-}
-
-// Plain-text rendering
-const fmt = (n) => (n === null ? " - " : String(n));
-console.log(`Multi-Agent Pipeline  -  metrics summary`);
-console.log(`source: ${summary.source}`);
-console.log(`events: ${summary.total_events} (${summary.parse_errors} parse errors)`);
-console.log(`unique tasks: ${summary.unique_tasks}`);
-console.log(``);
-console.log(`Reviews:`);
-console.log(`  completed:           ${summary.reviews_completed}`);
-console.log(`  cycles per task avg: ${summary.review_cycles.avg}`);
-console.log(`  cycles per task p95: ${summary.review_cycles.p95}`);
-console.log(``);
-console.log(`Triage classification (sum across all reviews):`);
-console.log(`  raw findings:        ${summary.triage_totals.raw}`);
-console.log(
-  `  accepted:            ${summary.triage_totals.accepted} (rate ${fmt(summary.triage_totals.accept_rate)})`,
-);
-console.log(`  deferred:            ${summary.triage_totals.deferred}`);
-console.log(
-  `  rejected:            ${summary.triage_totals.rejected} (rate ${fmt(summary.triage_totals.reject_rate)})`,
-);
-
-if (Object.keys(summary.edge_cases).length) {
+} else {
+  // Plain-text rendering
+  const fmt = (n) => (n === null ? " - " : String(n));
+  console.log(`Multi-Agent Pipeline  -  metrics summary`);
+  console.log(`source: ${summary.source}`);
+  console.log(`events: ${summary.total_events} (${summary.parse_errors} parse errors)`);
+  console.log(`unique tasks: ${summary.unique_tasks}`);
+  console.log(``);
+  console.log(`Reviews:`);
+  console.log(`  completed:           ${summary.reviews_completed}`);
+  console.log(`  cycles per task avg: ${summary.review_cycles.avg}`);
+  console.log(`  cycles per task p95: ${summary.review_cycles.p95}`);
   console.log(``);
-  console.log(`Triage edge cases:`);
-  for (const [k, v] of Object.entries(summary.edge_cases).sort((a, b) => b[1] - a[1])) {
-    console.log(`  ${k.padEnd(28)} ${v}`);
+  console.log(`Triage classification (sum across all reviews):`);
+  console.log(`  raw findings:        ${summary.triage_totals.raw}`);
+  console.log(
+    `  accepted:            ${summary.triage_totals.accepted} (rate ${fmt(summary.triage_totals.accept_rate)})`,
+  );
+  console.log(`  deferred:            ${summary.triage_totals.deferred}`);
+  console.log(
+    `  rejected:            ${summary.triage_totals.rejected} (rate ${fmt(summary.triage_totals.reject_rate)})`,
+  );
+
+  if (Object.keys(summary.edge_cases).length) {
+    console.log(``);
+    console.log(`Triage edge cases:`);
+    for (const [k, v] of Object.entries(summary.edge_cases).sort((a, b) => b[1] - a[1])) {
+      console.log(`  ${k.padEnd(28)} ${v}`);
+    }
   }
-}
 
-if (Object.keys(summary.rework_iterations).length) {
-  console.log(``);
-  console.log(`Phase 3 rework iterations:`);
-  for (const [it, n] of Object.entries(summary.rework_iterations).sort(
-    (a, b) => Number(a[0]) - Number(b[0]),
-  )) {
-    console.log(`  iteration ${it.padEnd(5)} ${n}`);
+  if (Object.keys(summary.rework_iterations).length) {
+    console.log(``);
+    console.log(`Phase 3 rework iterations:`);
+    for (const [it, n] of Object.entries(summary.rework_iterations).sort(
+      (a, b) => Number(a[0]) - Number(b[0]),
+    )) {
+      console.log(`  iteration ${it.padEnd(5)} ${n}`);
+    }
   }
-}
 
-if (Object.keys(summary.language_preference).length) {
-  console.log(``);
-  console.log(`Language preference (events tagged with lang=):`);
-  for (const [lang, n] of Object.entries(summary.language_preference)) {
-    console.log(`  ${lang.padEnd(8)} ${n}`);
+  if (Object.keys(summary.language_preference).length) {
+    console.log(``);
+    console.log(`Language preference (events tagged with lang=):`);
+    for (const [lang, n] of Object.entries(summary.language_preference)) {
+      console.log(`  ${lang.padEnd(8)} ${n}`);
+    }
   }
-}
 
-if (Object.keys(summary.cost_per_model).length) {
-  console.log(``);
-  console.log(`Cost / token telemetry (per model):`);
-  console.log(
-    `  ${"model".padEnd(20)} ${"calls".padStart(6)} ${"duration_ms".padStart(13)} ${"tokens_in".padStart(11)} ${"tokens_out".padStart(11)} ${"cached".padStart(11)} ${"cache%".padStart(7)}`,
-  );
-  for (const [m, t] of Object.entries(summary.cost_per_model).sort(
-    (a, b) => b[1].calls - a[1].calls,
-  )) {
-    const pct = t.cache_ratio === null ? " - " : `${Math.round(t.cache_ratio * 100)}%`;
+  if (Object.keys(summary.cost_per_model).length) {
+    console.log(``);
+    console.log(`Cost / token telemetry (per model):`);
+    console.log(
+      `  ${"model".padEnd(20)} ${"calls".padStart(6)} ${"duration_ms".padStart(13)} ${"tokens_in".padStart(11)} ${"tokens_out".padStart(11)} ${"cached".padStart(11)} ${"cache%".padStart(7)}`,
+    );
+    for (const [m, t] of Object.entries(summary.cost_per_model).sort(
+      (a, b) => b[1].calls - a[1].calls,
+    )) {
+      const pct = t.cache_ratio === null ? " - " : `${Math.round(t.cache_ratio * 100)}%`;
+      console.log(
+        `  ${m.padEnd(20)} ${String(t.calls).padStart(6)} ${String(t.duration_ms).padStart(13)} ${String(t.tokens_in).padStart(11)} ${String(t.tokens_out).padStart(11)} ${String(t.tokens_cached).padStart(11)} ${pct.padStart(7)}`,
+      );
+    }
+    const oc = summary.cache_reuse;
+    const ocPct = oc.cache_ratio === null ? " - " : `${Math.round(oc.cache_ratio * 100)}%`;
     console.log(
-      `  ${m.padEnd(20)} ${String(t.calls).padStart(6)} ${String(t.duration_ms).padStart(13)} ${String(t.tokens_in).padStart(11)} ${String(t.tokens_out).padStart(11)} ${String(t.tokens_cached).padStart(11)} ${pct.padStart(7)}`,
+      `  overall prompt-cache reuse: ${oc.tokens_cached} / ${oc.tokens_in + oc.tokens_cached} input tokens = ${ocPct}`,
     );
   }
-  const oc = summary.cache_reuse;
-  const ocPct = oc.cache_ratio === null ? " - " : `${Math.round(oc.cache_ratio * 100)}%`;
-  console.log(
-    `  overall prompt-cache reuse: ${oc.tokens_cached} / ${oc.tokens_in + oc.tokens_cached} input tokens = ${ocPct}`,
-  );
 }

package/pipeline/scripts/autopilot-arming.mjs

@@ -32,6 +32,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
 
 const ROOT = process.env.MA_AUTOPILOT_ROOT || join(homedir(), ".claude", "autopilot");
 const PREFS =
@@ -142,6 +143,6 @@ function main(argv) {
   return 0;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (invokedDirectly(import.meta.url)) {
   process.exit(main(process.argv));
 }

package/pipeline/scripts/autopilot-intake.mjs

@@ -39,6 +39,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, mkdirSync, writeFileSync, renameSync, chmodSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
 
 const ROOT = process.env.MA_AUTOPILOT_ROOT || join(homedir(), ".claude", "autopilot");
 
@@ -382,6 +383,6 @@ function main(argv) {
   return 0;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (invokedDirectly(import.meta.url)) {
   process.exit(main(process.argv));
 }