klypix-mcp 1.67.2 → 1.68.0

package/README.md

@@ -693,17 +693,22 @@ Read this section before you build on any of it.
 Every number here is measured on our own project brain. Nothing below is published, benchmarked or
 independently validated.
 
-- **Dogfood scale.** KLYPIX itself is built with its own brain: **1,645 cards and 1,521
+- **Dogfood scale.** KLYPIX itself is built with its own brain: **2,479 cards and 2,018
   connections**, written by multiple concurrent agent sessions, receipts in the file. Current as of
-  2026-08-01.
+  2026-08-13.
 - **Recall.** 73% of past decisions recovered with one search round, 55% brief-only, 0% cold.
   Caveat that travels with it: n=20, our own brain, self-authored questions, LLM-judged.
-- **Ranker.** recall@5 of the true source card went **15% → 40%** across two upgrades (n=20 frozen
-  human-paraphrase questions), measured with the optional on-device reranker enabled. The
-  experiment that *regressed* — contextual prefixes on short cards — is recorded next to the wins.
+- **Ranker.** With the production embedder (the eval harness was fixed 2026-08-10 — it had been
+  measuring a vector space the product does not use): recall@5 **30%**, recall@10 35%, recall@20
+  45%, MRR 0.22 of the true source card on n=20 frozen human-paraphrase questions. Lexical-only
+  scores 0% on the same set. The previously published "15% → 40% with the reranker" is **retired**:
+  re-measured validly, the reranker *reduced* recall@5 to 25% and now ships off by default. At n=20
+  every one of these percentages carries a ±20-point 95% confidence interval — treat them as
+  directional until the larger frozen set lands. The regressions are recorded next to the wins:
+  contextual prefixes on short cards, and the reranker itself.
 - **What we do not publish.** No download count: this package's own 24-hour auto-updater generates
   most of it, so it is not a user count. No adoption, team or customer figures. No brief-token
-  figure — the last one was measured at ~600 cards and is stale at 1,645.
+  figure — the last one was measured at ~600 cards and is stale at 2,479.
 - **The eval harness is not in this repo.** It lives in the private KLYPIX desktop repository. The
   numbers above are ours to defend, not yours to reproduce from here — treat them accordingly.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.67.2",
+  "version": "1.68.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -83,7 +83,7 @@
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
     "pretest": "node test/publish-workflow.mjs",
-    "test": "node test/publish-verdict.mjs && node test/remote-client.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/context-gateway.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
+    "test": "node test/publish-verdict.mjs && node test/remote-client.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/context-gateway.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs"

package/src/agent-presence.mjs

@@ -454,6 +454,7 @@ function normalizeDeliveryRecord(record) {
     ...(record?.acknowledgedActionId ? { acknowledgedActionId: String(record.acknowledgedActionId).slice(0, 160) } : {}),
     ...(record?.consumedActionId ? { consumedActionId: String(record.consumedActionId).slice(0, 160) } : {}),
     ...(record?.offerToken ? { offerToken: String(record.offerToken).slice(0, 160) } : {}),
+    ...(record?.consumedVia ? { consumedVia: String(record.consumedVia).slice(0, 40) } : {}),
     ...(record?.reason ? { reason: String(record.reason).slice(0, 120) } : {}),
     ...(record?.legacySeen ? { legacySeen: true } : {}),
   };
@@ -485,9 +486,16 @@ export function normalizeMessageDelivery(message, now = Date.now()) {
   next.deliveryVersion = MESSAGE_DELIVERY_VERSION;
   next.deliveries = [...byRecipient.values()];
   if (!Array.isArray(next.seen)) next.seen = [];
-  // v2 retired on acknowledgement, which proved only model-context injection.
-  // v3 must conservatively replay it until a token-bound consume receipt lands.
-  if (sourceVersion < MESSAGE_DELIVERY_VERSION && next.retiredAt && !next.deadLetter) delete next.retiredAt;
+  // History is never rewritten (2026-08-13). The previous migration deleted
+  // retiredAt from v2-retired messages to "conservatively replay" them — which
+  // resurrected up to a week of already-delivered notes, and immediately
+  // re-terminalized every one older than 24h as FAILED. That falsified
+  // delivery history in both directions on first post-upgrade touch. A v2
+  // retirement proved model-context injection; it stays retired, recorded as
+  // exactly that and no more.
+  if (sourceVersion < MESSAGE_DELIVERY_VERSION && next.retiredAt && !next.deadLetter && !next.retirement) {
+    next.retirement = { reason: 'v2-retired — model-context injection proven, explicit consumption unknown', at: Number(next.retiredAt) || now };
+  }
   return next;
 }
 
@@ -527,6 +535,7 @@ function setDeliveryState(message, sessionId, state, now, reason = null, actionI
     delete record.consumedAt;
     delete record.acknowledgedActionId;
     delete record.consumedActionId;
+    delete record.consumedVia;
     delete record.failedAt;
     delete record.reason;
   } else if (state === 'acknowledged') {
@@ -557,14 +566,29 @@ function terminalizeMessage(message, now, reason) {
     ...(Array.isArray(next.candidateIds) ? next.candidateIds : []),
     ...next.deliveries.map((entry) => entry.recipientId),
   ].map(recipientKey).filter(Boolean));
-  let unconsumed = known.size === 0;
+  // Split by how far delivery actually got (2026-08-13). 'acknowledged' means
+  // the note was rendered into model context on two independent actions —
+  // expiring after that is NOT a delivery failure, and the old blanket
+  // 'failed' told the sender "no target consumed it" about a note the model
+  // saw repeatedly. Only recipients the note never reached (pending) or
+  // reached exactly once without confirmation (offered) fail, each with a
+  // reason that says which. A message whose every recipient at least
+  // acknowledged retires as delivered-unconfirmed instead of dead-lettering.
+  let failures = 0, reachedUnconsumed = 0;
   for (const recipientId of known) {
-    if (messageDeliveryState(next, recipientId) === 'consumed') continue;
-    unconsumed = true;
-    setDeliveryState(next, recipientId, 'failed', now, reason);
+    const state = messageDeliveryState(next, recipientId);
+    if (state === 'consumed') continue;
+    if (state === 'acknowledged') { reachedUnconsumed++; continue; }
+    failures++;
+    setDeliveryState(next, recipientId, 'failed', now,
+      state === 'pending' ? `${reason} (never delivered)` : `${reason} (offered once, unconfirmed)`);
+  }
+  if (failures || known.size === 0) {
+    next.deadLetter = { state: 'failed', reason, at: now };
+  } else {
+    next.retiredAt = now;
+    if (reachedUnconsumed) next.retirement = { reason: `${reason} — after acknowledgement (delivered, consumption unconfirmed)`, at: now };
   }
-  if (unconsumed) next.deadLetter = { state: 'failed', reason, at: now };
-  else next.retiredAt = now;
   return next;
 }
 
@@ -1537,9 +1561,13 @@ export function receiveMessages({
       const record = messageDeliveryRecord(message, sessionId);
       return !isTerminalMessage(message)
         && message.from !== sessionId
-        && (state === 'pending' || state === 'offered' || state === 'acknowledged')
+        // 'acknowledged' re-renders ONLY when there is no action-identity
+        // evidence of a third action (no actionId on this call, or a legacy
+        // record acknowledged without one). With evidence, the lease pass
+        // below retires it as consumed instead of injecting it a third time.
+        && (state === 'pending' || state === 'offered'
+          || (state === 'acknowledged' && (!actionId || !record?.acknowledgedActionId)))
         && !(state === 'offered' && actionId && record?.offeredActionId === String(actionId))
-        && !(state === 'acknowledged' && actionId && record?.acknowledgedActionId === String(actionId))
         && messageTargetsSession(message, me, sessionId, sessions);
     }).sort((left, right) => {
       // Never let an acknowledged-but-not-yet-consumed replay starve a fresh
@@ -1577,6 +1605,30 @@ export function receiveMessages({
         setDeliveryState(message, sessionId, 'acknowledged', now, null, actionId);
       }
     }
+    // Lease auto-consume (2026-08-13). An acknowledged note was rendered into
+    // model context on TWO independent actions; when a THIRD independent
+    // action arrives, the model has demonstrably moved on with the note in
+    // hand. Retire it as consumed (consumedVia 'auto-lease') instead of
+    // replaying it every action for 24h and then dead-lettering a note the
+    // model saw repeatedly as "failed" — the old design guaranteed a steady
+    // background rate of false-failure receipts from every recipient that
+    // cannot (hook-only lanes) or does not copy offer tokens back. The
+    // explicit brain_message_receipt remains the only path that can record
+    // the stronger claim (consumedVia 'receipt' — "I acted on it").
+    // Requires a real, DIFFERENT actionId: with no action identity there is
+    // no evidence of a third action, so behavior stays replay-until-receipt.
+    if (actionId) {
+      for (const message of messages) {
+        if (isTerminalMessage(message) || message.from === sessionId) continue;
+        const record = messageDeliveryRecord(message, sessionId);
+        if (!record || record.state !== 'acknowledged') continue;
+        if (!record.acknowledgedActionId || record.acknowledgedActionId === String(actionId)) continue;
+        if (!messageTargetsSession(message, me, sessionId, sessions)) continue;
+        setDeliveryState(message, sessionId, 'consumed', now, null, actionId);
+        record.consumedVia = 'auto-lease';
+        retireFullyConsumed(message, now);
+      }
+    }
     // Persist migration/expiry/dead-letter changes even when the inbox is empty.
     fs.mkdirSync(path.dirname(laneFile), { recursive: true });
     writeLaneFileAtomic(laneFile, JSON.stringify({ ...data, sessions, messages }));
@@ -1684,6 +1736,15 @@ export function consumeMessageReceipt({
       return receiptResult(false, false, 'rejected', 'offer-token-mismatch', wantedMessageId, recipientId);
     }
     if (state === 'consumed') {
+      // An auto-leased consumption (the third-action lease in receiveMessages)
+      // proves the model moved on with the note in context; an explicit
+      // receipt is the STRONGER claim — "I acted on it". Record the upgrade.
+      if (record.consumedVia !== 'receipt') {
+        record.consumedVia = 'receipt';
+        fs.mkdirSync(path.dirname(laneFile), { recursive: true });
+        writeLaneFileAtomic(laneFile, JSON.stringify({ ...data, sessions, messages }));
+        return receiptResult(true, true, 'consumed', null, wantedMessageId, recipientId);
+      }
       return receiptResult(true, false, 'consumed', null, wantedMessageId, recipientId);
     }
     if (state === 'offered') {
@@ -1698,6 +1759,8 @@ export function consumeMessageReceipt({
       return receiptResult(false, false, 'rejected', 'delivery-not-acknowledged', wantedMessageId, recipientId);
     }
     setDeliveryState(message, recipientId, 'consumed', now, null, actionId);
+    const consumedRecord = messageDeliveryRecord(message, recipientId);
+    if (consumedRecord) consumedRecord.consumedVia = 'receipt';
     retireFullyConsumed(message, now);
     fs.mkdirSync(path.dirname(laneFile), { recursive: true });
     writeLaneFileAtomic(laneFile, JSON.stringify({ ...data, sessions, messages }));

package/src/global-brain-hook.mjs

@@ -400,20 +400,80 @@ function sweepStaleTmp(dir) {
 // replace only what it drained, so a batch a peer queued meanwhile survives.
 const PENDING_CAPTURES_FILE = path.join(os.homedir(), '.claude', 'project-brain', 'pending', `${sha(normBrainPath(laneCanon(BRAIN)))}.captures.json`);
 const PENDING_CAPTURES_LOCK = PENDING_CAPTURES_FILE + '.lock';
+// A non-ENOENT read failure must ABORT any read-modify-write instead of
+// masquerading as an empty queue — an RMW over a transient EPERM/corrupt read
+// would rewrite the file as "just my change" and destroy every queued batch
+// (2026-08-14 adversarial review). ENOENT alone means genuinely empty.
+function readMainPendingChecked() {
+    try { const d = JSON.parse(fs.readFileSync(PENDING_CAPTURES_FILE, 'utf8')); return { ok: true, batches: Array.isArray(d) ? d : [] }; }
+    catch (e) { return e?.code === 'ENOENT' ? { ok: true, batches: [] } : { ok: false, batches: [] }; }
+}
+function readMainPendingFile() { return readMainPendingChecked().batches; }
+// Orphan sidecars: the lossless fallback when the pending LOCK itself is
+// contended (two sessions refuse in the same instant — the trigger, a held
+// brain lock, is CORRELATED across sessions, so "rare" was wrong). Each orphan
+// is one batch in its own uniquely-named file, written tmp→rename so a drain's
+// readdir never sees a torn one. Drained orphans are deleted by PATH only
+// after the brain write is durable — same discipline as clear-by-id.
+function listOrphanCaptureFiles() {
+    try {
+        const dir = path.dirname(PENDING_CAPTURES_FILE);
+        const prefix = path.basename(PENDING_CAPTURES_FILE) + '.orphan-';
+        return fs.readdirSync(dir).filter((n) => n.startsWith(prefix) && !/\.tmp-[a-z0-9-]+$/.test(n)).map((n) => path.join(dir, n));
+    } catch { return []; }
+}
 function readPendingCaptures() {
-    try { const d = JSON.parse(fs.readFileSync(PENDING_CAPTURES_FILE, 'utf8')); return Array.isArray(d) ? d : []; } catch { return []; }
+    const batches = readMainPendingFile();
+    for (const f of listOrphanCaptureFiles()) {
+        try { const b = JSON.parse(fs.readFileSync(f, 'utf8')); if (b && typeof b === 'object') batches.push({ ...b, __orphanPath: f }); }
+        catch { /* unreadable orphan stays in place; the next drain retries it */ }
+    }
+    return batches;
 }
 function updatePendingCaptures(mutate) {
     const got = acquireLock(PENDING_CAPTURES_LOCK, { tries: 20, waitMs: 25 });
     try {
-        const next = mutate(readPendingCaptures());
+        const read = readMainPendingChecked();
+        if (!read.ok) return;   // unreadable ≠ empty: abort the RMW, preserve the bytes; the next drain retries
+        const next = mutate(read.batches);
         fs.mkdirSync(path.dirname(PENDING_CAPTURES_FILE), { recursive: true });
-        const tmp = PENDING_CAPTURES_FILE + '.tmp';
+        const tmp = `${PENDING_CAPTURES_FILE}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
         fs.writeFileSync(tmp, JSON.stringify(next));
         fs.renameSync(tmp, PENDING_CAPTURES_FILE);
-    } catch { /* never break the session; the transcript markers remain the fallback */ }
+    } catch { /* clears are retried by the next drain; adds go through queuePendingCapture */ }
     finally { if (got) releaseLock(PENDING_CAPTURES_LOCK); }
 }
+// Lossless add. RMW under the pending lock is first choice; on lock contention
+// or a failed write it falls back to an append-only orphan file. Returns false
+// only when BOTH paths failed — the caller must then leave every baseline
+// unadvanced so the markers are re-gathered next Stop instead of lost.
+function queuePendingCapture(batch) {
+    const got = acquireLock(PENDING_CAPTURES_LOCK, { tries: 20, waitMs: 25 });
+    if (got) {
+        try {
+            const read = readMainPendingChecked();
+            if (!read.ok) throw new Error('pending queue unreadable — RMW would destroy it; using the orphan path');
+            const next = [...read.batches, batch];
+            fs.mkdirSync(path.dirname(PENDING_CAPTURES_FILE), { recursive: true });
+            const tmp = `${PENDING_CAPTURES_FILE}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+            fs.writeFileSync(tmp, JSON.stringify(next));
+            fs.renameSync(tmp, PENDING_CAPTURES_FILE);
+            return true;
+        } catch { /* fall through to the orphan path */ }
+        finally { releaseLock(PENDING_CAPTURES_LOCK); }
+    }
+    try {
+        fs.mkdirSync(path.dirname(PENDING_CAPTURES_FILE), { recursive: true });
+        const orphan = `${PENDING_CAPTURES_FILE}.orphan-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+        const tmp = `${orphan}.tmp-${process.pid}`;
+        fs.writeFileSync(tmp, JSON.stringify(batch));
+        fs.renameSync(tmp, orphan);
+        return true;
+    } catch { return false; }
+}
+function clearDrainedOrphans(paths) {
+    for (const f of (paths || [])) { try { fs.unlinkSync(f); } catch { /* re-drained next time; landing twice is superseded away */ } }
+}
 const SESSION_FRESH_MS = 10 * 60 * 1000;   // a lane unseen for 10min is treated as ended
 const MCP_SESSION_FRESH_MS = 3 * 60 * 1000; // an mcp-channel heartbeat is dead after 3min (matches agent-presence)
 // The host CLI's pid (Claude Code exports CLAUDE_PID to every child, including
@@ -806,6 +866,7 @@ function normalizeMsg(m, now = Date.now()) {
             ...(raw.acknowledgedActionId ? { acknowledgedActionId: String(raw.acknowledgedActionId).slice(0, 160) } : {}),
             ...(raw.consumedActionId ? { consumedActionId: String(raw.consumedActionId).slice(0, 160) } : {}),
             ...(raw.offerToken ? { offerToken: String(raw.offerToken).slice(0, 160) } : {}),
+            ...(raw.consumedVia ? { consumedVia: String(raw.consumedVia).slice(0, 40) } : {}),
             ...(raw.reason ? { reason: String(raw.reason).slice(0, 120) } : {}),
             ...(raw.legacySeen ? { legacySeen: true } : {}),
         });
@@ -821,10 +882,15 @@ function normalizeMsg(m, now = Date.now()) {
     next.deliveryVersion = MSG_DELIVERY_VERSION;
     next.deliveries = [...records.values()];
     if (!Array.isArray(next.seen)) next.seen = [];
-    // v2 retired on acknowledgement, which proved only model-context injection.
-    // Conservatively reopen those records. A native v3 retired receipt already
-    // represents full consumption and must survive normalization unchanged.
-    if (sourceVersion < MSG_DELIVERY_VERSION && next.retiredAt && !next.deadLetter) delete next.retiredAt;
+    // History is never rewritten (2026-08-13, PARITY with agent-presence.mjs
+    // normalizeMessageDelivery). The old "conservatively reopen" migration
+    // deleted retiredAt from v2-retired messages, resurrecting a week of
+    // delivered notes and re-terminalizing the >24h ones as FAILED. A v2
+    // retirement proved model-context injection; it stays retired, recorded
+    // as exactly that and no more.
+    if (sourceVersion < MSG_DELIVERY_VERSION && next.retiredAt && !next.deadLetter && !next.retirement) {
+        next.retirement = { reason: 'v2-retired — model-context injection proven, explicit consumption unknown', at: Number(next.retiredAt) || now };
+    }
     return next;
 }
 function msgDeliveryState(m, sid) {
@@ -852,6 +918,7 @@ function setMsgDelivery(m, sid, state, now, reason = null, actionId = '') {
         if (actionId) r.offeredActionId = String(actionId).slice(0, 160);
         delete r.acknowledgedAt; delete r.consumedAt;
         delete r.acknowledgedActionId; delete r.consumedActionId;
+        delete r.consumedVia;
         delete r.failedAt; delete r.reason;
     } else if (state === 'acknowledged') {
         if (!r.offerToken) r.offerToken = makeMsgOfferToken();
@@ -874,13 +941,25 @@ function setMsgDelivery(m, sid, state, now, reason = null, actionId = '') {
 function terminalizeMsg(m, now, reason) {
     const next = normalizeMsg(m, now);
     const known = new Set([...(Array.isArray(next.candidateIds) ? next.candidateIds : []), ...next.deliveries.map(r => r.recipientId)].map(msgRecipientKey).filter(Boolean));
-    let failed = known.size === 0;
+    // Honest terminal split (2026-08-13, PARITY with agent-presence.mjs
+    // terminalizeMessage): 'acknowledged' reached model context on two
+    // independent actions — expiry after that is not a delivery failure.
+    // Only never-delivered (pending) and offered-once-unconfirmed records
+    // fail; an all-acknowledged message retires as delivered-unconfirmed.
+    let failures = 0, reachedUnconsumed = 0;
     for (const id of known) {
-        if (msgDeliveryState(next, id) === 'consumed') continue;
-        failed = true; setMsgDelivery(next, id, 'failed', now, reason);
+        const state = msgDeliveryState(next, id);
+        if (state === 'consumed') continue;
+        if (state === 'acknowledged') { reachedUnconsumed++; continue; }
+        failures++;
+        setMsgDelivery(next, id, 'failed', now, state === 'pending' ? `${reason} (never delivered)` : `${reason} (offered once, unconfirmed)`);
+    }
+    if (failures || known.size === 0) {
+        next.deadLetter = { state: 'failed', reason, at: now };
+    } else {
+        next.retiredAt = now;
+        if (reachedUnconsumed) next.retirement = { reason: `${reason} — after acknowledgement (delivered, consumption unconfirmed)`, at: now };
     }
-    if (failed) next.deadLetter = { state: 'failed', reason, at: now };
-    else next.retiredAt = now;
     return next;
 }
 const msgTerminal = (m) => Boolean(m?.deadLetter || m?.retiredAt);
@@ -1273,10 +1352,14 @@ function messageFooter(sid, tp, lib, actionId = messageActionId(readHookInput(),
         const due = messages.filter(m => {
             const state = msgDeliveryState(m, sid);
             const record = msgDeliveryRecord(m, sid);
+            // 'acknowledged' re-renders ONLY without action-identity evidence
+            // of a third action; with evidence the lease pass below retires it
+            // as consumed instead of injecting it a third time (PARITY with
+            // agent-presence.mjs receiveMessages).
             return m && !msgTerminal(m) && m.from !== sid
-                && ['pending', 'offered', 'acknowledged'].includes(state)
+                && (['pending', 'offered'].includes(state)
+                    || (state === 'acknowledged' && (!actionId || !record?.acknowledgedActionId)))
                 && !(state === 'offered' && actionId && record?.offeredActionId === String(actionId))
-                && !(state === 'acknowledged' && actionId && record?.acknowledgedActionId === String(actionId))
                 && msgTargetsMe(m, me, sid, sessions);
         }).sort((left, right) => {
             // Fresh pending work wins the six-message context budget, followed
@@ -1320,13 +1403,29 @@ function messageFooter(sid, tp, lib, actionId = messageActionId(readHookInput(),
             const prior = msgDeliveryState(m, sid);
             if (prior === 'pending') setMsgDelivery(m, sid, 'offered', now, null, actionId);
             else if (prior === 'offered' || prior === 'acknowledged') {
-                // A later independent action acknowledges the offer. Further
-                // actions keep replaying it and refresh only the action dedupe;
-                // acknowledgement never retires a note in v3.
+                // A later independent action acknowledges the offer.
                 setMsgDelivery(m, sid, 'acknowledged', now, null, actionId);
             }
             retireFullyConsumedMsg(m, now);
         }
+        // Lease auto-consume (2026-08-13, PARITY with agent-presence.mjs
+        // receiveMessages): a note acknowledged on an EARLIER action is retired
+        // as consumed (consumedVia 'auto-lease') when this later independent
+        // action arrives, instead of replaying for 24h and dead-lettering as
+        // "failed" a note the model saw repeatedly. The explicit
+        // brain_message_receipt still records the stronger 'receipt' claim.
+        if (actionId) {
+            for (const m of messages) {
+                if (msgTerminal(m) || m.from === sid) continue;
+                const record = msgDeliveryRecord(m, sid);
+                if (!record || record.state !== 'acknowledged') continue;
+                if (!record.acknowledgedActionId || record.acknowledgedActionId === String(actionId)) continue;
+                if (!msgTargetsMe(m, me, sid, sessions)) continue;
+                setMsgDelivery(m, sid, 'consumed', now, null, actionId);
+                record.consumedVia = 'auto-lease';
+                retireFullyConsumedMsg(m, now);
+            }
+        }
         writeLaneAtomic(JSON.stringify({ ...data, sessions, messages }));
     } catch (error) {
         const reason = String(error?.code || error?.message || 'lane-write-failed').slice(0, 100);
@@ -2531,28 +2630,35 @@ async function capture(lib) {
     // cards into [Area] containers, and wires [[wikilink]] connections.
     const doCapture = async (locked) => {
         const merged = readState(); for (const k of seen) merged.add(k);
+        // Own-batch snapshot BEFORE the drain merges queued peers' batches in:
+        // if the brain write fails we re-queue only OUR contribution (drained
+        // batches stay queued — ids/paths clear only after a durable write),
+        // so nothing lands twice and nothing is lost.
+        const ownCards = cards.slice(), ownResolutions = resolutions.slice(), ownUpdates = updates.slice();
         if (!locked) {
-            // REFUSED: never write from a stale base. The batch is queued durably
-            // (same home as the dedup state) and drained by the next capture in
-            // this project — deferred-but-safe beats immediate-but-clobbering.
-            if (cards.length || resolutions.length || updates.length) {
-                updatePendingCaptures((current) => [
-                    ...current,
-                    { id: `${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2)}`, ts: nowIso(), cards, resolutions, updates },
-                ]);
+            // REFUSED: never write from a stale base. The batch is queued
+            // (lock-held RMW, falling back to an orphan sidecar) and drained by
+            // the next capture — deferred-but-safe beats immediate-but-clobbering.
+            // Baselines advance ONLY if the queue write really succeeded;
+            // otherwise everything stays re-gatherable from the transcript.
+            const queued = (cards.length || resolutions.length || updates.length)
+                ? queuePendingCapture({ id: `${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2)}`, ts: nowIso(), cards, resolutions, updates })
+                : true;
+            if (queued) {
+                writeState(merged);
+                writeLastCommit(newLastCommit); // safe: the batch itself is durably queued (verified above, not assumed)
+                if (drainedShips && typeof lib.clearPendingShips === 'function') lib.clearPendingShips(CWD);
+                advanceShipBaseline(lib);
             }
-            writeState(merged);
-            writeLastCommit(newLastCommit); // safe: the batch itself is durably queued
-            if (drainedShips && typeof lib.clearPendingShips === 'function') lib.clearPendingShips(CWD);
-            advanceShipBaseline(lib);
-            appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode: 'capture', ok: false, err: 'lock-timeout — batch QUEUED for the next capture; brain untouched' }, 500);
-            process.stderr.write('[brain] capture deferred: the brain lock is held (desktop save or peer capture) — batch queued durably, nothing lost\n');
+            appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode: 'capture', ok: false, err: queued ? 'lock-timeout — batch QUEUED for the next capture; brain untouched' : 'lock-timeout AND queue write failed — nothing advanced; markers remain re-gatherable' }, 500);
+            process.stderr.write(queued ? '[brain] capture deferred: the brain lock is held (desktop save or peer capture) — batch queued durably, nothing lost\n' : '[brain] capture deferred AND queueing failed — markers stay in the transcript for the next Stop\n');
             return null;
         }
         // Drain the queue UNDER the lock: read, land, clear-by-id — a peer's
         // batch queued after this read survives, and no batch lands twice.
         const pendingBatches = readPendingCaptures();
         const drainedPendingIds = new Set(pendingBatches.map(b => b && b.id).filter(Boolean));
+        const drainedOrphanPaths = pendingBatches.map(b => b && b.__orphanPath).filter(Boolean);
         for (const b of pendingBatches) {
             if (!b || typeof b !== 'object') continue;
             for (const c of (Array.isArray(b.cards) ? b.cards : [])) cards.push(c);
@@ -2594,6 +2700,7 @@ async function capture(lib) {
             writeState(merged);
             writeLastCommit(newLastCommit);
             if (drainedPendingIds.size) updatePendingCaptures((current) => current.filter(b => b && !drainedPendingIds.has(b.id)));
+            clearDrainedOrphans(drainedOrphanPaths);
             if (drainedShips && typeof lib.clearPendingShips === 'function') lib.clearPendingShips(CWD);
             advanceShipBaseline(lib);
             return null;
@@ -2605,10 +2712,28 @@ async function capture(lib) {
         });
         // Re-pack the whole grid so a container that grew never overlaps its neighbor.
         let out = res.buffer; try { out = (await lib.tidyBrain(res.buffer)).buffer; } catch { /* keep append result if tidy fails */ }
-        await lib.atomicWrite(BRAIN, out);
+        try {
+            await lib.atomicWrite(BRAIN, out);
+        } catch (e) {
+            // The write failed even after atomicWrite's bounded EPERM backoff
+            // (something held brain.klypix past ~2.7s — a desktop save, AV, an
+            // indexer). Same discipline as a lock refusal: queue OUR OWN batch
+            // durably (drained batches stay queued — their ids/paths were never
+            // cleared), advance baselines only if that queue write succeeded,
+            // and exit 0 by contract. Field case: the 2026-08-12 EPERM landed
+            // on a session's FINAL Stop and its markers had nowhere to go.
+            const queued = (ownCards.length || ownResolutions.length || ownUpdates.length)
+                ? queuePendingCapture({ id: `${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2)}`, ts: nowIso(), cards: ownCards, resolutions: ownResolutions, updates: ownUpdates })
+                : true;
+            if (queued) { writeState(merged); writeLastCommit(newLastCommit); }
+            appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode: 'capture', ok: false, err: `write failed (${e?.code || String(e?.message || e).slice(0, 80)}) — own batch ${queued ? 'QUEUED durably' : 'NOT queued; markers remain re-gatherable'}; drained batches remain queued` }, 500);
+            process.stderr.write(`[brain] capture write failed (${e?.code || 'error'}) — ${queued ? 'batch queued durably, nothing lost' : 'queueing ALSO failed; markers stay in the transcript for the next Stop'}\n`);
+            return null;
+        }
         writeState(merged);
         writeLastCommit(newLastCommit); // advance the commit baseline only after a successful write
         if (drainedPendingIds.size) updatePendingCaptures((current) => current.filter(b => b && !drainedPendingIds.has(b.id)));
+        clearDrainedOrphans(drainedOrphanPaths);
         // Same discipline for the two ship channels: the queue is consumed and
         // the observation baseline advances ONLY now that the cards are durable.
         if (drainedShips && typeof lib.clearPendingShips === 'function') lib.clearPendingShips(CWD);

package/src/klypix-core.mjs

@@ -171,12 +171,15 @@ const sha1 = (s) => crypto.createHash('sha1').update(s).digest('hex');
 // "↩ superseded" variant AND the gardener's "⤵ consolidated" stamp), so
 // cross-brain as_of was silently stricter than brain_ask as_of (2026-07-23).
 
-// ── On-device cross-encoder reranker (brain_ask precision) ───────────────────
-// Eval-proven on the frozen human-paraphrase set (2026-07-15): recall@5 15%→40%,
-// MRR 0.087→0.28, top-1 0%→20%. Scores (question, cardText) PAIRS jointly (full
-// token interaction, unlike the bi-encoder cosine) and reorders a wide candidate
-// net. The bounded runtime keeps the same q8 model and scoring while owning
-// tensor disposal and serialization. Disable outright with KLYPIX_RERANK=0.
+// ── On-device cross-encoder reranker (brain_ask, opt-in experiment) ──────────
+// RETIRED as a default after the 2026-08-10 harness fix. The "recall@5 15%→40%"
+// that once justified it here was measured in a vector space the product does
+// not use (mean-pooled, unprefixed queries — the broken pre-fix harness).
+// Re-measured with the PRODUCTION embedder on the frozen human-paraphrase set:
+// the single BGE pass scores recall@5 30% / MRR 0.22; adding the reranker DROPS
+// that to 25% / 0.167 and costs ~3.5s/query. It still scores (question, card)
+// pairs jointly with full token interaction; keep it reachable for experiments
+// via KLYPIX_RERANK=1 (opt-IN — off by default; see the gate below).
 
 // ── small block helpers ──────────────────────────────────────────────────────
 const text = (t) => ({ kind: 'text', text: t });
@@ -523,11 +526,23 @@ export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log =
       const vecs = await vectorsForBrain(pipe, t.file, struct.cards);
       if (qv && vecs && vecs.size) { semantic = new Map(); for (const [id, v] of vecs) semantic.set(id, dot(qv, v)); cardVecs = vecs; mode = 'semantic+lexical (on-device)'; }
     }
-  } catch { semantic = null; cardVecs = null; mode = 'lexical (semantic warming — retry for semantic ranking)'; }
+  } catch { semantic = null; cardVecs = null; }
+  // Parity with search_all_brains (8445e9c): never say "warming — retry" to a
+  // host with no runtime installed — for them that advice is wrong forever and
+  // their results are the measured recall@5 = 0% lexical path. The full notice
+  // is a SEPARATE advisory line: gluing three sentences and a filesystem path
+  // into the "N matched, X ranking" header garbled every lexical-only answer
+  // (2026-08-14 review), and later "+ rerank"/"+ status-mode" suffixes would
+  // have landed mid-sentence.
+  let fallbackNotice = null;
+  if (!semantic) {
+    fallbackNotice = semanticFallbackNotice(false);
+    if (fallbackNotice) mode = fallbackNotice.startsWith('LEXICAL ONLY') ? 'lexical-only (no semantic runtime)' : 'lexical (semantic warming)';
+  }
   const kk = Math.max(1, Math.min(20, k || 10));
   const timeTravel = asOfTs != null;
   // Cross-encoder rerank is OPT-IN. On the frozen human/paraphrase set it made
-  // BGE top-5 recall worse (35%→25%) and added ~3.5s/query. Keep the reversible
+  // BGE top-5 recall worse (30%→25%) and added ~3.5s/query. Keep the reversible
   // escape hatch for experiments, but the best measured experience is the single
   // BGE pass. Suppressed under as_of either way.
   const wantRerank = !timeTravel && process.env.KLYPIX_RERANK === '1';
@@ -558,7 +573,8 @@ export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log =
   if (result.statusStrong && !timeTravel) {
     try { statusMd = statusContextToMarkdown(struct); mode += ' + status-mode'; } catch { statusMd = ''; }
   }
-  return { blocks: [text(stamp + statusMd + questionContextToMarkdown(q, result, { mode, as_of: timeTravel ? as_of : null }))] };
+  const noticeMd = fallbackNotice ? `> ${fallbackNotice}\n\n` : '';
+  return { blocks: [text(stamp + noticeMd + statusMd + questionContextToMarkdown(q, result, { mode, as_of: timeTravel ? as_of : null }))] };
 }
 
 // ── brain_challenge — the adversarial brain ───────────────────────────────────

package/src/klypix-format.mjs

@@ -218,9 +218,25 @@ export async function atomicWrite(filePath, buf, opts = {}) {
     }
     const tmp = filePath + '.tmp-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
     fs.writeFileSync(tmp, buf);
-    try { fs.renameSync(tmp, filePath); }    // Node uses MoveFileEx(REPLACE_EXISTING) on Windows → overwrites atomically
-    catch (e) { try { fs.rmSync(tmp); } catch { /* */ } throw e; }
+    // Windows rename-over-open-destination throws EPERM/EBUSY/EACCES while
+    // another process (a desktop save/read, AV, an indexer) briefly holds the
+    // target — three real capture failures in the field (.hook-health.jsonl,
+    // 2026-08-11/12). A bounded backoff (~2.7s total) outlasts a transient
+    // hold; a persistent holder still throws so callers can queue the batch —
+    // delayed is acceptable, lost is not.
+    for (let attempt = 0; ; attempt++) {
+        try { fs.renameSync(tmp, filePath); break; }   // Node uses MoveFileEx(REPLACE_EXISTING) on Windows → overwrites atomically
+        catch (e) {
+            if (attempt >= RENAME_BACKOFF_MS.length || !RENAME_RETRYABLE_CODES.has(e?.code)) {
+                try { fs.rmSync(tmp); } catch { /* */ }
+                throw e;
+            }
+            await new Promise((resolve) => setTimeout(resolve, RENAME_BACKOFF_MS[attempt]));
+        }
+    }
 }
+const RENAME_RETRYABLE_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
+const RENAME_BACKOFF_MS = [40, 120, 300, 700, 1500];
 
 // ── verify: suffix (decay-aware status, 2026-07-28 post-mortem) ──────────────
 // A card may carry the EXACT live-probe command for its fast-decay claim as a

package/src/mcp-presence.mjs

@@ -1589,6 +1589,11 @@ export function createMcpPresence({
       hostIdentityPrepared: details.hostIdentityPrepared === true,
       clientInfoPrepared: details.clientInfoPrepared || null,
       branchPrepared: details.branchPrepared,
+      // Forward the action identity (2026-08-14 review): without it, every
+      // server instance's FIRST sync advanced delivery receipts with
+      // actionId '' — records got no offered/acknowledgedActionId, breaking
+      // same-action dedupe and the lease's third-action evidence.
+      actionId: details.actionId || '',
     });
     // Consume the write verdict (1.52.0 plumbed it; nothing read it): a
     // contended lane skips the write, and ~3 skipped heartbeats in a row used
@@ -2157,9 +2162,9 @@ export function createMcpPresence({
       delivery: {
         proactive: 'mcp-logging-best-effort-preview',
         modelContext: shouldDeliverMessages ? 'supported-klypix-action' : 'deferred',
-        stateMachine: 'pending -> offered -> acknowledged -> consumed | failed',
-        acknowledgement: 'a later independent supported action followed an offer; explicit token-bound brain_message_receipt records actual model consumption',
-        retention: 'machine-local; 24h TTL and bounded lane capacity, with explicit failed receipts on expiry/overflow',
+        stateMachine: 'pending -> offered -> acknowledged -> consumed (auto-lease on the next independent action, or explicit receipt) | failed',
+        acknowledgement: 'a later independent supported action followed an offer; a further independent action auto-consumes the lease, and explicit token-bound brain_message_receipt records the stronger acted-on-it claim',
+        retention: 'machine-local; 24h TTL and bounded lane capacity; expiry fails only never-delivered or offered-once records — an acknowledged note retires as delivered-unconfirmed, never as failed',
         writeOk: shouldDeliverMessages ? report.deliveryWriteOk : null,
         ...(report.deliveryWriteSkippedReason ? { writeFailure: report.deliveryWriteSkippedReason } : {}),
       },