klypix-mcp 1.19.0 → 1.20.0

package/bin/klypix-mcp.mjs

@@ -138,22 +138,24 @@ server.registerTool('brain_insights', {
 
 server.registerTool('brain_connect', {
   title: 'Connect related-but-unlinked brain cards (densify the graph)',
-  description: 'Finds genuinely related cards that AREN\'T linked yet and proposes connections — semantic similarity when the on-device model is installed, else shared tags + [[mentions]]. Dry-run by default (review the suggestions); pass apply:true to draw them (ADDITIVE — never deletes; the human can remove any arrow). Use after brain_insights flags many orphans, to turn a flat list into a real knowledge graph.',
+  description: 'Finds genuinely related cards that AREN\'T linked yet and proposes connections — semantic similarity when the on-device model is installed, else shared tags + [[mentions]]. Dry-run by default (review the suggestions); pass apply:true to draw them (ADDITIVE — never deletes; the human can remove any arrow). Use after brain_insights flags many orphans, to turn a flat list into a real knowledge graph. To DISMISS a brain_reconcile false-positive contradiction, pass pairs:[{fromId,toId}] (the ids are in the reconcile output) with relationship:"not_contradiction" — a persisted dismissal that stops that pair ever resurfacing as a candidate.',
   inputSchema: {
     canvas: z.string().optional().describe('Canvas filename/path. Defaults to the project brain ("brain").'),
     apply: z.boolean().optional().describe('false (default) = suggest only; true = draw the connections.'),
     max: z.number().optional().describe('Max connections to propose/draw (default 24).'),
     threshold: z.number().optional().describe('Min semantic similarity 0–1 to link (default 0.45). Higher = fewer, tighter links.'),
+    pairs: z.array(z.object({ fromId: z.string(), toId: z.string() })).optional().describe('Explicit card-id pairs to connect (bypasses auto-proposal). Use to dismiss a reconcile false-positive: pass the two card ids with relationship:"not_contradiction".'),
+    relationship: z.string().optional().describe('Relationship for explicit `pairs` (e.g. "not_contradiction" to permanently dismiss a contradiction candidate, or "relates_to", "depends_on", "supports").'),
   },
-}, async ({ canvas, apply, max, threshold }) => toContent(await opBrainConnect({ vault: VAULT, canvas, apply, max, threshold, log })));
+}, async ({ canvas, apply, max, threshold, pairs, relationship }) => toContent(await opBrainConnect({ vault: VAULT, canvas, apply, max, threshold, pairs, relationship, log })));
 
 server.registerTool('brain_reconcile', {
   title: 'Reconcile the brain — contradictions between cards + unrecorded migrations',
-  description: 'Truth maintenance in two passes. (1) CONTRADICTIONS: finds same-subject live card pairs where one carries an explicit correction cue (uppercase "CORRECTION", "was WRONG", "OBSOLETE" — that side is the presumed truth) or the two use opposite polarity words (deferred↔wired, broken↔fixed, dead↔live), i.e. stale facts whose correction never got linked — candidates only, YOU confirm each: retire the stale card via brain_note ✓; a false POLARITY pair is dismissed by deliberately connecting the pair (brain_connect), while a correction-cue pair clears only when the stale card is retired. (2) MIGRATIONS: lists committed migration files (Supabase / Rails / Prisma / Knex / generic) that NO brain card references, so an applied-but-unnarrated rollout can be recorded. Reads ONLY the filesystem — never the database, never the network — and changes nothing. Run it periodically, or when recall surfaces something you believe is stale.',
+  description: 'Truth maintenance. (1) CONTRADICTIONS: finds same-subject live card pairs where one carries an explicit correction cue (uppercase "CORRECTION", "was WRONG", "OBSOLETE" — that side is the presumed truth) or the two use opposite polarity words (deferred↔wired, broken↔fixed, dead↔live), i.e. stale facts whose correction never got linked — candidates only, YOU confirm each: retire the stale card via brain_note ✓. Dismiss a FALSE positive (either kind) by connecting the two ids with brain_connect pairs + relationship:"not_contradiction" — persisted, so it never resurfaces. (2) MIGRATIONS: lists committed migration files (Supabase / Rails / Prisma / Knex / generic) that NO brain card references, so an applied-but-unnarrated rollout can be recorded. (3) LEGACY: pre-v1.15 raw-bash ship cards to tidy. Reads ONLY the filesystem — never the database, never the network — and changes nothing. Run it periodically, or when recall surfaces something you believe is stale.',
   inputSchema: {
     canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
     root: z.string().optional().describe("Project root holding the migrations dir (default: the brain file's folder)."),
-    mode: z.enum(['all', 'contradictions', 'migrations']).optional().describe('Which pass to run (default "all").'),
+    mode: z.enum(['all', 'contradictions', 'migrations', 'legacy']).optional().describe('Which pass to run (default "all"): contradictions · migrations · legacy (pre-v1.15 raw-bash ship cards to tidy).'),
   },
 }, async ({ canvas, root, mode }) => toContent(await opBrainReconcile({ vault: VAULT, canvas, root, mode })));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "An open, local-first, agent-neutral canvas file your AI reads and writes over MCP — works with Claude, Cursor, Cline, any model.",
   "type": "module",
   "license": "MIT",
@@ -53,7 +53,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs"
+    "test": "node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/src/global-brain-hook.mjs

@@ -307,6 +307,12 @@ function touchSession(sid, patch = {}) {
                 // the per-prompt recall renders a re-hit as one headline instead of
                 // re-paying the full card (a ~600-word card was injected 3× before).
                 injected: patch.injected !== undefined ? patch.injected : (prev.injected ?? []),
+                // Sibling ledger for LARGE cards (>1KB) with a much deeper cap: the
+                // 100-entry `injected` set evicts old ids in a long session, so a big
+                // card injected early could re-inflate full-text after ~100 other
+                // cards scrolled it out. Big cards are rare, so this cap effectively
+                // never evicts one — enforcing "no >1KB card full-text twice".
+                injectedBig: patch.injectedBig !== undefined ? patch.injectedBig : (prev.injectedBig ?? []),
                 startedAt: prev.startedAt || now, lastSeen: now,
             });
             fs.mkdirSync(SESSIONS_DIR, { recursive: true });
@@ -436,9 +442,16 @@ function messageFooter(sid, tp) {
         fs.writeFileSync(SESSIONS_FILE, JSON.stringify(d2));
     } catch { /* */ } finally { if (got) releaseLock(SESSIONS_LOCK); }
     if (!show.length) return '';
+    // De-dupe identical message TEXT within one delivery: the same note can reach
+    // the lane twice (posted via both the 🧠 MSG marker and the brain_message MCP
+    // twin, or re-sent) as two distinct ids — all are already acked above, so
+    // dropping the repeats here shows each note once without ever re-surfacing it.
+    const seenTxt = new Set();
+    const showUniq = show.filter(m => { const k = String(m.text || '').replace(/\s+/g, ' ').trim().toLowerCase(); if (!k || seenTxt.has(k)) return false; seenTxt.add(k); return true; });
+    if (!showUniq.length) return '';
     const ago = (ts) => { const mm = Math.max(0, Math.round((now - (ts || now)) / 60000)); return mm <= 0 ? 'just now' : `${mm}m ago`; };
     const out = ['', '## 📨 Message(s) from another session in this project (delivered once — act on or reply to them)'];
-    for (const m of show.slice(0, 6)) out.push(`- from ${String(m.from || '?').slice(0, 8)} · ${ago(m.ts)}: ${String(m.text).replace(/\s+/g, ' ').trim().slice(0, 400)}`);
+    for (const m of showUniq.slice(0, 6)) out.push(`- from ${String(m.from || '?').slice(0, 8)} · ${ago(m.ts)}: ${String(m.text).replace(/\s+/g, ' ').trim().slice(0, 400)}`);
     out.push('Reply with `🧠 MSG [<their-id or all>]: <text>` — it reaches them on their next prompt.');
     return '\n' + out.join('\n');
 }
@@ -1236,15 +1249,30 @@ async function promptRetrieve(lib) {
         if (struct && typeof lib.correctionOverlaysFor === 'function') {
             try { overlays = lib.correctionOverlaysFor(struct, freshHits.map(h => h.card)); } catch { /* best-effort */ }
         }
-        // Per-session injection dedup: a card already shown full-text this
-        // session renders as one headline, not another ~600 words of context.
+        // Awaits-merge decay: a hit saying "PR #N awaits merge" gets a merged-overlay
+        // when a harvested ship event already recorded #N MERGED (deterministic, no
+        // retirement — the fact is right, only its status decayed).
+        let mergeOv = new Map();
+        if (struct && typeof lib.mergeOverlaysFor === 'function') {
+            try { mergeOv = lib.mergeOverlaysFor(struct, freshHits.map(h => h.card)); } catch { /* best-effort */ }
+        }
+        const mergeTag = (id) => { const m = mergeOv.get(id); return m ? `\n  ↳ ⚠️ PR #${m.num} is since MERGED${m.date ? ` (ship event ${m.date})` : ''} — this "awaits merge" note is stale; nothing to do.` : ''; };
+        // Per-session injection dedup: a card already shown full-text this session
+        // renders as one headline, not another ~600 words of context. LARGE cards
+        // (>1KB) are tracked in a separate, deep-capped ledger so the 100-entry
+        // `injected` set's eviction can never re-inflate one (the observed 3× bug).
+        const BIG_CHARS = 1000;
         let me = null; try { me = readSessions().find(s => s.id === sid) || null; } catch { /* */ }
         const injected = new Set((me && Array.isArray(me.injected)) ? me.injected : []);
+        const injectedBig = new Set((me && Array.isArray(me.injectedBig)) ? me.injectedBig : []);
+        const isBig = (c) => flat(c.text).length > BIG_CHARS;
+        const wasInjected = (c) => injected.has(c.id) || (isBig(c) && injectedBig.has(c.id));
         const shownNow = new Set();
         lines.push(semMode === 'sem-hit'
             ? "# Related prior decisions (semantic match — no exact keyword overlap; full brain via the klypix-canvas MCP)"
             : "# Relevant prior decisions from this project's brain (task-matched; full brain via the klypix-canvas MCP)");
-        const newlyInjected = [];
+        const newlyInjected = [], newlyBig = [];
+        const noteInjected = (c) => { newlyInjected.push(c.id); if (isBig(c)) newlyBig.push(c.id); };
         for (const h of freshHits) {
             if (shownNow.has(h.card.id)) continue;                      // already rendered this turn (e.g. as a corrector)
             const ov = overlays.get(h.card.id);
@@ -1256,11 +1284,11 @@ async function promptRetrieve(lib) {
                 let correctorLine = false;
                 if (!shownNow.has(ov.by.id)) {
                     correctorLine = true;
-                    if (injected.has(ov.by.id)) {
+                    if (wasInjected(ov.by)) {
                         lines.push(`- ⚠️ CORRECTED — current (already shown this session): ${head(ov.by, 110)}`);
                     } else {
                         lines.push(`- ⚠️ CORRECTED — current: ${flat(ov.by.text)}`);
-                        newlyInjected.push(ov.by.id);
+                        noteInjected(ov.by);
                     }
                     shownNow.add(ov.by.id);
                 }
@@ -1268,16 +1296,20 @@ async function promptRetrieve(lib) {
                 shownNow.add(h.card.id);
                 continue;
             }
-            if (injected.has(h.card.id)) {
-                lines.push(`- (already shown this session) ${head(h.card, 110)}`);
+            if (wasInjected(h.card)) {
+                lines.push(`- (already shown this session) ${head(h.card, 110)}${mergeTag(h.card.id)}`);
                 shownNow.add(h.card.id);
                 continue;
             }
-            lines.push(`- ${flat(h.card.text)}`);
+            lines.push(`- ${flat(h.card.text)}${mergeTag(h.card.id)}`);
             shownNow.add(h.card.id);
-            newlyInjected.push(h.card.id);
+            noteInjected(h.card);
+        }
+        if (newlyInjected.length) {
+            const patch = { injected: [...new Set([...injected, ...newlyInjected])].slice(-100) };
+            if (newlyBig.length) patch.injectedBig = [...new Set([...injectedBig, ...newlyBig])].slice(-400);
+            touchSession(sid, patch);
         }
-        if (newlyInjected.length) touchSession(sid, { injected: [...new Set([...injected, ...newlyInjected])].slice(-100) });
     }
     const parts = [];
     if (lines.length) parts.push(lines.join('\n'));

package/src/klypix-core.mjs

@@ -26,7 +26,7 @@ import {
   brainInsights, insightsToMarkdown, addBrainConnections, proposeStructuralConnections, atomicWrite,
   findUnrecordedMigrations, captureIntoBrain, tidyBrain, noteToCaptureInput,
   selectGardenCandidates, applyGarden, detectContradictions,
-  rankForQuestion, questionContextToMarkdown,
+  rankForQuestion, questionContextToMarkdown, findLegacyShipCards,
 } from './klypix-format.mjs';
 
 // ── Card / connection input shape (single source for every face) ─────────────
@@ -462,14 +462,30 @@ export async function opBrainReconcile({ vault, canvas, root, mode = 'all' }) {
       const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim();
       const lines = pairs.map((p, i) =>
         `${i + 1}. ${p.why} · overlap ${p.overlap}\n`
-        + `   · likely STALE   [${p.stale.area || '?'}] ${flat(p.stale.text).slice(0, 180)}\n`
-        + `   · likely CURRENT [${p.fresh.area || '?'}] ${flat(p.fresh.text).slice(0, 180)}`);
-      sections.push(`# ⚔️ ${pairs.length} contradiction candidate(s) — confirm, then reconcile\n_Candidates only — nothing was changed. For each REAL contradiction: retire the stale card with \`brain_note\` marker \`✓\` (text = what it resolved to), or record a correction-cue decision ("CORRECTION: …", uppercase) — capture auto-supersedes it across areas. Dismissing a FALSE positive: a **polarity** pair is dismissed by deliberately connecting the two cards (\`brain_connect\`); a **correction-cue** pair only clears when the stale card is retired (✓ / supersede) — a mere link does not settle a declared correction._\n\n${lines.join('\n')}`);
+        + `   · likely STALE   [${p.stale.area || '?'}] (id ${p.stale.id}) ${flat(p.stale.text).slice(0, 180)}\n`
+        + `   · likely CURRENT [${p.fresh.area || '?'}] (id ${p.fresh.id}) ${flat(p.fresh.text).slice(0, 180)}`);
+      sections.push(`# ⚔️ ${pairs.length} contradiction candidate(s) — confirm, then reconcile\n_Candidates only — nothing was changed. For each REAL contradiction: retire the stale card with \`brain_note\` marker \`✓\` (text = what it resolved to), or record a correction-cue decision ("CORRECTION: …", uppercase) — capture auto-supersedes it across areas. Dismissing a FALSE positive (either kind — polarity OR correction-cue): \`brain_connect\` with \`pairs:[{fromId, toId}]\` and \`relationship:"not_contradiction"\` using the ids above — the dismissal is persisted, so that pair never resurfaces here again._\n\n${lines.join('\n')}`);
     } else if (mode === 'contradictions') {
       sections.push('✓ No contradiction candidates — no live card pair shows a correction cue or a polarity flip over the same subject.');
     }
   }
 
+  // (1b) LEGACY SHIP CARDS — pre-v1.15 auto-captured "merged PR — auto-captured
+  // (`gh …`)" cards with raw shell text / path-scraped junk PR numbers. Already
+  // excluded from repeat-matching (so they no longer cry wolf); this surfaces them
+  // for optional one-time cleanup. Suggestion-only — retire each with a ✓ marker.
+  if (mode === 'all' || mode === 'legacy') {
+    const { cards: legacy, total } = findLegacyShipCards(struct);
+    if (legacy.length) {
+      const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+      const lines = legacy.map(c => `- (id ${c.id}) [${c.area || '?'}] ${flat(c.text).slice(0, 140)}`);
+      const more = total > legacy.length ? `\n\n…and ${total - legacy.length} more.` : '';
+      sections.push(`# 🧹 ${total} legacy raw-bash ship card(s) — optional cleanup\n_Pre-v1.15 auto-capture residue (raw shell command / path-scraped PR numbers). They are ALREADY excluded from repeat-detection, so this is cosmetic hygiene, not a correctness fix. To tidy: retire each with \`brain_note\` marker \`✓\`, or leave them — they no longer trigger false repeat warnings._\n\n${lines.join('\n')}${more}`);
+    } else if (mode === 'legacy') {
+      sections.push('✓ No legacy raw-bash ship cards — every ship card is a clean fact.');
+    }
+  }
+
   // (2) MIGRATIONS — the brain reconciled against committed external state.
   // Migrations live in the CODE repo (usually beside brain.klypix), not in a
   // separate canvas vault — so default the root to the brain file's folder.
@@ -530,7 +546,7 @@ export async function opBrainGarden({ vault, canvas, apply = false, syntheses })
   }
 }
 
-export async function opBrainConnect({ vault, canvas, apply = false, max = 24, threshold = 0.45, log = () => {} }) {
+export async function opBrainConnect({ vault, canvas, apply = false, max = 24, threshold = 0.45, pairs = null, relationship = null, label = null, log = () => {} }) {
   const tgt = brainTarget(vault, canvas);
   if (tgt.ambiguous) return ambiguousBrainErr(tgt.ambiguous);
   if (!tgt.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}.`);
@@ -542,6 +558,28 @@ export async function opBrainConnect({ vault, canvas, apply = false, max = 24, t
   const live = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim() && !/^archive$/i.test(c.area || ''));
   const linked = new Set(struct.connections.map(c => [c.fromId, c.toId].sort().join('|')));
 
+  // ── Explicit-pairs mode ─────────────────────────────────────────────────────
+  // Draw EXACTLY the given card-id pairs with a chosen relationship, bypassing the
+  // auto-proposer. This is the persisted DISMISS path for a reconcile false
+  // positive: pass relationship:"not_contradiction" and detectContradictions will
+  // treat the pair as settled forever (the escape hatch a correction-cue false
+  // positive — which has no stale card to retire — previously lacked).
+  if (Array.isArray(pairs) && pairs.length) {
+    const rel = typeof relationship === 'string' && relationship ? relationship : 'relates_to';
+    const lbl = (typeof label === 'string' && label) ? label : (rel === 'not_contradiction' ? 'not a contradiction' : undefined);
+    const explicit = pairs
+      .filter(p => p && p.fromId && p.toId && byId.has(p.fromId) && byId.has(p.toId) && p.fromId !== p.toId)
+      .map(p => ({ fromId: p.fromId, toId: p.toId, relationship: rel, ...(lbl ? { label: lbl } : {}) }));
+    if (!explicit.length) return err('pairs needs [{fromId, toId}, …] where both ids are real cards in this brain (see the ids in brain_reconcile output).');
+    const render2 = (e) => `- ${flat(byId.get(e.fromId)?.text)} ↔ ${flat(byId.get(e.toId)?.text)}  (${e.relationship}${e.label ? `: ${e.label}` : ''})`;
+    if (!apply) return { blocks: [text(`# ${explicit.length} explicit connection(s) to draw\n_Re-run with apply:true to draw them.${rel === 'not_contradiction' ? ' These pairs will then be permanently dismissed as contradiction candidates.' : ''}_\n\n${explicit.map(render2).join('\n')}`)] };
+    try {
+      const { buffer, added } = await addBrainConnections(fs.readFileSync(file), explicit);
+      await atomicWrite(file, buffer);
+      return { blocks: [text(`✓ Drew ${added} connection(s)${rel === 'not_contradiction' ? ' — these pair(s) are now dismissed and will NOT resurface as brain_reconcile contradiction candidates' : ''}.\n\n${explicit.slice(0, added).map(render2).join('\n')}`)] };
+    } catch (e) { return err(`Apply failed (brain unchanged): ${e.message}`); }
+  }
+
   let edges = [];
   let mode = 'structural (shared tags + [[mentions]])';
   const pipe = await Promise.race([getEmbedder(log), new Promise(r => setTimeout(() => r(null), 20_000))]);

package/src/klypix-format.mjs

@@ -127,7 +127,11 @@ export async function parseKlypix(buffer) {
     return { struct, zip, assetPaths, isV4, canvas, manifest };
 }
 
-const REL = new Set(['leads_to', 'depends_on', 'relates_to', 'conflicts_with', 'supports', 'questions', 'costs', 'blocks']);
+// 'not_contradiction' is a DISMISSAL edge, not a topical relation: an agent draws
+// it between two cards a reconcile pass flagged as a FALSE contradiction, and
+// detectContradictions then treats the pair as settled forever (the persisted
+// dismiss path the correction-cue false-positive previously lacked).
+const REL = new Set(['leads_to', 'depends_on', 'relates_to', 'conflicts_with', 'supports', 'questions', 'costs', 'blocks', 'not_contradiction']);
 
 /**
  * Build a real .klypix v4 file (nodebuffer) from a simple spec:
@@ -827,13 +831,17 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     const out = [];
     const push = (...lines) => { for (const l of lines) { out.push(l); used += l.length + 1; } };
 
+    // Overdue open cards (self-declared deadline passed) — badged inline so a
+    // stale-dated reminder is flagged the next session instead of decaying silently.
+    const overdueById = findOverdueOpenCards(struct).byId;
+    const odBadge = (c) => { const o = overdueById.get(c.id); return o ? `  ·  ⏰ OVERDUE — deadline ${o.date} passed ${o.daysOverdue}d ago; verify or close (✓)` : ''; };
     push(`# ${struct.title} — brain brief`);
     push(`*${struct.format} · ${struct.counts.cards} cards · ${struct.counts.connections} connections · tiered brief (focus + open + last ${recentDays}d headlines); full cards via klypix-canvas MCP search*`);
     if (focus.length) {
         push('', '## 📌 Human focus (cards the human placed here — act on these first)');
-        for (const c of focus) push(`- ${fr(c)}${flat(c.text)}`);
+        for (const c of focus) push(`- ${fr(c)}${flat(c.text)}${odBadge(c)}`);
     }
-    if (open.length) { push('', '## Open questions & goals'); for (const c of open) push(`- ${fr(c)}${flat(c.text)}`); }
+    if (open.length) { push('', '## Open questions & goals'); for (const c of open) push(`- ${fr(c)}${flat(c.text)}${odBadge(c)}`); }
     if (skills.length) {
         push('', '## 🛠️ Skills — how we do things here (reusable; applies every session)');
         for (const c of skills.slice(0, maxSkills)) push(`- ${fr(c)}${flat(c.text)}`);
@@ -942,9 +950,13 @@ export function structToUltraBrief(struct, { freshness = null, briefPath = '.cla
         for (const c of conflicts.slice(0, 4)) { if (!pushIf(`- ${clip(c.from, 70)} ⚔️ ${clip(c.to, 70)}`)) break; shown++; }
         if (shown < conflicts.length) pushIf(`- …and ${conflicts.length - shown} more conflict(s) — in the full brief.`);
     }
-    if (open.length && pushIf('') && pushIf(`## Open questions & goals (${open.length})`)) {
+    // Overdue opens lead (and get a ⏰ prefix) so a passed deadline is never the
+    // line that falls off the bottom of the preview-sized budget.
+    const overdueById = findOverdueOpenCards(struct).byId;
+    const openSorted = open.slice().sort((a, b) => (overdueById.has(b.id) ? 1 : 0) - (overdueById.has(a.id) ? 1 : 0));
+    if (open.length && pushIf('') && pushIf(`## Open questions & goals (${open.length}${overdueById.size ? `, ${overdueById.size} ⏰ overdue` : ''})`)) {
         let shown = 0;
-        for (const c of open) { if (!pushIf(`- ${fr(c)}${head(c)}`)) break; shown++; }
+        for (const c of openSorted) { if (!pushIf(`- ${overdueById.has(c.id) ? '⏰ OVERDUE ' : ''}${fr(c)}${head(c)}`)) break; shown++; }
         if (shown < open.length) pushIf(`- …and ${open.length - shown} more — in the full brief.`);
     }
     const areas = struct.cards.filter(c => c.type === 'container' && !/^archive$/i.test(c.title || ''))
@@ -1193,6 +1205,35 @@ const REPEAT_VERB_STOP = new Set([
 // PR#), or a kebab/snake identifier. A #file-/#dir- tag-stem match counts as an
 // entity at match time regardless of shape (tags are capture-stamped anchors).
 const isEntityToken = (t) => /\d/.test(t) || t.includes('-') || t.includes('_');
+// ── Legacy raw-bash ship cards (pre-v1.15 auto-capture residue) ──────────────
+// Before the v1.15 ship-capture rewrite, auto-harvest dumped the RAW shell command
+// into the card ("🏁 merged PR #850 — auto-captured (`cd /c/Users/…/8db42`)") and
+// scraped stray path digits as PR numbers ("merged PR #238886"). These are dense
+// with generic ship verbs + junk numbers, so the possible-repeat warner kept
+// matching them and crying wolf — training agents to ignore repeat warnings. They
+// are (a) excluded from detectRepeatWork below and (b) surfaced by findLegacyShip-
+// Cards for a one-time cleanup. Detection is SIGNATURE-based (not just "old"), so a
+// CLEAN ship card ("Ship: 🏁 merged PR #286") is never touched.
+export const isLegacyRawShipCard = (text) => {
+    const t = String(text || '');
+    if (!/🏁|\bmerged\b|\brelease|\bpublish|\bshipped\b|\btagged\b/i.test(t)) return false;   // ship-shaped only
+    return /auto-captured/i.test(t)                              // the explicit pre-v1.15 stamp
+        || /`[^`]*\b(?:cd|gh|git|npm|node|npx)\b[^`]*`/i.test(t) // a raw shell command left inside the card
+        || /(?:\/c\/users\/|[a-z]:[\\/]+users[\\/]|\/(?:home|users|mnt|tmp)\/)/i.test(t)   // a filesystem-path fragment
+        || /\b(?:PR|pull request|#)\s*#?\d{6,}\b/i.test(t);      // a 6+ digit "PR number" = scraped path digits, not a real PR
+};
+// One-time cleanup surface: the legacy raw-bash ship cards still live in a brain.
+// Suggestion-only (retire each with a ✓ marker) — they're already excluded from
+// repeat-matching, so this is cosmetic hygiene, not a correctness fix.
+export function findLegacyShipCards(struct, { max = 20 } = {}) {
+    const empty = { cards: [], total: 0 };
+    if (!struct || !Array.isArray(struct.cards)) return empty;
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const hits = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim()
+        && !isArchived(c) && !/↩|✅/.test(c.text) && isLegacyRawShipCard(c.text));
+    return { cards: hits.slice(0, max), total: hits.length };
+}
+
 export function detectRepeatWork(struct, query, { topK = 2, minScore = 5, minTokens = 2 } = {}) {
     const tokens = Array.isArray(query) ? query.filter(Boolean) : queryTokens(query);
     if (tokens.length < minTokens || !struct || !Array.isArray(struct.cards)) return [];
@@ -1203,6 +1244,7 @@ export function detectRepeatWork(struct, query, { topK = 2, minScore = 5, minTok
         if (c.type === 'container' || !(c.text || '').trim()) continue;
         const kind = kindOf(c.text);
         if (!kind) continue;                          // only COMPLETED-work cards qualify
+        if (isLegacyRawShipCard(c.text)) continue;    // pre-v1.15 raw-bash residue — never a repeat candidate (nonsense scraped PR numbers)
         // Score the first MEANINGFUL line, not a marker stamp: supersede/resolve
         // prepend "↩︎ superseded <date>" / lead with "✅ …", which would otherwise
         // become the title and hide the real content from title-weighted matching.
@@ -1307,6 +1349,12 @@ export function detectContradictions(struct, { minOverlap = 0.45, topK = 12 } =
     for (const e of struct.connections || []) {
         const k1 = e.fromId + '|' + e.toId, k2 = e.toId + '|' + e.fromId;
         if (e.label === 'superseded by' || e.label === 'closed by' || e.relationship === 'conflicts_with') { settled.add(k1); settled.add(k2); }
+        // Explicit "not a contradiction" dismissal — settles BOTH a cue pair and a
+        // polarity pair. This is the persisted escape hatch for a correction-cue
+        // FALSE positive: it had no stale card to retire, so a plain link never
+        // cleared it and it re-reported on every run forever. A deliberate
+        // not_contradiction edge (brain_connect pairs:…) now permanently dismisses it.
+        if (e.relationship === 'not_contradiction' || e.label === 'not a contradiction') { settled.add(k1); settled.add(k2); }
         if (e.label !== 'auto') { linked.add(k1); linked.add(k2); }
     }
     const out = [];
@@ -1577,6 +1625,50 @@ export function correctionOverlaysFor(struct, cards, { at = CORRECTION_SUPERSEDE
     return out;
 }
 
+// ── Awaits-merge decay — the deterministic twin of the correction overlay ────
+// A milestone written minutes before the human merges ("PR #332 awaits founder
+// merge") stays stale forever, even though ship-event auto-capture DOES record
+// "merged PR #332" — nothing linked the two. Matching a "PR #N" + awaits-cue card
+// against a harvested "merged PR #N" is EXACT-STRING, zero-inference work. Given
+// the cards recall is about to inject, return for each one carrying an unmet
+// merge that the ship event contradicts a merged-overlay {num, by, date}. The
+// caller annotates the card (never retires it — the fact is right, only its
+// status decayed). Pure + cheap. PR numbers are capped at 5 digits — a 6+ digit
+// "#N" is a path-scraped junk number (see isLegacyRawShipCard), never a real PR.
+const PR_MERGE_AWAIT_RE = /\b(?:await(?:s|ing)?|pending|not\s+yet|yet\s+to\s+be|to\s+be|unmerged|needs?)\b[^.\n]{0,24}?\bmerg/i;
+const PR_MERGED_RE = /\bmerged\b[^.\n]{0,16}?(?:PR|pull\s+request|#)\s*#?(\d{1,5})\b/i;
+const PR_REFS_RE = /\b(?:PR|pull\s+request|#)\s*#?(\d{1,5})\b/ig;
+function prNumbersIn(text) {
+    const out = new Set(); const s = String(text || '');
+    PR_REFS_RE.lastIndex = 0; let m;
+    while ((m = PR_REFS_RE.exec(s))) out.add(m[1]);
+    return out;
+}
+export function mergeOverlaysFor(struct, cards) {
+    const out = new Map();
+    if (!struct || !Array.isArray(struct.cards) || !Array.isArray(cards) || !cards.length) return out;
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    // Index PR number → the NEWEST live card that says it merged (ship event or hand marker).
+    const mergedBy = new Map();
+    for (const c of struct.cards) {
+        if (c.type === 'container' || isArchived(c) || !(c.text || '').trim()) continue;
+        const mm = PR_MERGED_RE.exec(c.text); if (!mm) continue;
+        const prev = mergedBy.get(mm[1]);
+        if (!prev || (c.createdAt || 0) >= (prev.createdAt || 0)) mergedBy.set(mm[1], c);
+    }
+    if (!mergedBy.size) return out;
+    for (const card of cards) {
+        if (!card || !card.id || !(card.text || '').trim()) continue;
+        if (PR_MERGED_RE.test(card.text)) continue;       // the hit IS a merge note — nothing to overlay
+        if (!PR_MERGE_AWAIT_RE.test(card.text)) continue; // must actually claim it's awaiting a merge
+        for (const num of prNumbersIn(card.text)) {
+            const by = mergedBy.get(num);
+            if (by && by.id !== card.id) { out.set(card.id, { kind: 'merged', num, by, date: by.createdAt ? new Date(by.createdAt).toISOString().slice(0, 10) : null }); break; }
+        }
+    }
+    return out;
+}
+
 // ── Auto-skill classifier (skills emerge from the flow, not just the '+' marker) ─
 // A REUSABLE skill (how-to / gotcha / convention) reads as a GENERAL RULE that
 // applies next time — distinct from a one-time decision ("we shipped X"). This is
@@ -2124,6 +2216,45 @@ export function findStaleOpenCards(struct, { coverAt = 0.6, max = 5 } = {}) {
     return { gaps: out.slice(0, max), total: out.length };
 }
 
+// ── Open-question deadline awareness ─────────────────────────────────────────
+// An open card can carry a self-declared deadline ("Rotate NPM_TOKEN before
+// ~2026-07-03"). Once that day passes the card is OVERDUE — but nothing surfaced
+// it, so it decayed silently and served the same stale reminder a day late. This
+// parses an EXPLICIT, cue-anchored ISO date only (a bare date elsewhere in the
+// card — "shipped 2026-06-30" — is NOT a deadline), so a false overdue flag can't
+// fire. Deadline = end of the named UTC day. Used to badge overdue opens in both
+// brief tiers (the "flag it in the next session's brief" acceptance criterion).
+const DEADLINE_RE = /\b(?:before|by|due(?:\s+(?:date|by|on))?|deadline|until|no\s+later\s+than|not\s+later\s+than|eod|end\s+of(?:\s+day)?)\b[^\n.]{0,32}?~?\s*(\d{4}-\d{2}-\d{2})\b/i;
+export function parseDeadline(text) {
+    const m = DEADLINE_RE.exec(String(text || ''));
+    if (!m) return null;
+    const ts = Date.parse(m[1] + 'T23:59:59Z');   // due at the END of the named day (UTC)
+    return Number.isFinite(ts) ? { date: m[1], ts } : null;
+}
+// Live open (❓/🎯) cards whose parsed deadline has passed, newest-overdue-last so
+// the most-overdue lead. Injectable `now` for hermetic tests. Skips already
+// resolved/superseded cards (they carry ✅/↩︎) and skills (standing reference).
+export function findOverdueOpenCards(struct, { now = Date.now() } = {}) {
+    const empty = { overdue: [], total: 0, byId: new Map() };
+    if (!struct || !Array.isArray(struct.cards)) return empty;
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const dayMs = (iso) => Date.parse(iso + 'T00:00:00Z');
+    const nowDay = dayMs(new Date(now).toISOString().slice(0, 10));
+    const out = [];
+    for (const c of struct.cards) {
+        if (c.type === 'container' || !(c.text || '').trim() || isArchived(c)) continue;
+        if (/↩|✅/.test(c.text)) continue;                       // already superseded/resolved
+        if (!/❓|🎯/.test(c.text) || /🛠/.test(c.text)) continue; // open questions & goals only
+        const d = parseDeadline(c.text);
+        // Overdue gate is LENIENT (end of the named day, d.ts) — a card isn't overdue
+        // at 00:01 on its deadline day. The DISPLAY count is a whole-calendar-day
+        // difference, so "before 2026-07-03" seen on 2026-07-04 reads "passed 1d ago".
+        if (d && d.ts < now) out.push({ card: c, date: d.date, daysOverdue: Math.max(0, Math.round((nowDay - dayMs(d.date)) / 86_400_000)) });
+    }
+    out.sort((a, b) => b.daysOverdue - a.daysOverdue);
+    return { overdue: out, total: out.length, byId: new Map(out.map(o => [o.card.id, o])) };
+}
+
 // ── Deliberate note → capture input ──────────────────────────────────────────
 // Turn ONE structured note into captureIntoBrain's input shape — the deliberate
 // twin of the Stop hook's transcript marker parser. This is what lets an ON-DEMAND