@polycode-projects/the-mechanical-code-talker 2.10.5 → 2.11.0

package/src/services/ledger-viz.mjs

@@ -16,6 +16,7 @@
 
 import { loadMemory, readFactRows, findContradictions, normFactTerm } from "../adapters/memory/core.mjs";
 import { THEME_TOKENS_CSS, SERIF_STACK, MONO_STACK, escapeHtml, embedJson } from "./viz-theme.mjs";
+import { createTicker, prefersReducedMotion } from "./viz-ticker.mjs";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
@@ -533,6 +534,14 @@ export function renderLedgerHtml({ rows, terms, edges, focus, contradictions, wo
           <button type="button" id="ingestToggle" class="dockbtn">ingest text&hellip;</button>
           <button type="button" id="exportFacts" class="dockbtn">export facts</button>
         </div>
+        <div class="researchrow" title="Fetches the topic from Simple English Wikipedia into this graph, then queues the topics its lead section links to — each queued topic runs as its own dock turn, paced politely. Asking is the network consent for these fetches.">
+          <label for="researchTopic" class="mono">research:</label>
+          <input id="researchTopic" type="text" autocomplete="off" spellcheck="false"
+            placeholder="a topic, e.g. owls" aria-label="Topic to research on Simple English Wikipedia">
+          <button type="button" class="dockbtn" id="researchGo">go</button>
+          <button type="button" class="dockbtn" id="researchPlay" aria-pressed="false" hidden>play</button>
+          <span class="ingeststatus mono" id="researchStatus" aria-live="polite"></span>
+        </div>
         <div class="ingestpanel" id="ingestPanel" hidden>
           <textarea id="ingestText" spellcheck="false" aria-label="Text to ingest into the graph"
             placeholder="Paste text or drop a .txt/.md file. Each sentence it recognizes as a fact is added to the graph; the rest are skipped honestly."></textarea>
@@ -680,6 +689,10 @@ ${THEME_TOKENS_CSS}
   .dockbtn { font-family: ${MONO_STACK}; font-size: .68rem; color: var(--muted); border: 1px solid var(--line); border-radius: 6px; padding: .22rem .6rem; background: var(--bg); cursor: pointer; }
   .dockbtn:hover { color: var(--ink); border-color: var(--ink); }
   .dockbtn.primary { background: var(--ink); color: var(--bg); border-color: var(--ink); }
+  .dockbtn[aria-pressed="true"] { background: var(--ink); color: var(--bg); border-color: var(--ink); }
+  .researchrow { display: flex; align-items: center; gap: .5rem; margin-top: .45rem; font-size: .72rem; color: var(--muted); flex-wrap: wrap; }
+  .researchrow input { flex: 1 1 8rem; min-width: 6rem; font-family: ${MONO_STACK}; font-size: .72rem; background: var(--card); color: var(--ink); border: 1px solid var(--line); border-radius: 6px; padding: .25rem .55rem; }
+  .researchrow input::placeholder { color: var(--muted); }
   .ingestpanel { margin-top: .55rem; display: flex; flex-direction: column; gap: .45rem; }
   .ingestpanel[hidden] { display: none; }
   .ingestpanel textarea { width: 100%; box-sizing: border-box; min-height: 96px; resize: vertical; font-family: ${MONO_STACK}; font-size: .76rem; line-height: 1.45; background: var(--bg); color: var(--ink); border: 1px solid var(--line); border-radius: 6px; padding: .5rem .6rem; }
@@ -1006,6 +1019,8 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
   // (renderLedgerHtml's own ledgerBundleAvailable defaults false there), so
   // this branch is simply never reachable on a CLI-generated page.
   const resolveAnsweredTerm = ${resolveAnsweredTerm.toString()};
+  const createTicker = ${createTicker.toString()};
+  const prefersReducedMotion = ${prefersReducedMotion.toString()};
   const chatForm = el("chatform");
   if (chatForm && typeof tmctLedger !== "undefined" && typeof tmctLedger.createLedgerSession === "function") {
     const log = el("chatlog");
@@ -1177,6 +1192,90 @@ ${ledgerBundleAvailable ? `<script src="./ledger-browser.bundle.js"></script>` :
         });
       });
     }
+
+    // ---- research: a Simple English Wikipedia queue through the SAME dock
+    // session. The engine owns the queue (each turn's result.research is its
+    // snapshot); this dock decides WHEN "research next" is asked, through
+    // the shared viz-ticker verbs, and re-derives the whole ledger after a
+    // step that grounded facts so the new rows can be examined in place —
+    // the same refresh a successful teach performs.
+    const researchTopicEl = el("researchTopic");
+    if (researchTopicEl) {
+      const researchGoBtn = el("researchGo");
+      const researchPlayBtn = el("researchPlay");
+      const researchStatusEl = el("researchStatus");
+      let researchQueue = null; // the engine's latest snapshot, null when no run stands
+
+      function renderResearchControls(tickState) {
+        const st = tickState || researchTicker.getState();
+        researchPlayBtn.hidden = !(researchQueue && !researchQueue.complete);
+        researchPlayBtn.textContent = st.playing ? "pause" : "play";
+        researchPlayBtn.setAttribute("aria-pressed", String(st.playing));
+        researchStatusEl.textContent = !researchQueue ? ""
+          : researchQueue.complete
+            ? 'research "' + researchQueue.topic + '" complete \\u2014 ' + researchQueue.done.length + " topic" + (researchQueue.done.length === 1 ? "" : "s")
+            : researchQueue.done.length + " done \\u00b7 " + researchQueue.pending.length + " queued";
+      }
+
+      // One research turn through the dock — rendered exactly like a typed
+      // line, so the transcript reads as if the visitor asked each search.
+      function researchLine(q) {
+        addLine("u", esc(q));
+        const pending = addLine("a pending", "researching\\u2026");
+        return withLock(async () => {
+          try {
+            const s = await ensureSession();
+            const result = await s.turn(q);
+            const missed = !result.record || Boolean(result.record.miss);
+            pending.className = "a" + (missed ? " miss" : "");
+            pending.innerHTML = esc(result.answer).replace(/\\n/g, "<br>");
+            if (result.research !== undefined) {
+              researchQueue = result.research;
+              renderResearchControls();
+              if (!missed) {
+                const fresh = tmctLedger.computeLedgerDataFromPayload(s.memoryDir.payload, {});
+                applyLedgerData(fresh);
+              }
+            }
+            return result;
+          } catch {
+            pending.className = "a miss";
+            pending.textContent = "Something went wrong with that research step. Try again, or reload the page.";
+            return null;
+          }
+        });
+      }
+
+      const researchTicker = createTicker({
+        onTick: async () => { await researchLine("research next"); },
+        hasNext: () => Boolean(researchQueue && !researchQueue.complete),
+        onRender: renderResearchControls,
+        waitMs: 2400,
+      });
+
+      researchGoBtn.addEventListener("click", () => {
+        const topic = researchTopicEl.value.trim();
+        if (!topic) return;
+        researchTopicEl.value = "";
+        researchLine("research " + topic).then(() => {
+          // A fresh run with topics queued auto-plays, unless the visitor
+          // asked for reduced motion — the play button covers them too.
+          if (researchQueue && !researchQueue.complete && !prefersReducedMotion() && !researchTicker.getState().playing) {
+            researchTicker.play();
+          }
+        });
+      });
+      researchTopicEl.addEventListener("keydown", (e) => {
+        if (e.key === "Enter") { e.preventDefault(); researchGoBtn.click(); }
+      });
+      // pause() directly, not play()'s own toggle: play() declines while a
+      // step is mid-animation, and a pause pressed exactly then must not be
+      // dropped — the in-flight step still settles, then the loop stops.
+      researchPlayBtn.addEventListener("click", () => {
+        if (researchTicker.getState().playing) researchTicker.pause();
+        else researchTicker.play();
+      });
+    }
   } else if (chatForm && typeof tmctMemoryAsk !== "undefined") {
     const memHandle = tmctMemoryAsk.createInMemoryStore();
     memHandle.payload = PAYLOAD;

package/src/services/memory-panel-viz.mjs

@@ -0,0 +1,159 @@
+// memory-panel-viz.mjs — the docked "this session's memory" panel shared by
+// chat.html and ingest.html: both pages seed from the same chat-seed.json
+// bands and want the identical band-count/taught-list/forget-everything
+// chrome, so the rendering lives once here instead of twice.
+//
+// Every export below is pure and `.toString()`-splice safe (no references
+// outside its own parameters), the same discipline chat-page-viz.mjs's own
+// provenanceChipFor/loadProgressLine hold — a page's inline script splices
+// these in as text, so a closure over this module's top-level scope would
+// silently vanish at splice time. Collaborators a caller may want to vary
+// (the band-label lookup, a forget hook) are passed in as parameters, not
+// imported, mirroring provenanceChipFor's own injected `bucketFor`.
+
+/** The human label for one memoryStats() band key — the same band names
+ *  build-chat-seed.mjs/extensions.mjs seed under, plus the two synthetic
+ *  buckets memoryStats mints for anything outside a seed band
+ *  ("taught this session", "other"). An unrecognized key renders as itself
+ *  rather than disappearing, so a future band never goes unlabeled. */
+export function bandLabelFor(key) {
+  const BAND_LABELS = {
+    human: "human persona",
+    "human-medium": "human persona (medium)",
+    "human-large": "human persona (large)",
+    seon: "seon ontology",
+    conceptnet: "ConceptNet",
+    "tier2-aws": "AWS",
+    "tier2-python": "Python",
+    "tier2-java": "Java",
+    "wordnet-xl": "WordNet",
+  };
+  return BAND_LABELS[key] || key;
+}
+
+/** The boot line's own memory summary — every seed band a session actually
+ *  loaded, named with its real count, left to right in the fixed band order;
+ *  a session with nothing seeded says so plainly instead of naming zero
+ *  facts. `bandLabel` is the label lookup to use for each band key (pass
+ *  bandLabelFor, or a page's own override). */
+export function statsSummaryLine(stats, bandLabel) {
+  const BAND_ORDER = [
+    "human", "human-medium", "human-large", "seon", "conceptnet",
+    "tier2-aws", "tier2-python", "tier2-java", "wordnet-xl",
+    "taught this session", "other",
+  ];
+  if (!stats || !stats.total) return "no starter memory; starting empty";
+  const parts = BAND_ORDER.filter((k) => stats.bandCounts[k]).map((k) => stats.bandCounts[k] + " " + bandLabel(k));
+  return parts.length
+    ? "starter memory: " + parts.join(" + ") + " (" + stats.total + " facts total)"
+    : stats.total + " starter facts loaded";
+}
+
+/** Fetch `url` reading the body as a stream, reporting (loadedBytes,
+ *  totalBytes) after every chunk — total is 0 when the response carries no
+ *  Content-Length. Resolves to a Blob of the whole body. Falls back to a
+ *  single-shot blob() read when the runtime has no streaming body reader. */
+export async function fetchWithProgress(url, onProgress) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error("HTTP " + res.status);
+  const total = Number(res.headers.get("content-length")) || 0;
+  if (!res.body || !res.body.getReader) {
+    const blob = await res.blob();
+    onProgress(blob.size, total || blob.size);
+    return blob;
+  }
+  const reader = res.body.getReader();
+  const chunks = [];
+  let loaded = 0;
+  for (;;) {
+    const step = await reader.read();
+    if (step.done) break;
+    chunks.push(step.value);
+    loaded += step.value.byteLength;
+    onProgress(loaded, total);
+  }
+  return new Blob(chunks);
+}
+
+/**
+ * (Re)render the docked "this session's memory" panel into `panelEl` from a
+ * memoryStats() result: a total-facts row, one row per seed band the session
+ * actually holds, then the last 8 taught facts (most recent first), most
+ * recently taught last shown first. Clears and rebuilds `panelEl`'s children
+ * every call — cheap at this row count, and it means a stale row can never
+ * survive a re-render.
+ *
+ *   opts.bandLabel     required — the band-key -> label lookup (bandLabelFor,
+ *                      or a page's own override).
+ *   opts.taughtHint    the empty-state copy under "taught this session" when
+ *                      nothing has been taught yet. Defaults to the plain
+ *                      teach-a-fact prompt every page can show verbatim.
+ *   opts.onForget      when set, renders a "forget everything" button wired
+ *                      to this callback; omitted, no button renders (a page
+ *                      with no persistence to forget).
+ *   opts.persistNote   when set (and onForget is set), a short note under the
+ *                      forget button naming where the state lives.
+ */
+export function renderStatsPanelInto(panelEl, stats, opts) {
+  const { bandLabel, taughtHint, onForget = null, persistNote = null } = opts;
+  const BAND_ORDER = [
+    "human", "human-medium", "human-large", "seon", "conceptnet",
+    "tier2-aws", "tier2-python", "tier2-java", "wordnet-xl",
+    "taught this session", "other",
+  ];
+  function bandRow(label, count) {
+    const row = document.createElement("p");
+    row.className = "band-row";
+    const l = document.createElement("span");
+    l.textContent = label;
+    const c = document.createElement("span");
+    c.className = "band-count";
+    c.textContent = String(count);
+    row.appendChild(l);
+    row.appendChild(c);
+    return row;
+  }
+
+  panelEl.textContent = "";
+  panelEl.appendChild(Object.assign(document.createElement("h2"), { textContent: "this session's memory" }));
+  panelEl.appendChild(bandRow("total facts", stats.total));
+  for (const key of BAND_ORDER) {
+    if (stats.bandCounts[key]) panelEl.appendChild(bandRow(bandLabel(key), stats.bandCounts[key]));
+  }
+
+  panelEl.appendChild(Object.assign(document.createElement("h2"), { textContent: "taught this session" }));
+  if (!stats.taught.length) {
+    const empty = document.createElement("p");
+    empty.className = "empty";
+    empty.textContent = taughtHint || 'nothing yet — teach it something ("a dog is a kind of animal") and it lands here, with its source.';
+    panelEl.appendChild(empty);
+  } else {
+    for (const fact of stats.taught.slice(-8).reverse()) {
+      const item = document.createElement("p");
+      item.className = "taught-item";
+      item.appendChild(document.createTextNode(fact.subject + " " + fact.predicate + " " + fact.object));
+      const tag = document.createElement("span");
+      tag.className = "taught-tag";
+      tag.textContent = fact.tag;
+      item.appendChild(tag);
+      panelEl.appendChild(item);
+    }
+  }
+
+  if (onForget) {
+    const forget = document.createElement("button");
+    forget.type = "button";
+    forget.id = "forgetEverything";
+    forget.className = "forget-btn";
+    forget.textContent = "forget everything";
+    forget.title = "clear what this device has saved and restart from the fresh seed";
+    forget.addEventListener("click", onForget);
+    panelEl.appendChild(forget);
+    if (persistNote) {
+      const note = document.createElement("p");
+      note.className = "persist-note";
+      note.textContent = persistNote;
+      panelEl.appendChild(note);
+    }
+  }
+}

package/src/services/research.mjs

@@ -0,0 +1,266 @@
+// research.mjs — the "research <topic>" lane: a Simple English Wikipedia
+// queue that grounds one topic per turn. Depth 0 is the requested topic
+// (opensearch + summary, ingested as graph facts); the topics its lead
+// section links to queue at depth 1, capped by the request's own
+// "limit N" or the configured default. Every completed search reports back
+// as its own chat turn — the queue advances one step per "research next"
+// (or a bare "next" while nothing else owns it), which is exactly what the
+// web pages' auto-play button submits.
+//
+// No node builtins — this module ships in the browser bundles unchanged.
+// The provider (network) and the ingest step (memory writes) are both
+// injected by the caller (chat.mjs), so this file owns only the queue
+// mechanics, the request grammar and the reported prose.
+//
+// Consent posture: an explicit "research <topic>" request IS the network
+// consent for its own fetches. Unlike the clean-miss rescue (which fires on
+// an ordinary question and therefore hides behind /wiki on), nobody types
+// "research owls" without meaning "go and look owls up" — the reply names
+// the source it reached either way. The /wiki toggle keeps governing every
+// other lane unchanged.
+//
+// The abstention invariant holds throughout: a topic whose fetch or
+// grounding fails reports the miss plainly, stores nothing, and the queue
+// moves on. No fact is ever fabricated to keep a research run tidy.
+
+import { normFactTerm } from "../domain/hash.mjs";
+import { loadLexicon, lookupNoun } from "../domain/grammar/lexicon.mjs";
+
+/** The search key a topic folds to: normFactTerm, then the lexicon lemma
+ *  when the noun is known ("owls" → "owl") — the same fold the live
+ *  clean-miss gate applies, and what keeps the provider's topic-drift guard
+ *  happy with an inflected request. An unknown word keys on its own folded
+ *  form (a topic the lexicon has never met is a fine thing to research). */
+export function researchTopicKey(topic, lexicon = null) {
+  const t = normFactTerm(topic);
+  if (!t) return "";
+  try {
+    const lex = lexicon ?? loadLexicon();
+    const entry = lookupNoun(lex, t);
+    if (entry) return normFactTerm(entry.lemma) || t;
+  } catch { /* lexicon unavailable — the folded form still works */ }
+  return t;
+}
+
+/** The most linked topics any request or config may queue at depth 1 —
+ *  the fair-use cap on a research run's total round trips. */
+export const RESEARCH_FANOUT_MAX = 12;
+
+export const RESEARCH_DEFAULTS = Object.freeze({
+  fanoutLimit: 5,
+  depthLimit: 1,
+  minIntervalMs: 2000,
+});
+
+const clampInt = (n, lo, hi) => Math.min(hi, Math.max(lo, Math.floor(n)));
+
+/** tmct.toml's `[research]` table → the lane's effective knobs, shipped
+ *  defaults filling every unset key (the same posture resolveGameConfig
+ *  takes with `[games.*]`). `fanout_limit` caps at RESEARCH_FANOUT_MAX;
+ *  `depth_limit` is 0 (no fan-out) or 1 (the depths engineered today);
+ *  `min_interval_ms` may only RAISE the polite floor between round trips,
+ *  never lower it. */
+export function resolveResearchConfig(toml = null) {
+  const raw = toml?.research || {};
+  const cfg = { ...RESEARCH_DEFAULTS };
+  const fanout = Number(raw.fanout_limit);
+  if (Number.isFinite(fanout)) cfg.fanoutLimit = clampInt(fanout, 0, RESEARCH_FANOUT_MAX);
+  const depth = Number(raw.depth_limit);
+  if (Number.isFinite(depth)) cfg.depthLimit = clampInt(depth, 0, 1);
+  const interval = Number(raw.min_interval_ms);
+  if (Number.isFinite(interval)) cfg.minIntervalMs = Math.max(RESEARCH_DEFAULTS.minIntervalMs, interval);
+  return cfg;
+}
+
+// The verbs that step/inspect/end a run, checked before the start shape so
+// "research next" never parses as a topic called "next".
+const RESEARCH_NEXT_RE = /^research[,:]?\s+(?:next|continue|more)\s*[.!?]*$/i;
+const RESEARCH_STATUS_RE = /^research[,:]?\s+status\s*[.!?]*$/i;
+const RESEARCH_STOP_RE = /^research[,:]?\s+(?:stop|cancel|quit|end)\s*[.!?]*$/i;
+const RESEARCH_START_RE = /^research[,:]?\s+(.+?)(?:[,;]?\s+(?:with\s+)?limit\s+(\d{1,3}))?\s*[.!?]*$/i;
+// A bare continuation word steps the queue too, but only when a run is
+// actually pending and no plan lane owns the word — parseResearchRequest
+// reports it as its own kind so the caller can apply that gate.
+const BARE_NEXT_RE = /^(?:next|continue|carry on|keep going)\s*[.!?]*$/i;
+
+/** The research request a line carries, or null. Kinds: start {topic,
+ *  limit?}, next, bareNext, status, stop. The topic keeps the user's own
+ *  words minus a leading article and any wrapping quotes; limit is only
+ *  present when the request named one. */
+export function parseResearchRequest(line) {
+  const q = String(line || "").trim();
+  if (!q) return null;
+  if (BARE_NEXT_RE.test(q)) return { kind: "bareNext" };
+  if (RESEARCH_NEXT_RE.test(q)) return { kind: "next" };
+  if (RESEARCH_STATUS_RE.test(q)) return { kind: "status" };
+  if (RESEARCH_STOP_RE.test(q)) return { kind: "stop" };
+  const m = q.match(RESEARCH_START_RE);
+  if (!m) return null;
+  const topic = m[1].trim()
+    .replace(/^["'‘’“”]+|["'‘’“”]+$/g, "")
+    .replace(/^(?:an?|the)\s+/i, "")
+    .trim();
+  if (!topic) return null;
+  const out = { kind: "start", topic };
+  if (m[2] !== undefined) out.limit = Number(m[2]);
+  return out;
+}
+
+/** The provenance tag every fact a research run stores carries:
+ *  `research:<topic>@<depth>` — memory/trust.mjs parses it back to the
+ *  referenceLive kind, so live-fetched research content scores exactly like
+ *  any other live Wikipedia load, below the curated packs. */
+export function researchProvenanceTag(topicKey, depth) {
+  return `research:${topicKey}@${depth}`;
+}
+
+/** The cited per-topic report — the same title/licence/revision-pinned-URL
+ *  discipline renderLiveReferenceAnswer holds, naming this lane's source. */
+export function renderResearchAnswer(term, article) {
+  return `${term} — ${article.summary} (source: research article "${article.title}", `
+    + `Simple English Wikipedia, CC BY-SA 4.0 — ${article.url}?oldid=${article.revid})`;
+}
+
+/** The queue as plain data for a UI: pending titles, per-topic fact counts,
+ *  skips, and whether the run is complete. Null for no run. */
+export function researchSnapshot(state) {
+  if (!state) return null;
+  return {
+    topic: state.topic,
+    limit: state.limit,
+    pending: [...state.pending],
+    done: state.done.map((d) => ({ title: d.title, facts: d.facts, depth: d.depth })),
+    skipped: [...state.skipped],
+    complete: state.pending.length === 0,
+  };
+}
+
+const totalFacts = (state) => state.done.reduce((sum, d) => sum + d.facts, 0);
+
+function progressLine(state) {
+  const done = `${state.done.length} topic${state.done.length === 1 ? "" : "s"} grounded, ${totalFacts(state)} fact${totalFacts(state) === 1 ? "" : "s"} stored`;
+  const skipped = state.skipped.length ? `, ${state.skipped.length} skipped` : "";
+  if (!state.pending.length) return `research on "${state.topic}" is complete — ${done}${skipped}.`;
+  return `${done}${skipped}; ${state.pending.length} linked topic${state.pending.length === 1 ? "" : "s"} still queued — "research next" fetches the next one.`;
+}
+
+async function startRun({ topic, limit }, { holder, provider, ingest, config, notify, lexicon }) {
+  const key = researchTopicKey(topic, lexicon);
+  if (!key) {
+    holder.state = null;
+    return { text: `I can't make a search key out of "${topic}".`, miss: true };
+  }
+  try { if (typeof notify === "function") notify(key); } catch { /* notify-only */ }
+  let article = null;
+  try { article = await provider.lookup(key); } catch { article = null; }
+  if (!article) {
+    holder.state = null;
+    return {
+      text: `I couldn't ground "${topic}" from Simple English Wikipedia just now — no matching article, or the network didn't answer. Nothing was stored.`,
+      miss: true,
+    };
+  }
+  let facts = 0;
+  try { facts = await ingest(key, article, researchProvenanceTag(key, 0)); } catch { facts = 0; }
+  const fanout = clampInt(
+    limit !== undefined && Number.isFinite(limit) ? limit : config.fanoutLimit,
+    0,
+    RESEARCH_FANOUT_MAX,
+  );
+  let pending = [];
+  if (fanout > 0 && config.depthLimit > 0 && typeof provider.linkedTitles === "function") {
+    let linked = null;
+    try { linked = await provider.linkedTitles(article.title, { limit: fanout + 2 }); } catch { linked = null; }
+    const seen = new Set([key, normFactTerm(article.title)]);
+    for (const title of linked || []) {
+      const folded = normFactTerm(title);
+      if (!folded || seen.has(folded)) continue;
+      seen.add(folded);
+      pending.push(title);
+      if (pending.length >= fanout) break;
+    }
+  }
+  holder.state = {
+    topic, key, title: article.title, limit: fanout,
+    pending, done: [{ title: article.title, facts, depth: 0 }], skipped: [],
+  };
+  const queueLine = pending.length
+    ? `queued ${pending.length} linked topic${pending.length === 1 ? "" : "s"}: ${pending.join(", ")} — "research next" fetches the next one (the page's play button does this for you).`
+    : `no linked topics queued — research on "${topic}" is complete.`;
+  return {
+    text: `${renderResearchAnswer(key, article)}\nstored ${facts} fact${facts === 1 ? "" : "s"} from "${article.title}". ${queueLine}`,
+    miss: false,
+  };
+}
+
+async function stepRun({ holder, provider, ingest, notify }) {
+  const state = holder.state;
+  const title = state.pending[0];
+  state.pending = state.pending.slice(1);
+  try { if (typeof notify === "function") notify(title); } catch { /* notify-only */ }
+  let article = null;
+  try { article = await (provider.pageByTitle ? provider.pageByTitle(title) : provider.lookup(normFactTerm(title))); } catch { article = null; }
+  if (!article) {
+    state.skipped = [...state.skipped, title];
+    return {
+      text: `I couldn't fetch "${title}" from Simple English Wikipedia — skipped, nothing stored. ${progressLine(state)}`,
+      miss: true,
+    };
+  }
+  const key = normFactTerm(article.title) || normFactTerm(title);
+  let facts = 0;
+  try { facts = await ingest(key, article, researchProvenanceTag(state.key, 1)); } catch { facts = 0; }
+  state.done = [...state.done, { title: article.title, facts, depth: 1 }];
+  return {
+    text: `${renderResearchAnswer(key, article)}\nstored ${facts} fact${facts === 1 ? "" : "s"} from "${article.title}". ${progressLine(state)}`,
+    miss: false,
+  };
+}
+
+/**
+ * The whole lane behind one call — chat.mjs's dispatch stays one thin block.
+ * Returns null when the line carries no research request (or carries a bare
+ * "next" this lane must not claim), else { text, miss, note, goal } with
+ * `holder.state` updated in place; the caller snapshots it for the UI and
+ * threads it to the next turn.
+ *
+ * `ctx`: { holder, provider, ingest(key, article, tag) -> stored count,
+ * config (resolveResearchConfig's shape), memoryDir, planActive,
+ * pagerActive, notify, lexicon }.
+ */
+export async function researchTurn(line, ctx) {
+  const req = parseResearchRequest(line);
+  if (!req) return null;
+  const { holder, memoryDir, planActive, pagerActive } = ctx;
+  const pendingRun = Boolean(holder.state && holder.state.pending.length);
+  // A bare "next" belongs to an active plan first, then to paging — this
+  // lane only claims it when a research queue is the one thing running.
+  if (req.kind === "bareNext" && (!pendingRun || planActive || pagerActive)) return null;
+  const goal = "research a topic on Simple English Wikipedia and remember what it grounds";
+  const wrap = (r, note) => ({ ...r, goal, note });
+  if (req.kind === "status") {
+    if (!holder.state) return wrap({ text: 'no research is running — "research <topic>" starts one.', miss: true }, "RESEARCH — status with no run standing");
+    return wrap({ text: progressLine(holder.state), miss: false }, "RESEARCH — queue status read-out");
+  }
+  if (req.kind === "stop") {
+    if (!holder.state) return wrap({ text: 'no research is running — "research <topic>" starts one.', miss: true }, "RESEARCH — stop with no run standing");
+    const state = holder.state;
+    holder.state = null;
+    const dropped = state.pending.length;
+    return wrap({
+      text: `stopped research on "${state.topic}" — ${state.done.length} topic${state.done.length === 1 ? "" : "s"} grounded, ${totalFacts(state)} fact${totalFacts(state) === 1 ? "" : "s"} stored${dropped ? `, ${dropped} queued topic${dropped === 1 ? "" : "s"} dropped` : ""}.`,
+      miss: false,
+    }, "RESEARCH — run stopped, queue dropped");
+  }
+  if (!memoryDir) {
+    return wrap({ text: "research needs a memory store to write into, and this session has none.", miss: true }, "RESEARCH — declined, no memory store");
+  }
+  if (req.kind === "next" || req.kind === "bareNext") {
+    if (!pendingRun) {
+      if (holder.state) return wrap({ text: progressLine(holder.state), miss: false }, "RESEARCH — next on a completed run reads the summary");
+      return wrap({ text: 'no research is running — "research <topic>" starts one.', miss: true }, "RESEARCH — next with no run standing");
+    }
+    return wrap(await stepRun(ctx), "RESEARCH — one queued topic fetched and grounded");
+  }
+  return wrap(await startRun(req, ctx), "RESEARCH — depth-0 topic fetched, linked topics queued");
+}

package/src/services/sentences.mjs

@@ -43,3 +43,22 @@ export function splitSentencesPreservingPaths(text) {
   }
   return out;
 }
+
+/** Bracketed reference residue an encyclopedia paragraph leaves in prose:
+ *  numeric footnote markers ([3], [12]), single-letter notes ([a]), and the
+ *  named ones ([note 4], [citation needed], [source?], [page 2]). Removed
+ *  case-insensitively so the sentence downstream reads as plain text, with the
+ *  gap tidied so "period.[3] Sales" becomes "period. Sales", not
+ *  "period.  Sales". A file path never carries a bracket, so a dotted module
+ *  identifier ("src/core/store.mjs") is left whole — only bracketed spans are
+ *  touched. Deliberately NOT wired into the shared splitter; a caller that
+ *  wants clean prose applies it before or after splitting. */
+export function stripCitationResidue(text) {
+  return String(text ?? "")
+    .replace(/\[\s*\d+\s*\]/g, "")
+    .replace(/\[\s*[a-z]\s*\]/gi, "")
+    .replace(/\[\s*(?:note|citation|ref|source|page|pp?)\b[^\]]*\]/gi, "")
+    .replace(/ +([.,;:!?])/g, "$1")
+    .replace(/ {2,}/g, " ")
+    .trim();
+}

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

@@ -304,7 +304,7 @@ ${THEME_TOKENS_CSS}
      split plus the gap approximates that pair of fractions without them
      needing to sum to a full width. */
   .stage { display: grid; grid-template-columns: minmax(0, 8fr) minmax(280px, 3fr); gap: 1.2rem; align-items: start; }
-  @media (max-width: 760px) { .stage { grid-template-columns: 1fr; } }
+  @media (max-width: 760px) { .stage { grid-template-columns: minmax(0, 1fr); } }
   /* A dusty window corner: a soft light glow near the top-left (WEB_HOME
      already sits near that corner — spider-fly-world.mjs's own header
      comment), and a faint diagonal weave standing in for dust/silk caught
@@ -349,7 +349,18 @@ ${THEME_TOKENS_CSS}
   /* Both the controls strip above the board and the tuning strip below it
      match the board's own width (not the wider stage-left column they sit
      in), so all three line up as one visual stack. */
-  .tuning, .controls-panel { width: ${BOARD_PX}px; max-width: 100%; margin: 0 auto; box-sizing: border-box; }
+  .tuning, .controls-panel, .head-inner { width: ${BOARD_PX}px; max-width: 100%; margin: 0 auto; box-sizing: border-box; }
+  /* the eyebrow+h1 sit in their own board-width column (.head-inner), inside
+     a .page-head row that mirrors the real board's own 8fr/3fr split below
+     it — the second, empty column just holds that split in place so the
+     first column's own left edge lines up with the board's, instead of the
+     wider page margin. min-width: 0 matches .stage-left's own override:
+     without it, a grid item's default automatic minimum size is its
+     content's own max-content width, and at the phone-width single-column
+     override below the fixed-width child would force the track (and the
+     page) wider than the viewport instead of actually shrinking. */
+  .page-head { margin-bottom: 0; }
+  .head-inner { min-width: 0; }
   .hud h2, .chat h2, .tuning h2 {
     font-family: ${MONO_STACK}; font-size: .68rem; letter-spacing: .1em; text-transform: uppercase; font-weight: 600;
     margin: -.6rem -.75rem .5rem; padding: .42rem .75rem;
@@ -465,13 +476,18 @@ ${THEME_TOKENS_CSS}
   body.preview main { padding: 0; max-width: none; }
   body.preview .stage, body.preview .stage-left { display: block; }
   body.preview .board-frame { margin: 0; }
-  body.preview .eyebrow, body.preview h1 { display: none; }
+  body.preview .page-head { display: none; }
 </style>
 </head>
 <body>
 <main>
-  <div class="eyebrow">tmct &middot; spider and fly</div>
-  <h1>Multiple competing planning agents</h1>
+  <div class="stage page-head">
+    <div class="head-inner">
+      <div class="eyebrow">tmct &middot; spider and fly</div>
+      <h1>Multiple competing planning agents</h1>
+    </div>
+    <div></div>
+  </div>
   <div class="stage">
     <div class="stage-left">
     <div class="controls-panel" id="controlsPanel" aria-label="game controls">