klypix-mcp 1.45.1 → 1.47.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.45.1",
+  "version": "1.47.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/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/uninstall.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.4",

package/src/agent-presence.mjs

@@ -268,6 +268,87 @@ export function upsertSession({
   }
 }
 
+// ── Cross-PC remote rows (presence-relay.mjs is the only intended caller) ───
+// Writes rows RECEIVED from the cloud presence channel into the same per-brain
+// lane every reader already renders (peer footer, brain_sync peers, overlap
+// conflicts, doctor) — one rendering path, zero reader changes. Precedence is
+// explicit (D3, 2026-08-01): a row claiming THIS machine is refused (own-echo
+// insurance beyond the frame-level drop), and a session id that already exists
+// as a LOCAL row is never overwritten by a cloud frame — a session on this
+// machine renders once, as local. Rows land with via:'cloud' + channelSeen.cloud
+// so existing TTL pruning governs their lifetime (P3) and buildPresenceFrame
+// refuses to re-broadcast them (loop prevention).
+export function upsertRemoteSessions({ brainPath, rows, machineId = MACHINE_ID, home, now = Date.now() }) {
+  if (!brainPath || !Array.isArray(rows) || !rows.length) return withWriteVerdict([], false, 'nothing-to-write');
+  const laneFile = laneFileFor(brainPath, home);
+  const lockFile = laneFile + '.lock';
+  const gotLock = acquireLock(lockFile);
+  if (!gotLock) return withWriteVerdict(listActiveSessions({ brainPath, home, now }), false, 'lane-locked');
+  try {
+    const data = readLane(laneFile);
+    const sessions = pruneSessions(data.sessions, now);
+    for (const row of rows) {
+      if (!row?.id || !row.machine || row.via !== 'cloud') continue;
+      if (String(row.machine) === String(machineId)) continue;   // never a remote row for this machine
+      const existingIdx = sessions.findIndex((session) => session.id === row.id);
+      if (existingIdx >= 0 && sessions[existingIdx].via !== 'cloud') continue;   // local row wins
+      const previous = existingIdx >= 0 ? sessions[existingIdx] : {};
+      const next = {
+        ...previous,
+        id: String(row.id),
+        project: path.basename(path.dirname(brainPath)),
+        client: String(row.client || previous.client || 'unknown'),
+        surface: row.surface ?? previous.surface ?? null,
+        branch: row.branch ?? previous.branch ?? null,
+        intent: String(row.intent || '').slice(0, 160),
+        files: normalizeFiles(row.files),
+        machine: String(row.machine),
+        host: row.host ?? previous.host ?? null,
+        via: 'cloud',
+        channels: ['cloud'],
+        channelSeen: { cloud: now },   // receiver clock (P4) — frame time never decides freshness
+        startedAt: previous.startedAt || now,
+        lastSeen: now,
+      };
+      if (existingIdx >= 0) sessions[existingIdx] = next;
+      else sessions.push(next);
+    }
+    fs.mkdirSync(path.dirname(laneFile), { recursive: true });
+    fs.writeFileSync(laneFile, JSON.stringify({
+      ...data,
+      sessions: sessions.slice(-40),
+      messages: capMessages(pruneMessages(data.messages, now), 30),
+    }));
+    return withWriteVerdict(sessions.sort((a, b) => Number(b.lastSeen || 0) - Number(a.lastSeen || 0)), true);
+  } finally {
+    if (gotLock) releaseLock(lockFile);
+  }
+}
+
+// Consent revoked, or the channel deliberately left: receive-display stops too
+// (symmetric consent, P9). Removes ONLY cloud-sourced rows — local presence is
+// untouched, so degradation lands exactly on today's local-only behavior.
+export function purgeRemoteSessions({ brainPath, home, now = Date.now() }) {
+  if (!brainPath) return [];
+  const laneFile = laneFileFor(brainPath, home);
+  const lockFile = laneFile + '.lock';
+  const gotLock = acquireLock(lockFile);
+  if (!gotLock) return listActiveSessions({ brainPath, home, now });
+  try {
+    const data = readLane(laneFile);
+    const sessions = pruneSessions(data.sessions, now).filter((session) => session.via !== 'cloud');
+    fs.mkdirSync(path.dirname(laneFile), { recursive: true });
+    fs.writeFileSync(laneFile, JSON.stringify({
+      ...data,
+      sessions,
+      messages: capMessages(pruneMessages(data.messages, now), 30),
+    }));
+    return sessions;
+  } finally {
+    if (gotLock) releaseLock(lockFile);
+  }
+}
+
 export function removeSession({ brainPath, id, channel = null, home, now = Date.now() }) {
   if (!brainPath || !id) return [];
   const laneFile = laneFileFor(brainPath, home);

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);
@@ -4617,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)',

package/src/presence-relay.mjs

@@ -0,0 +1,250 @@
+// Cross-PC presence relay core — PURE frame logic, no IO of any kind.
+//
+// Extends the machine-local presence lane (agent-presence.mjs) across machines:
+// Dev A's sessions and Dev B's sessions on the same shared brain surface each
+// other's declared intent, expected files, and one-line messages. The transport
+// (one Supabase Realtime channel per shared brain, keyed by the Brain Sync
+// blobId stamped in the brain manifest — brain-sync-core.mjs readCloudLink) is
+// OWNED BY THE DESKTOP APP; this module only builds, validates, and merges the
+// frames that ride it, so every rule here is unit-testable with a mock channel.
+//
+// GOVERNING PROPERTIES (do not weaken):
+//   1. Presence is ADVISORY and EPHEMERAL. It never blocks, never gates a
+//      write, and writes NOTHING to any brain file — its worst failure is a
+//      missing or stale advisory, never corruption. This module deliberately
+//      imports only node:crypto (test/presence-relay.mjs asserts it): no fs,
+//      no network, no brain format API can even be reached from here.
+//   2. METADATA ONLY. A frame carries at most: session id, hashed machine id,
+//      host label, client, surface, branch, the one-line declared intent,
+//      canonical repo-relative expected-file keys, and an informational send
+//      time. Never cwd, pid, card text, file contents, diffs, or screen data.
+//      buildPresenceFrame constructs by WHITELIST — unknown row fields cannot
+//      leak because nothing copies them.
+//   3. DEFAULT OFF, symmetric consent. presenceConsentAllows() gates BOTH
+//      directions at this seam (relayOutbound / relayInbound): no consent
+//      record ⇒ zero outbound frames AND no receive-display of others.
+//   4. Receiver-clock truth (P4): a peer's freshness is stamped with the
+//      RECEIVER's clock at accept time. frame.sentAt is informational only —
+//      a machine with a wrong clock can neither appear permanently fresh nor
+//      permanently stale.
+//   5. Old clients never crash on new frames (P7): every accept function
+//      returns null for an unknown wire version or malformed frame, silently.
+import crypto from 'crypto';
+
+export const PRESENCE_WIRE_VERSION = 1;
+export const PRESENCE_HEARTBEAT_MS = 60_000;
+// Consent record contract (mirrors src/services/screenCloudConsent.ts in the
+// desktop app: versioned, revocable, default-off, checked at send time).
+export const PRESENCE_CONSENT_VERSION = 1;
+export const PRESENCE_CONSENT_PURPOSE = 'session-presence';
+export const PRESENCE_CONSENT_SCOPE = 'metadata-only';
+// Cross-PC lane-message dedup prefix: also the marker that stops a received
+// message from being re-broadcast (loop prevention for the message lane).
+export const XPC_DEDUPE_PREFIX = 'xpc:';
+
+const sha16 = (value) => crypto.createHash('sha1').update(String(value)).digest('hex').slice(0, 16);
+const compact = (value) => String(value || '').replace(/\s+/g, ' ').trim();
+const str = (value, max) => compact(value).slice(0, max);
+
+// Canonical wire form of an expected-file declaration: repo-relative, lowercase,
+// forward slashes — the SAME fold mcp-presence.mjs normalizeFileKey applies at
+// compare time, applied at SEND time so two machines with different clone roots
+// ("E:/work/repo" vs "/home/dev/repo") produce identical keys. A path that
+// cannot be placed under `root` is DROPPED from the wire (unlike the local
+// comparator, which keeps it): an absolute path outside the repo is local
+// machine structure — usernames, drive layout — and metadata-only (property 2)
+// wins over completeness for anything that leaves the machine.
+export function canonicalWireFiles(files, root) {
+  const rootKey = String(root || '')
+    .replace(/\\/g, '/')
+    .replace(/\/+$/, '')
+    .trim()
+    .toLowerCase();
+  const out = [];
+  const seen = new Set();
+  for (const file of Array.isArray(files) ? files : []) {
+    const raw = String(file || '')
+      .replace(/\\/g, '/')
+      .replace(/^\.\//, '')
+      .trim()
+      .toLowerCase();
+    if (!raw) continue;
+    let key = raw;
+    if (/^([a-z]:)?\//.test(raw)) {
+      if (!rootKey || !raw.startsWith(`${rootKey}/`)) continue;   // outside the repo — never leaves the machine
+      key = raw.slice(rootKey.length + 1);
+    }
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    out.push(key);
+  }
+  return out.slice(0, 20);
+}
+
+// One lane row → one wire frame, or null when the row must not be broadcast:
+// a row this relay itself wrote from the channel (via:'cloud') would loop, and
+// a row with no session id is unaddressable. Constructed by whitelist — this
+// is the ONLY place a frame is assembled, so the metadata-only guarantee is
+// structural, not a filter that can miss a field.
+export function buildPresenceFrame(session, { machineId, hostLabel = null, root = null, now = Date.now() } = {}) {
+  if (!session || !session.id || !machineId) return null;
+  if (session.via === 'cloud') return null;   // loop prevention: never re-broadcast a received row
+  return {
+    v: PRESENCE_WIRE_VERSION,
+    kind: 'presence',
+    sid: str(session.id, 64),
+    machine: str(machineId, 40),
+    host: hostLabel ? str(hostLabel, 40) : null,
+    client: str(session.client || 'unknown', 40),
+    surface: session.surface ? str(session.surface, 40) : null,
+    branch: session.branch ? str(session.branch, 80) : null,
+    intent: str(session.intent, 160),
+    files: canonicalWireFiles(session.files, root),
+    sentAt: Number(now) || Date.now(),          // informational only — see property 4
+  };
+}
+
+// One received frame → one lane row, or null (silently) when the frame is not
+// ours to render: unknown wire version (P7 — an old client must never crash on
+// a new schema, and vice versa), malformed, or an echo of this machine's own
+// broadcast (loop prevention + D3 precedence: a session on THIS machine renders
+// once, as local). lastSeen/channelSeen are stamped with the RECEIVER's clock.
+export function acceptPresenceFrame(frame, { machineId, now = Date.now() } = {}) {
+  if (!frame || typeof frame !== 'object') return null;
+  if (frame.v !== PRESENCE_WIRE_VERSION || frame.kind !== 'presence') return null;
+  const sid = str(frame.sid, 64);
+  const machine = str(frame.machine, 40);
+  if (!sid || !machine) return null;
+  if (machineId && machine === String(machineId)) return null;   // own echo
+  return {
+    id: sid,
+    client: str(frame.client || 'unknown', 40) || 'unknown',
+    surface: frame.surface ? str(frame.surface, 40) : null,
+    branch: frame.branch ? str(frame.branch, 80) : null,
+    intent: str(frame.intent, 160),
+    files: canonicalWireFiles(frame.files, null),
+    machine,
+    host: frame.host ? str(frame.host, 40) : null,
+    via: 'cloud',
+    lastSeen: now,
+  };
+}
+
+// One lane message → one wire frame, or null when it must not cross machines:
+// a message this relay injected FROM the channel (xpc: dedupe key) would loop.
+export function buildMessageFrame(message, { machineId, now = Date.now() } = {}) {
+  if (!message || !machineId) return null;
+  if (String(message.dedupeKey || '').startsWith(XPC_DEDUPE_PREFIX)) return null;
+  const text = str(message.text, 400);
+  const from = str(message.from, 64);
+  if (!text || !from) return null;
+  return {
+    v: PRESENCE_WIRE_VERSION,
+    kind: 'message',
+    machine: str(machineId, 40),
+    from,
+    to: str(message.to, 160) || 'all',
+    text,
+    sentAt: Number(message.ts) || Number(now) || Date.now(),
+  };
+}
+
+// One received message frame → arguments for agent-presence postPresenceMessage,
+// or null. The dedupe key is (origin session id + content hash), NOT a message
+// id: an at-least-once transport may re-deliver the same content under a new
+// envelope, and it must still render exactly once (P5). postPresenceMessage's
+// existing dedupeKey mechanism enforces it under the lane lock.
+export function acceptMessageFrame(frame, { machineId } = {}) {
+  if (!frame || typeof frame !== 'object') return null;
+  if (frame.v !== PRESENCE_WIRE_VERSION || frame.kind !== 'message') return null;
+  const machine = str(frame.machine, 40);
+  const from = str(frame.from, 64);
+  const text = str(frame.text, 400);
+  if (!machine || !from || !text) return null;
+  if (machineId && machine === String(machineId)) return null;   // own echo
+  return {
+    from,
+    to: str(frame.to, 160) || 'all',
+    text,
+    dedupeKey: `${XPC_DEDUPE_PREFIX}${sha16(`${machine}|${from}|${text.toLowerCase()}`)}`,
+  };
+}
+
+// Versioned, revocable, default-OFF consent — the shape the desktop stores per
+// linked brain (klypix:brainPresenceConsent:v1:<blobId>). Anything short of an
+// explicit, current-version grant is a NO: null record (never asked), wrong
+// version (re-consent after a scope change), wrong purpose/scope, revoked.
+export function presenceConsentAllows(record) {
+  return Boolean(
+    record
+    && typeof record === 'object'
+    && record.version === PRESENCE_CONSENT_VERSION
+    && record.decision === 'granted'
+    && record.purpose === PRESENCE_CONSENT_PURPOSE
+    && record.scope === PRESENCE_CONSENT_SCOPE,
+  );
+}
+
+// Which lane messages are due for broadcast: authored on this machine (never
+// xpc:-injected), newer than the caller's cursor. The caller advances the
+// cursor to the max ts it sent — re-pumps then skip already-sent content, and
+// even a re-send is harmless (receiver dedup, P5).
+export function selectOutboundMessages(messages, { sinceTs = 0 } = {}) {
+  return (Array.isArray(messages) ? messages : [])
+    .filter((message) => message
+      && Number(message.ts || 0) > Number(sinceTs || 0)
+      && !String(message.dedupeKey || '').startsWith(XPC_DEDUPE_PREFIX));
+}
+
+// ── The transport seam ───────────────────────────────────────────────────────
+// The desktop relay calls exactly these two functions around its Realtime
+// channel; the conformance harness calls them around a mock. Consent is
+// checked HERE, per call, in both directions — so "no consent ⇒ zero outbound
+// frames" and "no consent ⇒ no receive-display" are assertable at this seam
+// (acceptance gate 3), and a mid-session revoke takes effect on the next
+// heartbeat/frame with no further wiring (P9).
+
+export function relayOutbound({
+  sessions = [],
+  messages = [],
+  consent = null,
+  machineId,
+  hostLabel = null,
+  root = null,
+  sinceTs = 0,
+  now = Date.now(),
+  send,
+} = {}) {
+  if (!presenceConsentAllows(consent)) return { sent: 0, reason: 'no-consent', maxMessageTs: sinceTs };
+  if (typeof send !== 'function') return { sent: 0, reason: 'no-channel', maxMessageTs: sinceTs };
+  let sent = 0;
+  let maxMessageTs = Number(sinceTs || 0);
+  for (const session of Array.isArray(sessions) ? sessions : []) {
+    const frame = buildPresenceFrame(session, { machineId, hostLabel, root, now });
+    if (!frame) continue;
+    send(frame);
+    sent++;
+  }
+  for (const message of selectOutboundMessages(messages, { sinceTs })) {
+    const frame = buildMessageFrame(message, { machineId, now });
+    if (!frame) continue;
+    send(frame);
+    sent++;
+    maxMessageTs = Math.max(maxMessageTs, Number(message.ts || 0));
+  }
+  return { sent, reason: null, maxMessageTs };
+}
+
+export function relayInbound(frame, { consent = null, machineId, now = Date.now() } = {}) {
+  if (!presenceConsentAllows(consent)) return null;   // symmetric: no consent ⇒ no receive-display
+  if (!frame || typeof frame !== 'object') return null;
+  if (frame.kind === 'presence') {
+    const row = acceptPresenceFrame(frame, { machineId, now });
+    return row ? { type: 'presence', row } : null;
+  }
+  if (frame.kind === 'message') {
+    const message = acceptMessageFrame(frame, { machineId });
+    return message ? { type: 'message', message } : null;
+  }
+  return null;   // unknown kind — a future schema this build doesn't know (P7)
+}