klypix-mcp 1.83.0 → 1.84.0

package/A2A.md

@@ -113,6 +113,12 @@ If a write (`make_board`/`remember`) returns `input-required`, reply with a mess
 carrying the same `taskId` plus the missing input to **continue that task** (the
 server resumes it with a stable id and accumulated history).
 
+For `remember` or `learn_skill`, one-card requests may also provide `args.evidence`
+and `args.verify` using the [brain capture schema](README.md#capture-and-corrections).
+Such requests use the shared capture engine even without a marker. References and
+verification text are preserved; malformed metadata is rejected instead of discarded.
+Verification text is never executed.
+
 ## Notes
 
 - Tasks complete synchronously (the work is local file I/O), so `message/send`

package/FORMAT.md

@@ -132,6 +132,18 @@ strings: `text`, `box`, `image`, `file`, `container`, `approval`, `link`,
 `createdBy` (`user` | `agent`) and the optional `createdVia` (which agent/channel
 captured it) are the provenance bits the brain surfaces as badges and lenses.
 
+Brain cards may also carry `evidence` and `verify`. An evidence reference has `kind`
+(`file`, `pr`, `url`, `commit`, or `run`), `ref`, optional caller-supplied file blob `oid`,
+and optional caller-reported ISO `verifiedAt`. The host-neutral capture API rejects
+unknown input fields, unsafe file paths, and malformed metadata before writing.
+It adds `capturedAt`; readable local files up to 2 MiB also receive a SHA-256 `sha256`
+and `sourceBasis: "working-tree"`. Optional `headRevision` identifies HEAD at capture,
+which does not imply the captured working bytes were committed. Legacy `oid`-only
+references are read with both HEAD and working-file changes considered. These fields
+describe source provenance and change detection, never factual verification.
+`verify` is retained text, not executable configuration. All these optional fields
+survive the format codec and capture lifecycle; an explicit empty amendment clears them.
+
 The optional **`author`** answers the question a team actually asks: `createdBy` says
 *what* wrote a card, `author` says *whose*. It is resolved from `git config user.name`
 so brain attribution matches commit attribution with no configuration (override with

package/README.md

@@ -346,6 +346,30 @@ there are no lifecycle hooks on those hosts.
 
 ## Capture and corrections
 
+`brain_note` accepts structured supporting references and inert verification text:
+
+```json
+{
+  "text": "Retry failed uploads with a bounded backoff to preserve queued work.",
+  "area": "Storage",
+  "evidence": [{ "kind": "file", "ref": "src/uploads.mjs:42" }],
+  "verify": "node test/uploads.mjs"
+}
+```
+
+File references must stay inside the project. The capture records a fingerprint of the
+working file and, when available, the repository HEAD revision. An unchanged fingerprint
+means **source unchanged**, not that the remembered claim is correct or that tests passed.
+Dirty working files are fingerprinted as they are; HEAD alone does not describe those bytes.
+Read results distinguish changed, missing, and unverified sources. External references
+(`pr`, `url`, `commit`, `run`) are retained without fetching or verifying them. `verify` is
+shown as recorded text and never executed. Optional `verifiedAt` is explicitly caller-reported.
+
+On an amendment (`marker: "~"`), omitted metadata is preserved; `evidence: []` and
+`verify: ""` clear obsolete metadata. A resolve (`✓`) archives existing evidence; attach
+new evidence with a milestone and `closes`, or amend before resolving. The CLI accepts the
+same JSON on stdin, or `--evidence '<JSON array>'` and `--verify '<text>'`.
+
 On Claude Code, decisions are captured automatically at turn end from inline `🧠 BRAIN [Area]:`
 markers in the transcript, deduped, under a capture lock.
 

package/bin/klypix-a2a.mjs

@@ -327,14 +327,15 @@ async function runSkill(skill, args, text, via) {
       if (skill === 'learn_skill') marker = '+';
       const single = (!args.cards && text.trim()) ? stripVerb(text) : null;
       if (!marker && single && looksLikeSkill(single)) marker = '+';   // NL "remember this gotcha: always…" → skill
-      if (marker) {
+      if (marker || args.evidence !== undefined || args.verify !== undefined) {
         const noteText = single ?? (Array.isArray(args.cards) && args.cards[0]?.text) ?? '';
         if (!String(noteText).trim()) return needInput('Nothing to capture — send text or a card to remember.');
         if (String(noteText).length > 20_000) return needInput('Captured text must be 20,000 characters or fewer.');
         const requested = args.canvas ?? 'brain';
         const target = confinedCanvas(requested);
         if (!target.ok) return refusedCanvas(requested);
-        return await opBrainNote({ vault: VAULT, canvas: target.canvas, text: noteText, area: args.area, marker, closes: args.closes, via });
+        if (Array.isArray(args.cards) && args.cards.length !== 1) return needInput('Evidence capture requires exactly one card per request.');
+        return await opBrainNote({ vault: VAULT, canvas: target.canvas, text: noteText, area: args.area, marker, closes: args.closes, evidence: args.evidence, verify: args.verify, via });
       }
       // NL convenience: a bare "remember: X" becomes a single card on the brain.
       const cards = args.cards ?? (text.trim() ? [{ text: stripVerb(text) }] : null);

package/bin/klypix-install.mjs

@@ -391,7 +391,7 @@ try {
     // canvas-view-app.html is the canvas_view MCP App UI — staged raw (an HTML
     // file must never get a JS-comment banner) beside the flat server, which
     // resolves it via its ./canvas-view-app.html candidate path.
-    for (const f of ['global-brain-hook.mjs', 'capture-gap.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'enrichment.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'brain-graveyard.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'editor-detect.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'repo-state.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
+    for (const f of ['global-brain-hook.mjs', 'capture-gap.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'enrichment.mjs', 'brain-note.mjs', 'brain-evidence.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'brain-graveyard.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'editor-detect.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'repo-state.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
         const s = path.join(SRC, f); if (exists(s)) staged.push({ dst: f, content: fs.readFileSync(s, 'utf8') });
     }
     for (const [src, dst] of [

package/bin/klypix-worker.mjs

@@ -684,6 +684,13 @@ server.registerTool('brain_note', {
     marker: z.enum(['', '?', '!', '+', '✓', '~']).optional().describe('(none)=decision · ?=open question · !=milestone · +=🛠️ skill (reusable how-to/gotcha; always resurfaces, never ages out) · ✓=resolve+archive the best-matching card · ~=update the matching card in place. Default: decision.'),
     area: z.string().optional().describe('Area/topic — routes the card into that titled container and becomes a #tag (e.g. "Auth", "Release").'),
     closes: z.string().optional().describe('Title or [[wikilink]] of a strategy/question card this note fulfils — resolves+archives it and draws a "closed by" arrow.'),
+    evidence: z.array(z.object({
+      kind: z.enum(['file', 'pr', 'url', 'commit', 'run']),
+      ref: z.string().min(1).max(1000).describe('A project-relative file path (optional :line or #Lline), or an external reference. External references are stored without fetching them.'),
+      oid: z.string().optional().describe('Optional full file blob hash from Git; a caller-supplied anchor, not proof of the claim.'),
+      verifiedAt: z.string().optional().describe('Optional caller-reported ISO verification date/time; not independently verified.'),
+    }).strict()).max(16).optional().describe('Supporting references. File bytes are fingerprinted as captured working-tree sources; hashes only detect source changes. On ~, [] clears evidence. Not accepted on resolve; use a milestone with closes to attach new evidence.'),
+    verify: z.string().max(2000).optional().describe('Verification instructions or command text to retain and display. Never executed by KLYPIX. On ~, an empty string clears it.'),
     guard: z.object({
       when: z.object({
         tool: z.string().max(200).optional().describe('Regex matched against the tool name (e.g. "Bash", "Edit|Write").'),
@@ -697,10 +704,10 @@ server.registerTool('brain_note', {
     }).optional().describe("GUARD CARDS: make this '+' skill fire BEFORE a matching tool call runs (Claude Code PreToolUse denies on severity block; other hosts warn), not just resurface in briefs. The card stays a normal 🛠️ rule — ✓-resolving it retires the guard, ~ with {remove:true} disarms it."),
     canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
   },
-}, async ({ text, marker, area, closes, guard, canvas }, extra) => {
+}, async ({ text, marker, area, closes, evidence, verify, guard, canvas }, extra) => {
   // Both 1.77 and 1.78 ride this call: the enrichment question (the asker's
   // vocabulary for retrieval) AND the per-session capture receipt below.
-  const result = await opBrainNote({ vault: mcpPresence.vault, canvas: boundBrainCanvas(canvas), text, area, marker: marker || '', closes, guard, via: extra.klypixClientName, enrichmentQuestion: mcpPresence.declaredIntent });
+  const result = await opBrainNote({ vault: mcpPresence.vault, canvas: boundBrainCanvas(canvas), text, area, marker: marker || '', closes, evidence, verify, guard, via: extra.klypixClientName, enrichmentQuestion: mcpPresence.declaredIntent });
   // Per-session capture receipt — this is what stops the uncaptured-work nudge
   // from firing at a session that DID record its reasoning, just through MCP
   // rather than a 🧠 marker. The Stop hook and this server share one session-id
@@ -708,7 +715,7 @@ server.registerTool('brain_note', {
   // hook reads. Best-effort: a receipt failure must never fail the note.
   try {
     const { recordSessionCapture } = await import('../src/capture-gap.mjs');
-    recordSessionCapture(extra?.klypixRequestIdentity?.sessionId || mcpPresence.id);
+    if (!result.isError) recordSessionCapture(extra?.klypixRequestIdentity?.sessionId || mcpPresence.id, undefined, Date.now(), { project: mcpPresence.vault });
   } catch { /* receipt is best-effort */ }
   return toContent(result);
 });
@@ -939,32 +946,34 @@ server.registerTool('brain_sync', {
         if (head) gap.recordTaskBaseline(sid, { head, project: projectDir });
       } else if (phase === 'complete' && projectDir && sid) {
         const baseline = gap.readTaskBaseline(sid);
-        if (baseline?.head) {
-          // An ancestry check first: a rebase/reset makes the range meaningless,
-          // and reporting a rewritten history as "commits you didn't record" is
-          // exactly the cry-wolf that gets a nudge switched off.
-          const reachable = gitOk(['merge-base', '--is-ancestor', baseline.head, 'HEAD']);
-          const count = reachable ? Number(gitOut(['rev-list', '--count', '--no-merges', `${baseline.head}..HEAD`]) || 0) : 0;
+        const sameProject = baseline?.project && path.resolve(baseline.project) === path.resolve(projectDir);
+        if (sameProject && baseline?.head) {
+          // A successful note checkpoints the observed HEAD only. Work committed
+          // after that note belongs to a new outcome even in the same task/session.
+          const receipt = gap.sessionCaptureReceipt(sid, projectDir);
+          let from = baseline.head;
+          if (receipt?.head && receipt.at >= baseline.at
+              && gitOk(['merge-base', '--is-ancestor', baseline.head, receipt.head])
+              && gitOk(['merge-base', '--is-ancestor', receipt.head, 'HEAD'])) from = receipt.head;
+          const reachable = gitOk(['merge-base', '--is-ancestor', from, 'HEAD']);
+          const range = from + '..HEAD';
+          const count = reachable ? Number(gitOut(['rev-list', '--count', '--no-merges', range]) || 0) : 0;
           if (count > 0) {
-            const subjects = gitOut(['log', '--no-merges', '--format=%s', `${baseline.head}..HEAD`])
+            const subjects = gitOut(['log', '--no-merges', '--format=%s', range])
               .split('\n').map((s) => s.trim()).filter(Boolean).slice(0, 5);
-            // Bodies decide whether ANY rationale was recorded — the same rule
-            // the hook uses, so the two halves never disagree about one session.
-            const withRationale = gitOut(['log', '--no-merges', '--format=%x1e%b', `${baseline.head}..HEAD`])
+            const withRationale = gitOut(['log', '--no-merges', '--format=%x1e%b', range])
               .split('\x1e').map((b) => b.replace(/\s+/g, ' ').trim()).filter((b) => b.length >= 12).length;
+            const outcome = projectDir + ':' + gitOut(['rev-parse', 'HEAD']);
             const decision = gap.captureGapDecision({
               commitTotal: count,
               commitCards: withRationale,
-              sessionCaptured: gap.sessionHasCaptured(sid),
+              alreadyNudged: gap.outcomeWasNudged(sid, outcome),
             });
             if (decision) {
-              const changed = gitOut(['diff', '--name-only', `${baseline.head}..HEAD`]).split('\n').filter(Boolean).slice(0, 20);
-              const draft = gap.draftCaptureMarker({
-                commits: subjects.map((subject) => ({ subject })),
-                filesTouched: changed,
-              });
+              const changed = gitOut(['diff', '--name-only', range]).split('\n').filter(Boolean).slice(0, 20);
+              const draft = gap.draftCaptureMarker({ commits: subjects.map((subject) => ({ subject })), filesTouched: changed });
               captureGapText = gap.captureGapReason({ ...decision, draft, mode: 'advise' });
-              gap.recordCaptureGapNudge(sid);
+              gap.recordCaptureGapNudge(sid, undefined, outcome);
             }
           }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.83.0",
+  "version": "1.84.0",
   "mcpName": "io.github.dahshanlabs/klypix-mcp",
   "description": "Active state management for multi-agent coding: a shared, versioned project brain over MCP.",
   "type": "module",
@@ -84,10 +84,11 @@
     "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/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/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/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/plan-fulfillment.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/enrichment.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.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-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/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/uninstall.mjs",
+    "test": "node test/publish-verdict.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/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/plan-fulfillment.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/enrichment.mjs && node test/decay-status.mjs && node test/decay-hook.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-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/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/uninstall.mjs && node test/current-guidance.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
-    "runtime": "node bin/klypix-runtime.mjs"
+    "runtime": "node bin/klypix-runtime.mjs",
+    "eval:retrieval": "node scripts/eval-retrieval.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",

package/src/brain-evidence.mjs

@@ -0,0 +1,205 @@
+// Evidence is provenance, not a truth verdict. Capture snapshots the WORKING
+// file; HEAD identifies the repository revision but does not certify dirty bytes.
+// Verification text is inert data. No caller-provided command is ever executed.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const KINDS = new Set(['file', 'pr', 'url', 'commit', 'run']);
+const INPUT_FIELDS = new Set(['kind', 'ref', 'oid', 'verifiedAt']);
+const SHA_RE = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i;
+const READ_BUDGET = Symbol('brain-evidence-read-budget');
+// Read-side metadata can come from imported JSON, not the capture schema.
+// Never coerce objects (an own toString field can throw); bound string work
+// before normalization so oversized metadata cannot monopolize a recall call.
+const flat = (value, max = 1000) => typeof value === 'string'
+  ? value.slice(0, max).replace(/[\r\n\t]+/g, ' ').trim() : '';
+const inside = (root, target) => {
+  const rel = path.relative(root, target);
+  return rel !== '' && rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+};
+
+// Permit line anchors, but require portable project-relative file paths at the
+// API boundary. Check the nearest existing ancestor to catch missing paths below
+// a junction/symlink too. Read-side legacy invalid paths become unverified.
+export function resolveEvidenceFile(projectRoot, ref) {
+  if (typeof ref !== 'string' || !ref.trim() || /[\x00-\x1f\x7f]/.test(ref)) return null;
+  const clean = ref.trim().replace(/#L\d+(?:-L?\d+)?$/i, '').replace(/:\d+(?::\d+)?$/, '').replace(/\\/g, '/');
+  if (!clean || clean.startsWith('/') || /^[a-z]:/i.test(clean) || clean.includes(':')
+      || clean.split('/').some(part => !part || part === '.' || part === '..') || /[*?\[\]]/.test(clean)) return null;
+  if (!projectRoot) return null;
+  const root = path.resolve(projectRoot), target = path.resolve(root, clean);
+  if (!inside(root, target)) return null;
+  try {
+    const realRoot = fs.realpathSync(root);
+    let ancestor = target;
+    while (!fs.existsSync(ancestor) && ancestor !== root) {
+      // existsSync follows symlinks; lstat catches a dangling link.
+      try { if (fs.lstatSync(ancestor).isSymbolicLink()) return null; } catch { /* missing */ }
+      ancestor = path.dirname(ancestor);
+    }
+    const real = fs.realpathSync(ancestor);
+    if (real !== realRoot && !inside(realRoot, real)) return null;
+    return { target, relative: clean };
+  } catch { return null; }
+}
+
+function readSnapshot(file) {
+  try {
+    const stat = fs.statSync(file);
+    if (!stat.isFile() || stat.size > MAX_FILE_BYTES) return { status: 'unverified' };
+    // Bound the read even if another process grows the file after stat.
+    const fd = fs.openSync(file, 'r');
+    try {
+      const buffer = Buffer.alloc(Math.min(MAX_FILE_BYTES + 1, stat.size + 1));
+      const count = fs.readSync(fd, buffer, 0, buffer.length, 0);
+      const after = fs.fstatSync(fd);
+      if (count !== stat.size || after.size !== stat.size || after.mtimeMs !== stat.mtimeMs) return { status: 'unverified' };
+      return { status: 'read', sha256: crypto.createHash('sha256').update(buffer.subarray(0, count)).digest('hex') };
+    } finally { fs.closeSync(fd); }
+  } catch (error) { return { status: error.code === 'ENOENT' ? 'missing' : 'unverified' }; }
+}
+
+function git(root, args, timeout = 500) {
+  if (timeout <= 0) return null;
+  try { return execFileSync('git', args, { cwd: root, encoding: 'utf8', timeout: Math.max(1, Math.min(500, timeout)), maxBuffer: 16_384, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true }).trim(); }
+  catch { return null; }
+}
+
+function workingTreeStatus(root, relative, deadline) {
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) return 'unverified';
+  try {
+    execFileSync('git', ['diff', '--no-ext-diff', '--no-textconv', '--quiet', 'HEAD', '--', relative], {
+      cwd: root, timeout: Math.max(1, Math.min(500, remaining)), stdio: 'ignore', windowsHide: true,
+      env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
+    });
+    return 'unchanged';
+  } catch (error) { return error.status === 1 ? 'changed' : 'unverified'; }
+}
+
+export function prepareBrainEvidence({ projectRoot, evidence, verify, marker = '', text = '' } = {}) {
+  const bad = error => ({ ok: false, error });
+  if (marker === '✓' && (evidence !== undefined || verify !== undefined)) {
+    return bad('A resolve marker archives existing evidence. To record new evidence, write a milestone with closes, or amend the card with marker ~.');
+  }
+  if (verify !== undefined && (typeof verify !== 'string' || verify.length > 2000 || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(verify))) {
+    return bad('verify must be a string of at most 2000 characters; it is recorded, never executed.');
+  }
+  if (marker === '~' && typeof verify === 'string' && !verify.trim() && /(?:^|\s)verify:\s*[^\n\s]/i.test(String(text))) {
+    return bad('To clear verification, remove the inline verify: suffix from the amended text too.');
+  }
+  if (evidence !== undefined && (!Array.isArray(evidence) || evidence.length > 16)) return bad('evidence must be an array of at most 16 references.');
+  const normalized = [];
+  // Validate EVERY entry before any snapshot work (and, at the callers, before
+  // taking the write lock or draining pending capture queues).
+  for (const [index, item] of (evidence || []).entries()) {
+    const prefix = `evidence[${index}]`;
+    if (!item || typeof item !== 'object' || Array.isArray(item)) return bad(`${prefix} must be an object.`);
+    if (Object.keys(item).some(key => !INPUT_FIELDS.has(key))) return bad(`${prefix} has an unknown field; use kind, ref, optional oid and verifiedAt.`);
+    if (!KINDS.has(item.kind)) return bad(`${prefix}.kind must be file, pr, url, commit, or run.`);
+    if (typeof item.ref !== 'string' || !item.ref.trim() || item.ref.length > 1000 || /[\x00-\x1f\x7f]/.test(item.ref)) return bad(`${prefix}.ref must be a non-empty single-line string of at most 1000 characters.`);
+    if (item.oid !== undefined && (item.kind !== 'file' || typeof item.oid !== 'string' || !SHA_RE.test(item.oid))) return bad(`${prefix}.oid must be a full 40- or 64-character file blob hash.`);
+    if (item.verifiedAt !== undefined && (typeof item.verifiedAt !== 'string' || !/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z)?$/.test(item.verifiedAt) || !Number.isFinite(Date.parse(item.verifiedAt)) || new Date(item.verifiedAt).toISOString().slice(0, 10) !== item.verifiedAt.slice(0, 10))) return bad(`${prefix}.verifiedAt must be an ISO date or UTC timestamp (caller-reported, not independently verified).`);
+    if (item.kind === 'file' && !resolveEvidenceFile(projectRoot, item.ref)) return bad(`${prefix}.ref must be a safe project-relative file path (no traversal, absolute paths, or links outside the project).`);
+    if (item.kind === 'url') {
+      try { const url = new URL(item.ref); if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password) return bad(`${prefix}.ref must be an HTTP(S) URL without credentials.`); }
+      catch { return bad(`${prefix}.ref must be an HTTP(S) URL without credentials.`); }
+    }
+    normalized.push({ ...item, ref: item.ref.trim(), ...(item.oid ? { oid: item.oid.toLowerCase() } : {}) });
+  }
+  const now = new Date().toISOString();
+  const revision = normalized.some(item => item.kind === 'file') ? git(projectRoot, ['rev-parse', '--verify', 'HEAD']) : null;
+  for (const item of normalized) {
+    item.capturedAt = now;
+    if (item.kind !== 'file') continue;
+    const file = resolveEvidenceFile(projectRoot, item.ref);
+    const snapshot = file ? readSnapshot(file.target) : { status: 'unverified' };
+    if (snapshot.sha256) { item.sha256 = snapshot.sha256; item.sourceBasis = 'working-tree'; }
+    if (revision && SHA_RE.test(revision)) item.headRevision = revision;
+  }
+  return { ok: true, ...(evidence !== undefined ? { evidence: normalized } : {}), ...(verify !== undefined ? { verify: verify.trim() } : {}) };
+}
+
+export function inspectCardEvidence(card, { projectRoot, cache = new Map(), maxRefs = 4, budgetMs = 150 } = {}) {
+  // One shared cache is one response budget. Never pay refs * git-timeout on
+  // brain_sync's fast path. Local synchronous filesystem probes cannot be
+  // interrupted mid-call, but no additional probe starts after this deadline.
+  if (!cache.has(READ_BUDGET)) cache.set(READ_BUDGET, { deadline: Date.now() + Math.max(0, Math.min(1000, Number.isFinite(budgetMs) ? budgetMs : 150)), probes: 0 });
+  const budget = cache.get(READ_BUDGET);
+  const limit = Math.max(1, Math.min(16, Number(maxRefs) || 4));
+  const refs = Array.isArray(card?.evidence) ? card.evidence : [];
+  const sources = refs.slice(0, limit).map(item => {
+    const source = { kind: flat(item?.kind, 20), ref: flat(item?.ref, 1000), status: 'unverified' };
+    if (typeof item?.capturedAt === 'string') source.capturedAt = flat(item.capturedAt, 30);
+    if (typeof item?.verifiedAt === 'string') source.reportedVerifiedAt = flat(item.verifiedAt, 30);
+    if (typeof item?.headRevision === 'string' && SHA_RE.test(item.headRevision)) source.headRevision = item.headRevision;
+    // Never resolve a truncated reference as if it were the authored path.
+    if (item?.kind !== 'file' || typeof item?.ref !== 'string' || item.ref.length > 1000) return source;
+    const root = typeof projectRoot === 'string' && projectRoot ? path.resolve(projectRoot) : null;
+    if (!root) return source;
+    const exhausted = () => Date.now() >= budget.deadline || budget.probes >= 24;
+    // Remember containment-checked path resolutions separately from snapshots.
+    // A repeated reference can then reuse its observation after the deadline
+    // without even repeating filesystem-based path/symlink validation.
+    const pathKey = root + '\0path\0' + source.ref;
+    if (!cache.has(pathKey)) {
+      if (exhausted()) { source.reason = 'inspection budget exhausted'; return source; }
+      cache.set(pathKey, resolveEvidenceFile(root, source.ref));
+    }
+    const file = cache.get(pathKey);
+    if (!file) return source;
+    const key = root + '\0' + file.relative;
+    if (!cache.has(key)) {
+      if (exhausted()) { source.reason = 'inspection budget exhausted'; return source; }
+      budget.probes++;
+      cache.set(key, readSnapshot(file.target));
+    }
+    const current = cache.get(key);
+    if (current.status !== 'read') { source.status = current.status; return source; }
+    if (typeof item.sha256 === 'string' && /^[a-f0-9]{64}$/.test(item.sha256) && item.sourceBasis === 'working-tree') {
+      source.basis = 'captured working file';
+      source.status = current.sha256 === item.sha256 ? 'source-unchanged' : 'changed';
+      return source;
+    }
+    // Legacy hooks stamped HEAD blobs. Check both HEAD and local dirtiness;
+    // matching HEAD alone can conceal uncommitted changes. No repo/no git means
+    // unverified, never missing or unchanged by inference.
+    if (typeof item.oid === 'string' && SHA_RE.test(item.oid)) {
+      const gitKey = `${key}\0legacy`;
+      if (!cache.has(gitKey)) {
+        if (exhausted()) { source.reason = 'inspection budget exhausted'; return source; }
+        const oid = git(projectRoot, ['rev-parse', '--verify', `HEAD:${file.relative}`], budget.deadline - Date.now());
+        const working = oid ? workingTreeStatus(projectRoot, file.relative, budget.deadline) : 'unverified';
+        cache.set(gitKey, { oid, working });
+      }
+      const legacy = cache.get(gitKey);
+      source.basis = 'recorded HEAD blob and current working file';
+      source.status = !legacy.oid ? 'unverified'
+        : legacy.oid !== item.oid || legacy.working === 'changed' ? 'changed'
+        : legacy.working === 'unchanged' ? 'source-unchanged' : 'unverified';
+    }
+    return source;
+  });
+  const verification = typeof card?.verify === 'string' ? card.verify.slice(0, 2000).trim() : '';
+  return {
+    sources,
+    omitted: Math.max(0, refs.length - sources.length),
+    verify: verification ? { text: verification, status: 'not-executed' } : null,
+    recordedVia: flat(card?.createdVia, 80) || null,
+    recordedAt: Number.isFinite(card?.createdAt) && Math.abs(card.createdAt) <= 8.64e15 ? new Date(card.createdAt).toISOString() : null,
+  };
+}
+
+export function formatCardEvidence(summary, { maxChars = 700 } = {}) {
+  if (!summary?.sources?.length && !summary?.verify) return '';
+  const lines = ['Evidence (current source status is not claim verification):'];
+  if (summary.recordedVia) lines.push(`Recorded via ${flat(summary.recordedVia)}${summary.recordedAt ? ` at ${summary.recordedAt}` : ''}.`);
+  if (summary.verify) lines.push(`Recorded verification text (not executed):\n${summary.verify.text.replace(/\r\n?/g, '\n').split('\n').map(line => `> ${line}`).join('\n')}`);
+  for (const source of summary.sources) lines.push(`- ${source.status}: ${source.ref}${source.basis ? ` (${source.basis})` : ''}${source.reason ? ` (${source.reason})` : ''}${source.capturedAt ? `; captured ${source.capturedAt}` : ''}${source.headRevision ? `; HEAD ${source.headRevision.slice(0, 12)} (revision only)` : ''}${source.reportedVerifiedAt ? `; caller reported verification ${source.reportedVerifiedAt}` : ''}`);
+  if (summary.omitted) lines.push(`- ${summary.omitted} more reference(s) omitted.`);
+  const value = lines.join('\n'), limit = Math.max(160, Math.min(4000, Number(maxChars) || 700));
+  return value.length <= limit ? value : `${value.slice(0, limit - 1)}…`;
+}

package/src/brain-note.mjs

@@ -16,9 +16,12 @@
 //
 // --marker:  (none)=decision · ?/question · !/milestone · ✓/resolve · ~/update
 // --area X   route into the [Area] container (also a #tag) · --closes "<title>"
+// --evidence '<JSON array>' · --verify '<inert verification text>' (also JSON stdin)
 // Optional trailing path picks a different .klypix (default ./brain.klypix).
 import fs from 'fs';
 import path from 'path';
+import { prepareBrainEvidence } from './brain-evidence.mjs';
+import { looksLikeUnfilledDraft } from './capture-gap.mjs';
 import { captureIntoBrain, tidyBrain, atomicWrite, noteToCaptureInput, formatCaptureReceipts } from './klypix-format.mjs';
 import { brainCaptureLockPath, withAdvisoryWriteLock } from './brain-write-lock.mjs';
 
@@ -33,6 +36,13 @@ function parseArgs(argv) {
         if (a === '--area') out.area = argv[++i] || '';
         else if (a === '--marker' || a === '-m') out.marker = normMarker(argv[++i]);
         else if (a === '--closes') out.closes = argv[++i] || '';
+        else if (a === '--verify') {
+            if (argv[i + 1] === undefined) throw new Error('--verify needs a text argument.');
+            out.verify = argv[++i];
+        }
+        else if (a === '--evidence') {
+            try { out.evidence = JSON.parse(argv[++i]); } catch { throw new Error('--evidence needs a JSON array of references.'); }
+        }
         else rest.push(a);
     }
     // A trailing .klypix/.any token is the target file; the rest is the note text.
@@ -45,19 +55,27 @@ function readStdin() {
     try { if (process.stdin.isTTY) return ''; return fs.readFileSync(0, 'utf8'); } catch { return ''; }
 }
 
-let opts = parseArgs(process.argv.slice(2));
+let opts;
+try { opts = parseArgs(process.argv.slice(2)); }
+catch (e) { console.error(`brain-note: ${e.message}`); process.exit(1); }
 if (!opts.text) {
     const raw = readStdin().trim();
     if (raw) {
         try { const j = JSON.parse(raw); opts = { ...opts, ...j, marker: normMarker(j.marker ?? opts.marker) }; }
-        catch { opts.text = raw; }
+        catch {
+            if (/^[\[{]/.test(raw)) { console.error('brain-note refused (brain unchanged): malformed JSON input.'); process.exit(1); }
+            opts.text = raw;
+        }
     }
 }
 const file = path.resolve(opts.file || 'brain.klypix');
 if (!opts.text) { console.error('brain-note: nothing to write — pass a note as an arg, or JSON/text on stdin.'); process.exit(1); }
 if (!fs.existsSync(file)) { console.error(`brain-note: no brain at ${file} (run from a project with ./brain.klypix, or pass a path).`); process.exit(1); }
 
-const input = noteToCaptureInput({ text: opts.text, area: opts.area, marker: opts.marker, closes: opts.closes, createdVia: 'cli' });
+if (looksLikeUnfilledDraft(opts.text)) { console.error('brain-note refused (brain unchanged): complete or discard the draft rationale before capturing it.'); process.exit(1); }
+const metadata = prepareBrainEvidence({ projectRoot: path.dirname(file), evidence: opts.evidence, verify: opts.verify, marker: opts.marker, text: opts.text });
+if (!metadata.ok) { console.error(`brain-note refused (brain unchanged): ${metadata.error}`); process.exit(1); }
+const input = noteToCaptureInput({ text: opts.text, area: opts.area, marker: opts.marker, closes: opts.closes, evidence: metadata.evidence, verify: metadata.verify, createdVia: 'cli' });
 try {
     // Same cross-process lock as the MCP engine, hooks, and desktop app: an
     // unlocked read-modify-write racing any of them is silent last-writer-wins