@ngockhoale/ukit 3.4.22 → 3.4.23

package/template_project/.claude/ukit/index/cleanup-task-worktree.mjs

@@ -0,0 +1,418 @@
+#!/usr/bin/env node
+/**
+ * cleanup-task-worktree.mjs — receipt-gated, recoverable task cleanup
+ * (C97 TASK-C97-010 · MODULE04-SPEC FR-M4-003/003a · §7–§14).
+ *
+ * The shipped handoff samples removed task worktrees with
+ * `git worktree remove <wt> --force` plus `git branch -D "handoff/<name>"`, so a
+ * FAIL, an unreported task or a missing-model task lost its recovery evidence,
+ * and the final gate kept a global "only main worktree must remain" assertion
+ * that force-deleted anything left over. This helper replaces that with one
+ * narrow, fail-closed contract:
+ *
+ *   node .claude/ukit/index/cleanup-task-worktree.mjs \
+ *     --receipt <json-path> --approval <json-path> [--apply]
+ *
+ * Dry-run is the default and mutates nothing. `--apply` removes EXACTLY the one
+ * worktree named by a verified C97-009 landing receipt whose result has been
+ * independently Approved, and only when the source still matches the receipt
+ * snapshot, is Git-clean, unlocked and carries no active run. The worktree is
+ * removed WITHOUT `--force`; the branch is deleted only with safe `-d` when
+ * ancestry is provable, otherwise it is retained and reported. Unrelated,
+ * dirty, active, locked, stale or unapproved state is retained with a named
+ * reason — never destroyed.
+ *
+ * Authority (SPEC §7): the receipt is an attestation backed by a sha256, and
+ * the approval is a plain file; the receipt and approval paths must lie OUTSIDE
+ * the source worktree and outside the receipt's changed set, so an executor
+ * cannot self-author authority inside its own tree. The receipt is never reused
+ * for a different root or task.
+ *
+ * CLI: --help exits 0. stdout is one JSON object:
+ *   { status: "retained" | "eligible" | "removed", taskId, reason, branchRetained }
+ * exit 0 dry-run / retained / removed; exit 2 invalid input or authority;
+ * exit 1 a Git runtime failure (a removal failure retains the branch). A
+ * retained result is never a successful removal.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+
+const GIT_TIMEOUT_MS = (() => {
+  const raw = Number(process.env.UKIT_CLEANUP_GIT_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 20000;
+})();
+const MAX_BUFFER = 64 * 1024 * 1024;
+
+const USAGE = `cleanup-task-worktree.mjs — receipt-gated recoverable task cleanup
+
+Usage:
+  node cleanup-task-worktree.mjs --receipt <json-path> --approval <json-path> [--apply]
+  node cleanup-task-worktree.mjs --help
+
+Dry-run is the default (mutates nothing). --apply removes EXACTLY the one
+worktree named by a verified C97-009 landing receipt whose result is Approved,
+never with --force; an unmerged branch is retained. exit 0 dry-run/retained/
+removed; exit 2 invalid input/authority; exit 1 Git runtime failure.`;
+
+// --- bounded git -------------------------------------------------------------
+
+function git(root, args) {
+  return spawnSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    timeout: GIT_TIMEOUT_MS,
+    killSignal: 'SIGKILL',
+    maxBuffer: MAX_BUFFER,
+  });
+}
+
+// --- exit contract -----------------------------------------------------------
+
+function emit(status, taskId, reason, branchRetained) {
+  process.stdout.write(`${JSON.stringify({
+    status,
+    taskId: taskId ?? null,
+    reason,
+    branchRetained,
+  })}\n`);
+}
+
+// Invalid input or authority: the task is retained (never removed) and the
+// process exits 2. A bounded diagnostic never includes file contents.
+function refuse(taskId, reason, diagnostic) {
+  if (diagnostic) process.stderr.write(`cleanup-task-worktree: ${reason}: ${diagnostic}\n`);
+  emit('retained', taskId, reason, true);
+  process.exit(2);
+}
+
+// A named recovery state (not invalid authority): retained, exit 0.
+function retain(taskId, reason) {
+  emit('retained', taskId, reason, true);
+  process.exit(0);
+}
+
+function runtimeError(taskId, reason, diagnostic) {
+  if (diagnostic) process.stderr.write(`cleanup-task-worktree: ${reason}: ${diagnostic}\n`);
+  emit('retained', taskId, reason, true);
+  process.exit(1);
+}
+
+// --- args --------------------------------------------------------------------
+
+const argv = process.argv.slice(2);
+let receiptPath = null;
+let approvalPath = null;
+let apply = false;
+for (let i = 0; i < argv.length; i += 1) {
+  const a = argv[i];
+  if (a === '--help' || a === '-h') {
+    process.stdout.write(`${USAGE}\n`);
+    process.exit(0);
+  } else if (a === '--apply') {
+    apply = true;
+  } else if (a === '--receipt') {
+    receiptPath = argv[++i];
+    if (receiptPath === undefined) { process.stderr.write('cleanup-task-worktree: missing value for --receipt\n'); process.exit(2); }
+  } else if (a === '--approval') {
+    approvalPath = argv[++i];
+    if (approvalPath === undefined) { process.stderr.write('cleanup-task-worktree: missing value for --approval\n'); process.exit(2); }
+  } else {
+    process.stderr.write(`cleanup-task-worktree: unknown argument: ${a}\n${USAGE}\n`);
+    process.exit(2);
+  }
+}
+if (!receiptPath || !approvalPath) {
+  process.stderr.write(`cleanup-task-worktree: --receipt and --approval are both required\n${USAGE}\n`);
+  process.exit(2);
+}
+
+// --- path helpers ------------------------------------------------------------
+
+const realPath = (p) => {
+  try { return fs.realpathSync(p); } catch { return path.resolve(p); }
+};
+// Resolve symlinks in the longest existing ancestor, then append the remaining
+// segments (macOS /var → /private/var makes a naive resolve a different string).
+function resolveReal(p) {
+  const abs = path.resolve(p);
+  const root = path.parse(abs).root;
+  const parts = abs.slice(root.length).split(path.sep).filter(Boolean);
+  let cur = root;
+  let i = 0;
+  for (; i < parts.length; i += 1) {
+    const next = path.join(cur, parts[i]);
+    if (fs.existsSync(next)) cur = next; else break;
+  }
+  return path.join(realPath(cur), ...parts.slice(i));
+}
+const isInsideOrEqual = (child, parent) => {
+  const c = resolveReal(child);
+  const p = realPath(parent);
+  return c === p || c.startsWith(p + path.sep);
+};
+
+const sha256File = (p) => crypto.createHash('sha256').update(fs.readFileSync(p)).digest('hex');
+
+// --- schema ------------------------------------------------------------------
+
+const RECEIPT_KEYS = [
+  'schemaVersion', 'taskId', 'baseCommit', 'sourceRoot', 'destinationRoot',
+  'sourceBranch', 'sourceHead', 'destinationHeadBefore', 'sourceSnapshotTree',
+  'resultTree', 'patchSha256', 'scopeSha256', 'changedPaths', 'createdAt', 'status',
+];
+const APPROVAL_KEYS = [
+  'schemaVersion', 'taskId', 'receiptSha256', 'verdict', 'executorModel',
+  'reviewerModel', 'reviewedResultTree',
+];
+const TASK_TOKEN = /^TASK-C97-\d{3}$/;
+const OID = /^[0-9a-f]{40}$/;
+
+function readJson(p, taskId, label) {
+  let raw;
+  try {
+    raw = fs.readFileSync(p, 'utf8');
+  } catch {
+    refuse(taskId, 'invalid-authority', `${label} file unreadable`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    refuse(taskId, 'invalid-authority', `${label} is not valid JSON`);
+  }
+}
+
+function validateReceipt(receipt) {
+  const taskId = receipt && typeof receipt === 'object' ? receipt.taskId : null;
+  if (receipt === null || typeof receipt !== 'object' || Array.isArray(receipt)) {
+    refuse(null, 'invalid-authority', 'receipt must be a JSON object');
+  }
+  for (const key of Object.keys(receipt)) {
+    if (!RECEIPT_KEYS.includes(key)) refuse(taskId, 'invalid-authority', `unknown receipt key: ${key}`);
+  }
+  if (receipt.schemaVersion !== 1) refuse(taskId, 'invalid-authority', 'receipt schemaVersion must be 1');
+  if (typeof receipt.taskId !== 'string' || !TASK_TOKEN.test(receipt.taskId)) {
+    refuse(taskId, 'invalid-authority', 'receipt taskId must be an exact TASK-C97-NNN token');
+  }
+  if (receipt.status !== 'landed') refuse(taskId, 'invalid-authority', 'receipt status must be "landed"');
+  for (const k of ['baseCommit', 'sourceRoot', 'destinationRoot', 'sourceHead', 'sourceSnapshotTree', 'resultTree', 'patchSha256', 'scopeSha256']) {
+    if (typeof receipt[k] !== 'string' || receipt[k].length === 0) {
+      refuse(taskId, 'invalid-authority', `receipt ${k} must be a nonempty string`);
+    }
+  }
+  for (const k of ['sourceSnapshotTree', 'resultTree']) {
+    if (!OID.test(receipt[k])) refuse(taskId, 'invalid-authority', `receipt ${k} must be a full tree OID`);
+  }
+  if (receipt.sourceBranch !== null && typeof receipt.sourceBranch !== 'string') {
+    refuse(taskId, 'invalid-authority', 'receipt sourceBranch must be a string or null');
+  }
+  if (!Array.isArray(receipt.changedPaths)) {
+    refuse(taskId, 'invalid-authority', 'receipt changedPaths must be an array');
+  }
+  for (const p of receipt.changedPaths) {
+    if (typeof p !== 'string' || p.length === 0) refuse(taskId, 'invalid-authority', 'receipt changedPaths entries must be nonempty strings');
+  }
+  return receipt.taskId;
+}
+
+function validateApproval(approval, receipt, receiptSha, taskId) {
+  if (approval === null || typeof approval !== 'object' || Array.isArray(approval)) {
+    refuse(taskId, 'invalid-authority', 'approval must be a JSON object');
+  }
+  for (const key of Object.keys(approval)) {
+    if (!APPROVAL_KEYS.includes(key)) refuse(taskId, 'invalid-authority', `unknown approval key: ${key}`);
+  }
+  if (approval.schemaVersion !== 1) refuse(taskId, 'invalid-authority', 'approval schemaVersion must be 1');
+  if (approval.taskId !== taskId) refuse(taskId, 'invalid-authority', 'approval taskId does not match the receipt');
+  if (approval.receiptSha256 !== receiptSha) refuse(taskId, 'invalid-authority', 'approval receiptSha256 does not match the receipt');
+  if (approval.verdict !== 'Approved') refuse(taskId, 'invalid-authority', 'approval verdict must be "Approved"');
+  if (typeof approval.executorModel !== 'string' || approval.executorModel.length === 0) {
+    refuse(taskId, 'invalid-authority', 'approval executorModel must be a nonempty string');
+  }
+  if (typeof approval.reviewerModel !== 'string' || approval.reviewerModel.length === 0) {
+    refuse(taskId, 'invalid-authority', 'approval reviewerModel must be a nonempty string');
+  }
+  if (approval.reviewerModel === approval.executorModel) {
+    refuse(taskId, 'invalid-authority', 'approval reviewerModel must differ from executorModel');
+  }
+  if (approval.reviewedResultTree !== receipt.resultTree) {
+    refuse(taskId, 'invalid-authority', 'approval reviewedResultTree does not match the receipt resultTree');
+  }
+}
+
+// --- state helpers -----------------------------------------------------------
+
+function registeredWorktrees(root) {
+  const res = git(root, ['worktree', 'list', '--porcelain']);
+  if (res.status !== 0) runtimeError(null, 'git-failure', 'worktree list failed');
+  const out = [];
+  let cur = null;
+  for (const line of res.stdout.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      if (cur) out.push(cur);
+      cur = { path: line.slice('worktree '.length), branch: null, locked: false };
+    } else if (cur) {
+      if (line.startsWith('branch ')) cur.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+      else if (line.startsWith('locked')) cur.locked = true;
+    }
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+function hasActiveRun(root) {
+  try {
+    const runsDir = path.join(root, '.ukit', 'storage', 'runs');
+    if (fs.statSync(runsDir).isDirectory() && fs.readdirSync(runsDir).some((f) => f.endsWith('.json'))) {
+      return true;
+    }
+  } catch { /* absent */ }
+  try {
+    const raw = fs.readFileSync(path.join(root, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
+    const m = raw.match(/^Phase:\s*(\S+)/m);
+    if (m && m[1] !== 'done' && m[1] !== 'blocked') return true;
+  } catch { /* no cursor */ }
+  return false;
+}
+
+// Snapshot a worktree's FINAL content via an isolated temp index (never the
+// repository's real index) — the same definition the landing helper used.
+function worktreeTree(root) {
+  const idx = path.join(os.tmpdir(), `ukit-cleanup-${process.pid}-${crypto.randomBytes(6).toString('hex')}.index`);
+  try {
+    const env = { ...process.env, GIT_INDEX_FILE: idx };
+    for (const args of [['read-tree', 'HEAD'], ['add', '-A']]) {
+      const r = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8', timeout: GIT_TIMEOUT_MS, killSignal: 'SIGKILL', env, maxBuffer: MAX_BUFFER });
+      if (r.status !== 0) runtimeError(null, 'git-failure', r.stderr?.split('\n')[0] ?? 'snapshot failed');
+    }
+    const t = spawnSync('git', ['-C', root, 'write-tree'], { encoding: 'utf8', timeout: GIT_TIMEOUT_MS, killSignal: 'SIGKILL', env, maxBuffer: MAX_BUFFER });
+    if (t.status !== 0) runtimeError(null, 'git-failure', t.stderr?.split('\n')[0] ?? 'write-tree failed');
+    return t.stdout.trim();
+  } finally {
+    try { fs.rmSync(idx, { force: true }); } catch { /* absent */ }
+  }
+}
+
+// mode+object of `path` in `treeish` (null when the path is absent — a deletion).
+function treeEntry(root, treeish, p) {
+  const r = git(root, ['ls-tree', '-z', treeish, '--', p]);
+  if (r.status !== 0 || !r.stdout) return null;
+  const row = r.stdout.split('\0').find((x) => x.length > 0);
+  if (!row) return null;
+  const [meta] = row.split('\t');
+  const [mode, , object] = meta.split(' ');
+  return `${mode}:${object}`;
+}
+
+// --- main --------------------------------------------------------------------
+
+function main() {
+  const receipt = readJson(receiptPath, null, 'receipt');
+  const taskId = validateReceipt(receipt);
+  const receiptSha = sha256File(receiptPath);
+  const approval = readJson(approvalPath, taskId, 'approval');
+  validateApproval(approval, receipt, receiptSha, taskId);
+
+  // Authority locations (SPEC §7): outside the source worktree and outside the
+  // receipt's changed set. An executor must not self-author authority in its own
+  // tree or in a path the landing already touched.
+  const sourceRoot = realPath(receipt.sourceRoot);
+  // The receipt changedPaths are DESTINATION-relative (they name what the landing
+  // wrote into the destination). Resolve the containment against BOTH roots: an
+  // authority file sitting at a changed path inside the destination worktree is
+  // just as unsafe as one inside the source worktree, and resolving only against
+  // sourceRoot would silently miss it (review F1).
+  const dstRootForAuthority = realPath(receipt.destinationRoot);
+  // A path is inside `base` only when its base-relative form is not a PARENT
+  // escape. The boundary is the exact `..` segment (or a `../` prefix) — NOT any
+  // `..`-prefixed name, because `..hidden.txt` is a legal repo-relative filename
+  // and a naive `startsWith('..')` would treat it as outside the root and let an
+  // authority file at that changed path bypass the containment check (review F2).
+  // An absolute result (`path.relative` on different drives) is also outside.
+  const containedIn = (base, abs) => {
+    const rel = path.relative(base, abs).split(path.sep).join('/');
+    if (!rel || path.isAbsolute(rel) || rel === '..' || rel.startsWith('../')) return null;
+    return rel;
+  };
+  for (const [label, p] of [['receipt', receiptPath], ['approval', approvalPath]]) {
+    if (isInsideOrEqual(p, sourceRoot)) {
+      refuse(taskId, 'invalid-authority', `${label} path is inside the source worktree`);
+    }
+    const abs = resolveReal(p);
+    for (const base of [sourceRoot, dstRootForAuthority]) {
+      const rel = containedIn(base, abs);
+      if (!rel) continue;
+      for (const changed of receipt.changedPaths) {
+        if (rel === changed || rel.startsWith(`${changed}/`)) {
+          refuse(taskId, 'invalid-authority', `${label} path is inside the receipt changed set`);
+        }
+      }
+    }
+  }
+
+  if (!fs.existsSync(sourceRoot)) retain(taskId, 'source-missing');
+  const destinationRoot = realPath(receipt.destinationRoot);
+  if (!fs.existsSync(destinationRoot)) runtimeError(taskId, 'git-failure', 'destination root is not present');
+
+  // The source must be a registered, unlocked worktree of the same common repo.
+  const worktrees = registeredWorktrees(destinationRoot);
+  const entry = worktrees.find((w) => realPath(w.path) === sourceRoot);
+  if (!entry) refuse(taskId, 'invalid-authority', 'source root is not a registered worktree');
+  if (entry.locked) retain(taskId, 'locked');
+
+  // The task must not carry an in-flight run.
+  if (hasActiveRun(sourceRoot)) retain(taskId, 'active');
+
+  // Revalidate the exact source identity and content against the receipt.
+  const headRes = git(sourceRoot, ['rev-parse', 'HEAD']);
+  if (headRes.status !== 0) retain(taskId, 'source-head-unreadable');
+  if (headRes.stdout.trim() !== receipt.sourceHead) retain(taskId, 'source-head-changed');
+  const branchRes = git(sourceRoot, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+  const branch = branchRes.status === 0 ? branchRes.stdout.trim() : null;
+  if ((receipt.sourceBranch ?? null) !== branch) retain(taskId, 'source-branch-changed');
+
+  // "Dirty" = the source tree differs from the receipt snapshot (tracked, staged
+  // or nonignored untracked content). A snapshot-identical tree is Git-clean and
+  // `git worktree remove` succeeds without --force.
+  if (worktreeTree(sourceRoot) !== receipt.sourceSnapshotTree) retain(taskId, 'dirty-vs-snapshot');
+
+  // Destination path-scoped verification: for every receipt changedPath, the
+  // blob (or absence, for a deletion) in the destination HEAD must equal the
+  // receipt resultTree — the checkpoint commit may move HEAD, so no blind
+  // whole-tree equality.
+  for (const p of receipt.changedPaths) {
+    const expected = treeEntry(destinationRoot, receipt.resultTree, p);
+    const actual = treeEntry(destinationRoot, 'HEAD', p);
+    if (expected !== actual) retain(taskId, 'destination-path-changed');
+  }
+
+  if (!apply) {
+    emit('eligible', taskId, 'eligible', true);
+    process.exit(0);
+  }
+
+  // Remove the registered worktree WITHOUT --force. A refusal or failure (dirty
+  // by Git's own definition, locked, etc.) is a runtime failure that keeps the
+  // worktree and branch — never escalated to --force.
+  const rm = git(destinationRoot, ['worktree', 'remove', sourceRoot]);
+  if (rm.status !== 0) {
+    runtimeError(taskId, 'remove-failed', (rm.stderr || '').split('\n')[0] || 'git worktree remove failed');
+  }
+  if (fs.existsSync(sourceRoot)) {
+    runtimeError(taskId, 'remove-failed', 'worktree still present after removal');
+  }
+
+  // Delete the branch only with safe `-d` when ancestry is provable; an
+  // unmerged milestone branch is retained as recovery evidence (never -D).
+  let branchRetained = true;
+  if (branch) {
+    const del = git(destinationRoot, ['branch', '-d', branch]);
+    branchRetained = del.status !== 0;
+  }
+  emit('removed', taskId, branchRetained ? 'removed-branch-retained' : 'removed', branchRetained);
+  process.exit(0);
+}
+
+main();

package/template_project/.claude/ukit/index/extract-image.mjs

@@ -673,43 +673,98 @@ function main() {
       }
     }
 
-    const written = [];
-    for (const img of selected) {
-      const markerPath = path.join(markerDir, `pending-${img.sha}.json`);
-      const marker = { sha: img.sha, mediaType: img.mediaType, ts: Date.now(), sessionId };
+    // Idempotent unread pending (SPEC FR-M5-001/002 §7):
+    // an existing pending-<sha>.json is UNREAD AUTHORITY — it is never overwritten,
+    // refreshed (no new ts), or reported as newly armed. Creation is EXCLUSIVE
+    // (`wx`), so a concurrent sweep cannot double-arm the same sha: the loser gets
+    // EEXIST and reports alreadyPending instead of NEW.
+    const newlyArmed = [];
+    const alreadyPending = [];
+    const pendingDiagnostics = [];
+
+    // Does the marker already exist? Never throws. An unreadable/corrupt body is
+    // retained byte-identically and surfaced as a bounded diagnostic — it can never
+    // be repaired into a fresh arm, and it never fabricates an analyzed receipt.
+    const inspectExistingMarker = (markerPath, sha) => {
       try {
-        fs.writeFileSync(markerPath, JSON.stringify(marker));
-        written.push({ sha: img.sha, path: markerPath, mediaType: img.mediaType, bytes: 0 });
+        fs.readFileSync(markerPath);
       } catch (err) {
-        process.stderr.write(`extract-image: failed to write marker ${markerPath}: ${err.message}\n`);
+        if (err && err.code === 'ENOENT') return false;
+        // EACCES / EISDIR / anything else: the marker may well exist but we cannot
+        // verify it. Preserve the bytes, diagnose, and do NOT re-arm.
+        pendingDiagnostics.push({ sha, code: 'pending-marker-corrupt' });
+        process.stderr.write(`ukit-vision: pending marker corrupt sha=${sha} retained\n`);
+        return true;
+      }
+      // The bytes exist. A body that is not valid JSON is a half-write: retained and
+      // diagnosed, still not NEW (the sha identity comes from the current input).
+      let corrupt = false;
+      try {
+        JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+      } catch {
+        corrupt = true;
+      }
+      if (corrupt) {
+        pendingDiagnostics.push({ sha, code: 'pending-marker-corrupt' });
+        process.stderr.write(`ukit-vision: pending marker corrupt sha=${sha} retained\n`);
+      }
+      return true;
+    };
+
+    const armMarker = (entry, marker) => {
+      const markerPath = path.join(markerDir, `pending-${entry.sha}.json`);
+      const receipt = { ...entry, path: markerPath, bytes: 0 };
+      if (inspectExistingMarker(markerPath, entry.sha)) {
+        alreadyPending.push(receipt);
+        return;
       }
-    }
-    for (const ref of refs) {
-      const markerPath = path.join(markerDir, `pending-${ref.sha}.json`);
-      const marker = {
-        sha: ref.sha,
-        mediaType: ref.mediaType,
-        ts: Date.now(),
-        sessionId,
-        source: ref.source,
-        ref: ref.value,
-      };
       try {
-        fs.writeFileSync(markerPath, JSON.stringify(marker));
-        written.push({ sha: ref.sha, path: markerPath, mediaType: ref.mediaType, bytes: 0, source: ref.source, ref: ref.value });
+        fs.writeFileSync(markerPath, JSON.stringify(marker), { flag: 'wx' });
+        newlyArmed.push(receipt);
       } catch (err) {
+        if (err && err.code === 'EEXIST') {
+          // Lost the exclusive-create race (or a marker appeared between the read
+          // and the write): the winner owns the NEW report, we report alreadyPending.
+          alreadyPending.push(receipt);
+          return;
+        }
         process.stderr.write(`extract-image: failed to write marker ${markerPath}: ${err.message}\n`);
       }
+    };
+
+    for (const img of selected) {
+      armMarker(
+        { sha: img.sha, mediaType: img.mediaType },
+        { sha: img.sha, mediaType: img.mediaType, ts: Date.now(), sessionId },
+      );
+    }
+    for (const ref of refs) {
+      armMarker(
+        { sha: ref.sha, mediaType: ref.mediaType, source: ref.source, ref: ref.value },
+        {
+          sha: ref.sha,
+          mediaType: ref.mediaType,
+          ts: Date.now(),
+          sessionId,
+          source: ref.source,
+          ref: ref.value,
+        },
+      );
     }
     pruneMarkerDirs(outDir);
     // images[] invariant: marker receipts (bytes: 0, .json path) NEVER belong
     // here — they live in pendingMarkers[]. images[] is the materialized-only
     // shape; detect/mark-pending mode keeps it empty by definition.
+    // imageCount/pendingMarkers[] count NEWLY ARMED markers only; an input whose
+    // marker already existed is reported in the additive alreadyPending[] so the
+    // router can stay silent without the local ref reading as unresolved.
     printResult(opts, {
-      imageCount: written.length,
+      imageCount: newlyArmed.length,
       sessionId,
       images: [],
-      pendingMarkers: written,
+      pendingMarkers: newlyArmed,
+      alreadyPending,
+      pendingDiagnostics,
       alreadyAnalyzed,
     });
     return;