klypix-mcp 1.97.0 → 1.99.0

package/README.md

@@ -528,12 +528,22 @@ Future hosts get baseline support merely by connecting the MCP server. A deeper
 
 ## Overlap warnings
 
-When two sessions declare overlapping expected files, `brain_sync` surfaces it: the peer, its
-declared task, and the exact paths in common. A one-time alert is queued to whichever session got
-there first, so a late arrival is not the only one who knows.
-
-This warns. It does not prevent. Nothing blocks an edit, matching is exact-path, and both sides
-have to have declared their files for the overlap to be visible at all.
+`brain_sync` reports three kinds of overlap with other live sessions on the same brain:
+
+- **Same file.** Both sessions declared, or were observed editing, the same path. You see the peer,
+  its task and the paths in common, and a one-time alert is queued to whichever session got there
+  first, so a late arrival is not the only one who knows.
+- **Would conflict at merge.** The two sessions are on different branches, and a test merge of the
+  two branch tips (`git merge-tree`, git 2.38 or newer) conflicts in named files, even though no
+  declared file overlaps. This sees committed work only: an uncommitted edit is invisible to git.
+  It also gets a one-time alert. Files the brain tooling regenerates on every branch (AGENTS.md,
+  rule files, `.mcp.json`, `brain.klypix`) are not counted.
+- **Same folder (advisory).** Both sessions work in one folder with no file in common yet. No alert
+  is sent. A folder that at least three sessions, and more than half of them, touch is treated as
+  noise and not reported.
+
+This warns. It does not prevent. Nothing blocks an edit. A session that never declared its files
+and was never observed editing is invisible to the file and folder checks.
 
 ## Handoffs and messages
 
@@ -580,8 +590,36 @@ receives the waiting note at its first action and the sender sees the receipt as
   waiting for them; `npx klypix-mcp sessions reopen <id>` reopens one (`--quiet` lets it wait for
   you instead of starting on the note).
 
-Durable handoffs go in the brain itself — decisions, findings, open questions and skills captured
-as cards, each stamped with the agent that wrote it.
+### Session handoff — continue in the next session, with any agent
+
+The case this exists for: a Claude Code session stops at its usage limit in the middle of a task,
+and the person opens Codex (or a fresh Claude Code) and says *continue*. Until 1.99.0 the only
+handoff was whatever the person pasted. Now there are two layers, and the person does not have
+to ask for either.
+
+**Automatic.** At every turn end the hooks record the session's last state on the lane that already
+remembers sessions for two weeks: the last human prompt, the tail of the last reply (where "done /
+next" usually is), the files it touched, and its *own* commits (the shas its `git commit` printed —
+never a branch range, because twenty sessions can share one checkout). When that session goes quiet
+for ten minutes or closes with its task uncompleted, every new session on the project sees
+**⏸️ Unfinished work left by other sessions** at its first `brain_sync` and at session start — in
+Claude Code, Codex, and any MCP host — with a status (*closed*, *idle 83m*), the files, the commits,
+the last words, and the resume command should the person want the old transcript. The agent takes it
+over with `brain_handoff {action:"take", session:"<id>"}` so peers see it is taken, continues from
+the record, and marks it `done`. Machine-local, like the rest of the lane.
+
+**Deliberate.** When a session knows it is stopping — the person asks for a handoff, the context or
+usage limit is near, the day ends, it is blocked, it is switching tool — it calls
+`brain_handoff {action:"write"}` with the task, what is done, what is **next in order**, the files
+and how to verify. That becomes a 🤝 HANDOFF card in the project brain: an open card the person can
+see and correct on the canvas, with the files as evidence anchors, that travels with the repo and
+syncs like every other card. It leads the session-start brief and the `brain_sync` start response
+until a session takes it (`{action:"take", id}`) and finishes it (`{action:"done", id}`, which
+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.
+
+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.
 
 ## Evidence-gated completion
 
@@ -757,6 +795,15 @@ lost 0 of 46. If the control ever loses nothing, the run reports **inconclusive*
 
 Latest results, with hardware and date: [BENCHMARKS.md](BENCHMARKS.md).
 
+**Does it change what agents do?** That needs real agents, so it lives in the repository rather than
+the package: [`bench/coordination/`](bench/coordination/README.md) runs Claude Code or Codex on four
+small repos where another session knows something the agent needs (a decision changed today, work
+overlapping on another branch, a note from a session that has ended, a root cause another vendor's
+session found). Each run is graded by a test written after the agent finishes, against no shared
+channel, a human copy-paste, `AGENTS.md` kept tidy or appended, and KLYPIX over MCP only. Every number
+is printed with its sample size and interval; tools it has not measured are listed as not measured.
+`--dry-run` costs nothing and proves the graders.
+
 ## Git and concurrency
 
 One file in your repo, committed with your code — versioned, branchable, portable. So two
@@ -872,7 +919,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 
 ---
 
-## The verbs: 25, and 26 on Windows
+## The verbs: 26, and 27 on Windows
 
 | Tool | What it does |
 |---|---|
@@ -886,6 +933,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_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 |
@@ -903,7 +951,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `add_to_canvas` | Append cards/connections (positions preserved), bordered and readable on KLYPIX's dark and Paper themes; a card's `group` puts it in that titled box. On a canvas open in KLYPIX (Windows) the cards go to KLYPIX itself: live, attributed, one undo. When KLYPIX cannot take them it refuses (`OPEN_IN_APP`, `ACCESS_OFF`, `BLOCKED`), a box locked from AI tools (`SCOPE_LOCKED`) or a frozen box (`FROZEN`), and writes nothing; project brains are the exception to the first. Returns the new card ids |
 | `list_canvases` | List every `.klypix` in the vault |
 
-Exactly 25 on Linux and macOS and 26 on Windows, where `show_in_klypix` is registered; machine-verifiable with `npx klypix-mcp doctor`, whose TOOLS line applies the same rule and whose App bridge line says whether KLYPIX is running, with access on or off.
+Exactly 26 on Linux and macOS and 27 on Windows, where `show_in_klypix` is registered; machine-verifiable with `npx klypix-mcp doctor`, whose TOOLS line applies the same rule and whose App bridge line says whether KLYPIX is running, with access on or off.
 
 > **`canvas_view`:** no MCP Apps host has been observed rendering the UI resource yet — there is no
 > screenshot and no host-level test. Hosts without the extension get clean text, which is the path
@@ -1105,9 +1153,10 @@ Read this section before you build on any of it.
   loop prevention, stable message IDs and per-recipient-machine acknowledgement primitives), but no
   transport: carrying frames between machines is the desktop app's job. With `klypix-mcp` alone,
   coordination is machine-local.
-- **Overlap matching is exact-path, and both sides must declare.** A session that never declares
-  its expected files is invisible to overlap detection, and `src/auth/token.ts` does not match a
-  rename or a parent directory.
+- **File overlap is exact-path.** A session needs declared files or observed edits to be checked;
+  `src/auth/token.ts` does not match a rename. Folder overlap is advisory. The merge test sees
+  committed work only, needs git 2.38 or newer, and runs only for sessions on different local
+  branches of the same repository.
 - **Overlap warnings are advisory.** Nothing is blocked. One severity string in the payload reads
   `blocking`; the mechanism is not.
 - **Codex has no automatic capture**, with or without `--codex-hooks`. The Codex hook never writes

package/bin/klypix-a2a.mjs

@@ -243,6 +243,7 @@ const DELIBERATELY_UNWIRED = Object.freeze({
   opBrainReconcile: 'wire-supplied roots can traverse host directories; keep MCP-only',
   opBrainGarden: 'apply requires an out-of-band human approval code and must never be weakened for A2A',
   opBrainMessage: 'send-only machine-local messaging has no receivable A2A half',
+  opBrainHandoff: 'take/done stamp the calling session identity on the lane; A2A has no authenticated session identity (MCP-only)',
 });
 
 const canonicalPath = (p) => {

package/bin/klypix-install.mjs

@@ -493,7 +493,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', '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', '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

@@ -28,7 +28,7 @@ import {
   resolveVault, getEmbedder, shouldPrewarmSemantic, buildKlypixMap, cardSchema, connSchema, groupSchema,
   opListCanvases, opReadCanvas, opSearchCanvases, opSearchAllBrains,
   opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage, opBrainAsk, opBrainChallenge, opCanvasView, opBrainLens,
-  opBrainTaskContext,
+  opBrainTaskContext, opBrainHandoff,
 } from '../src/klypix-core.mjs';
 import { compareProjectGraphResults, projectGraphContextMarkdown, queryProjectGraph, suggestProjectGraphBrainLinks, scanNativeProjectMap, checkBrainDrift, brainDriftMarkdown } from '../src/project-graph.mjs';
 import { auditProject, compactAgentsBrief, linkProject, mcpServerEntry } from '../src/agent-rules.mjs';
@@ -1064,9 +1064,64 @@ server.registerTool('brain_reopen', {
   return reply('reopened', `🔓 Reopened ${label} — the human said yes${consent.via === 'dialog' ? ' in the KLYPIX dialog' : ''}. It opened in a new ${plan.method === 'windows-terminal' ? 'Windows Terminal window' : plan.method === 'macos-terminal' ? 'Terminal window' : 'terminal window'} in ${candidate.cwd} with ${candidate.command}${consent.start ? ', and starts on the note right away' : ', waiting for the human to prompt it'}. ${notes === 1 ? 'The waiting note is' : `The ${notes} waiting notes are`} delivered at its first action; your next prompt shows the receipt. If the window shows an error (for example the command is not found), the note stays queued — ${manualLine}.`, { via: consent.via, method: plan.method, cwd: candidate.cwd, command: candidate.command, start: Boolean(consent.start), notes });
 });
 
+// ── brain_handoff (1.99.0): a session hands its unfinished work to the next ─
+// Two layers. AUTOMATIC: every Stop hook records the session's last state on
+// the lane (intent, files, own commits, the tail of its last reply); when the
+// session goes quiet or closes with its task uncompleted, every new session of
+// any agent sees "unfinished work" at its first brain_sync. DELIBERATE: this
+// verb's `write` puts a 🤝 HANDOFF card into the brain — what is done, what is
+// next, files, how to verify — which the next session takes over by id.
+server.registerTool('brain_handoff', {
+  title: 'Hand unfinished work to the next session — or take over what another session left',
+  description: 'The session handoff. Call {action:"write"} when you are stopping before the work is done — the human asked for a handoff, your context or usage limit is near, the day ends, you are blocked or switching tool — with the task, what is done, what is NEXT in order, the files and how to verify: it becomes a 🤝 card in the project brain that the human can see and correct, and the next session on this project (any agent — Codex, Claude Code, Cursor) sees it at its first brain_sync / session start. Call {action:"take", id} (a card) or {action:"take", session} (unfinished work a session left without a card — KLYPIX records every session\'s last reply, files and commits automatically) before continuing it, so peers see it is taken; {action:"done"} when it is finished (the card is archived); {action:"list"} shows every open handoff and every unfinished session. Never ask the human to paste a summary into the next session — write a handoff. Machine-local for the automatic layer; the card travels with the brain.',
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+  },
+  inputSchema: {
+    action: z.enum(['write', 'take', 'done', 'list']).optional().describe('write (default): record a handoff card. take: claim a handoff card (id) or unfinished work (session) before continuing it. done: mark it finished. list: every open handoff card and every unfinished session on this project.'),
+    project: z.string().optional().describe('Absolute project root containing brain.klypix. Defaults to this connection\'s project.'),
+    canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
+    title: z.string().max(120).optional().describe('write: the work, in a few words ("Drive upload: the Place-it-now chooser").'),
+    task: z.string().max(400).optional().describe('write: one or two sentences — what the work is and why.'),
+    done: z.array(z.string().max(240)).max(12).optional().describe('write: what is already finished (so it is not redone).'),
+    next: z.array(z.string().max(240)).max(12).optional().describe('write: the remaining steps IN ORDER, as the next session should do them. Required.'),
+    files: z.array(z.string().max(200)).max(20).optional().describe('write: project-relative files the work touches (recorded as evidence anchors).'),
+    verify: z.string().max(400).optional().describe('write: how to check the state — a command or a visible result.'),
+    open: z.array(z.string().max(240)).max(8).optional().describe('write: questions still open, or decisions the human has to make.'),
+    reason: z.enum(['context_limit', 'usage_limit', 'end_of_session', 'blocked', 'switching_tool', 'other']).optional().describe('write: why the work stops here.'),
+    area: z.string().max(40).optional().describe('write: the brain area (titled box) the card goes into. Defaults to "Handoff".'),
+    continues: z.string().max(64).optional().describe('write: the id of an earlier handoff card this one continues — it is closed as "continued by" this one.'),
+    id: z.string().max(64).optional().describe('take / done: the handoff card id (from brain_sync, the session-start brief, or list).'),
+    session: z.string().max(160).optional().describe('take / done: the session id (or a unique prefix of 8+ characters) from the unfinished-work list, when the work has no card.'),
+    summary: z.string().max(400).optional().describe('done: what was finished, in one or two sentences. take: an optional note.'),
+  },
+}, async ({ action, project, canvas, ...rest }, extra) => {
+  const identity = extra?.klypixRequestIdentity || {};
+  const result = await opBrainHandoff({
+    vault: project ? path.resolve(project) : mcpPresence.vault,
+    canvas: canvas || boundBrainCanvas(undefined),
+    action: action || 'write',
+    from: { sessionId: identity.sessionId || mcpPresence.id, client: identity.clientInfo?.client || extra?.klypixClientName || 'unknown' },
+    via: extra?.klypixClientName,
+    ...rest,
+  });
+  // Capture receipt, as for brain_note: a written handoff IS this session's
+  // reasoning recorded through MCP — the uncaptured-work nudge must not fire.
+  if ((action || 'write') === 'write' && !result.isError) {
+    try {
+      const { recordSessionCapture } = await import('../src/capture-gap.mjs');
+      recordSessionCapture(identity.sessionId || mcpPresence.id, undefined, Date.now(), { project: mcpPresence.vault });
+    } catch { /* receipt is best-effort */ }
+  }
+  const out = toContent(result);
+  return result.structured ? { ...out, structuredContent: result.structured } : out;
+});
+
 server.registerTool('brain_sync', {
   title: 'KLYPIX Context Gateway — synchronize task, peers, conflicts, and relevant memory',
-  description: 'APPROVAL-FREE task gateway over the authorized MCP connection. Call FIRST with a concise intent and expected files, again when scope changes, and with phase:"complete" before the final response. One bounded response returns compact task-relevant brain context, active TASK peers (idle connections hidden), one-time messages, structured exact-file conflicts, and late-arrival overlap alerts. A completion that supplies machine-checkable result manifests is fail-closed: invalid, conflicting, or incomparable evidence returns needs-reconciliation and retains task scope. Works on any MCP host — it needs only the authorized MCP connection, so native lifecycle hooks are optional. LIMITS: conflict matching is EXACT-PATH and both sessions must have declared their files, coordination/result reconciliation is machine-local and OS-user-local (a teammate on another machine is invisible), and file overlap remains ADVISORY.',
+  description: 'APPROVAL-FREE task gateway over the authorized MCP connection. Call FIRST with a concise intent and expected files, again when scope changes, and with phase:"complete" before the final response. One bounded response returns compact task-relevant brain context, active TASK peers (idle connections hidden), one-time messages, structured exact-file conflicts, and late-arrival overlap alerts. A completion that supplies machine-checkable result manifests is fail-closed: invalid, conflicting, or incomparable evidence returns needs-reconciliation and retains task scope. `results` is ONLY for such manifests, never a summary of the work: with nothing machine-checkable to claim, complete without it. Works on any MCP host — it needs only the authorized MCP connection, so native lifecycle hooks are optional. LIMITS: blocking overlap is EXACT-PATH over the declared files of each session plus the edits its host observed; sessions on different branches are also test-merged with git merge-tree (committed work only); a same-folder overlap is an advisory notice; coordination/result reconciliation is machine-local and OS-user-local (a teammate on another machine is invisible), and file overlap remains ADVISORY.',
   annotations: {
     destructiveHint: false,
     idempotentHint: true,
@@ -1343,6 +1398,23 @@ server.registerTool('brain_sync', {
     .map((block) => block.text)
     .filter(Boolean)
     .join('\n\n') || '';
+  // ── Handoffs (1.99.0): on task START only — the one moment a session asked
+  // to "continue" needs them. Open 🤝 cards + unfinished work other sessions
+  // left on the lane, as one block; a second brain parse, bounded, never
+  // fails a sync. Checkpoints and completions print nothing here.
+  let handoffText = '';
+  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 cards = h?.structured?.handoffs || [];
+      const lane = h?.structured?.unfinished || [];
+      if (!h?.isError && (cards.length || lane.length)) {
+        handoffText = String(h.blocks?.[0]?.text || '').replace(/^_brain:[^\n]*_\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.map((r) => ({ id: r.id, client: r.client, intent: r.intent, status: r.status, lastSeen: r.lastSeen, files: r.files, commits: r.commits, handoffCardId: r.handoffCardId, takenBy: r.takenBy })) };
+      }
+    } catch { /* never fails a sync */ }
+  }
   const totalMs = Math.max(0, Date.now() - totalStartedAt);
   const structuredContent = {
     ...(report.structured || {
@@ -1363,6 +1435,7 @@ server.registerTool('brain_sync', {
     },
     ...(registration ? { registration } : {}),
     ...(harness ? { harness } : {}),
+    ...(handoffData ? { handoffs: handoffData } : {}),
   };
   const harnessText = harness?.failed
     ? `KLYPIX harness self-heal needs attention: ${harness.failed} project(s) remain partially aligned; brain_doctor has the exact files.`
@@ -1374,7 +1447,7 @@ server.registerTool('brain_sync', {
   return {
     content: [{
       type: 'text',
-      text: [report.text, harnessText, shipNotice, releaseReconcileText, captureGapText, contextText, timingText].filter(Boolean).join('\n\n'),
+      text: [report.text, harnessText, shipNotice, releaseReconcileText, captureGapText, 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.97.0",
+  "version": "1.99.0",
   "mcpName": "io.github.dahshanlabs/klypix-mcp",
   "description": "Active state management for multi-agent coding: a shared, versioned project brain over MCP.",
   "type": "module",
@@ -86,7 +86,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/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/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/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/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/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/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/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

@@ -493,6 +493,55 @@ const endedMatches = (row, id) => {
 // ── Session directory upkeep (mailbox) ───────────────────────────────────────
 // PARITY: global-brain-hook.mjs keeps a verbatim twin (dirPrune/dirRemember)
 // because that hook stays free of sibling imports — change both.
+//
+// ── Unfinished work (session handoff, 1.99.0) ────────────────────────────────
+// A session's last known STATE rides its directory entry as `work`, so the
+// work a session stopped in the middle of — at a usage or context limit, a
+// closed window, a crash — is visible to the next session of ANY agent, with
+// no one having to write or paste a summary:
+//   lastPrompt   the last human prompt the session answered
+//   lastWords    the tail of its last reply (where "done / next" usually is)
+//   commits      commits made since the session started (sha + subject)
+//   baseHead     the HEAD the session started from (what `commits` counts from)
+//   handoffCardId a deliberate 🤝 handoff card it wrote into the brain
+//   takenBy      the session that took the work over (brain_handoff take)
+//   doneAt/doneBy marked finished (brain_handoff done)
+// `intentAt` and `completedAt` are copied from the lane row for the same
+// reason: a session whose intent was never completed is the one to show.
+// Every field is capped here, and an empty object is dropped, so an old entry
+// without `work` is byte-stable through a touch that changes nothing.
+export const WORK_LAST_WORDS_MAX = 700;
+export const WORK_COMMITS_MAX = 6;
+export function normalizeWork(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const out = {};
+  const str = (value, max) => String(value || '').replace(/\s+/g, ' ').trim().slice(0, max);
+  const ms = (value) => (Number.isFinite(Number(value)) && Number(value) > 0 ? Number(value) : null);
+  // Both texts are rendered into OTHER sessions' prompts: a capture marker
+  // inside them must never be harvestable there (see neutralizeMarkers).
+  if (raw.lastPrompt) out.lastPrompt = neutralizeMarkers(str(raw.lastPrompt, 240));
+  if (raw.lastWords) out.lastWords = neutralizeMarkers(String(raw.lastWords).replace(/[ \t]+/g, ' ').replace(/\n{3,}/g, '\n\n').trim().slice(0, WORK_LAST_WORDS_MAX));
+  if (ms(raw.lastWordsAt)) out.lastWordsAt = ms(raw.lastWordsAt);
+  if (raw.baseHead) out.baseHead = String(raw.baseHead).trim().slice(0, 40);
+  if (Array.isArray(raw.commits)) {
+    const commits = raw.commits
+      .map((c) => (c && typeof c === 'object' ? { sha: str(c.sha, 12), subject: str(c.subject, 120) } : null))
+      .filter((c) => c && c.sha)
+      .slice(0, WORK_COMMITS_MAX);
+    if (commits.length) out.commits = commits;
+  }
+  if (raw.handoffCardId) out.handoffCardId = str(raw.handoffCardId, 64);
+  if (raw.takenBy && typeof raw.takenBy === 'object' && raw.takenBy.id) {
+    out.takenBy = { id: str(raw.takenBy.id, 160), client: str(raw.takenBy.client, 40) || 'unknown', at: ms(raw.takenBy.at) };
+  }
+  if (ms(raw.doneAt)) { out.doneAt = ms(raw.doneAt); if (raw.doneBy) out.doneBy = str(raw.doneBy, 160); }
+  return Object.keys(out).length ? out : null;
+}
+export function mergeWork(previous, patch) {
+  if (patch === undefined) return normalizeWork(previous);
+  if (patch === null) return null;
+  return normalizeWork({ ...(normalizeWork(previous) || {}), ...(patch && typeof patch === 'object' ? patch : {}) });
+}
 const pruneDirectory = (rows, now) => (Array.isArray(rows) ? rows : [])
   .filter((row) => row && recipientKey(row.id) && now - Number(row.lastSeen || 0) < DIRECTORY_FRESH_MS)
   .map((row) => ({
@@ -508,6 +557,9 @@ const pruneDirectory = (rows, now) => (Array.isArray(rows) ? rows : [])
     lastSeen: Number(row.lastSeen) || now,
     endedAt: Number(row.endedAt) || null,
     hostStatus: row.hostStatus ? String(row.hostStatus).slice(0, 16) : null,
+    ...(Number(row.intentAt) > 0 ? { intentAt: Number(row.intentAt) } : {}),
+    ...(Number(row.completedAt) > 0 ? { completedAt: Number(row.completedAt) } : {}),
+    ...(normalizeWork(row.work) ? { work: normalizeWork(row.work) } : {}),
   }))
   .sort((left, right) => Number(left.lastSeen) - Number(right.lastSeen))
   .slice(-DIRECTORY_CAP);
@@ -524,6 +576,12 @@ function rememberSession(directory, row, now, { ended = false } = {}) {
   const prev = index >= 0 ? rows[index] : null;
   const scope = [...new Set([...normalizeFiles(row.files), ...normalizeFiles(row.observedFiles)])].slice(-8);
   const intent = String(row.intent || '').replace(/\s+/g, ' ').trim().slice(0, 120);
+  // The lane row's own timestamps decide "unfinished": an intent newer than
+  // its completion is work nobody finished. A row that carries neither keeps
+  // what the directory already knew (a hook twin predating 1.99.0).
+  const intentAt = Number(row.intentAt) > 0 ? Number(row.intentAt) : (Number(prev?.intentAt) > 0 ? Number(prev.intentAt) : null);
+  const completedAt = Number(row.completedAt) > 0 ? Number(row.completedAt) : (row.completedAt === null && intent ? null : (Number(prev?.completedAt) > 0 ? Number(prev.completedAt) : null));
+  const work = mergeWork(prev?.work, row.work);
   const entry = {
     id,
     client: String(row.client || prev?.client || 'unknown').slice(0, 40),
@@ -537,6 +595,9 @@ function rememberSession(directory, row, now, { ended = false } = {}) {
     lastSeen: now,
     endedAt: ended ? now : null,
     hostStatus: row.hostStatus ? String(row.hostStatus).slice(0, 16) : (prev?.hostStatus || null),
+    ...(intentAt ? { intentAt } : {}),
+    ...(completedAt ? { completedAt } : {}),
+    ...(work ? { work } : {}),
   };
   if (index >= 0) rows[index] = entry; else rows.push(entry);
   return rows
@@ -957,6 +1018,10 @@ export function upsertSession({
   // Host activity status (mailbox, 1.88.0): 'busy' | 'idle'. Derived from
   // `event` when a writer does not pass it; heartbeats keep the previous value.
   hostStatus = null,
+  // Unfinished-work state (session handoff, 1.99.0): a PATCH merged over the
+  // row's `work` (see normalizeWork) — last reply tail, commits, base head,
+  // handoff card, taken/done stamps. Absent = keep what the row has.
+  work,
   now = Date.now(),
 }) {
   if (!brainPath || !id) return withWriteVerdict([], false, 'no-brain-or-id');
@@ -1119,6 +1184,9 @@ export function upsertSession({
           ...(taskCompleted ? { completedAt: now } : (previous.completedAt ? { completedAt: previous.completedAt } : {})),
         }),
       ...(statusDigestHash !== undefined ? { statusDigestHash: String(statusDigestHash || '').slice(0, 16) } : {}),
+      // ADDITIVE unfinished-work state: merged only when this touch carries a
+      // patch; the `...previous` spread keeps it verbatim otherwise.
+      ...(work !== undefined ? (mergeWork(previous.work, work) ? { work: mergeWork(previous.work, work) } : {}) : {}),
       // ADDITIVE host status: stamped only when this touch carries one, kept
       // verbatim otherwise, so a heartbeat never turns "working" into unknown.
       ...(nextHostStatus
@@ -2824,6 +2892,144 @@ export function listKnownSessions({ brainPath, home, now = Date.now() } = {}) {
   }).sort((left, right) => Number(right.lastSeen) - Number(left.lastSeen));
 }
 
+// ── Unfinished work — the automatic session handoff (1.99.0) ────────────────
+// The field case (2026-10-11): the founder's Claude Code session stops at a
+// usage limit mid-task, and Codex is asked to "continue" — with nothing to
+// continue from but whatever the human pastes. The lane already remembers
+// every exactly-identified session for two weeks; `work` (see normalizeWork)
+// adds the state a Stop hook can record without anyone writing a summary.
+// This is the READ side: every session whose intent was never completed and
+// that nobody is working on right now — closed, or live but quiet — newest
+// first, with its last words, commits and files, and whether another session
+// already took it over. Nothing here starts, wakes or routes a session.
+export const UNFINISHED_QUIET_MS = 10 * 60 * 1000;
+export function clientWord(client) {
+  const key = String(client || '').toLowerCase();
+  if (key === 'claude-code' || key === 'claude') return 'Claude Code';
+  if (key === 'codex') return 'Codex';
+  return key ? key.replace(/(^|[-_ ])([a-z])/g, (_m, p, c) => `${p}${c.toUpperCase()}`) : 'Unknown';
+}
+// How long since the row's host last did WORK: a heartbeat refreshes lastSeen
+// without touching it, so a connected-but-idle MCP session reads as quiet, not
+// as busy. A row with no host status falls back to its last activity/intent.
+const quietFor = (row, now) => {
+  if (!row) return Infinity;
+  const status = String(row.hostStatus || '');
+  if (status === 'busy' && now - Number(row.hostStatusAt || row.lastSeen || now) < HOST_STATUS_BUSY_FRESH_MS) return 0;
+  const at = Number(row.hostStatusAt || row.activityAt || row.intentAt || row.startedAt || row.lastSeen || now);
+  return Math.max(0, now - at);
+};
+export function listUnfinishedWork({ brainPath, home, now = Date.now(), selfId = '', includeWorking = false } = {}) {
+  if (!brainPath) return [];
+  const lane = readLane(laneFileFor(brainPath, home));
+  const live = pruneSessions(lane.sessions, now);
+  const liveRow = (id) => live.find((session) => sessionIdentityKeys(session).includes(String(id || '').toLowerCase())) || null;
+  const self = recipientKey(selfId).toLowerCase();
+  return pruneDirectory(lane.directory, now)
+    .filter((entry) => entry.intent && entry.id.toLowerCase() !== self)
+    .map((entry) => {
+      const row = liveRow(entry.id);
+      const work = entry.work || {};
+      const intentAt = Number(entry.intentAt) || Number(entry.firstSeen) || 0;
+      const completed = Number(entry.completedAt) > 0 && Number(entry.completedAt) >= intentAt;
+      const done = Number(work.doneAt) > 0 && Number(work.doneAt) >= intentAt;
+      const taker = work.takenBy ? liveRow(work.takenBy.id) : null;
+      const quietMs = quietFor(row, now);
+      return { entry, row, work, completed, done, taker, quietMs };
+    })
+    .filter(({ completed, done, quietMs }) => !completed && !done && (includeWorking || quietMs >= UNFINISHED_QUIET_MS))
+    .map(({ entry, row, work, taker, quietMs }) => ({
+      id: entry.id,
+      client: entry.client,
+      intent: entry.intent,
+      intentAt: entry.intentAt || null,
+      branch: entry.branch || null,
+      cwd: entry.cwd || null,
+      files: Array.isArray(entry.files) ? entry.files : [],
+      lastSeen: entry.lastSeen,
+      endedAt: entry.endedAt || null,
+      ageMs: Math.max(0, now - Number(entry.lastSeen || now)),
+      quietMs: Number.isFinite(quietMs) ? quietMs : null,
+      live: Boolean(row),
+      status: row
+        ? (sessionStatusLabel(row, now) || 'live')
+        : (entry.endedAt ? 'closed' : `not seen for ${agoLabel(now - entry.lastSeen).replace(/ ago$/, '')}`),
+      resumeCommand: row ? '' : resumeCommandFor(entry.client, entry.id),
+      lastPrompt: work.lastPrompt || '',
+      lastWords: work.lastWords || '',
+      lastWordsAt: work.lastWordsAt || null,
+      commits: Array.isArray(work.commits) ? work.commits : [],
+      handoffCardId: work.handoffCardId || null,
+      takenBy: work.takenBy
+        ? { ...work.takenBy, live: Boolean(taker), status: taker ? (sessionStatusLabel(taker, now) || 'live') : 'not running' }
+        : null,
+    }))
+    .sort((left, right) => Number(right.lastSeen) - Number(left.lastSeen));
+}
+
+// Stamp unfinished-work state onto one remembered session (directory entry
+// AND its live row when there is one): the writer of a handoff card, the
+// session that takes work over, the one that marks it done. Exact id or a
+// unique prefix; ambiguity and unknown ids fail closed. Machine-local.
+export function stampSessionWork({ brainPath, sessionId, patch, home, now = Date.now() }) {
+  if (!brainPath || !sessionId || !patch || typeof patch !== 'object') return { ok: false, reason: 'invalid-stamp' };
+  const laneFile = laneFileFor(brainPath, home);
+  const lockFile = laneFile + '.lock';
+  if (!acquireLock(lockFile)) return { ok: false, reason: 'lane-locked' };
+  try {
+    const laneRead = readMutableLane(laneFile);
+    if (!laneRead.ok) return { ok: false, reason: laneRead.reason };
+    const data = laneRead.data;
+    const sessions = pruneSessions(data.sessions, now);
+    const directory = pruneDirectory(data.directory, now);
+    const wanted = String(sessionId).trim();
+    const known = resolveDirectoryTarget(wanted, directory);
+    if (known.ambiguous) return { ok: false, reason: 'target-not-unique' };
+    const entry = known.entry;
+    const keys = [wanted.toLowerCase(), ...(entry ? [entry.id.toLowerCase()] : [])];
+    const row = sessions.find((session) => sessionIdentityKeys(session).some((key) => keys.includes(key))) || null;
+    if (!entry && !row) return { ok: false, reason: 'target-unknown' };
+    if (entry) { const merged = mergeWork(entry.work, patch); if (merged) entry.work = merged; else delete entry.work; }
+    if (row) { const merged = mergeWork(row.work, patch); if (merged) row.work = merged; else delete row.work; }
+    fs.mkdirSync(path.dirname(laneFile), { recursive: true });
+    writeLaneFileAtomic(laneFile, JSON.stringify({ ...data, sessions, directory }));
+    return { ok: true, id: entry?.id || row?.logicalSessionId || row?.id, entry: entry || null };
+  } catch (error) {
+    return { ok: false, reason: writeFailureReason(error) };
+  } finally {
+    releaseLock(lockFile);
+  }
+}
+
+// The block every surface prints (brain_sync, the Claude and Codex hooks):
+// one record per unfinished session, newest first, then how to take it over.
+// Quoted text is another session's record and is labelled as such — never as
+// the human's instructions; markers inside it were neutralized at store time.
+export function formatUnfinishedWork(records, { now = Date.now(), max = 5, cardTitles = null } = {}) {
+  const list = Array.isArray(records) ? records : [];
+  if (!list.length) return '';
+  const flat = (value) => String(value || '').replace(/\s+/g, ' ').trim();
+  const lines = [`⏸️ Unfinished work left by other sessions on this project (${list.length}, newest first) — each stopped before its task was done and nobody is working on it now:`];
+  for (const r of list.slice(0, max)) {
+    const who = `${clientWord(r.client)} ${String(r.id).slice(0, 8)}`;
+    const bits = [r.status, `last active ${agoLabel(r.ageMs)}`];
+    if (r.branch) bits.push(`branch ${r.branch}`);
+    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: ${r.files.slice(-8).join(', ')}`);
+    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)`);
+    }
+    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}`);
+  }
+  if (list.length > max) lines.push(`- …and ${list.length - max} more — brain_handoff {action:"list"} shows all.`);
+  lines.push('To continue one: brain_handoff {action:"take", session:"<its id>"} (peers then see it is taken), then brain_sync with that intent and files; when it is finished, brain_handoff {action:"done", session:"<its id>"}. If it is not what the human asked for, leave it.');
+  return lines.join('\n');
+}
+
 // ── Reopen on the human's OK (1.91.0) ───────────────────────────────────────
 // A note to a session that has closed waits up to a week and is delivered the
 // moment that session next acts — but only if a human happens to reopen it.

package/src/agent-rules.mjs

@@ -86,6 +86,8 @@ const CODEX_GLOBAL_BODY = [
   'To reach another agent session on this project, call `brain_message` with its session id (from',
   '`brain_sync` or `brain_doctor`); a session that has closed receives the note when it next starts.',
   'Never ask the human to carry a message between agents — send it and say it was sent or queued.',
+  'Stopping before the work is done (limit, end of day, blocked)? Call `brain_handoff` {action:"write"} with what is done, what is next, files and how to verify;',
+  'the next session of any agent sees it at its first `brain_sync` and takes it with {action:"take"}. Asked to continue what another session left? Take it there first.',
   'Capture durable decisions and milestones with `brain_note`. Never hand-edit `brain.klypix`.',
   'If the project has no `brain.klypix`, ignore this section.',
   CODEX_GLOBAL_END,
@@ -503,6 +505,16 @@ otherwise ask the human to relay or paste something to another agent session, se
 \`brain_message\` refuses. Notes are ephemeral, NOT brain cards — durable decisions still go
 through \`brain_note\`.
 
+**Stopping before the work is done?** (the human asks for a handoff, your context or usage limit
+is near, the day ends, you are blocked, you are switching tool) Call \`brain_handoff\`
+{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. Never ask the human to paste a summary into the next session.
+
 **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.`;
 
 // Content fingerprint of the canonical instructions — stamped into the fence so a