@polycode-projects/the-mechanical-code-talker 5.0.6 → 5.0.8

package/src/services/plan-viz.mjs

@@ -530,6 +530,11 @@ const PLAN = ${embedded};
   // server-rendered embed, for a plain renderPlanHtml() caller with no live
   // bundle nearby).
   let plan = null, N = 0, blockEls = {}, step = 0, playing = false, animating = false;
+  // The promise of whatever animateMove() call is currently in flight, or
+  // null between moves — reset() awaits this instead of declining outright
+  // when it is clicked mid-move, so a reset can never be silently dropped
+  // (see the reset handler below for why that mattered).
+  let animatingPromise = null;
 
   const posIn = (snap, id) => snap.items.find((i) => i.id === id && i.kind === "block");
   function drawState(i) {
@@ -609,7 +614,11 @@ const PLAN = ${embedded};
   }
   async function forward() {
     if (animating || step >= N) return;
-    render(); await animateMove(step); step += 1; render();
+    render();
+    animatingPromise = animateMove(step);
+    await animatingPromise;
+    animatingPromise = null;
+    step += 1; render();
   }
   async function playRange(from, to) {
     if (animating) return;
@@ -675,7 +684,19 @@ const PLAN = ${embedded};
 
   btn.next.addEventListener("click", () => { playing = false; forward(); });
   btn.back.addEventListener("click", () => { if (animating) return; playing = false; step = Math.max(0, step - 1); drawState(step); render(); });
-  btn.reset.addEventListener("click", () => { if (animating) return; playing = false; step = 0; drawState(0); render(); });
+  // playing drops the instant reset is clicked, even mid-move — a click
+  // that landed while animating used to bail out before touching playing
+  // at all, which left playRange's own loop free to run one more step the
+  // moment the in-flight move settled, so a fast play-then-reset click could
+  // reset the board and have it immediately start moving again. Waiting on
+  // animatingPromise (rather than declining) means the reset itself still
+  // never fires while a move might be touching the same block elements, but
+  // it is never dropped either.
+  btn.reset.addEventListener("click", async () => {
+    playing = false;
+    if (animatingPromise) await animatingPromise;
+    step = 0; drawState(0); render();
+  });
   btn.play.addEventListener("click", async () => {
     if (animating) return;
     if (playing) { playing = false; render(); return; }

package/src/services/predator-prey.mjs

@@ -52,13 +52,36 @@ import { objectClassChain, parseSnapshotSubject, snapshotSubject, worldEpochFact
 export { DEFAULT_VISION_RADIUS, believedCellOf, nearestBelievedTarget, beliefSnapshotFor };
 
 /** The v1 cast. Keyed by role, never by species — every knob this engine reads
- *  is role-keyed too, so swapping the pair is data. */
+ *  is role-keyed too, so swapping the pair is data. `hunts` is the cast's own
+ *  statement of who preys on whom, and it is the only thing the decision chain
+ *  reads to tell a threat from a bystander. */
 export const MUDIII_ROLES = Object.freeze({
-  predator: { role: "predator", kind: "fox", idPrefix: "fox" },
-  prey: { role: "prey", kind: "goblin", idPrefix: "goblin" },
+  predator: { role: "predator", kind: "fox", idPrefix: "fox", hunts: "prey" },
+  prey: { role: "prey", kind: "goblin", idPrefix: "goblin", hunts: null },
   food: { spawnedKind: "crumb", placedKind: "morsel" },
 });
 
+const CAST_ROLES = Object.freeze(["predator", "prey"]);
+
+/** Which roles `role` hunts, as the cast declares it: a role name, a list of
+ *  them, or null for a role that hunts nothing. A roles object that states no
+ *  link at all keeps the pairing its two role names already name, so a cast
+ *  written before `hunts` existed hunts exactly as it did. Pure. */
+export function rolesHuntedBy(role, roles = MUDIII_ROLES) {
+  const entry = roles?.[role];
+  if (!entry) return [];
+  const declared = "hunts" in entry ? entry.hunts : (role === "predator" ? "prey" : null);
+  if (declared === null || declared === undefined) return [];
+  return [].concat(declared).filter((named) => CAST_ROLES.includes(named));
+}
+
+/** Which roles hunt `role`, read back off those same links. Empty for a role
+ *  nothing preys on, which is what keeps a predator hunting when it catches
+ *  sight of another predator rather than fleeing its own kind. Pure. */
+export function rolesHunting(role, roles = MUDIII_ROLES) {
+  return CAST_ROLES.filter((other) => rolesHuntedBy(other, roles).includes(role));
+}
+
 const PLACEMENT_PREDICATE = "mgx:currently-in";
 const MASS_PREDICATE = "mgx:hasMass";
 const MOOD_PREDICATE = "mgx:feels";
@@ -371,15 +394,14 @@ function bestOneStepBy(fromCell, applyActions, scoreOf, isBetter, tieBreakScoreO
 }
 
 /** One-ply greedy: the reachable cell (or staying put) furthest in Chebyshev
- *  terms from `awayFrom`. Both the prey's evade rung and the predator's avoid
- *  rung are this function.
+ *  terms from `awayFrom`. The evade rung is this function.
  *
  *  `opts.towardCell`, when given, breaks a tie among equally-safe cells in
  *  favor of whichever is closest to it — a fleeing prey that knows where food
  *  is should flee toward it, not toward whichever direction DIRECTION_DELTA's
  *  key order happens to check first. Opt-in and null by default, so a caller
- *  that never passes it (the predator's own avoid rung) sees no change at
- *  all: same options, same scores, same first-wins tie order. */
+ *  that never passes it sees no change at all: same options, same scores, same
+ *  first-wins tie order. */
 export function greedyAway(fromCell, awayFrom, applyActions, { towardCell = null } = {}) {
   if (!awayFrom) return fromCell;
   return bestOneStepBy(
@@ -511,14 +533,13 @@ const round2 = (n) => Math.round(n * 100) / 100;
 // ---- the goal line and the mood word -------------------------------------------
 // Every branch assigns a mood beside the goal sentence it renders, and that
 // word is written as a real mgx:feels fact for the turn. The words are the four
-// spider-fly already uses: a predator mid-chase is angry, one avoiding a rival
-// is scared, anything wandering or foraging is calm, and anything that just ate
-// is happy.
+// spider-fly already uses: an agent mid-chase is angry, one fleeing something
+// that hunts it is scared, anything wandering or foraging is calm, and anything
+// that just ate is happy.
 
 function goalLine(kind, { subject, cell, arrived, boardNoun = "square", catches = false, facing = null, held = false } = {}) {
   switch (kind) {
     case "driven": return held ? `driven by hand — holding at ${cell}, facing ${facing}.` : `driven by hand — stepping to ${cell}.`;
-    case "avoid": return `avoiding ${subject}, last seen at ${cell}.`;
     case "chase":
       if (!arrived) return `chasing ${subject}, last seen at ${cell}.`;
       return catches ? `co-located with ${subject} — catching it.` : `standing over ${subject} — taking it.`;
@@ -902,22 +923,41 @@ export async function recastTownSquare(memoryDir, {
   });
 }
 
+/** The opening cast, seeded: predators on open cells, prey on the perimeter
+ *  they wander in from, and NO cell handed out twice.
+ *
+ *  Every other placement path in this engine already refuses a cell something
+ *  stands on — spawn-prey and spawn-food both filter the occupied set and
+ *  simply don't spawn when nothing is left, and placeFood refuses a prop or
+ *  another item. The page's own blocked-cell rule counts a single agent as
+ *  enough to block a cell too, so a mint that stacked two would put the board
+ *  in breach of the rule it opens under.
+ *
+ *  Prey prefer the perimeter, but a perimeter with no room left puts one a
+ *  cell inside rather than inside another animal. An agent goes unminted only
+ *  when the whole board is full, which is the same answer spawn-prey gives. */
 function seededRoster(layout, { predators, prey, roles, epoch }) {
   const roster = {};
   const taken = new Set();
   const open = openCells(layout);
   const edge = perimeterCells(layout);
+  const pickFreeCell = (preferred, id) => {
+    const free = preferred.filter((c) => !taken.has(c));
+    const options = free.length ? free : open.filter((c) => !taken.has(c));
+    if (!options.length) return null;
+    return seededPick(options, seedKey(layout.name, epoch, 0, id, "spawn"));
+  };
   for (let i = 1; i <= predators; i += 1) {
     const id = `${roles.predator.idPrefix}-${i}`;
-    const free = open.filter((c) => !taken.has(c));
-    const cell = seededPick(free.length ? free : open, seedKey(layout.name, epoch, 0, id, "spawn"));
+    const cell = pickFreeCell(open, id);
+    if (!cell) break;
     taken.add(cell);
     roster[id] = { role: "predator", cell, facing: DEFAULT_FACING };
   }
   for (let i = 1; i <= prey; i += 1) {
     const id = `${roles.prey.idPrefix}-${i}`;
-    const free = edge.filter((c) => !taken.has(c));
-    const cell = seededPick(free.length ? free : edge, seedKey(layout.name, epoch, 0, id, "spawn"));
+    const cell = pickFreeCell(edge, id);
+    if (!cell) break;
     taken.add(cell);
     roster[id] = { role: "prey", cell, facing: DEFAULT_FACING };
   }
@@ -1051,7 +1091,7 @@ function itemsPayload(liveItemIds, { state, itemCellOf, roles, taken = null }) {
  * `agents` and `items` and `ecology` are the frozen render payload — see
  * townSquareTickPayload, which projects exactly those three plus the turn.
  * `rungs` is the decision each live agent reached this turn ("driven" for a
- * hand-driven move, then "chase", "evade", "forage", "avoid", "wander", and —
+ * hand-driven move, then "chase", "evade", "forage", "wander", and —
  * on a cast that carries or spins webs —
  * "carry", "deliver", "carried", "trapped", "hold-web", "build-web"); an agent
  * that decided and then died still has a rung and no longer has an `agents`
@@ -1102,6 +1142,10 @@ export async function runTownSquareTick(memoryDir, {
     }
   }
 
+  const liveIdsOfRole = { predator: predators, prey };
+  const agentsOfRoles = (roleList, exceptId) =>
+    roleList.flatMap((r) => liveIdsOfRole[r] ?? []).filter((id) => id !== exceptId).sort();
+
   const decide = (agentId, role) => {
     const fromCell = parseCellId(state.placements.get(agentId).cell);
     // The visitor's hand, checked before any of the belief chain below. A
@@ -1122,8 +1166,14 @@ export async function runTownSquareTick(memoryDir, {
     // visionRadius: Infinity call, not new belief machinery. The rival-threat
     // lookup below stays on beliefOpts either way: this switch is about food.
     const foodBeliefOpts = foodVisionGated ? beliefOpts : { ...beliefOpts, visionRadius: Infinity };
-    const rivals = role === "predator" ? predators.filter((id) => id !== agentId) : predators;
-    const threat = driven ? null : nearestBelievedTarget(agentId, fromCell, rivals, state, beliefOpts);
+    // Who counts as a threat and who counts as quarry both come off the cast's
+    // own hunts links. Nothing hunts a predator on either shipped board, so a
+    // predator's threat list is empty and a second predator in view is just
+    // another animal on the square.
+    const huntedRoles = rolesHuntedBy(role, roles);
+    const huntsAgents = huntedRoles.length > 0;
+    const hunters = agentsOfRoles(rolesHunting(role, roles), agentId);
+    const threat = driven ? null : nearestBelievedTarget(agentId, fromCell, hunters, state, beliefOpts);
 
     let rung;
     let nextCell;
@@ -1132,8 +1182,7 @@ export async function runTownSquareTick(memoryDir, {
     let mood;
     let drivenFacing = null;
     // A carried prey and its captor both leave the ordinary chain. A carrying
-    // predator never drops its catch to dodge a rival or chase a second one:
-    // nothing here eats a predator, so "avoid" is contention, not survival.
+    // predator never drops its catch to chase a second one.
     const carriedPreyId = (carriesPrey && role === "predator") ? (state.carrying.get(agentId)?.prey ?? null) : null;
     const isCarrying = Boolean(carriedPreyId) && prey.includes(carriedPreyId);
     const captorId = (carriesPrey && role === "prey") ? (captorOfPrey.get(agentId) ?? null) : null;
@@ -1184,10 +1233,10 @@ export async function runTownSquareTick(memoryDir, {
       goal = goalLine("trapped");
       mood = "scared";
     } else if (threat) {
-      const towardFood = role === "prey"
-        ? nearestBelievedTarget(agentId, fromCell, [...foodIds].sort(), state, foodBeliefOpts)
-        : null;
-      if (blendsPreyDecision && role === "prey" && towardFood) {
+      const towardFood = huntsAgents
+        ? null
+        : nearestBelievedTarget(agentId, fromCell, [...foodIds].sort(), state, foodBeliefOpts);
+      if (blendsPreyDecision && !huntsAgents && towardFood) {
         // The one case the two rungs disagree about: this prey believes a
         // predator AND food, so a strict order has to pick between them and a
         // score does not.
@@ -1209,22 +1258,22 @@ export async function runTownSquareTick(memoryDir, {
           : goalLine("evade", { subject: threat.subject, cell: cellId(threat.cell.x, threat.cell.y) });
         mood = closedOnFood ? "calm" : "scared";
       } else {
-        rung = role === "predator" ? "avoid" : "evade";
-        // A fleeing prey that already knows where food is should flee toward
-        // it, not away from it — among cells that are equally safe, break the
-        // tie toward the nearest believed crumb. Prey-only: the predator's own
-        // avoid rung passes nothing, so its ties still resolve the old way.
+        rung = "evade";
+        // An agent that already knows where food is should flee toward it, not
+        // away from it — among cells that are equally safe, break the tie
+        // toward the nearest believed crumb. An agent that hunts has no food
+        // cell to offer, so its ties resolve on first-wins order alone.
         nextCell = greedyAway(fromCell, threat.cell, applyActions, { towardCell: towardFood?.cell ?? null });
         plan = stepPlan(fromCell, nextCell);
         goal = goalLine(rung, { subject: threat.subject, cell: cellId(threat.cell.x, threat.cell.y) });
         mood = "scared";
       }
     } else {
-      const quarry = role === "predator"
-        ? nearestBelievedTarget(agentId, fromCell, prey, state, beliefOpts)
+      const quarry = huntsAgents
+        ? nearestBelievedTarget(agentId, fromCell, agentsOfRoles(huntedRoles, agentId), state, beliefOpts)
         : nearestBelievedTarget(agentId, fromCell, [...foodIds].sort(), state, foodBeliefOpts);
       if (quarry) {
-        rung = role === "predator" ? "chase" : "forage";
+        rung = huntsAgents ? "chase" : "forage";
         const path = findActionPath(fromCell, (s) => s.x === quarry.cell.x && s.y === quarry.cell.y, applyActions, { stateKey: pathStateKey });
         if (path && path.actions.length) {
           nextCell = path.states[1];
@@ -1238,7 +1287,7 @@ export async function runTownSquareTick(memoryDir, {
         }
         const arrived = nextCell.x === quarry.cell.x && nextCell.y === quarry.cell.y;
         goal = goalLine(rung, { subject: quarry.subject, cell: cellId(quarry.cell.x, quarry.cell.y), arrived, catches: carriesPrey });
-        mood = role === "predator" ? "angry" : "calm";
+        mood = huntsAgents ? "angry" : "calm";
       } else if (role === "predator" && buildsWebs) {
         // A web-spinning predator with nothing in sight has something better to
         // do than wander: hold this cell, and spin a web here unless a live one

package/src/services/research-viz.mjs

@@ -20,7 +20,7 @@
 // input. scripts/build-demo-site.mjs calls it directly and writes the result to
 // public/research.html, after research-browser.bundle.js already exists.
 import { THEME_TOKENS_CSS, MONO_STACK, escapeHtml, demoEyebrowHtml, EYEBROW_LINKS_CSS } from "./viz-theme.mjs";
-import { fetchWithProgress, loadProgressLine, factTripleParts } from "./memory-panel-viz.mjs";
+import { fetchWithProgress, loadSeedPayload, loadProgressLine, factTripleParts } from "./memory-panel-viz.mjs";
 import { createTicker, prefersReducedMotion } from "./viz-ticker.mjs";
 import { loadWinkVendor } from "./viz-boot.mjs";
 import { cloneMemoryPayload } from "../adapters/memory/core.mjs";
@@ -354,6 +354,7 @@ ${DASH_DARK_CHROME_CSS}
   const sourceLabelFor = ${sourceLabelFor.toString()};
   const factTripleParts = ${factTripleParts.toString()};
   const fetchWithProgress = ${fetchWithProgress.toString()};
+  const loadSeedPayload = ${loadSeedPayload.toString()};
   const createTicker = ${createTicker.toString()};
   const prefersReducedMotion = ${prefersReducedMotion.toString()};
   const loadWinkVendor = ${loadWinkVendor.toString()};
@@ -397,25 +398,17 @@ ${DASH_DARK_CHROME_CSS}
 
   let seedPayload = null;
   let seedFacts = 0;
-  // One retry with a cache-busting query param: a CDN edge can serve a
-  // corrupted or truncated precompressed response (a transient bad cache
-  // entry, not a code defect — real bytes decompress fine, and the same URL
-  // fetched moments later is clean), and JSON.parse throwing is the only
-  // signal of that. The bust param forces a fresh fetch past that one entry.
+  // The same starter memory chat.html and ingest.html load, reported the same
+  // way: tmct.seed carries whether it arrived, so a page with an empty store
+  // can say which kind of empty it is.
+  window.tmct.seed = { state: "loading", facts: 0 };
   async function fetchSeed() {
-    for (let attempt = 1; attempt <= 2; attempt++) {
-      try {
-        const bust = attempt === 1 ? "" : (SEED_QUERY ? "&" : "?") + "retry=1";
-        const blob = await fetchWithProgress("./chat-seed.json" + SEED_QUERY + bust, (loaded, total) => noteProgress("seed", loaded, total));
-        seedPayload = JSON.parse(await blob.text());
-        seedFacts = (seedPayload.individuals || []).filter((i) => i.class === "Fact").length;
-        return;
-      } catch (err) {
-        if (attempt === 2) {
-          seedPayload = null;
-          console.warn("tmct research: chat-seed.json unavailable — starting unseeded", err);
-        }
-      }
+    const outcome = await loadSeedPayload(fetchWithProgress, "./chat-seed.json", SEED_QUERY, (loaded, total) => noteProgress("seed", loaded, total));
+    seedPayload = outcome.payload;
+    seedFacts = outcome.status.facts;
+    window.tmct.seed = outcome.status;
+    if (outcome.status.state === "failed") {
+      console.error("tmct research: chat-seed.json unavailable — starting unseeded (" + outcome.status.error + ")");
     }
   }
   async function newSession() {

package/src/services/spider-fly-turn.mjs

@@ -130,6 +130,12 @@ const SPIDER_FLY_SEE_RE = /^what (?:does|can) the (spider|fly)(?:-(\d+))?\s+see[
 const WORLD_OPENING_FALLBACK =
   "a spider waits in its web; a fly drifts in from the edge of the board. Neither is yours to move. Watch, or address one by name in chat.";
 
+/** The word that steps the board, said on the OPENING turn. It used to appear
+ *  only on re-entry, so a first-time player was told to watch a board that
+ *  never moved. Appended to whatever opening the worlds pack carries, so the
+ *  pack owns the scene and this owns the control. */
+const ADVANCE_HINT = 'Say "tick" to advance a turn.';
+
 // ---- the opening turn: load the shipped board through the worlds pack -------
 
 async function openSpiderFlyGame({ planHolder, memoryDir, env, cache, gameConfig = DEFAULT_GAME_CONFIG }) {
@@ -164,7 +170,7 @@ async function openSpiderFlyGame({ planHolder, memoryDir, env, cache, gameConfig
   const { started } = await startSpiderFlyGame(memoryDir, { flyCount: 1, config: gameConfig?.spiderFly });
   planHolder.state = { spiderFly: { turn: 0 } };
   const opener = started
-    ? (payload.meta?.opening || WORLD_OPENING_FALLBACK)
+    ? `${payload.meta?.opening || WORLD_OPENING_FALLBACK} ${ADVANCE_HINT}`
     : 'back to the spider-and-fly board — the spider and fly are already in play. Say "tick" to advance, or address one, e.g. "@spider the fly is east".';
   return {
     text: opener,

package/src/services/spider-fly-viz.mjs

@@ -1008,12 +1008,19 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
       chatqEl.focus();
     });
   }
+  // A direction pill REPLACES the claim rather than appending to it — unlike
+  // adventure.html/mud.html's claim pills, which are meant to compose ("look
+  // at" then "the book"), these four are mutually exclusive readings of the
+  // SAME fact (where one agent is), so a second click was building
+  // "@spider the fly is north the fly is east", which the grammar has never
+  // accepted and never will: a thing has one position, not several at once.
+  // The address prefix survives a direction click (so "@fly" then a
+  // direction still addresses the fly), the same way it already did before
+  // this fix — only the claim after it is replaced rather than grown.
   for (const btn of directionPillEls) {
     btn.addEventListener("click", () => {
       const kind = addresseeKindOf(chatqEl.value) || "spider";
-      let value = chatqEl.value;
-      if (!addresseeKindOf(value)) value = "@" + kind + " " + value.trimStart();
-      chatqEl.value = value.replace(/\\s+$/, "") + " " + btn.textContent;
+      chatqEl.value = "@" + kind + " " + btn.textContent;
       refreshPills();
       chatqEl.focus();
     });

package/src/services/viz-ticker.mjs

@@ -55,6 +55,10 @@ export function createTicker({
 } = {}) {
   const state = { playing: false, animating: false };
   const render = () => onRender({ ...state });
+  // The promise of whatever onTick() call is currently in flight, or null
+  // between ticks — reset() awaits this (see below) rather than bailing out
+  // when a click lands mid-tick, so a reset can never be silently dropped.
+  let inFlight = null;
 
   /** Advance exactly one step, honoring `hasNext`/`animating` guards. Returns
    *  whether it actually advanced. */
@@ -62,7 +66,9 @@ export function createTicker({
     if (state.animating || !hasNext()) return false;
     state.animating = true;
     render();
-    await onTick();
+    inFlight = Promise.resolve(onTick());
+    await inFlight;
+    inFlight = null;
     state.animating = false;
     render();
     return true;
@@ -95,9 +101,16 @@ export function createTicker({
     render();
   }
 
+  /** Stop and rewind. `state.playing` drops immediately, even mid-tick, so
+   *  `play()`'s own loop can never start one more tick once this has been
+   *  called — a reset clicked while a tick is animating used to return here
+   *  before touching `playing` at all, which left the loop running right
+   *  past it. If a tick IS in flight, this waits for it to actually settle
+   *  (never calling `onReset` while `onTick` might still be touching the
+   *  same state/DOM) before rewinding, rather than dropping the reset. */
   async function reset() {
-    if (state.animating) return;
     state.playing = false;
+    if (inFlight) await inFlight;
     if (onReset) await onReset();
     render();
   }

package/src/surfaces/http/server-http.mjs

@@ -15,6 +15,7 @@
 // HTTP surface.
 
 import { createServer } from "node:http";
+import { stat } from "node:fs/promises";
 import { runTurn, selectTool, capabilityPlanDeps } from "../../services/chat.mjs";
 import { TOOLS, dispatchTool } from "../../tools/server.mjs";
 import { runCapabilityPlan, buildCapabilityPlanCtx, declaredCapabilityNames } from "../../domain/router/drive.mjs";
@@ -143,7 +144,28 @@ function withRestNote(text, rest) {
  *   - a mapped, declared graph tool → tool_use
  *   - otherwise → end_turn text via runTurn
  */
-export async function respondToMessages(body, { config, graph, source = defaultSource } = {}) {
+/** How many Fact individuals a store snapshot holds. Facts only: an ordinary
+ *  turn records an Utterance and a Session too, and counting those made a game
+ *  move or a cited lookup read as a teach that went nowhere. */
+function countStoredFacts(snapshot) {
+  const individuals = snapshot?.payload?.individuals;
+  if (!Array.isArray(individuals)) return 0;
+  return individuals.reduce((n, i) => n + ((i?.class || "") === "Fact" ? 1 : 0), 0);
+}
+
+/** The memory store's vocabulary reader over a throwaway copy of `memoryDir` —
+ *  the seam a cold tool call gets so `tmct_ask` here answers what chat answers
+ *  over the same repo. Null when the server was started without a store. */
+async function memoryFactLookup(memoryDir) {
+  if (!memoryDir) return null;
+  const { readOnlyMemorySnapshot } = await import("../../adapters/memory/core.mjs");
+  const snapshot = await readOnlyMemorySnapshot(memoryDir);
+  if (!snapshot) return null;
+  const { factAnswer } = await import("../../services/chat.mjs");
+  return (query, envelope) => factAnswer(snapshot, query, envelope, true);
+}
+
+export async function respondToMessages(body, { config, graph, memoryDir = null, source = defaultSource } = {}) {
   const { model, messages, tools } = body || {};
   const declaredNames = new Set(
     (Array.isArray(tools) ? tools : []).map((t) => t && t.name).filter(Boolean),
@@ -185,7 +207,7 @@ export async function respondToMessages(body, { config, graph, source = defaultS
       return msg;
     }
     try {
-      const out = await dispatchTool(name, input, { config, source });
+      const out = await dispatchTool(name, input, { config, source, factLookup: await memoryFactLookup(memoryDir) });
       const msg = assistantMessage(model, [{ type: "text", text: withRestNote(out, rest) }], "end_turn");
       msg.tmct_checked_call = { name, input, problems: [] };
       return msg;
@@ -225,10 +247,25 @@ export async function respondToMessages(body, { config, graph, source = defaultS
     }
   }
 
-  // text answer: the cited, read-only answer the chat surface gives. memoryDir is
-  // null so the endpoint is PURE — no session artifacts, no writes, deterministic.
-  const { answer } = await runTurn(userText, { config, graph, source, memoryDir: null });
-  return assistantMessage(model, [{ type: "text", text: answer }], "end_turn");
+  // text answer: the cited, read-only answer the chat surface gives, over the
+  // same repo's memory store — without it, a term chat answers came back from
+  // this endpoint as a miss. The store is handed over as a throwaway in-memory
+  // COPY, so the endpoint stays PURE: reads see the real facts, and anything a
+  // turn would write lands in the copy rather than on disk.
+  const { readOnlyMemorySnapshot } = await import("../../adapters/memory/core.mjs");
+  const snapshot = await readOnlyMemorySnapshot(memoryDir);
+  const factsBefore = countStoredFacts(snapshot);
+  const { answer } = await runTurn(userText, { config, graph, source, memoryDir: snapshot });
+  // A teach turn lands in the copy and confirms itself. Say plainly that the
+  // fact went nowhere, rather than leaving "noted — remembered" as the last
+  // word on a write this endpoint never makes.
+  const wrote = countStoredFacts(snapshot) > factsBefore;
+  // A game's opening move writes board facts the same way a teach writes one,
+  // so the advice names the turn rather than assuming a fact was taught.
+  const text = wrote
+    ? `${answer}\n(nothing was stored — this endpoint reads the memory store and never writes to it. Run the same turn in a chat session to keep what it writes.)`
+    : answer;
+  return assistantMessage(model, [{ type: "text", text }], "end_turn");
 }
 
 /** The capability names a /v1/plan request restricts its plan to (its `tools`
@@ -308,9 +345,48 @@ function sendError(res, status, type, message) {
   sendJson(res, status, { type: "error", error: { type, message } });
 }
 
+/** A stamp of every graph file's size and mtime. Two equal stamps mean the
+ *  parsed graph in hand is still the graph on disk. */
+async function graphFileStamp(config) {
+  const files = config.graphFiles?.length ? config.graphFiles : [config.graphFile];
+  const parts = [];
+  for (const f of files) {
+    try {
+      const s = await stat(f);
+      parts.push(`${f}:${s.size}:${s.mtimeMs}`);
+    } catch { parts.push(`${f}:absent`); }
+  }
+  return parts.join("|");
+}
+
+/**
+ * A graph reader that re-parses when the artifact underneath it changes. The
+ * cold tool route loads the graph per call (dispatchTool → loadGraph), so a
+ * text answer served from a graph parsed at startup and a tool answer served
+ * from the file disagreed about the same repo the moment anything reindexed it
+ * mid-run. Stat-guarded, so an unchanged file costs one stat rather than a
+ * re-parse.
+ */
+function reloadingGraph(config, source) {
+  let stamp = null;
+  let graph = null;
+  return async () => {
+    const now = await graphFileStamp(config);
+    if (graph && now === stamp) return graph;
+    // source.fetchEntities keys its own per-process cache on the file PATH
+    // alone, so a same-path rewrite would still serve the payload parsed at
+    // startup. Drop it before re-reading; a stamp only changes when the bytes
+    // on disk did.
+    if (graph) source.clearCache?.();
+    graph = parseEntities(await source.fetchEntities(config));
+    stamp = now;
+    return graph;
+  };
+}
+
 /**
- * Start the HTTP server. Loads the graph once (tolerant: a missing artifact is
- * the empty bootstrap graph, never an error). Returns { server, url, host, port,
+ * Start the HTTP server. The graph is read tolerantly: a missing artifact is
+ * the empty bootstrap graph, never an error. Returns { server, url, host, port,
  * config, close } — `close()` shuts the socket cleanly (no hanging handles).
  *
  *   config — { graphFile } (build via configFor(repoPath) in bin/tmct.mjs)
@@ -319,9 +395,10 @@ function sendError(res, status, type, message) {
  */
 export async function startServer({ config, host = "127.0.0.1", port = 0, source = defaultSource, memoryDir = null } = {}) {
   if (!config || !config.graphFile) throw new Error("startServer requires config.graphFile");
-  // Load the graph once, up front. A missing artifact loads as the empty
-  // bootstrap graph — runTurn tolerates it (an honest empty/orienting answer).
-  const graph = parseEntities(await source.fetchEntities(config));
+  const currentGraph = reloadingGraph(config, source);
+  // Parse once up front so a listening server has already paid for the common
+  // case, and so a broken artifact surfaces before the first request.
+  await currentGraph();
 
   const server = createServer(async (req, res) => {
     try {
@@ -352,7 +429,7 @@ export async function startServer({ config, host = "127.0.0.1", port = 0, source
           sendError(res, 400, "invalid_request_error", `unknown tools name(s): ${unknown.join(", ")}; registered capabilities: ${declared.join(", ")}`);
           return;
         }
-        const out = await respondToPlan(body, { config, graph, memoryDir, source });
+        const out = await respondToPlan(body, { config, graph: await currentGraph(), memoryDir, source });
         sendJson(res, 200, out);
         return;
       }
@@ -375,7 +452,7 @@ export async function startServer({ config, host = "127.0.0.1", port = 0, source
         sendError(res, 400, "invalid_request_error", "`messages` array is required");
         return;
       }
-      const out = await respondToMessages(body, { config, graph, source });
+      const out = await respondToMessages(body, { config, graph: await currentGraph(), memoryDir, source });
       sendJson(res, 200, out);
     } catch (e) {
       sendError(res, 500, "api_error", e && e.message ? e.message : String(e));