klypix-mcp 1.68.0 → 1.69.0

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.68.0",
+  "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/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": "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)
@@ -691,6 +741,7 @@ export function upsertSession({
   transportStatus = null,
   cwd = null,
   hostPid = null,
+  hostPidSource = null,
   logicalSessionId = null,
   identitySource = null,
   aliases,
@@ -782,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),
@@ -1043,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,
@@ -1071,6 +1139,7 @@ export function rotateEndedSessionIdentity({
   surface = 'mcp',
   cwd = null,
   hostPid = null,
+  hostPidSource = null,
   identitySource = 'mcp-request',
   home,
   now = Date.now(),
@@ -1129,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
@@ -1172,6 +1243,7 @@ export function switchMcpSessionIdentity({
   surface = 'mcp',
   cwd = null,
   hostPid = null,
+  hostPidSource = null,
   identitySource = 'mcp-request',
   home,
   now = Date.now(),
@@ -1270,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.
@@ -1895,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.`);

package/src/brain-doctor.mjs

@@ -43,6 +43,19 @@ let gitCaptureLib = null;
 try { gitCaptureLib = await import('./git-capture-install.mjs'); } catch { gitCaptureLib = null; }
 let historyLib = null;
 try { historyLib = await import('./brain-history.mjs'); } catch { historyLib = null; }
+// repo-state powers the advisory CHECKOUT line (released-tag visibility). Same
+// failure-tolerant idiom: a half-updated flat bundle that predates the module
+// must degrade to omitting the line, never kill the doctor.
+let repoStateLib = null;
+try { repoStateLib = await import('./repo-state.mjs'); } catch { repoStateLib = null; }
+// agent-presence is the CANONICAL owner of the session-liveness rule (freshness
+// windows + dead-host sweep). The doctor deliberately keeps reading lane files
+// directly so it can diagnose a broken bundle, so this import is failure-
+// tolerant too: on a bundle without it, the local fallback literals below keep
+// the doctor alive — but a healthy bundle can no longer drift from the engine
+// (the exact drift that once produced three different live-session counts).
+let presenceLib = null;
+try { presenceLib = await import('./agent-presence.mjs'); } catch { presenceLib = null; }
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -56,7 +69,12 @@ const cmpSemver = (a, b) => { const pa = String(a || '').split('.').map(n => par
 
 const HOOK_MARK = 'global-brain-hook';
 const HOOK_EVENTS = ['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse'];
-const SESSION_FRESH_MS = 10 * 60 * 1000;   // matches the hook's lane-freshness window
+// Liveness windows imported from the canonical rule; literals are the LAST
+// RESORT for a bundle whose agent-presence predates the exports.
+const SESSION_FRESH_MS = Number(presenceLib?.SESSION_FRESH_MS) > 0
+  ? Number(presenceLib.SESSION_FRESH_MS) : 10 * 60 * 1000;
+const MCP_SESSION_FRESH_MS = Number(presenceLib?.MCP_SESSION_FRESH_MS) > 0
+  ? Number(presenceLib.MCP_SESSION_FRESH_MS) : 3 * 60 * 1000;
 
 // ── VERSION layer ────────────────────────────────────────────────────────────
 function inspectVersion(brainDir) {
@@ -256,8 +274,11 @@ function inspectSupervisors(brainDir, baked) {
 // Channel-aware liveness, mirroring agent-presence.mjs: an mcp-channel heartbeat
 // is dead after 3 minutes even though the flat 10-minute window keeps the row —
 // without this the hook, brain_sync, and doctor reported three different counts.
-const MCP_SESSION_FRESH_MS = 3 * 60 * 1000;
+// (Both windows are now imported from agent-presence at the top of this file.)
 const sessionLiveness = (s, now) => {
+  // Dead-host parity: a row every WRITER would sweep on its next lane touch
+  // must not render as live here. Guarded — an old bundle simply skips it.
+  if (typeof presenceLib?.isDeadHostRow === 'function' && presenceLib.isDeadHostRow(s, now)) return null;
   const channelSeen = (s?.channelSeen && typeof s.channelSeen === 'object' && !Array.isArray(s.channelSeen)) ? s.channelSeen : null;
   if (channelSeen && Object.keys(channelSeen).length) {
     const fresh = Object.entries(channelSeen)
@@ -468,6 +489,31 @@ export function inspect(opts = {}) {
     } catch { history = { available: true, count: 0, newestAt: null }; }
   }
   const tools = inspectTools(brainDir, PKG_ROOT);
+  // ── CHECKOUT (release-state visibility, 2026-08-14 incident) ──────────────
+  // Advisory, never a verdict layer: when the PROJECT itself is a versioned
+  // source checkout, report mechanically whether HEAD carries its own release
+  // tag — the 1.3.107 release shipped from an off-trunk branch because no
+  // surface made branch/release state visible at the moment of action, and
+  // doctor is the one client-neutral surface every agent can query. Only set
+  // when a git identity AND a package version exist (release state is
+  // meaningless without a version to be released); any probe failure omits
+  // the block. collectRepoState is bounded + 60s-cached, so this adds no
+  // meaningful cost to a doctor run.
+  let checkout = null;
+  if (repoStateLib && typeof repoStateLib.collectRepoState === 'function') {
+    try {
+      const state = repoStateLib.collectRepoState(projectDir);
+      if (state && state.packageVersion) {
+        checkout = {
+          branch: state.branch,
+          headShort: state.headShort,
+          version: state.packageVersion,
+          tagsAtHead: state.tagsAtHead,
+          releaseState: state.isReleaseTag ? 'released-tag' : 'untagged-working-tree',
+        };
+      }
+    } catch { checkout = null; }
+  }
   const env = opts.env || process.env;
   // MCP passes the adopted live id explicitly. The CLI can inherit a host id,
   // but never invents one: a guessed sender would display somebody else's note.
@@ -553,7 +599,10 @@ export function inspect(opts = {}) {
   const actions = [];
   if (!version.installed) actions.push('npx klypix-mcp install   # no brain installed on this machine');
   else {
-    if (version.dirty) actions.push('node scripts/deploy-brain.mjs   # running uncommitted (dirty) hook code — commit + re-deploy');
+    // The old remediation here named scripts/deploy-brain.mjs — a script that
+    // does not exist in the published package, so the one string every client
+    // renders verbatim was unrunnable. Point at commands that actually run.
+    if (version.dirty) actions.push('npx klypix-mcp install --force   # running uncommitted (dirty) source code — restore the released npm version, or commit and re-deploy deliberately with --allow-untagged');
     if (npm && npm.matches === false) actions.push(`npx klypix-mcp install   # installed brain v${version.baked} < npm latest v${npm.latest}`);
     if (running.matchesInstalled === false) actions.push(`/mcp reconnect (or restart the session)   # LIVE server v${running.version} ≠ installed v${version.baked} — the running MCP server is stale`);
     if (version.supervisorCapable && running.known && !supervisors.active) actions.push('/mcp reconnect once   # activate the zero-restart supervisor; compatible future core updates hot-swap automatically');
@@ -576,7 +625,9 @@ export function inspect(opts = {}) {
     }
   }
 
-  return { verdict, layers, drifted, readinessWarnings, version, running, supervisors, autoUpdate, hooks, codexSmart, codexHooks, gitCapture, history, tools, peers, sessions: peers, receipts: peers.receipts, receiptSessionId, harness, npm, decayGuard, project: { dir: projectDir, brainPath, hasBrain }, brainDir, actions };
+  // `checkout` is additive (schema-stable): downstream renderers keep parsing
+  // every existing field; it never feeds layers/verdict/actions by design.
+  return { verdict, layers, drifted, readinessWarnings, version, running, supervisors, autoUpdate, hooks, codexSmart, codexHooks, gitCapture, history, tools, peers, sessions: peers, receipts: peers.receipts, receiptSessionId, harness, npm, decayGuard, checkout, project: { dir: projectDir, brainPath, hasBrain }, brainDir, actions };
 }
 
 // One-line drift summary (empty when clean) — for a footer / status line.
@@ -723,6 +774,17 @@ export function render(r, opts = {}) {
             : `${c.dim}${gc.state} — installs automatically at the next session start${c.rst}`;
     L.push(`${gmark} ${c.bold}GIT-CAP${c.rst}  ${detail}`);
   }
+  // CHECKOUT — release state of the project's own source tree. Advisory only
+  // (never a verdict layer): its job is to make branch + released-tag truth
+  // visible at the moment of action, not to fail anything.
+  if (r.checkout) {
+    const where = `${r.checkout.branch ? `branch ${r.checkout.branch}` : 'detached HEAD'}, head ${r.checkout.headShort || '?'}`;
+    if (r.checkout.releaseState === 'released-tag') {
+      L.push(`${ok} ${c.bold}CHECKOUT${c.rst} source checkout at its release tag: v${r.checkout.version} (${where})`);
+    } else {
+      L.push(`${warn}${c.bold}CHECKOUT${c.rst} untagged working tree — v${r.checkout.version} has no release tag at HEAD (${c.yel}${where}${c.rst}) ${c.dim}· a build/release from here ships unreleased code (advisory)${c.rst}`);
+    }
+  }
   // Restore points — say the count and the age, because "you can undo an
   // accidental delete" is only believable if the machine can show the receipts.
   if (r.history?.available) {