trantor 0.18.92 → 0.18.93

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.92",
+  "version": "0.18.93",
   "description": "Trantor — the hub-world for AI agent crews: live message bus, presence, project Kanban/flow board + crew orchestration for independent AI coding agents (Claude, Codex, Gemini, Kimi, DeepSeek)",
   "mcpServers": {
     "relay": {

package/README.md

@@ -436,7 +436,12 @@ trantor setup | doctor | connect | profile | provider | models
   `add <name> --key … [--plan api] [--base-url <url> --models a,b]` to bring any provider (custom
   endpoints are wired into OpenCode for you) · `remove <name>`.
 - **`trantor models [<provider>]`** — browse the live models behind each seat + the router's pick
-  per difficulty.
+  per difficulty. A model with no known price is listed as unpriced and never picked.
+- **`trantor memory`** — pins a project's Claude memory notes to the code they describe
+  (graft symbols and files) and flags a note **stale** when a pinned symbol's body changes, or
+  **broken** when it disappears. `check [--strict]` reports; `pin <note> | --all [--dry-run]`
+  pins or re-pins. Notes are pinned automatically when saved, and a session's first context line
+  names any stale or broken note. Terms: [GLOSSARY.md](GLOSSARY.md).
 - **`trantor up`** — `agent:model` pins a model (`deepseek:deepseek-v4-pro`); `agent:provider
   --task <k> --difficulty <d>` picks the **best live model** for the work at spawn
   (`glm:zai-coding-plan --difficulty hard`); spawns are verified on the bus with one retry;

package/bin/cli.mjs

@@ -26,6 +26,7 @@ switch (cmd) {
   case "secrets": run("bin/secrets.mjs"); break;
   case "keys":    run("bin/keys.mjs"); break;
   case "models": run("bin/models.mjs"); break;
+  case "memory": run("bin/memory.mjs"); break;
   case "advise":  run("bin/advise.mjs"); break;
   case "verify":  run("bin/crew-verify.mjs"); break;
   case "up":      runCrew(); break;
@@ -271,6 +272,8 @@ switch (cmd) {
   trantor hub         run the hub in the foreground (setup installs it as a service instead)
                       …or manage per-project hub pins: hub list · hub set <project> <url> · hub unset <project>
                       seats: which project lives in which directory — seats · seats add · seats up · seats login install
+  trantor memory check [--project <dir>] [--json]  check note pins for stale or broken code
+  trantor memory pin <note> | --all [--dry-run]  pin or re-pin notes from code mentions
   trantor state       a seat's working memory: show <seat> <card> [--json] · validate · reset --force · gc [--apply]
   trantor seat-why    WHY a seat is down (err file, logs, pids): seat-why <agent> [--json] — quota, auth, crash, or just no pane
   trantor seat-record the per-project seat record the advisor benches from (✓/∅/↩ per difficulty) — [--project p] [--reset <seat>] [--json]

package/bin/crew-runner.mjs

@@ -1111,7 +1111,13 @@ exit $turn_exit`;
     if (endStatus !== null) {
       cardStatusAtEnd = endStatus;
       const moved = ["testing", "done"].includes(endStatus) && !["testing", "done"].includes(cardStatusBefore);
-      noDelivery = !newCommit && !moved && !askVerdict && !blockedVerdict;
+      // #11551: a card ALREADY at testing/done when the turn began is delivered work — the
+      // codex-2 specimen's redelivered contract could neither commit anew nor move the card, and
+      // the check parked the seat for work it had already shipped. It only stands while the card
+      // still IS testing/done: a mid-turn bounce to doing (endStatus doing) reopens the contract.
+      const alreadyDelivered = ["testing", "done"].includes(cardStatusBefore)
+        && ["testing", "done"].includes(endStatus);
+      noDelivery = !newCommit && !moved && !alreadyDelivered && !askVerdict && !blockedVerdict;
     }
   }
   lastNoDelivery = noDelivery;

package/bin/memory.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { checkMemory, formatMemoryCheck } from "../lib/memory-pins.mjs";
+import { pinMemory, formatMemoryPin } from "../lib/memory-pin-write.mjs";
+
+const usage = "Usage: trantor memory check [--project <dir>] [--json] [--strict]\n       trantor memory pin <note> | --all [--dry-run] [--project <dir>] [--json]";
+try {
+  const { values, positionals } = parseArgs({ allowPositionals: true, options: {
+    project: { type: "string" }, json: { type: "boolean" }, help: { type: "boolean" },
+    strict: { type: "boolean" }, all: { type: "boolean" }, "dry-run": { type: "boolean" },
+  } });
+  if (values.help) {
+    console.log(usage);
+  } else {
+    const [command, note] = positionals;
+    let result;
+    let format;
+    if (command === "check" && positionals.length === 1 && !values.all && !values["dry-run"]) {
+      result = checkMemory({ project: values.project });
+      format = formatMemoryCheck;
+      if (values.strict && result.notes.some(note => note.pins.some(pin => ["stale", "broken"].includes(pin.status)))) process.exitCode = 1;
+    } else if (command === "pin" && !values.strict && positionals.length <= 2 && Boolean(note) !== Boolean(values.all)) {
+      result = pinMemory({ project: values.project, note, all: values.all, dryRun: values["dry-run"] });
+      format = formatMemoryPin;
+    } else {
+      throw new Error(usage);
+    }
+    const output = values.json ? JSON.stringify(result, null, 2) : format(result);
+    if (output) console.log(output);
+  }
+} catch (error) {
+  console.error(`memory: ${error.message}`);
+  process.exitCode = 1;
+}

package/hooks/hooks.json

@@ -150,6 +150,17 @@
             "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/ask-sidecar.mjs"
           }
         ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/memory-pin.mjs",
+            "async": true,
+            "timeout": 130
+          }
+        ]
       }
     ],
     "PostToolUseFailure": [

package/hooks/lib/memory-start.mjs

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { isMainThread, parentPort, Worker, workerData } from "node:worker_threads";
+import { gitCheckoutRoot } from "./git-checkout.mjs";
+
+const SLOW = "pin check skipped (slow), run trantor memory check";
+
+export function memoryStartLine(project) {
+  return new Promise(resolveLine => {
+    let worker;
+    let settled = false;
+    const finish = line => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolveLine(line);
+      if (worker) void worker.terminate().catch(() => {});
+    };
+    // Keep synchronous graph parsing and file reads off the hook's deadline timer.
+    const timer = setTimeout(() => finish(SLOW), 500);
+    try {
+      worker = new Worker(new URL(import.meta.url), { workerData: { project } });
+      worker.once("message", finish);
+      worker.once("error", () => finish(""));
+      worker.once("exit", () => finish(""));
+    } catch { finish(""); }
+  });
+}
+
+async function cachedMemoryLine(directory) {
+  const project = gitCheckoutRoot(directory) || resolve(directory);
+  const graphPath = join(project, "graft/.graph/wiring.json");
+  if (!existsSync(graphPath)) return "";
+  const { checkPin, memoryDirectory, notePins, pinFileNewer } = await import("../../lib/memory-pins.mjs");
+  const memoryDir = memoryDirectory(project);
+  if (!existsSync(memoryDir)) return "";
+  const graph = JSON.parse(readFileSync(graphPath, "utf8"));
+  const nodes = new Map(graph.nodes.map(node => [node.id, node]));
+  const graphTime = statSync(graphPath).mtimeMs;
+  let unchecked = 0;
+  const stale = new Set(), broken = new Set();
+  const notes = readdirSync(memoryDir, { withFileTypes: true })
+    .filter(entry => entry.isFile() && entry.name.endsWith(".md") && entry.name !== "MEMORY.md");
+  for (const note of notes) {
+    try {
+      const pins = notePins(readFileSync(join(memoryDir, note.name), "utf8"));
+      for (const pin of pins) {
+        if (pinFileNewer(project, pin, graphTime)) { unchecked++; continue; }
+        const { status } = checkPin(pin, project, nodes);
+        if (status === "stale") stale.add(note.name);
+        if (status === "broken") broken.add(note.name);
+      }
+    } catch { /* A concurrent edit or invalid span must not suppress other notes. */ }
+  }
+  const names = [...new Set([...stale, ...broken])].sort().map(name => name.replace(/[\s\x00-\x1f\x7f]+/g, " "));
+  const suffix = unchecked ? ` (${unchecked} unchecked: graph older than code, run trantor memory check)` : "";
+  return names.length || unchecked ? `${stale.size} stale, ${broken.size} broken notes: ${names.join(", ")}; run trantor memory check${suffix}` : "";
+}
+
+if (!isMainThread) {
+  try { parentPort.postMessage(await cachedMemoryLine(workerData.project)); }
+  catch { parentPort.postMessage(""); }
+}

package/hooks/memory-pin.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { pinMemory } from "../lib/memory-pin-write.mjs";
+import { memoryDirectory } from "../lib/memory-pins.mjs";
+import { gitCheckoutRoot } from "./lib/git-checkout.mjs";
+
+async function pinSavedNote() {
+  let raw = "";
+  for await (const chunk of process.stdin) raw += chunk;
+  const input = JSON.parse(raw);
+  if (!["Write", "Edit"].includes(input.tool_name) || !input.cwd || !input.tool_input?.file_path) return;
+  const path = resolve(input.cwd, input.tool_input.file_path);
+  if (!path.endsWith(".md") || basename(path) === "MEMORY.md") return;
+  const memoryRoot = dirname(dirname(memoryDirectory(input.cwd)));
+  if (!path.startsWith(`${memoryRoot}/`) || basename(dirname(path)) !== "memory") return;
+  const project = gitCheckoutRoot(input.cwd) || resolve(input.cwd);
+  const memoryDir = memoryDirectory(project);
+  if (dirname(path) !== memoryDir) return;
+  // A symlink must not turn a note-save hook into a write outside project memory.
+  if (dirname(realpathSync(path)) !== realpathSync(memoryDir)) return;
+  const result = pinMemory({ project, memoryDir, note: basename(path) });
+  if (result.message) console.error(`memory-pin: ${result.message}`);
+  for (const note of result.notes) {
+    for (const diagnostic of note.diagnostics) console.error(`memory-pin: ${note.name}: ${diagnostic}`);
+  }
+}
+
+try { await pinSavedNote(); }
+catch (error) { console.error(`memory-pin: ${error.message}`); }

package/hooks/sessionstart.mjs

@@ -16,6 +16,7 @@ import { maybeCheckBalances } from "./lib/balance-check.mjs";
 import { getJSON, signedGet, signedPost, loadIdentity } from "./lib/api.mjs";
 import { ledgerPaths, ensureStart, anchorCursor, writeCursor } from "./lib/inbox-ledger.mjs";
 import { ensureEnrolled } from "../lib/enroll.mjs";
+import { memoryStartLine } from "./lib/memory-start.mjs";
 
 // The build doctrine (docs/BUILD-DOCTRINE.md) in short form, one line per rule, injected for every
 // project's ORCHESTRATOR at boot (#6452): orchestrators that never opened the doc missed the ruling.
@@ -156,6 +157,8 @@ try {
     process.stdout.write(emit(ctx, banner, ""));
     process.exit(0);
   }
+  const memoryLine = await memoryStartLine(projectDir);
+  if (memoryLine) additionalContext += `${memoryLine}\n`;
   const project = resolveProject(projectDir);
   sessionTitle = project;   // baseline — enriched with the current work item after the catch-up fetch below
   const session = process.env.RELAY_SESSION

package/hub/routes/cards.mjs

@@ -38,7 +38,7 @@ export async function routeCards({ req, res, q, P, auth, ctx }) {
     appendTaskLog, appendTaskNote, cleanChecklist, cleanDrill, hasDrillLine, linkCommitToFocus,
     derivePhases, PROPOSAL_CAP, propFp, healthOf, REAP_GRACE_MS, subFp,
     prunePeers, canRead, HUB_VERSION, cmpSemver, isCardEvent, fmtAge, hubSend,
-    ONLINE_MS, PEER_TTL_MS,
+    ONLINE_MS, PEER_TTL_MS, AUTH_MODE,
   } = ctx;
     if (req.method === "POST" && P === "/task") {           // create a card
       const b = await body(req);
@@ -596,6 +596,22 @@ export async function routeCards({ req, res, q, P, auth, ctx }) {
       appendEvent("lesson", lProj, b.by || "", { text, scope });
       return json(res, 200, { ok: true, count: state.lessons.length });
     }
+    // A lesson can outlive the world it was learned in; only a global owner rewrites one, keeping its id and old text.
+    if (req.method === "POST" && P === "/lesson/update") {
+      if (AUTH_MODE !== "off" && !auth?.identity?.scopes?.some(s => s.project === "*" && s.role === "owner")) {
+        return json(res, 403, { error: "global owner permission required" });
+      }
+      const b = await body(req);
+      const lesson = state.lessons.find(l => l.id === Number(b.id));
+      if (!lesson) return json(res, 404, { error: "no such lesson" });
+      const text = stripNulText(b.text).trim().slice(0, 400);
+      if (!text) return json(res, 400, { error: "text required" });
+      lesson.revisions = [...(lesson.revisions || []), { text: lesson.text, by: lesson.by, ts: lesson.ts }].slice(-5);
+      Object.assign(lesson, { text, by: b.by || "", ts: now() });
+      markDirty();
+      appendEvent("lesson.revised", "", b.by || "", { id: lesson.id, text, scope: lesson.scope });
+      return json(res, 200, { ok: true, lesson });
+    }
     // --- verification gates: structured "must verify before shipping" claims that travel with
     // handoffs and surface PROMINENTLY to whoever takes over (so a safety-critical check can't be
     // skimmed past in narrative prose — the "verify Gail coefficients" intent that got lost). ---

package/lib/memory-pin-write.mjs

@@ -0,0 +1,163 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, renameSync, unlinkSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { stringify } from "yaml";
+import { checkPin, frontMatter, memoryDirectory, notePins, pinTarget, refreshPinGraph, symbolFingerprint } from "./memory-pins.mjs";
+
+export function replaceNotePins(text, pins) {
+  const front = frontMatter(text);
+  const newline = text.includes("\r\n") ? "\r\n" : "\n";
+  const value = stringify(pins, { collectionStyle: "flow", lineWidth: 0 }).trimEnd();
+  if (!front) return `---${newline}pins: ${value}${newline}---${newline}${text}`;
+  const pair = front.document.contents?.items.find(item => item.key?.value === "pins");
+  if (!pair) {
+    if (front.document.contents?.flow) throw new Error("cannot add pins to flow-style front matter without changing other keys");
+    const at = front.start + front.yaml.length;
+    return `${text.slice(0, at)}pins: ${value}${newline}${text.slice(at)}`;
+  }
+  // Value ranges exclude neighboring keys and their comments; never reserialize the whole note.
+  const [start, end] = pair.value.range;
+  const old = front.yaml.slice(start, end);
+  const ending = old.match(/\r?\n$/)?.[0] || "";
+  const spacing = start === end ? " " : "";
+  return text.slice(0, front.start + start) + spacing + value + ending + text.slice(front.start + end);
+}
+
+export function extractMentions(text, project, nodes, siblingNotes = new Set()) {
+  const front = frontMatter(text);
+  const body = (front ? text.slice(front.end) : text)
+    .replace(/\[\[[\s\S]*?\]\]/g, " ").replace(/\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, " ");
+  const paths = new Set([...nodes.values()].map(node => node.path));
+  const mentions = [];
+  const seen = new Set();
+  const pattern = /(?<![\w./\\-])((?:\.\/)?(?:[\w@.-]+\/)*[\w@.-]+)(?:#([\w$.-]+)|:(\d+))?/g;
+  for (const match of body.matchAll(pattern)) {
+    let file = match[1].replace(/^\.\//, "").replace(/[.,]+$/, "");
+    if (!pinTarget({ file }) || file === "Node.js") continue;
+    if (siblingNotes.has(file)) continue;
+    if (!file.includes("/") && /^v?\d+(?:\.[\da-z-]+)+$/i.test(file)
+      && !/\.(?:[cm]?jsx?|tsx?|py|rs|go|swift|c|h|cpp|hpp|java|kt|rb|sh|php|vue|svelte)$/i.test(file)) continue;
+    const prefix = `${basename(project)}/`;
+    if (!existingFile(project, file) && file.startsWith(prefix) && existingFile(project, file.slice(prefix.length))) {
+      file = file.slice(prefix.length);
+    }
+    if (!paths.has(file) && !existingFile(project, file) && !file.includes("/") && !/\.(?:[cm]?jsx?|tsx?|py|rs|go|swift|c|h|cpp|hpp|java|kt|rb|sh|php|vue|svelte|md|mdx|txt|json|ya?ml|toml|sql|css|html)$/i.test(file)) continue;
+    const symbol = match[2]?.replace(/\.+$/, "");
+    const mention = symbol ? { file, symbol: `${file}#${symbol}` }
+      : match[3] ? { file, line: Number(match[3]) } : { file };
+    const key = JSON.stringify(mention);
+    if (!seen.has(key)) { seen.add(key); mentions.push(mention); }
+  }
+  return mentions;
+}
+
+function existingFile(project, file) {
+  try { return statSync(join(project, file)).isFile(); }
+  catch { return false; }
+}
+
+function resolveMention(mention, nodes, project) {
+  if (!existingFile(project, mention.file)) return null;
+  if (mention.symbol) return nodes.has(mention.symbol) ? { symbol: mention.symbol, fp: symbolFingerprint(project, nodes.get(mention.symbol)) } : null;
+  if (mention.line === undefined) return { file: mention.file };
+  const lines = readFileSync(join(project, mention.file), "utf8").split(/\r?\n/);
+  if (mention.line < 1 || mention.line > lines.length) return null;
+  const enclosing = [...nodes.values()].filter(node => node.path === mention.file && node.kind !== "file")
+    .map(node => ({ node, span: /^L(\d+)-L(\d+)$/.exec(node.span) }))
+    .filter(({ span }) => span && +span[1] <= mention.line && +span[2] >= mention.line)
+    .sort((a, b) => (+a.span[2] - +a.span[1]) - (+b.span[2] - +b.span[1]));
+  return enclosing.length ? { symbol: enclosing[0].node.id, fp: symbolFingerprint(project, enclosing[0].node) } : { file: mention.file };
+}
+
+function planNote(text, project, nodes, date, siblingNotes) {
+  const pins = notePins(text);
+  const diagnostics = [];
+  const keys = new Set(pins.map(pin => pinTarget(pin)).filter(Boolean).map(pin => pin.symbol || pin.file));
+  for (const mention of extractMentions(text, project, nodes, siblingNotes)) {
+    if (!existingFile(project, mention.file)) {
+      diagnostics.push(`mentions a path that doesn't exist: ${mention.file}`);
+      continue;
+    }
+    const pin = resolveMention(mention, nodes, project);
+    if (!pin) { diagnostics.push(`unresolved mention: ${mention.symbol || `${mention.file}:${mention.line}`}`); continue; }
+    const key = pin.symbol || pin.file;
+    if (!keys.has(key)) { pins.push({ ...pin, at: date }); keys.add(key); }
+  }
+  const refreshed = pins.map(pin => {
+    const checked = checkPin(pin, project, nodes);
+    if (checked.status === "broken" || checked.status === "invalid pin") {
+      diagnostics.push(`${checked.status}: ${checked.detail}`);
+      return pin;
+    }
+    const refreshed = { ...pin };
+    if (checked.actual) { refreshed.fp = checked.actual; refreshed.at = date; }
+    return refreshed;
+  });
+  return { pins: refreshed, diagnostics, text: refreshed.length ? replaceNotePins(text, refreshed) : text };
+}
+
+export function pinMemory({ project = process.cwd(), memoryDir = memoryDirectory(project), note, all = false, dryRun = false } = {}) {
+  project = resolve(project);
+  if (Boolean(note) === Boolean(all)) throw new Error("specify one note or --all");
+  const files = existsSync(memoryDir) ? readdirSync(memoryDir, { withFileTypes: true })
+    .filter(entry => entry.isFile() && entry.name.endsWith(".md") && entry.name !== "MEMORY.md").map(entry => entry.name).sort() : [];
+  let selected = files;
+  if (!all) {
+    const requested = note.endsWith(".md") ? note : `${note}.md`;
+    const name = basename(requested);
+    if (name === "MEMORY.md") throw new Error("MEMORY.md is an index and cannot be pinned");
+    if (resolve(memoryDir, requested) !== resolve(memoryDir, name) || !files.includes(name)) throw new Error(`note not found in project memory: ${note}`);
+    selected = [name];
+  }
+  const siblingNotes = new Set(files);
+  const plans = selected.map(name => {
+    const plan = { name, path: join(memoryDir, name), original: undefined, pins: [], diagnostics: [], targets: [] };
+    try {
+      plan.original = readFileSync(plan.path, "utf8");
+      plan.text = plan.original;
+      plan.pins = notePins(plan.original);
+      plan.targets = [...plan.pins, ...extractMentions(plan.original, project, new Map(), siblingNotes)
+        .map(mention => ({ file: mention.file }))];
+    } catch (error) { failNote(plan, error); }
+    return plan;
+  });
+  const nodes = refreshPinGraph(project, plans.flatMap(plan => plan.targets));
+  if (!nodes) return { project, status: "pins off", message: "no graft graph, pins off", notes: [] };
+  const date = new Date().toISOString().slice(0, 10);
+  for (const plan of plans) {
+    if (plan.failed) continue;
+    try {
+      Object.assign(plan, planNote(plan.original, project, nodes, date, siblingNotes));
+      if (!dryRun && plan.text !== plan.original) atomicNoteWrite(plan);
+    } catch (error) { failNote(plan, error); }
+  }
+  return { project, status: dryRun ? "dry run" : "pinned", notes: plans.map(plan => {
+    const note = { name: plan.name, pins: plan.pins, diagnostics: plan.diagnostics, changed: plan.text !== plan.original };
+    if (plan.failed) note.failed = true;
+    return note;
+  }) };
+}
+
+function failNote(plan, error) {
+  plan.failed = true;
+  plan.text = plan.original;
+  plan.pins = plan.original === undefined ? [] : notePins(plan.original);
+  plan.diagnostics.push(error.message);
+}
+
+function atomicNoteWrite(plan) {
+  const temp = join(dirname(plan.path), `.${basename(plan.path)}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temp, plan.text, { flag: "wx", mode: statSync(plan.path).mode });
+    if (readFileSync(plan.path, "utf8") !== plan.original) throw new Error(`note changed during pinning: ${plan.name}; retry`);
+    renameSync(temp, plan.path);
+  } finally { if (existsSync(temp)) unlinkSync(temp); }
+}
+
+export function formatMemoryPin(result) {
+  if (result.message) return result.message;
+  return result.notes.map(note => {
+    const pins = note.pins.map(pin => pinTarget(pin)).map(pin => pin?.symbol || pin?.file || "invalid pin");
+    return `${note.name}: ${note.failed ? "failed" : result.status} — ${pins.join(", ") || "no pins"}${note.diagnostics.map(message => `\n  ${message}`).join("")}`;
+  }).join("\n");
+}

package/lib/memory-pins.mjs

@@ -0,0 +1,151 @@
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, openSync, readFileSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { isMap, parseDocument } from "yaml";
+import { z } from "zod";
+
+export function fingerprint(text) {
+  const normalized = text.replace(/\r\n/g, "\n").split("\n")
+    .map(line => line.trimEnd()).join("\n").replace(/^\n+|\n+$/g, "");
+  return `sha256:${createHash("sha256").update(normalized, "utf8").digest("hex").slice(0, 16)}`;
+}
+
+export function memoryDirectory(project, configDir = process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude")) {
+  return join(configDir, "projects", resolve(project).replace(/[^a-zA-Z0-9]/g, "-"), "memory");
+}
+
+export function frontMatter(text) {
+  const match = /^(---\r?\n)([\s\S]*?)(^---(?:\r?\n|$))/m.exec(text);
+  if (!match || match.index !== 0) {
+    if (/^---\r?\n/.test(text)) throw new Error("unterminated front matter");
+    return null;
+  }
+  const document = parseDocument(match[2]);
+  if (document.errors.length) throw new Error(`invalid front matter: ${document.errors[0].message.split("\n")[0]}`);
+  if (document.contents && !isMap(document.contents)) throw new Error("front matter must be a mapping");
+  return { document, yaml: match[2], start: match[1].length, end: match[0].length };
+}
+
+export function notePins(text) {
+  try {
+    const front = frontMatter(text);
+    const data = front?.document.toJS();
+    if (!data || data.pins == null) return [];
+    return Array.isArray(data.pins) ? data.pins : [data.pins];
+  } catch (error) {
+    return [{ invalid: error.message.split("\n")[0] }];
+  }
+}
+
+const fileSchema = z.string().min(1).refine(file => !isAbsolute(file)
+  && !file.split(/[\\/]/).some(part => part === ".." || part === "" || part === "."));
+const symbolSchema = z.object({
+  symbol: z.string().refine(symbol => {
+    const split = symbol.lastIndexOf("#");
+    return split > 0 && split < symbol.length - 1 && fileSchema.safeParse(symbol.slice(0, split)).success;
+  }),
+  fp: z.string().regex(/^sha256:[0-9a-f]{16}$/),
+}).passthrough().refine(pin => !Object.hasOwn(pin, "file"));
+const pinSchema = z.union([
+  symbolSchema,
+  z.object({ file: fileSchema }).passthrough()
+    .refine(pin => !Object.hasOwn(pin, "symbol") && !Object.hasOwn(pin, "fp")),
+]);
+
+export function pinTarget(pin) {
+  const parsed = pinSchema.safeParse(pin);
+  if (!parsed.success) return null;
+  const value = parsed.data;
+  return value.symbol ? { file: value.symbol.slice(0, value.symbol.lastIndexOf("#")), symbol: value.symbol }
+    : { file: value.file };
+}
+
+export function checkPin(pin, project, nodes) {
+  try { return checkTarget(pin, project, nodes); }
+  catch (error) { return { pin, status: "invalid pin", detail: error.message }; }
+}
+
+function checkTarget(pin, project, nodes) {
+  const target = pinTarget(pin);
+  if (!target) return { pin, status: "invalid pin", detail: pin?.invalid || "expected symbol + fp, or file without fp" };
+  const path = join(project, target.file);
+  if (!existsSync(path) || !statSync(path).isFile()) return { pin, status: "broken", detail: `file gone: ${target.file}` };
+  if (!target.symbol) return { pin, status: "ok" };
+  const node = nodes.get(target.symbol);
+  if (!node) return { pin, status: "broken", detail: `symbol gone: ${target.symbol}` };
+  const actual = symbolFingerprint(project, node);
+  return actual === pin.fp ? { pin, status: "ok" }
+    : { pin, status: "stale", actual, detail: `body changed: ${target.symbol} (${pin.fp} -> ${actual})` };
+}
+
+export function symbolFingerprint(project, node) {
+  const span = /^L(\d+)-L(\d+)$/.exec(node.span);
+  const lines = readFileSync(join(project, node.path), "utf8").replace(/\r\n/g, "\n").split("\n");
+  if (!span || +span[1] < 1 || +span[2] < +span[1] || +span[2] > lines.length) {
+    throw new Error(`invalid graft span for ${node.id}; run graft build`);
+  }
+  return fingerprint(lines.slice(+span[1] - 1, +span[2]).join("\n"));
+}
+
+export function pinFileNewer(project, pin, graphTime) {
+  const target = pinTarget(pin);
+  if (!target) return false;
+  try { return statSync(join(project, target.file)).mtimeMs > graphTime; }
+  catch { return false; }
+}
+
+export function refreshPinGraph(project, pins = []) {
+  const graphPath = join(project, "graft", ".graph", "wiring.json");
+  if (!existsSync(graphPath)) return null;
+  const needsBuild = () => pins.some(pin => pinFileNewer(project, pin, statSync(graphPath).mtimeMs));
+  if (needsBuild()) {
+    const lockPath = `${graphPath}.lock`;
+    const deadline = Date.now() + 125000;
+    let lock;
+    while (lock === undefined) {
+      try { lock = openSync(lockPath, "wx"); }
+      catch (error) {
+        if (error.code !== "EEXIST") throw error;
+        if (Date.now() >= deadline) throw new Error("timed out waiting for graft build lock");
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+      }
+    }
+    try {
+      // Another note writer may have refreshed the graph while we waited.
+      if (needsBuild()) {
+        const build = spawnSync("graft", ["build", project, "--no-gitignore", "--no-ignore"], {
+          encoding: "utf8", timeout: 120000, maxBuffer: 16 * 1024 * 1024,
+        });
+        if (build.error || build.status !== 0) throw new Error(`graft build failed: ${build.error?.message || build.stderr || build.stdout}`);
+      }
+    } finally { closeSync(lock); unlinkSync(lockPath); }
+  }
+  const graph = JSON.parse(readFileSync(graphPath, "utf8"));
+  if (!Array.isArray(graph.nodes)) throw new Error("invalid graft wiring graph: missing nodes");
+  return new Map(graph.nodes.map(node => [node.id, node]));
+}
+
+export function checkMemory({ project = process.cwd(), memoryDir = memoryDirectory(project) } = {}) {
+  project = resolve(project);
+  const graphPath = join(project, "graft", ".graph", "wiring.json");
+  if (!existsSync(graphPath)) return { project, status: "pins off", message: "no graft graph, pins off", notes: [] };
+  const notes = existsSync(memoryDir) ? readdirSync(memoryDir, { withFileTypes: true })
+    .filter(entry => entry.isFile() && entry.name.endsWith(".md") && entry.name !== "MEMORY.md")
+    .map(entry => ({ name: entry.name, pins: notePins(readFileSync(join(memoryDir, entry.name), "utf8")) })) : [];
+  let nodes = new Map();
+  if (notes.some(note => note.pins.some(pin => pinTarget(pin)?.symbol))) {
+    try { nodes = refreshPinGraph(project, notes.flatMap(note => note.pins)); }
+    catch (error) { return { project, status: "pins off", message: `pins off: ${error.message}`, notes: [] }; }
+  }
+  return { project, status: "checked", notes: notes.map(note => ({
+    name: note.name, pins: note.pins.map(pin => checkPin(pin, project, nodes)),
+  })) };
+}
+
+export function formatMemoryCheck(result) {
+  if (result.message) return result.message;
+  return result.notes.flatMap(note => note.pins.filter(pin => pin.status !== "ok")
+    .map(pin => `${note.name}: ${pin.status} — ${pin.detail}`)).join("\n") || `ok: ${result.notes.length} notes, ${result.notes.reduce((sum, note) => sum + note.pins.length, 0)} pins`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.92",
+  "version": "0.18.93",
   "type": "module",
   "bin": {
     "trantor": "bin/cli.mjs"
@@ -8,6 +8,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "pg": "^8.22.0",
+    "yaml": "^2.9.1",
     "zod": "^4.4.3"
   },
   "scripts": {