klypix-mcp 1.40.2 → 1.42.0

package/bin/klypix-conformance.mjs

@@ -57,6 +57,15 @@ fs.writeFileSync(path.join(vault, 'brain.klypix'), await buildKlypixMap({
 const baseEnv = Object.fromEntries(
   Object.entries(process.env).filter(([, value]) => typeof value === 'string'),
 );
+// The harness simulates two INDEPENDENT hosts. When it itself runs inside an
+// agent session (Claude Code exports CLAUDE_PID + CLAUDE_CODE_SESSION_ID to
+// children), both simulated clients would inherit the SAME host identity and
+// be correctly treated as one session's twin halves — failing every two-client
+// check. Strip host/session identity; each client gets its own KLYPIX_SESSION_ID.
+for (const key of [
+  'CLAUDE_PID', 'KLYPIX_HOST_PID', 'CLAUDE_CODE_SESSION_ID', 'CLAUDE_SESSION_ID',
+  'CODEX_THREAD_ID', 'CURSOR_SESSION_ID', 'CLINE_SESSION_ID', 'WINDSURF_SESSION_ID',
+]) delete baseEnv[key];
 
 async function connect(name, sessionId) {
   const logs = [];

package/bin/klypix-worker.mjs

@@ -33,6 +33,10 @@ import {
 import { mcpServerEntry } from '../src/agent-rules.mjs';
 import { createMcpPresence, KLYPIX_MCP_INSTRUCTIONS } from '../src/mcp-presence.mjs';
 import { spawnAutoUpdateHelper } from '../src/mcp-auto-update.mjs';
+// Namespace import (already in-process via the klypix-core chain, so zero added
+// load cost) so a bundle whose klypix-format predates classifyDecay degrades
+// gracefully — a named import of a missing export would kill the whole server.
+import * as brainFormat from '../src/klypix-format.mjs';
 
 // Real package version for the MCP handshake (was hardcoded '1.0.0', which
 // misled every client/version diagnosis — it could never reflect the true release).
@@ -118,7 +122,21 @@ const server = new McpServer(
     capabilities: { logging: {} },
   },
 );
-const mcpPresence = createMcpPresence({ server, initialVault: VAULT });
+// Decay-aware LAST-KNOWN stamps for every MCP delivery surface (2026-07-28
+// post-mortem, class B): the classifier lives ONCE in klypix-format.mjs and is
+// INJECTED here so mcp-presence/agent-presence stay builtin-only. The typeof
+// guards let a bundle predating the feature degrade to unstamped delivery —
+// no crash, no stamp, never a throw.
+const mcpPresence = createMcpPresence({
+  server,
+  initialVault: VAULT,
+  decay: typeof brainFormat.classifyDecay === 'function' ? {
+    classifyDecay: brainFormat.classifyDecay,
+    decayStaleMs: brainFormat.DECAY_STALE_MS,
+    decayMessageStamp: typeof brainFormat.decayMessageStamp === 'function' ? brainFormat.decayMessageStamp : undefined,
+    formatDecayAge: typeof brainFormat.formatDecayAge === 'function' ? brainFormat.formatDecayAge : undefined,
+  } : {},
+});
 
 // Map a protocol-neutral core result → an MCP tool result.
 const toContent = (r) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "klypix-mcp",
-  "version": "1.40.2",
-  "description": "Every project gets a brain — one open .klypix file your AI agents read, write, and argue from, over MCP. Works with Claude, Codex, Cursor, Cline, any model.",
+  "version": "1.42.0",
+  "description": "Every project gets a brain — one open .klypix file your AI agents read, write, and argue from, over MCP. Works with Claude, Codex, Cursor, Cline, any model.",
   "type": "module",
   "license": "Apache-2.0",
   "keywords": [
@@ -58,7 +58,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/codex-hooks.mjs && node test/agent-presence.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/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/canvas-view.mjs && node test/status-completeness.mjs"
+    "test": "node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/codex-hooks.mjs && node test/agent-presence.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/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/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-gate.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/presence-visibility.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.4",

package/src/agent-presence.mjs

@@ -113,6 +113,29 @@ function pruneMessages(messages, now) {
     .filter((message) => message?.id && now - Number(message.ts || 0) < MESSAGE_FRESH_MS);
 }
 
+// Cap the message lane WITHOUT silently destroying undelivered notes: the old
+// flat `.slice(-30)` evicted the OLDEST rows first regardless of delivery, so a
+// burst of >30 messages could destroy a note nobody had seen yet. Evict
+// delivered (seen-by-someone) messages first, oldest first; only then the
+// oldest undelivered ones. Order of survivors is preserved.
+export function capMessages(messages, cap = 30) {
+  const list = Array.isArray(messages) ? messages : [];
+  if (list.length <= cap) return list;
+  let excess = list.length - cap;
+  const dropped = new Set();
+  const evict = (predicate) => {
+    for (const message of list) {
+      if (!excess) return;
+      if (dropped.has(message) || !predicate(message)) continue;
+      dropped.add(message);
+      excess--;
+    }
+  };
+  evict((m) => Array.isArray(m?.seen) && m.seen.length > 0);   // delivered at least once
+  evict(() => true);                                            // still over cap → oldest of the rest
+  return list.filter((message) => !dropped.has(message));
+}
+
 function normalizeFiles(files) {
   const seen = new Set();
   const out = [];
@@ -140,11 +163,13 @@ export function upsertSession({
   permissionMode = null,
   branch = null,
   intent,
+  intentSource = null,
   files,
   replaceFiles = false,
   event = null,
   channel = null,
   cwd = null,
+  hostPid = null,
   home,
   now = Date.now(),
 }) {
@@ -162,6 +187,14 @@ export function upsertSession({
     const mergedFiles = files === undefined
       ? normalizeFiles(previous.files)
       : normalizeFiles(replaceFiles ? files : [...(previous.files || []), ...(files || [])]);
+    // Intent freshness is its OWN timestamp: lastSeen is refreshed by heartbeats
+    // that never touch intent, so without intentAt a 100-minute-old intent renders
+    // under "active just now" (2026-07-29 audit). Stamped only when the intent
+    // VALUE actually changes; additive — old rows/readers are unaffected.
+    const nextIntent = intent !== undefined
+      ? String(intent || '').replace(/\s+/g, ' ').trim().slice(0, 160)
+      : (previous.intent || '');
+    const intentChanged = intent !== undefined && nextIntent !== (previous.intent || '');
     const next = {
       ...previous,
       id: String(id),
@@ -172,13 +205,19 @@ export function upsertSession({
       model: model ?? previous.model ?? null,
       permissionMode: permissionMode ?? previous.permissionMode ?? null,
       branch: branch ?? previous.branch ?? null,
-      intent: intent !== undefined ? String(intent || '').replace(/\s+/g, ' ').trim().slice(0, 160) : (previous.intent || ''),
+      intent: nextIntent,
+      ...(intentChanged ? { intentAt: now, intentSource: intentSource || 'declared' }
+        : (previous.intentAt ? { intentAt: previous.intentAt, intentSource: previous.intentSource || null } : {})),
       files: mergedFiles,
       event: event ?? previous.event ?? null,
       ...(Object.keys(channelSeen).length
         ? { channels: Object.keys(channelSeen), channelSeen }
         : {}),
       cwd: cwd ? path.resolve(cwd) : (previous.cwd || path.dirname(brainPath)),
+      // Host-process correlation (e.g. Claude Code exports CLAUDE_PID to every
+      // child): lets readers recognize one logical session's lifecycle row and
+      // MCP row as TWINS instead of two independent peers.
+      hostPid: Number(hostPid) || previous.hostPid || null,
       startedAt: previous.startedAt || now,
       lastSeen: now,
     };
@@ -188,7 +227,7 @@ export function upsertSession({
     fs.writeFileSync(laneFile, JSON.stringify({
       ...data,
       sessions: kept.slice(-40),
-      messages: pruneMessages(data.messages, now).slice(-30),
+      messages: capMessages(pruneMessages(data.messages, now), 30),
     }));
     return kept.sort((a, b) => Number(b.lastSeen || 0) - Number(a.lastSeen || 0));
   } finally {
@@ -226,7 +265,7 @@ export function removeSession({ brainPath, id, channel = null, home, now = Date.
     fs.writeFileSync(laneFile, JSON.stringify({
       ...data,
       sessions,
-      messages: pruneMessages(data.messages, now).slice(-30),
+      messages: capMessages(pruneMessages(data.messages, now), 30),
     }));
     return sessions;
   } finally {
@@ -271,24 +310,45 @@ export function receiveMessages({
       && messageTargetsSession(message, me, sessionId));
     if (!unseen.length) return [];
 
-    const unseenIds = new Set(unseen.map((message) => message.id));
-    for (const message of messages) {
-      if (!unseenIds.has(message.id)) continue;
-      if (!Array.isArray(message.seen)) message.seen = [];
-      if (!message.seen.includes(sessionId)) message.seen.push(sessionId);
-    }
-    fs.writeFileSync(laneFile, JSON.stringify({ ...data, sessions, messages }));
-
+    // Deliver-then-ack, never ack-then-truncate: the old path acked EVERY unseen
+    // message under lock but returned only the first 6 — anything past the cap
+    // was marked seen without ever being shown, permanently lost under the
+    // delivered-once contract (2026-07-29 audit). Ack exactly: the delivered 6,
+    // plus self-ignored texts and text-duplicates OF a delivered message (their
+    // content was shown once via the twin). Overflow stays unacked and arrives
+    // on the next call.
+    const normText = (message) => String(message.text || '').replace(/\s+/g, ' ').trim().toLowerCase();
     const ignored = new Set(ignoreTexts.map((text) => String(text || '').replace(/\s+/g, ' ').trim().toLowerCase()));
     const shown = [];
+    const dropped = [];   // ignored (own sends) — content intentionally never shown
     const seenText = new Set();
+    const dupesByText = new Map();
     for (const message of unseen) {
-      const key = String(message.text || '').replace(/\s+/g, ' ').trim().toLowerCase();
-      if (!key || ignored.has(key) || seenText.has(key)) continue;
+      const key = normText(message);
+      if (!key || ignored.has(key)) { dropped.push(message); continue; }
+      if (seenText.has(key)) {
+        if (!dupesByText.has(key)) dupesByText.set(key, []);
+        dupesByText.get(key).push(message);
+        continue;
+      }
       seenText.add(key);
       shown.push(message);
     }
-    return shown.slice(0, 6);
+    const delivered = shown.slice(0, 6);
+    const ackIds = new Set(delivered.map((message) => message.id));
+    for (const message of dropped) ackIds.add(message.id);
+    for (const message of delivered) {
+      for (const dupe of dupesByText.get(normText(message)) || []) ackIds.add(dupe.id);
+    }
+    if (ackIds.size) {
+      for (const message of messages) {
+        if (!ackIds.has(message.id)) continue;
+        if (!Array.isArray(message.seen)) message.seen = [];
+        if (!message.seen.includes(sessionId)) message.seen.push(sessionId);
+      }
+      fs.writeFileSync(laneFile, JSON.stringify({ ...data, sessions, messages }));
+    }
+    return delivered;
   } finally {
     if (gotLock) releaseLock(lockFile);
   }
@@ -368,7 +428,7 @@ export function postPresenceMessage({
     fs.writeFileSync(laneFile, JSON.stringify({
       ...data,
       sessions,
-      messages: messages.slice(-30),
+      messages: capMessages(messages, 30),
     }));
     return { posted: true, message };
   } finally {
@@ -405,24 +465,81 @@ export function formatPresenceMessage(sessions, selfId, { includeSolo = false, 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));
+    // 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 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)}"` : null,
+      session.intent ? `"${String(session.intent).slice(0, 90)}"${intentAge}` : null,
       `${ageMin}m ago`,
     ].filter(Boolean);
     lines.push(`- ${String(session.id).slice(0, 8)}: ${details.join(' | ')}`);
   }
-  lines.push('Coordinate before touching shared files; use brain_message for a targeted note.');
+  // 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.`);
+  lines.push(`Presence is point-in-time (as of ${new Date(now).toISOString().slice(11, 16)}Z) — re-check before coordinating; use brain_message for a targeted note.`);
   return lines.join('\n');
 }
 
-export function formatReceivedMessages(messages, now = Date.now()) {
+// ── Decay-aware LAST-KNOWN stamps (2026-07-28 post-mortem, class B) ──────────
+// A delivered inter-session message is MEMORY, not a SENSOR: one older than 6h
+// whose text asserts fast-decay build/deploy status ("no TestFlight upload
+// triggered yet") must never read as CURRENT state — the ENGINE stamps it,
+// never the reading model. The classifier lives ONCE in klypix-format.mjs;
+// this file stays builtin-only, so consumers INJECT it (the optional third
+// `decay` argument). With no injection the output is byte-identical to the
+// unstamped form — an old bundle degrades to no stamp, never a throw. Each
+// stamp is its OWN line appended AFTER the 400-char render slice (the v1.32.0
+// law: a warning is never subject to the budget/cut it warns about) and exists
+// in render output only — the lane file is never mutated.
+const MSG_DECAY_STAMP_MS = 6 * 60 * 60 * 1000;
+// classifyDecay is precision-first; mirror that here — only an explicit `true`
+// or an explicitly fast-shaped object stamps. Anything ambiguous does NOT
+// (a false stamp erodes trust in every stamp).
+const isFastDecayResult = (r) => r === true || r === 'fast'
+  || (!!r && typeof r === 'object' && (r.fast === true || r.fastDecay === true || r.decay === 'fast' || r.class === 'fast' || r.kind === 'fast'));
+const decayAgeLabel = (ms) => {
+  const h = Math.floor(Math.max(0, ms) / 3_600_000);
+  return h >= 48 ? `${Math.floor(h / 24)}d` : `${Math.max(1, h)}h`;
+};
+
+// Decay verdict for ONE delivered message: null, or { age, stampText } when it
+// is stale (ts older than the engine threshold) AND its RAW text classifies
+// fast-decay (raw, not the render slice — a claim cut out of the 400 chars
+// must still stamp). Threshold, wording, and age format come from the injected
+// engine surface ({ classifyDecay, decayStaleMs, decayMessageStamp,
+// formatDecayAge }) so the renderers can never drift apart; the local
+// fallbacks mirror klypix-format verbatim for a bundle old enough to carry the
+// classifier but not the helpers.
+export function messageDecayInfo(message, now = Date.now(), decay = {}) {
+  const { classifyDecay, decayStaleMs, decayMessageStamp, formatDecayAge } = decay || {};
+  if (typeof classifyDecay !== 'function') return null;
+  try {
+    const ts = Number(message?.ts) || 0;
+    const staleMs = Number(decayStaleMs) > 0 ? Number(decayStaleMs) : MSG_DECAY_STAMP_MS;
+    if (!ts || now - ts < staleMs) return null;
+    if (!isFastDecayResult(classifyDecay(String(message?.text || '')))) return null;
+    const ageMs = now - ts;
+    return {
+      age: typeof formatDecayAge === 'function' ? String(formatDecayAge(ageMs)) : decayAgeLabel(ageMs),
+      stampText: typeof decayMessageStamp === 'function'
+        ? String(decayMessageStamp(ageMs))
+        : `⏱️ This message is ${decayAgeLabel(ageMs)} old and contains build/deploy status — treat as LAST KNOWN, verify live before reporting it.`,
+    };
+  } catch { return null; }   // stamping is best-effort — a classifier bug must never break delivery
+}
+
+export function formatReceivedMessages(messages, now = Date.now(), decay = {}) {
   if (!Array.isArray(messages) || !messages.length) return '';
   const lines = ['KLYPIX message(s) from another active session:'];
   for (const message of messages) {
     const ageMin = Math.max(0, Math.round((now - Number(message.ts || now)) / 60_000));
     lines.push(`- from ${String(message.from || '?').slice(0, 12)} (${ageMin}m ago): ${String(message.text || '').replace(/\s+/g, ' ').trim().slice(0, 400)}`);
+    const info = messageDecayInfo(message, now, decay);
+    if (info) lines.push(`  ${info.stampText}`);
   }
   return lines.join('\n');
 }

package/src/agent-rules.mjs

@@ -521,8 +521,15 @@ function classifyFenced(file, version, frontmatter = null) {
   const raw = fs.readFileSync(file, 'utf8');
   const fence = parseFence(raw);
   if (!fence) return { status: 'missing' };
-  if (fence.hash && sha8(fence.body.trim()) !== fence.hash) return { status: 'hand-edited', stampedVersion: fence.version };
-  const bodyCurrent = sha8(fence.body.trim()) === INSTRUCTIONS_HASH;
+  // Normalize CRLF before hashing (matching norm() in the frontmatter branch
+  // below): the stamped hash is always computed from the LF-only canonical
+  // instructions, so a git-autocrlf checkout or CRLF-saving editor flipped
+  // EVERY projected file to hand-edited at once — the destructive-repair class
+  // — when the true status was a losslessly healable 'stale' (2026-07-29 audit,
+  // the likely cause of "9/14 HAND-EDITED at the same stamp").
+  const bodyHash = sha8(fence.body.replace(/\r\n/g, '\n').trim());
+  if (fence.hash && bodyHash !== fence.hash) return { status: 'hand-edited', stampedVersion: fence.version };
+  const bodyCurrent = bodyHash === INSTRUCTIONS_HASH;
   const stampConsistent = !fence.hash || fence.hash === INSTRUCTIONS_HASH;
   if (bodyCurrent && stampConsistent) {
     // Owned dedicated files are OURS wholesale — frontmatter included. Compare the
@@ -541,11 +548,20 @@ function classifyFenced(file, version, frontmatter = null) {
 
 // Shared markdown (AGENTS.md, copilot-instructions.md, GEMINI.md): merge our fenced
 // block in place, preserving the user's own prose outside the fence.
+// A hand-edited file is about to be rebuilt wholesale — keep the human's version.
+// One rolling .klypix-bak per file (repair stops being an all-or-nothing choice).
+function backupHandEdited(file, status) {
+  if (status !== 'hand-edited' || !exists(file)) return;
+  try { fs.copyFileSync(file, file + '.klypix-bak'); } catch { /* best-effort */ }
+}
+
 function fenceMerge(file, version) {
   // Zero-touch IFF the audit says 'ok' (same classifier, so check and write can
   // never disagree): current+consistent block → byte-identical file, no stamp-only
   // churn; a hand-edited stamp or stale body falls through and gets rebuilt.
-  if (classifyFenced(file, version).status === 'ok') return { action: 'unchanged' };
+  const status = classifyFenced(file, version).status;
+  if (status === 'ok') return { action: 'unchanged' };
+  backupHandEdited(file, status);
   let cur = '';
   let had = false;
   if (exists(file)) { cur = fs.readFileSync(file, 'utf8'); had = true; }
@@ -564,7 +580,9 @@ function fenceMerge(file, version) {
 function writeDedicated(file, frontmatter, version) {
   // Zero-touch IFF the audit says 'ok' — which for owned dedicated files includes
   // the frontmatter (a stripped alwaysApply/trigger MUST be repaired, not skipped).
-  if (classifyFenced(file, version, frontmatter || '').status === 'ok') return { action: 'unchanged' };
+  const status = classifyFenced(file, version, frontmatter || '').status;
+  if (status === 'ok') return { action: 'unchanged' };
+  backupHandEdited(file, status);
   const had = exists(file);
   const body = (frontmatter ? frontmatter + '\n' : '') + fencedBlock(version) + '\n';
   ensureDir(file); fs.writeFileSync(file, body, 'utf8');