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

package/src/services/chat.mjs

@@ -52,7 +52,8 @@ import {
 } from "../domain/reference-pack.mjs";
 import { getReferencePackProvider } from "../adapters/corpus/reference-pack.mjs";
 import { getLiveReferenceProvider, getResearchProvider } from "../adapters/corpus/wikipedia-live.mjs";
-import { researchTurn, researchSnapshot, resolveResearchConfig, RESEARCH_DEFAULTS } from "./research.mjs";
+import { researchTurn, researchSnapshot, resolveResearchConfig, RESEARCH_DEFAULTS, parseResearchRequest } from "./research.mjs";
+import { loadResearchQueue, saveResearchQueue } from "../adapters/research-queue-store.mjs";
 import { CHILD_PACK_NAME, childProvenanceTag } from "../domain/child-pack.mjs";
 import { getChildPackProvider } from "../adapters/corpus/child-pack.mjs";
 import { dialogueActForLane } from "../domain/dialogue-acts.mjs";
@@ -5973,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)"],
   ];
@@ -14539,16 +14540,27 @@ 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
   // same way planState does.
   {
-    const researchHolder = { state: researchState };
+    // A fresh CLI session carries no in-memory queue, so a research-family line
+    // arriving with none resumes the queue persisted under .tmct/ — that is
+    // what makes "research next"/"status"/"stop" work across process restarts.
+    // The gate keeps ordinary turns off the disk (only a parsed research line
+    // loads), and a store with no path (the browser) simply reads back null.
+    let priorResearchState = researchState;
+    if (!priorResearchState && parseResearchRequest(workingLine)) {
+      priorResearchState = await loadResearchQueue(memoryDir);
+    }
+    const researchHolder = { state: priorResearchState };
     const resolvedResearchConfig = researchConfig ?? RESEARCH_DEFAULTS;
     const rTurn = await researchTurn(workingLine, {
       holder: researchHolder,
@@ -14569,6 +14581,10 @@ export async function runTurn(input, { config, source = defaultSource, graph = n
       result.lane = "research";
       const snapshot = researchSnapshot(researchHolder.state);
       if (snapshot) result.record.research = snapshot;
+      // Write-through: persist the queue this turn just mutated (start, next,
+      // skip), and clear the file when it ended (stop, or a failed start that
+      // left no run). A store with no path no-ops, so the browser is untouched.
+      await saveResearchQueue(memoryDir, researchHolder.state);
       const rec = withLast(result, rTurn.goal);
       rec.planState = planHolder.state;
       rec.researchState = researchHolder.state;

package/src/services/extract-facts.mjs

@@ -118,6 +118,13 @@ const COPULA_OF_READ_THROUGH = new Set(["type", "kind", "sort", "form", "class",
 // bare copula does, unlike any other verb after "is".
 const COPULA_NAMING_PARTICIPLES = new Set(["termed", "known", "defined", "described", "referred", "called", "classified"]);
 const COPULA_PARTITIVE_HEADS = new Set(["body", "mass", "group", "collection", "set", "series", "number", "amount", "piece", "part", "lot", "pair", "bunch", "pile"]);
+// The relative pronouns that open a clause predicating about the SENTENCE
+// subject: "a mountain that has lava" is a fact about the volcano, so the
+// relative clause's verb binds to the copula's own subject, not to its object.
+const RELATIVE_PRONOUNS = new Set(["that", "which", "who", "whom", "whose"]);
+// At most this many triples from one sentence — a bound so a run-on can never
+// shatter into noise, not a first-wins cap.
+const MAX_TRIPLES_PER_SENTENCE = 4;
 
 /** Fold an entity surface to its stored key: a lexicon noun's lemma, else the
  *  word's own normFactTerm (the optimistic tier mints unlisted content nouns
@@ -144,6 +151,7 @@ function optimisticTriplesPos(sentence, lexicon, nlp) {
   // folded — "a string instrument" is the class "string instrument", never
   // its modifier "string"; a single-word run keeps the plain lemma fold.
   const isNounish = (i) => pos[i] === "NOUN" || pos[i] === "PROPN";
+  const runLoOf = (i) => { let lo = i; while (lo - 1 >= 0 && isNounish(lo - 1)) lo -= 1; return lo; };
   const entityRunAt = (i) => {
     let lo = i;
     let hi = i;
@@ -153,18 +161,63 @@ function optimisticTriplesPos(sentence, lexicon, nlp) {
     const head = lookupNoun(lexicon, String(values[hi]).toLowerCase());
     return normFactTerm([...values.slice(lo, hi), head ? head.lemma : values[hi]].join(" "));
   };
-  const nearestEntity = (idx, step, blocked = null) => {
+  const nearestEntityIndex = (idx, step, blocked = null) => {
     for (let i = idx + step; i >= 0 && i < values.length; i += step) {
       if (pos[i] === "PUNCT") break;
       if (blocked && blocked.has(pos[i])) break;
-      if (isNounish(i)) return entityRunAt(i);
+      if (isNounish(i)) return i;
     }
     return null;
   };
-  const tripleAt = (i, predicate, blocked = null) => {
-    const subject = nearestEntity(i, -1, blocked);
-    const object = nearestEntity(i, +1, blocked);
-    return subject && object && subject !== object ? { subject, predicate, object } : null;
+  const nearestEntity = (idx, step, blocked = null) => {
+    const i = nearestEntityIndex(idx, step, blocked);
+    return i === null ? null : entityRunAt(i);
+  };
+  // The subject-side mirror of the copula-object of-chain rule: when a found
+  // subject run is the inner noun of an of-chain ("the weight of all of the
+  // snow …"), climb to the outer run's nominal head ("weight"), bounded to two
+  // hops. A classifier head (type/kind/sort/…) reads THROUGH — a "kind of X"
+  // outer never becomes the subject, so the inner noun is kept. When the run is
+  // governed by "of" but no readable noun heads the chain (a mis-tagged head,
+  // e.g. "the top of the mountain …"), return null: an honest abstain, never the
+  // inner-noun confusion ("mountain", "snow"). A run not governed by "of" is
+  // returned unchanged. Returns a run-lo index to fold, or null to abstain.
+  const ofChainSkip = (k) => {
+    const p = pos[k];
+    return p === "DET" || p === "ADJ" || p === "ADV" || p === "NUM";
+  };
+  const climbSubjectRun = (found) => {
+    let lo = runLoOf(found);
+    for (let hop = 0; hop < 2; hop += 1) {
+      let g = lo - 1;
+      while (g >= 0 && ofChainSkip(g)) g -= 1;
+      if (g < 0 || values[g]?.toLowerCase() !== "of") return lo; // not an of-chain object
+      let k = g - 1;
+      while (k >= 0 && !isNounish(k) && (ofChainSkip(k) || values[k]?.toLowerCase() === "of")) k -= 1;
+      if (k < 0 || !isNounish(k)) return null; // no readable head — abstain
+      if (COPULA_OF_READ_THROUGH.has(String(values[k]).toLowerCase())) return lo; // classifier reads through
+      lo = runLoOf(k);
+    }
+    return lo;
+  };
+  // The subject resolution shared by the relation-verb tiers: a run climbed
+  // through its of-chain and folded, or null when the of-chain has no readable
+  // head (abstain rather than store the inner-noun confusion).
+  const climbedSubjectAt = (idx) => {
+    const found = nearestEntityIndex(idx, -1);
+    if (found === null) return null;
+    const climbed = climbSubjectRun(found);
+    return climbed === null ? null : entityRunAt(climbed);
+  };
+  // A relation verb whose nearest content token leftward (skipping adverbs and
+  // the auxiliaries of its own verb complex) is a relative pronoun sits in a
+  // "that/which …" relative clause — its subject is the sentence subject.
+  const inRelativeFrame = (i) => {
+    for (let k = i - 1; k >= 0; k -= 1) {
+      if (pos[k] === "ADV" || pos[k] === "AUX") continue;
+      return RELATIVE_PRONOUNS.has(String(values[k]).toLowerCase());
+    }
+    return false;
   };
   // An isa needs a CLEAN copula frame: only determiners/adjectives/adverbs/
   // numerals may sit between each entity and the copula. Crossing a verb or
@@ -191,36 +244,87 @@ function optimisticTriplesPos(sentence, lexicon, nlp) {
       while (hi + 1 < values.length && isNounish(hi + 1)) hi += 1;
       const headWord = String(values[hi]).toLowerCase();
       const nextIsOf = values[hi + 1]?.toLowerCase() === "of";
-      if (!nextIsOf) return entityRunAt(j);
+      if (!nextIsOf) return { label: entityRunAt(j), hi };
       if (COPULA_OF_READ_THROUGH.has(headWord)) { i = hi + 1; j = hi + 1; continue; }
       if (COPULA_PARTITIVE_HEADS.has(headWord)) return null;
-      return entityRunAt(j);
+      return { label: entityRunAt(j), hi };
     }
     return null;
   };
   // The copula's own modal chain ("can be", "may be") is part of one verb
   // complex — the subject scan starts left of it, while a free-standing VERB
-  // on the way still voids the frame.
+  // on the way still voids the frame. An of-chain subject climbs to its head
+  // ("the weight of the snow is …" → weight); a mis-headed of-chain abstains.
   const copulaSubjectAt = (i) => {
     let k = i - 1;
     while (k >= 0 && pos[k] === "AUX") k -= 1;
-    return nearestEntity(k + 1, -1, COPULA_FRAME_BLOCKERS);
+    const found = nearestEntityIndex(k + 1, -1, COPULA_FRAME_BLOCKERS);
+    if (found === null) return null;
+    const climbed = climbSubjectRun(found);
+    return climbed === null ? null : entityRunAt(climbed);
   };
+
+  const triples = [];
+  const seen = new Set();
+  const push = (subject, predicate, object) => {
+    if (!(subject && object && subject !== object)) return;
+    const key = `${subject}\0${predicate}\0${object}`;
+    if (seen.has(key) || triples.length >= MAX_TRIPLES_PER_SENTENCE) return;
+    seen.add(key);
+    triples.push({ subject, predicate, object });
+  };
+
+  // Pass 1 — the first clean copula frame yields the isa (all guards unchanged);
+  // its subject and object-run end anchor the relative-clause continuation.
+  let copulaSubject = null;
+  let copulaObjHi = -1;
   for (let i = 1; i < values.length - 1; i += 1) {
     if (pos[i] === "AUX" && OPTIMISTIC_COPULAS.has(values[i].toLowerCase())) {
       const subject = copulaSubjectAt(i);
       const object = copulaObjectAt(i);
-      if (subject && object && subject !== object) return [{ subject, predicate: "rdfs:subClassOf", object }];
+      if (subject && object && subject !== object.label) {
+        push(subject, "rdfs:subClassOf", object.label);
+        copulaSubject = subject;
+        copulaObjHi = object.hi;
+        break;
+      }
+    }
+  }
+
+  // Pass 2a — with a copula isa in hand, CONTINUE past its object for relation
+  // verbs (has/creates/…), so one sentence contributes every fact it grounds.
+  // A "that/which <verb>" clause right after the object predicates about the
+  // SENTENCE subject ("a mountain that has lava" → volcano has lava); any other
+  // relation verb keeps its nearest-entity-leftward subject. AUX relation verbs
+  // ("has") count here — but only inside a copula frame that already resolved,
+  // so a bare "… is that Earth has …" complement never mints "earth has lot".
+  if (copulaSubject) {
+    for (let i = copulaObjHi + 1; i < values.length; i += 1) {
+      if (pos[i] !== "VERB" && pos[i] !== "AUX") continue;
+      const word = values[i].toLowerCase();
+      if (OPTIMISTIC_COPULAS.has(word)) continue;
+      const verb = lookupVerb(lexicon, word);
+      if (!verb) continue;
+      const subject = inRelativeFrame(i) ? copulaSubject : climbedSubjectAt(i);
+      if (subject === null) continue;
+      push(subject, predicateOf(verb), nearestEntity(i, +1));
     }
+    return triples;
   }
+
+  // Pass 2b — no copula isa: the relation-verb tier over the whole sentence,
+  // climbing an of-chain subject to its head ("the weight of the snow creates
+  // pressure" → weight creates pressure, not snow). VERB-tagged only, so a bare
+  // AUX ("Earth has …") in a non-frame sentence stays an honest miss.
   for (let i = 1; i < values.length - 1; i += 1) {
     if (pos[i] !== "VERB") continue;
     const verb = lookupVerb(lexicon, values[i].toLowerCase());
     if (!verb) continue;
-    const t = tripleAt(i, predicateOf(verb));
-    if (t) return [t];
+    const subject = climbedSubjectAt(i);
+    if (subject === null) continue;
+    push(subject, predicateOf(verb), nearestEntity(i, +1));
   }
-  return [];
+  return triples;
 }
 
 /** The lexical fallback for a checkout with no wink model: a copula flanked by
@@ -254,11 +358,15 @@ function optimisticTriplesLexical(sentence, lexicon) {
 }
 
 /**
- * A bounded triple candidate from a sentence the strict recognizer skipped: a
- * copula (→ rdfs:subClassOf) or a lexicon-known relation verb (→ its predicate)
- * flanked by two entities. At most one triple per sentence; [] when nothing
- * resolves both sides — no guessing past the shape. Uses wink POS tags when a
- * model is available (the precise tier), else a narrower lexicon-only fallback.
+ * The bounded triple candidates from a sentence the strict recognizer skipped:
+ * a copula (→ rdfs:subClassOf) and, past its object, the relation verbs it
+ * grounds (→ their predicates), so one sentence contributes every fact it holds
+ * ("a volcano is a mountain that has lava" → volcano ⊑ mountain AND volcano has
+ * lava). Every triple passes the same entity/guard checks on its own, deduped,
+ * capped at MAX_TRIPLES_PER_SENTENCE so a run-on never shatters into noise; []
+ * when nothing resolves both sides — no guessing past the shape. Uses wink POS
+ * tags when a model is available (the precise tier), else a narrower
+ * lexicon-only fallback.
  *
  *   opts.lexicon  a loaded lexicon (the core vocabulary when absent).
  *   opts.nlp      a wink instance (winkInstance() when absent); null forces 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,