@polymorphism-tech/morph-spec 8.31.0 → 8.33.0

package/src/lib/tasks/test-runner.js

@@ -8,32 +8,46 @@
  *      .sln) → "dotnet test <proj> --nologo -v q" for each match
  *   4. package.json present AND has scripts.test → "npm test"
  *   5. null (no test suite detected)
+ *
+ * Step 3 deliberately does NOT see linked git worktrees. A worktree is another
+ * feature's checkout of the SAME repo: its `tests/X.Tests.csproj` is a copy of
+ * the one already matched at the root, so including it both doubles the wall
+ * clock and reports on code that is not the tree under verification. In the
+ * field this produced a red `tests` node — "fail" at exactly the timeout, with
+ * the first run's own summary reading "Com falha: 0" — while nothing had
+ * failed. Two independent filters carry that rule (see collectDotnetTestProjects):
+ * the CONVENTION path (worktrees/, .worktrees/) and, for worktrees created
+ * anywhere else, the registry git itself keeps.
  */
 
-import { execSync } from 'child_process';
+import { execSync, execFileSync } from 'child_process';
 import { existsSync, readFileSync, readdirSync } from 'fs';
-import { join } from 'path';
+import { join, resolve, relative, isAbsolute } from 'path';
 import { globSync } from 'glob';
 
+import { WORKTREES_DIR, LEGACY_WORKTREES_DIR } from '../../commands/project/worktree.js';
+
 /**
- * Resolve the test command for a project.
+ * Timeout budget granted to ONE test project. The chained `a && b` command is
+ * given this much per link: a fixed cap made every multi-project chain born
+ * condemned — it timed out for being long, not for being broken.
+ */
+export const DEFAULT_TEST_TIMEOUT_PER_PROJECT = 120_000;
+
+/**
+ * Resolve the test command for a project, together with how many test projects
+ * it chains — the timeout budget is derived from that count.
  *
  * @param {string} [projectPath] - Project root directory (defaults to '.')
- * @returns {string | null} The test command to run, or null if none found
+ * @returns {{ command: string | null, projectCount: number, source: string }}
+ *   `source` is one of 'config' | 'dotnet-root' | 'dotnet-scan' | 'npm' | 'none'.
  */
-export function resolveTestCommand(projectPath = '.') {
+export function resolveTestPlan(projectPath = '.') {
   // 1. Read from .morph/config/config.json
-  const configPath = join(projectPath, '.morph', 'config', 'config.json');
-  if (existsSync(configPath)) {
-    try {
-      const config = JSON.parse(readFileSync(configPath, 'utf8'));
-      const cmd = config?.project?.testCommand;
-      if (cmd && typeof cmd === 'string') {
-        return cmd;
-      }
-    } catch {
-      // Malformed config — fall through to detection
-    }
+  const config = readConfig(projectPath);
+  const configured = config?.project?.testCommand;
+  if (configured && typeof configured === 'string') {
+    return { command: configured, projectCount: 1, source: 'config' };
   }
 
   // 2. Detect .NET project (sln/csproj at root) → dotnet test
@@ -43,7 +57,7 @@ export function resolveTestCommand(projectPath = '.') {
       (entry) => entry.endsWith('.sln') || entry.endsWith('.csproj')
     );
     if (hasDotnetProject) {
-      return 'dotnet test';
+      return { command: 'dotnet test', projectCount: 1, source: 'dotnet-root' };
     }
   } catch {
     // Unreadable project directory — fall through to next detection
@@ -53,19 +67,13 @@ export function resolveTestCommand(projectPath = '.') {
   // (e.g. tests/MyApp.Tests/MyApp.Tests.csproj), common in monorepos that
   // have no root .sln. Run each matched project explicitly rather than a
   // bare `dotnet test` (which finds nothing to build at the root).
-  try {
-    const testProjects = globSync('**/*Tests.csproj', {
-      cwd: projectPath,
-      ignore: ['**/bin/**', '**/obj/**', '**/node_modules/**'],
-    });
-    if (testProjects.length > 0) {
-      return testProjects
-        .sort()
-        .map((p) => `dotnet test "${p}" --nologo -v q`)
-        .join(' && ');
-    }
-  } catch {
-    // Glob failure — fall through to next detection
+  const testProjects = collectDotnetTestProjects(projectPath);
+  if (testProjects.length > 0) {
+    return {
+      command: testProjects.map((p) => `dotnet test "${p}" --nologo -v q`).join(' && '),
+      projectCount: testProjects.length,
+      source: 'dotnet-scan',
+    };
   }
 
   // 4. package.json present AND has scripts.test → npm test
@@ -74,7 +82,7 @@ export function resolveTestCommand(projectPath = '.') {
     try {
       const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
       if (pkg?.scripts?.test) {
-        return 'npm test';
+        return { command: 'npm test', projectCount: 1, source: 'npm' };
       }
     } catch {
       // Malformed package.json — fall through to null
@@ -82,43 +90,197 @@ export function resolveTestCommand(projectPath = '.') {
   }
 
   // 5. Nothing found
-  return null;
+  return { command: null, projectCount: 0, source: 'none' };
+}
+
+/**
+ * Resolve the test command for a project.
+ *
+ * @param {string} [projectPath] - Project root directory (defaults to '.')
+ * @returns {string | null} The test command to run, or null if none found
+ */
+export function resolveTestCommand(projectPath = '.') {
+  return resolveTestPlan(projectPath).command;
+}
+
+/**
+ * Find the *Tests.csproj files that belong to THIS tree — never to a linked
+ * worktree of the same repo.
+ *
+ * Two filters, because one is not enough:
+ *   - the glob ignore covers worktrees created by convention (`worktrees/{f}`
+ *     and the legacy `.worktrees/{f}`), which is where `morph-spec worktree
+ *     setup` puts them;
+ *   - `git worktree list --porcelain` covers every OTHER location, including a
+ *     worktree someone created by hand outside the convention. Fail-open: no
+ *     git, no answer, no filter — the convention filter still stands.
+ *
+ * @param {string} projectPath
+ * @returns {string[]} Project-relative csproj paths, sorted
+ */
+function collectDotnetTestProjects(projectPath) {
+  let matches;
+  try {
+    matches = globSync('**/*Tests.csproj', {
+      cwd: projectPath,
+      ignore: [
+        '**/bin/**',
+        '**/obj/**',
+        '**/node_modules/**',
+        `${WORKTREES_DIR}/**`,
+        `${LEGACY_WORKTREES_DIR}/**`,
+      ],
+    });
+  } catch {
+    // Glob failure — caller falls through to the next detection step
+    return [];
+  }
+
+  const linked = listLinkedWorktreePaths(projectPath);
+  if (linked.length > 0) {
+    matches = matches.filter(
+      (p) => !linked.some((wt) => isInside(resolve(projectPath, p), wt))
+    );
+  }
+
+  return matches.sort();
+}
+
+/**
+ * Absolute paths of the git worktrees linked to this repo, excluding the tree
+ * being verified. Fail-open — a repo without git (or a git that errors) yields
+ * an empty list, and discovery proceeds on the convention filter alone.
+ *
+ * @param {string} projectPath
+ * @returns {string[]}
+ */
+function listLinkedWorktreePaths(projectPath) {
+  let out;
+  try {
+    out = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+      cwd: projectPath,
+      stdio: 'pipe',
+      encoding: 'utf8',
+      windowsHide: true,
+    });
+  } catch {
+    return [];
+  }
+
+  const self = resolve(projectPath);
+  return out
+    .split('\n')
+    .filter((line) => line.startsWith('worktree '))
+    .map((line) => resolve(line.slice('worktree '.length).trim()))
+    .filter((p) => p && p !== self);
+}
+
+/** True when `child` is `parent` or lives under it. */
+function isInside(child, parent) {
+  const rel = relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+function readConfig(projectPath) {
+  const configPath = join(projectPath, '.morph', 'config', 'config.json');
+  if (!existsSync(configPath)) return null;
+  try {
+    return JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch {
+    // Malformed config — treated as absent by every caller
+    return null;
+  }
+}
+
+/**
+ * Resolve the timeout budget for the test node.
+ *
+ * Precedence: explicit override (`morph-spec verify --timeout`) >
+ * `config.project.testTimeoutMs` > default scaled by the number of chained
+ * test projects.
+ *
+ * @param {string} projectPath
+ * @param {number} projectCount - How many test projects the command chains
+ * @param {number} [override] - Explicit override in ms, if the caller has one
+ * @returns {number} Timeout in ms
+ */
+export function resolveTestTimeout(projectPath, projectCount, override) {
+  if (Number.isFinite(override) && override > 0) return override;
+
+  const configured = readConfig(projectPath)?.project?.testTimeoutMs;
+  if (Number.isFinite(configured) && configured > 0) return configured;
+
+  return DEFAULT_TEST_TIMEOUT_PER_PROJECT * Math.max(1, projectCount);
+}
+
+/**
+ * Count the test runs that reported a summary before the command was cut off.
+ * Heuristic by construction (the summary line is localized), and used only to
+ * name WHICH link of the chain was still running when the clock ran out.
+ */
+function countCompletedRuns(output) {
+  const matches = (output || '').match(
+    /(?:^|\n)\s*(?:Aprovado|Passed|Failed|Reprovado|Com falha|Erro)!/gi
+  );
+  return matches ? matches.length : 0;
 }
 
 /**
  * Run the project's test suite.
  *
  * @param {string} [projectPath] - Project root directory (defaults to '.')
- * @param {object} [opts] - Optional overrides for testing
+ * @param {object} [opts]
+ * @param {number} [opts.timeout] - Explicit timeout in ms (highest precedence)
  * @param {Function} [opts._execSync] - Override execSync for unit testing
- * @returns {{ passed?: boolean, output?: string, exitCode?: number, skipped?: boolean, reason?: string }}
+ * @returns {{ passed?: boolean, output?: string, exitCode?: number, skipped?: boolean, reason?: string, timedOut?: boolean, timeoutMs?: number, message?: string }}
  */
 export function runTestSuite(projectPath = '.', opts = {}) {
-  const cmd = resolveTestCommand(projectPath);
+  const { command: cmd, projectCount } = resolveTestPlan(projectPath);
 
   if (!cmd) {
     return { skipped: true, reason: 'No testCommand configured and no known project file detected' };
   }
 
   const exec = opts._execSync ?? execSync;
+  const timeout = resolveTestTimeout(projectPath, projectCount, opts.timeout);
 
   try {
     const output = exec(cmd, {
       cwd: projectPath,
-      timeout: 120_000,
+      timeout,
       encoding: 'utf8',
       stdio: 'pipe'
     });
-    return { passed: true, output: output ?? '', exitCode: 0 };
+    return { passed: true, output: output ?? '', exitCode: 0, timeoutMs: timeout };
   } catch (err) {
     const output = (err.stdout || '') + (err.stderr || '');
+
+    // A timeout is NOT a red suite: the command was interrupted, so no verdict
+    // exists. Saying so by name is the whole point — the field diagnosis of
+    // this cost a reading of durationMs against a truncated log.
+    if (err.code === 'ETIMEDOUT' || err.killed === true) {
+      const total = Math.max(1, projectCount);
+      const at = Math.min(countCompletedRuns(output) + 1, total);
+      const where = total > 1 ? ` na execução ${at} de ${total}` : '';
+      return {
+        passed: false,
+        timedOut: true,
+        timeoutMs: timeout,
+        buildFailed: false,
+        message: `timeout após ${timeout} ms${where} — nenhum teste falhou, o comando foi interrompido`,
+        output,
+        exitCode: err.status ?? null,
+      };
+    }
+
     const BUILD_FAIL = /Build FAILED|error MSB\d+|error CS\d+|Could not find.*\.csproj/i;
     const buildFailed = BUILD_FAIL.test(output);
     return {
       passed: false,
       buildFailed,
       output,
-      exitCode: err.status ?? 1
+      exitCode: err.status ?? 1,
+      timeoutMs: timeout,
     };
   }
 }

package/src/lib/validators/verify-runner.js

@@ -48,7 +48,8 @@ const OUTPUT_TAIL_LINES = 20;
  * @param {string|null} [taskId] - Task ID for task-scoped verify, or null/undefined for feature scope
  * @param {Object} [options]
  * @param {string} [options.rubric] - Force a rubric id (highest precedence)
- * @param {number} [options.timeout] - Build timeout in ms (default 120000)
+ * @param {number} [options.timeout] - Timeout in ms for the build AND tests nodes
+ *   (default: 120000 for build; for tests, see resolveTestTimeout())
  * @param {boolean} [options.skipTests] - Skip the tests node
  * @param {boolean} [options.skipBuild] - Skip the build node
  * @param {boolean} [options.skipE2e] - Skip the e2e node
@@ -86,7 +87,18 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
   appendBuildFeedback(feedback, nodes.build);
 
   // 2. tests — skipped entirely (no invocation) when build already failed.
-  nodes.tests = await runTestsNode({ projectPath, skipTests, buildNode: nodes.build, _runTestSuite });
+  // The tests node gets the SAME --timeout the user typed, but only when they
+  // typed one: `timeout` above is defaulted for the build, and passing that
+  // default down would silently outrank config.project.testTimeoutMs and the
+  // per-project scaling (see resolveTestTimeout()).
+  const explicitTimeout = Number.isFinite(options.timeout) ? options.timeout : undefined;
+  nodes.tests = await runTestsNode({
+    projectPath,
+    skipTests,
+    buildNode: nodes.build,
+    timeout: explicitTimeout,
+    _runTestSuite,
+  });
   appendTestsFeedback(feedback, nodes.tests);
 
   // 3. validators — ALWAYS runs, even on a red build (free static feedback).
@@ -174,7 +186,7 @@ function appendBuildFeedback(feedback, buildNode) {
 // Tests node
 // ============================================================================
 
-async function runTestsNode({ projectPath, skipTests, buildNode, _runTestSuite }) {
+async function runTestsNode({ projectPath, skipTests, buildNode, timeout, _runTestSuite }) {
   const command = resolveTestCommand(projectPath);
 
   if (skipTests) {
@@ -192,7 +204,7 @@ async function runTestsNode({ projectPath, skipTests, buildNode, _runTestSuite }
   }
 
   const start = Date.now();
-  const result = await _runTestSuite(projectPath);
+  const result = await _runTestSuite(projectPath, { timeout });
   const durationMs = Date.now() - start;
 
   if (result.skipped) {
@@ -205,6 +217,20 @@ async function runTestsNode({ projectPath, skipTests, buildNode, _runTestSuite }
     };
   }
 
+  // A timeout has no verdict to report: the tail of a truncated log reads like
+  // a passing run cut mid-sentence. Lead with what actually happened.
+  if (result.timedOut) {
+    const tail = tailLines(result.output, OUTPUT_TAIL_LINES);
+    return {
+      status: 'fail',
+      command,
+      durationMs,
+      timedOut: true,
+      reason: result.message,
+      output: tail ? `${result.message}\n${tail}` : result.message,
+    };
+  }
+
   return {
     status: result.passed ? 'pass' : 'fail',
     command,

package/src/lib/worktree/fleet-scanner.js

@@ -28,6 +28,8 @@ import {
   pendingGatesFrom,
 } from '../../../framework/hooks/shared/state-reader.js';
 import { listClaims } from '../../../framework/hooks/shared/claim-registry.js';
+import { buildPrIndex } from '../git/pr-index.js';
+import { pendingPrFeatures } from '../git/pending-prs.js';
 
 function countFrom(raw) {
   const data = JSON.parse(raw);
@@ -133,32 +135,18 @@ function remoteHeads(root) {
 /**
  * One `gh pr list` for the whole scan → Map<headRefName, {number, state}>.
  *
- * Gated on the origin URL actually pointing at github.com — `gh` against any
- * other host is a guaranteed error, and paying its start-up cost to learn that
- * on every `fleet` call is pure latency. Fail-open: no `gh`, not authenticated,
- * or a timeout all yield `null`, which just leaves the PR half of the column
- * empty while `pushed` still works.
+ * Delegates to the shared `buildPrIndex` so `fleet`, `branch prune` and
+ * `doctor --worktrees` cannot answer "does this branch have a PR" differently
+ * — the destructive two read it to decide what NOT to delete.
+ *
+ * Fail-open: `null` (no `gh`, not authenticated, not GitHub, timeout) just
+ * leaves the PR half of the column empty while `pushed` still works.
  *
  * @param {string} root
  * @returns {Map<string,{number:number,state:string}>|null}
  */
 function remotePrs(root) {
-  try {
-    const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: root, stdio: 'pipe' }).toString();
-    if (!/github\.com/i.test(url)) return null;
-    const out = execFileSync('gh', ['pr', 'list', '--state', 'all', '--limit', '100', '--json', 'number,state,headRefName'], {
-      cwd: root, stdio: 'pipe', timeout: 8000,
-    }).toString();
-    const map = new Map();
-    for (const pr of JSON.parse(out)) {
-      // First wins: `gh` lists newest-first, so an OPEN PR shadows an older
-      // closed one on the same branch.
-      if (pr?.headRefName && !map.has(pr.headRefName)) map.set(pr.headRefName, { number: pr.number, state: pr.state });
-    }
-    return map;
-  } catch {
-    return null;
-  }
+  return buildPrIndex(root, { limit: 100 });
 }
 
 /**
@@ -297,5 +285,47 @@ export function scanFleet(cwd = process.cwd()) {
     }
   } catch { /* fail-open */ }
 
+  // Features that exist ONLY as an open PR: no registered worktree, no
+  // `.morph/features/*` folder in this tree. This is exactly what
+  // `finish --pr` leaves behind — and without this pass `fleet` would say
+  // "nothing in flight" about work that is under review on GitHub.
+  //
+  // `prs` was attempted above whenever `heads` is truthy (`remotePrs` runs —
+  // see `const prs = heads ? remotePrs(root) : null;` — regardless of
+  // whether that `gh` call itself succeeded). Gate on the SAME condition
+  // `remotePrs` used, not on `prs !== null`: `remotePrs`/`buildPrIndex` can
+  // fail (timeout, not authenticated, malformed JSON) and legitimately
+  // return `null` even after really invoking `gh`. Passing that `null`
+  // through lets `pendingPrFeatures` short-circuit on its own documented
+  // contract (explicit `null` index = known unknown, never a fallback build)
+  // instead of retrying `gh` a second time in the same scan. Only when
+  // `remotePrs` was never attempted at all (`heads` falsy) does
+  // `pendingPrFeatures` get no index, so it makes the first (and only) `gh`
+  // call itself.
+  try {
+    const seen = new Set(entries.map((e) => e.feature));
+    const pendOpts = heads ? { index: prs } : {};
+    for (const p of pendingPrFeatures(root, pendOpts) || []) {
+      if (seen.has(p.feature)) continue;
+      entries.push({
+        feature: p.feature,
+        workType: null,
+        phase: 'aguardando-merge',
+        status: 'in_progress',
+        pendingGates: [],
+        location: 'pr-pending',
+        path: null,
+        branch: p.branch,
+        tasks: null,
+        env: null,
+        handoff: { exists: false, generatedAt: null },
+        lastCommit: null,
+        dirty: null,
+        remote: { branch: p.branch, pushed: true, sha: null, pr: { number: p.number, state: p.state } },
+        claim: null,
+      });
+    }
+  } catch { /* fail-open — a pendency not listed must never take down the scan */ }
+
   return { root, entries };
 }

package/src/lib/worktree/ignored-triage.js

@@ -0,0 +1,197 @@
+/**
+ * ignored-triage.js — decide, per gitignored leftover, whether removing a
+ * worktree would DESTROY something or merely delete a copy.
+ *
+ * WHY THIS EXISTS: `git worktree remove` deletes gitignored files outright and
+ * the clean-check that gates it (`git status --porcelain`) omits them by
+ * design, so a user's `.env` dies silently while the command reports success.
+ * The first fix for that refused the removal whenever ANY unrecognised
+ * gitignored path was present — correct, but blind: in the observed session a
+ * worktree carried `.env` and `.env.e2e` that were BYTE-IDENTICAL to the
+ * primary root's, alongside a `keys/key-*.xml` that existed nowhere else. The
+ * refusal treated them alike, and the only escape it offered
+ * (`--discard-ignored`) destroyed the unique one together with the replicas.
+ *
+ * The triage below replaces "recognised vs not" with the question that actually
+ * decides whether bytes are lost:
+ *
+ *   REPLICABLE — the primary root has the same relative path with identical
+ *                content. Deleting the worktree's copy loses nothing; the
+ *                original stays where it always was.
+ *   DISPOSABLE — a well-known build artifact (`bin/`, `obj/`, `node_modules/`,
+ *                `__pycache__/`, `test-results/`, `.auth/`, `*.tsbuildinfo`).
+ *                Reproducible from source, which is a STRONGER guarantee than
+ *                backed up.
+ *   EXCLUSIVE  — everything else: no counterpart in the root, or a counterpart
+ *                whose content differs. These are the only bytes at stake, and
+ *                the caller copies them to `finish-backup` before proceeding.
+ *
+ * Fail-CLOSED on every uncertainty: an unreadable file, a hash that cannot be
+ * computed, a directory too large to compare, a counterpart that is a link
+ * rather than a real file — all classify as EXCLUSIVE. Being wrong in that
+ * direction costs a backup copy; being wrong the other way costs the file.
+ */
+
+import { createHash } from 'crypto';
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Well-known, regenerable build artifacts. Deliberately narrow — do NOT add
+ * speculative patterns (`dist/`, `.next/`) that a project might legitimately
+ * hand-edit; anything unlisted still reaches the EXCLUSIVE bucket, where it is
+ * backed up rather than assumed disposable.
+ *
+ * `.auth/` (Playwright storage state) belongs here for a reason worth stating:
+ * it holds a captured session, so it LOOKS like precious local state — but it
+ * is regenerated by the auth setup project on the next run, and it expires on
+ * its own. Keeping it out of the backup avoids copying credentials around.
+ */
+const DISPOSABLE_DIR_NAMES = new Set([
+  'bin', 'obj', 'node_modules', '__pycache__', 'test-results', '.auth',
+]);
+const DISPOSABLE_FILE_RE = /\.tsbuildinfo$/;
+
+/**
+ * Comparing a directory recursively is only worth doing while it stays small:
+ * the point is to spare `.env`-sized replicas from a needless refusal, not to
+ * checksum a data set. Past either cap the answer becomes EXCLUSIVE (the safe
+ * direction), and the caller backs it up.
+ */
+const REPLICABLE_MAX_FILES = 500;
+const REPLICABLE_MAX_BYTES = 8 * 1024 * 1024;
+
+/**
+ * @param {string} p - forward-slash relative path
+ * @returns {boolean}
+ */
+export function isDisposableBuildArtifact(p) {
+  if (DISPOSABLE_FILE_RE.test(p)) return true;
+  return p.split('/').filter(Boolean).some((seg) => DISPOSABLE_DIR_NAMES.has(seg));
+}
+
+function sha256OfFile(path) {
+  try {
+    return createHash('sha256').update(readFileSync(path)).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Real file (not a link, not a directory)? A reparse point must never be read
+ * THROUGH — following one is the exact failure mode the whole teardown path
+ * exists to prevent — so a link on either side makes the pair incomparable.
+ */
+function isRealFile(path) {
+  try {
+    return lstatSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isRealDir(path) {
+  try {
+    return lstatSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every real file under `dir`, relative to it. Returns null when the walk hits
+ * a link, an unreadable entry, or either cap — "cannot enumerate" and "too big
+ * to compare" both mean "do not claim this is replicable".
+ */
+function walkFiles(dir, budget) {
+  const out = [];
+  const stack = [''];
+  while (stack.length) {
+    const rel = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(join(dir, rel), { withFileTypes: true });
+    } catch {
+      return null;
+    }
+    for (const e of entries) {
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      const childAbs = join(dir, childRel);
+      if (e.isSymbolicLink()) return null; // never compare through a link
+      if (e.isDirectory()) { stack.push(childRel); continue; }
+      if (!e.isFile()) return null; // socket/fifo/unknown — incomparable
+      let size;
+      try { size = lstatSync(childAbs).size; } catch { return null; }
+      budget.files += 1;
+      budget.bytes += size;
+      if (budget.files > REPLICABLE_MAX_FILES || budget.bytes > REPLICABLE_MAX_BYTES) return null;
+      out.push(childRel);
+    }
+  }
+  return out;
+}
+
+/**
+ * Does `root/rel` hold exactly the same content as `worktree/rel`?
+ *
+ * Files compare by SHA-256; directories compare by having the SAME set of
+ * files, each with an identical hash — a root copy that is merely a SUPERSET
+ * is not a replica of the worktree's, because the worktree's own extra files
+ * would still be lost.
+ *
+ * @returns {boolean} false on ANY uncertainty
+ */
+export function isReplicatedInRoot(worktreePath, rootPath, rel) {
+  const src = join(worktreePath, rel);
+  const dst = join(rootPath, rel);
+  if (!existsSync(src) || !existsSync(dst)) return false;
+
+  if (isRealFile(src)) {
+    if (!isRealFile(dst)) return false;
+    const a = sha256OfFile(src);
+    const b = sha256OfFile(dst);
+    return a !== null && a === b;
+  }
+
+  if (isRealDir(src)) {
+    if (!isRealDir(dst)) return false;
+    const srcFiles = walkFiles(src, { files: 0, bytes: 0 });
+    if (srcFiles === null) return false;
+    const dstFiles = walkFiles(dst, { files: 0, bytes: 0 });
+    if (dstFiles === null) return false;
+    if (srcFiles.length !== dstFiles.length) return false;
+    const dstSet = new Set(dstFiles);
+    for (const f of srcFiles) {
+      if (!dstSet.has(f)) return false;
+      const a = sha256OfFile(join(src, f));
+      const b = sha256OfFile(join(dst, f));
+      if (a === null || a !== b) return false;
+    }
+    return true;
+  }
+
+  return false; // a link, or something that is neither — incomparable
+}
+
+/**
+ * Split gitignored worktree paths into the three buckets above.
+ *
+ * ORDER IS DELIBERATE: disposable is checked FIRST, so a `bin/` that happens to
+ * be byte-identical to the root's is discarded rather than hashed, and a
+ * `node_modules` never enters the comparison budget at all.
+ *
+ * @param {{ worktreePath: string, rootPath: string, paths: string[] }} args
+ * @returns {{ replicable: string[], disposable: string[], exclusive: string[] }}
+ */
+export function triageIgnoredPaths({ worktreePath, rootPath, paths }) {
+  const replicable = [];
+  const disposable = [];
+  const exclusive = [];
+  for (const rel of paths) {
+    if (isDisposableBuildArtifact(rel)) { disposable.push(rel); continue; }
+    if (isReplicatedInRoot(worktreePath, rootPath, rel)) { replicable.push(rel); continue; }
+    exclusive.push(rel);
+  }
+  return { replicable, disposable, exclusive };
+}