archgen-mcp 0.0.6 → 0.0.7

package/src/core/codegraph-manager.mjs

@@ -15,7 +15,7 @@
 //
 // SAFETY: MCP configs are written only with approval (otherwise the plan is
 // reported); non-JSON configs are reported, never rewritten.
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -26,20 +26,81 @@ export const CODEGRAPH_PACKAGE = '@colbymchenry/codegraph';
 
 /** Run a command; never throws. Returns {ok, status, stdout, stderr}. */
 export function run(cmd, args, opts = {}) {
-  const { timeout = 120000, cwd, env } = opts;
+  const { timeout = 120000, cwd, env, shell } = opts;
   const r = spawnSync(cmd, args, {
     encoding: 'utf8',
     timeout,
     cwd,
     env: env ? { ...process.env, ...env } : process.env,
-    shell: false,
-    // On Windows the npm/codegraph shims are .cmd files, which need a shell.
-    ...(process.platform === 'win32' && /\.(cmd|bat)$/i.test(cmd) ? { shell: true } : {}),
+    // The caller's `shell` wins; otherwise only a Windows .cmd/.bat shim needs
+    // one. The option used to be dropped, so a caller asking for a shell did
+    // not get one.
+    shell: shell === true || (process.platform === 'win32' && /\.(cmd|bat)$/i.test(cmd)),
   });
   if (r.error) return { ok: false, status: -1, stdout: '', stderr: String(r.error.message ?? r.error) };
   return { ok: r.status === 0, status: r.status ?? -1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
 }
 
+/**
+ * Run a command asynchronously; never throws. Returns {ok, status, stdout, stderr}.
+ *
+ * The SYNCHRONOUS form blocks the event loop for the child's whole lifetime,
+ * and the stdio MCP server cannot answer a single request while that
+ * happens — a global install or a full index can take minutes, so every
+ * other request simply queues behind it.
+ *
+ * 'close' (not 'exit') decides the outcome: 'exit' fires when the process is
+ * gone, while its output may still be in flight, and the last chunk of a
+ * long install log would be lost.
+ */
+export function runAsync(cmd, args, opts = {}) {
+  const { timeout = 120000, cwd, env, shell } = opts;
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, args, {
+        cwd,
+        env: env ? { ...process.env, ...env } : process.env,
+        shell: shell === true,
+      });
+    } catch (e) {
+      resolve({ ok: false, status: -1, stdout: '', stderr: String(e?.message ?? e) });
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(result);
+    };
+    const timer =
+      timeout > 0
+        ? setTimeout(() => {
+            try {
+              child.kill('SIGKILL');
+            } catch {
+              /* already gone */
+            }
+          }, timeout)
+        : null;
+    child.stdout?.on('data', (d) => {
+      stdout += d.toString();
+    });
+    child.stderr?.on('data', (d) => {
+      stderr += d.toString();
+    });
+    child.on('error', (e) => {
+      finish({ ok: false, status: -1, stdout, stderr: String(e?.message ?? e) });
+    });
+    child.on('close', (code) => {
+      finish({ ok: code === 0, status: code ?? -1, stdout, stderr });
+    });
+  });
+}
+
 /** Locate an executable on PATH (cross-platform, no shell). */
 export function which(bin, env = process.env) {
   const exts = process.platform === 'win32' ? (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';') : [''];
@@ -102,7 +163,6 @@ export function telemetryState(bin) {
  *   approved?: boolean,
  *   dryRun?: boolean,
  *   telemetry?: 'keep'|'off'|'on',
- *   noUpgrade?: boolean,
  *   noInstall?: boolean,
  *   home?: string,
  *   env?: Record<string, string|undefined>,
@@ -119,7 +179,6 @@ export async function manageCodegraph(opts) {
     approved = false,
     dryRun = false,
     telemetry = 'keep',
-    noUpgrade = false,
     noInstall = false,
     home = homedir(),
     env = process.env,
@@ -140,11 +199,26 @@ export async function manageCodegraph(opts) {
     ok: true,
   };
 
-  /** Install CodeGraph when missing; upgrade to the latest published version. */
-  const ensureCli = () => {
+  /**
+   * Resolve the CodeGraph CLI.
+   *
+   * THE RULE: install it when it is MISSING, and leave it alone when it is
+   * ALREADY THERE.
+   *
+   * An installed CodeGraph is the user's to manage. Upgrading it behind
+   * their back changes a program they may have pinned, and the upgrade ran
+   * on every bootstrap — so a plain `npx archgen-skill init` could rewrite a
+   * working installation. The version that is already on the machine is the
+   * version the MCP config points at, and it works.
+   *
+   * `install` lets a caller ask for the RESOLUTION only — the binary's path
+   * without touching the machine. That is what `wire` needs: wiring is a
+   * configuration change; installing a program globally is not.
+   */
+  const ensureCli = async ({ install = true } = {}) => {
     let found = findCodegraph(env);
     if (!found) {
-      if (noInstall) {
+      if (noInstall || !install) {
         // Caller manages the CLI — fall back to the npx form in the MCP config.
         report.cli.action = 'absent';
         report.cli.detail = `not installed and installation was skipped — the MCP config will use "npx -y ${CODEGRAPH_PACKAGE} serve --mcp"`;
@@ -156,7 +230,7 @@ export async function manageCodegraph(opts) {
       }
       // Official install path; always the latest published release.
       const inv = npmInvocation(['install', '-g', CODEGRAPH_PACKAGE], env);
-      const r = run(inv.command, inv.args, { timeout: 600000, shell: inv.shell, env });
+      const r = await runAsync(inv.command, inv.args, { timeout: 600000, shell: inv.shell, env });
       found = findCodegraph(env);
       if (!found) {
         report.cli.action = 'failed';
@@ -166,37 +240,17 @@ export async function manageCodegraph(opts) {
       }
       report.cli.action = 'installed';
     } else {
+      // Already installed: report it and stop. No upgrade, no version check.
       report.cli.action = 'present';
     }
     report.cli.present = true;
     report.cli.bin = found.bin;
     report.cli.version = found.version;
-
-    if (noUpgrade) return found;
-
-    // Freshness via the official updater (no-op when already current).
-    const chk = run(found.bin, ['upgrade', '--check'], { timeout: 120000, env });
-    const m = /latest\s+v?([0-9][^\s]*)/i.exec((chk.stdout ?? '') + (chk.stderr ?? ''));
-    report.cli.latest = m ? m[1] : null; // informational only
-    if (dryRun) {
-      report.cli.action += '+upgrade';
-      return found;
-    }
-    const up = run(found.bin, ['upgrade'], { timeout: 600000, env });
-    const after = findCodegraph(env);
-    if (after) {
-      report.cli.version = after.version;
-      report.cli.bin = after.bin;
-      report.cli.action += /already up to date/i.test(up.stdout ?? '') ? '+current' : '+upgraded';
-    } else {
-      report.cli.action += '+upgrade-failed';
-      report.ok = false;
-    }
     return found;
   };
 
   /** Wire the MCP server into every detected harness (native + fallback). */
-  const wireHarnesses = (cli) => {
+  const wireHarnesses = async (cli) => {
     const detected = detectHarnesses(registry, projectRoot, home);
     const wanted = targets ?? detected.map((d) => d.id);
     const selected = detected.filter((d) => wanted.includes(d.id));
@@ -222,7 +276,7 @@ export async function manageCodegraph(opts) {
           report.wiring.native.push({ targets: uniqueNative.join(','), location: loc, status: 'planned' });
           continue;
         }
-        const r = run(
+        const r = await runAsync(
           cli.bin ?? 'codegraph',
           ['install', `--target=${uniqueNative.join(',')}`, `--location=${loc}`, '--yes'],
           {
@@ -258,6 +312,7 @@ export async function manageCodegraph(opts) {
       binPath: cli.bin,
       fallbackCommand: 'codegraph',
       skipHarnesses: selected.filter((d) => d.spec.codegraphTarget).map((d) => d.id),
+      targets: selected.map((d) => d.id),
     });
     for (const w of manual.wired) {
       report.wiring.manual.push({ harness: w.harness, path: w.path, key: w.key, ...w });
@@ -290,7 +345,7 @@ export async function manageCodegraph(opts) {
   };
 
   /** Index the project: `codegraph init` builds `.codegraph/` + the first graph. */
-  const initIndex = (cli) => {
+  const initIndex = async (cli) => {
     const codegraphDir = join(projectRoot, '.codegraph');
     if (existsSync(codegraphDir)) {
       report.index.action = 'already-indexed';
@@ -311,7 +366,7 @@ export async function manageCodegraph(opts) {
       return;
     }
     // Official indexing command: creates .codegraph/ AND builds the graph.
-    const r = run(cli.bin ?? 'codegraph', ['init', projectRoot], { timeout: 900000, env });
+    const r = await runAsync(cli.bin ?? 'codegraph', ['init', projectRoot], { timeout: 900000, env });
     if (!r.ok) {
       report.index.action = 'failed';
       report.index.detail = (r.stderr || r.stdout || 'codegraph init failed').trim().split('\n')[0];
@@ -332,7 +387,7 @@ export async function manageCodegraph(opts) {
     }
   };
 
-  const applyTelemetry = (cli) => {
+  const applyTelemetry = async (cli) => {
     const state = telemetryState(cli.bin);
     report.telemetry.state = state;
     if (telemetry === 'keep' || !cli.bin) return;
@@ -356,7 +411,7 @@ export async function manageCodegraph(opts) {
     report.cli.version = cli?.version ?? null;
     // Official freshness check — reports what "latest" means today, no pin.
     if (cli) {
-      const chk = run(cli.bin, ['upgrade', '--check'], { timeout: 120000, env });
+      const chk = await runAsync(cli.bin, ['upgrade', '--check'], { timeout: 120000, env });
       const m = /latest\s+v?([0-9][^\s]*)/i.exec((chk.stdout ?? '') + (chk.stderr ?? ''));
       report.cli.latest = m ? m[1] : null;
     }
@@ -382,23 +437,32 @@ export async function manageCodegraph(opts) {
     }
     report.index.action = existsSync(join(projectRoot, '.codegraph')) ? 'indexed' : 'not-indexed';
   } else if (mode === 'init') {
-    const cli = ensureCli();
-    applyTelemetry(cli);
-    initIndex(cli);
+    const cli = await ensureCli();
+    await applyTelemetry(cli);
+    await initIndex(cli);
+  } else if (mode === 'wire') {
+    // WIRE ONLY. It resolves the binary (so the config can point at it) but
+    // never installs, never upgrades and never writes a global setting: a
+    // wiring request is a request to change the MCP CONFIGS.
+    const cli = await ensureCli({ install: false });
+    const detected = await wireHarnesses(cli);
+    report.detected = detected.map((d) => d.id);
   } else {
-    // ensure | wire
-    const cli = ensureCli();
-    applyTelemetry(cli);
-    const detected = wireHarnesses(cli);
+    // ensure — install the CLI if it is MISSING (an installed one is left
+    // exactly as it is), wire the configs, and index the project.
+    const cli = await ensureCli();
+    await applyTelemetry(cli);
+    const detected = await wireHarnesses(cli);
     if (mode === 'ensure') {
       if (!approved && !dryRun) {
-        // Without approval: print the plan, write no MCP config. The CLI itself
-        // is still installed/upgraded (a program, not a user config).
+        // Without approval: print the plan, write no MCP config. The CLI
+        // itself is still installed if it was missing (a program, not a user
+        // config); an existing one is never touched.
         report.ok = true;
         report.planned = true;
         report.index.action = 'would-index';
       } else {
-        initIndex(cli);
+        await initIndex(cli);
       }
     }
     report.detected = detected.map((d) => d.id);

package/src/core/compat.mjs

@@ -10,7 +10,7 @@
 //   skill/SKILL.md frontmatter
 //     metadata:
 //       requires:
-//         archgen_mcp: ">=0.0.6"
+//         archgen_mcp: ">=x.y.z"
 //
 // `doctor` reports the mismatch; `bootstrap` warns before wiring; CI refuses
 // to ship a skill whose declared minimum exceeds the server's version.
@@ -29,11 +29,21 @@ export function parseVersion(v) {
   return m ? { major: +m[1], minor: +m[2], patch: +m[3] } : null;
 }
 
-/** Compare two versions: -1 / 0 / 1. Unparseable versions compare as equal. */
+/**
+ * Compare two versions: -1 / 0 / 1.
+ *
+ * An unparseable version THROWS. The question "which of these is newer?"
+ * has no answer when one of them is not a version, and answering "0" — the
+ * old behaviour — said "they are the same", which is false and quietly
+ * wrong. `satisfies` answers a different question ("does this version meet
+ * this requirement?") and handles an unknown version as "meets nothing".
+ */
 export function compareVersions(a, b) {
   const x = parseVersion(a);
   const y = parseVersion(b);
-  if (!x || !y) return 0;
+  if (!x || !y) {
+    throw invalidInput(`cannot compare versions: '${a}' and '${b}' are not both versions`, { a, b });
+  }
   for (const k of ['major', 'minor', 'patch']) {
     if (x[k] !== y[k]) return x[k] < y[k] ? -1 : 1;
   }

package/src/core/doc-navigator.mjs

@@ -65,10 +65,10 @@ const FR_ID_SOURCE = '(?<![A-Za-z0-9_])FR-[A-Z0-9]+-\\d+(?![A-Za-z0-9_])';
  * @param {string} input
  * @returns {{slugDir: string, repoRoot: string, slug: string}}
  */
-export function resolveDocScope(input) {
+export function resolveDocScope(input, projectRoot = null) {
   let scoped;
   try {
-    scoped = resolveSlugInput(input);
+    scoped = resolveSlugInput(input, projectRoot);
   } catch (e) {
     if (e instanceof ScopeError) throw invalidInput(`doc-index: ${e.message}`, { input });
     throw invalidInput(`cannot read ${input} (missing or not a directory)`, { input });
@@ -121,13 +121,14 @@ function walkFiles(slugDir, filter) {
     const rel = stack.pop();
     for (const e of readdirSync(rel ? join(slugDir, rel) : slugDir, { withFileTypes: true })) {
       if (e.name.startsWith('.')) continue;
-      const r = rel ? `${rel}/${e.name}` : e.name;
+      const r = rel ? `${rel}/${e.name}` : rel === '' ? e.name : `${rel}/${e.name}`;
       if (e.isDirectory()) stack.push(r);
       else if (filter.test(e.name)) candidates.push(r);
     }
   }
   const chosen = new Map(); // real key -> { rel, isLink }
   let duplicatesSkipped = 0;
+  let escapesSkipped = 0;
   for (const r of candidates.sort()) {
     const abs = join(slugDir, r);
     let key;
@@ -139,6 +140,14 @@ function walkFiles(slugDir, filter) {
       key = resolve(abs); // dangling symlink: keep, keyed by spelled path
       isLink = false;
     }
+    // A file whose REAL path is outside the artifact space is a symlink out
+    // of it. Reading it would return whatever it points at — a private key,
+    // a file from elsewhere on the machine — inside a tool that promises to
+    // read nothing but archgen's own artifacts. Such a file is skipped.
+    if (key !== slugDir && !key.startsWith(slugDir + sep)) {
+      escapesSkipped++;
+      continue;
+    }
     const prev = chosen.get(key);
     if (!prev) {
       chosen.set(key, { rel: r, isLink });
@@ -147,7 +156,11 @@ function walkFiles(slugDir, filter) {
     duplicatesSkipped++;
     if (prev.isLink && !isLink) chosen.set(key, { rel: r, isLink }); // real spelling wins over alias
   }
-  return { files: [...chosen.values()].map((v) => v.rel).sort(), duplicatesSkipped };
+  return {
+    files: [...chosen.values()].map((v) => v.rel).sort(),
+    duplicatesSkipped,
+    escapesSkipped,
+  };
 }
 
 const wordCount = (lines) => lines.join(' ').split(/\s+/).filter(Boolean).length;
@@ -165,7 +178,7 @@ export function docIndex(input, opts = {}) {
   const sectionRef = opts.section ?? null;
   const fileScopeArg = opts.file ?? null;
 
-  const { slugDir, repoRoot, slug } = resolveDocScope(input);
+  const { slugDir, repoRoot, slug } = resolveDocScope(input, opts.projectRoot ?? null);
   const relFromRoot = (abs) => relative(repoRoot, abs).split(sep).join('/');
   const relFromSlug = (abs) => relative(slugDir, abs).split(sep).join('/');
   const parsedDocAt = makeDocCache();
@@ -324,12 +337,18 @@ export function docIndex(input, opts = {}) {
         const hash = link.target.indexOf('#');
         const target = hash === -1 ? link.target : link.target.slice(0, hash);
         const anchor = hash === -1 ? null : link.target.slice(hash + 1);
-        if (target && !existsSync(resolve(dirname(doc.abs), target))) {
+        // A link target is resolved against the document's directory, so a
+        // link like `../../../secrets.md` would otherwise point outside the
+        // artifact space. The link is checked, never READ from outside: a
+        // target outside the slug directory is reported as broken rather
+        // than followed.
+        const targetAbs = target ? resolve(dirname(doc.abs), target) : '';
+        const inside = targetAbs && (targetAbs === slugDir || targetAbs.startsWith(slugDir + sep));
+        if (target && (!inside || !existsSync(targetAbs))) {
           broken.push({ kind: 'link', ref: link.target, file: relFromRoot(doc.abs), line: link.line });
           continue;
         }
         if (anchor && target && /\.md$/i.test(target)) {
-          const targetAbs = resolve(dirname(doc.abs), target);
           const targetDoc = parsedDocAt(targetAbs);
           if (targetDoc && !anchorExists(targetDoc, anchor)) {
             broken.push({ kind: 'anchor', ref: link.target, file: relFromRoot(doc.abs), line: link.line });

package/src/core/fs-safety.mjs

@@ -17,9 +17,9 @@
 // These semantics are inherited verbatim from the CLI's store.js and from
 // skill/scripts/set-status.mjs — the MCP server must not be weaker than the
 // scripts it replaces.
-import { lstatSync, mkdirSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { lstatSync, mkdirSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, resolve, sep } from 'node:path';
-import { permissionDenied } from './errors.mjs';
+import { conflict, permissionDenied } from './errors.mjs';
 
 /** Canonical refusal message — identical wording to the CLI's. */
 export function refuseSymlinkMessage(absPath) {
@@ -42,21 +42,40 @@ export function assertNotSymlink(absPath) {
 }
 
 /**
- * Realpath-escape guard: resolve `absPath` (climbing to the nearest existing
- * ancestor when it does not exist yet, so a symlinked PARENT dir is caught
- * before anything is created beneath it) and refuse when the real location
- * lands outside `rootAbs`.
+ * Realpath-escape guard: refuse anything that lands outside `rootAbs`.
+ *
+ * TWO CHECKS, IN ORDER.
+ *
+ *   1. LEXICAL. After normalization, the path must be inside the root. This
+ *      always applies — it is the primary guard, and it cannot be skipped
+ *      because a path does not exist yet.
+ *   2. REAL. The nearest existing ancestor is resolved and must also be
+ *      inside the root's real path. This is what catches a symlinked
+ *      PARENT directory that would redirect the write elsewhere.
+ *
+ * The guard does NOT fail open: if the root cannot be resolved, only the
+ * lexical check stands, and the lexical check is always applied.
+ *
  * @param {string} rootAbs
  * @param {string} absPath
  */
 export function assertWithinRoot(rootAbs, absPath) {
+  const root = resolve(rootAbs);
+  const abs = resolve(absPath);
+  if (abs !== root && !abs.startsWith(root + sep)) {
+    throw permissionDenied(
+      `refusing a path outside the project: ${absPath} is not inside ${rootAbs}`,
+      { path: absPath, root: rootAbs },
+    );
+  }
+
   let rootReal;
   try {
-    rootReal = realpathSync(rootAbs);
+    rootReal = realpathSync(root);
   } catch {
-    return; // the root itself does not exist yet — nothing can escape it
+    return; // the root itself does not exist yet — the lexical check stands
   }
-  let probe = absPath;
+  let probe = abs;
   for (;;) {
     let exists = true;
     try {
@@ -105,10 +124,13 @@ export function containPath(rootAbs, candidate) {
  *
  * @param {string} file absolute target path
  * @param {string|Buffer} content
- * @param {{eol?: string}} [opts]
+ * @param {{eol?: string, root?: string}} [opts] `root` adds a containment
+ *   check for the whole parent chain, so a symlinked PARENT cannot redirect
+ *   the write outside the tree.
  */
 export function writeFileAtomic(file, content, opts = {}) {
   mkdirSync(dirname(file), { recursive: true });
+  if (opts.root) assertWithinRoot(opts.root, file);
   assertNotSymlink(file);
   let tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
   for (let attempt = 0; ; attempt++) {
@@ -136,5 +158,71 @@ export function writeFileAtomic(file, content, opts = {}) {
   return file;
 }
 
+/**
+ * Run `fn` while holding an exclusive lock on `file`.
+ *
+ * WHY. An atomic write stops a READER seeing a half-written file. It does
+ * not stop two WRITERS losing each other's work: worker A reads tasks.yaml,
+ * worker B reads the same bytes, A writes its status change, B writes its
+ * own from the stale snapshot — and A's change is gone. The parallel
+ * workers are separate processes by design, so the guard has to live on
+ * disk, not in memory.
+ *
+ * The lock is a sibling `<file>.lock` created with O_EXCL. A lock older than
+ * `staleMs` is a crashed holder's leftover and is broken. The lock is always
+ * released, including when `fn` throws.
+ *
+ * @param {string} file the file being mutated
+ * @param {() => any} fn
+ * @param {{timeoutMs?: number, staleMs?: number, pollMs?: number}} [opts]
+ * @returns {any} whatever `fn` returns
+ */
+export function withFileLock(file, fn, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 10_000;
+  const staleMs = opts.staleMs ?? 30_000;
+  const pollMs = opts.pollMs ?? 50;
+  const lockPath = `${file}.lock`;
+  const deadline = Date.now() + timeoutMs;
+
+  mkdirSync(dirname(lockPath), { recursive: true });
+  for (;;) {
+    try {
+      writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+      break;
+    } catch (e) {
+      if (e?.code !== 'EEXIST') throw e;
+      // A lock older than staleMs belongs to a holder that died.
+      try {
+        const age = Date.now() - statSync(lockPath).mtimeMs;
+        if (age > staleMs) {
+          unlinkSync(lockPath);
+          continue;
+        }
+      } catch {
+        continue; // the lock vanished between the EEXIST and the stat
+      }
+      if (Date.now() > deadline) {
+        throw conflict(`timed out after ${timeoutMs}ms waiting for the lock on ${file}`, { file, lockPath });
+      }
+      sleepSync(pollMs);
+    }
+  }
+
+  try {
+    return fn();
+  } finally {
+    try {
+      unlinkSync(lockPath);
+    } catch {
+      /* the lock is already gone */
+    }
+  }
+}
+
+/** Block the current thread for `ms` milliseconds. */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
 
 

package/src/core/graph.mjs

@@ -78,9 +78,14 @@ export function findCycle(prerequisites) {
  * @param {Map<string,any>} byId
  * @param {Map<string,string[]>} prerequisites
  * @returns {{waves: Array<Array<any>>, blockedByFailure: string[]}}
- * Wave membership: every prerequisite is done. Tasks whose TRANSITIVE
- * prerequisites include any failed task are excluded entirely and reported in
- * blockedByFailure (no silent cascades — orchestrator re-plans around them). */
+ * Wave membership: every prerequisite is DONE OR ALREADY QUEUED in an earlier
+ * wave. That is standard topological layering — a task in wave 3 may depend
+ * on a task in wave 2, which is not done yet when wave 3 starts; it is
+ * merely no longer blocked.
+ *
+ * Tasks whose TRANSITIVE prerequisites include any failed task are excluded
+ * entirely and reported in blockedByFailure (no silent cascades — the
+ * orchestrator re-plans around them). */
 export function computeWaves(byId, prerequisites) {
   const done = new Set();
   const failed = new Set();