klypix-mcp 1.67.2 → 1.69.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/bin/klypix-install.mjs

@@ -10,6 +10,8 @@
 //   npx klypix-mcp install            # install / update the brain on this machine
 //   npx klypix-mcp install --force    # overwrite even a newer / dev-deployed brain
 //   npx klypix-mcp install --codex-hooks  # optional prompt/file awareness; Codex asks for trust
+//   npx klypix-mcp install --allow-untagged  # acknowledge deploying an UNTAGGED source checkout
+//                                            # (dev deploy; also KLYPIX_MCP_ALLOW_UNTAGGED=1)
 //
 // Never-throws-silently: it's an explicit CLI, so it reports what it did and exits
 // non-zero on a real failure. Never wires a broken settings.json (refuse + restore).
@@ -17,7 +19,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import crypto from 'crypto';
-import { spawn } from 'child_process';
+import { execFileSync, spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import {
     connectCodexMcpServer,
@@ -29,8 +31,9 @@ import {
     codexPresenceHookStatus,
     mergeCodexPresenceHooks,
 } from '../src/codex-hooks.mjs';
-import { brainInstallDecision } from '../src/install-version.mjs';
+import { brainInstallDecision, deploySourceDecision } from '../src/install-version.mjs';
 import { acquireInstallLockSync, releaseInstallLockSync } from '../src/install-lock.mjs';
+import { collectRepoState } from '../src/repo-state.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(__dirname, '..');
@@ -45,6 +48,11 @@ const VERSION = (() => { try { return JSON.parse(fs.readFileSync(path.join(PKG_R
 const FORCE = process.argv.includes('--force');
 const CODEX_HOOKS = process.argv.includes('--codex-hooks');
 const RUNTIME_ONLY = process.argv.includes('--runtime-only');
+// Released-tag deploy-guard acknowledgement. Deliberately a SEPARATE axis from
+// --force: --force is destination authority (overwrite what is installed),
+// this is source authority (knowingly deploy an untagged working tree).
+const ALLOW_UNTAGGED = process.argv.includes('--allow-untagged')
+    || process.env.KLYPIX_MCP_ALLOW_UNTAGGED === '1';
 
 const HOME = os.homedir();
 const CLAUDE_DIR = path.join(HOME, '.claude');
@@ -224,6 +232,52 @@ try {
         if (!RUNTIME_ONLY) reportCodex(wireCodex());
         process.exit(0);
     }
+
+    // ── Released-tag deploy guard (2026-08-14 bundle-currency incident) ──────
+    // A source checkout whose HEAD does not carry the release tag for its own
+    // package version is UNRELEASED code, yet this installer used to lay it
+    // down machine-globally with receipts claiming a clean npm delivery — the
+    // exact twin of the desktop near-miss that shipped this wave. Only
+    // PKG_ROOT's own git state is interrogated (never process.cwd(): the
+    // auto-update child runs the installer with the PROJECT as cwd), and only
+    // when PKG_ROOT itself contains a .git entry — an npm/npx tarball install
+    // has none and IS the released artifact, so it stays exempt; the registry
+    // channel is already tag-bound by publish.yml. The tag must point at HEAD
+    // (`git tag --points-at HEAD` semantics inside collectRepoState): the
+    // release tag names the exact evidence commit, so any non-HEAD comparison
+    // would certify code the tag never covered.
+    const checkout = exists(path.join(PKG_ROOT, '.git')) ? collectRepoState(PKG_ROOT) : null;
+    const sourceDecision = deploySourceDecision({ checkout, allowUntagged: ALLOW_UNTAGGED });
+    const checkoutLabel = `v${VERSION}, branch ${checkout?.branch || '(detached)'}, head ${checkout?.headShort || '?'}`;
+    if (sourceDecision.action === 'refuse') {
+        releaseInstallLockSync(installLock);
+        console.error(`✗ refusing to deploy an UNRELEASED source checkout machine-globally: ${checkoutLabel} — no release tag v${VERSION} at HEAD; no files were changed.`);
+        console.error('  Released installs come from the registry: npx -y klypix-mcp@latest install');
+        console.error('  To deliberately deploy this working tree (a dev deploy), acknowledge it: re-run with --allow-untagged or KLYPIX_MCP_ALLOW_UNTAGGED=1.');
+        console.error('  An acknowledged dev deploy is stamped dev-owned, so brain_doctor shows it and auto-update will not silently replace it.');
+        process.exit(1);
+    }
+    const untaggedSource = sourceDecision.source === 'untagged-working-tree';
+    // Deploy-time snapshot for ANY git-checkout deploy (tagged or acknowledged-
+    // untagged): the release tag certifies HEAD's bytes, not the working
+    // tree's, so uncommitted changes make even a TAGGED deploy differ from
+    // what was released — a clean `dirty:false` stamp would lie about exactly
+    // that (the receipt-honesty defect this wave exists to kill). An
+    // unreadable status degrades to false rather than inventing a DIRTY nag
+    // in every session brief. Tarball installs (checkout null) skip the spawn.
+    const sourceDirty = Boolean(checkout) && (() => {
+        try {
+            return execFileSync('git', ['status', '--porcelain'], {
+                cwd: PKG_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 1500,
+            }).trim().length > 0;
+        } catch { return false; }
+    })();
+    if (untaggedSource) {
+        console.log(`• untagged source deploy acknowledged: ${checkoutLabel}${sourceDirty ? ' (working tree DIRTY)' : ''} — receipts record a dev-owned install; a later released install needs --force.`);
+    } else if (sourceDirty) {
+        console.log(`⚠ release-tagged checkout has uncommitted changes (${checkoutLabel}) — deployed bytes differ from the release; stamping dirty:true so brain_doctor surfaces it.`);
+    }
+
     fs.mkdirSync(BRAIN_DIR, { recursive: true });
     // 1) runtime dependency CLOSURE (jszip+fractional-indexing for the hook/engine,
     //    @modelcontextprotocol/sdk+zod for the local MCP server). Resolve each via
@@ -281,7 +335,7 @@ try {
     // canvas-view-app.html is the canvas_view MCP App UI — staged raw (an HTML
     // file must never get a JS-comment banner) beside the flat server, which
     // resolves it via its ./canvas-view-app.html candidate path.
-    for (const f of ['global-brain-hook.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'brain-graveyard.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'remote-client.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
+    for (const f of ['global-brain-hook.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'brain-graveyard.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'repo-state.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'remote-client.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
         const s = path.join(SRC, f); if (exists(s)) staged.push({ dst: f, content: fs.readFileSync(s, 'utf8') });
     }
     for (const [src, dst] of [
@@ -344,19 +398,38 @@ try {
     // a crash between receipts remains recoverable because the next installer
     // compares both and keeps the highest valid Brain Core version.
     const installedAt = new Date().toISOString();
+    // Receipt honesty (2026-08-14): an acknowledged untagged source deploy is
+    // a DEV delivery — stamping it 'npm'/dirty:false made unreleased code
+    // byte-for-byte indistinguishable from a released install. 'dev' is
+    // existing receipt vocabulary (brainInstallDecision's dev-owned preserve,
+    // auto-update's dev skip, doctor's channel/dev/dirty rendering all consume
+    // it); sourceSha/branch are additive fields for post-hoc audit. dev:true
+    // goes in BOTH receipts because the runtime receipt commits first — a
+    // crash between the two writes must not leave a dev deploy unmarked.
     const runtime = {
         protocol: 1,
         version: VERSION,
         worker: 'klypix-mcp-worker.mjs',
-        channel: 'npm',
+        channel: untaggedSource ? 'dev' : 'npm',
+        ...(untaggedSource ? { dev: true, sourceSha: checkout?.headShort || null, branch: checkout?.branch || null } : {}),
         installedAt,
         files: Object.fromEntries(staged.map(st => [st.dst, crypto.createHash('sha256').update(st.content).digest('hex')])),
     };
     const runtimePath = path.join(BRAIN_DIR, '.mcp-runtime.json');
     fs.writeFileSync(runtimePath + '.klypix-new', JSON.stringify(runtime, null, 2) + '\n', 'utf8');
     fs.renameSync(runtimePath + '.klypix-new', runtimePath);
+    // A tagged-but-DIRTY checkout keeps via:'npm' (the tag still names the
+    // payload identity, and dev:true would stop auto-update from healing the
+    // machine back to clean released bytes) but stamps dirty:true + the audit
+    // fields — doctor's DIRTY line and the hook's dirty nag both read the
+    // stamp. The clean released path stays byte-identical to pre-guard.
+    const versionStamp = untaggedSource
+        ? { brainVersion: VERSION, via: 'dev', dev: true, dirty: sourceDirty, sourceSha: checkout?.headShort || null, branch: checkout?.branch || null, installedAt }
+        : sourceDirty
+            ? { brainVersion: VERSION, via: 'npm', dirty: true, sourceSha: checkout?.headShort || null, branch: checkout?.branch || null, installedAt }
+            : { brainVersion: VERSION, via: 'npm', dirty: false, installedAt };
     const versionPath = path.join(BRAIN_DIR, '.brain-version.json');
-    fs.writeFileSync(versionPath + '.klypix-new', JSON.stringify({ brainVersion: VERSION, via: 'npm', dirty: false, installedAt }, null, 2), 'utf8');
+    fs.writeFileSync(versionPath + '.klypix-new', JSON.stringify(versionStamp, null, 2), 'utf8');
     fs.renameSync(versionPath + '.klypix-new', versionPath);
 
     // 7) migrate THIS project's .mcp.json off npx onto the now-installed local bundle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.67.2",
+  "version": "1.69.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/repo-state.mjs && node test/released-tag-guard.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/presence-liveness.mjs && node test/completion-guard.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

@@ -49,6 +49,53 @@ export const MACHINE_ID = (() => {
   catch { return sha16(`${os.hostname?.() || 'unknown'}|${os.platform?.() || 'unknown'}`); }
 })();
 
+// ── Dead-host sweep (2026-08-14 wave) ────────────────────────────────────────
+// TTL pruning alone leaves a crashed host's rows visible for up to 10 minutes —
+// long enough for a peer to "coordinate" with a ghost. When any session touches
+// the lane, rows whose HOST process is provably dead are swept immediately.
+// The probe is deliberately narrow, because a false sweep erases live presence:
+//   · only rows written on THIS machine (row.machine === MACHINE_ID; a pid from
+//     another machine or a cloud-relayed row lives in a foreign pid namespace),
+//   · only rows whose hostPid came from a host-declared env var
+//     (hostPidSource === 'env'). A ppid-guessed pid may be a short-lived shell
+//     wrapper — probing it would sweep a perfectly live session — so guessed
+//     pids are used for row correlation only, never for liveness,
+//   · only rows older than a grace window, so a row written moments ago by a
+//     process racing its own exit cannot flap.
+// Anything the probe cannot decide falls back to the TTL rule — the sweep can
+// only ever REMOVE provably-dead rows earlier, never keep rows longer.
+// The grace deliberately EXCEEDS the MCP heartbeat interval (60s in
+// mcp-presence.mjs — not imported here because that module imports this one):
+// a session that is still writing heartbeats keeps its row's age under the
+// grace, so even a WRONGLY-declared host pid (say, a stale KLYPIX_HOST_PID
+// leaked from a shell profile) can never sweep a session that is actively
+// alive. Only silent rows — the crash shape the sweep exists for — get probed.
+export const DEAD_HOST_GRACE_MS = 90 * 1000;
+
+// kill(pid, 0) is the portable liveness probe (works on Windows via
+// OpenProcess). ESRCH ⇒ no such process; EPERM/EACCES ⇒ exists but owned by
+// someone else ⇒ alive. Anything else — invalid input or an error code this
+// table doesn't know — returns null ("cannot say"), NEVER false: an unproven
+// death must fall back to TTL, because a false "dead" erases live presence.
+export function isProcessAlive(pid) {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 0) return null;
+  try { process.kill(n, 0); return true; }
+  catch (err) {
+    if (err?.code === 'ESRCH') return false;
+    if (err?.code === 'EPERM' || err?.code === 'EACCES') return true;
+    return null;
+  }
+}
+
+export function isDeadHostRow(session, now = Date.now(), probe = isProcessAlive) {
+  if (!session || session.via === 'cloud') return false;
+  if (String(session.hostPidSource || '') !== 'env') return false;
+  if (!session.machine || String(session.machine) !== String(MACHINE_ID)) return false;
+  if (now - Number(session.lastSeen || 0) < DEAD_HOST_GRACE_MS) return false;
+  return probe(session.hostPid) === false;
+}
+
 // A lane write can legitimately FAIL: the lock is held and we give up rather than
 // clobber a peer's just-posted message. That path returned listActiveSessions(),
 // i.e. the exact same shape as a success — so a dropped heartbeat was
@@ -405,6 +452,9 @@ function pruneSessions(sessions, now) {
   const out = [];
   for (const session of (Array.isArray(sessions) ? sessions : [])) {
     if (!session?.id) continue;
+    // Dead-host sweep: a row whose host process is provably gone is removed on
+    // the next lane touch instead of lingering for the full TTL window.
+    if (isDeadHostRow(session, now)) continue;
     const hadChannels = session.channelSeen
       && typeof session.channelSeen === 'object'
       && !Array.isArray(session.channelSeen)
@@ -454,6 +504,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 +536,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 +585,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 +616,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;
 }
 
@@ -667,6 +741,7 @@ export function upsertSession({
   transportStatus = null,
   cwd = null,
   hostPid = null,
+  hostPidSource = null,
   logicalSessionId = null,
   identitySource = null,
   aliases,
@@ -758,6 +833,16 @@ export function upsertSession({
       // Host-process correlation is diagnostic topology only. A desktop parent
       // can own many chats, so hostPid must never imply identity or deduping.
       hostPid: Number(hostPid) || previous.hostPid || null,
+      // Provenance of the pid decides what it may be used for: 'env' (declared
+      // by the host itself, safe to liveness-probe) vs 'ppid' (a best-effort
+      // parent guess, correlation only). ADDITIVE — absent means unknown, and
+      // unknown is never probed. Kept aligned with the pid it describes: a new
+      // pid without a declared source resets the field rather than inheriting
+      // the previous pid's provenance.
+      hostPidSource: Number(hostPid)
+        ? (hostPidSource ? String(hostPidSource).slice(0, 16)
+          : (Number(hostPid) === Number(previous.hostPid) ? previous.hostPidSource || null : null))
+        : previous.hostPidSource || null,
       logicalSessionId: recipientKey(logicalSessionId || previous.logicalSessionId || '') || null,
       identitySource: String(identitySource || previous.identitySource || 'provisional').slice(0, 80),
       aliases: normalizeAliases(aliases === undefined ? previous.aliases : [...(previous.aliases || []), ...(aliases || [])], id),
@@ -1019,8 +1104,15 @@ export function endSession({ brainPath, id, home, now = Date.now(), expectedPid
     endedSessions.push({ id: recipientKey(row?.logicalSessionId || row?.id || id), endedAt: now,
       aliases: normalizeAliases(identities, row?.logicalSessionId || row?.id || id) });
     endedSessions = endedSessions.slice(-ENDED_SESSION_CAP);
+    // The sweep also removes transport twins that never completed id adoption:
+    // an mcp-<pid> row whose logicalSessionId names the ended identity IS this
+    // session and must not linger until its own TTL. Rotation stays safe — a
+    // NEW conversation created after SessionEnd(A) carries its OWN id as
+    // logicalSessionId (rotateEndedSessionIdentity sets logicalSessionId=toKey
+    // and never aliases A), so it can never match A's identity set here.
     const kept = sessions.filter((session) => !identities.includes(recipientKey(session.id))
-      && !normalizeAliases(session.aliases).some((alias) => identities.includes(alias)));
+      && !normalizeAliases(session.aliases).some((alias) => identities.includes(alias))
+      && !(session.logicalSessionId && identities.includes(recipientKey(session.logicalSessionId))));
     fs.mkdirSync(path.dirname(laneFile), { recursive: true });
     writeLaneFileAtomic(laneFile, JSON.stringify({
       ...data,
@@ -1047,6 +1139,7 @@ export function rotateEndedSessionIdentity({
   surface = 'mcp',
   cwd = null,
   hostPid = null,
+  hostPidSource = null,
   identitySource = 'mcp-request',
   home,
   now = Date.now(),
@@ -1105,6 +1198,8 @@ export function rotateEndedSessionIdentity({
       deliveryReachability: sessionDeliveryReachability({ channels: Object.keys(channelSeen), transport }),
       cwd: cwd ? path.resolve(cwd) : (existing?.cwd || path.dirname(brainPath)),
       hostPid: Number(hostPid) || existing?.hostPid || null,
+      hostPidSource: (Number(hostPid) && hostPidSource) ? String(hostPidSource).slice(0, 16)
+        : existing?.hostPidSource || null,
       logicalSessionId: toKey,
       identitySource: String(identitySource || 'mcp-request').slice(0, 80),
       // Never attach A as an alias: targeting A after its close must continue
@@ -1148,6 +1243,7 @@ export function switchMcpSessionIdentity({
   surface = 'mcp',
   cwd = null,
   hostPid = null,
+  hostPidSource = null,
   identitySource = 'mcp-request',
   home,
   now = Date.now(),
@@ -1246,6 +1342,8 @@ export function switchMcpSessionIdentity({
       deliveryReachability: sessionDeliveryReachability({ channels: Object.keys(channelSeen), transport }),
       cwd: cwd ? path.resolve(cwd) : (existing?.cwd || path.dirname(brainPath)),
       hostPid: Number(hostPid) || existing?.hostPid || null,
+      hostPidSource: (Number(hostPid) && hostPidSource) ? String(hostPidSource).slice(0, 16)
+        : existing?.hostPidSource || null,
       logicalSessionId: toKey,
       identitySource: String(identitySource || 'mcp-request').slice(0, 80),
       // Even a stale/pre-fix B row must not retain A as a targeting alias.
@@ -1537,9 +1635,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 +1679,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 +1810,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 +1833,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 }));
@@ -1832,39 +1969,127 @@ const clientLabel = (session) => {
   return client.replace(/(^|[-_ ])([a-z])/g, (_m, prefix, letter) => `${prefix}${letter.toUpperCase()}`);
 };
 
+// 'mcp'/'unknown' are placeholders (getClientVersion() is optional) — only a
+// concretely known client name may VETO a fold; a placeholder stays compatible.
+const specificClient = (client) => {
+  const value = String(client || '').toLowerCase();
+  return value && value !== 'mcp' && value !== 'unknown' ? value : null;
+};
+
+// Group live lane rows into LOGICAL sessions for rendering. One conversation
+// can hold multiple transport rows when id adoption failed mid-flight (the
+// lifecycle id plus an mcp-<pid> provisional). Rendering each row as its own
+// session double-counts peers, so the footer merges — but merge order matters:
+//   1. exact logical identity (logicalSessionId || id) — always safe;
+//   2. pid-assisted fold, ONLY for an mcp-only row with no logical identity
+//      that shares machine + hostPid + a compatible client with EXACTLY ONE
+//      identity-anchored session. Codex runs many threads below one desktop
+//      pid, so any ambiguity fails open as separate sessions (hiding a real
+//      peer is worse than showing a twin twice — 2026-07-30 hardening).
+// This is a RENDER grouping only: lane rows, identity, message audiences and
+// conflict detection are untouched.
+export function mergePresenceRows(sessions) {
+  const rows = (Array.isArray(sessions) ? sessions : []).filter((row) => row?.id);
+  const keyOf = (row) => (recipientKey(row.logicalSessionId) || recipientKey(row.id)).toLowerCase();
+  const groups = new Map();
+  for (const row of rows) {
+    const key = keyOf(row);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(row);
+  }
+  const isAnchored = (group) => group.some((row) => recipientKey(row.logicalSessionId)
+    || (Array.isArray(row.channels) && row.channels.includes('lifecycle')));
+  const isFoldableOrphan = (group) => group.length === 1
+    && group.every((row) => !recipientKey(row.logicalSessionId)
+      && row.via !== 'cloud'
+      && Number(row.hostPid) > 0
+      && row.machine
+      && Array.isArray(row.channels) && row.channels.length
+      && row.channels.every((channel) => channel === 'mcp'));
+  const anchoredKeys = [...groups.keys()].filter((key) => isAnchored(groups.get(key)));
+  for (const [key, group] of [...groups.entries()]) {
+    if (!isFoldableOrphan(group)) continue;
+    const orphan = group[0];
+    const candidates = anchoredKeys.filter((anchorKey) => groups.get(anchorKey)?.some((row) => row.machine
+      && String(row.machine) === String(orphan.machine)
+      && Number(row.hostPid) === Number(orphan.hostPid)
+      && (!specificClient(row.client) || !specificClient(orphan.client)
+        || specificClient(row.client) === specificClient(orphan.client))));
+    if (candidates.length !== 1) continue;   // ambiguous or none → fail open
+    groups.get(candidates[0]).push(orphan);
+    groups.delete(key);
+  }
+  return [...groups.values()].map((groupRows) => {
+    const primary = groupRows.find((row) => Array.isArray(row.channels) && row.channels.includes('lifecycle'))
+      || groupRows.find((row) => recipientKey(row.logicalSessionId))
+      || [...groupRows].sort((a, b) => Number(b.lastSeen || 0) - Number(a.lastSeen || 0))[0];
+    // The freshest declared intent wins across the group's rows — a brain_sync
+    // scope declared on the mcp twin must not vanish behind a silent lifecycle
+    // row (the twin's channels/scope count TOWARD the session, never hidden).
+    const intentRow = [...groupRows]
+      .filter((row) => String(row.intent || '').trim())
+      .sort((a, b) => Number(b.intentAt || b.lastSeen || 0) - Number(a.intentAt || a.lastSeen || 0))[0] || primary;
+    return {
+      primary,
+      rows: groupRows,
+      channels: [...new Set(groupRows.flatMap((row) => Array.isArray(row.channels) ? row.channels : []))],
+      lastSeen: Math.max(...groupRows.map((row) => Number(row.lastSeen || 0)), 0),
+      intent: String(intentRow.intent || ''),
+      intentAt: intentRow.intentAt || null,
+      branch: primary.branch || groupRows.map((row) => row.branch).find(Boolean) || null,
+    };
+  });
+}
+
 export function formatPresenceMessage(sessions, selfId, { includeSolo = false, now = Date.now() } = {}) {
   const active = Array.isArray(sessions) ? sessions : [];
-  const others = active.filter((session) => session.id !== selfId);
+  const merged = mergePresenceRows(active);
+  const selfKey = recipientKey(selfId);
+  const isSelfGroup = (group) => group.rows.some((row) => recipientKey(row.id) === selfKey
+    || recipientKey(row.logicalSessionId) === selfKey
+    || normalizeAliases(row.aliases).includes(selfKey));
+  const others = merged.filter((group) => !isSelfGroup(group));
   if (!includeSolo && !others.length) return '';
 
   const counts = new Map();
-  for (const session of active) {
-    const label = clientLabel(session);
+  for (const group of merged) {
+    const label = clientLabel(group.primary);
     counts.set(label, (counts.get(label) || 0) + 1);
   }
   const mix = [...counts.entries()].map(([label, count]) => `${label} ${count}`).join(', ');
+  // When transports outnumber logical sessions, say so — folding a twin must
+  // never silently understate how many live connections the lane holds.
+  const connectionNote = active.length > merged.length
+    ? `; ${active.length} connections` : '';
   const lines = [
-    `KLYPIX session awareness: ${active.length} active session${active.length === 1 ? '' : 's'} on this project (${mix || 'none'}); ${others.length} other${others.length === 1 ? '' : 's'} besides this chat.`,
+    `KLYPIX session awareness: ${merged.length} active session${merged.length === 1 ? '' : 's'} on this project (${mix || 'none'}${connectionNote}); ${others.length} other${others.length === 1 ? '' : 's'} besides this chat.`,
   ];
   if (!others.length) {
     lines.push('Saved/recent chat rows are history, not active sessions; a session counts only while an authorized MCP connection or lifecycle adapter has heartbeated in the last 10 minutes.');
     return lines.join('\n');
   }
   lines.push('Other active sessions:');
-  for (const session of others.slice(0, 8)) {
-    const ageMin = Math.max(0, Math.round((now - Number(session.lastSeen || now)) / 60_000));
+  // Uniqueness is computed over the merged primaries: UUIDv7 ids started in the
+  // same window share a long time prefix, so each shown prefix grows (git
+  // short-hash style, floor 8) until it names exactly one session.
+  const prefixRows = merged.map((group) => group.primary);
+  for (const group of others.slice(0, 8)) {
+    const session = group.primary;
+    const ageMin = Math.max(0, Math.round((now - Number(group.lastSeen || now)) / 60_000));
     // A heartbeat refreshes lastSeen while carrying an old intent forward — show
     // the INTENT's own age when it meaningfully lags the heartbeat, so a
     // 100-minute-old task line can never read as "what they're doing right now".
-    const intentAgeMin = session.intentAt ? Math.max(0, Math.round((now - Number(session.intentAt)) / 60_000)) : null;
+    const intentAgeMin = group.intentAt ? Math.max(0, Math.round((now - Number(group.intentAt)) / 60_000)) : null;
     const intentAge = intentAgeMin !== null && intentAgeMin - ageMin > 3 ? ` (intent set ${intentAgeMin}m ago)` : '';
     const details = [
       clientLabel(session),
-      session.branch ? `branch ${session.branch}` : null,
-      session.intent ? `"${String(session.intent).slice(0, 90)}"${intentAge}` : null,
+      group.rows.length > 1 ? `${group.rows.length} connections` : null,
+      group.branch ? `branch ${group.branch}` : null,
+      group.intent ? `"${String(group.intent).slice(0, 90)}"${intentAge}` : null,
       `${ageMin}m ago`,
     ].filter(Boolean);
-    lines.push(`- ${String(session.id).slice(0, 8)}: ${details.join(' | ')}`);
+    const shortId = shortestUniqueSessionPrefix(prefixRows, session.id) || String(session.id).slice(0, 8);
+    lines.push(`- ${shortId}: ${details.join(' | ')}`);
   }
   // v1.32.0 law: a truncated list must never render as a complete one.
   if (others.length > 8) lines.push(`- …and ${others.length - 8} more live session(s) not listed — brain_doctor shows all.`);