klypix-mcp 1.100.0 → 1.101.1

package/README.md

@@ -1,20 +1,34 @@
-# Every project gets a brain.
+# klypix-mcp — shared project memory for Claude Code, Codex and Cursor
+
+**Every project gets a brain.**
 
 Shared project memory for **Claude Code, Codex, Cursor** and other MCP coding tools. One
 `brain.klypix` file, committed with your code, carries the project's decisions, corrections and open
 questions across sessions and between tools. Corrections supersede stale decisions; sessions declare
 the files they expect to touch and get warned about same-machine overlap. Versioned in Git. Served
-over MCP by a process on your machine; Klypix uploads nothing (your agent's provider still receives
-what the agent reads). Integration depth differs by host — see
+over MCP by a process on your machine. In the standalone setup, brain data stays in your files;
+your agent's provider can still receive what the agent reads. Integration depth differs by host — see
 [Supported hosts](#supported-hosts-and-their-integration-level).
 
+The **Apache-2.0 engine works without the KLYPIX desktop app or a KLYPIX account**. The optional
+[Windows workspace](https://klypix.com/developers) lets people inspect the same project brain
+beside their files. App-based sharing has its own cloud path; see [Security and permissions](#security-and-permissions).
+
+[Install](#quick-start) · [Try your first decision](#your-first-decision-and-correction) ·
+[Supported hosts](#supported-hosts-and-their-integration-level) ·
+[Privacy](#security-and-permissions) · [Limits](#current-limitations) · [Uninstall](#uninstall)
+
+For a team walkthrough, read the [shared project memory setup guide](https://klypix.com/guides/shared-project-memory).
+Choosing an approach? Our [memory tools comparison](https://klypix.com/guides/shared-project-memory-tools)
+links each tool's official documentation and discloses that Klypix wrote it.
+
 ![Two real MCP sessions on one project: Session B declares a file Session A already declared, and the server's exact-file-overlap warning fires; Session A then records a correction that supersedes its stale card](docs/demo/demo.gif)
 
 <sub>Real output, not a mockup: both panes run a real MCP client against this server
 ([docs/demo/](docs/demo/) — the GIF is rendered by CI from a scripted tape against this server, not
 hand-recorded, and re-rendered when the server's responses change).</sub>
 
-Run this inside your project:
+With **Node.js 20 or newer**, run this inside your project:
 
 ```bash
 npx klypix-mcp install
@@ -59,15 +73,14 @@ carry forward into supported coding-agent sessions.
 ## The problem
 
 You are running more than one coding agent on one codebase — a Claude Code session here, Codex in
-another terminal, Cursor open on the side. Each one has excellent memory of *itself* and none of
-the others:
+another terminal, Cursor open on the side. Context saved in one tool may be missing from the next:
 
-- Every new session starts from zero, and you explain the same architecture again.
-- Codex does not know what Claude learned an hour ago.
+- A new session misses a prior decision, and you explain the same architecture again.
+- A decision captured only in a Claude conversation is unavailable to your Codex session.
 - One agent implements an approach the team already rejected, because the reason it was rejected
   lived in a chat that ended.
 - Two sessions start changing the same files and nobody finds out until review.
-- Git stores the code history. It does not store a reliable history of project *intent*.
+- Git stores the code history; the reasons behind a change still need to be recorded.
 
 Your agents may run independently. Their project understanding should not.
 
@@ -75,10 +88,14 @@ Your agents may run independently. Their project understanding should not.
 
 ## 60 seconds: two agents, one project
 
+Illustrative calls and responses: replace `/absolute/path/to/project` with the same project root
+in both sessions (for example, `C:/work/api` on Windows).
+
 Session A — Claude Code, in your repo:
 
 ```jsonc
-brain_sync { intent: "rewrite the auth token refresh", files: ["src/auth/token.ts"] }
+brain_sync { project: "/absolute/path/to/project", phase: "start",
+             intent: "rewrite the auth token refresh", files: ["src/auth/token.ts"] }
 // → task-relevant memory capsule (bounded, ~2.8KB)
 // → peers: none
 ```
@@ -86,7 +103,8 @@ brain_sync { intent: "rewrite the auth token refresh", files: ["src/auth/token.t
 Session B — Codex, same repo, half a minute later:
 
 ```jsonc
-brain_sync { intent: "add rate limiting to the auth routes",
+brain_sync { project: "/absolute/path/to/project", phase: "start",
+             intent: "add rate limiting to the auth routes",
              files: ["src/auth/token.ts", "src/auth/routes.ts"] }
 // → task capsule
 // → peers: 1 active session (claude-code) — "rewrite the auth token refresh"
@@ -100,7 +118,7 @@ expected to touch.
 Then the brain pushes back before the decision, not after:
 
 ```jsonc
-brain_challenge { "move token storage to localStorage" }
+brain_challenge { claim: "move token storage to localStorage" }
 // → "reversed on June 12 — here's the correction card, captured by a different agent."
 ```
 
@@ -213,6 +231,59 @@ npx klypix-mcp link --check    # audits without writing; exits non-zero on drift
 [KLYPIX app](https://klypix.com) does it in one click (*Save canvas as project brain*), or
 `create_canvas` makes one from any agent.
 
+### Your first decision and correction
+
+After installation, reopen your coding tool or reconnect its MCP server, and allow the KLYPIX
+tools if your host asks. Run `npx klypix-mcp doctor` in the project to inspect the installation;
+a clean config report does not prove that your host has loaded the tools.
+
+Try the following in a **disposable trial project**, or replace the example decision with a real
+one before saving it. These are MCP tool calls for your agent, not shell commands. Replace
+`/absolute/path/to/project` with your project root throughout. The `files: []` scope means this
+trial does not plan source-code edits.
+
+1. **Record a decision and its reason.** Ask your agent to call:
+
+   ```jsonc
+   brain_sync { project: "/absolute/path/to/project", phase: "start",
+                intent: "Record the trial storage decision", files: [] }
+   brain_note { area: "Storage",
+                text: "Use SQLite for the trial project database because this prototype runs on one machine." }
+   brain_sync { project: "/absolute/path/to/project", phase: "complete" }
+   ```
+
+2. **Open a fresh session in the same project**, optionally in a different supported coding tool.
+   Ask it to retrieve the decision rather than infer the answer from your code:
+
+   ```jsonc
+   brain_sync { project: "/absolute/path/to/project", phase: "start",
+                intent: "Review the trial storage decision", files: [] }
+   brain_ask { question: "Which database does the trial project use, and why?" }
+   ```
+
+   Check that the returned card contains SQLite and the one-machine rationale. If the tool is
+   missing, reconnect the host and check the [host integration table](#supported-hosts-and-their-integration-level).
+   If the card is missing, confirm both sessions used the same project and that `brain_note`
+   reported a successful capture. A fresh brain only knows what has been recorded.
+
+3. **Change the trial decision explicitly**, then ask again:
+
+   ```jsonc
+   brain_note { area: "Storage",
+                text: "CORRECTION: Use PostgreSQL instead of SQLite for the trial project database because the trial now needs concurrent writes from several machines." }
+   brain_ask { question: "Which database does the trial project use now, and why?" }
+   brain_sync { project: "/absolute/path/to/project", phase: "complete" }
+   ```
+
+   Inspect the returned source cards: PostgreSQL should be the current decision, with SQLite
+   retained as superseded history. Confirm that the correction names the earlier decision; a
+   correction cue alone is not a guarantee of a match. This small trial checks your capture and
+   recall path. It does not establish retrieval quality for a larger brain or prove host automation.
+
+For a team on different machines, follow the [Git sharing steps](https://klypix.com/guides/shared-project-memory#team)
+and install in each clone. Standalone live presence and file-overlap warnings stay local to one
+machine and OS user. Keep approved architecture records and stable conventions alongside the brain.
+
 ---
 
 ## How the brain works
@@ -597,16 +668,29 @@ and the person opens Codex (or a fresh Claude Code) and says *continue*. Until 1
 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.
+**Automatic — whichever agent stopped.** Each session's last state is recorded on the lane that
+already remembers sessions for two weeks, by whatever that host offers:
+
+| Host | Recorded automatically |
+|---|---|
+| Claude Code (hooks) | last prompt, the tail of the last reply, files edited, its *own* commits |
+| Codex (hooks) | last prompt, the tail of the last reply, files edited, its *own* commits |
+| Any MCP host — Cursor, VS Code, Windsurf, Gemini CLI, … | the task and files it declared with `brain_sync` |
+
+*Own* commits are the shas that session's `git commit` printed, never a branch range, because
+twenty sessions can share one checkout. A session is listed when it stopped in the last 24 hours
+without completing its task — quiet for ten minutes, or closed — and left a record. A session that
+recorded nothing is never listed, so finished chats do not pile up.
+
+The next session on the project, in any agent, sees **⏸️ Work other sessions may have left
+unfinished** at its first `brain_sync` when its task is to continue something ("continue what Codex
+was doing on the invoice" puts that session first) or touches a file one of them touched. It sees the
+same list at session start. Each record carries its status, files, commits, last words and resume
+command. It says, in the text and in the JSON (`state`, `working:false`, `holdsFiles:false`), that
+the session is not running, holds no claim on any file, and that a "do not touch" note it left no
+longer applies: the list is history, not a lock. The agent takes a record over with
+`brain_handoff {action:"take", session:"<id>"}` so peers see it is taken, then marks it `done`. This
+layer is 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
@@ -1174,8 +1258,11 @@ Read this section before you build on any of it.
   that list together with the shared one.
 - **`npx klypix-mcp link` does not manage `CLAUDE.md`.** It manages `AGENTS.md` and seven other
   rules files. Only the desktop app writes `CLAUDE.md`.
-- **A fresh `npx klypix-mcp install` gets lexical retrieval.** The optional on-device model is
-  deliberately not installed.
+- **Semantic retrieval depends on the install path.** An interactive terminal install enables
+  the on-device search runtime by default. CI and noninteractive installs need `--semantic`;
+  `--no-semantic` (or `KLYPIX_SEMANTIC=0`) opts out. The Claude plugin stays keyword-only. Without
+  the model, retrieval uses keywords; a model download or a brain still being prepared is not a
+  guarantee that a particular decision will be found.
 - **The capture lock is fail-open** past ~3.6 seconds of contention (see *Git and concurrency*).
 - **`test/` is not in the published tarball.** Run the suite from a clone. The publish workflow
   *does* gate on it — a `gate` job runs `npm ci`, asserts the test chain is intact, runs `npm test`,
@@ -1208,7 +1295,8 @@ independently validated.
   2026-10-11 on the same brain grown to 3,829 cards (102 of the frozen questions still answerable),
   with words written by Gemini 2.5 Flash as a stand-in for the calling agent: recall@5 54% → 59%
   (8 found, 3 lost), recall@8 61% → 68%, recall@20 68% → 76%, MRR 0.375 → 0.424. With no local
-  model (a fresh install, the Claude plugin) the words count as extra keywords at half weight:
+  model (for example, an install with `--no-semantic` or the Claude plugin) the words count as extra
+  keywords at half weight:
   recall@5 19% → 24% (5 found, none lost), recall@10 25% → 31%. Without the line, ranking is
   unchanged byte for byte.
 - **Second brain.** The same ranker on a different project's brain (1,601 cards, 19 hand-written
@@ -1240,14 +1328,17 @@ independently validated.
 ## Uninstall
 
 ```bash
-npx klypix-mcp uninstall --check   # full inventory — writes nothing
-npx klypix-mcp uninstall           # asks, then removes the machine-global install
-npx klypix-mcp uninstall unlink    # run inside a project: removes the files `link` wrote there
+npx klypix-mcp uninstall --check          # preview machine-global removal — writes nothing
+npx klypix-mcp uninstall --yes            # remove the machine-global install
+npx klypix-mcp uninstall unlink --check   # preview this project's managed files
+npx klypix-mcp uninstall unlink --yes     # remove this project's managed files
 ```
 
 It strips only KLYPIX's own entries — every other hook and setting in
 `~/.claude/settings.json` stays — backs up each file it edits, and **never deletes a `.klypix`**.
-`--yes` skips the prompt for scripted removal.
+Removal requires `--yes`. Without it, the command prints the plan and changes nothing;
+there is no interactive confirmation prompt. Run the project-local form in each project you
+want to unlink. A preview exits non-zero while managed files remain.
 
 Your `brain.klypix` is yours — it is a plain ZIP and stays readable with or without this package.
 
@@ -1266,10 +1357,9 @@ are not in the published tarball, though the publish workflow does run them as a
 
 ## Why this exists
 
-A model provider can fix continuity inside its own sessions, and several are. None of them will
-ever carry a competitor's context. Cross-tool, cross-agent and cross-provider understanding is the
-seam that stays open — so it should live in a file you own, in your repo, that any agent can read
-and write.
+Coding tools have their own memory and instruction systems. A team using several tools still
+needs a shared place for decisions, reasons and corrections. Keeping that record in a file you
+own lets supported agents read and update it through the same interface.
 
 **Your project, your file, any supported agent, offline.**
 

package/bin/klypix-worker.mjs

@@ -1418,13 +1418,28 @@ server.registerTool('brain_sync', {
       const wantsContinue = HANDOFF_CONTINUE_RE.test(String(intent || ''));
       const normPath = (p) => String(p || '').replace(/\\/g, '/').toLowerCase();
       const mine = new Set((Array.isArray(files) ? files : []).map(normPath));
-      const lane = (h?.structured?.unfinished || []).filter((r) => wantsContinue
-        || (Array.isArray(r.files) && r.files.some((p) => mine.has(normPath(p)))));
+      const overlaps = (r) => Array.isArray(r.files) && r.files.some((p) => mine.has(normPath(p)));
+      // "continue what codex was doing on the invoice": rank by what the
+      // request names — the agent, words of the task, last words, files,
+      // commit subjects — then by recency, so the one meant leads the list.
+      const words = new Set(String(intent || '').toLowerCase().match(/[\p{L}\p{N}_-]{3,}/gu) || []);
+      for (const w of ['continue', 'resume', 'what', 'was', 'were', 'doing', 'the', 'and', 'left', 'off', 'where', 'session', 'other', 'work', 'pick', 'carry', 'keep', 'going', 'finish', 'take', 'over', 'handoff', 'hand']) words.delete(w);
+      const relevance = (r) => {
+        const hay = [r.client === 'claude-code' ? 'claude' : r.client, r.intent, r.lastPrompt, r.lastWords, ...(r.files || []), ...(r.commits || []).map((c) => c.subject)].join(' ').toLowerCase();
+        let n = 0;
+        for (const w of words) if (hay.includes(w)) n++;
+        return n + (overlaps(r) ? 3 : 0);
+      };
+      const lane = (h?.structured?.unfinished || [])
+        .filter((r) => wantsContinue || overlaps(r))
+        .map((r) => ({ r, score: relevance(r) }))
+        .sort((a, b) => b.score - a.score || Number(b.r.lastSeen || 0) - Number(a.r.lastSeen || 0))
+        .map(({ r }) => r);
       if (!h?.isError && (cards.length || lane.length)) {
         const now = Date.now();
         handoffText = [
           formatHandoffCards(cards, { now, max: 5 }),
-          formatUnfinishedWork(lane, { now, max: 4 }),
+          formatUnfinishedWork(lane, { now, max: 4, ranked: wantsContinue && words.size > 0 }),
         ].filter(Boolean).join('\n\n');
         handoffData = {
           cards: cards.length,

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "klypix-mcp",
-  "version": "1.100.0",
+  "version": "1.101.1",
   "mcpName": "io.github.dahshanlabs/klypix-mcp",
-  "description": "Active state management for multi-agent coding: a shared, versioned project brain over MCP.",
+  "description": "Shared project memory for Claude Code, Codex and Cursor: decisions and corrections through MCP.",
   "type": "module",
   "license": "Apache-2.0",
   "keywords": [
     "mcp",
     "model-context-protocol",
+    "mcp-server",
+    "claude-code",
+    "codex",
+    "cursor",
+    "shared-memory",
     "multi-agent",
     "agent-coordination",
     "project-memory",
@@ -24,7 +29,7 @@
     "klypix",
     "ai"
   ],
-  "homepage": "https://github.com/dahshanlabs/klypix-mcp#readme",
+  "homepage": "https://klypix.com/developers",
   "repository": {
     "type": "git",
     "url": "https://github.com/dahshanlabs/klypix-mcp"

package/src/agent-presence.mjs

@@ -535,12 +535,28 @@ export function normalizeWork(raw) {
     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); }
+  // 1.99.1 (universal): a task DECLARED through brain_sync — any MCP host,
+  // 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);
   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 prev = normalizeWork(previous) || {};
+  const next = patch && typeof patch === 'object' ? { ...patch } : {};
+  // `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`.
+  if (Array.isArray(next.addCommits)) {
+    const seen = new Set();
+    next.commits = [...(prev.commits || []), ...next.addCommits]
+      .filter((c) => c && c.sha && !seen.has(String(c.sha).slice(0, 7)) && seen.add(String(c.sha).slice(0, 7)))
+      .slice(-WORK_COMMITS_MAX);
+    delete next.addCommits;
+  }
+  return normalizeWork({ ...prev, ...next });
 }
 const pruneDirectory = (rows, now) => (Array.isArray(rows) ? rows : [])
   .filter((row) => row && recipientKey(row.id) && now - Number(row.lastSeen || 0) < DIRECTORY_FRESH_MS)
@@ -1186,7 +1202,14 @@ export function upsertSession({
       ...(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) } : {}) : {}),
+      ...(() => {
+        // A brain_sync-DECLARED task (any MCP host) is itself a work record:
+        // stamp declaredAt beside whatever patch this touch carries.
+        const declared = intentSource === 'declared' && intentChanged && nextIntent ? { declaredAt: now } : null;
+        if (work === undefined && !declared) return {};
+        const merged = mergeWork(previous.work, { ...(work && typeof work === 'object' ? work : {}), ...(declared || {}) });
+        return merged ? { work: merged } : {};
+      })(),
       // ADDITIVE host status: stamped only when this touch carries one, kept
       // verbatim otherwise, so a heartbeat never turns "working" into unknown.
       ...(nextHostStatus
@@ -2914,7 +2937,10 @@ export const UNFINISHED_QUIET_MS = 10 * 60 * 1000;
 // and every record says, in text and JSON, that it is not running and holds
 // no claim on any file.
 export const UNFINISHED_WINDOW_MS = 24 * 60 * 60 * 1000;
-export const hasWorkEvidence = (work) => Boolean(work && (work.lastWords || (Array.isArray(work.commits) && work.commits.length) || work.handoffCardId));
+// 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));
 export function clientWord(client) {
   const key = String(client || '').toLowerCase();
   if (key === 'claude-code' || key === 'claude') return 'Claude Code';
@@ -3026,11 +3052,11 @@ export function stampSessionWork({ brainPath, sessionId, patch, home, now = Date
 // 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 } = {}) {
+export function formatUnfinishedWork(records, { now = Date.now(), max = 5, cardTitles = null, ranked = false } = {}) {
   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, 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 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:`];
   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)}`];

package/src/codex-brain-hook.mjs

@@ -371,6 +371,8 @@ async function statusDigestContext({ brainPath, sessionId, prompt, sessions, cwd
 // ⏸️ Unfinished work other sessions left — the engine's block (agent-presence
 // listUnfinishedWork + formatUnfinishedWork), read-only, never throws.
 const CONTINUE_PROMPT_RE = /\b(continue|resume|pick (it |this |that )?up|carry on|keep going|where (were|did) we|what('s| is| was) (next|left|remaining|pending)|unfinished|left off|hand[- ]?off|handed (over|off)|take over|finish (what|the work|it|this))\b/i;
+const HANDOFF_ASK_PROMPT_RE = /\b(hand[- ]?off|hand (it|this|the work) (over|off)|before (we|i|you) (hit|reach|approach|run out of) (the )?(limit|context|window|quota)|(context|usage|token|rate) (limit|window|quota)|out of context|switch(ing)? to (claude|another (agent|session|tool)))\b/i;
+const CODEX_HANDOFF_HINT = '🤝 KLYPIX: to hand this session\'s work to the next one (any agent — Claude Code or Codex), call brain_handoff with the task, what is done, what is next, the files and how to verify; the next session on this project sees it at its first brain_sync and takes it with {action:"take"}. Your last reply and commits are recorded automatically at each turn end regardless — but a deliberate handoff says what you know. Never make the human paste a summary into the next session.';
 function unfinishedWorkBlock(brainPath, sessionId) {
   try {
     return formatUnfinishedWork(listUnfinishedWork({ brainPath, selfId: sessionId }));
@@ -390,8 +392,31 @@ function codexWorkPatch({ event, humanTurn, prompt, input }) {
     const text = typeof words === 'string' ? words.trim() : '';
     if (text) { patch.lastWords = text.length > 700 ? '…' + text.slice(-699) : text; patch.lastWordsAt = Date.now(); }
   }
+  // 1.99.1 (universal): this session's OWN commits, from the output git
+  // printed for a commit it ran ("[branch abc1234] subject") — never a branch
+  // range, which would credit a peer's commits in a shared checkout.
+  if (event === 'PostToolUse') {
+    const commits = commitsFromToolResult(input);
+    if (commits.length) patch.addCommits = commits;
+  }
   return Object.keys(patch).length ? patch : null;
 }
+function toolOutputText(input) {
+  const r = input.tool_response ?? input.toolResponse ?? input.tool_output ?? input.toolOutput;
+  if (typeof r === 'string') return r;
+  if (!r || typeof r !== 'object') return '';
+  const parts = [r.output, r.stdout, r.aggregated_output, r.formatted_output, r.text, r.content];
+  return parts.map((p) => (typeof p === 'string' ? p : Array.isArray(p) ? p.map((x) => (typeof x === 'string' ? x : x?.text || '')).join('\n') : '')).filter(Boolean).join('\n');
+}
+export function commitsFromToolResult(input) {
+  const ti = input.tool_input || input.toolInput || {};
+  const cmd = typeof ti === 'string' ? ti : [ti.command, ti.cmd, Array.isArray(ti.command) ? ti.command.join(' ') : ''].filter((v) => typeof v === 'string').join(' ');
+  if (!/\bgit\b[^\n]*\bcommit\b/.test(cmd)) return [];
+  const out = toolOutputText(input);
+  const commits = [];
+  for (const m of out.matchAll(/^\[[^\]\n]{1,80}?\s([0-9a-f]{7,40})\]\s+(.+)$/gm)) commits.push({ sha: m[1].slice(0, 12), subject: m[2].trim().slice(0, 120) });
+  return commits.slice(0, 6);
+}
 
 async function compactTaskContext(projectDir, prompt, files) {
   if (!prompt) return '';
@@ -533,6 +558,8 @@ async function main() {
       stampReceivedMessages(messages, Date.now(), undefined, sessionId),
       // Only on a continue-shaped human prompt — SessionStart printed it once.
       ...(prompt && CONTINUE_PROMPT_RE.test(prompt) ? [unfinishedWorkBlock(brainPath, sessionId)] : []),
+      // The human asked for a handoff or named the limit (Codex has one too).
+      ...(prompt && HANDOFF_ASK_PROMPT_RE.test(prompt) ? [CODEX_HANDOFF_HINT] : []),
     ], event);
     return;
   }

package/src/global-brain-hook.mjs

@@ -1086,6 +1086,7 @@ function workNorm(raw) {
     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); }
+    if (ms(raw.declaredAt)) out.declaredAt = ms(raw.declaredAt);   // 1.99.1 twin: a brain_sync-declared task (any MCP host)
     return Object.keys(out).length ? out : null;
 }
 const workMerge = (prev, patch) => (patch === undefined ? workNorm(prev) : patch === null ? null : workNorm({ ...(workNorm(prev) || {}), ...(patch && typeof patch === 'object' ? patch : {}) }));
@@ -1470,7 +1471,7 @@ const UNFINISHED_QUIET_MS = 10 * 60 * 1000;
 // 1.99.1 twin of agent-presence UNFINISHED_WINDOW_MS / hasWorkEvidence: only a
 // session that stopped in the last 24h AND left a 1.99+ work record is listed.
 const UNFINISHED_WINDOW_MS = 24 * 60 * 60 * 1000;
-const hasWorkEvidence = (w) => Boolean(w && (w.lastWords || (Array.isArray(w.commits) && w.commits.length) || w.handoffCardId));
+const hasWorkEvidence = (w) => Boolean(w && (w.lastWords || (Array.isArray(w.commits) && w.commits.length) || w.handoffCardId || w.declaredAt));
 const CONTINUE_RE = /\b(continue|resume|pick (it |this |that )?up|carry on|keep going|where (were|did) we|what('s| is| was) (next|left|remaining|pending)|unfinished|left off|hand[- ]?off|handed (over|off)|take over|finish (what|the work|it|this))\b/i;
 const HANDOFF_ASK_RE = /\b(hand[- ]?off|hand (it|this|the work) (over|off)|before (we|i|you) (hit|reach|approach|run out of) (the )?(limit|context|window|quota)|(context|usage|token) (limit|window|quota)|out of context|switch(ing)? to (codex|another (agent|session|tool)))\b/i;
 function unfinishedFooter(sid, { max = 4 } = {}) {