trantor 0.18.91 → 0.18.93

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trantor",
-  "version": "0.18.91",
+  "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/models.mjs

@@ -10,21 +10,26 @@ function routeModel(ctx, provider, candidates, task, difficulty) {
     ? [script, "route", "--candidates", candidates, "-t", task, "-d", difficulty, "--json"]
     : [script, "route", "--provider", provider, "-t", task, "-d", difficulty, "--json"];
   const result = call("python3", args, { env: ctx.env });
-  if (!result.ok || !result.stdout) return "";
-  try { return JSON.parse(result.stdout).qualified || ""; }
-  catch { return ""; }
+  try {
+    const decision = JSON.parse(result.stdout);
+    if (decision.error) throw new Error(`[crew] router refused ${provider}: ${decision.error}`);
+    return result.ok ? decision.qualified || "" : "";
+  } catch (error) {
+    if (error instanceof SyntaxError) return "";
+    throw error;
+  }
 }
 
 export function resolveModel(ctx, agent, provider, task, difficulty) {
   const result = call("opencode", ["models", provider], { env: ctx.env });
   const candidates = result.ok ? result.stdout.split(/\s+/).filter(Boolean).join(" ") : "";
   let model = routeModel(ctx, provider, candidates, task, difficulty);
-  if (!model && candidates) {
-    const first = candidates.split(" ")[0];
-    model = first.startsWith(`${provider}/`) ? first : `${provider}/${first}`;
-    console.error(`[crew] router unavailable for ${agent}:${provider} — using the provider's own catalog head (${model})`);
+  // An unavailable router must not erase seats from a layout preview. Never launch an unresolved model.
+  if (!model && ctx.dry && candidates) {
+    model = `${provider}/<unresolved>`;
+    console.error(`[crew] dry run only for ${agent}:${provider} — router unavailable; model unresolved, live launch would be refused`);
   }
-  if (!model) throw new Error(`[crew] live model selection failed for ${agent}:${provider} — no router and no catalog; refusing opencode global default`);
+  if (!model) throw new Error(`[crew] live model selection failed for ${agent}:${provider} — no priced model matching provider preference; refusing opencode global default`);
   if (model.split("/")[0] !== provider) throw new Error(`[crew] router selected ${model} outside ${provider} — refusing cross-provider fallback`);
   return model;
 }
@@ -50,7 +55,7 @@ export function resolveSpec(ctx, spec, task, difficulty, skipped) {
     const model = resolveModel(ctx, agent, field, task, difficulty);
     // #7777: the live model is known — attach the catalog's per-difficulty effort parameters here
     // so the runner applies them where the CLI accepts them (CREW_EFFORT, below).
-    console.log(`  → ${agent}: live model ${model} (${field} · ${task}/${difficulty})`);
+    console.log(`  → ${agent}: ${model.endsWith("/<unresolved>") ? "preview" : "live"} model ${model} (${field} · ${task}/${difficulty})`);
     return { agent, model, effort: resolveEffort(agent, model, difficulty) };
   } catch (error) {
     console.error(error.message);

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/bin/models.mjs

@@ -1,10 +1,6 @@
 #!/usr/bin/env node
-// trantor models — browse the live models behind your crew seats (opencode is the adapter).
-//
-//   trantor models                # every opencode-driven seat + how many live models it serves
-//   trantor models <provider>     # list that provider's live models + what the router picks per
-//                                 # difficulty (so you can see hard→strong, easy→cheap at a glance)
-import { execSync } from "node:child_process";
+// Browse live crew models and preview the same routing used at launch.
+import { execSync, spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { existsSync, statSync } from "node:fs";
@@ -25,16 +21,11 @@ const liveModels = (providerOc) => {
   catch { return []; }
 };
 
-const FLASH_TIER = /(flash|turbo|lite|mini|highspeed|small)/i;
-
 function routePick(candList, diff) {
-  try {
-    const hard = diff === "hard";
-    const strong = hard ? candList.filter(id => !FLASH_TIER.test(id)) : candList;
-    const pool = strong.length > 0 ? strong : candList;
-    const out = execSync(`python3 ${SCROOGE} route --candidates ${JSON.stringify(pool.join(" "))} -t code -d ${diff} --json 2>/dev/null`, { encoding: "utf8" });
-    return JSON.parse(out).qualified || "?";
-  } catch { return "?"; }
+  const result = spawnSync("python3", [SCROOGE, "route", "--candidates", candList.join(" "),
+    "-t", "code", "-d", diff, "--json"], { encoding: "utf8" });
+  try { return JSON.parse(result.stdout); }
+  catch { return { error: "router unavailable", unpriced: [] }; }
 }
 
 function listAll() {
@@ -57,12 +48,14 @@ function detail(name) {
   const models = liveModels(providerOc);
   if (!models.length) { console.log(`No live models for '${providerOc}' (opencode offline / no key / unknown provider).`); return; }
   console.log(`${C.gold}${providerOc}${C.off} — ${models.length} live models\n`);
-  for (const m of models.slice(0, 60)) console.log(`  ${m}`);
+  const picks = Object.fromEntries(["easy", "medium", "hard"].map(d => [d, routePick(models, d)]));
+  const unpriced = new Set(Object.values(picks).flatMap(p => p.unpriced || []));
+  for (const m of models.slice(0, 60)) console.log(`  ${m}${unpriced.has(m.split("/").at(-1)) ? " (unpriced)" : ""}`);
   if (models.length > 60) console.log(`  ${C.dim}… +${models.length - 60} more${C.off}`);
   if (existsSync(SCROOGE) || has("scrooge")) {
     console.log(`\n${C.gold}router picks (code task):${C.off}`);
-    for (const d of ["easy", "medium", "hard"]) console.log(`  ${d.padEnd(7)} → ${routePick(models, d)}`);
-    const caps = join(H, ".token-scrooge", "capabilities.json");
+    for (const d of ["easy", "medium", "hard"]) console.log(`  ${d.padEnd(7)} → ${picks[d].qualified || picks[d].error}`);
+    const caps = join(process.env.SCROOGE_HOME || join(H, ".token-scrooge"), "capabilities.json");
     // only nag when the scores are missing or older than the weekly refresh allows for
     const ageDays = existsSync(caps) ? (Date.now() - statSync(caps).mtimeMs) / 86400e3 : Infinity;
     if (ageDays > 9) console.log(`${C.dim}(scores ${ageDays === Infinity ? "missing" : `${Math.floor(ageDays)}d old`} — run scrooge-capabilities to (re)score the catalog for accurate difficulty routing)${C.off}`);

package/engine/bin/scrooge

@@ -37,7 +37,7 @@ Config:  $SCROOGE_HOME (default ~/.token-scrooge) holds registry.json + calls.js
 Keys:    read from the environment; optionally also from $SCROOGE_ENV_FILE (KEY=VALUE)
 Exit: 0 ok, non-zero on error (message to stderr).
 """
-import sys, os, json, time, argparse, urllib.request, urllib.error, re, shutil, hashlib
+import sys, os, json, time, argparse, urllib.request, urllib.error, re, shutil, hashlib, math
 
 HOME = os.path.expanduser("~")
 SCROOGE_DIR = os.environ.get("SCROOGE_HOME", os.path.join(HOME, ".token-scrooge"))
@@ -171,18 +171,26 @@ def model_quality(caps, mid, metric):
         v = c.get("intelligence")          # fall back to the general index
     return float(v) if isinstance(v, (int, float)) else 0.0
 
-def blended_cost(reg, caps, mid):
+def model_prices(reg, caps, mid):
     # The curated registry carries cost for its own models; for CATALOG models (OpenRouter's
     # hundreds, brought via --candidates) the per-model price rides on the capability entry
     # instead — so a brought model is ranked on its real price without bloating the registry.
-    m = reg["models"].get(mid) or (caps.get(mid) if isinstance(caps, dict) else None) or {}
-    return max(1e-6, 0.3 * m.get("cost_in", 0) + 0.7 * m.get("cost_out", 0))
+    for m in (reg["models"].get(mid) or {}, (caps or {}).get(mid) or {}):
+        prices = [m.get("cost_in"), m.get("cost_out")]
+        if all(type(v) in (int, float) and math.isfinite(v) and v >= 0 for v in prices):
+            return prices
+    return None
+
+def blended_cost(reg, caps, mid):
+    prices = model_prices(reg, caps, mid)
+    return max(1e-6, 0.3 * prices[0] + 0.7 * prices[1]) if prices is not None else None
 
 def weigh_candidates(reg, caps, cand_ids, task, difficulty):
     """Apply the difficulty floor, then rank survivors by quality^qw / cost^cw.
     Returns [(model_id, score)] best-first."""
     metric = task_metric(task)
-    quals = [(mid, model_quality(caps, mid, metric)) for mid in cand_ids]
+    quals = [(mid, model_quality(caps, mid, metric)) for mid in cand_ids
+             if blended_cost(reg, caps, mid) is not None]
     scored_q = sorted(q for _, q in quals if q > 0)
     pct = DIFF_PCTL.get(difficulty, 0.5)
     floor = 0.0
@@ -218,6 +226,9 @@ def route_task(reg, caps, task, difficulty, prompt, spread=0):
     live = [m for m in cands if provider_key(reg, reg["models"][m]["provider"])]
     if not live:
         raise SystemExit("No live API key for any model serving task '%s'." % task)
+    live = [m for m in live if blended_cost(reg, caps, m) is not None]
+    if not live:
+        raise SystemExit("No priced candidate models; enrich pricing before routing.")
     if not caps:                                   # no quality data → legacy cheapest-first
         return live[0], reg["models"][live[0]]["provider"], {"difficulty": None, "weighed": False}
     diff = difficulty or infer_difficulty(task, prompt)
@@ -659,7 +670,19 @@ def cmd_route(reg, args):
     by_bare = {}
     for r in raw:
         by_bare.setdefault(r.split("/")[-1], r)
-    bare_ids = list(by_bare.keys())
+    unpriced = [b for b in by_bare if blended_cost(reg, caps, b) is None]
+    bare_ids = [b for b in by_bare if b not in unpriced]
+    if not provider:
+        providers = {r.split("/")[0] for r in raw if "/" in r}
+        if len(providers) == 1:
+            provider = next(iter(providers))
+    if provider == "qwen":
+        preferred = "qwen3.8-max" if args.difficulty == "hard" else "qwen3.8-flash"
+        bare_ids = [b for b in bare_ids if b == preferred]
+    if not bare_ids:
+        print(json.dumps({"error": "no priced candidate models matching provider preference",
+                          "unpriced": unpriced}))
+        raise SystemExit(2)
     task = args.task or "code"
     difficulty = args.difficulty or "medium"
     metric = task_metric(task)
@@ -681,11 +704,13 @@ def cmd_route(reg, args):
     original = by_bare[pick_bare]
     qualified = original if "/" in original else (("%s/%s" % (provider, pick_bare)) if provider else pick_bare)
     result = {"provider": provider, "model": pick_bare, "qualified": qualified,
-              "weighed": weighed, "task": task, "difficulty": difficulty, "why": why, "candidates": cand_out}
+              "weighed": weighed, "task": task, "difficulty": difficulty, "why": why, "candidates": cand_out, "unpriced": unpriced}
     if getattr(args, "json", False):
         print(json.dumps(result))
     else:
         err(DIM("[scrooge route] %s → %s (%s)" % (provider or "?", qualified, "weighed" if weighed else "heuristic")))
+        if unpriced:
+            err("[scrooge route] unpriced (excluded): " + ", ".join(unpriced))
         print(qualified)
     return 0
 
@@ -704,7 +729,9 @@ def cmd_list(reg, args):
             q = caps.get(m) or {}
             fmt = lambda v: ("%2.0f" % v) if isinstance(v, (int, float)) else " -"
             cap = "%s/%s/%s " % (fmt(q.get("intelligence")), fmt(q.get("coding")), fmt(q.get("reasoning")))
-        print("  %s %-24s %5.2f/%-5.2f %s%-9s %s" % (live, m, c.get("cost_in",0), c.get("cost_out",0),
+        prices = model_prices(reg, caps, m)
+        price = "unpriced" if prices is None else "%5.2f/%-5.2f" % tuple(prices)
+        print("  %s %-24s %s %s%-9s %s" % (live, m, price,
               cap, c.get("trust",""), ",".join(c.get("good_for", []))))
     print("\nTASKS (weighed by capability×cost, gated by difficulty):")
     for t, ms in reg.get("tasks", {}).items():

package/engine/test-routing.py

@@ -36,8 +36,16 @@ def ok(name, cond):
 # 1. catalog cost via caps fallback (model absent from registry)
 ok("blended_cost falls back to the capability entry for catalog models",
    abs(g["blended_cost"](reg, caps, "frontier") - (0.3 * 5.0 + 0.7 * 22.5)) < 1e-6)
-ok("blended_cost is 1e-6 for an entirely unknown model (no crash)",
-   g["blended_cost"](reg, caps, "does-not-exist") == 1e-6)
+ok("unknown model is unpriced", g["blended_cost"](reg, caps, "does-not-exist") is None)
+for bad in ({}, {"cost_in": 1}, {"cost_in": None, "cost_out": 1},
+            {"cost_in": -1, "cost_out": 1}, {"cost_in": float("nan"), "cost_out": 1}):
+    ok("invalid or incomplete prices are unpriced", g["blended_cost"](reg, {"bad": bad}, "bad") is None)
+ok("explicit zero prices are free", g["blended_cost"](reg, {"free": {"cost_in": 0, "cost_out": 0}}, "free") == 1e-6)
+for diff in ("easy", "medium", "hard"):
+    mixed = {"priced": {"coding": 50, "cost_in": 2, "cost_out": 6}, "unpriced": {"coding": 99}}
+    ranked = g["weigh_candidates"](reg, mixed, list(mixed), "code", diff)
+    ok("priced beats stronger unpriced at " + diff, [m for m, _ in ranked] == ["priced"])
+ok("all unpriced yields no pick", g["weigh_candidates"](reg, {}, ["unknown"], "code", "easy") == [])
 
 def winner(diff):
     return g["weigh_candidates"](reg, caps, cands, "code", diff)[0][0]

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.91",
+  "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": {