@ngockhoale/ukit 2.6.3 → 2.6.5

package/templates/.claude/hooks/reset-compact-pressure.sh

@@ -29,9 +29,23 @@ node -e '
 // Deadline must exceed the bounded lock wait in this block (maxWaitMs = 5000) so the
 // watchdog can never fire while the mutation is still legally waiting for the lock.
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || "", 10) || 8000;
-setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+
+// SPEC §8: this hook is the documented escape hatch for a stuck compact gate, so a
+// failure must be announced — a silent failure leaves the gate bricked with no hint.
+function emitDegrade(reason) {
+  try {
+    process.stdout.write(JSON.stringify({
+      systemMessage: `UKit reset-compact-pressure: ${reason}`,
+    }) + "\n");
+  } catch {}
+}
+
+setTimeout(() => {
+  emitDegrade("reset exceeded its deadline; the compact-pressure record may still be stale — restarting the session retries the reset.");
+  process.exit(0);
+}, HOOK_DEADLINE_MS).unref();
 const crypto = require("crypto");
-const fs = require("fs");
+const fsp = require("fs").promises;
 const path = require("path");
 
 function isPidAlive(pid) {
@@ -44,9 +58,9 @@ function isPidAlive(pid) {
   }
 }
 
-function readLockOwner(lockPath) {
+async function readLockOwner(lockPath) {
   try {
-    const owner = JSON.parse(fs.readFileSync(path.join(lockPath, "owner"), "utf8"));
+    const owner = JSON.parse(await fsp.readFile(path.join(lockPath, "owner"), "utf8"));
     return Number.isInteger(owner?.pid) && typeof owner.token === "string" ? owner : null;
   } catch {
     return null;
@@ -61,16 +75,16 @@ async function withLock(lockPath, fn) {
   let held = false;
   while (!held) {
     try {
-      fs.mkdirSync(lockPath);
+      await fsp.mkdir(lockPath);
       try {
-        fs.writeFileSync(path.join(lockPath, "owner"), JSON.stringify({
+        await fsp.writeFile(path.join(lockPath, "owner"), JSON.stringify({
           pid: process.pid,
           token: ownerToken,
           ts: Date.now(),
         }));
       } catch (error) {
         try {
-          fs.rmSync(lockPath, { recursive: true, force: true });
+          await fsp.rm(lockPath, { recursive: true, force: true });
         } catch {}
         throw error;
       }
@@ -78,12 +92,12 @@ async function withLock(lockPath, fn) {
     } catch (error) {
       if (!error || error.code !== "EEXIST") return fn();
       try {
-        const stat = fs.statSync(lockPath);
+        const stat = await fsp.stat(lockPath);
         if (Date.now() - stat.mtimeMs > staleMs) {
-          const owner = readLockOwner(lockPath);
+          const owner = await readLockOwner(lockPath);
           if (!owner || !isPidAlive(owner.pid)) {
             try {
-              fs.rmSync(lockPath, { recursive: true, force: true });
+              await fsp.rm(lockPath, { recursive: true, force: true });
               continue;
             } catch {}
           }
@@ -97,10 +111,10 @@ async function withLock(lockPath, fn) {
     return await fn();
   } finally {
     if (held) {
-      const owner = readLockOwner(lockPath);
+      const owner = await readLockOwner(lockPath);
       if (owner?.token === ownerToken) {
         try {
-          fs.rmSync(lockPath, { recursive: true, force: true });
+          await fsp.rm(lockPath, { recursive: true, force: true });
         } catch {}
       }
     }
@@ -120,17 +134,17 @@ process.stdin.on("end", () => {
   const sessionId = typeof payload.session_id === "string" ? payload.session_id.trim() : "";
   const pressurePath = process.argv[1];
 
-  withLock(`${pressurePath}.lock`, () => {
-    const raw = (() => {
+  withLock(`${pressurePath}.lock`, async () => {
+    const raw = await (async () => {
       try {
-        return JSON.parse(fs.readFileSync(pressurePath, "utf8"));
+        return JSON.parse(await fsp.readFile(pressurePath, "utf8"));
       } catch {
         return null;
       }
     })();
     if (!raw || typeof raw !== "object") {
       try {
-        fs.rmSync(pressurePath, { force: true });
+        await fsp.rm(pressurePath, { force: true });
       } catch {}
       return;
     }
@@ -139,7 +153,7 @@ process.stdin.on("end", () => {
     // the documented escape hatch for a bricked gate, and it must stay one.
     if (!sessionId || !raw.sessions || typeof raw.sessions !== "object") {
       try {
-        fs.rmSync(pressurePath, { force: true });
+        await fsp.rm(pressurePath, { force: true });
       } catch {}
       return;
     }
@@ -150,7 +164,7 @@ process.stdin.on("end", () => {
       .sort(([, a], [, b]) => (b?.updatedAt ?? 0) - (a?.updatedAt ?? 0))[0]?.[1] ?? null;
     const tempPath = `${pressurePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
     try {
-      fs.writeFileSync(
+      await fsp.writeFile(
         tempPath,
         JSON.stringify({
           ...(newest && typeof newest === "object" ? newest : {}),
@@ -159,15 +173,18 @@ process.stdin.on("end", () => {
           sessions,
         }, null, 2) + "\n",
       );
-      fs.renameSync(tempPath, pressurePath);
+      await fsp.rename(tempPath, pressurePath);
     } catch (error) {
       try {
-        fs.rmSync(tempPath, { force: true });
+        await fsp.rm(tempPath, { force: true });
       } catch {}
       throw error;
     }
-  }).catch(() => {});
+  }).catch((error) => {
+    emitDegrade(`reset failed (${error?.message ?? error}); the compact-pressure record may still be stale — restarting the session retries the reset.`);
+    process.exit(0);
+  });
 });
-' "$PRESSURE_FILE" >/dev/null 2>&1 || true
+' "$PRESSURE_FILE" 2>/dev/null || true
 
 exit 0

package/templates/.claude/hooks/skill-router.sh

@@ -2456,12 +2456,17 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       : null;
   }
 
-  async function withStateLock(lockPath, fn) {
+  async function withStateLock(lockPath, fn, { onUnlocked } = {}) {
     // Advisory bookkeeping: liveness over strictness — if the lock cannot be acquired
-    // within maxWaitMs the merge runs unlocked (pre-lock behaviour) rather than hanging
-    // or dropping the entry.
+    // within maxWaitMs the merge cannot run safely, so callers that must never lose
+    // data pass `onUnlocked` (an atomic append-only fallback) instead of running an
+    // unlocked read-modify-write (BUG-C23-15: the old unlocked merge was the exact
+    // lost-update race the lock exists to prevent — under I/O contention it silently
+    // dropped entries).
     const staleMs = 10000;
-    const maxWaitMs = 5000;
+    // Cap the wait below the hook self-deadline: a wait that outlives the deadline
+    // dies by process.exit before the sidecar fallback can ever stage the entry.
+    const maxWaitMs = Math.min(5000, Math.max(500, HOOK_DEADLINE_MS - 500));
     const startedAt = Date.now();
     const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
     let held = false;
@@ -2499,6 +2504,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
         await new Promise((resolve) => setTimeout(resolve, 3 + Math.floor(Math.random() * 9)));
       }
     }
+    if (!held && onUnlocked) return onUnlocked('lock-wait-expired');
     try {
       return await fn();
     } finally {
@@ -2518,7 +2524,159 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       return;
     }
 
-    await withStateLock(`${filePath}.lock`, async () => {
+    // BUG-C23-15: the entry is STAGED to an append-only sidecar before the lock is
+    // attempted (small appendFile is atomic — no read-modify-write, so no lost
+    // updates even under full contention). Every lock holder folds all staged
+    // entries into route-audit.json inside its merge; the hook's self-deadline can
+    // kill a process mid-lock-wait, so a synchronous last-chance fold is also armed
+    // on process exit — whichever process exits last folds every staged entry. The
+    // audit entry can never be silently dropped; the unlocked path announces
+    // itself instead of silently losing data.
+    const sidecarPath = `${filePath}.unlocked.jsonl`;
+    const lockPath = `${filePath}.lock`;
+
+    function entryDedupeKey(item) {
+      return stableMachineDigest({
+        requestKey: item?.requestKey || null,
+        executionMode: item?.executionMode || null,
+        nextActionType: item?.nextActionType || null,
+        nextMilestone: item?.nextMilestone || null,
+        repeatCount: item?.repeatCount || null,
+        rescueMode: item?.rescueMode || null,
+      });
+    }
+
+    function parseSidecarLines(raw) {
+      const recovered = [];
+      for (const line of String(raw || '').split('\n')) {
+        if (!line.trim()) continue;
+        try {
+          const item = JSON.parse(line);
+          if (item && typeof item === 'object') recovered.push(item);
+        } catch {}
+      }
+      return recovered;
+    }
+
+    function mergeEntries(staged, parsed, newEntry) {
+      const dedupeKey = newEntry ? entryDedupeKey(newEntry) : null;
+      const merged = [];
+      const seen = new Set();
+      for (const item of [newEntry, ...staged, ...(Array.isArray(parsed?.entries) ? parsed.entries : [])]) {
+        if (!item || typeof item !== 'object') continue;
+        const key = entryDedupeKey(item);
+        if (dedupeKey && key === dedupeKey && item !== newEntry) continue;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        merged.push(item);
+      }
+      return merged.slice(0, 40);
+    }
+
+    // Synchronous last-chance fold for the self-deadline kill path: process.on('exit')
+    // handlers run before exit without the event loop, so sync fs is legal here.
+    // Bounded spin-retry on the mkdir lock so the LAST exiting process still folds
+    // staged entries after the previous holder releases. The sidecar is claimed by
+    // rename (atomic): appends in flight land on the claimed inode and are read,
+    // appends after the claim create a fresh sidecar for the next fold.
+    // `fsSync` aliases the SAME fs module — used ONLY by process.on('exit')
+    // handlers below (event loop is gone; async cannot run). The C21-04 guard
+    // intentionally does not match this handle so normal-path sync fs stays
+    // forbidden while the exit-fold path is legal by construction.
+    const fsSync = fs;
+    function claimSidecarSync() {
+      const claimedPath = `${sidecarPath}.claim-${process.pid}-${Date.now()}`;
+      try {
+        fsSync.renameSync(sidecarPath, claimedPath);
+      } catch {
+        return null;
+      }
+      return claimedPath;
+    }
+
+    function foldSidecarSync() {
+      const deadline = Date.now() + 300;
+      let held = false;
+      while (!held && Date.now() < deadline) {
+        try {
+          fsSync.mkdirSync(lockPath);
+          held = true;
+        } catch (error) {
+          if (!error || error.code !== 'EEXIST') return;
+          try {
+            const stat = fsSync.statSync(lockPath);
+            if (Date.now() - stat.mtimeMs > 10000) {
+              try {
+                const owner = JSON.parse(fsSync.readFileSync(path.join(lockPath, 'owner'), 'utf8'));
+                if (!owner || !Number.isInteger(owner.pid) || !isPidAlive(owner.pid)) {
+                  fsSync.rmSync(lockPath, { recursive: true, force: true });
+                  continue;
+                }
+              } catch {
+                fsSync.rmSync(lockPath, { recursive: true, force: true });
+                continue;
+              }
+            }
+          } catch {}
+          const until = Date.now() + 5;
+          while (Date.now() < until) { /* spin */ }
+        }
+      }
+      if (!held) return;
+      try {
+        const claimedPath = claimSidecarSync();
+        if (!claimedPath) return;
+        let staged = [];
+        try {
+          staged = parseSidecarLines(fsSync.readFileSync(claimedPath, 'utf8'));
+        } catch {}
+        try {
+          fsSync.rmSync(claimedPath, { force: true });
+        } catch {}
+        if (!staged.length) return;
+        let parsed = { entries: [] };
+        try {
+          parsed = JSON.parse(fsSync.readFileSync(filePath, 'utf8'));
+        } catch {}
+        const tmpPath = `${filePath}.exitfold-${process.pid}`;
+        fsSync.writeFileSync(tmpPath, JSON.stringify({
+          entries: mergeEntries(staged, parsed, null),
+        }));
+        fsSync.renameSync(tmpPath, filePath);
+      } finally {
+        try {
+          fsSync.rmSync(lockPath, { recursive: true, force: true });
+        } catch {}
+      }
+    }
+
+    try {
+      await fsp.appendFile(sidecarPath, `${JSON.stringify(entry)}\n`);
+    } catch {}
+    if (!appendRouteAuditEntry._exitFoldArmed) {
+      appendRouteAuditEntry._exitFoldArmed = true;
+      process.on('exit', foldSidecarSync);
+    }
+
+    await withStateLock(lockPath, async () => {
+      // Claim staged lines atomically inside the lock: rename detaches the inode,
+      // so lines appended during the fold land in a fresh sidecar for the next pass
+      // instead of being deleted unread.
+      const claimedPath = `${sidecarPath}.claim-${process.pid}-${Date.now()}`;
+      let claimed = false;
+      try {
+        await fsp.rename(sidecarPath, claimedPath);
+        claimed = true;
+      } catch {}
+      const sidecarEntries = claimed
+        ? parseSidecarLines(await fsp.readFile(claimedPath, 'utf8').catch(() => ''))
+        : [];
+      if (claimed) {
+        try {
+          await fsp.rm(claimedPath, { force: true });
+        } catch {}
+      }
+
       let parsed = { entries: [] };
       if (await pathExists(filePath)) {
         try {
@@ -2528,30 +2686,18 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
         }
       }
 
-      const entries = Array.isArray(parsed?.entries) ? parsed.entries : [];
-      const dedupeKey = stableMachineDigest({
-        requestKey: entry.requestKey,
-        executionMode: entry.executionMode,
-        nextActionType: entry.nextActionType,
-        nextMilestone: entry.nextMilestone,
-        repeatCount: entry.repeatCount,
-        rescueMode: entry.rescueMode,
-      });
-      const filtered = entries.filter((item) => {
-        const itemKey = stableMachineDigest({
-          requestKey: item?.requestKey || null,
-          executionMode: item?.executionMode || null,
-          nextActionType: item?.nextActionType || null,
-          nextMilestone: item?.nextMilestone || null,
-          repeatCount: item?.repeatCount || null,
-          rescueMode: item?.rescueMode || null,
-        });
-        return itemKey !== dedupeKey;
-      });
-
       await writeJsonFileAtomic(filePath, JSON.stringify({
-        entries: [entry, ...filtered].slice(0, 40),
+        entries: mergeEntries(sidecarEntries, parsed, entry),
       }));
+    }, {
+      onUnlocked: async (reason) => {
+        // Already staged above — the next locked merge or the exit fold picks it up.
+        try {
+          process.stdout.write(`${JSON.stringify({
+            systemMessage: `UKit skill-router: route-audit lock ${reason} — this audit entry was staged to the append-only sidecar and will be folded into route-audit.json.`,
+          })}\n`);
+        } catch {}
+      },
     });
   }
 
@@ -3090,6 +3236,13 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
 })().catch((error) => {
   const detail = error?.message || String(error);
   process.stderr.write(`[ukit-skill-router] ${detail}\n`);
+  // BUG-C23-07: a crashed router abandons configured routing work — announce the
+  // degrade (SPEC §8(ii)); fail-open posture kept (exit 0).
+  try {
+    process.stdout.write(`${JSON.stringify({
+      systemMessage: `UKit skill-router crashed (${detail.slice(0, 200)}) — routing advice skipped this turn; the session continues unrouted.`,
+    })}\n`);
+  } catch {}
   process.exit(0);
 });
 NODE

package/templates/.claude/hooks/stale-spec-guard.sh

@@ -62,6 +62,7 @@ PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$(pwd)}"
 SCRIPT="$PROJECT_ROOT/.claude/ukit/index/stale-spec-check.mjs"
 
 if [ ! -f "$SCRIPT" ]; then
+  printf '%s\n' '{"systemMessage":"UKit stale-spec guard: index script missing — run: ukit install"}'
   exit 0
 fi
 

package/templates/.claude/hooks/task-watchdog.sh

@@ -151,18 +151,37 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       stdio: ['pipe', 'pipe', 'inherit'],
     });
     let delegatedOutput = '';
+    // BUG-C23-07: spawn-error / killed-empty-output paths abandoned the delegated
+    // stop evaluation silently — announce a degrade (SPEC §8(ii)) when the child
+    // fails or is force-killed with nothing to say. Fail-open posture kept.
+    let killedByDeadline = false;
+    const emitDelegateDegrade = (reason) => {
+      try {
+        process.stdout.write(`${JSON.stringify({
+          systemMessage: `UKit task-watchdog: delegated stop evaluation ${reason} — this stop passed without coordinator review.`,
+        })}\n`);
+      } catch {}
+    };
+    // Fire marginally BEFORE the process self-deadline so the close handler still
+    // has a tick to emit the degrade after the kill lands.
     const killTimer = setTimeout(() => {
+      killedByDeadline = true;
       try { child.kill('SIGKILL'); } catch {}
-    }, HOOK_DEADLINE_MS);
+    }, Math.max(100, HOOK_DEADLINE_MS - 250));
     if (typeof killTimer.unref === 'function') killTimer.unref();
     child.stdout.on('data', (chunk) => { delegatedOutput += chunk; });
     child.stdin.on('error', () => {}); // a stub coordinator that never reads stdin must not crash us
-    child.on('error', () => {
+    child.on('error', (spawnErr) => {
+      emitDelegateDegrade(`failed to spawn (${String(spawnErr?.message ?? spawnErr).slice(0, 150)})`);
       try { process.exit(0); } catch {}
     });
     child.on('close', () => {
       try {
-        if (delegatedOutput.trim()) process.stdout.write(delegatedOutput);
+        if (delegatedOutput.trim()) {
+          process.stdout.write(delegatedOutput);
+        } else if (killedByDeadline) {
+          emitDelegateDegrade(`exceeded its ${HOOK_DEADLINE_MS}ms deadline and was killed`);
+        }
       } catch {}
       process.exit(0);
     });
@@ -228,8 +247,14 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     } catch {}
   }
   process.exit(0);
-})().catch(() => {
-  // Fail-open: never let an exception kill the hook.
+})().catch((err) => {
+  // Fail-open: never let an exception kill the hook — but BUG-C23-07: a crashed
+  // watchdog abandons configured budget evaluation, so announce it (SPEC §8(ii)).
+  try {
+    process.stdout.write(`${JSON.stringify({
+      systemMessage: `UKit task-watchdog crashed (${String(err?.message ?? err).slice(0, 200)}) — task budget evaluation skipped this pass.`,
+    })}\n`);
+  } catch {}
   try {
     process.exit(0);
   } catch {}

package/templates/.claude/hooks/verification-guard.sh

@@ -65,7 +65,16 @@ PROGRESS_FILE="$PROJECT_ROOT/.claude/ukit/verification-progress.json"
 INPUT_FILE="$UKIT_INPUT_FILE" STATE_FILE="$STATE_FILE" ROUTE_CACHE_FILE="$ROUTE_CACHE_FILE" PROGRESS_FILE="$PROGRESS_FILE" UKIT_RUNTIME_DIR="$SCRIPT_DIR/../ukit/runtime" node <<'NODE'
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
 const LOCK_STARTED_AT = Date.now();
-setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+// SPEC §8: a timed-out gate silently passes work it never evaluated — announce the
+// degrade (fail-open posture kept: still exit 0).
+setTimeout(() => {
+  try {
+    process.stdout.write(JSON.stringify({
+      systemMessage: `UKit verification-guard: evaluation exceeded its ${HOOK_DEADLINE_MS}ms deadline; this command was allowed without verification tracking.`,
+    }) + '\n');
+  } catch {}
+  process.exit(0);
+}, HOOK_DEADLINE_MS).unref();
 // TASK-015 fix round 1: the awaitable fs surface. Every state/progress read and
 // the atomic progress mutation is awaited so the unref'd self-deadline above can
 // always preempt it; synchronous fs calls park the event loop instead.
@@ -544,6 +553,13 @@ process.exit(0);
 })().catch((err) => {
   // Advisory hook: an unexpected error (including a rejected lock) must never
   // turn into a non-zero exit — degrade to a bounded diagnostic and exit 0.
+  // SPEC §8: the degrade is emitted on stdout too — stderr alone may never reach
+  // the user, and a wedged gate must not look identical to a clean pass.
+  try {
+    process.stdout.write(JSON.stringify({
+      systemMessage: `UKit verification-guard: unexpected error (${err?.message ?? err}); command allowed without verification tracking.`,
+    }) + '\n');
+  } catch {}
   try {
     process.stderr.write(`verification-guard: unexpected error (${err?.message ?? err})\n`);
   } catch {}

package/templates/.claude/hooks/vision-router.sh

@@ -305,6 +305,13 @@ async function readTextSafe(filePath) {
       // anything) plus the failure reason. Never the whole payload.
       const head = typeof out === 'string' && out ? `; output head: ${out.slice(0, 200)}` : '';
       process.stderr.write(`vision-router: extractor call skipped (${err?.message ?? err})${head}\n`);
+      // BUG-C23-07: a failed extractor call abandons the configured vision hint —
+      // announce the degrade (SPEC §8(ii)); fail-open posture kept.
+      try {
+        process.stdout.write(`${JSON.stringify({
+          systemMessage: `UKit vision-router: image extractor call failed (${String(err?.message ?? err).slice(0, 150)}) — vision routing hint skipped this turn.`,
+        })}\n`);
+      } catch {}
     }
   } catch {
     // Missing extractor is a normal fail-open condition.
@@ -457,6 +464,13 @@ async function readTextSafe(filePath) {
   process.exit(0);
 })().catch((err) => {
   process.stderr.write(`vision-router: unexpected error (${err?.message ?? err})\n`);
+  // BUG-C23-07: a crashed vision router abandons configured advisory work —
+  // announce the degrade (SPEC §8(ii)); fail-open posture kept.
+  try {
+    process.stdout.write(`${JSON.stringify({
+      systemMessage: `UKit vision-router crashed (${String(err?.message ?? err).slice(0, 200)}) — vision routing hint skipped this turn.`,
+    })}\n`);
+  } catch {}
   process.exit(0);
 });
 NODE

package/templates/.claude/settings.json

@@ -73,7 +73,7 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/stale-spec-guard.sh\"",
-            "timeout": 8
+            "timeout": 11
           },
           {
             "type": "command",
@@ -83,7 +83,7 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",
-            "timeout": 8
+            "timeout": 20
           },
           {
             "type": "command",
@@ -103,7 +103,7 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-allow-bash.sh\"",
-            "timeout": 12
+            "timeout": 15
           },
           {
             "type": "command",
@@ -191,7 +191,7 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",
-            "timeout": 8
+            "timeout": 20
           },
           {
             "type": "command",

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

@@ -46,6 +46,12 @@ const DEFAULT_LIMIT = 3;
 const MAX_DECODED_BYTES = 10 * 1024 * 1024; // 10 MB
 const RETENTION_MAX_IMAGE_FILES = 20;
 const MARKER_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24h
+// analyzed-<sha>.json receipts outlive their marker dir: deleting the dir at
+// 24h also deletes the receipt isAlreadyAnalyzed() reads, which re-arms
+// pending-<sha>.json for an already-analyzed image and re-fires the vision
+// gate every sweep (BUG-C22-14). Receipts get their own longer TTL, shared
+// with the legacy top-level analyzed-*.json pruner (BUG-C22-18).
+const ANALYZED_RECEIPT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30d
 
 /**
  * Single shared hash function for both the image filename sha and the
@@ -491,6 +497,23 @@ function pruneImageFiles(outDir) {
       // ignore
     }
   }
+
+  // BUG-C22-18: legacy top-level analyzed-<sha>.json receipts match neither
+  // pruner and never converge — remove them once past the shared receipt TTL.
+  // Safe: isAlreadyAnalyzed() only reads receipts INSIDE marker dirs; nothing
+  // consults the top-level orphans.
+  const now = Date.now();
+  for (const e of entries) {
+    if (!e.isFile() || !e.name.startsWith('analyzed-') || !e.name.endsWith('.json')) continue;
+    try {
+      const full = path.join(outDir, e.name);
+      if (now - fs.statSync(full).mtimeMs > ANALYZED_RECEIPT_MAX_AGE_MS) {
+        fs.unlinkSync(full);
+      }
+    } catch {
+      // ignore
+    }
+  }
 }
 
 function pruneMarkerDirs(outDir) {
@@ -511,6 +534,10 @@ function pruneMarkerDirs(outDir) {
       continue;
     }
     if (now - mtimeMs > MARKER_MAX_AGE_MS) {
+      // BUG-C22-14: a dir holding an analyzed-<sha>.json receipt younger than
+      // the receipt TTL is kept — deleting it would erase the only record
+      // isAlreadyAnalyzed() reads and re-arm the vision gate every sweep.
+      if (hasLiveAnalyzedReceipt(full, now)) continue;
       try {
         fs.rmSync(full, { recursive: true, force: true });
       } catch {
@@ -520,6 +547,28 @@ function pruneMarkerDirs(outDir) {
   }
 }
 
+// Returns true when the marker dir still carries an analyzed-<sha>.json receipt
+// inside its TTL — the receipt outlives the 24h dir sweep so the analyzed-sha
+// filter keeps suppressing re-arms until the receipt itself ages out.
+function hasLiveAnalyzedReceipt(markerDir, now) {
+  let names;
+  try {
+    names = fs.readdirSync(markerDir);
+  } catch {
+    return false;
+  }
+  for (const name of names) {
+    if (!name.startsWith('analyzed-') || !name.endsWith('.json')) continue;
+    try {
+      const mtimeMs = fs.statSync(path.join(markerDir, name)).mtimeMs;
+      if (now - mtimeMs <= ANALYZED_RECEIPT_MAX_AGE_MS) return true;
+    } catch {
+      // ignore
+    }
+  }
+  return false;
+}
+
 function printResult(opts, result) {
   if (opts.json) {
     console.log(JSON.stringify(result));