@polycode-projects/the-mechanical-code-talker 2.11.11 → 2.11.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.11.11",
+  "version": "2.11.12",
   "private": false,
   "type": "module",
   "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",

package/src/adapters/toml-config.mjs

@@ -129,8 +129,9 @@ export async function normalizeConfig(raw, { configDir } = {}) {
 
   // Research-lane knobs (src/services/research.mjs): sparse PASS-THROUGH,
   // same discipline as [games.*] — the raw `[research]` table
-  // (fanout_limit / depth_limit / min_interval_ms, snake_case) rides through
-  // unmodified; clamping and default-filling is resolveResearchConfig's job.
+  // (fanout_limit / max_depth / max_topics / min_interval_ms, snake_case)
+  // rides through unmodified; clamping and default-filling is
+  // resolveResearchConfig's job.
   if (src.research !== undefined) cfg.research = src.research;
 
   const idx = src.index || {};

package/src/domain/grammar/ace.mjs

@@ -528,6 +528,15 @@ export function parseAce(sentence, lexicon = loadLexicon()) {
 const IMPERATIVE_VERBS = new Set(["go", "take", "drop", "open", "unlock", "close", "give", "look", "talk", "examine"]);
 const IMPERATIVE_DIRECTIONS = new Set(["north", "south", "east", "west", "up", "down"]);
 
+// The object pronouns an imperative object slot may carry ("examine it", "take
+// them", "talk to him"). This parser only MARKS such a slot with the bare
+// pronoun as its term — the antecedent lives in the running world, not the
+// sentence, so binding it to a concrete object is the adventure lane's job (it
+// alone holds the session's FOCUS). Kept out of resolveNP's lexicon gate on
+// purpose: a pronoun is never a declared noun, so without this it rides out as
+// residue and mis-declines as an unknown word.
+export const OBJECT_PRONOUNS = new Set(["it", "them", "him", "her"]);
+
 const VERB_SYNONYMS = new Map([
   ["pick up", "take"], ["pick", "take"], ["grab", "take"],
   ["put down", "drop"], ["set down", "drop"], ["leave", "drop"],
@@ -603,8 +612,14 @@ function resolveImperativeVerb(toks) {
   return { ...retried, corrected: { from: first, to: fixedFirst } };
 }
 
-/** Resolve one imperative object phrase to its bare lexicon term. */
+/** Resolve one imperative object phrase to its bare lexicon term. A lone
+ *  object pronoun ("it", "them", "him", "her") rides through as its own term
+ *  for the lane to bind against the session focus — never a lexicon lookup,
+ *  never residue. */
 function imperativeNP(lexicon, tokens) {
+  if (tokens.length === 1 && OBJECT_PRONOUNS.has(tokens[0].toLowerCase())) {
+    return { term: tokens[0].toLowerCase(), unknown: [] };
+  }
   const np = resolveNP(lexicon, tokens);
   if (np.term == null) return { term: null, unknown: np.unknown };
   return { term: local(lexicon, np.term), unknown: [] };

package/src/services/adventure-viz.mjs

@@ -428,6 +428,20 @@ export function pillsForRoom(rows, state, here) {
   return roomAffordances(rows, state, here);
 }
 
+/** The chat input's grounding placeholder, built from an affordance list: the
+ *  first couple of OBJECT commands (examine/take/open/unlock/talk to <thing>)
+ *  spelled with the room's real props, so the empty input teaches the grounded
+ *  noun form ("examine lamp, take letter…") rather than a bare pronoun the
+ *  player has no antecedent for yet. `fallback` stands in when the list holds
+ *  no object command (a room with only exits, or a just-emptied object dock).
+ *  Pure and `.toString()`-splice-safe — the page splices it in and drives both
+ *  input docks off it every redraw. */
+export function groundedPlaceholder(actions, fallback) {
+  const objectActions = (actions || []).filter((a) => /^(?:examine|take|open|unlock|talk to) /.test(a));
+  if (!objectActions.length) return fallback;
+  return objectActions.slice(0, 2).join(", ") + "…";
+}
+
 /** Edit mode's cursor-driven suggestion pills for one typed `term`: the
  *  lateral SKOS neighbourhood (`relatedForTerm`'s own synonyms/related
  *  concepts) plus the vertical rdfs:subClassOf ancestor chain
@@ -929,7 +943,7 @@ ${THEME_TOKENS_CSS}
       <div class="docklog" id="objDockLog" aria-live="polite"></div>
       <form class="chatask" id="objForm">
         <span class="prompt mono">tmct&gt;</span>
-        <input id="objInput" type="text" placeholder="examine it, take it&hellip;" aria-label="Type a command for this object">
+        <input id="objInput" type="text" placeholder="examine lamp, take key&hellip;" aria-label="Type a command for this object">
       </form>
     </div>
   </div>
@@ -975,6 +989,7 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   const carriedItems = ${carriedItems.toString()};
   const visitedRoomGraph = ${visitedRoomGraph.toString()};
   const allRoomIds = ${allRoomIds.toString()};
+  const groundedPlaceholder = ${groundedPlaceholder.toString()};
   const spriteAncestryRows = ${spriteAncestryRows.toString()};
   const factsForSubject = ${factsForSubject.toString()};
   const renderWorldEditorText = ${renderWorldEditorText.toString()};
@@ -1260,6 +1275,9 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
     if (!lastSnapshot || !objLightboxSubject) { objPillsEl.innerHTML = ""; return; }
     const actions = objectPillsFor(lastSnapshot.rows, lastSnapshot.state, lastSnapshot.here, objLightboxSubject);
     objPillsEl.innerHTML = actions.map((a) => '<button type="button" class="pill">' + esc(a) + "</button>").join("");
+    // Grounded to the open object itself ("take lamp…"), so the dock teaches
+    // the noun form even though a bare pronoun now binds here too.
+    objInputEl.placeholder = groundedPlaceholder(actions, "examine " + objLightboxSubject);
   }
   // A dock turn: paused, echoed into the main transcript AND the dock, run on
   // the one session, then the main page and the lightbox both redraw off the
@@ -1369,6 +1387,10 @@ ${engineBundleJs ? `<script>\n${embedScriptText(engineBundleJs)}\n</script>` : `
   function renderPills(rows, state, here) {
     const actions = pillsFor(rows, state, here);
     pillsEl.innerHTML = actions.map((a) => '<button type="button" class="pill">' + esc(a) + "</button>").join("");
+    // The empty input teaches the grounded noun form off the same affordance
+    // list the pills read — real props from THIS room, so a first-time player
+    // types "examine lamp", not a pronoun with nothing to bind to yet.
+    chatqEl.placeholder = groundedPlaceholder(actions, "go north");
   }
   pillsEl.addEventListener("click", (e) => {
     const btn = e.target.closest(".pill");

package/src/services/adventure.mjs

@@ -9,7 +9,7 @@
 // share the slot.
 
 import { worldProvenanceTag } from "../domain/worlds-pack.mjs";
-import { parseImperative } from "../domain/grammar/ace.mjs";
+import { parseImperative, OBJECT_PRONOUNS } from "../domain/grammar/ace.mjs";
 import { createCompletionsGraphAdapter } from "../domain/completions/graph-adapter.mjs";
 import { actionFamilies } from "../domain/router/taught.mjs";
 import { compileDomain, precondHolds, roleBinding } from "../domain/domain.mjs";
@@ -1224,6 +1224,63 @@ function renderedImperativeCommand(cmd) {
   return parts.join(" ");
 }
 
+// ---- pronoun binding: the session focus ---------------------------------------
+//
+// A world command may name its object with a pronoun ("examine it", "take
+// them", "talk to him") instead of a noun. The antecedent is not in the
+// sentence — it's the last thing the player successfully acted on this
+// session, the FOCUS — so the parser leaves the pronoun bare (ace.mjs's
+// OBJECT_PRONOUNS) and the lane binds it here, through ONE seam that every
+// object-taking verb passes on its way to runWorldCommand. With no focus
+// standing, a pronoun gets an honest reference nudge, never the vocabulary
+// decline (a pronoun is a reference, not an unknown word).
+
+const PRONOUN_SLOTS = ["object", "indirectObject", "instrument"];
+
+const commandHasPronoun = (cmd) => PRONOUN_SLOTS.some((s) => cmd[s] && OBJECT_PRONOUNS.has(cmd[s]));
+
+/** A pronoun command with no focus standing: the reference nudge, embedding a
+ *  real, actionable object from the current room when one is on show (else a
+ *  static example). Never the "I don't know the word" line — the vocabulary
+ *  misdiagnosis is unreachable for a pronoun. */
+async function noFocusPronounNudge(pronoun, { memoryDir }) {
+  let example = null;
+  try {
+    const rows = readFactRows(await loadMemory(memoryDir));
+    const state = foldWorldState(worldActionRows(rows));
+    const here = state.placements.get("player")?.object ?? null;
+    if (here) {
+      for (const action of roomAffordances(rows, state, here)) {
+        const m = action.match(/^(?:examine|take|open|unlock|talk to) (.+)$/);
+        if (m) { example = m[1]; break; }
+      }
+    }
+  } catch { /* no probe available — the static example carries the nudge */ }
+  const eg = example ?? "lamp";
+  return answer(
+    `I'm not sure what "${pronoun}" refers to yet — name the thing, e.g. "examine ${eg}".`,
+    `ADVENTURE — pronoun "${pronoun}" arrived with no focus standing; asked which thing it means, never the vocabulary decline`,
+    { miss: true },
+  );
+}
+
+/** Bind any pronoun object/indirect/instrument slot to the session focus.
+ *  Returns `{ cmd }` with the pronouns rewritten to the focus term, or `{
+ *  nudge }` (the reference nudge) when a pronoun stands but no focus does. A
+ *  command with no pronoun passes straight through untouched. */
+async function bindPronouns(cmd, { focus, memoryDir }) {
+  if (!commandHasPronoun(cmd)) return { cmd };
+  if (!focus) {
+    const pronoun = PRONOUN_SLOTS.map((s) => cmd[s]).find((v) => v && OBJECT_PRONOUNS.has(v));
+    return { nudge: await noFocusPronounNudge(pronoun, { memoryDir }) };
+  }
+  const bound = { ...cmd };
+  for (const s of PRONOUN_SLOTS) {
+    if (bound[s] && OBJECT_PRONOUNS.has(bound[s])) bound[s] = focus;
+  }
+  return { cmd: bound };
+}
+
 // ---- the lane ----------------------------------------------------------------
 
 /**
@@ -1292,9 +1349,18 @@ export async function adventureTurn(line, { planHolder, memoryDir, sessionId = "
     };
   }
   if (INVENTORY_RE.test(line)) return inventoryAnswer({ memoryDir, graph });
-  const cmd = parseImperative(line, lexicon ?? undefined);
-  if (cmd) {
+  const parsed = parseImperative(line, lexicon ?? undefined);
+  if (parsed) {
+    const bound = await bindPronouns(parsed, { focus: adventure.focus, memoryDir });
+    if (bound.nudge) return bound.nudge;
+    const cmd = bound.cmd;
     const result = await runWorldCommand(cmd, { world: adventure.world, memoryDir, env, graph, cache });
+    // The object a command SUCCESSFULLY named becomes the focus a later
+    // pronoun binds to — so "look lamp" then "examine it" reads the lamp, and
+    // "talk to housekeeper" makes "him"/"her" the housekeeper. A miss leaves
+    // the standing focus untouched; a bare room look or a move carries no
+    // object and so never disturbs it.
+    if (!result.miss && cmd.object) adventure.focus = cmd.object;
     if (!cmd.corrected?.length) return result;
     // A fuzzy-repaired verb or direction still executes normally, but the
     // response says what it read the line as, so a genuine miss is never

package/src/services/chat.mjs

@@ -5974,7 +5974,7 @@ export async function helpText() {
     ["/ingest <path>", "read a local text file and store every fact the recognizer grounds from it (same recognizer as `tmct extract`)"],
     ["/narrate on|off", "verbose developer/debug mode: decision points, matched pattern, results+sources, goal per turn"],
     ["/wiki on|off|supplement|always", "live Wikipedia (default off): on tries en.wikipedia.org when I can't answer (network), cited; supplement also adds a read-out under every grounded vocabulary answer; always widens that to every grounded answer"],
-    ["research <topic> [limit N]", "fetch the topic from Simple English Wikipedia (the explicit ask is the network consent), store what it grounds, and queue its linked topics — \"research next\" steps the queue; also status/stop"],
+    ["research <topic> [limit N] [depth D]", "fetch the topic from Simple English Wikipedia (the explicit ask is the network consent), store what it grounds, and queue its linked topics — \"research next\" steps the queue; also status/stop. limit N caps the links queued per topic, depth D how many hops the queue follows (1 by default); a run also stops at its total node budget"],
     ["/help", "this list"],
     ["/exit", "leave the session (also Ctrl+C / Ctrl+D)"],
   ];
@@ -14540,10 +14540,12 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
     }
   }
 
-  // RESEARCH — "research <topic>[, limit N]" runs a Simple English Wikipedia
-  // queue through the same ingest path a live-Wikipedia rescue uses: depth 0
-  // now, the lead section's linked topics queued for "research next" (which
-  // the web pages' auto-play button submits turn by turn). The explicit
+  // RESEARCH — "research <topic>[, limit N][, depth D]" runs a Simple English
+  // Wikipedia queue through the same ingest path a live-Wikipedia rescue uses:
+  // depth 0 now, the lead section's linked topics queued for "research next"
+  // (which the web pages' auto-play button submits turn by turn), and each of
+  // those fanning out again while the run's depth knob allows, up to its total
+  // node budget. The explicit
   // request is the network consent for its own fetches — unlike the
   // clean-miss rescue, which fires on an ordinary question and so stays
   // behind /wiki on. Queue state threads turn-to-turn as researchState, the

package/src/services/research-viz.mjs

@@ -128,6 +128,9 @@ ${THEME_TOKENS_CSS}
   .card .note { font-family: ${MONO_STACK}; font-size: .68rem; color: var(--muted); min-height: 1rem; }
   .optionToggle { display: inline-flex; align-items: center; gap: .35rem; font-family: ${MONO_STACK}; font-size: .68rem; color: var(--muted); cursor: pointer; }
   .optionToggle input { margin: 0; accent-color: var(--corpus); }
+  .knobs { display: flex; gap: .9rem; align-items: center; flex-wrap: wrap; }
+  .knob { display: inline-flex; align-items: center; gap: .4rem; font-family: ${MONO_STACK}; font-size: .68rem; color: var(--muted); }
+  .knob input[type="number"] { width: 3.4rem; font-family: ${MONO_STACK}; font-size: .74rem; background: var(--card); color: var(--ink); border: 1px solid var(--line); border-radius: 6px; padding: .25rem .35rem; text-align: right; }
 
   /* highlights + ask, two columns */
   .cols { display: grid; grid-template-columns: 1fr 1fr; gap: 1.4rem; align-items: start; }
@@ -197,6 +200,14 @@ ${THEME_TOKENS_CSS}
           <button type="button" class="btn" id="researchNext" hidden>research next</button>
           <button type="button" class="btn" id="researchPlay" aria-pressed="false" hidden>play</button>
         </div>
+        <div class="knobs">
+          <label class="knob" title="How many topics one research run may fetch and store in total (the first topic counts as one). A deep run stops fetching once it reaches this budget.">
+            max nodes <input id="researchNodes" type="number" min="1" max="50" step="1" value="12" inputmode="numeric" aria-label="Maximum response nodes">
+          </label>
+          <label class="knob" title="How deep the link fan-out follows: depth 1 is the topic's own lead links, depth 2 those topics' links, and so on. Applies to the next run you start.">
+            max depth <input id="researchDepth" type="number" min="1" max="3" step="1" value="1" inputmode="numeric" aria-label="Maximum node depth">
+          </label>
+        </div>
         <p class="note" id="researchNote"></p>
       </div>
       <div class="card">
@@ -593,15 +604,31 @@ ${THEME_TOKENS_CSS}
     el("researchPlay").setAttribute("aria-pressed", String(state.playing));
     const note = el("researchNote");
     if (!researchQueue) { /* leave whatever the last turn's note said */ }
-    else if (researchQueue.complete) {
-      note.textContent = 'research "' + researchQueue.topic + '" complete — '
-        + researchQueue.done.length + " topic" + (researchQueue.done.length === 1 ? "" : "s") + " grounded.";
-    } else {
-      note.textContent = 'research "' + researchQueue.topic + '": '
-        + researchQueue.done.length + " done · " + researchQueue.pending.length + " queued.";
+    else {
+      const depth = researchQueue.maxDepth || 1;
+      const budget = researchQueue.maxTopics || 0;
+      const knobs = " (depth " + depth + (budget ? ", budget " + budget : "") + ")";
+      const capped = researchQueue.nodeCapReached ? " — node budget reached" : "";
+      if (researchQueue.complete) {
+        note.textContent = 'research "' + researchQueue.topic + '" complete — '
+          + researchQueue.done.length + " topic" + (researchQueue.done.length === 1 ? "" : "s") + " grounded" + knobs + capped + ".";
+      } else {
+        note.textContent = 'research "' + researchQueue.topic + '": '
+          + researchQueue.done.length + " done · " + researchQueue.pending.length + " queued" + knobs + capped + ".";
+      }
     }
   }
 
+  // Read the two node knobs off the page and hand them to the session for the
+  // NEXT run started. A run already going keeps the knobs it captured.
+  function applyResearchConfig() {
+    if (!session || !session.setResearchConfig) return;
+    session.setResearchConfig({
+      maxTopics: parseInt(el("researchNodes").value, 10),
+      maxDepth: parseInt(el("researchDepth").value, 10),
+    });
+  }
+
   async function researchStep(line) {
     if (!session) return;
     let res;
@@ -619,6 +646,7 @@ ${THEME_TOKENS_CSS}
   async function startResearch() {
     const topic = el("researchTopic").value.trim();
     if (!topic || !session) return;
+    applyResearchConfig();
     el("researchTopic").value = "";
     el("researchNote").textContent = 'researching "' + topic + '"…';
     const previous = researchQueue;

package/src/services/research.mjs

@@ -42,34 +42,64 @@ export function researchTopicKey(topic, lexicon = null) {
   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. */
+/** The most linked topics any single fan-out may queue — the per-fan-out cap
+ *  the request's "limit N" (or the configured `fanoutLimit`) sets, itself
+ *  bounded here. */
 export const RESEARCH_FANOUT_MAX = 12;
 
+/** How deep the link fan-out may follow: depth 0 is the requested topic, and
+ *  each further tier is the previous tier's own lead-section links. The user
+ *  knob (page "maximum node depth", CLI `depth D`) is clamped to this. */
+export const RESEARCH_MAX_DEPTH = 3;
+
+/** The largest total node budget a run may carry — the page's "maximum
+ *  response nodes" upper bound. `maxTopics` caps how many topics one run
+ *  fetches and stores in total (depth 0 counts as the first). */
+export const RESEARCH_MAX_TOPICS = 50;
+
 export const RESEARCH_DEFAULTS = Object.freeze({
   fanoutLimit: 5,
-  depthLimit: 1,
+  maxDepth: 1,
+  maxTopics: 12,
   minIntervalMs: 2000,
 });
 
 const clampInt = (n, lo, hi) => Math.min(hi, Math.max(lo, Math.floor(n)));
 
+/** A partial `{ fanoutLimit?, maxDepth?, maxTopics?, minIntervalMs? }` (camelCase,
+ *  as the page and CLI supply it) folded onto the shipped defaults and clamped
+ *  to the engineered ranges: fan-out at RESEARCH_FANOUT_MAX, depth at
+ *  RESEARCH_MAX_DEPTH, the node budget at [1, RESEARCH_MAX_TOPICS], and the
+ *  polite interval only ever RAISED above its floor, never lowered. Every
+ *  non-finite field falls back to its default, so a corrupt/absent value is
+ *  the shipped knob, never a crash. */
+export function clampResearchConfig(partial = {}) {
+  const cfg = { ...RESEARCH_DEFAULTS };
+  const fanout = Number(partial.fanoutLimit);
+  if (Number.isFinite(fanout)) cfg.fanoutLimit = clampInt(fanout, 0, RESEARCH_FANOUT_MAX);
+  const depth = Number(partial.maxDepth);
+  if (Number.isFinite(depth)) cfg.maxDepth = clampInt(depth, 0, RESEARCH_MAX_DEPTH);
+  const topics = Number(partial.maxTopics);
+  if (Number.isFinite(topics)) cfg.maxTopics = clampInt(topics, 1, RESEARCH_MAX_TOPICS);
+  const interval = Number(partial.minIntervalMs);
+  if (Number.isFinite(interval)) cfg.minIntervalMs = Math.max(RESEARCH_DEFAULTS.minIntervalMs, interval);
+  return cfg;
+}
+
 /** 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. */
+ *  `depth_limit`/`max_depth` set how deep the fan-out follows (0 means no
+ *  fan-out); `max_topics` sets the total node budget; `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;
+  return clampResearchConfig({
+    fanoutLimit: raw.fanout_limit,
+    maxDepth: raw.max_depth ?? raw.depth_limit,
+    maxTopics: raw.max_topics,
+    minIntervalMs: raw.min_interval_ms,
+  });
 }
 
 // The verbs that step/inspect/end a run, checked before the start shape so
@@ -77,16 +107,21 @@ export function resolveResearchConfig(toml = null) {
 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;
+const RESEARCH_START_RE = /^research[,:]?\s+(.+?)\s*[.!?]*$/i;
+// The trailing knob tokens a start request may carry, stripped one at a time
+// off the END so "limit N" and "depth D" read in either order: "research owls,
+// limit 2 depth 2" and "research owls depth 2, limit 2" both parse the same.
+const RESEARCH_OPTION_RE = /[,;]?\s+(?:with\s+)?(limit|depth)\s+(\d{1,3})$/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. */
+/** The research request a line carries, or null. Kinds: start {topic, limit?,
+ *  depth?}, next, bareNext, status, stop. The topic keeps the user's own words
+ *  minus a leading article and any wrapping quotes; `limit` (per-fan-out cap)
+ *  and `depth` (how deep the fan-out follows) are present only when the request
+ *  named them. */
 export function parseResearchRequest(line) {
   const q = String(line || "").trim();
   if (!q) return null;
@@ -96,13 +131,21 @@ export function parseResearchRequest(line) {
   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()
+  let rest = m[1].trim();
+  const opts = {};
+  for (let om = rest.match(RESEARCH_OPTION_RE); om; om = rest.match(RESEARCH_OPTION_RE)) {
+    const kind = om[1].toLowerCase();
+    if (opts[kind] === undefined) opts[kind] = Number(om[2]);
+    rest = rest.slice(0, om.index).trim();
+  }
+  const topic = rest
     .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]);
+  if (opts.limit !== undefined) out.limit = opts.limit;
+  if (opts.depth !== undefined) out.depth = opts.depth;
   return out;
 }
 
@@ -122,29 +165,101 @@ export function renderResearchAnswer(term, article) {
 }
 
 /** 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. */
+ *  skips, the two node knobs this run carries, and whether the run is complete
+ *  (and, if so, whether the node budget is why). Null for no run. */
 export function researchSnapshot(state) {
   if (!state) return null;
   return {
     topic: state.topic,
     limit: state.limit,
+    maxDepth: runMaxDepth(state),
+    maxTopics: runMaxTopics(state),
     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,
+    nodeCapReached: Boolean(state.nodeCapReached),
   };
 }
 
 const totalFacts = (state) => state.done.reduce((sum, d) => sum + d.facts, 0);
 
+/** The run's effective knobs, defaulted so a queue resumed from an older
+ *  persisted file (which carried neither field) reads as today's depth-1
+ *  behaviour rather than crashing. */
+const runMaxDepth = (state) => (Number.isFinite(state?.maxDepth) ? state.maxDepth : RESEARCH_DEFAULTS.maxDepth);
+const runMaxTopics = (state) => (Number.isFinite(state?.maxTopics) ? state.maxTopics : RESEARCH_DEFAULTS.maxTopics);
+const runFanout = (state) => clampInt(Number.isFinite(state?.limit) ? state.limit : RESEARCH_DEFAULTS.fanoutLimit, 0, RESEARCH_FANOUT_MAX);
+
+/** The depth a queued title carries, or 1 for a queue resumed off an older
+ *  file that never recorded per-title depths. */
+const pendingDepth = (state, title) => {
+  const d = state.depths ? state.depths[normFactTerm(title)] : undefined;
+  return Number.isFinite(d) ? d : 1;
+};
+
+/** Every folded title this run has already touched — the run key, its grounded
+ *  topics, its skips and its still-pending queue — so a fan-out never re-queues
+ *  a topic the run has met. */
+function queuedFolds(state) {
+  const seen = new Set();
+  if (state.key) seen.add(state.key);
+  for (const d of state.done) { const f = normFactTerm(d.title); if (f) seen.add(f); }
+  for (const t of state.skipped) { const f = normFactTerm(t); if (f) seen.add(f); }
+  for (const t of state.pending) { const f = normFactTerm(t); if (f) seen.add(f); }
+  return seen;
+}
+
+/** Queue `article`'s lead-section links at `fromDepth + 1`, subject to the run's
+ *  depth ceiling, its per-fan-out cap and — crucially — its TOTAL node budget:
+ *  the number added never pushes grounded+pending past `maxTopics`. Sets
+ *  `state.nodeCapReached` when the budget (not the depth, not a lack of links)
+ *  is what stopped the fan-out, so the progress line can say so. Returns the
+ *  titles it enqueued. */
+async function enqueueFrom(state, article, fromDepth, provider) {
+  const childDepth = fromDepth + 1;
+  if (childDepth > runMaxDepth(state)) return [];
+  const fanoutCap = runFanout(state);
+  if (fanoutCap <= 0 || typeof provider.linkedTitles !== "function") return [];
+  const budget = runMaxTopics(state) - (state.done.length + state.pending.length);
+  const want = Math.min(fanoutCap, budget);
+  if (want <= 0) { state.nodeCapReached = true; return []; }
+  let linked = null;
+  try { linked = await provider.linkedTitles(article.title, { limit: want + 2 }); } catch { linked = null; }
+  const seen = queuedFolds(state);
+  if (!state.depths) state.depths = {};
+  const added = [];
+  for (const title of linked || []) {
+    const folded = normFactTerm(title);
+    if (!folded || seen.has(folded)) continue;
+    seen.add(folded);
+    state.pending.push(title);
+    state.depths[folded] = childDepth;
+    added.push(title);
+    if (added.length >= want) break;
+  }
+  // The budget, not the fan-out cap, was the binding constraint: the run wanted
+  // more topics than the node budget would allow and filled to that ceiling.
+  if (want < fanoutCap && added.length >= want) state.nodeCapReached = true;
+  return added;
+}
+
 function progressLine(state) {
-  const done = `${state.done.length} topic${state.done.length === 1 ? "" : "s"} grounded, ${totalFacts(state)} fact${totalFacts(state) === 1 ? "" : "s"} stored`;
+  const n = state.done.length;
+  const facts = totalFacts(state);
+  const done = `${n} topic${n === 1 ? "" : "s"} grounded, ${facts} fact${facts === 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.`;
+  const capped = Boolean(state.nodeCapReached);
+  if (!state.pending.length) {
+    if (capped) return `research on "${state.topic}" reached its node budget — ${done}${skipped}.`;
+    return `research on "${state.topic}" is complete — ${done}${skipped}.`;
+  }
+  const queued = `${state.pending.length} linked topic${state.pending.length === 1 ? "" : "s"} still queued`;
+  if (capped) return `${done}${skipped}; ${queued} — "research next" fetches the next one. Node budget of ${runMaxTopics(state)} reached, so no more topics will be added; "research stop" clears the queue.`;
+  return `${done}${skipped}; ${queued} — "research next" fetches the next one.`;
 }
 
-async function startRun({ topic, limit }, { holder, provider, ingest, config, notify, lexicon }) {
+async function startRun({ topic, limit, depth }, { holder, provider, ingest, config, notify, lexicon }) {
   const key = researchTopicKey(topic, lexicon);
   if (!key) {
     holder.state = null;
@@ -167,25 +282,17 @@ async function startRun({ topic, limit }, { holder, provider, ingest, config, no
     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;
-    }
-  }
+  const maxDepth = Number.isFinite(depth) ? clampInt(depth, 0, RESEARCH_MAX_DEPTH) : config.maxDepth;
+  const maxTopics = Number.isFinite(config.maxTopics) ? config.maxTopics : RESEARCH_DEFAULTS.maxTopics;
   holder.state = {
-    topic, key, title: article.title, limit: fanout,
-    pending, done: [{ title: article.title, facts, depth: 0 }], skipped: [],
+    topic, key, title: article.title, limit: fanout, maxDepth, maxTopics,
+    pending: [], depths: {}, done: [{ title: article.title, facts, depth: 0 }],
+    skipped: [], nodeCapReached: false,
   };
+  const pending = await enqueueFrom(holder.state, article, 0, provider);
+  const depthNote = maxDepth > 1 ? ` following links up to depth ${maxDepth}` : "";
   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).`
+    ? `queued ${pending.length} linked topic${pending.length === 1 ? "" : "s"}: ${pending.join(", ")}${depthNote} — "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}`,
@@ -196,7 +303,9 @@ async function startRun({ topic, limit }, { holder, provider, ingest, config, no
 async function stepRun({ holder, provider, ingest, notify }) {
   const state = holder.state;
   const title = state.pending[0];
+  const depth = pendingDepth(state, title);
   state.pending = state.pending.slice(1);
+  if (state.depths) delete state.depths[normFactTerm(title)];
   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; }
@@ -209,8 +318,9 @@ async function stepRun({ holder, provider, ingest, notify }) {
   }
   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 }];
+  try { facts = await ingest(key, article, researchProvenanceTag(state.key, depth)); } catch { facts = 0; }
+  state.done = [...state.done, { title: article.title, facts, depth }];
+  if (depth < runMaxDepth(state)) await enqueueFrom(state, article, depth, provider);
   return {
     text: `${renderResearchAnswer(key, article)}\nstored ${facts} fact${facts === 1 ? "" : "s"} from "${article.title}". ${progressLine(state)}`,
     miss: false,