klypix-mcp 1.89.0 → 1.90.1

package/README.md

@@ -460,8 +460,8 @@ receiving model calls `brain_message_receipt` with the exact message id and per-
 token; only that token-bound action records `consumed`. Pending, offered, and acknowledged notes
 survive reconnects. Expiry or bounded-capacity eviction records a failed per-recipient receipt
 instead of silently looking delivered. The send-time audience is fixed, unresolved targeted sends
-fail closed, the core lane is machine-local, notes expire after 24 hours, and they are never written
-into the brain.
+fail closed, the core lane is machine-local, a note to every session expires after 24 hours and a
+directed note after 7 days, and notes are never written into the brain.
 
 Durable handoffs go in the brain itself — decisions, findings, open questions and skills captured
 as cards, each stamped with the agent that wrote it.
@@ -750,19 +750,59 @@ replaceable worker runs the brain core. A staged update is hash-verified, initia
 checked for backward-compatible tool schemas, and handed the current `brain_sync` task scope before
 the supervisor switches between requests. Added tools use the standard
 `notifications/tools/list_changed` signal. A failed or breaking candidate is rejected while the old
-worker keeps serving. A blocked result claim is kept in a durable per-project/session marker, so a
-worker replacement cannot turn a failed evidence check into a result-less completion.
+worker keeps serving. A connection idle for 10 minutes releases its worker and keeps its presence;
+it stays asleep until its host sends a request, and the new worker it then starts passes the same
+checks. If they reject it, the connection resumes the version it last ran, or answers with a
+retryable `/mcp reconnect` error rather than restarting in a loop. A blocked result claim is kept
+in a durable per-project/session marker, so a worker replacement cannot turn a failed evidence
+check into a result-less completion.
 
 Compatible engine updates therefore activate behind the same live connection — no reconnect, no
 host restart. Three cases still require a deliberate reconnect or manual install: the one-time
-legacy→supervisor migration, a supervisor-code change, and a major or tool-removing release.
-`brain_doctor` reports the live supervisor and the automatic-update receipt explicitly.
-
-The supervisor performs **one machine-wide npm version check per 24 hours**, however many sessions
-are open. It installs an exact stable same-major release in `--runtime-only` mode, preserving host
-settings and project files. The check is detached and fail-open, developer-owned installs are
-protected, concurrent sessions collapse behind one lock, and `KLYPIX_AUTO_UPDATE=0` opts out
-entirely.
+legacy→supervisor migration, a supervisor-code change, and a major or tool-removing release. Fixes
+to the supervisor itself reach a connection only after one `/mcp` reconnect or a host restart;
+worker and doctor changes hot-swap. `brain_doctor` reports the live supervisors (including how many
+still run older supervisor code) and the automatic-update schedule: the last result, which install
+it describes, and when the next check runs. The MCP tool also returns these as structured data.
+
+The updater checks npm **once per machine every 6 hours**, however many sessions are open. It
+checks once more, never sooner than 5 minutes after the last attempt, when another install upgrades
+this runtime or moves it from a developer deploy to a released install. Examples are a manual
+`npx klypix-mcp install` of a newer release, or a release replacing a developer deploy. A failed
+check retries after 15 minutes, then 1 hour, then 4 hours, then returns to the 6-hour cadence. Each
+attempt is recorded as failed before it touches the network, so a check that dies part-way backs
+off instead of retrying in a loop. Checks run from the open KLYPIX sessions: the supervisor and
+worker look every 10 minutes, and a new session looks 2 seconds after it starts.
+
+The updater installs an exact stable release of the **same major version** in `--runtime-only`
+mode, preserving host settings and project files; a new major always needs a manual install. It
+never downgrades. A deliberate downgrade (`npx klypix-mcp@<older> install --force`) onto a release
+newer than 1.89.0 is **held**: the updater does not re-install the version it was rolled back from,
+only a newer release. To take the held version back, run `npx -y klypix-mcp@latest install` (or set
+`KLYPIX_AUTO_UPDATE_FORCE=1` where `KLYPIX_AUTO_UPDATE` is set, below, for one check, then remove
+it). A rollback onto 1.89.0 or earlier also rolls the updater back, and those releases have no
+hold: they re-install the newest same-major release within 24 hours of their last check. To stay
+on such a release, set `KLYPIX_AUTO_UPDATE=0` in every place listed below for as long as you stay;
+`brain_doctor` warns when a downgrade is not held. The updater never fetches anything for a
+developer-owned install and never installs over it. The check is detached and fail-open, and
+concurrent sessions collapse behind one lock.
+
+`KLYPIX_AUTO_UPDATE=0` opts out. Every process reads its own environment, so set it in each host's
+launch environment: the `env` of each KLYPIX MCP server entry, and the environment Claude Code runs
+its hooks in. It takes effect at that host's next supervisor start or `/mcp` reconnect.
+
+There is one second, smaller probe. In a brain project (a directory with `./brain.klypix`), the
+Claude Code Stop hook refreshes a local npm-version cache, which the next SessionStart reads to say
+whether an update is available. That notice also says what the updater will do with the update,
+and when. The probe:
+
+- runs at most once a day, developer-owned installs included;
+- makes the same kind of anonymous request the updater makes, a GET of
+  `https://registry.npmjs.org/klypix-mcp/latest` that carries no user or machine identifier;
+- is skipped while the updater fetched npm's latest version less than a day ago;
+- is off with the same `KLYPIX_AUTO_UPDATE=0`, read from the environment Claude Code runs its hooks
+  in;
+- never installs anything.
 
 When the optional semantic runtime is already enabled, an update also schedules one detached,
 single-writer cache migration across registered brains. That removes the multi-minute first-query
@@ -774,9 +814,13 @@ keep lazy first-use indexing instead.
 
 - **Apache-2.0, source public** at [github.com/dahshanlabs/klypix-mcp](https://github.com/dahshanlabs/klypix-mcp).
 - **The brain engine makes no network calls and sends no telemetry.** All engine intelligence is
-  deterministic and local; the only LLM anywhere is *your* agent. The one exception in this package
-  is the supervisor's once-per-24h npm version check described above — turn it off with
-  `KLYPIX_AUTO_UPDATE=0`.
+  deterministic and local; the only LLM anywhere is *your* agent. The exceptions in this package
+  are the two update probes described above. One is the updater's npm version check, every 6
+  hours, plus one re-check after another install upgrades the runtime, and retries after a failed
+  check (15 minutes, 1 hour, 4 hours); when it finds a newer same-major release, it also runs that
+  release's npm install. The other is the Claude Code Stop hook's version probe, at most once a day
+  in brain projects. Both are the same kind of anonymous GET of the package's `latest` version, and
+  `KLYPIX_AUTO_UPDATE=0` turns both off.
 - **The optional semantic model runs on device.** Enabling it (or upgrading its model) can fetch
   model weights from Hugging Face; retrieval inference and brain data stay local.
 - **Coordination state is local files.** The brain is a file in your repo; the presence lane is a
@@ -869,8 +913,8 @@ independently validated.
   fewer than four content words: junk injection 93% → 35%, mean cards injected on junk 3.6 → 1.5,
   at a one-question cost on the 35 real prompts (inside noise). The prompts stay private; the
   sweep tables are in the source next to the bars they chose.
-- **What we do not publish.** No download count: this package's own 24-hour auto-updater generates
-  most of it, so it is not a user count. No adoption, team or customer figures. No brief-token
+- **What we do not publish.** No download count: this package's own auto-updater generates most
+  of it, so it is not a user count. No adoption, team or customer figures. No brief-token
   figure — the last one was measured at ~600 cards and is stale at 2,479.
 - **The eval harness is not in this repo.** It lives in the private KLYPIX desktop repository. The
   numbers above are ours to defend, not yours to reproduce from here — treat them accordingly.

package/bin/klypix-doctor.mjs

@@ -2,8 +2,8 @@
 // klypix-doctor — `npx klypix-mcp doctor`. The brain's self-check: is THIS machine's
 // brain current, are the Claude capture and Codex presence adapters wired, what verbs
 // does it expose, which lifecycle sessions are live, and is the harness projection in
-// sync? ONE fact, ONE reconcile block. Read-only (never writes). Exits 0 = ALIGNED,
-// 1 = DRIFTED — so it
+// sync? ONE fact, ONE reconcile block. Read-only (never writes). Exits 0 = ALIGNED
+// or PARTIAL (readiness warnings, no drift), 1 = DRIFTED — so it
 // doubles as a pre-commit / CI readiness gate.
 //
 //   npx klypix-mcp doctor              # this project + this machine's brain
@@ -63,9 +63,14 @@ try {
   }
 
   const drifted = report.verdict === 'DRIFTED' || extraDrift > 0;
+  // PARTIAL used to end with "✓ aligned." under a head that said PARTIAL
+  // (2026-10-03) — the closing line is what people read. Exit code unchanged.
+  const warnings = Array.isArray(report.readinessWarnings) ? report.readinessWarnings.length : 0;
   console.log(drifted ? (color ? '\x1b[33m' : '') + `\n✗ drift found — see reconcile above.` + (color ? '\x1b[0m' : '')
     : report.verdict === 'NOT-INSTALLED' ? '\n• brain not installed on this machine.'
-      : (color ? '\x1b[32m' : '') + '\n✓ aligned.' + (color ? '\x1b[0m' : ''));
+      : report.verdict === 'PARTIAL'
+        ? (color ? '\x1b[33m' : '') + `\n• partial — ${warnings} readiness warning${warnings === 1 ? '' : 's'} above (no drift)` + (color ? '\x1b[0m' : '')
+        : (color ? '\x1b[32m' : '') + '\n✓ aligned.' + (color ? '\x1b[0m' : ''));
   process.exit(drifted ? 1 : 0);
 } catch (e) {
   console.error(`✗ doctor failed: ${e?.message || e}`);

package/bin/klypix-install.mjs

@@ -212,6 +212,33 @@ function renameSyncWithBackoff(from, to) {
     }
 }
 
+// The live install as its own `.mcp-runtime.json` describes it, every listed
+// file read and hashed now: { raw, entries: [[name, bytes]] }; { absent: true }
+// with no manifest (an install from before the supervisor); { error } when a
+// listed file is missing or differs — a half-applied install, two versions'
+// files side by side. Only the flat layout (bare file names) is accepted.
+function readVerifiedLiveRuntime(dir) {
+    const manifestPath = path.join(dir, '.mcp-runtime.json');
+    let raw;
+    try { raw = fs.readFileSync(manifestPath, 'utf8'); }
+    catch (e) { return e?.code === 'ENOENT' ? { absent: true } : { error: `manifest unreadable (${e?.code || e?.message})` }; }
+    let manifest;
+    try { manifest = JSON.parse(raw); } catch { return { error: 'manifest is not valid JSON' }; }
+    const files = manifest && typeof manifest.files === 'object' && !Array.isArray(manifest.files) ? manifest.files : null;
+    if (manifest?.protocol !== 1 || !files || !Object.prototype.hasOwnProperty.call(files, String(manifest.worker || ''))) {
+        return { error: 'manifest does not hash its worker' };
+    }
+    const entries = [];
+    for (const [name, expected] of Object.entries(files)) {
+        if (path.basename(name) !== name) return { error: `unexpected path ${name}` };
+        let bytes;
+        try { bytes = fs.readFileSync(path.join(dir, name)); } catch { return { error: `${name} is missing` }; }
+        if (crypto.createHash('sha256').update(bytes).digest('hex') !== expected) return { error: `${name} differs from its hash` };
+        entries.push([name, bytes]);
+    }
+    return { raw, entries };
+}
+
 function migrateProjectMcpConfig() {
     try {
         const file = path.join(process.cwd(), '.mcp.json');
@@ -416,10 +443,37 @@ try {
         const s = path.join(BIN, src); if (exists(s)) staged.push({ dst, content: flatten(fs.readFileSync(s, 'utf8')) });
     }
     for (const st of staged) fs.writeFileSync(path.join(BRAIN_DIR, st.dst + '.klypix-new'), st.content);
+    // .prev is what a supervisor boots while an install is half-applied (a
+    // fresh connection, a wake, a crash recovery), so it must be ONE version,
+    // whole (K1-PREV-UNVERIFIED, 2026-10-03 review). It used to be refreshed from
+    // whatever the live directory held: a retry after an install that stopped
+    // mid-rename (the updater's own, 15 min later) copied the MIXED set over the
+    // last complete snapshot. Now the live files are snapshotted only when they
+    // verify against their own manifest — the very bytes that were hashed are
+    // written — and that manifest is copied in LAST: it is what the supervisor
+    // verifies before it boots .prev (prevSnapshotAt). A live directory that
+    // fails its manifest leaves the last complete snapshot where it is.
     try {
-        const prevDir = path.join(BRAIN_DIR, '.prev'); fs.mkdirSync(prevDir, { recursive: true });
-        for (const st of staged) { const live = path.join(BRAIN_DIR, st.dst); if (exists(live)) fs.copyFileSync(live, path.join(prevDir, st.dst)); }
-    } catch { /* .prev rollback snapshot is best-effort */ }
+        const prevDir = path.join(BRAIN_DIR, '.prev');
+        const prevManifest = path.join(prevDir, '.mcp-runtime.json');
+        const live = readVerifiedLiveRuntime(BRAIN_DIR);
+        if (live.entries) {
+            fs.mkdirSync(prevDir, { recursive: true });
+            fs.rmSync(prevManifest, { force: true });   // nothing vouches for .prev while it changes
+            for (const [name, bytes] of live.entries) fs.writeFileSync(path.join(prevDir, name), bytes);
+            fs.writeFileSync(prevManifest + '.klypix-new', live.raw);
+            renameSyncWithBackoff(prevManifest + '.klypix-new', prevManifest);
+        } else if (live.absent) {
+            // No manifest to verify against (an install from before the
+            // supervisor): a plain copy for a manual rollback, which no
+            // supervisor boots — nothing vouches for it.
+            fs.mkdirSync(prevDir, { recursive: true });
+            fs.rmSync(prevManifest, { force: true });
+            for (const st of staged) { const file = path.join(BRAIN_DIR, st.dst); if (exists(file)) fs.copyFileSync(file, path.join(prevDir, st.dst)); }
+        } else {
+            console.log(`• .prev kept: the live core files do not match their manifest (${live.error}) — the last complete snapshot stays the rollback copy`);
+        }
+    } catch { /* .prev rollback snapshot is best-effort; an unfinished one has no manifest */ }
     const renameOrder = staged.slice().sort((a, b) => (a.dst === 'global-brain-hook.mjs' ? 1 : 0) - (b.dst === 'global-brain-hook.mjs' ? 1 : 0));
     let n = 0;
     for (const st of renameOrder) { renameSyncWithBackoff(path.join(BRAIN_DIR, st.dst + '.klypix-new'), path.join(BRAIN_DIR, st.dst)); n++; }

package/bin/klypix-worker.mjs

@@ -32,14 +32,18 @@ import {
 } 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';
-import { createMcpPresence, KLYPIX_MCP_INSTRUCTIONS } from '../src/mcp-presence.mjs';
-import { consumeMessageReceipt, findProjectBrain } from '../src/agent-presence.mjs';
+import { createMcpPresence, KLYPIX_MCP_INSTRUCTIONS, normalizeMcpClient } from '../src/mcp-presence.mjs';
+import { consumeMessageReceipt, findProjectBrain, listActiveSessions } from '../src/agent-presence.mjs';
 import { collectRepoState, commitsInRange, makeContainmentProbe } from '../src/repo-state.mjs';
 import {
   reconcileRegisteredProjects,
   registerProjectBrain,
   spawnAutoUpdateHelper,
 } from '../src/mcp-auto-update.mjs';
+// Namespace import for constants added after 1.89.0 (AUTO_UPDATE_POLL_MS): a
+// worker that meets an older mcp-auto-update.mjs mid-install must degrade to a
+// fallback, not fail to link over a missing named export.
+import * as autoUpdateModule from '../src/mcp-auto-update.mjs';
 // Namespace import (already in-process via the klypix-core chain, so zero added
 // load cost) so a bundle whose klypix-format predates classifyDecay degrades
 // gracefully — a named import of a missing export would kill the whole server.
@@ -1130,7 +1134,7 @@ server.registerTool('brain_sync', {
 
 server.registerTool('brain_doctor', {
   title: 'Brain doctor — is this brain current, wired, and in sync?',
-  description: 'Read-only self-check of the installed klypix brain, as ONE verdict: VERSION (deployed brain-core + optional npm currency), CLAUDE (existing 5-hook capture readiness), CODEX (automatic MCP presence plus optional enhanced-hook status), TOOLS (discoverable MCP verbs), SESSIONS (all active presence-adapter sessions across hosts, never recent-chat history), and HARNESS (projection drift). Use to answer "is my brain current, correctly installed, in sync, and who is actually live?" without file-spelunking. Never writes: the only side effects are read-only subprocess queries (git rev-parse / tag --list / log / merge-base with fixed argument arrays, and `npm view` only when check_npm is true) — it creates, edits, and deletes nothing. SCOPE: only CLAUDE and CODEX get behavioural verdicts. HARNESS classifies the projected config/rules FILES on disk — a project can read fully ok while no other host has ever actually loaded them, so do not report a clean HARNESS as "Cursor/Cline/Windsurf/Copilot is working". The MCP-callable twin of `npx klypix-mcp doctor`.',
+  description: 'Read-only self-check of the installed klypix brain, as ONE verdict: VERSION (deployed brain-core + optional npm currency), CLAUDE (existing 5-hook capture readiness), CODEX (automatic MCP presence plus optional enhanced-hook status), TOOLS (discoverable MCP verbs), SESSIONS (all active presence-adapter sessions across hosts, never recent-chat history), and HARNESS (projection drift). Use to answer "is my brain current, correctly installed, in sync, and who is actually live?" without file-spelunking. Never writes: the only side effects are read-only subprocess queries (git rev-parse / tag --list / log / merge-base with fixed argument arrays, and `npm view` only when check_npm is true) — it creates, edits, and deletes nothing. SCOPE: only CLAUDE and CODEX get behavioural verdicts. HARNESS classifies the projected config/rules FILES on disk — a project can read fully ok while no other host has ever actually loaded them, so do not report a clean HARNESS as "Cursor/Cline/Windsurf/Copilot is working". The MCP-callable twin of `npx klypix-mcp doctor`. Besides the text, the result carries structuredContent {verdict, layers, version, autoUpdate, supervisors, readinessWarnings, actions}: the same verdict as data, including when the next automatic update check runs and what it will do.',
   inputSchema: {
     project: z.string().optional().describe('Project dir to audit harness + peers for. Defaults to the server\'s working directory.'),
     check_npm: z.boolean().optional().describe('Also fetch npm latest to flag a stale brain (default false — this one does a network `npm view`).'),
@@ -1139,7 +1143,7 @@ server.registerTool('brain_doctor', {
   try {
     // Lazy import so a flat runtime missing brain-doctor.mjs can't crash server STARTUP —
     // the tool degrades gracefully (errors only when called) instead of taking the server down.
-    const { inspect, render } = await import('../src/brain-doctor.mjs');
+    const { inspect, render, structuredReport } = await import('../src/brain-doctor.mjs');
     let npmLatest = null;
     if (check_npm) {
       try { const { execSync } = await import('child_process'); npmLatest = execSync('npm view klypix-mcp version', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 8000 }).trim(); }
@@ -1153,7 +1157,17 @@ server.registerTool('brain_doctor', {
       npmLatest,
       self: { pid: process.pid, version: PKG_VERSION, id: mcpPresence.id },
     });
-    return { content: [{ type: 'text', text: render(report, { color: false }) }] };
+    // E1 (2026-10-03): the same verdict as data next to the unchanged text — the
+    // layers, the auto-update schedule and each connection's state, without
+    // parsing rendered lines. A brain-doctor.mjs that predates the projection
+    // (an install that stopped half-way) leaves it out; the text still answers.
+    let structuredContent = null;
+    try { if (typeof structuredReport === 'function') structuredContent = structuredReport(report); }
+    catch { structuredContent = null; }
+    return {
+      content: [{ type: 'text', text: render(report, { color: false }) }],
+      ...(structuredContent ? { structuredContent } : {}),
+    };
   } catch (e) {
     return { content: [{ type: 'text', text: `brain_doctor unavailable: ${e?.message || e}` }], isError: true };
   }
@@ -1269,6 +1283,44 @@ if (!canvasViewAsApp) {
   }, canvasViewHandler);
 }
 
+// ── Supervisor hibernation probe (2026-10-03) ────────────────────────────────
+// Before it retires an idle worker, the supervisor asks which lane row this
+// connection owns, so it can keep that row fresh while the worker sleeps. It
+// used to ask with an internal brain_sync checkpoint, which the lane records as
+// McpTaskCheckpoint — WORK — so every hibernation made an idle connection look
+// busy (6 idle Codex connections on the founder's PC read as active sessions
+// with no declared scope). This internal request is not a tool: hosts never see
+// it, and it reads the binding and the lane row without writing anything.
+// Supervisors from before it never send it; a worker from before it answers
+// "Method not found", and the supervisor falls back to the checkpoint.
+const SUPERVISOR_IDENTITY_METHOD = 'klypix/presenceIdentity';
+server.server.setRequestHandler(z.object({
+  method: z.literal(SUPERVISOR_IDENTITY_METHOD),
+  params: z.unknown().optional(),
+}), () => {
+  const brainPath = mcpPresence.brainPath;
+  if (!brainPath) return { schemaVersion: 1, reason: 'no-project-brain', brain: null, self: null };
+  const id = String(mcpPresence.id || '');
+  let row = null;
+  try { row = listActiveSessions({ brainPath }).find((session) => session.id === id) || null; }
+  catch { /* unreadable lane: the binding alone still names the row */ }
+  // No row (pruned, or a lane write that never landed): describe the client the
+  // way the worker's own heartbeat would, so the supervisor's upsert recreates
+  // an accurate row instead of an 'unknown' one.
+  let clientName = '';
+  try { clientName = String(server.server.getClientVersion?.()?.name || ''); } catch { /* optional */ }
+  return {
+    schemaVersion: 1,
+    brain: brainPath,
+    self: id ? {
+      id,
+      client: row?.client || normalizeMcpClient(clientName),
+      surface: row?.surface ?? (clientName.replace(/\s+/g, ' ').trim() || 'mcp'),
+      branch: row?.branch ?? null,
+    } : null,
+  };
+});
+
 const transport = new StdioServerTransport();
 let runningHeartbeat = null;
 let autoUpdateStarter = null;
@@ -1318,7 +1370,7 @@ server.server.oninitialized = () => {
   });
   autoUpdateStarter = setTimeout(checkForCoreUpdate, 2000);
   autoUpdateStarter.unref?.();
-  autoUpdatePoller = setInterval(checkForCoreUpdate, 60 * 60 * 1000);
+  autoUpdatePoller = setInterval(checkForCoreUpdate, Math.max(60_000, Number(autoUpdateModule.AUTO_UPDATE_POLL_MS) || 60 * 60 * 1000));
   autoUpdatePoller.unref?.();
   log(`ready · vault=${VAULT} · presence=mcp`);
 };

package/package.json

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

@@ -373,21 +373,51 @@ export function looksMachineTurn(text) {
 // lines) can never parse a torn lane as an authoritative "0 peers / no
 // messages", and a crash mid-write can never destroy undelivered messages.
 // On Windows, renaming over a destination a reader/AV momentarily holds open
-// throws EPERM — one immediate retry wins that race, and on final failure the
-// tmp is REMOVED before rethrowing (the field found dozens of orphaned
-// `.tmp-<pid>-<rand>` files littering the sessions dir, 2026-08-07).
+// throws EPERM/EACCES/EBUSY. ONE immediate retry used to be the whole answer,
+// and it stopped being enough once many sessions shared a lane: 16 lost races
+// in six hours at 15–23 live sessions (2026-10-02), and a lost race is not
+// cosmetic — the throw left an MCP tool call failed outright (a brain_note)
+// and a hook heartbeat or delivery dropped. The rename now backs off like the
+// brain's own atomic write does; worst case ~185 ms, inside the caller's lane
+// lock (peers' lock budget is 500–600 ms, so one slow writer delays them, it
+// does not starve them). On final failure the tmp is REMOVED before
+// rethrowing (the field found dozens of orphaned `.tmp-<pid>-<rand>` files
+// littering the sessions dir, 2026-08-07).
+// PARITY: global-brain-hook.mjs renameRetry — same codes, same backoff.
+const RENAME_RETRY_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
+export const LANE_RENAME_BACKOFF_MS = Object.freeze([10, 25, 50, 100]);
+// Returns the number of attempts it took. `rename` and `sleep` are injectable
+// for tests; the defaults are read at CALL time so a patched fs is honoured.
+export function renameWithRetry(from, to, { rename = fs.renameSync, sleep = sleepSync, backoffMs = LANE_RENAME_BACKOFF_MS } = {}) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      rename(from, to);
+      return attempt + 1;
+    } catch (error) {
+      if (!RENAME_RETRY_CODES.has(error?.code) || attempt >= backoffMs.length) throw error;
+      sleep(backoffMs[attempt]);
+    }
+  }
+}
+
 function writeLaneFileAtomic(laneFile, payload) {
   const tmp = `${laneFile}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
   fs.writeFileSync(tmp, payload);
   try {
-    fs.renameSync(tmp, laneFile);
+    renameWithRetry(tmp, laneFile);
   } catch (err) {
-    try { fs.renameSync(tmp, laneFile); }
-    catch { try { fs.unlinkSync(tmp); } catch { /* best-effort */ } throw err; }
+    try { fs.unlinkSync(tmp); } catch { /* best-effort */ }
+    throw err;
   }
   sweepStaleTmpFiles(path.dirname(laneFile));
 }
 
+// A lane write that still fails after the backoff is reported, never thrown
+// out of a heartbeat or a send: the caller gets a verdict it can show ("the
+// note was not posted, retry") instead of an exception that fails a whole tool
+// call for a reason unrelated to what the tool was asked to do.
+const writeFailureReason = (error) => `write-failed:${String(error?.code || error?.message || 'unknown').slice(0, 80)}`;
+
 // Opportunistic janitor for tmp orphans left by crashes or the pre-fix rename
 // path. Throttled to once per process per 10 minutes; only files matching our
 // own tmp naming and older than 15 minutes are touched, so an in-flight write
@@ -1097,14 +1127,20 @@ export function upsertSession({
     };
     const kept = sessions.filter((session) => session.id !== id);
     kept.push(next);
-    fs.mkdirSync(path.dirname(laneFile), { recursive: true });
-    writeLaneFileAtomic(laneFile, JSON.stringify({
-      ...data,
-      sessions: kept.slice(-40),
-      messages: maintainMessages(data.messages, now),
-      endedSessions,
-      directory: rememberSession(data.directory, next, now),
-    }));
+    try {
+      fs.mkdirSync(path.dirname(laneFile), { recursive: true });
+      writeLaneFileAtomic(laneFile, JSON.stringify({
+        ...data,
+        sessions: kept.slice(-40),
+        messages: maintainMessages(data.messages, now),
+        endedSessions,
+        directory: rememberSession(data.directory, next, now),
+      }));
+    } catch (error) {
+      // The heartbeat did not land: return the lane as it IS (without this
+      // touch) and say so, exactly like the lock-timeout path above.
+      return withWriteVerdict(sessions.sort((a, b) => Number(b.lastSeen || 0) - Number(a.lastSeen || 0)), false, writeFailureReason(error));
+    }
     return withWriteVerdict(kept.sort((a, b) => Number(b.lastSeen || 0) - Number(a.lastSeen || 0)), true);
   } finally {
     if (gotLock) releaseLock(lockFile);
@@ -2694,12 +2730,19 @@ export function postPresenceMessage({
       ...(offline ? { offline } : {}),
     };
     messages.push(message);
-    fs.mkdirSync(path.dirname(laneFile), { recursive: true });
-    writeLaneFileAtomic(laneFile, JSON.stringify({
-      ...data,
-      sessions,
-      messages: capMessages(messages, MESSAGE_LANE_CAP, now),
-    }));
+    try {
+      fs.mkdirSync(path.dirname(laneFile), { recursive: true });
+      writeLaneFileAtomic(laneFile, JSON.stringify({
+        ...data,
+        sessions,
+        messages: capMessages(messages, MESSAGE_LANE_CAP, now),
+      }));
+    } catch (error) {
+      // Nothing was written, so nothing was posted: tell the sender to retry
+      // rather than throwing — a thrown lane error reads to a model as "the
+      // tool is broken" and sends it back to asking the human to relay.
+      return { posted: false, message: null, reason: writeFailureReason(error) };
+    }
     // Who will actually see this, and in what state — the sender's reply to the
     // human is built from this, so it must say "idle 14m" or "not running",
     // never just "queued".