klypix-mcp 1.100.0 → 1.101.0

package/README.md

@@ -597,16 +597,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

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,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.100.0",
+  "version": "1.101.0",
   "mcpName": "io.github.dahshanlabs/klypix-mcp",
   "description": "Active state management for multi-agent coding: a shared, versioned project brain over MCP.",
   "type": "module",

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 } = {}) {