klypix-mcp 1.97.0 → 1.98.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
 
@@ -757,6 +767,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
@@ -1105,9 +1124,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-worker.mjs

@@ -1066,7 +1066,7 @@ server.registerTool('brain_reopen', {
 
 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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.97.0",
+  "version": "1.98.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/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/global-brain-hook.mjs

@@ -1462,6 +1462,22 @@ function peerFooter(sid) {
     const lines = ['', `## ⚠️ Other live session(s) in this project — ${peers.length} total, as of ${asOf}${hiddenIdle ? ` (+${hiddenIdle} inactive not shown)` : ''} — coordinate (the brain is shared, NOT live-merged)`];
     const releaseLine = releaseLeaseFooterLine(list, now);
     if (releaseLine) lines.push(releaseLine);
+    // Same branch, said ONCE (1.98.0). Two sessions can only share a branch
+    // name by sharing a checkout (git refuses one branch in two worktrees), so
+    // the risk is concrete: a broad `git add` sweeps the other session's edits
+    // into your commit. Per-peer, this line repeated on every row of a busy
+    // lane and stopped being read.
+    const sameBranchCount = myBranch ? peers.filter(p => p.branch === myBranch).length : 0;
+    if (sameBranchCount) lines.push(`- ⚠️ ${sameBranchCount} of these session(s) share your branch \`${myBranch}\` (one checkout): stage only your own files — never \`git add -u\` / \`-A\` — and coordinate before you commit.`);
+    // Same folder, no shared file yet (twin of mcp-presence findNearbyWork, no
+    // git): with 3+ scoped sessions, a folder most of them touch is noise.
+    const dirOf = (k) => { const at = k.lastIndexOf('/'); return at > 0 ? k.slice(0, at) : ''; };
+    const dirsOfScope = (s) => new Set(scopeOf(s).map(fileKey).map(dirOf).filter(Boolean));
+    const myDirs = dirsOfScope(me);
+    const scopedRows = [me, ...peers].filter(s => s && scopeOf(s).length);
+    const dirCount = new Map();
+    for (const s of scopedRows) for (const d of dirsOfScope(s)) dirCount.set(d, (dirCount.get(d) || 0) + 1);
+    const dirIsNoise = (d) => { const n = dirCount.get(d) || 0; return n >= 3 && n > scopedRows.length / 2; };
     for (const p of peers.slice(0, 4)) {
         const bits = [];
         if (p.branch) bits.push(`branch \`${p.branch}\``);
@@ -1496,10 +1512,12 @@ function peerFooter(sid) {
             warn = `  · ⚠️ both edited: ${marked.join(', ')} — expect a conflict, KEEP BOTH${legend}`;
         }
         // State the fact, never the git operation. This runs in a latency-sensitive
-        // hook and must not spawn git, so it cannot know whether the branch is merely
-        // behind or has DIVERGED — and on a diverged branch "pull/rebase" is advice
-        // the real state contradicts. Naming the collision is what this footer is for.
-        else if (p.branch && myBranch && p.branch === myBranch) warn = '  · ⚠️ same branch — your commits will interleave; coordinate before you commit';
+        // hook and must not spawn git. The same-branch fact is stated once above
+        // the list; per peer, only a shared folder is added (advisory).
+        else {
+            const near = [...dirsOfScope(p)].filter(d => myDirs.has(d) && !dirIsNoise(d)).sort().slice(0, 2);
+            if (near.length) warn = `  · 📁 same folder: ${near.map(d => `${d}/`).join(', ')} — no shared file yet`;
+        }
         // Unique over the full live list (not just shown peers) — the MSG router
         // resolves a prefix against every row, so uniqueness must match that set.
         lines.push(`- session ${shortestUniquePeerPrefix(list, p.id)} · ${bits.join(' · ')}${warn}`);

package/src/klypix-core.mjs

@@ -34,7 +34,7 @@ import {
   challengeBrain, challengeContextToMarkdown, buildRenderSpec, structToBrief,
   brainLensData, lensToMarkdown, deathDateOfCard,
   statusContextToMarkdown, findFulfillmentCandidates, findStaleOpenCards, releaseFulfilledOpens, openStatusSummary, perAreaTableToMarkdown,
-  splitQueryTokens, scoreCardsAgainstQuery, correctionOverlaysFor, currentGuidanceFor, currentGuidancePrefix,
+  splitQueryTokens, scoreCardsAgainstQuery, correctionOverlaysFor, supersededByNote, currentGuidanceFor, currentGuidancePrefix,
   isFastDecayCard, isUnresolvedOpenCard, isSkillCard, validateGuard, guardSidecarPathFor, ensureGuardSidecar, DECAY_STALE_MS, formatDecayAge,
   isPlanCard, planFulfillmentFor, PLAN_PAIR_SIM_BRAIN, isAgconfTwinId,
   readPendingShips, clearPendingShips, pendingShipCards, formatCaptureReceipts, parseVerifySuffix, amendmentFirst,
@@ -435,6 +435,9 @@ export async function opSearchCanvases({ vault, query }) {
       const isArchived = (c) => /^archive$/i.test(c.area || '');
       const n = struct.counts;
       const head = `## ${rel} — "${struct.title}" · ${n.live ?? n.cards} live cards${n.archived ? `, ${n.archived} archived` : ''}, ${n.connections} connections${saved ? ` · saved ${saved}` : ''}${nameMatch && !matched.length ? '  (name/title match)' : ''}`;
+      // A stale hit names its replacement (1.98.0) — never a bare "archived".
+      let successors = new Map();
+      try { successors = correctionOverlaysFor(struct, matched.slice(0, 8)); } catch { successors = new Map(); }
       const body = matched.slice(0, 8).map(c => {
         const pos = (c.pos && c.pos.x != null) ? ` @(${Math.round(c.pos.x)},${Math.round(c.pos.y)})` : '';
         const allTags = [...new Set([...(c.tags || []), ...itemTags(c)])];
@@ -449,7 +452,10 @@ export async function opSearchCanvases({ vault, query }) {
         const fromReading = reading && !hit(c.title) && !hit(c.text) && hit(reading.text)
           ? `\n    in KLYPIX's saved reading: ${escapeInstructionLines(reading.text.replace(/\s+/g, ' ').slice(0, 240))}`
           : '';
-        return `- [${c.type}] "${c.title || '(card)'}" (${c.id})${pos}${date ? ` · ${date}` : ''}${tags}${arch}\n    ${escapeInstructionLines(ownText)}${fromReading}`;
+        const replaced = successors.has(c.id)
+          ? `\n    ↪ ${supersededByNote(successors.get(c.id))} — read that card for the current state`
+          : '';
+        return `- [${c.type}] "${c.title || '(card)'}" (${c.id})${pos}${date ? ` · ${date}` : ''}${tags}${arch}\n    ${escapeInstructionLines(ownText)}${fromReading}${replaced}`;
       }).join('\n');
       hits.push(matched.length ? `${head}\n${body}` : head);
     }
@@ -504,6 +510,12 @@ export async function opSearchAllBrains({ vault, query, as_of, log = () => {} })
     try { ({ struct } = await parseKlypix(fs.readFileSync(b.path))); } catch { continue; }
     let vecs = null;
     if (qv) { try { const r = await questionVectors(pipe, b.path, struct.cards); vecs = r.usable ? r.vecs : null; } catch { /* lexical for this brain */ } }
+    // Replacement per stale card (1.98.0), only when this brain HAS lifecycle
+    // edges; skipped under as_of (a correction is a present-day fact).
+    let successors = new Map();
+    if (asOfTs == null && (struct.connections || []).some(cn => cn.label === 'superseded by' || cn.label === 'closed by')) {
+      try { successors = correctionOverlaysFor(struct, struct.cards); } catch { successors = new Map(); }
+    }
     for (const c of struct.cards) {
       if (c.type === 'container') continue;
       const t = String(c.text || '').toLowerCase();
@@ -529,7 +541,7 @@ export async function opSearchAllBrains({ vault, query, as_of, log = () => {} })
         if (isArchived) score -= 1;
         if (isCur) score += sem != null ? 1.5 : 1; // current-project locality prior
       }
-      scored.push({ score, sem, cur: isCur, project: b.project || path.basename(path.dirname(b.path)), area: c.area, c });
+      scored.push({ score, sem, cur: isCur, project: b.project || path.basename(path.dirname(b.path)), area: c.area, c, successor: successors.get(c.id) || null });
     }
   }
   if (!scored.length) return { blocks: [text(`No matches for "${query}" across ${brains.length} registered brain(s).`)] };
@@ -537,7 +549,7 @@ export async function opSearchAllBrains({ vault, query, as_of, log = () => {} })
   const top = scored.slice(0, 20);
   const lines = top.map(h => {
     const when = h.c.createdAt ? new Date(h.c.createdAt).toISOString().slice(0, 10) : '';
-    return `- ${h.cur ? '★ ' : ''}[${h.project}${h.area ? ' › ' + h.area : ''}] ${when} ${String(h.c.text || '').replace(/\s+/g, ' ').slice(0, 240)}`;
+    return `- ${h.cur ? '★ ' : ''}[${h.project}${h.area ? ' › ' + h.area : ''}] ${when} ${String(h.c.text || '').replace(/\s+/g, ' ').slice(0, 240)}${h.successor ? `\n    ↪ ${supersededByNote(h.successor)}` : ''}`;
   });
   // Never say "warming — retry" to someone who simply has not installed the
   // runtime: for them that advice is wrong forever, and their results are the

package/src/klypix-format.mjs

@@ -4405,17 +4405,63 @@ export function questionContextToMarkdown(question, result, { mode = 'lexical',
     }
     const out = [];
     out.push(`# Answer “${flat(question)}” from these ${hits.length} brain card(s)${as_of ? ` (as of ${as_of})` : ''} — ${total} matched, ${mode} ranking`);
-    out.push('_Synthesize a DIRECT answer from the cards below, then cite the ones you used by [Area]+date. Where a card is marked ⚠️ CORRECTED, answer from the correction, NOT the stale card. Include superseded/archived cards only to show how a decision CHANGED. If the cards don\'t actually answer the question, say so — don\'t pad._');
+    out.push('_Synthesize a DIRECT answer from the cards below, then cite the ones you used by [Area]+date. Where a card is marked ⚠️ CORRECTED, the CURRENT truth is printed FIRST — answer from it; the ↩︎ line under it is superseded history, never the answer. Include superseded/archived cards only to show how a decision CHANGED. If the cards don\'t actually answer the question, say so — don\'t pad._');
     out.push('');
     let used = out.join('\n').length;
     let shown = 0;
+    // CURRENT-FIRST corrections (1.98.0). Agents followed a withdrawn rule in
+    // 77% of tries unless its replacement was made prominent (arXiv 2608.25553),
+    // and a stale card can outrank its own replacement (corpseRate). So a
+    // corrected hit prints the current truth BEFORE the stale words, and when
+    // the replacement ranked too, the pair renders ONCE, at the better rank —
+    // never a stale block above a separate current block.
+    const hitById = new Map(hits.map(h => [h.card.id, h]));
+    const replaces = new Map();   // current id → the stale hit it supersedes
     for (const h of hits) {
-        const c = h.card;
+        const succ = h.correction?.by?.id;
+        if (succ && hitById.has(succ) && !replaces.has(succ)) replaces.set(succ, h);
+    }
+    const rendered = new Set();
+    const relOf = (h) => (h && h.sem != null ? ` · sim ${h.sem.toFixed(2)}` : '');
+    for (const h of hits) {
+        if (rendered.has(h.card.id)) continue;
+        let c = h.card;
+        let block;
+        // Pair: either this is the current card of a stale hit, or a stale hit
+        // whose current card is also in this answer — render the pair here.
+        const staleHit = replaces.get(c.id) || (h.correction && hitById.has(h.correction.by.id) ? h : null);
+        if (staleHit) {
+            const currentHit = hitById.get(staleHit.correction.by.id);
+            const cur = currentHit.card;
+            const old = staleHit.card;
+            rendered.add(cur.id); rendered.add(old.id);
+            c = cur;
+            block = `## [${flat(cur.area) || 'Notes'}] ${day(cur.createdAt)} · ✅ CURRENT (supersedes an older card)${relOf(currentHit)}\n`
+                + `⚠️ CORRECTED — the current truth is:\n${flat(cur.text)}\n\n`
+                + `  ↩︎ superseded [${flat(old.area) || 'Notes'}] ${day(old.createdAt)} (do NOT act on it — history only): ${flat(old.text).slice(0, 240)}`;
+            if (typeof evidenceForCard === 'function') {
+                const evidence = evidenceForCard(cur);
+                if (evidence) block += `\n\n${evidence}`;
+            }
+            if (used + block.length + 2 > budgetChars && shown > 0) { out.push(`\n_…and ${hits.filter(x => !rendered.has(x.card.id)).length + 2} more matched card(s) omitted for length — narrow the question or use search for the rest._`); break; }
+            out.push(block, '');
+            used += block.length + 2;
+            shown++;
+            continue;
+        }
+        rendered.add(c.id);
         const status = h.archived ? ' · ⛔ archived/superseded' : '';
-        const rel = h.sem != null ? ` · sim ${h.sem.toFixed(2)}` : '';
-        let block = `## [${flat(c.area) || 'Notes'}] ${day(c.createdAt)}${status}${rel}\n${flat(c.text)}`;
+        const rel = relOf(h);
+        if (h.correction) {
+            // The replacement is NOT in this answer: still print it first.
+            block = `## [${flat(c.area) || 'Notes'}] ${day(c.createdAt)}${status}${rel}\n`
+                + `⚠️ CORRECTED — this card is STALE; the current truth is:\n${flat(h.correction.by.text).slice(0, 600)}\n\n`
+                + `  ↩︎ stale text (do NOT act on it — history only): ${flat(c.text).slice(0, 240)}`;
+        } else {
+            block = `## [${flat(c.area) || 'Notes'}] ${day(c.createdAt)}${status}${rel}\n${flat(c.text)}`;
+        }
         if (h.correction) {
-            block += `\n\n  ⚠️ CORRECTED — this card is STALE; the current truth is:\n  ${flat(h.correction.by.text).slice(0, 600)}`;
+            // (rendered above — current truth first)
         } else if (h.fulfillment && (h.fulfillment.kind === 'plan' || isPlanCard(c))) {
             // A PLAN/PROPOSAL card a newer 🏁 appears to have shipped (2026-08-23
             // incident: "it's only a proposal" answered about a live feature).
@@ -4446,7 +4492,7 @@ export function questionContextToMarkdown(question, result, { mode = 'lexical',
                 if (correctionEvidence) block += `\n\nCorrection ${correctionEvidence}`;
             }
         }
-        if (used + block.length + 2 > budgetChars && shown > 0) { out.push(`\n_…and ${hits.length - shown} more matched card(s) omitted for length — narrow the question or use search for the rest._`); break; }
+        if (used + block.length + 2 > budgetChars && shown > 0) { out.push(`\n_…and ${hits.filter(x => !rendered.has(x.card.id)).length + 1} more matched card(s) omitted for length — narrow the question or use search for the rest._`); break; }
         out.push(block, '');
         used += block.length + 2;
         shown++;
@@ -4665,7 +4711,7 @@ export function statusContextToMarkdown(struct, { maxOpen = Infinity, budgetChar
         let shown = 0;
         for (const c of top) {
             if (used > budgetChars) break;
-            const flags = `${overdueById.has(c.id) ? ' ⏰OVERDUE' : ''}${overlays.has(c.id) ? ' ⚠️CORRECTED' : ''}${fulfills.has(c.id) ? (fulfills.get(c.id)?.unconfirmed ? ' ⏳likely-fulfilled?' : ' ⏳likely-fulfilled') : ''}`;
+            const flags = `${overdueById.has(c.id) ? ' ⏰OVERDUE' : ''}${overlays.has(c.id) ? ` ⚠️CORRECTED → current: “${cut(flat(overlays.get(c.id).by.text), 80)}”` : ''}${fulfills.has(c.id) ? (fulfills.get(c.id)?.unconfirmed ? ' ⏳likely-fulfilled?' : ' ⏳likely-fulfilled') : ''}`;
             const d = decayStamp(c);
             if (d) pushAlways(`- [${flat(c.area) || 'Notes'}]${flags} ⏱️ LAST KNOWN (${d.age}): ${cut(flat(c.text), perCard)} — VERIFY: ${d.probe}`);
             else pushAlways(`- [${flat(c.area) || 'Notes'}]${flags} ${cut(flat(c.text), perCard)}`);
@@ -5810,6 +5856,16 @@ const reAdoptionReceipt = (prior, today) => {
     return `↪ re-adopts ${today}: ${headline || 'an earlier superseded decision'}`;
 };
 
+// One wording for "this card was replaced, read that one" on every surface that
+// lists cards (status, read_canvas, search_canvases, search_all_brains), so a
+// stale card is never shown without naming its replacement (1.98.0).
+export function supersededByNote(overlay, max = 100) {
+    if (!overlay || !overlay.by) return '';
+    const head = String(overlay.by.text || '').replace(/\s+/g, ' ').trim();
+    const cutHead = head.length > max ? `${head.slice(0, max - 1)}…` : head;
+    return `superseded by “${cutHead}” (${overlay.by.id})`;
+}
+
 // Recall-side truth guard: label a card stale ONLY when the graph contains an
 // explicit identity-bearing lifecycle edge ("superseded by" / "closed by").
 // Lexical correction matching remains useful at capture/reconcile time, where
@@ -9675,8 +9731,13 @@ export function structToMarkdown(struct, { assetsDir, parsed = null, lockedBoxes
         if (strokes || lines) L.push(`*Ink: ${strokes} freehand stroke${strokes === 1 ? '' : 's'} · ${lines} drawn line${lines === 1 ? '' : 's'}/shape${lines === 1 ? '' : 's'}${frozenInk ? ` · ${frozenInk} frozen` : ''} (not readable as text)*\n`);
     }
     L.push(`## Cards`);
+    // The replacement rides in the stale card's own heading (1.98.0) — before,
+    // the edge appeared only in the separate connection list at the end.
+    let successors = new Map();
+    try { successors = correctionOverlaysFor(struct, struct.cards.filter(c => c.type !== 'container')); } catch { successors = new Map(); }
     for (const c of struct.cards) {
         const archived = isArchived(c);
+        const replacedNote = successors.has(c.id) ? ` — ${supersededByNote(successors.get(c.id), 90)}` : '';
         const it = items[c.id] || {};
         // Human-set state rides in the heading, where a reader cannot miss it.
         const state = [
@@ -9685,7 +9746,7 @@ export function structToMarkdown(struct, { assetsDir, parsed = null, lockedBoxes
             c.type === 'container' && c.containerKind === 'block' ? 'a frameless block' : null,
             c.type === 'container' && c.collapsed ? 'collapsed by the person (its cards are still listed)' : null,
         ].filter(Boolean);
-        L.push(`### ${c.title || `(${c.type})`}  \`${c.type}\` · id ${c.id}${archived ? '  ⛔ archived' : ''}${c.area && !archived ? `  _[${c.area}]_` : ''}${state.length ? `  · ${state.join(' · ')}` : ''}`);
+        L.push(`### ${c.title || `(${c.type})`}  \`${c.type}\` · id ${c.id}${archived ? `  ⛔ archived${replacedNote}` : (replacedNote ? `  ⚠️${replacedNote}` : '')}${c.area && !archived ? `  _[${c.area}]_` : ''}${state.length ? `  · ${state.join(' · ')}` : ''}`);
         if (c.text) L.push(escapeInstructionLines(c.type === 'text' ? String(c.text).trim() : `→ ${c.text}`));
         if (rich) {
             const extra = [];

package/src/mcp-presence.mjs

@@ -46,7 +46,7 @@ import {
 // canonical copy lives in the pure module because that one is import-restricted
 // (crypto only), so it can never grow a dependency this file would inherit.
 import { normalizeFileKey } from './finding-routing.mjs';
-import { cmpSemver3, collectRepoState, commitFiles, deleteCommittedClaim, readCommittedClaims, releaseAncestry, releaseAncestryWarnings, repoStateWarnings, settleClaimsAgainstRef, writeCommittedClaim } from './repo-state.mjs';
+import { cmpSemver3, collectRepoState, commitFiles, mergeTreeConflicts, deleteCommittedClaim, readCommittedClaims, releaseAncestry, releaseAncestryWarnings, repoStateWarnings, settleClaimsAgainstRef, writeCommittedClaim } from './repo-state.mjs';
 import { recordResultManifests } from './result-reconcile.mjs';
 
 export const MCP_HEARTBEAT_MS = 60_000;
@@ -82,6 +82,19 @@ export const KLYPIX_MCP_INSTRUCTIONS = [
 
 const compact = (value) => String(value || '').replace(/\s+/g, ' ').trim();
 
+// A `results` value is EVIDENCE-SHAPED when it is an array (the manifest list,
+// even an empty or malformed one) or an object carrying any field a result
+// manifest has. Only evidence-shaped submissions enter the fail-closed result
+// contract. Prose or a summary object claims nothing machine-checkable: it is
+// refused, but it must not lock the task — an AI tool that mistook `results`
+// for "describe what you did" (Codex did, 2026-10-11) finishes with a plain
+// retry instead of staying active to every peer.
+const MANIFEST_FIELDS = ['schemaVersion', 'claimKey', 'metrics', 'provenance', 'evaluation', 'inputFingerprint', 'scopeFingerprint'];
+export function isEvidenceShapedResults(value) {
+  if (Array.isArray(value)) return true;
+  return !!value && typeof value === 'object' && MANIFEST_FIELDS.some((key) => Object.prototype.hasOwnProperty.call(value, key));
+}
+
 const EXACT_FILE_MAX_CHARS = 512;
 const EXACT_FILE_MAX_COUNT = 20;
 const GLOB_FILE_CHARS = new Set(['*', '?', '[', ']', '{', '}']);
@@ -798,6 +811,151 @@ const isTaskSession = (session) =>
     // rest of the host process's life.
     || liveObservedFiles(session).length > 0);
 
+// ── Overlap tiers beyond the exact file (1.98.0) ────────────────────────────
+// Exact-file overlap (findPresenceConflicts) stays the blocking signal and its
+// shape is unchanged. Two further tiers, each with its own honesty limit:
+//
+//   same-directory (advisory) — both sessions work in one folder with no file
+//     in common yet. Most real collisions start as "I'm in the folder you're
+//     in". Noise control borrowed from release ownership: with three or more
+//     scoped sessions, a folder that more than half of them touch (docs/,
+//     src/) says nothing about any one pair and is dropped. Never alerts.
+//   merge-conflict (blocking) — the two sessions' BRANCHES, test-merged with
+//     git merge-tree, conflict in named files although no declared file
+//     overlaps. Committed work only; skipped silently whenever git cannot say.
+
+const dirOfKey = (key) => {
+  const at = String(key || '').lastIndexOf('/');
+  return at > 0 ? key.slice(0, at) : '';   // '' = repo root: never a "folder" signal
+};
+
+const scopeDisplayByKey = (session, root) => {
+  const out = new Map();
+  for (const file of [
+    ...(Array.isArray(session?.files) ? session.files : []),
+    ...liveObservedFiles(session),
+  ]) {
+    const key = normalizeFileKey(file, root);
+    if (key && !out.has(key)) out.set(key, String(file || '').replace(/\\/g, '/'));
+  }
+  return out;
+};
+
+export function findNearbyWork(sessions, selfId, { projectRoot, excludePeerIds = new Set(), maxDirs = 3, maxFiles = 4 } = {}) {
+  const active = Array.isArray(sessions) ? sessions : [];
+  const me = active.find((session) => session.id === selfId);
+  if (!me) return [];
+  const root = projectRoot || me.cwd || null;
+  const mine = scopeDisplayByKey(me, root);
+  if (!mine.size) return [];
+  const scoped = active.filter((s) => s && (s.id === selfId || (!isSuspectedTwin(s, me) && isTaskSession(s))));
+  const dirsOf = (byKey) => {
+    const map = new Map();   // dir → [display files]
+    for (const [key, display] of byKey) {
+      const dir = dirOfKey(key);
+      if (!dir) continue;
+      if (!map.has(dir)) map.set(dir, []);
+      map.get(dir).push(display);
+    }
+    return map;
+  };
+  const myDirs = dirsOf(mine);
+  if (!myDirs.size) return [];
+  // Shared-folder noise: count sessions touching each folder.
+  const dirSessions = new Map();
+  const scopes = new Map();
+  for (const s of scoped) {
+    const byKey = s.id === selfId ? mine : scopeDisplayByKey(s, root);
+    scopes.set(s.id, byKey);
+    for (const dir of dirsOf(byKey).keys()) dirSessions.set(dir, (dirSessions.get(dir) || 0) + 1);
+  }
+  const scopedCount = [...scopes.values()].filter((m) => m.size).length;
+  // Noise needs a CROWD: at least three sessions in the folder AND more than
+  // half of all scoped sessions. Two sessions sharing a folder is exactly the
+  // pair signal this tier exists for, however small the lane.
+  const isNoise = (dir) => {
+    const n = dirSessions.get(dir) || 0;
+    return n >= 3 && n > scopedCount / 2;
+  };
+  const out = [];
+  for (const peer of scoped) {
+    if (peer.id === selfId || excludePeerIds.has(peer.id)) continue;
+    const theirsByKey = scopes.get(peer.id);
+    if (!theirsByKey || !theirsByKey.size) continue;
+    if ([...theirsByKey.keys()].some((key) => mine.has(key))) continue;   // exact overlap is the stronger report
+    const theirDirs = dirsOf(theirsByKey);
+    const shared = [...theirDirs.keys()].filter((dir) => myDirs.has(dir) && !isNoise(dir)).sort();
+    if (!shared.length) continue;
+    const dirs = shared.slice(0, maxDirs);
+    out.push({
+      id: peer.id,
+      client: peer.client,
+      surface: peer.surface || null,
+      branch: peer.branch || null,
+      intent: peer.intent || '',
+      dirs,
+      mine: dirs.flatMap((d) => myDirs.get(d)).slice(0, maxFiles),
+      theirs: dirs.flatMap((d) => theirDirs.get(d)).slice(0, maxFiles),
+      kind: 'same-directory',
+      severity: 'advisory',
+    });
+  }
+  return out;
+}
+
+export function findMergeConflicts(sessions, selfId, {
+  repoDir,
+  maxPeers = 6,
+  budgetMs = 2000,
+  clock = () => Date.now(),
+  mergeTree = mergeTreeConflicts,
+} = {}) {
+  const active = Array.isArray(sessions) ? sessions : [];
+  const me = active.find((session) => session.id === selfId);
+  if (!me || !repoDir || !compact(me.branch)) return [];
+  const candidates = active
+    .filter((peer) => peer && peer.id !== selfId
+      && !isSuspectedTwin(peer, me)
+      && isTaskSession(peer)
+      && compact(peer.branch) && peer.branch !== me.branch
+      // A teammate's PC: its branch refs are not in this repo (the lookup
+      // would simply fail), so do not spend the budget on it.
+      && !(peer.machine && me.machine && peer.machine !== me.machine))
+    .sort((a, b) => Number(b.lastSeen || 0) - Number(a.lastSeen || 0))
+    .slice(0, maxPeers);
+  const started = clock();
+  const byBranch = new Map();
+  const out = [];
+  for (const peer of candidates) {
+    if (clock() - started > budgetMs) break;
+    let result = byBranch.get(peer.branch);
+    if (result === undefined) {
+      try { result = mergeTree(repoDir, me.branch, peer.branch); } catch { result = null; }
+      byBranch.set(peer.branch, result);
+    }
+    if (!result || result.clean || !Array.isArray(result.files) || !result.files.length) continue;
+    out.push({
+      id: peer.id,
+      client: peer.client,
+      surface: peer.surface || null,
+      branch: peer.branch || null,
+      intent: peer.intent || '',
+      files: result.files.slice(0, 12),
+      kind: 'merge-conflict',
+      severity: 'blocking',
+      sameWorktree: false,
+      peerObservedFiles: [],
+      selfObservedFiles: [],
+      refs: {
+        mine: `${me.branch}@${String(result.shaA || '').slice(0, 7)}`,
+        theirs: `${peer.branch}@${String(result.shaB || '').slice(0, 7)}`,
+      },
+      committedOnly: true,
+    });
+  }
+  return out;
+}
+
 const publicSession = (session, now) => {
   const transport = session?.transport && typeof session.transport === 'object'
     ? Object.fromEntries(Object.entries(session.transport).slice(0, 4).map(([channel, value]) => [
@@ -2411,6 +2569,7 @@ export function createMcpPresence({
     }
     if (nextPhase === 'checkpoint') checkpointSinceTaskStart = true;
     const hasDefinedResults = results !== undefined;
+    const resultsAreEvidenceShaped = hasDefinedResults && isEvidenceShapedResults(results);
     let resultReconciliation = null;
     let completionBlocked = false;
     let resultSubmissionRejected = false;
@@ -2437,7 +2596,31 @@ export function createMcpPresence({
       }
     }
 
-    if (hasDefinedResults) {
+    if (hasDefinedResults && !resultsAreEvidenceShaped) {
+      // Refused for THIS call (scope retained), with no durable evidence
+      // obligation: nothing machine-checkable was claimed, so a retry without
+      // `results` is the ordinary completion it always was. A prior
+      // evidence-shaped claim still holds — the next result-less complete reads
+      // it in the branch below and stays blocked.
+      resultSubmissionRejected = true;
+      resultReconciliation = {
+        ok: false,
+        status: 'needs-reconciliation',
+        ledgerWriteOk: null,
+        claims: [],
+        conflicts: [{
+          kind: 'results-not-manifests',
+          severity: 'blocking',
+          reason: '`results` takes only result manifests (machine-checkable claims, a list of 1-8), never a summary of the work. Nothing was recorded and this task owes no evidence: to finish, call brain_sync with phase "complete" again WITHOUT results.',
+        }],
+      };
+      if (completing) {
+        completionBlocked = true;
+        // A tool that writes up its outcome is ending the task, not a turn: the
+        // plain retry must not then be deferred as a premature turn-end.
+        checkpointSinceTaskStart = true;
+      }
+    } else if (hasDefinedResults) {
       resultClaimsPending = true;
       const marked = markResultClaimPendingFn({
         brainPath: resultBrainPath,
@@ -2660,16 +2843,28 @@ export function createMcpPresence({
     }
 
     const stamp = now();
-    const conflicts = findPresenceConflicts(report.sessions, sessionId);
+    const exactConflicts = findPresenceConflicts(report.sessions, sessionId);
+    // 1.98.0 tiers (see findNearbyWork / findMergeConflicts). Both are skipped
+    // on completion — a finished task has nothing left to collide with.
+    const mergeConflicts = completing ? [] : findMergeConflicts(report.sessions, sessionId, { repoDir: path.dirname(brainPath) });
+    const nearby = completing ? [] : findNearbyWork(report.sessions, sessionId, {
+      excludePeerIds: new Set([...exactConflicts, ...mergeConflicts].map((c) => c.id)),
+    });
+    // `conflicts` keeps its contract (blocking overlaps, exact-file shape) and
+    // gains the merge-conflict kind additively.
+    const conflicts = [...exactConflicts, ...mergeConflicts];
     const snapshot = buildPresenceSnapshot(report.sessions, sessionId, { now: stamp });
     const alertsQueued = [];
+    const selfLabel = shortestUniqueSessionPrefix(report.sessions, sessionId, 12) || String(sessionId).slice(0, 12);
+    const planLabel = compact(intent) ? ` plans "${compact(intent).slice(0, 110)}"` : ' synchronized a task';
     if (!completing) {
       for (const peer of conflicts) {
         // Explicit arrow: normalizeFileKey now takes an optional `root` second
         // argument, so a bare `.map(normalizeFileKey)` would hand it the array
         // INDEX as the project root.
         const filesKey = peer.files.map((file) => normalizeFileKey(file)).sort().join('|');
-        const key = `${peer.id}|${filesKey}`;
+        const isMerge = peer.kind === 'merge-conflict';
+        const key = `${isMerge ? 'merge|' : ''}${peer.id}|${filesKey}`;
         if (notifiedConflicts.has(key)) continue;
         notifiedConflicts.add(key);
         const annotated = annotateConflictFiles(peer);
@@ -2677,29 +2872,47 @@ export function createMcpPresence({
           brainPath,
           from: sessionId,
           to: peer.id,
-          text: `Automatic KLYPIX overlap alert: ${shortestUniqueSessionPrefix(report.sessions, sessionId, 12) || String(sessionId).slice(0, 12)}`
-            + `${compact(intent) ? ` plans "${compact(intent).slice(0, 110)}"` : ' synchronized a task'}`
-            + ` and reports the same file(s): ${annotated.files.join(', ')}${annotated.legend}. Coordinate before editing.`,
-          dedupeKey: `overlap|${sessionId}|${peer.id}|${taskStartedAt}|${filesKey}`,
+          text: isMerge
+            ? `Automatic KLYPIX merge-conflict alert: ${selfLabel}${planLabel}. A test merge of its branch ${peer.refs?.mine || ''} with yours ${peer.refs?.theirs || ''} conflicts in: ${peer.files.join(', ')} (committed work only; no declared file overlaps). Coordinate before either of you merges.`
+            : `Automatic KLYPIX overlap alert: ${selfLabel}${planLabel}`
+              + ` and reports the same file(s): ${annotated.files.join(', ')}${annotated.legend}. Coordinate before editing.`,
+          dedupeKey: `${isMerge ? 'merge-overlap' : 'overlap'}|${sessionId}|${peer.id}|${taskStartedAt}|${filesKey}`,
           home,
           now: stamp,
         });
-        if (queued.posted) alertsQueued.push({ peerId: peer.id, files: peer.files });
+        if (queued.posted) alertsQueued.push({ peerId: peer.id, files: peer.files, ...(isMerge ? { kind: 'merge-conflict' } : {}) });
       }
     }
 
-    const conflictText = conflicts.length
-      ? [
-        'KLYPIX exact file-overlap warning:',
-        ...conflicts.map((peer) => {
-          const annotated = annotateConflictFiles(peer);
-          return `- ${shortestUniqueSessionPrefix(report.sessions, peer.id, 12) || String(peer.id).slice(0, 12)}${peer.intent ? ` "${String(peer.intent).slice(0, 80)}"` : ''}: ${annotated.files.join(', ')}${annotated.legend}`;
-        }),
-        alertsQueued.length
-          ? 'The earlier peer was automatically queued an exact-once overlap alert; coordinate ownership before editing.'
-          : 'Coordinate ownership before editing the overlapping files.',
-      ].join('\n')
-      : 'No exact file overlap is currently reported by another synchronized task.';
+    const peerLabel = (peer) => `${shortestUniqueSessionPrefix(report.sessions, peer.id, 12) || String(peer.id).slice(0, 12)}${peer.intent ? ` "${String(peer.intent).slice(0, 80)}"` : ''}`;
+    const exactAlerted = alertsQueued.some((a) => a.kind !== 'merge-conflict');
+    const conflictText = [
+      exactConflicts.length
+        ? [
+          'KLYPIX exact file-overlap warning:',
+          ...exactConflicts.map((peer) => {
+            const annotated = annotateConflictFiles(peer);
+            return `- ${peerLabel(peer)}: ${annotated.files.join(', ')}${annotated.legend}`;
+          }),
+          exactAlerted
+            ? 'The earlier peer was automatically queued an exact-once overlap alert; coordinate ownership before editing.'
+            : 'Coordinate ownership before editing the overlapping files.',
+        ].join('\n')
+        : 'No exact file overlap is currently reported by another synchronized task.',
+      mergeConflicts.length
+        ? [
+          'KLYPIX merge-conflict warning (git merge-tree, committed work only — your branches would conflict even though no declared file overlaps):',
+          ...mergeConflicts.map((peer) => `- ${peerLabel(peer)} on ${peer.refs.theirs} vs your ${peer.refs.mine}: ${peer.files.join(', ')}`),
+          'Agree who merges first, or rebase onto the other branch before you finish.',
+        ].join('\n')
+        : '',
+      nearby.length
+        ? [
+          'KLYPIX nearby-work notice (advisory — same folder, no shared file yet):',
+          ...nearby.map((peer) => `- ${peerLabel(peer)}: ${peer.dirs.map((d) => `${d}/`).join(', ')} — theirs: ${peer.theirs.join(', ')}; yours: ${peer.mine.join(', ')}`),
+        ].join('\n')
+        : '',
+    ].filter(Boolean).join('\n\n');
     // Mechanical repo-state (2026-08-14 bundle-currency incident): branch, tag
     // and version truth plus bundled-mirror drift, collected IN THE SERVER so
     // every MCP client — Claude, Codex, Cursor, Cline, Desktop — gets equal
@@ -3352,6 +3565,8 @@ export function createMcpPresence({
       },
       peers: snapshot.peers,
       conflicts,
+      // Additive (1.98.0): same-folder work with no shared file (advisory).
+      ...(nearby.length ? { nearby } : {}),
       messages: report.messages.map((message) => {
         // Raw structured path gets the same decay verdict as the rendered
         // text: a consumer reading structured.messages directly must see the
@@ -3433,7 +3648,7 @@ export function createMcpPresence({
       ? `KLYPIX message delivery was deferred safely: ${report.deliveryWriteSkippedReason || 'the receipt write did not land'}. No queued note was reported as delivered; retry on the next KLYPIX action.`
       : '';
     const deferralText = completionDeferred
-      ? 'KLYPIX completion deferred: this complete carried no results and arrived moments after task start with no intervening checkpoint, so it reads as turn-end, not task-end. The declared intent/files were RETAINED for peers. When the task is truly finished, complete again after a checkpoint (or include a result manifest) to clear the scope.'
+      ? 'KLYPIX completion deferred: this complete carried no results and arrived moments after task start with no intervening checkpoint, so it reads as turn-end, not task-end. The declared intent/files were RETAINED for peers. When the task is truly finished, call brain_sync with phase "checkpoint", then "complete" again, to clear the scope. (Do not add `results` for this: it takes only machine-checkable result manifests, never a summary.)'
       : '';
     const text = [
       `KLYPIX Context Gateway: session ${sessionId} · phase ${nextPhase} · coordination ${durationMs}ms.`,
@@ -3459,6 +3674,7 @@ export function createMcpPresence({
       ...report,
       snapshot,
       conflicts,
+      nearby,
       resultConflicts,
       alertsQueued,
       structured,

package/src/mcp-verify.mjs

@@ -72,6 +72,13 @@ export function readLaunchSpec(file) {
   };
 }
 
+// How long setup waits for the first handshake. On a busy machine a first run
+// can spend most of it starting Node and loading the server (the release
+// suite's live handshake took 29-92 s under load on 2026-10-11, about 7 s
+// idle), and a false "did not start a server" sends a person hunting for a
+// fault that is not there. Setup runs once, so waiting longer costs little.
+export const VERIFY_TIMEOUT_MS = 60_000;
+
 /**
  * Launch the server exactly as the editor would and count the tools it offers.
  *
@@ -82,7 +89,7 @@ export function readLaunchSpec(file) {
  * @param {{ file: string, projectDir: string, timeoutMs?: number, env?: object }} opts
  * @returns {Promise<{ ok: boolean, toolCount?: number, ms?: number, why?: string, hasBrainSync?: boolean }>}
  */
-export async function verifyMcpConfig({ file, projectDir, timeoutMs = 25_000, env = process.env }) {
+export async function verifyMcpConfig({ file, projectDir, timeoutMs = VERIFY_TIMEOUT_MS, env = process.env }) {
   const spec = readLaunchSpec(file);
   if (!spec.ok) return { ok: false, why: spec.why };
 
@@ -108,7 +115,7 @@ export async function verifyMcpConfig({ file, projectDir, timeoutMs = 25_000, en
       client.connect(transport).then(() => 'ok'),
       new Promise((r) => setTimeout(() => r('timeout'), timeoutMs)),
     ]);
-    if (connected === 'timeout') return { ok: false, why: `no response within ${Math.round(timeoutMs / 1000)}s` };
+    if (connected === 'timeout') return { ok: false, why: `no response within ${Math.round(timeoutMs / 1000)}s (a busy machine or a first download can be this slow; \`npx klypix-mcp doctor\` checks again)` };
 
     const listed = await Promise.race([
       client.listTools().then((t) => t),

package/src/repo-state.mjs

@@ -29,7 +29,7 @@
 import crypto from 'crypto';
 import fs from 'fs';
 import path from 'path';
-import { execFileSync } from 'child_process';
+import { execFileSync, spawnSync } from 'child_process';
 
 // Same shape as the presence-side gitBranch / resolveAuthor probes: short
 // timeout, stderr discarded, failure is data (null), never an exception.
@@ -65,6 +65,101 @@ const makeGit = (execGit) => (cwd, args, timeoutMs) => {
   }
 };
 
+// ── Test-merge two sessions' branches (git merge-tree) ───────────────────────
+// Declared-file overlap misses the conflicts that matter most at merge time:
+// on 715 pairs of concurrently open agent PRs, 79 of 167 textual conflicts
+// (47%) happened although the two PRs' own file lists did not overlap — each
+// side was compared against a different base (arXiv 2610.04779). A real
+// three-way test merge of the two branch tips catches them, and costs a median
+// 0.02 s (git >= 2.38, `merge-tree --write-tree`, no working tree touched).
+//
+// Contract: committed work only (an uncommitted edit is invisible to git), never
+// throws, null whenever the answer is unknown — git too old (exit 129), unrelated
+// histories (128), a branch that does not exist in THIS repo (a teammate's PC),
+// a timeout, or a ref name that is not safe to hand to git.
+
+// Files the brain tooling regenerates on every branch, so they differ between
+// almost any two branches and a "conflict" in them is projection noise, not
+// work at risk. brain.klypix has its own merge driver. The rest mirror
+// uninstall.mjs PROJECT_TARGETS (test/overlap-tiers.mjs fails if they drift).
+export const MERGE_NOISE_PATHS = Object.freeze([
+  'brain.klypix', 'brain.any',
+  'agents.md', '.agents/agents.md', 'gemini.md', 'conventions.md',
+  '.cursor/rules/klypix-brain.mdc', '.windsurf/rules/klypix-brain.md', '.clinerules/klypix-brain.md',
+  '.github/copilot-instructions.md', '.codex/config.toml',
+  '.mcp.json', '.cursor/mcp.json', '.cline/mcp.json', '.gemini/settings.json', '.vscode/mcp.json',
+]);
+const MERGE_NOISE = new Set(MERGE_NOISE_PATHS);
+export const isMergeNoise = (file) => {
+  const key = String(file || '').replace(/\\/g, '/').replace(/^\.\//, '').trim().toLowerCase();
+  if (!key) return true;
+  const base = key.slice(key.lastIndexOf('/') + 1);
+  return MERGE_NOISE.has(key) || base === 'brain.klypix' || base === 'brain.any';
+};
+
+// A branch name we will put on a git command line: no leading dash (option
+// injection), no "..", no reflog/revision syntax, no whitespace.
+const SAFE_BRANCH = /^(?!-)(?!.*\.\.)(?!.*@\{)[A-Za-z0-9._/+-]{1,200}$/;
+export const isSafeBranchName = (name) => typeof name === 'string' && SAFE_BRANCH.test(name) && !name.endsWith('/') && !name.endsWith('.lock');
+
+function defaultRunMergeTree(args, cwd, timeoutMs) {
+  const r = spawnSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: Number(timeoutMs) > 0 ? Number(timeoutMs) : GIT_TIMEOUT_MS,
+    windowsHide: true,
+  });
+  return { status: r.error ? null : r.status, stdout: typeof r.stdout === 'string' ? r.stdout : '' };
+}
+
+const mergeTreeCache = new Map();   // `${dir}|${shaA}|${shaB}` → result (tips are immutable)
+const MERGE_TREE_CACHE_MAX = 200;
+
+/**
+ * Test-merge the tips of two local branches without touching any working tree.
+ * Returns { clean, files, shaA, shaB, noiseOnly } or null when unknown.
+ * `files` are the conflicted paths minus MERGE_NOISE_PATHS.
+ */
+export function mergeTreeConflicts(dir, branchA, branchB, {
+  execGit = defaultExecGit,
+  runMergeTree = defaultRunMergeTree,
+  timeoutMs = 1500,
+} = {}) {
+  if (!dir || !isSafeBranchName(branchA) || !isSafeBranchName(branchB) || branchA === branchB) return null;
+  const git = makeGit(execGit);
+  const shaA = git(dir, ['rev-parse', '--verify', '--quiet', `refs/heads/${branchA}^{commit}`]);
+  const shaB = git(dir, ['rev-parse', '--verify', '--quiet', `refs/heads/${branchB}^{commit}`]);
+  if (!shaA || !shaB || !/^[0-9a-f]{7,64}$/i.test(shaA) || !/^[0-9a-f]{7,64}$/i.test(shaB)) return null;
+  if (shaA === shaB) return { clean: true, files: [], shaA, shaB, noiseOnly: false };
+  const key = `${dir}|${shaA}|${shaB}`;
+  if (mergeTreeCache.has(key)) return mergeTreeCache.get(key);
+  let res = null;
+  try { res = runMergeTree(['merge-tree', '--write-tree', '--name-only', '--no-messages', shaA, shaB], dir, timeoutMs); } catch { res = null; }
+  let out = null;
+  if (res && res.status === 0) out = { clean: true, files: [], shaA, shaB, noiseOnly: false };
+  else if (res && res.status === 1) {
+    // Line 1 is the merged tree's OID; the conflicted file names follow, one
+    // per line, until a blank line (informational messages are suppressed).
+    const lines = String(res.stdout || '').split(/\r?\n/);
+    const all = [];
+    for (let i = 1; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (!line) break;
+      all.push(line);
+    }
+    const files = [...new Set(all)].filter((f) => !isMergeNoise(f));
+    out = { clean: files.length === 0, files, shaA, shaB, noiseOnly: all.length > 0 && files.length === 0 };
+  }
+  if (out) {
+    if (mergeTreeCache.size >= MERGE_TREE_CACHE_MAX) mergeTreeCache.delete(mergeTreeCache.keys().next().value);
+    mergeTreeCache.set(key, out);
+  }
+  return out;
+}
+
+export function __resetMergeTreeCacheForTests() { mergeTreeCache.clear(); }
+
 function readPackage(dir) {
   try {
     const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));

package/src/setup.mjs

@@ -19,7 +19,7 @@ import { fileURLToPath } from 'url';
 import { execFile } from 'child_process';
 import { detectEditors } from './editor-detect.mjs';
 import { linkProject } from './agent-rules.mjs';
-import { verifyMcpConfig, readLaunchSpec } from './mcp-verify.mjs';
+import { verifyMcpConfig, readLaunchSpec, VERIFY_TIMEOUT_MS } from './mcp-verify.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLI = path.join(__dirname, '..', 'bin', 'klypix-mcp.mjs');
@@ -228,7 +228,7 @@ export async function runSetup(opts = {}) {
       const res = await verifyMcpConfig({
         file: path.join(root, target.file),
         projectDir: root,
-        timeoutMs: opts.timeoutMs || 25_000,
+        timeoutMs: opts.timeoutMs || VERIFY_TIMEOUT_MS,
       });
       results.push({ tool: target.tool, file: target.file, ...res });
       if (!res.ok) report.warnings.push(`${target.file} did not start a server: ${res.why}`);