klypix-mcp 1.103.0 → 1.104.0

package/README.md

@@ -515,6 +515,33 @@ so fresh relevant findings are not crowded out by older area vocabulary.
 Briefs are **not** injected automatically on Cursor, Cline, Copilot, Gemini CLI or Antigravity —
 there are no lifecycle hooks on those hosts.
 
+### The live projection — the file the agent obeys
+
+The coordination bench showed that an agent trusts the instruction file it was launched with
+over anything a tool or hook tells it, and that each host reads a different surface. So the
+brain's state is projected into those files, in two halves:
+
+- **Committed, from the brain:** the compact brief block in `AGENTS.md` (standing rules,
+  corrections, open handoff cards), refreshed by the Claude Code Stop hook only when its content
+  changed, so diffs stay quiet.
+- **Machine-local, from the lane (klypix-mcp 1.104.0):** which sessions are live on this PC and
+  which files they hold, the work a stopped session left, and the evidence beside every
+  "keep off this file" note — written at session start and at every Stop by the Claude Code and
+  Codex hooks into `CLAUDE.local.md` at the project root (Claude Code loads it beside
+  `CLAUDE.md`; KLYPIX keeps it out of git through `.git/info/exclude`, never a committed file)
+  and into one section per project of the Codex global instructions file
+  (`~/.codex/AGENTS.override.md` when you have one, else `~/.codex/AGENTS.md`). A project-level
+  `AGENTS.override.md` is never written: Codex loads one file per directory, so it would hide
+  your `AGENTS.md`.
+
+The block is a snapshot and says so: bounded to about 2.4KB, rewritten only when its content
+changed (the time stamp alone never causes a write), with the keep-off evidence kept first when
+the budget bites, and "nothing live" written in words so an older snapshot never stands. It
+holds the same strings the hooks print, so the file and the session context cannot disagree.
+Sections for projects not touched in a day are pruned from the Codex file, at most eight are
+kept, and `uninstall unlink` strips the block (deleting `CLAUDE.local.md` only when nothing else
+is in it). `brain_sync` remains the live source; the block tells the agent to call it.
+
 ## Capture and corrections
 
 `brain_note` accepts structured supporting references and inert verification text:
@@ -1350,7 +1377,10 @@ It strips only KLYPIX's own entries — every other hook and setting in
 `~/.claude/settings.json` stays — backs up each file it edits, and **never deletes a `.klypix`**.
 Removal requires `--yes`. Without it, the command prints the plan and changes nothing;
 there is no interactive confirmation prompt. Run the project-local form in each project you
-want to unlink. A preview exits non-zero while managed files remain.
+want to unlink. A preview exits non-zero while managed files remain. The project-local form also
+strips the live-projection block from `CLAUDE.local.md` (the file goes only when nothing else is
+in it) and this project's section from the Codex global file; the machine-global form strips
+every live section there.
 
 Your `brain.klypix` is yours — it is a plain ZIP and stays readable with or without this package.
 

package/bin/klypix-install.mjs

@@ -495,7 +495,7 @@ try {
     // a newer klypix-format cannot. merge-brains and the driver ship here so
     // brain-history's restore merge, the KLYPIX core and the git driver all
     // find one engine in this directory.
-    for (const f of ['global-brain-hook.mjs', 'klypix-format.mjs', 'brain-graveyard.mjs', 'merge-brains.mjs', 'klypix-merge-driver.mjs', 'capture-gap.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'enrichment.mjs', 'provenance.mjs', 'brain-note.mjs', 'brain-evidence.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'app-lease.mjs', 'klypix-core.mjs', 'app-bridge-protocol.mjs', 'app-bridge-client.mjs', 'app-tools.mjs', 'card-files.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'editor-detect.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'repo-state.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'session-handoff.mjs', 'canvas-view-app.html']) {
+    for (const f of ['global-brain-hook.mjs', 'klypix-format.mjs', 'brain-graveyard.mjs', 'merge-brains.mjs', 'klypix-merge-driver.mjs', 'capture-gap.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'enrichment.mjs', 'provenance.mjs', 'brain-note.mjs', 'brain-evidence.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'app-lease.mjs', 'klypix-core.mjs', 'app-bridge-protocol.mjs', 'app-bridge-client.mjs', 'app-tools.mjs', 'card-files.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'editor-detect.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'repo-state.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'session-handoff.mjs', 'live-projection.mjs', 'canvas-view-app.html']) {
         const s = path.join(SRC, f); if (exists(s)) staged.push({ dst: f, content: fs.readFileSync(s, 'utf8') });
     }
     for (const [src, dst] of [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.103.0",
+  "version": "1.104.0",
   "mcpName": "io.github.dahshanlabs/klypix-mcp",
   "description": "Shared project memory for Claude Code, Codex and Cursor: decisions and corrections through MCP.",
   "type": "module",
@@ -91,7 +91,7 @@
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
     "pretest": "node test/publish-workflow.mjs",
-    "test": "node test/publish-verdict.mjs && node test/npx-owned-names.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/session-mailbox.mjs && node test/session-reopen.mjs && node test/session-handoff.mjs && node test/lock-notes.mjs && node test/lane-write-retry.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/brain-ask-words.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.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/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.mjs && node test/arrange-receipts.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/semantic-preparation.mjs && node test/semantic-hash-parity.mjs && node test/enrichment.mjs && node test/provenance.mjs && node test/confirm-trail.mjs && node test/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/hook-unified-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/marker-suffix-grammar.mjs && node test/marker-after-colon.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/overlap-tiers.mjs && node test/coordination-bench.mjs && node test/release-lease.mjs && node test/release-reconcile.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/results-not-manifests.mjs && node test/merge-brains.mjs && node test/merge-readings.mjs && node test/revival-map.mjs && node test/merge-scale.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/link-compat.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/current-first.mjs && node test/status-shape.mjs && node test/status-hook.mjs && node test/read-canvas-saved-readings.mjs && node test/document-readings.mjs && node test/open-lease.mjs && node test/agent-card-style.mjs && node test/tool-schema-freeze.mjs && node test/app-lease-vectors.mjs && node test/app-tools-stdio.mjs && node test/card-contents-files.mjs && node test/codex-app-table.mjs && node test/plugin-mode.mjs && node test/app-bridge-vectors.mjs && node test/app-bridge-client.mjs && node test/app-tools-static.mjs && node test/app-tools-stdio-live.mjs",
+    "test": "node test/publish-verdict.mjs && node test/npx-owned-names.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/session-mailbox.mjs && node test/session-reopen.mjs && node test/session-handoff.mjs && node test/lock-notes.mjs && node test/live-projection.mjs && node test/lane-write-retry.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/brain-ask-words.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.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/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.mjs && node test/arrange-receipts.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/semantic-preparation.mjs && node test/semantic-hash-parity.mjs && node test/enrichment.mjs && node test/provenance.mjs && node test/confirm-trail.mjs && node test/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/hook-unified-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/marker-suffix-grammar.mjs && node test/marker-after-colon.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/overlap-tiers.mjs && node test/coordination-bench.mjs && node test/release-lease.mjs && node test/release-reconcile.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/results-not-manifests.mjs && node test/merge-brains.mjs && node test/merge-readings.mjs && node test/revival-map.mjs && node test/merge-scale.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/link-compat.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/current-first.mjs && node test/status-shape.mjs && node test/status-hook.mjs && node test/read-canvas-saved-readings.mjs && node test/document-readings.mjs && node test/open-lease.mjs && node test/agent-card-style.mjs && node test/tool-schema-freeze.mjs && node test/app-lease-vectors.mjs && node test/app-tools-stdio.mjs && node test/card-contents-files.mjs && node test/codex-app-table.mjs && node test/plugin-mode.mjs && node test/app-bridge-vectors.mjs && node test/app-bridge-client.mjs && node test/app-tools-static.mjs && node test/app-tools-stdio-live.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs",

package/src/codex-brain-hook.mjs

@@ -385,7 +385,7 @@ function unfinishedWorkBlock(brainPath, sessionId) {
 // a "do not touch" / hands-off / WIP line in AGENTS.md checked against live
 // sessions, local branches and uncommitted changes. Dynamic import so a stale
 // deployment without it no-ops; never throws.
-async function lockNotesBlock(projectDir, brainPath, sessionId, sessions) {
+async function lockNotesBlock(projectDir, brainPath, sessionId, sessions, { budgetMs } = {}) {
   try {
     const lib = await import(new URL('./session-handoff.mjs', import.meta.url).href);
     if (typeof lib.readLockNotes !== 'function') return '';
@@ -393,7 +393,7 @@ async function lockNotesBlock(projectDir, brainPath, sessionId, sessions) {
     try { stopped = listUnfinishedWork({ brainPath, selfId: sessionId }); } catch { /* git still answers */ }
     // Lines naming a file a stopped session worked on ride too, whatever their wording.
     const mentions = [...new Set(stopped.flatMap((r) => (Array.isArray(r.files) ? r.files : [])))].slice(0, 20);
-    const probe = lib.createLockNoteProbe(projectDir);
+    const probe = lib.createLockNoteProbe(projectDir, budgetMs ? { budgetMs } : {});
     const notes = lib.readLockNotes(projectDir, { mentions, probe });
     if (!notes.length) return '';
     const assessed = notes.slice(0, 6).map((n) => lib.assessLockNote(projectDir, n, { live: sessions || [], stopped, selfId: sessionId ? [sessionId] : [], probe }));
@@ -403,6 +403,22 @@ async function lockNotesBlock(projectDir, brainPath, sessionId, sessions) {
   }
 }
 
+// Live projection (1.104.0): the same presence / unfinished / keep-off strings
+// this hook emits, written into CLAUDE.local.md and the Codex global
+// instructions file for the NEXT session of any host (session start and Stop).
+// Dynamic import so a stale deployment no-ops; never throws.
+async function projectLiveSafe({ projectDir, sessions, sessionId, lockNotes = '', unfinished = '' }) {
+  try {
+    const lib = await import(new URL('./live-projection.mjs', import.meta.url).href);
+    if (typeof lib.projectLive !== 'function') return null;
+    const peers = (Array.isArray(sessions) ? sessions : []).filter((s) => s && s.id && s.id !== sessionId)
+      .map((s) => ({ id: s.id, client: s.client, intent: s.intent, files: s.files, observedFiles: s.observedFiles }));
+    return lib.projectLive({ projectDir, peers, lockNotesText: String(lockNotes || '').trim(), unfinishedText: String(unfinished || '').trim() });
+  } catch {
+    return null;
+  }
+}
+
 // Unfinished-work patch for one Codex lifecycle event (session handoff). A
 // human prompt records what was asked; a Stop records the reply tail only if
 // the host put it in the payload. Null when the event carries nothing.
@@ -587,6 +603,8 @@ async function main() {
       } catch { return ''; }
     })();
     const lockNotes = await lockNotesBlock(projectDir, brainPath, sessionId, sessions);
+    const unfinished = unfinishedWorkBlock(brainPath, sessionId);
+    await projectLiveSafe({ projectDir, sessions, sessionId, lockNotes, unfinished });
     emitSystemMessage([
       formatPresenceMessage(sessions, sessionId, { includeSolo: true }),
       lockNotes,
@@ -600,10 +618,16 @@ async function main() {
       // ⏸️ Unfinished work other sessions left (session handoff, 1.99.0): the
       // same engine block brain_sync prints, so a Codex session asked to
       // "continue" what a Claude session stopped in starts from its record.
-      unfinishedWorkBlock(brainPath, sessionId),
+      unfinished,
     ], event);
     return;
   }
+  if (event === 'Stop') {
+    // The lane now carries this turn's files and reply tail: refresh the live
+    // projection for the next session, with a short git budget (a Stop must not wait).
+    const lockNotes = await lockNotesBlock(projectDir, brainPath, sessionId, sessions, { budgetMs: 1000 });
+    await projectLiveSafe({ projectDir, sessions, sessionId, lockNotes, unfinished: unfinishedWorkBlock(brainPath, sessionId) });
+  }
   if (event === 'UserPromptSubmit') {
     const me = sessions.find((session) => session.id === sessionId);
     // A STRONG status question is answered from computed state and REPLACES

package/src/global-brain-hook.mjs

@@ -1571,7 +1571,7 @@ function unfinishedFooter(sid, { max = 4 } = {}) {
 // live sessions, local branches and uncommitted changes — at session start,
 // before the agent decides to obey or ignore it. Same code as brain_sync
 // (session-handoff.mjs). Never edits the note; '' on any failure.
-async function lockNotesFooter(sid) {
+async function lockNotesFooter(sid, { budgetMs } = {}) {
     try {
         const lib = await import(new URL('./session-handoff.mjs', import.meta.url).href);
         if (typeof lib.readLockNotes !== 'function') return '';
@@ -1586,7 +1586,7 @@ async function lockNotesFooter(sid) {
         // Lines naming a file a stopped session worked on ride too, whatever
         // their wording (bench S5d/S5f: the agent with hooks never asked).
         const mentions = [...new Set(stopped.flatMap(r => Array.isArray(r.files) ? r.files : []))].slice(0, 20);
-        const probe = lib.createLockNoteProbe(CWD);
+        const probe = lib.createLockNoteProbe(CWD, budgetMs ? { budgetMs } : {});
         const notes = lib.readLockNotes(CWD, { mentions, probe });
         if (!notes.length) return '';
         const assessed = notes.slice(0, 6).map(n => lib.assessLockNote(CWD, n, { live, stopped, selfId: sid ? [sid] : [], now, probe }));
@@ -1595,6 +1595,28 @@ async function lockNotesFooter(sid) {
     } catch { return ''; }
 }
 
+// Live projection (1.104.0, bench rounds 2–3): write the machine-local half of
+// the brain's state — who is live on this PC and what they hold, the work a
+// stopped session left, the evidence beside every keep-off note — into the
+// files the hosts load by themselves and never commit (CLAUDE.local.md and the
+// Codex global instructions file), at session start and at every Stop. The
+// inputs are the SAME strings this hook prints, so the file and the context
+// cannot disagree. Dynamic import so a stale flat deployment no-ops; never throws.
+async function writeLiveProjection(sid, { lockText = null, unfinishedText = null, budgetMs } = {}) {
+    try {
+        const lib = await import(new URL('./live-projection.mjs', import.meta.url).href);
+        if (typeof lib.projectLive !== 'function') return null;
+        const lock = lockText === null ? await lockNotesFooter(sid, budgetMs ? { budgetMs } : {}) : lockText;
+        const unfinished = unfinishedText === null ? unfinishedFooter(sid) : unfinishedText;
+        return lib.projectLive({
+            projectDir: CWD,
+            peers: livePeers(sid).map(p => ({ id: p.id, client: p.client, intent: p.intent, files: p.files, observedFiles: p.observedFiles })),
+            lockNotesText: String(lock || '').trim(),
+            unfinishedText: String(unfinished || '').trim(),
+        });
+    } catch { return null; }
+}
+
 // The nudge a session gets when the human asks for a handoff or says the
 // limit is near: the deliberate layer (a 🤝 card in the brain) on top of the
 // automatic state above. One line; the tool's own description carries the rest.
@@ -6185,12 +6207,16 @@ async function read(lib) {
     // The full brief keeps its order.
     const messages = messageFooter(input.session_id || '', input.transcript_path, lib);
     const lockLine = await lockNotesFooter(input.session_id);
+    const unfinishedLine = unfinishedFooter(input.session_id);
     const out = ultra + messages + lockLine + versionLine + presenceLine + shipObsLine + gitHookNotice + laneWarning + healLine + draftLine
         + receiptLine
         + inflightFooter(input.session_id, struct)
-        + unfinishedFooter(input.session_id)
+        + unfinishedLine
         + selfCheckFooter() + doctorFooter();
     process.stdout.write(out);
+    // The same lock / unfinished strings go into CLAUDE.local.md and the Codex
+    // global file for the NEXT session of any host (live projection).
+    await writeLiveProjection(input.session_id, { lockText: lockLine, unfinishedText: unfinishedLine });
     // Heartbeat: prove the brief actually injected (and how big) so a dead or
     // stale live-copy of the hook stops being a silent no-op.
     appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode: 'read', ok: true, briefBytes: Buffer.byteLength(out), fullBriefBytes: Buffer.byteLength(full), cards: struct?.counts?.cards ?? null }, 500);
@@ -6262,6 +6288,9 @@ async function main() {
         // without paying the rebuild itself. Best-effort; guardCheck's currency
         // stat is the backstop.
         try { if (typeof lib.ensureGuardSidecar === 'function') await lib.ensureGuardSidecar(BRAIN); } catch { /* backstopped */ }
+        // Refresh the live projection after the turn: the lane now carries this
+        // session's files and reply tail. A short git budget — a Stop must not wait.
+        await writeLiveProjection(readHookInput().session_id, { budgetMs: 1000 });
         // Ambient version-currency: piggyback the post-session Stop hook to refresh the
         // npm-latest cache (≤ once/day, best-effort, failure-silent) so the next
         // SessionStart footer can surface a stale install with ZERO network. Awaited so

package/src/live-projection.mjs

@@ -0,0 +1,286 @@
+// Live projection (1.104.0) — the machine-local half of "project the brain
+// into the file the agent obeys".
+//
+// WHY. The coordination bench (rounds 2 and 3, 2026-10-12/13) showed that an
+// agent trusts the instruction file it was launched with more than anything a
+// tool or hook tells it: a two-day-old "keep off this file" line in AGENTS.md
+// beat KLYPIX's lane in 14 of 15 runs, and the hosts read different surfaces
+// (Claude the JSON, Codex the text, both the files). The brain-derived half —
+// standing rules, corrections, handoff cards — already lives in the committed
+// `<!-- klypix-brain-brief -->` block of AGENTS.md (refreshAgentsBrief). The
+// LIVE half — which sessions are on this PC right now and what files they
+// hold, what work a stopped session left, and the evidence beside every
+// keep-off note — reached the agent only through hook output and brain_sync,
+// never through a file. This module writes that half into the two files the
+// hosts load by themselves and never commit:
+//
+//   • `CLAUDE.local.md` at the project root — Claude Code loads it beside
+//     CLAUDE.md ("personal project-specific preferences; add to .gitignore");
+//     its HTML comments are stripped before injection, so the markers cost
+//     nothing. KLYPIX keeps it out of git through `.git/info/exclude` (local
+//     to this clone, never a committed file).
+//   • the Codex global instructions file — `~/.codex/AGENTS.override.md` when
+//     the person has one, else `~/.codex/AGENTS.md`, the file klypix-mcp
+//     already manages. Codex loads the global file first, then one file per
+//     directory from the project root down, so a project-level override would
+//     HIDE the project's AGENTS.md: never written. One section per project,
+//     keyed by the project's path, pruned when stale.
+//
+// CONTRACT. Snapshot semantics, said in the text: written at session start and
+// stop, not live, not shared, brain_sync is the live source. Bounded (budget
+// below), deterministic for one input, rewritten only when the non-volatile
+// content changed (the time stamp alone never causes a write). Never throws:
+// every writer returns an action word and swallows its own errors, because it
+// runs inside hooks that must exit 0.
+import crypto from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const LIVE_PROJECTION_VERSION = 1;
+export const LIVE_BUDGET_CHARS = 2400;
+export const LIVE_STALE_MS = 24 * 60 * 60 * 1000;
+export const LIVE_PROJECT_CAP = 8;
+export const CLAUDE_LOCAL_FILE = 'CLAUDE.local.md';
+export const LIVE_END = '<!-- klypix-live:end -->';
+
+const flat = (v) => String(v || '').replace(/\s+/g, ' ').trim();
+const minuteIso = (ms) => new Date(ms).toISOString().slice(0, 16) + 'Z';
+const CLIENT_WORDS = { 'claude-code': 'Claude Code', codex: 'Codex', cursor: 'Cursor', cline: 'Cline', windsurf: 'Windsurf', copilot: 'Copilot', gemini: 'Gemini CLI', aider: 'Aider', antigravity: 'Antigravity' };
+const clientWord = (c) => CLIENT_WORDS[String(c || '').toLowerCase()] || (c ? String(c) : 'agent');
+
+/** Stable key for a project path: same spelling rules as the presence lane. */
+export function liveKey(projectDir) {
+  const norm = path.resolve(String(projectDir || '.')).replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+  return crypto.createHash('sha1').update(norm).digest('hex').slice(0, 16);
+}
+
+export function liveStart(key, { at = Date.now(), projectDir = '' } = {}) {
+  const where = projectDir ? ` project=${JSON.stringify(path.resolve(projectDir).replace(/\\/g, '/'))}` : '';
+  return `<!-- klypix-live:start key=${key} at=${new Date(at).toISOString()}${where} (machine-local; written by klypix-mcp at session start and stop; do not edit; never commit) -->`;
+}
+
+// One regex per key; the marker's attributes are free text up to `-->`.
+const blockRe = (key) => new RegExp(`<!-- klypix-live:start key=${key}[^\\n]*-->[\\s\\S]*?<!-- klypix-live:end -->\\r?\\n?`);
+const ANY_BLOCK_RE = /<!-- klypix-live:start key=([0-9a-f]{16}) at=([^ \n]+)[^\n]*-->[\s\S]*?<!-- klypix-live:end -->\r?\n?/g;
+
+/** Everything in a block that may change without the content changing. */
+function stable(text) {
+  return String(text || '')
+    .replace(/<!-- klypix-live:start key=[0-9a-f]{16} at=[^ \n]+/g, '<!-- klypix-live:start')
+    .replace(/· as of [0-9T:-]+Z/g, '· as of')
+    .replace(/\r\n/g, '\n').trim();
+}
+
+function peerLine(p) {
+  const files = [...new Set([...(Array.isArray(p.files) ? p.files : []), ...(Array.isArray(p.observedFiles) ? p.observedFiles : [])])].filter(Boolean);
+  const bits = [`${clientWord(p.client)} ${String(p.id || '').slice(0, 8)}`];
+  if (p.intent) bits.push(`“${flat(p.intent).slice(0, 70)}”`);
+  if (files.length) bits.push(`files: ${files.slice(0, 4).join(', ')}${files.length > 4 ? ` +${files.length - 4}` : ''}`);
+  return bits.join(' · ');
+}
+
+function clip(text, max) {
+  const t = String(text || '').trim();
+  if (t.length <= max) return t;
+  return t.slice(0, Math.max(0, max - 60)).replace(/\s+\S*$/, '') + '\n  … (cut for size — brain_sync has the rest)';
+}
+
+/**
+ * The block body. Pure: same inputs, same text (the "as of" minute aside).
+ * `peers` are presence-lane rows OTHER than the writing session; `unfinishedText`
+ * and `lockNotesText` are the engine's own blocks (formatUnfinishedWork,
+ * formatLockNotes), passed through so this file never re-derives a verdict.
+ */
+export function renderLiveProjection({ projectDir, now = Date.now(), version = '', peers = [], unfinishedText = '', lockNotesText = '', budgetChars = LIVE_BUDGET_CHARS } = {}) {
+  const name = path.basename(path.resolve(projectDir || '.')) || 'project';
+  const budget = Math.max(800, Math.min(8000, Number(budgetChars) || LIVE_BUDGET_CHARS));
+  const head = [
+    `## KLYPIX live — ${name} on this PC · as of ${minuteIso(now)}`,
+    `Snapshot written by klypix-mcp${version ? ` ${version}` : ''} at session start and stop: this PC only, not committed, not shared. The decisions and corrections are in the AGENTS.md brain block; \`brain_sync\` for this project is the live source and must be called before acting on anything below.`,
+  ];
+  const rows = (Array.isArray(peers) ? peers : []).filter((p) => p && p.id);
+  const peersText = rows.length
+    ? `👥 ${rows.length} other live session(s) on this PC right now (a snapshot — re-query brain_sync before reporting them): ${rows.slice(0, 6).map(peerLine).join(' | ')}${rows.length > 6 ? ` | …and ${rows.length - 6} more` : ''}. A file two sessions both hold is a warning, not a lock: coordinate with brain_message.`
+    : '👥 No other live session on this PC at the time of writing.';
+  const lock = String(lockNotesText || '').trim();
+  const unfinished = String(unfinishedText || '').trim();
+  // Priority when the budget bites: the keep-off evidence first (it is what the
+  // bench lost on), then who is live, then the unfinished work.
+  const fixed = head.join('\n').length + 2;
+  let left = budget - fixed;
+  const lockPart = lock ? clip(lock, Math.max(600, Math.floor(left * 0.6))) : '';
+  left -= lockPart.length + 2;
+  const peersPart = clip(peersText, Math.max(200, Math.min(700, left)));
+  left -= peersPart.length + 2;
+  const unfinishedPart = unfinished ? clip(unfinished, Math.max(240, left)) : '⏸️ No unfinished work recorded from a stopped session.';
+  return [...head, '', peersPart, '', lockPart || '📌 No keep-off note in this project\'s instruction files named a file with a verdict to report.', '', unfinishedPart].join('\n').replace(/\n{3,}/g, '\n\n').trim();
+}
+
+export function wrapLiveBlock(key, body, opts = {}) {
+  return `${liveStart(key, opts)}\n${body}\n${LIVE_END}`;
+}
+
+/** Replace the block with this key in `raw`, or append it. */
+export function upsertLiveBlock(raw, key, block) {
+  const text = String(raw || '');
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const b = block.replace(/\r?\n/g, eol);
+  const re = blockRe(key);
+  if (re.test(text)) return text.replace(re, b + eol);
+  const base = text.trim() ? text.replace(/\s*$/, '') + eol + eol : '';
+  return base + b + eol;
+}
+
+export function stripLiveBlocks(raw, key = null) {
+  const text = String(raw || '');
+  const next = key ? text.replace(blockRe(key), '') : text.replace(ANY_BLOCK_RE, '');
+  return next.replace(/^\s+/, '').replace(/\s+$/, (m) => (m.includes('\n') ? '\n' : ''));
+}
+
+function atomicWrite(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.klypix-tmp-${process.pid}`;
+  fs.writeFileSync(tmp, content, 'utf8');
+  fs.renameSync(tmp, file);
+}
+
+function git(cwd, args, timeout = 1500) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', timeout, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true }).trim();
+}
+
+/**
+ * Keep CLAUDE.local.md out of this clone's git status without touching a
+ * committed file: `.git/info/exclude` (the worktree-aware git-path form). A
+ * project that already ignores it, or is not a repository, is left alone.
+ */
+export function ensureLocalExcluded(projectDir, { rel = CLAUDE_LOCAL_FILE } = {}) {
+  const root = path.resolve(projectDir);
+  try {
+    execFileSync('git', ['check-ignore', '-q', rel], { cwd: root, timeout: 1500, stdio: 'ignore', windowsHide: true });
+    return 'already-ignored';
+  } catch (e) {
+    if (e && e.status !== 1) return 'not-a-repo';
+  }
+  try {
+    const excludeRel = git(root, ['rev-parse', '--git-path', 'info/exclude']);
+    const exclude = path.isAbsolute(excludeRel) ? excludeRel : path.join(root, excludeRel);
+    let raw = '';
+    try { raw = fs.readFileSync(exclude, 'utf8'); } catch { /* fresh */ }
+    if (raw.split(/\r?\n/).some((l) => l.trim() === rel || l.trim() === `/${rel}`)) return 'already-excluded';
+    fs.mkdirSync(path.dirname(exclude), { recursive: true });
+    fs.appendFileSync(exclude, `${raw && !raw.endsWith('\n') ? '\n' : ''}# KLYPIX live projection (machine-local; written by klypix-mcp)\n${rel}\n`, 'utf8');
+    return 'excluded';
+  } catch {
+    return 'exclude-failed';
+  }
+}
+
+export function writeClaudeLocal(projectDir, body, { now = Date.now(), file = null } = {}) {
+  const root = path.resolve(projectDir);
+  const target = file || path.join(root, CLAUDE_LOCAL_FILE);
+  try {
+    const key = liveKey(root);
+    let raw = '';
+    try { raw = fs.readFileSync(target, 'utf8'); } catch { /* fresh */ }
+    const block = wrapLiveBlock(key, body, { at: now, projectDir: root });
+    const next = upsertLiveBlock(raw, key, block);
+    if (stable(next) === stable(raw)) return { path: target, action: 'unchanged', excluded: ensureLocalExcluded(root) };
+    atomicWrite(target, next);
+    return { path: target, action: raw ? 'updated' : 'created', excluded: ensureLocalExcluded(root) };
+  } catch (e) {
+    return { path: target, action: 'failed', error: e?.message || String(e) };
+  }
+}
+
+/** The one global instruction file Codex actually loads. */
+export function codexGlobalInstructionFile(home = os.homedir()) {
+  const dir = path.join(process.env.CODEX_HOME || path.join(home, '.codex'));
+  const override = path.join(dir, 'AGENTS.override.md');
+  try { if (fs.statSync(override).isFile()) return override; } catch { /* no override */ }
+  return path.join(dir, 'AGENTS.md');
+}
+
+/** Drop other projects' sections that are stale or beyond the cap (oldest first). */
+export function pruneLiveSections(raw, { keep = null, now = Date.now(), staleMs = LIVE_STALE_MS, cap = LIVE_PROJECT_CAP } = {}) {
+  const text = String(raw || '');
+  const found = [];
+  for (const m of text.matchAll(ANY_BLOCK_RE)) found.push({ key: m[1], at: Date.parse(m[2]) || 0, text: m[0] });
+  const others = found.filter((f) => f.key !== keep).sort((a, b) => a.at - b.at);
+  const drop = new Set();
+  for (const f of others) if (now - f.at > staleMs) drop.add(f.text);
+  const fresh = others.filter((f) => !drop.has(f.text));
+  const room = Math.max(0, cap - (keep ? 1 : 0));
+  for (const f of fresh.slice(0, Math.max(0, fresh.length - room))) drop.add(f.text);
+  let next = text;
+  for (const t of drop) next = next.replace(t, '');
+  return { text: next, dropped: drop.size };
+}
+
+export function writeCodexGlobal(projectDir, body, { now = Date.now(), home = os.homedir(), file = null } = {}) {
+  const root = path.resolve(projectDir);
+  const target = file || codexGlobalInstructionFile(home);
+  try {
+    const key = liveKey(root);
+    let raw = '';
+    try { raw = fs.readFileSync(target, 'utf8'); } catch { /* fresh */ }
+    const pruned = pruneLiveSections(raw, { keep: key, now });
+    const block = wrapLiveBlock(key, body, { at: now, projectDir: root });
+    const next = upsertLiveBlock(pruned.text, key, block);
+    if (stable(next) === stable(raw)) return { path: target, action: 'unchanged', dropped: pruned.dropped };
+    atomicWrite(target, next);
+    return { path: target, action: raw ? 'updated' : 'created', dropped: pruned.dropped };
+  } catch (e) {
+    return { path: target, action: 'failed', error: e?.message || String(e) };
+  }
+}
+
+/** Both files, never throws. The caller supplies what the hook already computed. */
+export function projectLive({ projectDir, now = Date.now(), home = os.homedir(), version = '', peers = [], unfinishedText = '', lockNotesText = '', claudeFile = null, codexFile = null } = {}) {
+  const body = renderLiveProjection({ projectDir, now, version, peers, unfinishedText, lockNotesText });
+  return {
+    claude: writeClaudeLocal(projectDir, body, { now, file: claudeFile }),
+    codex: writeCodexGlobal(projectDir, body, { now, home, file: codexFile }),
+    bytes: Buffer.byteLength(body),
+  };
+}
+
+/** Uninstall / unlink: remove this project's block from both files; delete CLAUDE.local.md only if nothing else is in it. */
+export function removeLiveProjection(projectDir, { home = os.homedir(), claudeFile = null } = {}) {
+  const root = path.resolve(projectDir);
+  const key = liveKey(root);
+  const out = { claude: 'unchanged', codex: 'unchanged' };
+  const local = claudeFile || path.join(root, CLAUDE_LOCAL_FILE);
+  try {
+    const raw = fs.readFileSync(local, 'utf8');
+    if (blockRe(key).test(raw)) {
+      const rest = stripLiveBlocks(raw, key);
+      if (rest.trim()) { atomicWrite(local, rest); out.claude = 'block-removed'; } else { fs.unlinkSync(local); out.claude = 'file-removed'; }
+    }
+  } catch { /* absent */ }
+  const dir = path.join(process.env.CODEX_HOME || path.join(home, '.codex'));
+  for (const f of [path.join(dir, 'AGENTS.override.md'), path.join(dir, 'AGENTS.md')]) {
+    try {
+      const raw = fs.readFileSync(f, 'utf8');
+      if (!blockRe(key).test(raw)) continue;
+      atomicWrite(f, stripLiveBlocks(raw, key));
+      out.codex = 'section-removed';
+    } catch { /* absent */ }
+  }
+  return out;
+}
+
+/** Does `raw` carry this project's live block? (uninstall planning, read-only) */
+export function hasLiveBlock(raw, projectDir) {
+  return blockRe(liveKey(projectDir)).test(String(raw || ''));
+}
+
+/** Every live section in the Codex global file (for doctor and uninstall). */
+export function listLiveSections(raw) {
+  const text = String(raw || '');
+  return [...text.matchAll(ANY_BLOCK_RE)].map((m) => {
+    const project = /project="([^"]*)"/.exec(m[0]);
+    return { key: m[1], at: Date.parse(m[2]) || 0, project: project ? project[1] : '' };
+  });
+}

package/src/uninstall.mjs

@@ -43,6 +43,13 @@ import {
   removeCodexPresenceHooks,
   resolveCodexHooksPath,
 } from './codex-hooks.mjs';
+import {
+  CLAUDE_LOCAL_FILE,
+  hasLiveBlock,
+  removeLiveProjection,
+  listLiveSections,
+  stripLiveBlocks,
+} from './live-projection.mjs';
 
 // ── the one absolute rule ────────────────────────────────────────────────────
 // A canvas is USER DATA. install/link never created one and uninstall must never
@@ -290,6 +297,20 @@ export function planUnlink(projectDir, { sidecars = false } = {}) {
     const target = { file, kind: meta.kind, wrapKey: meta.wrapKey, frontmatter: meta.frontmatter };
     items.push({ label: r.tool, rel, file, ...target, ...planOne(target) });
   }
+  // Live projection block (1.104.0). CLAUDE.local.md is not a managed install
+  // target — the person may own the rest of the file — so only KLYPIX's own
+  // marked block goes, and the file only when nothing else is in it. The
+  // project's section in the Codex global file goes with it.
+  {
+    const file = path.join(root, CLAUDE_LOCAL_FILE);
+    const raw = readText(file);
+    items.push({
+      label: 'Live projection (machine-local snapshot)', rel: CLAUDE_LOCAL_FILE, file, kind: 'live-block',
+      ...(raw !== null && hasLiveBlock(raw, root)
+        ? { action: 'strip-block', why: 'remove the KLYPIX live block (and this project\'s section in the Codex global file); your own lines stay' }
+        : { action: 'none', why: 'not present' }),
+    });
+  }
   if (sidecars) {
     for (const rel of PROJECT_SIDECARS) {
       const file = path.join(root, rel);
@@ -332,6 +353,18 @@ export function planUninstall({ home = os.homedir(), installDir, keepRegistry =
       ? { action: 'strip-block', why: 'remove the fenced KLYPIX block; your own guidance stays' }
       : { action: 'none', why: 'no managed block' }),
   });
+  // 2b) Live projection sections (1.104.0): one per project, in whichever
+  // global file Codex loads. Stripped whole; the person's own text stays.
+  for (const name of ['AGENTS.override.md', 'AGENTS.md']) {
+    const file = path.join(HOME, '.codex', name);
+    const raw = readText(file);
+    const count = raw === null ? 0 : listLiveSections(raw).length;
+    if (!count && name === 'AGENTS.override.md') continue;
+    items.push({
+      label: 'Live projection sections (Codex global)', rel: `.codex/${name}`, file, kind: 'live-sections',
+      ...(count ? { action: 'strip-block', why: `remove ${count} machine-local KLYPIX live section(s); your own guidance stays` } : { action: 'none', why: 'no live section' }),
+    });
+  }
   if (codexGlobalInstructionsInstalled(HOME)) {
     notes.push('~/.codex/AGENTS.md carries no version/hash stamp, so an edit you made INSIDE the KLYPIX block cannot be detected — the .klypix-bak backup is your only copy of it.');
   }
@@ -432,8 +465,28 @@ function applyOne(item, { root } = {}) {
     : item.kind === 'codex-hooks' ? null
       : item.kind === 'codex-agents' ? null
         : item.kind === 'bundle' ? null
-          : planOne(item);
+          : item.kind === 'live-block' || item.kind === 'live-sections' ? null
+            : planOne(item);
   try {
+    if (item.kind === 'live-block') {
+      // Both files at once: the project's CLAUDE.local.md block and its section
+      // in the Codex global file (the module owns the markers; never a blind delete).
+      const projectDir = root || path.dirname(item.file);
+      const raw = readText(item.file);
+      if (raw === null || !hasLiveBlock(raw, projectDir)) return { ok: true, action: 'none' };
+      const backup = backupFile(item.file);
+      const res = removeLiveProjection(projectDir, { claudeFile: item.file });
+      return { ok: true, action: res.claude === 'file-removed' ? 'delete-file' : res.claude === 'block-removed' ? 'strip-block' : 'none', backup };
+    }
+    if (item.kind === 'live-sections') {
+      const raw = readText(item.file);
+      if (raw === null || !listLiveSections(raw).length) return { ok: true, action: 'none' };
+      const backup = backupFile(item.file);
+      const next = stripLiveBlocks(raw);
+      if (next.trim() === '') { deleteFile(item.file); return { ok: true, action: 'delete-file', backup }; }
+      writeAtomic(item.file, next);
+      return { ok: true, action: 'strip-block', backup };
+    }
     if (item.kind === 'codex-agents') {
       if (!codexGlobalInstructionsInstalled(path.resolve(item.file, '..', '..'))) return { ok: true, action: 'none' };
       const res = removeCodexGlobalInstructions(path.resolve(item.file, '..', '..'));