@dogfood-lab/ingest 1.4.0 → 1.6.0

package/load-context.js

@@ -201,6 +201,25 @@ export function localScenarioFetcher(repoRoot) {
  */
 export const GITHUB_SCENARIO_FETCH_TIMEOUT_MS = 30000;
 
+/**
+ * Default number of fetch attempts (INGEST-PROACT-003). A transient GitHub-API
+ * fault (5xx, 429, network blip) should not turn a loadable scenario into a hard
+ * rejection; a small bounded retry rides out the hiccup. Kept small — three
+ * attempts is enough to clear a momentary throttle without amplifying a real
+ * outage into a multi-minute stall (the AbortController timeout still bounds each
+ * attempt, and a 404/invalid-id is never retried).
+ */
+export const GITHUB_SCENARIO_FETCH_ATTEMPTS = 3;
+
+/** Initial backoff before the first retry (ms); doubles per attempt, capped. */
+const RETRY_BASE_MS = 250;
+const RETRY_MAX_MS = 2000;
+
+/** Default async backoff. Injectable (`opts.sleepImpl`) so tests run instantly. */
+function defaultSleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
 /**
  * GitHub scenario fetcher. Loads scenario definitions from a source repo
  * via the GitHub API at a specific commit SHA.
@@ -219,28 +238,45 @@ export const GITHUB_SCENARIO_FETCH_TIMEOUT_MS = 30000;
  * Both surfaces honour the per-request AbortController timeout
  * (`GITHUB_SCENARIO_FETCH_TIMEOUT_MS`, overridable via `opts.timeoutMs`).
  *
+ * INGEST-PROACT-003: each call makes up to `opts.attempts`
+ * (`GITHUB_SCENARIO_FETCH_ATTEMPTS`) tries with exponential backoff, retrying
+ * ONLY the transient classes — request timeout, HTTP 5xx, HTTP 429, and network
+ * rejects. A 404 (`not_found`), an `invalid_id`, and a `parse_error` are
+ * DEFINITIVE answers and are returned immediately without a retry (mirrors the
+ * EPERM/EBUSY-only discipline in `lib/rename-with-retry.js`). The backoff sleep
+ * is injectable (`opts.sleepImpl`) so tests do not actually wait.
+ *
  * @param {string} token - GitHub PAT
  * @param {string} repoSlug - e.g. "mcp-tool-shop-org/shipcheck"
  * @param {string} commitSha - Commit to fetch scenarios from
- * @param {{ timeoutMs?: number, fetchImpl?: typeof fetch }} [opts]
+ * @param {{ timeoutMs?: number, fetchImpl?: typeof fetch, attempts?: number, sleepImpl?: (ms: number) => Promise<void> }} [opts]
  * @returns {{ fetch(scenarioId: string): Promise<object|null>, fetchWithReason(scenarioId: string): Promise<{ scenario: object|null, reason?: string }> }}
  */
 export function githubScenarioFetcher(token, repoSlug, commitSha, opts = {}) {
   const timeoutMs = opts.timeoutMs ?? GITHUB_SCENARIO_FETCH_TIMEOUT_MS;
   const fetchImpl = opts.fetchImpl ?? ((url, init) => globalThis.fetch(url, init));
+  const attempts = opts.attempts ?? GITHUB_SCENARIO_FETCH_ATTEMPTS;
+  const sleep = opts.sleepImpl ?? defaultSleep;
 
   const [org, repo] = repoSlug.split('/');
-  if (!org || !repo || isUnsafeSegment(org) || isUnsafeSegment(repo)) {
+  // commitSha is interpolated into the authenticated (Bearer-token) GitHub API
+  // URL's `?ref=` — a shape guard (lowercase-hex, 7–40 chars) refuses anything
+  // that could re-target the ref or inject query params, matching how org/repo
+  // and scenarioId are guarded below. encodeURIComponent alone would NOT reject
+  // a re-targeted ref (e.g. a branch name), so the shape guard is the floor.
+  if (
+    !org || !repo || isUnsafeSegment(org) || isUnsafeSegment(repo) ||
+    typeof commitSha !== 'string' || !/^[0-9a-f]{7,40}$/.test(commitSha)
+  ) {
     return {
       async fetch() { return null; },
       async fetchWithReason() { return { scenario: null, reason: 'invalid_id' }; }
     };
   }
 
-  async function fetchWithReason(scenarioId) {
-    if (!/^[\w-]+$/.test(scenarioId)) {
-      return { scenario: null, reason: 'invalid_id' };
-    }
+  // One bounded attempt. Returns `{ scenario, reason, retryable }`; the loop
+  // below decides whether to retry on `retryable`.
+  async function attemptOnce(scenarioId) {
     const path = `dogfood/scenarios/${scenarioId}.yaml`;
     const url = `https://api.github.com/repos/${repoSlug}/contents/${path}?ref=${commitSha}`;
 
@@ -262,16 +298,20 @@ export function githubScenarioFetcher(token, repoSlug, commitSha, opts = {}) {
         signal: controller.signal
       });
       if (!resp.ok) {
-        return { scenario: null, reason: 'not_found' };
+        // A 5xx server error or a 429 rate-limit is transient — retry. Any
+        // other non-ok (notably 404) is a definitive answer; do not retry.
+        const retryable = resp.status >= 500 || resp.status === 429;
+        return { scenario: null, reason: 'not_found', retryable };
       }
       text = await resp.text();
     } catch (err) {
       if (err && (err.name === 'AbortError' || err.code === 'ABORT_ERR')) {
-        return { scenario: null, reason: 'timeout' };
+        // A timed-out request may succeed on a retry.
+        return { scenario: null, reason: 'timeout', retryable: true };
       }
-      // Network reject, DNS failure, etc. — surface as not_found for
-      // back-compat with the legacy null contract.
-      return { scenario: null, reason: 'not_found' };
+      // Network reject, DNS failure, etc. — transient; surface as not_found
+      // for back-compat with the legacy null contract, but allow a retry.
+      return { scenario: null, reason: 'not_found', retryable: true };
     } finally {
       clearTimeout(timer);
     }
@@ -279,12 +319,28 @@ export function githubScenarioFetcher(token, repoSlug, commitSha, opts = {}) {
     try {
       const scenario = yaml.load(text);
       if (!scenario || typeof scenario !== 'object') {
-        return { scenario: null, reason: 'parse_error' };
+        return { scenario: null, reason: 'parse_error', retryable: false };
       }
       return { scenario };
     } catch {
-      return { scenario: null, reason: 'parse_error' };
+      return { scenario: null, reason: 'parse_error', retryable: false };
+    }
+  }
+
+  async function fetchWithReason(scenarioId) {
+    if (!/^[\w-]+$/.test(scenarioId)) {
+      return { scenario: null, reason: 'invalid_id' };
+    }
+
+    let last;
+    for (let i = 0; i < attempts; i++) {
+      last = await attemptOnce(scenarioId);
+      if (last.scenario || !last.retryable || i === attempts - 1) break;
+      await sleep(Math.min(RETRY_BASE_MS * (1 << i), RETRY_MAX_MS));
     }
+    // Strip the internal `retryable` flag from the public contract.
+    const { retryable: _drop, ...result } = last;
+    return result;
   }
 
   return {

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@dogfood-lab/ingest",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "type": "module",
   "description": "Ingestion pipeline for testing-os. Thin glue: dispatch → verifier → persist → indexes.",
   "main": "run.js",
   "exports": {
     ".": "./run.js",
     "./lib/*": "./lib/*",
-    "./validate-record.js": "./validate-record.js"
+    "./anchor/*": "./anchor/*",
+    "./validate-record.js": "./validate-record.js",
+    "./verify-chain.js": "./verify-chain.js"
   },
   "scripts": {
     "test": "node --test",
@@ -18,8 +20,10 @@
     "persist.js",
     "rebuild-indexes.js",
     "validate-record.js",
+    "verify-chain.js",
     "load-context.js",
     "lib/",
+    "anchor/",
     "README.md",
     "LICENSE"
   ],

package/persist.js

@@ -7,11 +7,13 @@
  */
 
 import { existsSync, mkdirSync, writeFileSync, renameSync, openSync, closeSync, unlinkSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join, dirname, relative, sep } from 'node:path';
 import { randomBytes } from 'node:crypto';
 
 import { validateRecord } from './validate-record.js';
 import { isUnsafeSegment } from './lib/unsafe-segment.js';
+import { submissionDigest } from './lib/integrity.js';
+import { readChainHead, appendChainEntry } from './lib/chain-manifest.js';
 
 /**
  * Error thrown when writeRecord loses a TOCTOU race for the same canonical path.
@@ -125,6 +127,26 @@ export function writeRecord(record, repoRoot) {
     return { path, written: false };
   }
 
+  // Integrity chain v1 — stamp the tamper-evident integrity block BEFORE
+  // validating + writing, so the persisted record self-certifies.
+  //
+  // Serialized-ingest assumption (LOCKED CONTRACT step 4): ingest.yml is
+  // concurrency-serialized and writeRecord is synchronous, so reading the chain
+  // head and then appending after the write is race-free. A fork for
+  // truly-concurrent ingest (two writers assigning the same seq) is OUT OF SCOPE
+  // — see lib/chain-manifest.js. The order is: read head → compute digest over
+  // the record WITHOUT integrity (stable regardless of the block) → stamp
+  // integrity → write the record → append the manifest line. The append happens
+  // ONLY after the record write succeeds, and only on this real-write path
+  // (never on the duplicate short-circuit above).
+  const head = readChainHead(repoRoot);
+  const digest = submissionDigest(record);
+  record.integrity = {
+    submission_digest: digest,
+    prev_digest: head.submission_digest,
+    seq: head.seq + 1,
+  };
+
   // Enforce dogfood-record.schema.json BEFORE touching the filesystem.
   // Better to throw loudly than silently persist a malformed record — the
   // schema is the contract every downstream consumer relies on.
@@ -168,5 +190,23 @@ export function writeRecord(record, repoRoot) {
     throw err;
   }
 
+  // Append the chain ledger line AFTER the record write succeeds. The manifest
+  // append is atomic (temp+rename rewrite — see lib/chain-manifest.js); a torn
+  // append cannot leave a half-line. `path` field is the record path RELATIVE to
+  // repoRoot, forward-slashed, so the ledger is portable across OSes and a line
+  // copy-pasted into a raw.githubusercontent URL is not a broken link (mirrors
+  // the posixify-at-the-boundary doctrine in run.js / rebuild-indexes.js).
+  const relPath = relative(repoRoot, path).split(sep).join('/');
+  appendChainEntry(repoRoot, {
+    seq: record.integrity.seq,
+    run_id: record.run_id,
+    repo: record.repo,
+    status: record.verification?.status ?? 'accepted',
+    path: relPath,
+    submission_digest: record.integrity.submission_digest,
+    prev_digest: record.integrity.prev_digest,
+    persisted_at: new Date().toISOString(),
+  });
+
   return { path, written: true };
 }

package/rebuild-indexes.js

@@ -8,7 +8,8 @@
  *
  * Regenerated on every accepted/rejected write in Phase 1.
  *
- * Multi-file commit-group atomicity (W3-PIPE-002):
+ * Multi-file commit-group: crash/IO-failure RECOVERY-atomic, NOT reader-atomic
+ * (W3-PIPE-002):
  * The 3 indexes are written together via a two-phase commit pattern. Phase 1
  * stages all 3 files to temp paths AND records them in a journal file. Phase 2
  * renames each temp into its final location, then deletes the journal. If the
@@ -17,10 +18,27 @@
  * is idempotent (it scans records/ end-to-end), so re-running is the correct
  * recovery action.
  *
- * Pattern reference: choke-point fix (Pattern #4) for multi-file atomicity.
+ * IMPORTANT — what "atomicity" means here. The guarantee is RECOVERY-atomic,
+ * not READER-atomic. Phase 2 promotes the temps with a per-leg `renameSync`
+ * (each rename is individually atomic), but the GROUP is not promoted under a
+ * single atomic operation. During the promote window — and during the heal
+ * window after a mid-promote IO failure (ENOSPC/EACCES after the first
+ * final is renamed but a later one is not) — a concurrent reader CAN observe
+ * the index group in a mutually-inconsistent intermediate state (e.g. an
+ * already-promoted latest-by-repo.json against a not-yet-promoted failing.json).
+ * The catch on a promote failure does NOT roll back already-promoted finals;
+ * it preserves the journal and emits a structured error event so an operator
+ * can force an immediate rebuild before the next scheduled run heals it. The
+ * design is sound because the only writer (the ingest pipeline) serializes
+ * rebuilds and `rebuildIndexes` is synchronous — there is no in-flight reader
+ * that races a writer mid-promote within a single process. If you ever need
+ * true reader-atomicity (a reader that NEVER sees a torn group), this design
+ * must change (e.g. swap a single directory symlink, or version the index dir).
+ *
+ * Pattern reference: choke-point fix (Pattern #4) for multi-file recovery.
  * Single-file `atomicWriteFileSync` (lib/atomic-write.js) handles each leg;
- * the journal handles the cross-file boundary. The single-file helper is
- * the same one Class #6 helper-adoption-sweep enforces as canonical for
+ * the journal handles the cross-file recovery boundary. The single-file helper
+ * is the same one Class #6 helper-adoption-sweep enforces as canonical for
  * temp+rename writes under `packages/ingest/`.
  */
 
@@ -98,6 +116,72 @@ export function findJsonFiles(dir) {
   return results;
 }
 
+/**
+ * Probe whether `dir` exists but is unreadable at its OWN level (EACCES /
+ * Windows lock / ENOTDIR) — as distinct from a deep leaf failing mid-walk.
+ *
+ * ingest-B-002: `findJsonFiles` deliberately degrades an unreadable subtree to
+ * "those records are missing" and returns `[]`. That is correct for a single
+ * locked LEAF, but catastrophic for the records/ ROOT: a transiently-locked
+ * root makes the WHOLE corpus invisible, and an unguarded rebuild would then
+ * overwrite every index with empty content. This probe lets `rebuildIndexes`
+ * tell the two apart so it can REFUSE to clobber good indexes when the root
+ * itself is the thing that failed. A non-existent dir is NOT unreadable — that
+ * is the legitimate empty-corpus case, which must still rebuild empty indexes.
+ *
+ * @param {string} dir
+ * @returns {{ unreadable: boolean, code: string|null, error: string|null }}
+ */
+function probeDirReadable(dir) {
+  if (!existsSync(dir)) return { unreadable: false, code: null, error: null };
+  try {
+    readdirSync(dir);
+    return { unreadable: false, code: null, error: null };
+  } catch (err) {
+    return {
+      unreadable: true,
+      code: err && err.code ? err.code : 'readdir_failed',
+      error: err && err.message ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * Read the prior committed latest-by-repo.json so a rebuild can tell whether
+ * the index it is about to overwrite currently has content. Used by the
+ * ingest-B-002 refuse-to-overwrite guard: an empty scan is only suspicious if
+ * the prior index was non-empty. A missing or unparseable prior index counts
+ * as "no prior content" (the legitimate first-run / empty-corpus case).
+ *
+ * @param {string} latestPath
+ * @returns {boolean} true if the prior index existed and held at least one repo
+ */
+function priorIndexHasContent(latestPath) {
+  if (!existsSync(latestPath)) return false;
+  try {
+    const prior = JSON.parse(readFileSync(latestPath, 'utf-8'));
+    return prior && typeof prior === 'object' && Object.keys(prior).length > 0;
+  } catch {
+    // Unparseable prior index — treat as no usable content so a corrupt index
+    // never wedges the rebuild into a permanent refuse state.
+    return false;
+  }
+}
+
+/**
+ * Whether the freshly-built latest-by-repo map has no repos. Used by the
+ * ingest-B-002 refuse-to-overwrite guard to recognise an empty scan. A scan
+ * can be empty because there are genuinely no accepted records (legitimate)
+ * or because the corpus was invisible (a transiently-locked records tree) —
+ * the guard combines this with `priorIndexHasContent` to tell them apart.
+ *
+ * @param {object} latestByRepo
+ * @returns {boolean}
+ */
+function latestByRepoIsEmpty(latestByRepo) {
+  return !latestByRepo || Object.keys(latestByRepo).length === 0;
+}
+
 /**
  * Load and parse a record file.
  *
@@ -131,8 +215,20 @@ export function rebuildIndexes(repoRoot, options = {}) {
   const indexDir = join(repoRoot, 'indexes');
   mkdirSync(indexDir, { recursive: true });
 
-  // Collect all records (accepted + rejected)
+  // ingest-B-002: capture two facts BEFORE the scan so we can refuse to clobber
+  // good indexes with empty ones when the corpus is invisible rather than empty.
+  //   1. Is the records/ ROOT itself unreadable (vs a deep leaf, vs absent)?
+  //      A locked root makes the WHOLE corpus invisible — findJsonFiles would
+  //      return [] after one low `dir_unreadable` warn, and an unguarded
+  //      commit-group would then overwrite every index with {}.
+  //   2. Did the PRIOR latest-by-repo.json have content? An empty scan is only
+  //      suspicious if there was something to lose; a legitimately empty
+  //      first-run corpus must still write empty indexes.
   const recordsDir = join(repoRoot, 'records');
+  const latestPath = join(indexDir, 'latest-by-repo.json');
+  const rootProbe = probeDirReadable(recordsDir);
+  const hadPriorIndex = priorIndexHasContent(latestPath);
+
   const acceptedFiles = findJsonFiles(recordsDir)
     .filter(f => {
       const rel = relative(recordsDir, f);
@@ -268,9 +364,49 @@ export function rebuildIndexes(repoRoot, options = {}) {
     }
   }
 
+  // ingest-B-002: REFUSE to overwrite good indexes with empty ones when the
+  // corpus was invisible rather than genuinely empty. Two refuse conditions:
+  //   - records_root_unreadable: the records/ ROOT itself failed to read
+  //     (EACCES / Windows lock / ENOTDIR). The entire corpus is invisible —
+  //     committing now would wipe every index. This is distinct from a single
+  //     locked leaf, which findJsonFiles already degrades to a partial scan.
+  //   - empty_scan_with_prior_index: the root read fine but the scan found
+  //     zero accepted records while the prior latest-by-repo had content. The
+  //     records likely vanished transiently; clobbering loses the portfolio.
+  // A legitimately empty corpus (no accepted records AND no prior content) is
+  // NOT refused — it must still write empty indexes (first-run case). We skip
+  // the commit-group and emit a structured, greppable event so the operator
+  // sees the refusal loudly instead of a silently-emptied portfolio.
+  const noAcceptedScanned = latestByRepoIsEmpty(latestByRepo);
+  if (rootProbe.unreadable || (noAcceptedScanned && hadPriorIndex)) {
+    const reason = rootProbe.unreadable
+      ? 'records_root_unreadable'
+      : 'empty_scan_with_prior_index';
+    // A root IO failure is an operator-actionable error (the corpus is gone);
+    // an empty scan over a readable root is a warn (recoverable next run).
+    logStage(rootProbe.unreadable ? 'error' : 'warn', {
+      kind: 'index_rebuild_skipped',
+      reason,
+      records_dir: recordsDir,
+      accepted_scanned: acceptedFiles.length,
+      prior_index_non_empty: hadPriorIndex,
+      root_error_code: rootProbe.code,
+      error: rootProbe.error,
+    });
+    return {
+      latestByRepo,
+      failing,
+      stale,
+      accepted: acceptedFiles.length,
+      rejected: rejectedFiles.length,
+      corrupted,
+      skipped,
+      skippedCommit: reason,
+    };
+  }
+
   // Write indexes via commit-group two-phase commit. See module header
   // for the full design rationale.
-  const latestPath = join(indexDir, 'latest-by-repo.json');
   const failingPath = join(indexDir, 'failing.json');
   const stalePath = join(indexDir, 'stale.json');
 
@@ -307,15 +443,23 @@ export function rebuildIndexes(repoRoot, options = {}) {
  * AND records them in a journal first; then renames them in caller-given
  * order. The journal is deleted only after every rename succeeds.
  *
- * Crash semantics:
- *   - Crash during STAGE phase: every staged temp is unlinked in the catch
+ * Crash / IO-failure semantics (RECOVERY-atomic, not reader-atomic):
+ *   - Failure during STAGE phase: every staged temp is unlinked in the catch
  *     block; the journal (if written) is unlinked too. No partial visible
- *     state.
- *   - Crash during PROMOTE phase: any successfully-renamed file is at its
- *     final path; remaining temps are still next to their finals. The
- *     journal still exists. Next run's `cleanupCrashedJournals` deletes
- *     residual temps and the journal; the next normal `rebuildIndexes`
- *     call rewrites all 3 indexes from scratch (idempotent).
+ *     state — no final was touched.
+ *   - Failure during PROMOTE phase: any successfully-renamed file is at its
+ *     final path with its NEW content; remaining temps are still next to
+ *     their (still-OLD) finals. The group is therefore mutually inconsistent
+ *     until healed — a reader in this window sees a torn group. We do NOT
+ *     roll back the already-promoted finals (their prior content was already
+ *     overwritten by the atomic rename — there is nothing to roll back to
+ *     without re-reading the journal). Instead we emit a structured
+ *     `logStage('error', { kind: 'commit_group_partial_promote', ... })`
+ *     naming which finals were promoted vs left stale so an operator can
+ *     force an immediate rebuild, and we preserve the journal. Next run's
+ *     `cleanupCrashedJournals` deletes residual temps and the journal; the
+ *     next normal `rebuildIndexes` call rewrites all 3 indexes from scratch
+ *     (idempotent), which is what heals the torn group.
  *
  * Why journal-then-rename rather than journal-only: the rename phase needs
  * to be the visible commit point. A journal-only design would require
@@ -339,8 +483,12 @@ function commitGroupRename(indexDir, entries) {
 
     // Write journal AFTER staging so it never points at a non-existent temp.
     // Atomic write of the journal itself: writeFileSync directly is fine here
-    // because the journal is process-private (the pid suffix guarantees no
-    // collision with concurrent rebuilds).
+    // because the journal is process-private — the pid + random suffix make
+    // the filename collision-free, and `cleanupCrashedJournals` is pid-aware
+    // (it skips journals whose pid is a still-live process), so a future
+    // concurrent rebuild's in-flight journal is never reaped out from under
+    // it. The temp `entries` it lists are equally collision-free (each carries
+    // its own random suffix from `stageWriteFileSync`).
     writeFileSync(
       journalPath,
       JSON.stringify({
@@ -374,6 +522,24 @@ function commitGroupRename(indexDir, entries) {
     // (their previous content is already overwritten — the rename was
     // atomic at each individual leg, just not as a group). The next run
     // is idempotent and will rewrite all three from scratch.
+    //
+    // ingest-A-001: the group is now reader-inconsistent (promoted finals
+    // carry new content; stale finals carry old content). Name which finals
+    // are which in a structured error event so an operator can force an
+    // immediate rebuild rather than wait for the next scheduled run to heal
+    // the torn group.
+    const promoted = stagedTmps.slice(0, promotedCount).map((e) => e.finalPath);
+    const stale = stagedTmps.slice(promotedCount).map((e) => e.finalPath);
+    logStage('error', {
+      kind: 'commit_group_partial_promote',
+      reason: err && err.code ? err.code : 'promote_failed',
+      promoted_count: promotedCount,
+      total: stagedTmps.length,
+      promoted_finals: promoted,
+      stale_finals: stale,
+      journal: journalPath,
+      error: err && err.message ? err.message : String(err),
+    });
     throw new Error(
       `commitGroupRename: promote failed after ${promotedCount}/${stagedTmps.length} files; ` +
       `journal preserved at ${journalPath} for next-run cleanup. Original error: ${err.message}`
@@ -387,11 +553,42 @@ function commitGroupRename(indexDir, entries) {
   try { unlinkSync(journalPath); } catch { /* will be cleaned next run */ }
 }
 
+/**
+ * Probe whether a pid is still a live process. `process.kill(pid, 0)` sends
+ * no signal — it only performs the permission/existence check, throwing
+ * ESRCH when the pid is dead. An EPERM means the process exists but is owned
+ * by another user; that still counts as "live" for our purpose (do not reap
+ * its journal). Any other error (or a non-integer pid) is treated as "not
+ * provably live" so a malformed journal never blocks its own cleanup.
+ *
+ * @param {unknown} pid
+ * @returns {boolean}
+ */
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err && err.code === 'EPERM';
+  }
+}
+
 /**
  * Find and clean up any in-progress journals from previous runs. Each journal
  * lists the temp paths that were staged; we unlink any that still exist
  * (they are residue from a crashed run) and delete the journal.
  *
+ * ingest-A-002: cleanup is PID-AWARE. A journal whose `pid` is a still-live
+ * process is the in-flight recovery state of a concurrent rebuild — reaping
+ * it would delete that run's temps and journal mid-flight. Today the only
+ * writer serializes rebuilds and `rebuildIndexes` is synchronous, so no live
+ * sibling journal exists at Phase-0 cleanup time; this guard makes the design
+ * correct (not merely safe-by-serialization) so a future maintainer who adds
+ * concurrency does not silently corrupt a peer. A dead pid, a missing/
+ * malformed pid, or an unreadable journal is still reaped — that is the
+ * crashed-run residue this function exists to clear.
+ *
  * Idempotent: on a clean filesystem it's a no-op; on a crashed-mid-promote
  * filesystem it cleans the slate so the upcoming `commitGroupRename` can
  * stage fresh temps without colliding.
@@ -412,6 +609,11 @@ function cleanupCrashedJournals(indexDir) {
       // referenced will linger but they're harmless (they have a unique
       // suffix that won't be re-used).
     }
+    // Skip a journal owned by a still-live process — it belongs to a
+    // concurrent rebuild's in-flight recovery state, not crashed residue.
+    if (parsed && isProcessAlive(parsed.pid) && parsed.pid !== process.pid) {
+      continue;
+    }
     if (parsed && Array.isArray(parsed.entries)) {
       for (const e of parsed.entries) {
         if (e && typeof e.tmpPath === 'string') {