klypix-mcp 1.101.1 → 1.103.0

package/README.md

@@ -702,6 +702,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 +1029,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 |

package/bin/klypix-worker.mjs

@@ -45,9 +45,10 @@ import {
   reopenQuestion,
   REOPEN_NUDGE,
   formatUnfinishedWork,
+  listUnfinishedWork,
 } from '../src/agent-presence.mjs';
 import { collectRepoState, commitsInRange, makeContainmentProbe } from '../src/repo-state.mjs';
-import { CONTINUE_RE as HANDOFF_CONTINUE_RE, formatHandoffCards } from '../src/session-handoff.mjs';
+import { CONTINUE_RE as HANDOFF_CONTINUE_RE, formatHandoffCards, readLockNotes, assessLockNote, formatLockNotes, lockNotesData, createLockNoteProbe } from '../src/session-handoff.mjs';
 import {
   reconcileRegisteredProjects,
   registerProjectBrain,
@@ -1408,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).
@@ -1437,19 +1444,56 @@ 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 })),
-          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, files: r.files, commits: r.commits, handoffCardId: r.handoffCardId, takenBy: r.takenBy })),
+          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 })),
         };
       }
     } catch { /* never fails a sync */ }
   }
+  // ── Lock notes (1.102.0, bench S5/S5b): a "do not touch" / hands-off / WIP
+  // line in AGENTS.md / CLAUDE.md is checked against live sessions, unmerged
+  // branches and uncommitted changes, and the verdict rides start (and any
+  // sync that declares a file a note names). Never edits the note; never
+  // fails a sync.
+  let lockText = '';
+  let lockData = null;
+  if (include_context !== false && phase !== 'complete' && report.structured?.brain && (phase === 'start' || (Array.isArray(files) && files.length))) {
+    try {
+      const projectDir = path.dirname(report.structured.brain);
+      const normPath = (p) => { const value = String(p || '').replace(/\\/g, '/').replace(/^\.\//, ''); return process.platform === 'win32' ? value.toLowerCase() : value; };
+      const declared = new Set((Array.isArray(files) ? files : []).map(normPath));
+      // Keyword-matched notes on start; on any sync, every instruction line that
+      // names a declared file, whatever its wording (the agent judges it).
+      const brainPath = report.structured.brain;
+      const selfId = [extra?.klypixRequestIdentity?.sessionId, mcpPresence.id].filter(Boolean);
+      let stopped = [];
+      try { stopped = listUnfinishedWork({ brainPath, selfId: selfId[0] || '', includeWorking: false }); } catch { /* lane unreadable: git still answers */ }
+      // At start, lines naming a file a stopped session worked on ride too,
+      // whatever their wording (bench S5d/S5f): the agent need not ask.
+      const stoppedFiles = new Set(phase === 'start' ? stopped.flatMap((r) => (Array.isArray(r.files) ? r.files : []).map(normPath)) : []);
+      const probe = createLockNoteProbe(projectDir);
+      const notes = readLockNotes(projectDir, { probe, mentions: [...new Set([...declared, ...stoppedFiles])].slice(0, 40) })
+        .filter((n) => (phase === 'start' && n.kind === 'lock') || n.files.some((f) => declared.has(normPath(f)) || stoppedFiles.has(normPath(f))));
+      if (notes.length) {
+        const live = listActiveSessions({ brainPath });
+        const assessed = notes.slice(0, 6).map((n) => assessLockNote(projectDir, n, { live, stopped, selfId, probe }));
+        lockText = formatLockNotes(assessed);
+        lockData = lockNotesData(assessed);
+      }
+    } catch { /* never fails a sync */ }
+  }
   const totalMs = Math.max(0, Date.now() - totalStartedAt);
   const structuredContent = {
     ...(report.structured || {
@@ -1471,6 +1515,7 @@ server.registerTool('brain_sync', {
     ...(registration ? { registration } : {}),
     ...(harness ? { harness } : {}),
     ...(handoffData ? { handoffs: handoffData } : {}),
+    ...(lockData ? { lockNotes: lockData } : {}),
   };
   const harnessText = harness?.failed
     ? `KLYPIX harness self-heal needs attention: ${harness.failed} project(s) remain partially aligned; brain_doctor has the exact files.`
@@ -1482,7 +1527,7 @@ server.registerTool('brain_sync', {
   return {
     content: [{
       type: 'text',
-      text: [report.text, harnessText, shipNotice, releaseReconcileText, captureGapText, handoffText, contextText, timingText].filter(Boolean).join('\n\n'),
+      text: [report.text, harnessText, shipNotice, releaseReconcileText, captureGapText, lockText, handoffText, contextText, timingText].filter(Boolean).join('\n\n'),
     }],
     structuredContent,
     ...(report.isError ? { isError: true } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.101.1",
+  "version": "1.103.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/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/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';
@@ -2957,6 +3035,10 @@ const quietFor = (row, now) => {
   const at = Number(row.hostStatusAt || row.activityAt || row.intentAt || row.startedAt || row.lastSeen || now);
   return Math.max(0, now - at);
 };
+// Shared with note evidence: connection heartbeats alone do not prove work.
+export const sessionWorkIsRecent = (row, now = Date.now()) => Boolean(row)
+  && row.working !== false && row.holdsFiles !== false
+  && quietFor(row, now) < UNFINISHED_QUIET_MS;
 export function listUnfinishedWork({ brainPath, home, now = Date.now(), selfId = '', includeWorking = false } = {}) {
   if (!brainPath) return [];
   const lane = readLane(laneFileFor(brainPath, home));
@@ -3001,12 +3083,16 @@ export function listUnfinishedWork({ brainPath, home, now = Date.now(), selfId =
       state: row ? 'stopped' : 'ended',
       working: false,
       holdsFiles: false,
-      note: 'This session is not running. It holds no claim on these files; a "do not touch" note it left no longer applies. Continue its work only if the human asks.',
+      note: 'This session is not running. It holds no claim on these files. A "do not touch" note it left may be stale or may still protect unmerged work: KLYPIX checks such notes against live sessions and branches — follow that check. Continue its work only if the human asks.',
       lastPrompt: work.lastPrompt || '',
       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,
@@ -3056,7 +3142,7 @@ export function formatUnfinishedWork(records, { now = Date.now(), max = 5, cardT
   const list = Array.isArray(records) ? records : [];
   if (!list.length) return '';
   const flat = (value) => String(value || '').replace(/\s+/g, ' ').trim();
-  const lines = [`⏸️ Work other sessions may have left unfinished (${list.length}, stopped in the last 24h, ${ranked ? 'most relevant first' : 'newest first'}). None of them is running: they hold NO claim on any file, and a "do not touch" or WIP note one of them left no longer applies. Use this only if the human asks you to continue their work:`];
+  const lines = [`⏸️ Work other sessions may have left unfinished (${list.length}, stopped in the last 24h, ${ranked ? 'most relevant first' : 'newest first'}). None of them is running: they hold NO live claim on any file. Whether a note about one of their files still holds is a question of evidence, not age: KLYPIX surfaces matching lines from supported instruction files with bounded checks of local sessions, branches and worktrees (📌, when there is such a line). Use this list only if the human asks you to continue their work:`];
   for (const r of list.slice(0, max)) {
     const who = `${clientWord(r.client)} ${String(r.id).slice(0, 8)}`;
     const bits = [r.state === 'ended' ? 'ended' : `stopped (${r.status})`, `last active ${agoLabel(r.ageMs)}`];
@@ -3064,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,12 +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
-files, and a "do not touch" note it left no longer applies. Never ask the human to paste a summary
-into the next session.
+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. 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

@@ -381,6 +381,28 @@ function unfinishedWorkBlock(brainPath, sessionId) {
   }
 }
 
+// 📌 Lock notes (1.102.0): the same check brain_sync and the Claude hook run —
+// 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) {
+  try {
+    const lib = await import(new URL('./session-handoff.mjs', import.meta.url).href);
+    if (typeof lib.readLockNotes !== 'function') return '';
+    let stopped = [];
+    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 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 }));
+    return lib.formatLockNotes(assessed);
+  } catch {
+    return '';
+  }
+}
+
 // 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.
@@ -473,6 +495,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,
@@ -495,8 +531,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
@@ -529,8 +586,10 @@ async function main() {
         return typeof ghl.ensureGitCaptureHook === 'function' ? (ghl.ensureGitCaptureHook(projectDir).notice || '') : '';
       } catch { return ''; }
     })();
+    const lockNotes = await lockNotesBlock(projectDir, brainPath, sessionId, sessions);
     emitSystemMessage([
       formatPresenceMessage(sessions, sessionId, { includeSolo: true }),
+      lockNotes,
       // Class-C ship observation — the engine's, not a Claude-hook-local copy.
       // Codex-driven projects had NO out-of-session ship detection at all, which
       // is exactly where the incident class bites hardest (2026-07-29 review).