klypix-mcp 1.45.0 → 1.46.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.45.0",
+  "version": "1.46.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -65,7 +65,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/skill-staleness.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 && node test/cli-args.mjs && node test/uninstall.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/skill-staleness.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 && node test/cli-args.mjs && node test/format-guard.mjs && node test/uninstall.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.4",

package/src/brain-note.mjs

@@ -19,7 +19,7 @@
 // Optional trailing path picks a different .klypix (default ./brain.klypix).
 import fs from 'fs';
 import path from 'path';
-import { captureIntoBrain, tidyBrain, atomicWrite, noteToCaptureInput } from './klypix-format.mjs';
+import { captureIntoBrain, tidyBrain, atomicWrite, noteToCaptureInput, formatCaptureReceipts } from './klypix-format.mjs';
 
 const MARKERS = { '': '', '?': '?', '!': '!', '✓': '✓', '~': '~', question: '?', milestone: '!', resolve: '✓', update: '~', decision: '', done: '✓' };
 const normMarker = (m) => MARKERS[String(m || '').toLowerCase()] ?? '';
@@ -66,6 +66,7 @@ try {
     const bits = [`${s.added || 0} added`];
     for (const k of ['resolved', 'updated', 'closed', 'superseded', 'linked']) if (s[k]) bits.push(`${s[k]} ${k}`);
     console.error(`✓ brain-note → ${path.basename(file)} (${bits.join(' · ')})`);
+    for (const line of formatCaptureReceipts(s)) console.error(`  ${line}`);
 } catch (e) {
     console.error(`brain-note failed (brain unchanged): ${e?.message || e}`);
     process.exit(1);

package/src/klypix-core.mjs

@@ -32,7 +32,7 @@ import {
   statusContextToMarkdown, findFulfillmentCandidates,
   splitQueryTokens, scoreCardsAgainstQuery, correctionOverlaysFor,
   isFastDecayCard, DECAY_STALE_MS, formatDecayAge,
-  readPendingShips, clearPendingShips, pendingShipCards,
+  readPendingShips, clearPendingShips, pendingShipCards, formatCaptureReceipts,
 } from './klypix-format.mjs';
 import { capMessages, findProjectBrain } from './agent-presence.mjs';
 
@@ -1031,7 +1031,12 @@ export async function opBrainNote({ vault, canvas, text: noteText, area, marker
       : '';
     // Name the resolved brain explicitly (basename + how) so a write never lands
     // in a surprise file silently — the write-side twin of the read-op stamp.
-    return { blocks: [text(`✓ brain_note → ${path.basename(file)} (via ${t.how}) · ${bits.join(' · ')}. Reopen the brain in the KLYPIX app to see it.${corr}`)] };
+    // Host-neutral capture receipts (2026-08-01): Codex/Cursor/Cline capture
+    // through THIS verb, not the Claude Stop hook — without these lines the
+    // write-side ⏳/⚠️ nudges existed only on one host brand.
+    const receipts = formatCaptureReceipts(s);
+    const rc = receipts.length ? `\n${receipts.join('\n')}` : '';
+    return { blocks: [text(`✓ brain_note → ${path.basename(file)} (via ${t.how}) · ${bits.join(' · ')}. Reopen the brain in the KLYPIX app to see it.${corr}${rc}`)] };
   } catch (e) {
     return err(`brain_note failed (brain unchanged): ${e.message}`);
   }

package/src/klypix-format.mjs

@@ -9,8 +9,36 @@
 import JSZip from 'jszip';
 import path from 'path';
 import fs from 'fs';
+import os from 'os';
+import { execFileSync } from 'child_process';
 import { generateKeyBetween } from 'fractional-indexing';
 
+// ── Card author identity (team attribution, 2026-08-01) ─────────────────────
+// `createdBy: 'agent'` says WHAT wrote a card; on a team brain the question is
+// WHOSE agent. Identity rides the same source as the dev's commits — git
+// `user.name` in the project — so brain attribution matches git attribution
+// with zero configuration; `KLYPIX_AUTHOR` overrides, OS account name is the
+// fallback, and on total failure the field is simply absent (additive — older
+// readers and older cards are untouched; merge preserves item bytes verbatim,
+// so authorship survives every sync route).
+let cachedAuthor;
+export function resolveAuthor() {
+    if (cachedAuthor !== undefined) return cachedAuthor;
+    const env = String(process.env.KLYPIX_AUTHOR || '').trim();
+    if (env) return (cachedAuthor = env.slice(0, 80));
+    try {
+        const name = execFileSync('git', ['config', 'user.name'], { stdio: ['ignore', 'pipe', 'ignore'], timeout: 1500 })
+            .toString().trim();
+        if (name) return (cachedAuthor = name.slice(0, 80));
+    } catch { /* not a repo / git absent — fall through */ }
+    try { cachedAuthor = String(os.userInfo().username || '').slice(0, 80) || null; }
+    catch { cachedAuthor = null; }
+    return cachedAuthor;
+}
+// Test seam: clears the per-process cache so env overrides can be exercised.
+export function __resetAuthorCache() { cachedAuthor = undefined; }
+const authorField = () => { const a = resolveAuthor(); return a ? { author: a } : {}; };
+
 // Valid fractional-indexing z-keys. Hand-rolled keys (e.g. 'a0000' / 'z00013')
 // are REJECTED by the fractional-indexing lib the KLYPIX app uses and crash it
 // the moment you edit such a canvas — so the writer MUST emit lib-valid keys.
@@ -91,6 +119,20 @@ export async function parseKlypix(buffer) {
     if (!canvasRaw) throw new Error('Not a valid .klypix/.any — no canvas.json inside.');
 
     const manifest = manifestRaw ? JSON.parse(manifestRaw) : null;
+    // Forward-compat guard: this engine reads format v4. A file stamped by a
+    // FUTURE format must be refused loudly, never parsed blindly — with brains
+    // syncing between machines (git / Brain Sync), mixed versions are a
+    // guaranteed state, and a blind parse here feeds every downstream writer
+    // (merge, arrange, capture) a structure it does not understand. The merge
+    // driver inherits this automatically: the throw exits it non-zero, which
+    // degrades to a normal manual git conflict.
+    const KLYPIX_FORMAT_CEILING = 4;
+    if (manifest && manifest.format === 'klypix' && Number(manifest.version) > KLYPIX_FORMAT_CEILING) {
+        throw new Error(
+            `This .klypix was saved by a newer format (v${manifest.version}); this engine reads up to v${KLYPIX_FORMAT_CEILING}. ` +
+            'Update KLYPIX / klypix-mcp instead of parsing it — a blind read could damage it.'
+        );
+    }
     const canvas = JSON.parse(canvasRaw);
     // v4 manifests are {format:"klypix", version:4}; positions presence is the
     // robust fallback (legacy .any keeps an inline items array, no positions).
@@ -272,7 +314,7 @@ export async function buildKlypix(spec) {
     const itemJson = (card, w) => {
         if (card.type === 'text') {
             return {
-                type: 'text', locked: false, createdAt: now, createdBy: 'agent',
+                type: 'text', locked: false, createdAt: now, createdBy: 'agent', ...authorField(),
                 content: String(card.text ?? ''), fontSize: FONT,
                 // PLAIN text (no border) renders at max-content width unless
                 // authoredWidth pins the wrap — without it a long single line
@@ -284,7 +326,7 @@ export async function buildKlypix(spec) {
                 textDecoration: 'none', textAlign: 'left', verticalAlign: 'top',
             };
         }
-        return { type: card.type, locked: false, createdAt: now, createdBy: 'agent', ...(card._raw || {}) };
+        return { type: card.type, locked: false, createdAt: now, createdBy: 'agent', ...authorField(), ...(card._raw || {}) };
     };
 
     const zip = new JSZip();
@@ -369,7 +411,7 @@ export async function appendToKlypix(buffer, addition) {
     const nextZKey = makeZKeyGen(existingTop);
     for (const a of added) {
         zip.file(`items/${shard(a.id)}/${a.id}.json`, JSON.stringify({
-            type: 'text', locked: false, createdAt: now, createdBy: 'agent',
+            type: 'text', locked: false, createdAt: now, createdBy: 'agent', ...authorField(),
             ...(a.card.createdVia ? { createdVia: String(a.card.createdVia) } : {}),
             content: String(a.card.text), fontSize: FONT,
             color: a.card.color || '#1a1a1f', border: !!a.card.border, borderColor: '#1e1e2e',
@@ -542,8 +584,10 @@ export async function appendIntoContainers(buffer, addition) {
         const id = `txt_${rand()}`;
         zip.file(`items/${shard(id)}/${id}.json`, JSON.stringify({
             type: 'text', locked: false, createdAt: now, createdBy: 'agent',
-            // Provenance: WHICH agent remembered this (claude-code / cursor /
-            // cline / …) — additive field, ignored by older readers.
+            // Provenance: WHOSE agent (git user.name — matches commit identity)…
+            ...authorField(),
+            // …and WHICH agent remembered this (claude-code / cursor /
+            // cline / …) — both additive fields, ignored by older readers.
             ...(card.createdVia ? { createdVia: String(card.createdVia) } : {}),
             // Evidence anchors (file:line / PR#) — additive, ignored by older readers.
             ...(Array.isArray(card.evidence) && card.evidence.length ? { evidence: card.evidence } : {}),
@@ -3837,7 +3881,7 @@ export async function applyGarden(buffer, { syntheses = [] } = {}) {
         // `sources` = machine lineage (which originals fed this synthesis, with
         // their birth dates) — as_of and future provenance passes read the
         // field, never the prose.
-        zip.file(`items/${shard(sid)}/${sid}.json`, JSON.stringify({ type: 'text', locked: false, createdAt: now, createdBy: 'agent', createdVia: 'gardener', content, fontSize: 12, color: '#e8e8ed', border: true, borderColor: 'rgba(59,130,246,0.6)', heading: false, sources: area.candidates.map(c => ({ id: c.id, createdAt: c.createdAt || 0 })) }));
+        zip.file(`items/${shard(sid)}/${sid}.json`, JSON.stringify({ type: 'text', locked: false, createdAt: now, createdBy: 'agent', ...authorField(), createdVia: 'gardener', content, fontSize: 12, color: '#e8e8ed', border: true, borderColor: 'rgba(59,130,246,0.6)', heading: false, sources: area.candidates.map(c => ({ id: c.id, createdAt: c.createdAt || 0 })) }));
         canvas.positions[sid] = { x: ctnPos.x + 20, y: ctnPos.y + (ctnPos.h || 0) + 10, w: 300, h: measureCardH(content), zKey: nextZKey(), zIndex: canvas.order.length, parentId: area.containerId };
         canvas.order.push(sid);
         newCards.push(sid);
@@ -4229,8 +4273,17 @@ const LIMITATION_CUE_RE = new RegExp([
     /\bnot (?:implemented|wired|supported|available|built|shipped|published|deployed|enforced|persisted|possible|reachable|exposed|functional)\b/u.source,
     /\breturns? (?:a )?(?:mock|stub|null|nothing)\b/u.source,
     /\bis (?:dead|unused|missing|absent|unreachable|unwired|talk[- ]?only)\b/u.source,
-    /\bonly (?:works|runs|streams|answers|covers|supports|reads)\b/u.source,
+    /\bonly (?:works|runs|streams|answers|covers|supports|reads|checks|compares|matches|lowercases|normalizes)\b/u.source,
     /\bstill (?:missing|absent|manual|unwired|blocked|mocked?)\b/u.source,
+    // 2026-08-01, first real-world miss (the day after shipping): the presence-
+    // bugs skill card asserted "compares hostPid ALONE", "only lowercases+slash-
+    // normalizes" and "indistinguishable from success" — all state claims, none
+    // matched a cue, so the card kept reading as settled law for a full session
+    // after ab10688 had fixed every one of them. Cues grow ON-DEMAND from real
+    // misses, never speculatively — each addition below names its incident.
+    /\b(?:compares?|keys?|keyed|matches?) [\p{L}\p{N}_-]+ alone\b/u.source,
+    /\bindistinguishable from\b/u.source,
+    /\bsilently (?:miss(?:es|ed)?|fail(?:s|ed)?|drop(?:s|ped)?)\b/u.source,
 ].join('|'), 'iu');
 // Imperative openers = advice, not state. Anchored to the CLAUSE start so
 // "Chat has no tools" (subject-first) passes while "never set X" is refused.
@@ -4321,6 +4374,29 @@ export function findSkillObsolescenceCandidates(struct, milestones, { coverAt =
     return capped;
 }
 
+// ── Capture receipts, host-neutral (2026-08-01 parity fix) ──────────────────
+// The ⏳/⚠️ capture receipts used to print ONLY through the Claude Stop-hook's
+// stderr — a Codex / Cursor / Cline session capturing through brain_note (MCP
+// or CLI) got "1 added · 1 superseded" and never saw the nudge, so on those
+// hosts the write-side half of both detection classes was silently absent.
+// One formatter, consumed by opBrainNote (MCP) and brain-note (CLI), so every
+// host hears what the hook hears; the hook keeps its own prefix style.
+export function formatCaptureReceipts(stats, { maxEach = 3 } = {}) {
+    const s = stats || {};
+    const lines = [];
+    for (const f of (Array.isArray(s.fulfillCandidates) ? s.fulfillCandidates : []).slice(0, maxEach)) {
+        const rest = f.uncovered && f.uncovered.length ? ` · does NOT cover: ${f.uncovered.map(u => `"${String(u).slice(0, 50)}"`).join(', ')}` : '';
+        const act = f.marker
+            ? `— if truly done, emit: ${f.marker}`
+            : '— PARTIAL/short: the card stays open (verify by hand; dismiss via brain_connect relationship:"not_fulfilled")';
+        lines.push(`⏳ likely fulfilled (${f.cov}): "${String(f.item).slice(0, 70)}"${rest} ${act}`);
+    }
+    for (const f of (Array.isArray(s.skillStale) ? s.skillStale : []).slice(0, maxEach)) {
+        lines.push(`⚠️ rule may be obsolete (${f.cov}): skill "${String(f.skill).slice(0, 70)}" asserts "${String(f.clause || '').slice(0, 60)}" — this ship appears to remove it. If so, amend: ${f.marker} (retire by naming it in closes:, or dismiss via brain_connect relationship:"not_fulfilled")`);
+    }
+    return lines;
+}
+
 // Persisted-edge overlay reader for 'may obsolete' hints — the 🛠️ twin of
 // fulfillmentOverlaysFor, same rules: dismissals win, a since-archived
 // milestone no longer vouches, machine-written hints stay hedged forever.
@@ -4585,7 +4661,7 @@ export async function buildKlypixMap(spec) {
             const id = `txt_${rand()}_${ai}_${ci}`;
             const h = measured[ci];
             items[id] = {
-                type: 'text', locked: false, createdAt: now, createdBy: 'agent',
+                type: 'text', locked: false, createdAt: now, createdBy: 'agent', ...authorField(),
                 content: String(c.text), fontSize: FONT,
                 color: c.color || '#e8e8ed', border: true,
                 borderColor: c.color || 'rgba(16,185,129,0.35)',