klypix-mcp 1.46.0 → 1.48.0

package/bin/klypix-conformance.mjs

@@ -160,6 +160,103 @@ try {
     a.client.callTool({ name: 'brain_sync', arguments: { phase: 'complete' } }),
     b.client.callTool({ name: 'brain_sync', arguments: { phase: 'complete' } }),
   ]);
+
+  // ── Cross-PC presence: simulated two-machine scenario ─────────────────────
+  // Two isolated registries (one per "machine") + a mock channel around the
+  // pure transport seam (src/presence-relay.mjs relayOutbound/relayInbound —
+  // the exact functions the desktop relay wraps its Realtime channel with).
+  // Proves: peer visibility across machines, overlap warning on the canonical
+  // file key, message delivered once under double-delivery, clean degradation
+  // with the channel dead, and the consent gate at the seam.
+  {
+    const [{ relayOutbound, relayInbound, PRESENCE_CONSENT_VERSION, PRESENCE_CONSENT_PURPOSE, PRESENCE_CONSENT_SCOPE },
+      { upsertSession, upsertRemoteSessions, listActiveSessions, postPresenceMessage, receiveMessages },
+      { findPresenceConflicts }] = await Promise.all([
+      import('../src/presence-relay.mjs'),
+      import('../src/agent-presence.mjs'),
+      import('../src/mcp-presence.mjs'),
+    ]);
+    const GRANT = {
+      version: PRESENCE_CONSENT_VERSION, decision: 'granted', decidedAt: new Date().toISOString(),
+      purpose: PRESENCE_CONSENT_PURPOSE, scope: PRESENCE_CONSENT_SCOPE,
+    };
+    const xpcRoot = path.join(tempRoot, 'xpc');
+    const homeA = path.join(xpcRoot, 'homeA');
+    const homeB = path.join(xpcRoot, 'homeB');
+    const repoA = path.join(xpcRoot, 'machineA', 'repo');
+    const repoB = path.join(xpcRoot, 'machineB', 'repo');
+    for (const dir of [homeA, homeB, repoA, repoB]) fs.mkdirSync(dir, { recursive: true });
+    const brainA = path.join(repoA, 'brain.klypix');
+    const brainB = path.join(repoB, 'brain.klypix');
+    fs.writeFileSync(brainA, 'xpc-fixture');
+    fs.writeFileSync(brainB, 'xpc-fixture');
+    const now = Date.now();
+
+    upsertSession({
+      brainPath: brainA, home: homeA, now, id: 'xpc-dev-a', client: 'claude-code', branch: 'main',
+      intent: 'edit the shared component', files: [path.join(repoA, 'src', 'Shared.tsx')],
+    });
+    upsertSession({
+      brainPath: brainB, home: homeB, now, id: 'xpc-dev-b', client: 'codex', branch: 'main',
+      intent: 'restyle the shared component', files: ['src/Shared.tsx'],
+    });
+
+    // Consent gate FIRST: with no record, the seam must emit nothing.
+    let framesSent = 0;
+    const gated = relayOutbound({
+      sessions: listActiveSessions({ brainPath: brainA, home: homeA, now }),
+      consent: null, machineId: 'xpc-mach-a', root: repoA, now, send: () => { framesSent++; },
+    });
+    checks.crossMachineConsentGate = framesSent === 0 && gated.reason === 'no-consent';
+
+    // Live channel: A's session and message reach B exactly once.
+    const wire = [];
+    relayOutbound({
+      sessions: listActiveSessions({ brainPath: brainA, home: homeA, now }),
+      messages: (() => {
+        postPresenceMessage({ brainPath: brainA, from: 'xpc-dev-a', text: 'starting on Shared.tsx now', home: homeA, now });
+        try { return JSON.parse(fs.readFileSync(path.join(homeA, '.claude', 'project-brain', 'sessions', fs.readdirSync(path.join(homeA, '.claude', 'project-brain', 'sessions')).find((f) => f.endsWith('.json'))), 'utf8')).messages || []; }
+        catch { return []; }
+      })(),
+      consent: GRANT, machineId: 'xpc-mach-a', hostLabel: 'MACHINE-A', root: repoA, now,
+      send: (frame) => wire.push(frame),
+    });
+    const deliverAll = (stampNow) => {
+      const rows = [];
+      for (const frame of wire) {   // double-delivery: every frame arrives twice (at-least-once transport)
+        for (let i = 0; i < 2; i++) {
+          const inbound = relayInbound(frame, { consent: GRANT, machineId: 'xpc-mach-b', now: stampNow });
+          if (inbound?.type === 'presence') rows.push(inbound.row);
+          if (inbound?.type === 'message') {
+            postPresenceMessage({
+              brainPath: brainB, from: inbound.message.from, to: inbound.message.to,
+              text: inbound.message.text, dedupeKey: inbound.message.dedupeKey, home: homeB, now: stampNow,
+            });
+          }
+        }
+      }
+      if (rows.length) upsertRemoteSessions({ brainPath: brainB, rows, machineId: 'xpc-mach-b', home: homeB, now: stampNow });
+    };
+    deliverAll(now + 500);
+
+    const bSessions = listActiveSessions({ brainPath: brainB, home: homeB, now: now + 500 });
+    const remote = bSessions.find((session) => session.id === 'xpc-dev-a');
+    checks.crossMachinePeerVisibility = !!remote && remote.via === 'cloud' && remote.host === 'MACHINE-A';
+    const overlaps = findPresenceConflicts(bSessions, 'xpc-dev-b', { projectRoot: repoB });
+    checks.crossMachineOverlapWarning = overlaps.length === 1
+      && overlaps[0].id === 'xpc-dev-a'
+      && overlaps[0].files.some((file) => file.toLowerCase().includes('src/shared.tsx'));
+    const delivered = receiveMessages({ brainPath: brainB, sessionId: 'xpc-dev-b', home: homeB, now: now + 600 });
+    checks.crossMachineMessageOnce = delivered.filter((message) => message.text.includes('Shared.tsx')).length === 1;
+
+    // Dead channel: outbound reports without throwing; local presence intact.
+    const dead = relayOutbound({
+      sessions: listActiveSessions({ brainPath: brainA, home: homeA, now: now + 700 }),
+      consent: GRANT, machineId: 'xpc-mach-a', root: repoA, now: now + 700, send: undefined,
+    });
+    checks.crossMachineOfflineDegradation = dead.sent === 0 && dead.reason === 'no-channel'
+      && listActiveSessions({ brainPath: brainA, home: homeA, now: now + 700 }).some((session) => session.id === 'xpc-dev-a');
+  }
 } catch (error) {
   checks.runtime = false;
   checks.error = error?.message || String(error);
@@ -176,6 +273,11 @@ const required = [
   'alertQueued',
   'proactiveLogging',
   'guaranteedInBandDelivery',
+  'crossMachineConsentGate',
+  'crossMachinePeerVisibility',
+  'crossMachineOverlapWarning',
+  'crossMachineMessageOnce',
+  'crossMachineOfflineDegradation',
 ];
 const ok = required.every((name) => checks[name] === true);
 const result = {

package/bin/klypix-diff.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Thin bin for `klypix-mcp diff` — the worker dispatcher splices the verb out
+// of argv before importing, so this bin re-supplies it. Standalone use works
+// identically: node bin/klypix-diff.mjs <args>
+import { run } from './klypix-git-tools.mjs';
+await run('diff', process.argv.slice(2));

package/bin/klypix-git-driver.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Thin bin for `klypix-mcp git-driver` — the worker dispatcher splices the verb out
+// of argv before importing, so this bin re-supplies it. Standalone use works
+// identically: node bin/klypix-git-driver.mjs <args>
+import { run } from './klypix-git-tools.mjs';
+await run('git-driver', process.argv.slice(2));

package/bin/klypix-git-tools.mjs

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+// klypix-git-tools — the GitHub lane: three verbs that put the brain where
+// dev teams actually live (the repo and the PR page).
+//
+//   git-driver [install|status] [repo]   register the lossless .klypix merge
+//                                        driver for a repo, zero-command
+//   diff [ref] [--brain <path>]          readable brain diff vs a git ref
+//   pr-brief [baseRef] [--brain <path>]  brain cards touching the files
+//                                        changed since baseRef (PR comment)
+//
+// Design rules inherited from the engine:
+//   • ONE merge engine — the driver rides src/merge-brains.mjs verbatim.
+//   • The registered driver path is the INSTALLED runtime
+//     (~/.claude/project-brain) — stable across npx cache evictions; this
+//     module self-provisions the three engine files + their two deps there
+//     when missing, without running the full hook installer.
+//   • A truncated list must NEVER render as complete: every capped section
+//     emits its "…and N more" through an unguarded push.
+//   • Failure is a calm, specific message + non-zero exit — never a stack.
+
+// SHAPE: this is a LIB — the worker dispatcher splices the verb out of argv
+// before importing a verb bin (see runVerb), so each verb has a THIN bin
+// (klypix-git-driver.mjs / klypix-diff.mjs / klypix-pr-brief.mjs) that calls
+// run(<verb>, argv.slice(2)) here. Standalone `node <bin> …` works identically.
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { execFile } from 'child_process';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SRC = path.join(HERE, '..', 'src');
+// Overridable for tests (temp dirs only — never point tests at the real one).
+const BRAIN_DIR = process.env.KLYPIX_BRAIN_DIR || path.join(os.homedir(), '.claude', 'project-brain');
+
+let args = [];
+const flag = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+let positional = [];
+
+const git = (cwd, gitArgs, opts = {}) => new Promise((resolve, reject) => {
+  execFile('git', gitArgs, { cwd, timeout: 15000, windowsHide: true, maxBuffer: 128 * 1024 * 1024, ...opts },
+    (err, stdout) => err ? reject(err) : resolve(stdout));
+});
+const gitText = async (cwd, ...a) => String(await git(cwd, a)).trim();
+
+async function repoToplevel(startDir) {
+  try { return await gitText(startDir, 'rev-parse', '--show-toplevel'); }
+  catch { return null; }
+}
+
+function findBrain(explicit) {
+  if (explicit) {
+    const p = path.resolve(explicit);
+    return fs.existsSync(p) ? p : null;
+  }
+  let dir = process.cwd();
+  for (let i = 0; i < 12; i++) {
+    const p = path.join(dir, 'brain.klypix');
+    if (fs.existsSync(p)) return p;
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+// Card text is stored CANVAS-WRAPPED (single \n ≈ visual line breaks), so a
+// naive first-line is ~35 chars of a sentence. Join the first paragraph back
+// into prose and cap it.
+const firstLine = (t) => {
+  const para = String(t || '').split(/\n\s*\n/)[0].replace(/\s*\n\s*/g, ' ').trim();
+  return para.length > 110 ? `${para.slice(0, 110)}…` : para;
+};
+
+async function loadEngine() {
+  const format = await import(new URL('../src/klypix-format.mjs', import.meta.url).href);
+  const merge = await import(new URL('../src/merge-brains.mjs', import.meta.url).href);
+  return { format, merge };
+}
+
+// ── git-driver ──────────────────────────────────────────────────────────────
+
+const ENGINE_FILES = ['klypix-merge-driver.mjs', 'merge-brains.mjs', 'klypix-format.mjs'];
+const ENGINE_DEPS = ['jszip', 'fractional-indexing'];
+
+// Make sure the INSTALLED runtime can actually run the driver: the three
+// engine files plus their two (dependency-free) deps. This is deliberately a
+// light provision — it never touches hooks or servers; the full installer
+// remains `npx klypix-mcp install`.
+function ensureDriverRuntime() {
+  const provisioned = [];
+  fs.mkdirSync(BRAIN_DIR, { recursive: true });
+  for (const f of ENGINE_FILES) {
+    const dest = path.join(BRAIN_DIR, f);
+    const srcFile = path.join(SRC, f);
+    if (!fs.existsSync(dest) || fs.readFileSync(dest, 'utf8') !== fs.readFileSync(srcFile, 'utf8')) {
+      fs.copyFileSync(srcFile, dest);
+      provisioned.push(f);
+    }
+  }
+  const requireHere = createRequire(import.meta.url);
+  // Modern packages fence `exports`, so `<dep>/package.json` may not resolve —
+  // resolve the MAIN entry instead and walk up to the package root.
+  const depRootOf = (dep) => {
+    let p = path.dirname(requireHere.resolve(dep));
+    for (let i = 0; i < 6; i++) {
+      const pkg = path.join(p, 'package.json');
+      try {
+        if (fs.existsSync(pkg) && JSON.parse(fs.readFileSync(pkg, 'utf8')).name === dep) return p;
+      } catch { /* keep walking */ }
+      const up = path.dirname(p);
+      if (up === p) break;
+      p = up;
+    }
+    throw new Error(`cannot locate package root for dependency "${dep}"`);
+  };
+  const destMods = path.join(BRAIN_DIR, 'node_modules');
+  // Deps are provisioned as their RECURSIVE closure (jszip alone pulls pako,
+  // lie, readable-stream, …) — everything resolves from the local install, so
+  // this stays offline and deterministic. Nested (unhoisted) deps resolve via
+  // a require scoped to their parent package.
+  const provisionDep = (dep, fromDir, seen) => {
+    if (seen.has(dep)) return;
+    seen.add(dep);
+    let root;
+    try { root = depRootOf(dep); }
+    catch {
+      const scoped = createRequire(path.join(fromDir, 'package.json'));
+      let p = path.dirname(scoped.resolve(dep));
+      while (p !== path.dirname(p) && !fs.existsSync(path.join(p, 'package.json'))) p = path.dirname(p);
+      root = p;
+    }
+    const destDir = path.join(destMods, dep);
+    if (!fs.existsSync(destDir)) {
+      // Exclude only node_modules NESTED INSIDE the package (the closure walk
+      // provisions those flat) — judged relative to the package root, because
+      // the source root itself lives under a node_modules path.
+      fs.cpSync(root, destDir, {
+        recursive: true,
+        filter: (s) => !path.relative(root, s).split(path.sep).includes('node_modules'),
+      });
+      provisioned.push(`node_modules/${dep}`);
+    }
+    let pkg = {};
+    try { pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')); } catch { /* leaf */ }
+    for (const child of Object.keys(pkg.dependencies || {})) provisionDep(child, root, seen);
+  };
+  const seen = new Set();
+  for (const dep of ENGINE_DEPS) provisionDep(dep, path.join(HERE, '..'), seen);
+  return provisioned;
+}
+
+const DRIVER_ATTR_RULE = '*.klypix merge=klypix -text';
+
+async function gitDriver() {
+  const sub = positional[0] && !fs.existsSync(positional[0]) ? positional[0] : 'install';
+  const repoArg = positional.find(p => fs.existsSync(p)) || process.cwd();
+  const toplevel = await repoToplevel(repoArg);
+  if (!toplevel) { console.error(`Not a git repository: ${repoArg}`); process.exit(1); }
+
+  const driverPath = path.join(BRAIN_DIR, 'klypix-merge-driver.mjs');
+  const driverCmd = `node "${driverPath.replace(/\\/g, '/')}" %O %A %B %P`;
+  const gaPath = path.join(toplevel, '.gitattributes');
+  const gaText = fs.existsSync(gaPath) ? fs.readFileSync(gaPath, 'utf8') : '';
+  const gaHasRule = /merge=klypix/.test(gaText);
+
+  if (sub === 'status') {
+    let configured = '';
+    try { configured = await gitText(toplevel, 'config', '--get', 'merge.klypix.driver'); } catch { /* unset */ }
+    const runtimeOk = ENGINE_FILES.every(f => fs.existsSync(path.join(BRAIN_DIR, f)));
+    console.log(`repo:          ${toplevel}`);
+    console.log(`driver config: ${configured || '(not registered)'}`);
+    console.log(`.gitattributes rule: ${gaHasRule ? 'present' : 'missing'}`);
+    console.log(`installed runtime:   ${runtimeOk ? BRAIN_DIR : 'missing — run: npx klypix-mcp git-driver install'}`);
+    process.exit(configured && gaHasRule && runtimeOk ? 0 : 1);
+  }
+
+  const provisioned = ensureDriverRuntime();
+  let already = false;
+  try { already = (await gitText(toplevel, 'config', '--get', 'merge.klypix.driver')) === driverCmd; } catch { /* unset */ }
+  if (!already) {
+    await git(toplevel, ['config', 'merge.klypix.name', 'KLYPIX lossless brain merge (union by card id)']);
+    await git(toplevel, ['config', 'merge.klypix.driver', driverCmd]);
+  }
+  let gaState = 'present';
+  if (!gaHasRule) {
+    const rule = `${gaText && !gaText.endsWith('\n') ? '\n' : ''}# .klypix brains merge losslessly via the KLYPIX 3-way union driver\n# (per-machine registration: npx klypix-mcp git-driver install).\n${DRIVER_ATTR_RULE}\n`;
+    fs.appendFileSync(gaPath, rule);
+    gaState = 'added';
+  }
+  console.log(`✓ ${already ? 'Already registered' : 'Registered'} the .klypix merge driver for ${toplevel}`);
+  console.log(`    driver: ${driverPath}${provisioned.length ? `  (provisioned: ${provisioned.join(', ')})` : ''}`);
+  console.log(`    .gitattributes rule: ${gaState}${gaState === 'added' ? ' — commit it so every teammate\'s clone routes .klypix merges here' : ''}`);
+  console.log('  Teammates run the same command once per machine; unregistered machines fall back to a normal conflict.');
+}
+
+// ── diff ────────────────────────────────────────────────────────────────────
+
+function renderCardList(title, entries, cap = 20) {
+  if (!entries.length) return [];
+  const lines = [`**${title} (${entries.length})**`];
+  for (const e of entries.slice(0, cap)) lines.push(`- ${e}`);
+  // Truncation notice is NEVER subject to the cap it reports.
+  if (entries.length > cap) lines.push(`- …and ${entries.length - cap} more`);
+  lines.push('');
+  return lines;
+}
+
+async function brainDiff() {
+  const ref = positional[0] || 'HEAD';
+  const brain = findBrain(flag('--brain'));
+  if (!brain) { console.error('No brain.klypix found (searched upward from cwd; use --brain <path>).'); process.exit(1); }
+  const toplevel = await repoToplevel(path.dirname(brain));
+  if (!toplevel) { console.error(`Brain is not inside a git repository: ${brain}`); process.exit(1); }
+  const rel = path.relative(toplevel, brain).replace(/\\/g, '/');
+
+  const { format, merge } = await loadEngine();
+  const current = fs.readFileSync(brain);
+
+  let baseBuf = null;
+  try { baseBuf = Buffer.from(await git(toplevel, ['show', `${ref}:${rel}`], { encoding: 'buffer' })); }
+  catch { baseBuf = null; }
+
+  const out = [`### 🧠 Brain diff — \`${rel}\` vs \`${ref}\``, ''];
+  if (!baseBuf || baseBuf.length === 0) {
+    const { struct } = await format.parseKlypix(current);
+    out.push(`The brain does not exist at \`${ref}\` — everything is new here (${struct.cards.length} cards).`);
+    console.log(out.join('\n'));
+    return;
+  }
+
+  // SEMANTIC diff, never byte diff: .klypix re-serialization is deliberately
+  // non-reproducible (zip metadata, zIndex renumbering), so comparing raw item
+  // bytes reports the whole brain as "updated" (live-reproduced: 1308 false
+  // updates over 8 commits). Parse both sides and compare key-sorted JSON with
+  // display-derived fields stripped — the same discipline as the sync core.
+  const stable = (v) => JSON.stringify(v, (_k, val) =>
+    (val && typeof val === 'object' && !Array.isArray(val))
+      ? Object.fromEntries(Object.keys(val).sort().map(x => [x, val[x]]))
+      : val);
+  const cardMap = async (buf) => {
+    const { zip, canvas } = await format.parseKlypix(buf);
+    const ids = [...new Set([...(Array.isArray(canvas.order) ? canvas.order : []), ...Object.keys(canvas.positions || {})])];
+    const m = new Map();
+    for (const id of ids) {
+      const f = zip.file(`items/${format.shard(id)}/${id}.json`);
+      if (!f) continue;
+      try {
+        const item = JSON.parse(await f.async('string'));
+        m.set(id, {
+          sig: stable({ ...item, zIndex: undefined }),
+          title: firstLine(item.content || item.title || '') || `\`${id}\``,
+        });
+      } catch { /* unreadable item — skip rather than mis-report */ }
+    }
+    return { map: m, connections: Array.isArray(canvas.connections) ? canvas.connections.length : 0 };
+  };
+  void merge; // brainDelta stays the live-apply engine; diff is semantic by design
+
+  const [baseSide, curSide] = await Promise.all([cardMap(baseBuf), cardMap(current)]);
+  const added = [], updated = [], removed = [];
+  for (const [id, cur] of curSide.map) {
+    const prev = baseSide.map.get(id);
+    if (!prev) added.push(cur.title);
+    else if (prev.sig !== cur.sig) updated.push(cur.title);
+  }
+  for (const [id, prev] of baseSide.map) {
+    if (!curSide.map.has(id)) removed.push(prev.title);
+  }
+  const connDelta = curSide.connections - baseSide.connections;
+
+  if (!added.length && !updated.length && !removed.length && !connDelta) {
+    out.push('No card-level changes.');
+  } else {
+    out.push(`**${added.length} added · ${updated.length} updated · ${removed.length} removed**`, '');
+    out.push(...renderCardList('Added', added));
+    out.push(...renderCardList('Updated', updated));
+    out.push(...renderCardList('Removed', removed));
+    if (connDelta) out.push(`_${connDelta > 0 ? '+' : ''}${connDelta} connection(s)._`);
+  }
+  console.log(out.join('\n'));
+}
+
+// ── pr-brief ────────────────────────────────────────────────────────────────
+
+// The brain's own evidence-tag convention: #file-<slug> where slug is the
+// basename minus its last extension, lowercased, non-alphanumerics folded to
+// hyphens. Tag matches only (precision over recall — a PR comment that spams
+// unrelated cards teaches people to ignore it).
+function fileSlug(p) {
+  const base = path.basename(p).replace(/\.[^.]+$/, '');
+  return base.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+async function prBrief() {
+  const baseRef = positional[0] || 'HEAD~1';
+  const brain = findBrain(flag('--brain'));
+  if (!brain) { console.error('No brain.klypix found (searched upward from cwd; use --brain <path>).'); process.exit(1); }
+  const toplevel = await repoToplevel(path.dirname(brain));
+  if (!toplevel) { console.error(`Brain is not inside a git repository: ${brain}`); process.exit(1); }
+
+  let changed = [];
+  try {
+    changed = String(await git(toplevel, ['diff', '--name-only', `${baseRef}...HEAD`]))
+      .split('\n').map(s => s.trim()).filter(Boolean);
+  } catch (e) {
+    console.error(`git diff against "${baseRef}" failed: ${String(e.message || e).split('\n')[0]}`);
+    process.exit(1);
+  }
+  if (!changed.length) { console.log('_No changed files — no brain context to attach._'); return; }
+
+  const { format } = await loadEngine();
+  const { struct } = await format.parseKlypix(fs.readFileSync(brain));
+
+  const perFile = new Map();   // file -> [card first lines]
+  let total = 0;
+  for (const file of changed) {
+    const slug = fileSlug(file);
+    if (!slug) continue;
+    const tag = `#file-${slug}`;
+    const hits = [];
+    for (const card of struct.cards) {
+      const text = String(card.text || card.title || '');
+      const idx = text.indexOf(tag);
+      if (idx < 0) continue;
+      // Tag boundary: the next char must not extend the slug (avoids
+      // #file-use matching #file-usechat).
+      const after = text[idx + tag.length];
+      if (after && /[a-z0-9-]/.test(after)) continue;
+      hits.push(firstLine(text));
+      if (hits.length >= 3) break;   // cap per file; total notice below
+    }
+    if (hits.length) { perFile.set(file, hits); total += hits.length; }
+  }
+
+  if (!perFile.size) {
+    console.log(`_No brain cards reference the ${changed.length} changed file(s)._`);
+    return;
+  }
+
+  const out = [`### 🧠 Brain context for this PR`, '',
+    `Decisions and findings already recorded about the files this PR touches (${perFile.size} of ${changed.length} changed files have brain context):`, ''];
+  let printed = 0;
+  const FILE_CAP = 12;
+  let fileIdx = 0;
+  for (const [file, hits] of perFile) {
+    if (fileIdx >= FILE_CAP) break;
+    fileIdx++;
+    out.push(`**\`${file}\`**`);
+    for (const h of hits) { out.push(`- ${h}`); printed++; }
+    out.push('');
+  }
+  if (perFile.size > FILE_CAP) out.push(`…and ${perFile.size - FILE_CAP} more file(s) with brain context.`);
+  out.push(`_From \`${path.relative(toplevel, brain).replace(/\\/g, '/')}\` — the project's shared brain. ${printed} card(s) shown._`);
+  console.log(out.join('\n'));
+}
+
+// ── entry ───────────────────────────────────────────────────────────────────
+
+export async function run(verb, rawArgs) {
+  args = Array.isArray(rawArgs) ? rawArgs : [];
+  positional = args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--brain');
+  try {
+    if (verb === 'git-driver') await gitDriver();
+    else if (verb === 'diff') await brainDiff();
+    else if (verb === 'pr-brief') await prBrief();
+    else { console.error(`klypix-git-tools: unknown verb "${verb}"`); process.exit(2); }
+  } catch (e) {
+    console.error(`${verb} failed: ${String(e?.message || e).split('\n')[0]}`);
+    process.exit(1);
+  }
+}

package/bin/klypix-mcp.mjs

@@ -19,7 +19,7 @@ const PKG_VERSION = (() => {
   }
 })();
 
-const DIRECT = new Set(['install', 'link', 'doctor', 'conformance', 'garden-code', 'init']);
+const DIRECT = new Set(['install', 'link', 'doctor', 'conformance', 'garden-code', 'init', 'git-driver', 'diff', 'pr-brief']);
 
 const USAGE = [
   `klypix-mcp ${PKG_VERSION} — shared project brain + MCP coordination server.`,
@@ -31,6 +31,9 @@ const USAGE = [
   '  conformance [--json]                launch two real MCP clients against this build',
   '  init                                seed a starter ./brain.klypix + print an MCP config',
   '  garden-code [brain]                 print the human approval code for brain_garden',
+  '  git-driver [install|status] [repo]  register the lossless .klypix merge driver for a repo (zero-command teams)',
+  '  diff [ref] [--brain <path>]         readable brain diff vs a git ref (default HEAD) — markdown to stdout',
+  '  pr-brief [baseRef] [--brain <path>] brain decisions touching the files changed since baseRef — PR-comment markdown',
   '',
   'With no verb (or any --flag, e.g. --vault <dir>) it runs as an MCP stdio server.',
   'There is no uninstall command — removal is manual (see README).',

package/bin/klypix-pr-brief.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Thin bin for `klypix-mcp pr-brief` — the worker dispatcher splices the verb out
+// of argv before importing, so this bin re-supplies it. Standalone use works
+// identically: node bin/klypix-pr-brief.mjs <args>
+import { run } from './klypix-git-tools.mjs';
+await run('pr-brief', process.argv.slice(2));

package/bin/klypix-worker.mjs

@@ -102,6 +102,14 @@ await runVerb('doctor', './klypix-doctor.mjs');
 // overlap detection, proactive logging, and guaranteed next-action delivery.
 await runVerb('conformance', './klypix-conformance.mjs');
 
+// `npx klypix-mcp git-driver | diff | pr-brief` — the GitHub lane: register the
+// lossless .klypix merge driver for any repo, render a readable brain diff vs a
+// git ref, and print the brain cards touching a PR's changed files. One module,
+// three verbs (it reads argv[2] itself).
+await runVerb('git-driver', './klypix-git-driver.mjs');
+await runVerb('diff', './klypix-diff.mjs');
+await runVerb('pr-brief', './klypix-pr-brief.mjs');
+
 // `npx klypix-mcp garden-code` — the HUMAN half of the garden approval gate.
 // brain_garden's apply requires an 8-char code derived from the exact dormant
 // candidate set + day; the agent is deliberately never shown it. The human runs

package/examples/github/brain-pr.yml

@@ -0,0 +1,68 @@
+# Brain-aware pull requests — copy this file to .github/workflows/brain-pr.yml
+# in any repo whose brain.klypix is committed.
+#
+# On every PR it posts (and keeps updated) ONE sticky comment with:
+#   1. the brain decisions/corrections that reference the files the PR touches
+#      (evidence tags: #file-<name> inside cards), and
+#   2. a readable card-level diff of the brain itself, when the PR changes it.
+#
+# Nothing here talks to any KLYPIX service — the brain is read from the
+# checkout, exactly as your agents read it. Requires only the default
+# GITHUB_TOKEN with pull-requests: write.
+
+name: brain-pr
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  brain-context:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0            # pr-brief and diff need the base ref
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Build the comment
+        id: brain
+        env:
+          BASE: ${{ github.event.pull_request.base.sha }}
+        run: |
+          {
+            npx --yes klypix-mcp pr-brief "$BASE" || true
+            echo ""
+            # Only show the brain diff when the PR actually changes the brain.
+            if git diff --name-only "$BASE"...HEAD | grep -q '\.klypix$'; then
+              npx --yes klypix-mcp diff "$BASE" || true
+            fi
+          } > brain-comment.md
+          # Skip the comment entirely when there is nothing to say.
+          if ! grep -qE '🧠' brain-comment.md; then
+            echo "post=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "post=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Post / update the sticky comment
+        if: steps.brain.outputs.post == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR: ${{ github.event.pull_request.number }}
+        run: |
+          MARKER="<!-- klypix-brain-pr -->"
+          printf '%s\n\n' "$MARKER" | cat - brain-comment.md > body.md
+          EXISTING=$(gh api "repos/${GITHUB_REPOSITORY}/issues/${PR}/comments" \
+            --jq ".[] | select(.body | startswith(\"$MARKER\")) | .id" | head -1)
+          if [ -n "$EXISTING" ]; then
+            gh api -X PATCH "repos/${GITHUB_REPOSITORY}/issues/comments/${EXISTING}" -F body=@body.md > /dev/null
+          else
+            gh pr comment "$PR" --body-file body.md > /dev/null
+          fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.46.0",
+  "version": "1.48.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -47,6 +47,7 @@
     "./core": "./src/klypix-core.mjs",
     "./presence": "./src/agent-presence.mjs",
     "./mcp-presence": "./src/mcp-presence.mjs",
+    "./presence-relay": "./src/presence-relay.mjs",
     "./supervisor": "./src/mcp-supervisor.mjs",
     "./auto-update": "./src/mcp-auto-update.mjs"
   },
@@ -65,7 +66,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/format-guard.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/presence-relay.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/git-tools.mjs && node test/uninstall.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.4",