@mmerterden/multi-agent-pipeline 17.6.0 → 19.0.0

package/pipeline/schemas/scope-check.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/scope-check.schema.json",
   "version": "1.0.0",
   "title": "Multi-Agent Pipeline  -  Phase 3 scope self-check",
-  "description": "Written by Phase 3 Step 3.7 to $WORKTREE/.pipeline/scope-check.json before the Phase 4 handoff: one stated reason per file in the diff, the changes deliberately not made, and the code-simplifier rationales. scope-check-gate.mjs compares files[] with the real diff; Phase 4 injects the record as <scope-self-check>; Phase 6 builds the PR Changes bullets and the follow-up list from it.",
+  "description": "Written by Phase 2 Step 3.7 to $WORKTREE/.pipeline/scope-check.json before the Phase 4 handoff: one stated reason per file in the diff, the changes deliberately not made, and the code-simplifier rationales. scope-check-gate.mjs compares files[] with the real diff; Phase 4 injects the record as <scope-self-check>; Phase 4 builds the PR Changes bullets and the follow-up list from it.",
   "type": "object",
   "additionalProperties": false,
   "required": ["version", "taskId", "files"],

package/pipeline/schemas/test-gap.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/test-gap.schema.json",
   "version": "1.0.0",
-  "title": "Multi-Agent Pipeline  -  Phase 5 test gap report",
+  "title": "Multi-Agent Pipeline  -  Phase 3 test gap report",
   "description": "Output of test-gap-scan.mjs. Lists symbols added/changed in the diff that have no paired test file or no matching test method. Advisory in default mode; opt-in blocking via prefs.testGap.blockingThreshold.",
   "type": "object",
   "additionalProperties": false,

package/pipeline/schemas/token-budget.json

@@ -1,32 +1,26 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/token-budget.json",
-  "description": "Per-phase token ceilings for the lazy-loaded pipeline docs, enforced by smoke-token-budget.sh. Only the ACTIVE phase is loaded at run time and nothing truncates a phase document, so these numbers govern what may be written, not what a run receives. Two rules, and the split is the point. `max_tokens` and `total_max_tokens` are committed constants a human owns: computing them would end the gate, because a ceiling that is always current x k can never fail. The warn tier is NOT stored - the gate derives it per phase from that phase's own git history (median + 3*MAD of its historical per-commit deltas, which is robust to the one 980-token release that makes sigma meaningless on phase-4), because a soft line maintained by hand rots, and this one rotted twice: it was reset at v13.6.0 when five lines had gone permanently amber, and six of eight were amber again by v17.1.0. A ceiling more than 25% above the measurement is stale and fails, which is the 'only ratchets down' rule the SKILL.md grace list always had and this budget never did. Change history: docs/token-budget-history.md.",
+  "description": "Per-phase token ceilings for the lazy-loaded pipeline docs, enforced by smoke-token-budget.sh. Only the ACTIVE phase is loaded at run time and nothing truncates a phase document, so these numbers govern what may be written, not what a run receives. Two rules, and the split is the point. `max_tokens` and `total_max_tokens` are committed constants a human owns: computing them would end the gate, because a ceiling that is always current x k can never fail. The warn tier is NOT stored - the gate derives it per phase from that phase's own git history (median + 3*MAD of its historical per-commit deltas, which is robust to the one 980-token release that makes sigma meaningless on phase-4), because a soft line maintained by hand rots, and this one rotted twice: it was reset at v13.6.0 when five lines had gone permanently amber, and six of eight were amber again by v17.1.0. A ceiling more than 25% above the measurement is stale and fails, which is the 'only ratchets down' rule the SKILL.md grace list always had and this budget never did. Ceilings are DERIVED from schemas/phases.json and re-measured after the v19.0.0 six-phase merge, not summed from the eight old ones: the two-sided rule fails a ceiling more than 25% above the measurement, so a sum would have shipped stale by construction. Change history: docs/token-budget-history.md.",
   "phases": {
     "phase-0-init": {
       "max_tokens": 13400
     },
-    "phase-1-analysis": {
-      "max_tokens": 4600
+    "phase-1-plan": {
+      "max_tokens": 10000
     },
-    "phase-2-planning": {
-      "max_tokens": 6500
-    },
-    "phase-3-dev": {
-      "max_tokens": 9450
+    "phase-2-dev": {
+      "max_tokens": 10650
     },
-    "phase-4-review": {
-      "max_tokens": 15150
+    "phase-3-review": {
+      "max_tokens": 17200
     },
-    "phase-5-test": {
-      "max_tokens": 3050
-    },
-    "phase-6-commit": {
-      "max_tokens": 6550
+    "phase-4-commit": {
+      "max_tokens": 6500
     },
-    "phase-7-report": {
-      "max_tokens": 6350
+    "phase-5-report": {
+      "max_tokens": 5550
     }
   },
-  "total_max_tokens": 63150
+  "total_max_tokens": 63300
 }

package/pipeline/schemas/triage-output.schema.json

@@ -2,8 +2,8 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/triage-output.schema.json",
   "version": "3.4.0",
-  "title": "Multi-Agent Pipeline  -  Phase 4 triage output",
-  "description": "Contract for the Opus triage agent's JSON output in Phase 4 Step 3. Triage consumes merged reviewer findings and splits them into accepted/deferred/rejected. Only `accepted` blocking/important items trigger Phase 3 rework. v3.1.0 adds the optional `consensus` block so triage can surface reviewer-agreement risk (false consensus among same-base-model reviewers) instead of silently merging. v3.2.0 adds the optional per-finding `verification` block written by Phase 4 Step 3.7 (verify-by-test): the empirical repro-test outcome for accepted blocking findings. v3.3.0 carries ruleId + criteriaSource through triage so a finding that cites a stable rule ID keeps that citation into Phase 6 and Phase 7, and the lesson loop can key durable learnings by rule. v3.4.0 adds the optional per-finding fingerprint (finding-fingerprint.mjs) so review-delta.mjs can tell still-present, resolved and new findings apart between rounds.",
+  "title": "Multi-Agent Pipeline  -  Phase 3 triage output",
+  "description": "Contract for the Opus triage agent's JSON output in Phase 4 Step 3. Triage consumes merged reviewer findings and splits them into accepted/deferred/rejected. Only `accepted` blocking/important items trigger Phase 3 rework. v3.1.0 adds the optional `consensus` block so triage can surface reviewer-agreement risk (false consensus among same-base-model reviewers) instead of silently merging. v3.2.0 adds the optional per-finding `verification` block written by Phase 3 Step 3.7 (verify-by-test): the empirical repro-test outcome for accepted blocking findings. v3.3.0 carries ruleId + criteriaSource through triage so a finding that cites a stable rule ID keeps that citation into Phase 4 and Phase 5, and the lesson loop can key durable learnings by rule. v3.4.0 adds the optional per-finding fingerprint (finding-fingerprint.mjs) so review-delta.mjs can tell still-present, resolved and new findings apart between rounds.",
   "type": "object",
   "additionalProperties": false,
   "required": ["accepted", "deferred", "rejected", "approved"],
@@ -17,7 +17,7 @@
     },
     "deferred": {
       "type": "array",
-      "description": "Findings that are real but out of current task scope. Surfaced in Phase 7 report; not actioned.",
+      "description": "Findings that are real but out of current task scope. Surfaced in Phase 5 report; not actioned.",
       "items": {
         "type": "object",
         "additionalProperties": false,
@@ -55,7 +55,7 @@
     },
     "approved": {
       "type": "boolean",
-      "description": "True if no accepted BLOCKING items remain. The pipeline uses this to gate Phase 5 / Phase 6 entry."
+      "description": "True if no accepted BLOCKING items remain. The pipeline uses this to gate Phase 5 / Phase 4 entry."
     },
     "consensus": {
       "$ref": "#/$defs/consensus"
@@ -111,7 +111,7 @@
         },
         "disagreements": {
           "type": "array",
-          "description": "Findings where reviewers split (existence or severity). Surfaced verbatim in the Phase 7 report and at the Step 4 user checkpoint.",
+          "description": "Findings where reviewers split (existence or severity). Surfaced verbatim in the Phase 5 report and at the Step 4 user checkpoint.",
           "items": {
             "type": "object",
             "additionalProperties": false,
@@ -142,7 +142,7 @@
     "verification": {
       "type": "object",
       "additionalProperties": false,
-      "description": "v3.2.0 verify-by-test outcome (Phase 4 Step 3.7, opt-in via prefs.global.verifyByTest). confirmed = repro test failed as the finding predicts (finding stands, test kept as the Phase 3 RED test); not-reproduced = repro test passed under evidence-gate (finding downgraded to deferred); inconclusive = compile error / timeout / not unit-testable (judgment verdict stands).",
+      "description": "v3.2.0 verify-by-test outcome (Phase 3 Step 3.7, opt-in via prefs.global.verifyByTest). confirmed = repro test failed as the finding predicts (finding stands, test kept as the Phase 3 RED test); not-reproduced = repro test passed under evidence-gate (finding downgraded to deferred); inconclusive = compile error / timeout / not unit-testable (judgment verdict stands).",
       "required": ["result"],
       "properties": {
         "result": {

package/pipeline/scripts/README.md

@@ -19,10 +19,10 @@ Validate contracts. Each emits `══ <name> smoke: N passed, M failed ══`
 
 ### Phase contracts
 - `smoke-phase-0-multi-repo.sh`  -  Phase 0 multi-repo mode fetch + worktree atomicity
-- `smoke-phase-6-multi.sh`  -  Phase 6 multi-repo commit/PR cross-linking
+- `smoke-phase-6-multi.sh`  -  Phase 4 multi-repo commit/PR cross-linking
 - `smoke-phase-banner.sh` + `smoke-phase-tracker.sh`  -  Phase UI output contracts
-- `smoke-phase4-triage.sh`  -  Phase 4 reviewer → triage flow
-- `smoke-verify-by-test.sh`  -  Phase 4 Step 3.7 verify-by-test contract (v10.8.0)
+- `smoke-phase4-triage.sh`  -  Phase 3 reviewer → triage flow
+- `smoke-verify-by-test.sh`  -  Phase 3 Step 3.7 verify-by-test contract (v10.8.0)
 - `smoke-handoff-contract.sh`  -  phase-boundary structured handoff + handoff-first resume (v10.8.0)
 - `smoke-update-check.sh`  -  Phase 0 Step 0.6 update-check + required-floor contract (v10.9.0, floor v15.14.0)
 - `smoke-context-links.sh`  -  context-link-extractor classification contract, all types (v15.14.0)

package/pipeline/scripts/_code-graph.mjs

@@ -1,7 +1,7 @@
 /**
- * @file _code-graph.mjs  -  deterministic, LLM-free code graph for Phase 1 and Phase 7.
+ * @file _code-graph.mjs  -  deterministic, LLM-free code graph for Phase 1 and Phase 5.
  *
- * Phase 1 narrows its Explore fan-out with this graph, and Phase 7 refreshes it
+ * Phase 1 narrows its Explore fan-out with this graph, and Phase 5 refreshes it
  * instead of hand-writing architecture.md from a single task's window. The
  * design follows graphify (Graphify-Labs/graphify): AST-quality extraction with
  * zero LLM cost, one graph file, an incremental manifest gate, god-node hubs,

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 4 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 4 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/_smoke-root.sh

@@ -20,7 +20,7 @@
 #
 # Usage (from any script in pipeline/scripts/):
 #   . "$(dirname "${BASH_SOURCE[0]}")/_smoke-root.sh"
-#   grep -q needle "$MA_REFS/phases/phase-4-review.md"
+#   grep -q needle "$MA_REFS/phases/phase-3-review.md"
 #
 # Exports:
 #   MA_LAYOUT     "repo" | "install"