@stravica-ai/digital-operator-pa 0.1.21 → 0.1.23

package/dist/engineering-pa-cli/src/sync/self-heal.mjs

@@ -0,0 +1,577 @@
+// estate-sync — self-heal on rebase-abort (R2, w-2026-08-12-004).
+//
+// Purpose. Kill the failure mode observed on ops-01 2026-08-11: estate-sync
+// committed locally, `git pull --rebase` conflicted on one path outside the
+// regenerated-artifacts allowlist, estate-sync aborted the rebase, and the
+// workspace stayed parked at ahead=1/behind=N with no self-heal. Every
+// downstream consumer (librarian sweep shares .git via symlink) inherited
+// the wedge until a human intervened. R1 (writer-scoped work-item IDs,
+// shipped 0.1.21) removed the dual-mint cause of THAT specific conflict;
+// R2 is the belt-and-braces for every other conflicting path.
+//
+// Shape (ratified 2026-08-12 via the library architecture review §7 R2 +
+// amendment from the coordinator on the drain design; corrected 2026-08-
+// 12 per the fresh-context reviewer's blocker on PR #120 — the original
+// implementation used `git reset --keep HEAD^` which destroys the non-
+// conflicting portion of the dropped commit; see the DROP note below).
+// On a non-allowlist conflict:
+//   (a) QUEUE   — write estate-sync's version of every conflicting path
+//                 to `<repoRoot>/.cache/estate-sync/pending/<id>` with a
+//                 JSON sidecar (originalPath, upstream commit sha, upstream
+//                 blob sha AT QUEUE TIME, attempt count, first-seen).
+//                 Content is fsynced BEFORE any git mutation runs — if
+//                 queueing fails, we do NOT reset; sync falls back to the
+//                 existing fail-rebase behaviour and stays loud rather
+//                 than lose bytes.
+//   (b) DROP    — abort the rebase, then GUARDED-drop only the local
+//                 commit estate-sync itself just created: HEAD must equal
+//                 the sha recorded at commit time; HEAD^..HEAD must
+//                 contain exactly one commit; HEAD^ must exist; the
+//                 workspace must be exactly one commit ahead of upstream.
+//                 Guard failure means the workspace has moved under us
+//                 (human commit landed, hook injected a merge, etc.) —
+//                 do NOT reset; alert loudly and fall back to fail-rebase.
+//                 The drop is `git reset --soft HEAD^` (NOT --keep):
+//                 --soft leaves the index and working tree entirely
+//                 untouched, so every non-conflicting path in the
+//                 dropped commit remains STAGED and its bytes remain
+//                 on disk. Then surgically for each conflicting path P:
+//                 if P was newly-added by our commit (existedInParent=
+//                 false) → `git rm --cached -- P` then `fs.unlink(P)`
+//                 (P is now un-staged and off disk; its bytes live in
+//                 pending); if P was modified (existedInParent=true) →
+//                 `git checkout HEAD -- P` (HEAD is now the parent;
+//                 restores parent's version in both index and working
+//                 tree). Result: HEAD=parent, index+working tree hold
+//                 exactly our commit's content MINUS the conflicting
+//                 paths; the next tick's step 6 re-stages via idempotent
+//                 `git add -A` / `git add -- <paths>` and recommits.
+//                 The reviewer's attack1 (multi-file commit, one
+//                 conflicting path) and attack2 (modified README
+//                 alongside a conflict) are pinned as regression tests.
+//   (c) ALERT   — audit-record for the tick uses a `fail-*` status so
+//                 librarian-alerts picks it up when wired against
+//                 estate-sync's runs.jsonl (see librarian-alerts config
+//                 field companionCadenceMinutes / executorRunsPath — the
+//                 shape is compatible without config changes here). Exit
+//                 code stays 0 because the workspace ITSELF is healthy
+//                 (fast-forwardable again) — the process is not the wedge.
+//   (d) DRAIN   — at the START of every subsequent tick, retry pending
+//                 files oldest-first. Placement: AFTER fetch, so
+//                 origin/<branch> reflects reality. For each pending file:
+//                 compare the upstream blob NOW against the sidecar's
+//                 recorded upstream blob at queue time. Three cases:
+//                   - Upstream unchanged → safe to re-apply: copy content
+//                     back into the workspace at originalPath; step 6
+//                     stages it normally; if the tick commits + pushes
+//                     successfully, remove the pending file.
+//                   - Upstream now MATCHES our content → already delivered
+//                     (another writer pushed it for us); remove the
+//                     pending file, no re-apply needed.
+//                   - Upstream DIVERGED (different blob than at queue) →
+//                     stamp the sidecar alertLevel='needs-human' (sticky —
+//                     never de-escalates), do NOT overwrite the workspace,
+//                     leave the pending file for a human. Skips the
+//                     5-attempt ladder entirely — attempts can't fix
+//                     divergence. Names both blob shas in the alert.
+//                 A crash mid-drain (after workspace copy, before commit)
+//                 leaves the pending file intact — next tick re-evaluates.
+//                 Removal happens ONLY after commit AND push are on HEAD.
+//
+// Content-safety invariant. Every path in the dropped commit ends up in
+// one of three places after self-heal completes:
+//   1. Still staged in the index (non-conflicting paths — --soft leaves
+//      them alone; next tick re-commits them naturally).
+//   2. On disk in `<pendingDir>/<id>` with a sidecar (conflicting paths,
+//      queued BEFORE any git mutation runs).
+//   3. Reverted to their parent-commit form (conflicting paths that
+//      existed in HEAD^ — we surgically `git checkout HEAD -- <path>` to
+//      restore the parent's version).
+// A conflicting path newly-added by our commit takes option 2 only
+// (queue then delete from working tree). If any queue write throws OR
+// any guard fires, `run.mjs` sees `{ ok: false }` and takes the classic
+// fail-rebase path (rebaseAbort only, no reset) — workspace stays
+// committed, staying wedged loudly. If the reset itself fails (extremely
+// unlikely; --soft has no working-tree dependency), the pending files
+// still hold the queued bytes and the audit surfaces the failure.
+//
+// Concurrency (audited in the safety argument section of the PR): the
+// existing PID lock (10-minute stale window; see lock.mjs) protects the
+// whole tick, so drain-at-tick-start and self-heal-at-conflict never race
+// with another sync tick on the same host. Cross-host is the git-level
+// contract — each host's pending queue is under its own gitignored
+// `.cache/estate-sync/pending/` and never leaves the host.
+
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import {
+  checkoutFromRef,
+  hashObject,
+  rebaseAbort,
+  refPathExists,
+  resetSoft,
+  revListCount,
+  revParseSha,
+  rmCached,
+} from './git.mjs';
+import {
+  ensurePendingDir,
+  loadAll,
+  queueConflict,
+  readContent,
+  removePending,
+  writeSidecar,
+} from './pending-store.mjs';
+
+const ESCALATE_AT = 5;
+
+function log(line, stderr) {
+  stderr.write(`[estate-sync] ${line}\n`);
+}
+
+// Resolve `origin/<branch>` to its blob sha for `path`, or null if the
+// blob doesn't exist there. Non-fatal: any git failure returns null so
+// the caller falls through to a defensive "unknown upstream state" branch.
+async function upstreamBlobSha(runner, { cwd, branch, path }) {
+  const ref = `origin/${branch}:${path}`;
+  const r = await runner.spawn('git', ['rev-parse', '--verify', `${ref}`], { cwd });
+  if (r.code !== 0) return null;
+  return r.stdout.trim();
+}
+
+// Resolve `origin/<branch>` to its commit sha, or null.
+async function upstreamCommitSha(runner, { cwd, branch }) {
+  const r = await runner.spawn('git', ['rev-parse', '--verify', `origin/${branch}^{commit}`], { cwd });
+  if (r.code !== 0) return null;
+  return r.stdout.trim();
+}
+
+/**
+ * Attempt the self-heal path in response to a non-allowlist rebase
+ * conflict. Contract:
+ *   - Runs AFTER classifyConflicts has already surfaced `disallowed`
+ *     paths (the caller is `tryAutoResolveRebase` in run.mjs, unchanged
+ *     for the allowlist branch).
+ *   - Returns { ok: true, queued: [{ id, originalPath, attemptCount,
+ *     alertLevel, upstreamBlobShaAtQueue, conflictingUpstreamCommitSha }]
+ *     } on success, with the workspace at HEAD = <our commit's parent>,
+ *     working tree carrying only the non-conflicting portion of the
+ *     dropped commit's diff (conflicting paths restored to their
+ *     pre-commit state — either HEAD^ version, or removed if newly added
+ *     by our commit).
+ *   - Returns { ok: false, reason: '<short>', stage: '<stage>' } on any
+ *     failure. Caller must fall back to the existing fail-rebase behaviour
+ *     (rebaseAbort has been called, but reset was NOT).
+ */
+export async function attemptSelfHeal({
+  runner,
+  repoRoot,
+  pendingDir,
+  branch,
+  disallowedPaths,
+  ourCommitSha,
+  firstSeenTs,
+  stderr,
+}) {
+  if (!ourCommitSha) {
+    return { ok: false, reason: 'self-heal called without ourCommitSha; refusing to reset', stage: 'precondition' };
+  }
+  if (!Array.isArray(disallowedPaths) || disallowedPaths.length === 0) {
+    return { ok: false, reason: 'self-heal called without conflicting paths', stage: 'precondition' };
+  }
+
+  // 1. Abort the rebase first. This is safe/reversible: it restores the
+  //    tree to HEAD = ourCommitSha, working tree matches our commit
+  //    (git reflog carries the aborted rebase). Doing this before content
+  //    capture means the file bytes we read from disk in step 2 are OUR
+  //    committed version, not conflict markers.
+  const abort = await rebaseAbort(runner, { cwd: repoRoot });
+  if (abort.code !== 0) {
+    return {
+      ok: false,
+      reason: `git rebase --abort failed: ${abort.stderr.trim()}`,
+      stage: 'rebase-abort',
+    };
+  }
+
+  // 2. GUARDS — before we touch anything else, prove HEAD is still our
+  //    commit and there's exactly one commit to drop.
+  const head = await revParseSha(runner, { cwd: repoRoot, ref: 'HEAD' });
+  if (head.code !== 0) {
+    return { ok: false, reason: `git rev-parse HEAD failed: ${head.stderr.trim()}`, stage: 'guard-head' };
+  }
+  if (head.sha !== ourCommitSha) {
+    return {
+      ok: false,
+      reason: `guard failed: HEAD=${head.sha.slice(0, 8)} but expected ourCommitSha=${ourCommitSha.slice(0, 8)} — refusing to reset a commit we did not just make`,
+      stage: 'guard-head-sha',
+    };
+  }
+  const parent = await revParseSha(runner, { cwd: repoRoot, ref: 'HEAD^' });
+  if (parent.code !== 0) {
+    return {
+      ok: false,
+      reason: `guard failed: HEAD^ does not exist (root commit?) — refusing to reset: ${parent.stderr.trim()}`,
+      stage: 'guard-parent-exists',
+    };
+  }
+  const count = await revListCount(runner, { cwd: repoRoot, range: 'HEAD^..HEAD' });
+  if (count.code !== 0 || count.count !== 1) {
+    return {
+      ok: false,
+      reason: `guard failed: expected exactly one commit in HEAD^..HEAD, got ${count.count} — refusing to reset a stack`,
+      stage: 'guard-single-commit',
+    };
+  }
+  // Belt-and-braces: also verify the workspace is exactly one commit
+  // ahead of origin/<branch>. If it's more (a human commit landed
+  // before this tick started, or a hook interposed one), --keep HEAD^
+  // would drop OUR commit but leave the other unresolved, so we'd
+  // still be ahead=1/behind=N — wedged. Refuse the reset instead; the
+  // classic fail-rebase behaviour surfaces the situation for a human.
+  const aheadOfUpstream = await revListCount(runner, {
+    cwd: repoRoot, range: `origin/${branch}..HEAD`,
+  });
+  if (aheadOfUpstream.code !== 0 || aheadOfUpstream.count !== 1) {
+    return {
+      ok: false,
+      reason: `guard failed: expected exactly one commit ahead of origin/${branch}, got ${aheadOfUpstream.count} — refusing to reset while other local commits exist`,
+      stage: 'guard-ahead-of-upstream',
+    };
+  }
+
+  // 3. Capture each conflicting path's content from the working tree
+  //    (matches our commit after rebase --abort). Also capture whether
+  //    the path existed at HEAD^ (drives the tree-cleanup shape after
+  //    reset), and origin's current blob sha for the path (upstream
+  //    state at queue time, drives the drain's divergence check).
+  const upstreamCommit = await upstreamCommitSha(runner, { cwd: repoRoot, branch });
+  const captures = [];
+  for (const p of disallowedPaths) {
+    let content;
+    try {
+      content = await readFile(join(repoRoot, p));
+    } catch (err) {
+      return {
+        ok: false,
+        reason: `capture failed: reading ${p} from working tree: ${err.message}`,
+        stage: 'capture-read',
+      };
+    }
+    const existedInParent = await refPathExists(runner, { cwd: repoRoot, ref: 'HEAD^', path: p });
+    const upstreamBlob = await upstreamBlobSha(runner, { cwd: repoRoot, branch, path: p });
+    captures.push({
+      path: p,
+      content,
+      existedInParent,
+      upstreamBlobShaAtQueue: upstreamBlob,
+    });
+  }
+
+  // 4. QUEUE — write pending files (raw + sidecar). Fsync-then-rename
+  //    inside pending-store gives us the durability guarantee. If any
+  //    queue write throws, we bail BEFORE the reset — data preserved
+  //    only in the working tree at that point, but the tree still
+  //    matches our commit and the caller's fail-rebase audit will be
+  //    accurate.
+  await ensurePendingDir(pendingDir);
+  const queued = [];
+  for (const c of captures) {
+    let result;
+    try {
+      result = await queueConflict(pendingDir, {
+        originalPath: c.path,
+        content: c.content,
+        firstSeen: firstSeenTs,
+        conflictingUpstreamCommitSha: upstreamCommit,
+        upstreamBlobShaAtQueue: c.upstreamBlobShaAtQueue,
+        existedInParent: c.existedInParent,
+        escalateAt: ESCALATE_AT,
+      });
+    } catch (err) {
+      return {
+        ok: false,
+        reason: `queue write failed for ${c.path}: ${err.message}`,
+        stage: 'queue-write',
+      };
+    }
+    queued.push({
+      id: result.sidecar.id,
+      originalPath: result.sidecar.originalPath,
+      attemptCount: result.sidecar.attemptCount,
+      alertLevel: result.sidecar.alertLevel,
+      upstreamBlobShaAtQueue: result.sidecar.upstreamBlobShaAtQueue,
+      conflictingUpstreamCommitSha: result.sidecar.conflictingUpstreamCommitSha,
+      pendingPath: result.contentPath,
+      existedInParent: result.sidecar.existedInParent,
+    });
+  }
+
+  // 5. DROP — reset --soft HEAD^. This is the corrected primitive
+  //    (2026-08-12, per the fresh-context reviewer's blocker on PR
+  //    #120). --soft moves HEAD to the parent while leaving BOTH the
+  //    index and the working tree entirely untouched, so every
+  //    non-conflicting path in the dropped commit remains staged and
+  //    on disk. The earlier `--keep HEAD^` implementation was wrong:
+  //    --keep updates working-tree files that differ between HEAD^
+  //    and HEAD, which silently destroys every non-conflicting path
+  //    we committed alongside the conflicting one. Attacks 1 and 2
+  //    from the reviewer's POC pin this correction as regressions.
+  const reset = await resetSoft(runner, { cwd: repoRoot, ref: 'HEAD^' });
+  if (reset.code !== 0) {
+    // Extremely unlikely path — --soft has no working-tree or index
+    // dependency. If it did fail, workspace is still at ourCommitSha
+    // (reset is atomic; failure means HEAD did not move), so pending
+    // files are still-honest bytes we can retry from later.
+    return {
+      ok: false,
+      reason: `guarded reset --soft HEAD^ failed: ${reset.stderr.trim()}`,
+      stage: 'reset',
+      queuedButNotDropped: queued,
+    };
+  }
+
+  // 6. Surgically clean up ONLY the conflicting paths. The index and
+  //    working tree are still at our dropped-commit's state; we need
+  //    the conflicting paths gone (their bytes are safe in pending)
+  //    while every other path stays exactly as we staged it. Two
+  //    branches per path:
+  //      - existedInParent === true → `git checkout HEAD -- <path>`.
+  //        HEAD is now the parent, so this restores the parent's
+  //        version in both index and working tree, cleanly reverting
+  //        just our modification.
+  //      - existedInParent === false → the file was newly added by
+  //        our commit. `git rm --cached -- <path>` unstages it (index
+  //        no longer tracks it), then `fs.unlink` removes the byte
+  //        content from the working tree. Neither op touches other
+  //        paths, so non-conflicting content is preserved.
+  const restorePaths = queued.filter((q) => q.existedInParent).map((q) => q.originalPath);
+  if (restorePaths.length > 0) {
+    const co = await checkoutFromRef(runner, { cwd: repoRoot, ref: 'HEAD', paths: restorePaths });
+    if (co.code !== 0) {
+      log(
+        `warning: post-reset checkout HEAD -- for restore failed: ${co.stderr.trim()} — pending queue holds content`,
+        stderr,
+      );
+    }
+  }
+  const newlyAddedPaths = queued.filter((q) => !q.existedInParent).map((q) => q.originalPath);
+  if (newlyAddedPaths.length > 0) {
+    const rmc = await rmCached(runner, { cwd: repoRoot, paths: newlyAddedPaths });
+    if (rmc.code !== 0) {
+      log(
+        `warning: post-reset git rm --cached for newly-added paths failed: ${rmc.stderr.trim()} — pending queue holds content`,
+        stderr,
+      );
+    }
+    for (const p of newlyAddedPaths) {
+      try {
+        await unlink(join(repoRoot, p));
+      } catch (err) {
+        if (err.code !== 'ENOENT') {
+          log(
+            `warning: post-reset unlink ${p} failed: ${err.message} — pending queue holds content`,
+            stderr,
+          );
+        }
+      }
+    }
+  }
+
+  return { ok: true, queued };
+}
+
+/**
+ * Drain the pending queue at the top of a tick (AFTER fetch, BEFORE
+ * commit-scope computation). Contract:
+ *   - Skipped entirely if the pending dir is empty.
+ *   - Runs in oldest-firstSeen order so the earliest conflict retries
+ *     first (deterministic ordering, easier operator debugging).
+ *   - Per pending entry:
+ *       a. If upstream blob for originalPath NOW matches our queued
+ *          content (someone else pushed it for us) → remove the pending
+ *          file, no workspace write. Return action: 'already-delivered'.
+ *       b. If upstream blob is UNCHANGED since queue time (or still
+ *          absent when it was absent at queue) → copy content into the
+ *          workspace at originalPath. Return action: 'staged-for-retry'.
+ *          Step 6 will stage it; the pending file is NOT removed here —
+ *          removal happens only after commit + push are confirmed on
+ *          HEAD (see finaliseDrainOnPushSuccess in run.mjs).
+ *       c. If upstream blob has diverged → stamp sidecar
+ *          alertLevel='needs-human' (sticky), name both blob shas in the
+ *          reason, do NOT overwrite the workspace. Return action:
+ *          'divergence-held'.
+ *   - Returns { drained: [{ id, originalPath, action, ... }], warnings }
+ *     — warnings surface corrupt sidecars from loadAll.
+ *
+ * Crash-safety: if the process is killed after step (b) writes the
+ * workspace but before step 6 commits, the pending file is still on
+ * disk — the next tick sees the same conflict blob-sha comparison and
+ * re-runs the drain step for this entry (idempotent).
+ */
+export async function drainPending({
+  runner,
+  repoRoot,
+  pendingDir,
+  branch,
+  stderr,
+}) {
+  const { entries, warnings } = await loadAll(pendingDir);
+  const drained = [];
+  if (entries.length === 0) return { drained, warnings };
+
+  for (const entry of entries) {
+    const { sidecar } = entry;
+    const originalPath = sidecar.originalPath;
+    const upstreamBlobNow = await upstreamBlobSha(runner, {
+      cwd: repoRoot, branch, path: originalPath,
+    });
+
+    // Case (a): upstream already carries our content. Compared via git
+    // blob shas both sides (binary-safe): upstream sha is what
+    // `origin/<branch>:<path>` resolves to; ours is what
+    // `git hash-object` produces from the pending file bytes. Equal
+    // shas === identical bytes, without any utf8 round-trip that would
+    // corrupt binary content.
+    if (upstreamBlobNow) {
+      const oursHash = await hashObject(runner, {
+        cwd: repoRoot,
+        path: join(pendingDir, sidecar.id),
+      });
+      if (oursHash.code === 0 && oursHash.sha === upstreamBlobNow) {
+        await removePending(pendingDir, sidecar.id);
+        drained.push({
+          id: sidecar.id,
+          originalPath,
+          action: 'already-delivered',
+          attemptCount: sidecar.attemptCount,
+        });
+        log(
+          `drain: ${originalPath} already delivered upstream (blob ${upstreamBlobNow.slice(0, 8)}) — pending removed`,
+          stderr,
+        );
+        continue;
+      }
+    }
+
+    // Case (c): upstream has DIFFERENT bytes than at queue time, AND
+    // those bytes are not ours (case a caught that). Divergence.
+    const upstreamMatchesQueue = (
+      (upstreamBlobNow == null && sidecar.upstreamBlobShaAtQueue == null)
+      || (upstreamBlobNow != null && upstreamBlobNow === sidecar.upstreamBlobShaAtQueue)
+    );
+    if (!upstreamMatchesQueue) {
+      // Stamp needs-human on the sidecar (sticky).
+      const next = {
+        ...sidecar,
+        alertLevel: 'needs-human',
+      };
+      await writeSidecar(pendingDir, next);
+      drained.push({
+        id: sidecar.id,
+        originalPath,
+        action: 'divergence-held',
+        attemptCount: sidecar.attemptCount,
+        alertLevel: 'needs-human',
+        upstreamBlobShaAtQueue: sidecar.upstreamBlobShaAtQueue,
+        upstreamBlobShaNow: upstreamBlobNow,
+      });
+      log(
+        `drain: ${originalPath} upstream DIVERGED (queue-time blob=${sidecar.upstreamBlobShaAtQueue?.slice(0, 8) || 'absent'}, now=${upstreamBlobNow?.slice(0, 8) || 'absent'}) — needs-human; pending held, workspace untouched`,
+        stderr,
+      );
+      continue;
+    }
+
+    // Case (b): safe to re-apply. Copy content into workspace so step 6
+    // stages it as part of the normal flow.
+    let content;
+    try { content = await readContent(pendingDir, sidecar.id); } catch (err) {
+      log(
+        `drain: WARNING reading pending content for ${originalPath} failed: ${err.message} — skipping`,
+        stderr,
+      );
+      continue;
+    }
+    try {
+      const targetPath = join(repoRoot, originalPath);
+      await mkdir(dirname(targetPath), { recursive: true });
+      await writeFile(targetPath, content);
+    } catch (err) {
+      log(
+        `drain: WARNING writing ${originalPath} back to workspace failed: ${err.message} — pending held, skipping`,
+        stderr,
+      );
+      continue;
+    }
+    drained.push({
+      id: sidecar.id,
+      originalPath,
+      action: 'staged-for-retry',
+      attemptCount: sidecar.attemptCount,
+    });
+    log(
+      `drain: ${originalPath} restored to workspace (attempt ${sidecar.attemptCount}) — step 6 will commit; pending held until push confirmed`,
+      stderr,
+    );
+  }
+  return { drained, warnings };
+}
+
+/**
+ * Called after the tick's push succeeded. Removes pending files whose
+ * originalPath is now delivered upstream (i.e. matches the pushed HEAD).
+ * Contract:
+ *   - Only touches entries with action='staged-for-retry' (divergence-
+ *     held ones stay for a human; already-delivered ones were removed
+ *     during drain).
+ *   - Verifies delivery by comparing the file at HEAD to the pending
+ *     content bytes. If HEAD's bytes don't match ours, keep the pending
+ *     file (the push may have carried the file but with intervening
+ *     changes on the same tick — bail loudly, next tick re-evaluates).
+ */
+export async function finaliseDrainOnPushSuccess({
+  runner,
+  repoRoot,
+  pendingDir,
+  drained,
+  stderr,
+}) {
+  const finalised = [];
+  for (const d of drained) {
+    if (d.action !== 'staged-for-retry') continue;
+    // Compare HEAD's blob for the path vs `git hash-object` of the
+    // pending file. Both sides yield git blob shas — binary-safe,
+    // no utf8 round-trip.
+    const headBlob = await runner.spawn(
+      'git', ['rev-parse', '--verify', `HEAD:${d.originalPath}`], { cwd: repoRoot },
+    );
+    if (headBlob.code !== 0) {
+      log(
+        `drain-finalise: HEAD:${d.originalPath} not readable (${headBlob.stderr.trim()}) — pending held`,
+        stderr,
+      );
+      continue;
+    }
+    const headSha = headBlob.stdout.trim();
+    const oursHash = await hashObject(runner, {
+      cwd: repoRoot,
+      path: join(pendingDir, d.id),
+    });
+    if (oursHash.code !== 0 || oursHash.sha !== headSha) {
+      log(
+        `drain-finalise: HEAD:${d.originalPath} blob=${headSha.slice(0, 8)} does not match pending content blob=${oursHash.sha?.slice(0, 8) || 'n/a'} — pending held for re-evaluation next tick`,
+        stderr,
+      );
+      continue;
+    }
+    await removePending(pendingDir, d.id);
+    finalised.push(d.id);
+    log(
+      `drain-finalise: ${d.originalPath} delivered on HEAD — pending removed`,
+      stderr,
+    );
+  }
+  return { finalised };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Digital Operator PA \u2014 single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",