klypix-mcp 1.102.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:
@@ -702,6 +729,18 @@ until a session takes it (`{action:"take", id}`) and finishes it (`{action:"done
 archives it). A later handoff can name the earlier one it `continues`. The per-prompt hook nudges
 the agent to write one when the person says *handoff* or names the limit.
 
+**Drafted by KLYPIX — when the session never got to write one.** A usage limit, a crash or a
+closed window leaves no time for `brain_handoff`. Since 1.103.0 the brain writes the card itself:
+at the next `brain_sync` start or `brain_handoff list` of *any* session, a record that qualifies —
+the session is closed or quiet for 30 minutes, left real work (its own commits, or touched files
+and a reply tail), has no card and no taker, and its task was a human's, not an app's — becomes a
+🤝 HANDOFF card on that session's behalf, reason *interrupted*. The card says `Drafted: by KLYPIX`
+on its own line, lists only what git proved under *Done*, tells the reader to confirm the state
+with `git status` before touching anything, and carries the session's last words verbatim. The
+record and every list say the session wrote none. If the session resumes and completes its task,
+the drafted card is archived at the next pass. Three drafts per pass at most; a draft can never
+fail the sync that triggered it.
+
 Durable decisions still go in the brain as cards — a handoff is the one card about *work in
 flight*, and it closes when the work lands.
 
@@ -1017,7 +1056,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `brain_doctor` | Self-diagnosis: version, core/enhanced host adapters, active sessions, tool count, projection drift |
 | `brain_message` | Session-to-session coordination notes — to a live session, or queued for one that is not running until it next starts — with a fixed send-time audience and per-recipient pending / offer / acknowledgement / consumption / failure receipts (a directed note is kept 7 days, a broadcast 24h; never written into the brain) |
 | `brain_message_receipt` | Explicitly record model-side consumption using the exact message id and per-recipient offer token; acknowledgement alone never consumes a note |
-| `brain_handoff` | The session handoff. `write` puts a 🤝 card in the brain — task, done, next in order, files, verify — when a session stops before the work is done; the next session of any agent sees it at its first `brain_sync` and `take`s it, then marks it `done`. `list` also shows the **unfinished work** KLYPIX recorded automatically for every session (its last reply, files and own commits), which can be taken over by session id |
+| `brain_handoff` | The session handoff. `write` puts a 🤝 card in the brain — task, done, next in order, files, verify — when a session stops before the work is done; the next session of any agent sees it at its first `brain_sync` and `take`s it, then marks it `done`. `list` also shows the **unfinished work** KLYPIX recorded automatically for every session (its last reply, files, own commits, and since 1.103.0 the directories it worked in with the uncommitted state of each checkout, so a fix left in a side checkout is named, not searched for), which can be taken over by session id. Since 1.103.0 a session that stopped without writing a card (a usage limit, a crash) gets one **drafted by KLYPIX** from that record at the next `brain_sync` start or `list` — marked `Drafted:`, reason *interrupted*, archived if the session later completes its task |
 | `brain_reopen` | Reopen a closed Claude Code or Codex session so a note waiting for it gets there now — only after the person answers *Reopen* in an in-chat prompt or KLYPIX's own dialog; opens a new, visible terminal in that session's folder with the host's resume command |
 | `brain_sync` | Context Gateway: task capsule, active-task peers, exact-file overlap, one-time alerts, timing, and optional result-manifest reconciliation |
 | `brain_connect` | Find and draw related-but-unlinked cards |
@@ -1338,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/bin/klypix-worker.mjs

@@ -1409,7 +1409,13 @@ server.registerTool('brain_sync', {
   let handoffData = null;
   if (phase === 'start' && include_context !== false && report.structured?.brain) {
     try {
-      const h = await opBrainHandoff({ vault: mcpPresence.vault, canvas: report.structured.brain, action: 'list', from: { sessionId: extra?.klypixRequestIdentity?.sessionId || mcpPresence.id } });
+      const h = await opBrainHandoff({ vault: mcpPresence.vault, canvas: report.structured.brain, action: 'list', from: { sessionId: extra?.klypixRequestIdentity?.sessionId || mcpPresence.id, client: extra?.klypixRequestIdentity?.clientInfo?.client || extra?.klypixClientName || 'unknown' } });
+      // 1.103.0: the list may have WRITTEN the brain (a card drafted for a dead
+      // session, or a drafted card archived) — an atomic replace that changes
+      // the brain inode captured at sync. Refresh the binding from the
+      // unchanged canonical root, as the tool wrapper does after any managed
+      // write, or the session's very next tool is rejected as project-changed.
+      if ((h?.structured?.autoDrafted || []).length || (h?.structured?.autoClosed || []).length) mcpPresence.refreshCurrentProjectBinding();
       const cards = h?.structured?.handoffs || [];
       // 1.99.1: the AUTOMATIC lane records are history, not a lock (bench S5:
       // an ended session's intent on a file made Claude and Codex defer, 0/5).
@@ -1438,14 +1444,19 @@ server.registerTool('brain_sync', {
         .map(({ r }) => r);
       if (!h?.isError && (cards.length || lane.length)) {
         const now = Date.now();
+        const drafted = Array.isArray(h?.structured?.autoDrafted) ? h.structured.autoDrafted : [];
         handoffText = [
+          // 1.103.0: a card KLYPIX drafted in THIS pass from a dead session's
+          // record is announced as such — a lead to verify, not the session's words.
+          drafted.length ? `🤝 KLYPIX drafted ${drafted.length} handoff card${drafted.length > 1 ? 's' : ''} just now from the record of a session that stopped without writing one: ${drafted.map((d) => `[${d.id}] “${d.title}”`).join('; ')}. A drafted card is a lead, not a verified state — confirm it with git before relying on it.` : '',
           formatHandoffCards(cards, { now, max: 5 }),
           formatUnfinishedWork(lane, { now, max: 4, ranked: wantsContinue && words.size > 0 }),
         ].filter(Boolean).join('\n\n');
         handoffData = {
           cards: cards.length,
           unfinished: lane.length,
-          handoffs: cards.map((c) => ({ id: c.id, title: c.title, from: c.from, at: c.at, reason: c.reason, state: c.state, next: c.next, files: c.files })),
+          handoffs: cards.map((c) => ({ id: c.id, title: c.title, from: c.from, at: c.at, reason: c.reason, state: c.state, next: c.next, files: c.files, auto: c.auto === true })),
+          ...(Array.isArray(h?.structured?.autoDrafted) && h.structured.autoDrafted.length ? { autoDrafted: h.structured.autoDrafted } : {}),
           sessions: lane.slice(0, 4).map((r) => ({ id: r.id, client: r.client, intent: r.intent, state: r.state, working: false, holdsFiles: false, note: r.note, status: r.status, lastSeen: r.lastSeen, lastPrompt: r.lastPrompt || null, lastWords: r.lastWords || null, files: r.files, commits: r.commits, handoffCardId: r.handoffCardId, takenBy: r.takenBy })),
         };
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.102.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/agent-presence.mjs

@@ -512,6 +512,37 @@ const endedMatches = (row, id) => {
 // without `work` is byte-stable through a touch that changes nothing.
 export const WORK_LAST_WORDS_MAX = 700;
 export const WORK_COMMITS_MAX = 6;
+// Where the session actually worked (1.103.0, field case 2026-10-15): the
+// directories its shell commands moved into (`workdirs`) and a bounded `git
+// status` of each checkout at Stop (`checkouts`). Codex had left a fix
+// UNCOMMITTED on a branch in a side checkout (C:\w\facts) that `git worktree
+// list` in the project does not show; its last words, files and commits were
+// all recorded and still nobody could find the work.
+export const WORK_WORKDIRS_MAX = 4;
+export const WORK_CHECKOUTS_MAX = 4;
+export const WORK_CHECKOUT_PATHS_MAX = 12;
+// Newest last; a directory used again moves to the tail (LRU, like observedFiles).
+const normalizeDirList = (raw, max) => {
+  const cleaned = (Array.isArray(raw) ? raw : []).map((d) => String(d || '').trim().replace(/[\\/]+$/, '').slice(0, 400)).filter(Boolean);
+  const out = [];
+  const seen = new Set();
+  for (const d of cleaned.reverse()) { if (seen.has(d)) continue; seen.add(d); out.unshift(d); }
+  return out.slice(-max);
+};
+export function normalizeCheckout(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const dir = String(raw.dir || '').trim().replace(/[\\/]+$/, '').slice(0, 400);
+  if (!dir) return null;
+  const paths = [...new Set((Array.isArray(raw.paths) ? raw.paths : []).map((p) => String(p || '').trim().slice(0, 200)).filter(Boolean))].slice(0, WORK_CHECKOUT_PATHS_MAX);
+  const changed = Math.max(Number.isFinite(Number(raw.changed)) ? Math.round(Number(raw.changed)) : 0, paths.length);
+  const head = String(raw.head || '').trim().slice(0, 12);
+  const branch = String(raw.branch || '').replace(/\s+/g, ' ').trim().slice(0, 120);
+  const at = Number.isFinite(Number(raw.at)) && Number(raw.at) > 0 ? Number(raw.at) : null;
+  return {
+    dir, branch: branch || null, head: /^[0-9a-f]{4,12}$/i.test(head) ? head : null, changed, paths,
+    shared: Boolean(raw.shared), ...(raw.statusUnknown ? { statusUnknown: true } : {}), ...(at ? { at } : {}),
+  };
+}
 export function normalizeWork(raw) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
   const out = {};
@@ -539,6 +570,17 @@ export function normalizeWork(raw) {
   // hooks or not — stamps when it was declared, so a Cursor / Gemini / VS Code
   // session that stopped mid-task is still found by the next session.
   if (ms(raw.declaredAt)) out.declaredAt = ms(raw.declaredAt);
+  // 1.103.0: where it worked — directories beyond cwd, and each checkout's
+  // uncommitted state at the last Stop (replaced whole on every Stop).
+  const workdirs = normalizeDirList(raw.workdirs, WORK_WORKDIRS_MAX);
+  if (workdirs.length) out.workdirs = workdirs;
+  if (Array.isArray(raw.checkouts)) {
+    const checkouts = raw.checkouts.map(normalizeCheckout).filter(Boolean).slice(0, WORK_CHECKOUTS_MAX);
+    if (checkouts.length) out.checkouts = checkouts;
+  }
+  // 1.103.0: the card at handoffCardId was DRAFTED BY KLYPIX from this record
+  // (the session never wrote one) — every renderer says so.
+  if (raw.handoffAuto === true) out.handoffAuto = true;
   return Object.keys(out).length ? out : null;
 }
 export function mergeWork(previous, patch) {
@@ -546,6 +588,12 @@ export function mergeWork(previous, patch) {
   if (patch === null) return null;
   const prev = normalizeWork(previous) || {};
   const next = patch && typeof patch === 'object' ? { ...patch } : {};
+  // `addWorkdirs` APPENDS (one tool call at a time on Codex; a transcript walk
+  // on Claude), newest last, de-duplicated, capped like `workdirs`.
+  if (Array.isArray(next.addWorkdirs)) {
+    next.workdirs = normalizeDirList([...(prev.workdirs || []), ...next.addWorkdirs], WORK_WORKDIRS_MAX);
+    delete next.addWorkdirs;
+  }
   // `addCommits` APPENDS (Codex records one commit per tool result; the
   // Claude Stop hook replaces the full list with `commits`), newest last,
   // de-duplicated by sha, capped like `commits`.
@@ -2940,7 +2988,37 @@ export const UNFINISHED_WINDOW_MS = 24 * 60 * 60 * 1000;
 // Evidence of real work, from ANY host: a reply tail (Claude and Codex Stop
 // hooks), own commits (Claude transcript, Codex tool results), a handoff card
 // (brain_handoff), or a task declared through brain_sync (every MCP host).
-export const hasWorkEvidence = (work) => Boolean(work && (work.lastWords || (Array.isArray(work.commits) && work.commits.length) || work.handoffCardId || work.declaredAt));
+// 1.103.0: uncommitted changes in a checkout it worked in are evidence too — a
+// session cut off before its first reply tail still left work on disk.
+export const hasUncommittedWork = (work) => Boolean(work && Array.isArray(work.checkouts) && work.checkouts.some((c) => c && Number(c.changed) > 0));
+export const hasWorkEvidence = (work) => Boolean(work && (work.lastWords || (Array.isArray(work.commits) && work.commits.length) || work.handoffCardId || work.declaredAt || hasUncommittedWork(work)));
+// The "where it worked" lines of one record — shared by formatUnfinishedWork,
+// the brain_handoff take reply and (as a twin) the Claude hook's footer. A
+// separate checkout is named in full with its branch, head and uncommitted
+// paths: the next session must not have to search for it. The project
+// checkout is shared by every session, so only the files THIS session touched
+// are reported there.
+export function formatCheckoutLines(work, { cwd = null } = {}) {
+  const lines = [];
+  const checkouts = Array.isArray(work?.checkouts) ? work.checkouts : [];
+  const named = new Set();
+  for (const c of checkouts) {
+    if (!c || !c.dir) continue;
+    named.add(String(c.dir).replace(/\\/g, '/').toLowerCase());
+    const more = Number(c.changed) > c.paths.length ? ` …and ${Number(c.changed) - c.paths.length} more` : '';
+    if (c.shared) {
+      if (Number(c.changed) > 0) lines.push(`  uncommitted in the project checkout (files this session touched): ${c.paths.join(', ')}${more}`);
+      continue;
+    }
+    const where = [c.branch ? `branch ${c.branch}` : 'detached HEAD', ...(c.head ? [`@ ${c.head}`] : [])].join(' ');
+    const state = c.statusUnknown ? 'git status unavailable' : (Number(c.changed) > 0 ? `${c.changed} uncommitted: ${c.paths.join(', ')}${more}` : 'clean');
+    lines.push(`  worked in a separate checkout: ${c.dir} (${where}; ${state}) — not the project folder; git worktree list may not show it`);
+  }
+  const extra = (Array.isArray(work?.workdirs) ? work.workdirs : [])
+    .filter((d) => !named.has(String(d).replace(/\\/g, '/').toLowerCase()) && (!cwd || String(d).replace(/\\/g, '/').toLowerCase() !== String(cwd).replace(/\\/g, '/').toLowerCase()));
+  if (extra.length) lines.push(`  also ran commands in: ${extra.join(', ')}`);
+  return lines;
+}
 export function clientWord(client) {
   const key = String(client || '').toLowerCase();
   if (key === 'claude-code' || key === 'claude') return 'Claude Code';
@@ -3010,7 +3088,11 @@ export function listUnfinishedWork({ brainPath, home, now = Date.now(), selfId =
       lastWords: work.lastWords || '',
       lastWordsAt: work.lastWordsAt || null,
       commits: Array.isArray(work.commits) ? work.commits : [],
+      // 1.103.0: where it worked — so a fix left in a side checkout is found.
+      workdirs: Array.isArray(work.workdirs) ? work.workdirs : [],
+      checkouts: Array.isArray(work.checkouts) ? work.checkouts : [],
       handoffCardId: work.handoffCardId || null,
+      handoffAuto: work.handoffAuto === true,
       takenBy: work.takenBy
         ? { ...work.takenBy, live: Boolean(taker), status: taker ? (sessionStatusLabel(taker, now) || 'live') : 'not running' }
         : null,
@@ -3068,10 +3150,13 @@ export function formatUnfinishedWork(records, { now = Date.now(), max = 5, cardT
     lines.push(`- ${who} · “${flat(r.intent).slice(0, 120)}” · ${bits.join(' · ')}`);
     if (r.commits.length) lines.push(`  commits: ${r.commits.map((c) => `${c.sha} ${c.subject}`).join('; ').slice(0, 320)}`);
     if (r.files.length) lines.push(`  files it touched (free — not reserved): ${r.files.slice(-8).join(', ')}`);
+    lines.push(...formatCheckoutLines(r, { cwd: r.cwd }));
     if (r.lastWords) lines.push(`  its last words: “${flat(r.lastWords).slice(0, 420)}”`);
     if (r.handoffCardId) {
       const title = cardTitles && cardTitles.get ? cardTitles.get(r.handoffCardId) : null;
-      lines.push(`  🤝 it left a handoff card in the brain: ${r.handoffCardId}${title ? ` — “${flat(title).slice(0, 100)}”` : ''} (brain_handoff {action:"list"} prints it in full)`);
+      lines.push(r.handoffAuto
+        ? `  🤝 KLYPIX drafted a handoff card from this record (the session wrote none): ${r.handoffCardId}${title ? ` — “${flat(title).slice(0, 100)}”` : ''} (brain_handoff {action:"list"} prints it in full)`
+        : `  🤝 it left a handoff card in the brain: ${r.handoffCardId}${title ? ` — “${flat(title).slice(0, 100)}”` : ''} (brain_handoff {action:"list"} prints it in full)`);
     }
     if (r.takenBy) lines.push(`  taken over by ${clientWord(r.takenBy.client)} ${String(r.takenBy.id).slice(0, 8)} ${r.takenBy.at ? agoLabel(now - r.takenBy.at) : ''} (${r.takenBy.status}) — coordinate with brain_message before duplicating it`);
     if (r.resumeCommand) lines.push(`  its own transcript, should the human want it: ${r.resumeCommand}`);

package/src/agent-rules.mjs

@@ -510,19 +510,21 @@ is near, the day ends, you are blocked, you are switching tool) Call \`brain_han
 {action:"write"} with the task, what is done, what is NEXT in order, the files and how to verify.
 It is a 🤝 card in this brain the human can see and correct, and the next session on this project —
 any agent — sees it at its first \`brain_sync\` / session start and takes it with {action:"take"},
-then {action:"done"} when finished. KLYPIX also records every session's last reply, files and
-commits automatically, so \`brain_sync\` may list **unfinished work** another session left without
-a card: if the human asks you to continue it, take it with \`brain_handoff\` {action:"take",
-session:"<id>"} first. That list is history, not a lock — a stopped session holds no claim on its
+then {action:"done"} when finished. KLYPIX also records every session's last reply, files,
+commits and the checkouts it worked in (with their uncommitted files) automatically, so
+\`brain_sync\` may list **unfinished work** another session left without a card: if the human asks
+you to continue it, take it with \`brain_handoff\` {action:"take", session:"<id>"} first, and look
+first in the checkout the record names — it may be a side folder, not the project. That list is history, not a lock — a stopped session holds no claim on its
 files. Never ask the human to paste a summary into the next session.
 
 **A note that asks agents to keep off a file**, whatever its wording (here, in AGENTS.md / CLAUDE.md or any
 notes file) can outlive the work it protected. Before you obey one, or before you edit the file
 anyway, call \`brain_sync\` with that file in \`files\`: KLYPIX checks the note against live sessions,
-unmerged local branches and registered worktrees. The result is evidence, not permission:
-standing rules, generated-file policies and explicit human restrictions still apply. An incomplete
-check says UNKNOWN. Only an expired temporary reservation may be stale; if your task authorizes
-editing, continue and tell the human so they can remove the note — never delete the note yourself.
+unmerged local branches and registered worktrees. Decide which kind of note it is: a temporary
+reservation for someone's in-flight change ends when that work ends; a permanent rule (generated
+file, policy, legal or human restriction) always holds, whatever the evidence says. If a temporary
+reservation's work has ended and your task needs the file, change it there and tell the human so
+they can remove the note — never delete the note yourself. An incomplete check says UNKNOWN.
 
 **Don't** hand-edit \`brain.klypix\` (it's a packaged canvas — use the tools) or dump file contents into it; capture the *decision*, not the file.`;
 

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.
@@ -495,6 +511,20 @@ async function main() {
     ? touchedFiles(input, projectDir)
     : undefined;
   const files = humanTurn ? [] : undefined;
+  const workPatch = codexWorkPatch({ event, humanTurn, prompt, input }) || {};
+  // Where it works (1.103.0): the directory a tool call ran in (Codex's exec
+  // carries `workdir`; a command may `cd` or `git -C` elsewhere). Dynamic +
+  // guarded so a stale bundle without the helper still records the rest.
+  let whereLib = null;
+  if (event === 'PostToolUse' || event === 'Stop') {
+    try { whereLib = await import(new URL('./session-handoff.mjs', import.meta.url).href); } catch { whereLib = null; }
+  }
+  if (event === 'PostToolUse' && typeof whereLib?.workdirsFromToolInput === 'function') {
+    try {
+      const dirs = whereLib.workdirsFromToolInput(toolInput(input));
+      if (dirs.length) workPatch.addWorkdirs = dirs;
+    } catch { /* best-effort */ }
+  }
   const sessions = upsertSession({
     brainPath,
     id: sessionId,
@@ -517,8 +547,29 @@ async function main() {
     // human prompt on a human turn, and at Stop the reply tail WHEN the host
     // hands it over (Codex's Stop payload may carry `last_assistant_message`;
     // this adapter never reads Codex's transcript). Absent = keep the known.
-    ...(codexWorkPatch({ event, humanTurn, prompt, input }) ? { work: codexWorkPatch({ event, humanTurn, prompt, input }) } : {}),
+    ...(Object.keys(workPatch).length ? { work: workPatch } : {}),
   });
+  // At Stop, a bounded git status of every checkout this session worked in
+  // (cwd first, then the workdirs its tool calls recorded) — the fix left
+  // uncommitted in a side checkout is what the 2026-10-15 field case lost.
+  // A second touch, so it sees the workdirs the first one merged.
+  if (event === 'Stop' && typeof whereLib?.snapshotCheckouts === 'function') {
+    try {
+      const me = sessions.find((session) => session.id === sessionId);
+      const checkouts = whereLib.snapshotCheckouts({
+        dirs: [cwd, ...(Array.isArray(me?.work?.workdirs) ? me.work.workdirs : [])],
+        projectDir,
+        sessionFiles: [...new Set([...(me?.files || []), ...(me?.observedFiles || [])])],
+      });
+      if (checkouts.length) {
+        upsertSession({
+          brainPath, id: sessionId, client: 'codex', event, channel: 'lifecycle', cwd,
+          ...(HOST_PID.pid ? { hostPid: HOST_PID.pid, hostPidSource: HOST_PID.source } : {}),
+          logicalSessionId: sessionId, identitySource: 'codex-lifecycle', work: { checkouts },
+        });
+      }
+    } catch { /* best-effort */ }
+  }
 
   const ignored = event === 'PostToolUse' ? ownBrainMessageText(input) : [];
   // Stop can show a UI warning but cannot add model context. Never advance a
@@ -552,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,
@@ -565,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