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

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-session.mjs

@@ -332,9 +332,9 @@ export async function createSession({
     // no code graph → point at how to GET one (a graph producer / --repo / the shipped
     // example), and at what IS answerable now — `vocabHint` is only ever a term
     // confirmed to resolve in THIS session's actual seed state (see vocabExampleHint),
-    // never a hardcoded example that might not have been seeded. tmct reads graphs;
-    // it never indexes code itself.
-    ...(noCodeGraph ? [`for code structure, point me at a .tmct/graph.json with --repo <path> or try \`npm run example:mini\` (tmct reads graphs, it doesn't index code). ${vocabHint}`] : []),
+    // never a hardcoded example that might not have been seeded. tmct can index a
+    // repo itself (`tmct index`) or read a graph any other producer wrote.
+    ...(noCodeGraph ? [`for code structure, index this repo with \`tmct index\`, or point me at a .tmct/graph.json with --repo <path> (or try \`npm run example:mini\`). ${vocabHint}`] : []),
     "pass --repo <path> to target a different repo",
     "ask a question, or /help for commands (/stats for an overview) — /exit to leave",
   ];

package/src/services/chat.mjs

@@ -602,7 +602,7 @@ export function answerCount(graph, query) {
     // empty — an honest, non-dangling message pointing at how to load one.
     if (!kinds.length) {
       return `I can't count "${noun}" — no code graph is loaded yet, so there's nothing to count ` +
-        `(point me at one with --repo, or run "npm run example:mini").`;
+        `(index this repo with "tmct index", point me at another with --repo, or run "npm run example:mini").`;
     }
     return `I can't count "${noun}". I count: ${kinds.join(", ")}. ` +
       `Try "how many classes are there".`;
@@ -2077,8 +2077,8 @@ function orientationAnswer(templates, graph, vocabHint) {
  *  null), matching the file's "never crash, always degrade to one honest line"
  *  ethos. Kept short and hand-written so it never drifts silently. */
 const ORIENTATION_EMPTY_FALLBACK = "I'm tmct — a deterministic, offline chat assistant (no LLM). "
-  + "For code structure (imports, calls, definitions) point me at a repo with `--repo <path>`, "
-  + "or try the shipped example `npm run example:mini`. tmct reads graphs; it doesn't index code itself. /help for commands.";
+  + "For code structure (imports, calls, definitions) run `tmct index` here, point me at a repo with `--repo <path>`, "
+  + "or try the shipped example `npm run example:mini`. /help for commands.";
 
 /** A dynamic orientation string for the meta/self lane: a /stats-style overview
  *  when a code graph is loaded, else the honest empty-graph orientation — rendered
@@ -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)"],
   ];
@@ -13009,8 +13009,8 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       answer = `${answer}\n(I don't know that yet — you can teach me: say "remember: <thing> is a <kind>".)`;
       note(trace, "intermediate: HONEST-EMPTY POLISH — a browser miss points at the teach lane, not the CLI-only --repo remedy");
     } else {
-      answer = `${answer}\n(this repo has no code graph — for structure, point me at a \`.tmct/graph.json\` with \`--repo <path>\` or run \`npm run example:mini\`; tmct doesn't index code itself.)`;
-      note(trace, "intermediate: HONEST-EMPTY POLISH — the loaded graph has 0 modules, so the dead-end got a --repo/tmct init pointer appended");
+      answer = `${answer}\n(this repo has no code graph — index it with \`tmct index\`, point me at a \`.tmct/graph.json\` with \`--repo <path>\`, or run \`npm run example:mini\`.)`;
+      note(trace, "intermediate: HONEST-EMPTY POLISH — the loaded graph has 0 modules, so the dead-end got a tmct index/--repo pointer appended");
     }
   }
   // TEACH-OFFER: a "what is X" miss where X is genuinely unknown EVERYWHERE —
@@ -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,