@hicaru/pi-rlm 0.3.6 → 0.3.8

package/src/core/budget.ts

@@ -0,0 +1,182 @@
+/**
+ * Token budget cascade (port of rlm_test v4/v5 `budget.py`).
+ *
+ * The budget is the PRIMARY run-length control: cap = budgetShare × model context window,
+ * one soft wrap-up turn at `softFrac` of the cap, and at the hard cap a deterministic
+ * handoff (`distillTrajectory`) is handed to a fresh continuation run — chain-capped at
+ * `maxContinuations`. Wall-clock timeouts stay only as hang backstops.
+ *
+ * v5 counts the whole tree (root turns + sub-LLM usage) against the cap; the engine feeds
+ * the run's LimitGuard totals in via `observeTotal` after every turn. Each continuation
+ * starts a fresh spend window (v5's offset-anchoring) — the chain total is bounded by
+ * `cap × (1 + maxContinuations)`, never by re-charging prior work.
+ */
+
+import type { ChatMsg } from "../bridge/model.ts";
+import type { RlmConfig } from "./types.ts";
+
+export interface TokenBudgetOptions {
+  readonly softFrac?: number;
+  readonly continuations?: number;
+  readonly maxContinuations?: number;
+}
+
+export type BudgetState = "" | "soft" | "hard";
+
+/** v5 verbatim: the soft wrap-up note prepended to the single turn after crossing soft. */
+export const WRAP_UP_BUDGET: string = Object.freeze(
+  "[budget] ~80% of your token cap — ONE turn left. If the task is answerable NOW, finalize " +
+    '(set answer["ready"] = True). Otherwise print a compact findings dump: what is confirmed, ' +
+    "current file/line or search position, and the exact next step — a fresh continuation picks " +
+    "it up. Do not start new exploration.",
+);
+
+export const DEFAULT_NEXT_STEP: string =
+  Object.freeze("continue the probing that was in flight, then finalize");
+
+/** v5 verbatim template (adapting the finalize spelling to this plugin's REPL). */
+const HANDOFF_TEMPLATE: string = Object.freeze(
+  "A prior RLM run hit its token cap mid-task.\n" +
+    "You are its continuation — pick up EXACTLY where it stopped.\n\n" +
+    "ORIGINAL TASK:\n{query}\n\n" +
+    "CONFIRMED FINDINGS SO FAR:\n{findings}\n\n" +
+    "CURRENT STATE / LAST ACTIONS:\n{state}\n\n" +
+    "NEXT STEP: {next}\n" +
+    "Do not re-do confirmed work; continue from the NEXT STEP and finalize as\n" +
+    'soon as the task is answerable (answer["ready"] = True).',
+);
+
+/** v5's elision marker, used whenever a handoff section is trimmed. */
+const ELISION_MARK = "\n…(+N chars elided [v5 handoff])…\n";
+
+export class TokenBudget {
+  readonly cap: number;
+  readonly softFrac: number;
+  readonly continuations: number;
+  readonly maxContinuations: number;
+  private spent = 0;
+
+  constructor(cap: number, opts: TokenBudgetOptions = {}) {
+    this.cap = Math.max(1, Math.floor(cap));
+    this.softFrac = opts.softFrac ?? 0.8;
+    this.continuations = opts.continuations ?? 0;
+    this.maxContinuations = opts.maxContinuations ?? 2;
+  }
+
+  get soft(): number {
+    return Math.floor(this.cap * this.softFrac);
+  }
+
+  get hard(): number {
+    return this.cap;
+  }
+
+  /** Tokens charged to this run so far (root + sub-LLM, whole tree). */
+  get tokensSpent(): number {
+    return this.spent;
+  }
+
+  /**
+   * Feed the run's cumulative token totals (LimitGuard::usage()) after each turn.
+   * Absolute, not incremental: one budget instance observes exactly one run, which is
+   * what makes a continuation's fresh instance start from zero (v5 offset anchoring).
+   */
+  observeTotal(inputTokens: number, outputTokens: number): void {
+    this.spent = Math.max(0, inputTokens) + Math.max(0, outputTokens);
+  }
+
+  state(): BudgetState {
+    if (this.cap <= 0) return "";
+    if (this.spent >= this.hard) return "hard";
+    if (this.spent >= this.soft) return "soft";
+    return "";
+  }
+
+  canContinue(): boolean {
+    return this.continuations < this.maxContinuations;
+  }
+
+  /** Fresh spend window, one step deeper in the chain. */
+  nextContinuation(): TokenBudget {
+    return new TokenBudget(this.cap, {
+      softFrac: this.softFrac,
+      continuations: this.continuations + 1,
+      maxContinuations: this.maxContinuations,
+    });
+  }
+}
+
+/** Cap derivation (v5 `resolve_budget`): share × context window, clamped by the task cap. */
+export function resolveBudget(contextWindow: number | undefined, config: RlmConfig): TokenBudget {
+  const ctx = contextWindow !== undefined && contextWindow > 0 ? contextWindow : 32_000;
+  const shareCap = Math.floor(ctx * config.budgetShare);
+  const cap = config.budgetTaskCap > 0 ? Math.min(shareCap, config.budgetTaskCap) : shareCap;
+  return new TokenBudget(Math.max(cap, 1), {
+    softFrac: config.budgetSoftFrac,
+    maxContinuations: config.budgetMaxContinuations,
+  });
+}
+
+/**
+ * Truncate at the midpoint so both the head and the tail of the content survive
+ * (v5 semantics: keep the opening context and the most recent actions).
+ */
+export function truncateMid(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  const half = Math.max(0, maxChars - ELISION_MARK.length) >> 1;
+  const elided = text.length - (half * 2);
+  return text.slice(0, half) + ELISION_MARK.replace("N", String(elided)) + text.slice(text.length - half);
+}
+
+const QUERY_CHARS = 800;
+const FINDINGS_MAX = 6;
+const FINDINGS_MIN_CHARS = 20;
+const STATE_MAX = 8;
+const STATE_NEEDLE = "REPL stdout";
+const NEXT_STEP_RE = /next|then|will |todo/i;
+
+/**
+ * Deterministic trajectory → handoff (v5 `distill_trajectory`). No LLM call: the model was
+ * just told (soft wrap-up) to print a findings dump, and this harvests it — query, the last
+ * substantive assistant findings, the last REPL states, and the next step.
+ */
+export function distillTrajectory(
+  history: readonly ChatMsg[],
+  query: string,
+  handoffChars = 4_000,
+): string {
+  const findings: string[] = [];
+  for (let i = history.length - 1; i >= 0 && findings.length < FINDINGS_MAX; i--) {
+    const m = history[i];
+    if (m.role === "assistant" && m.content.trim().length > FINDINGS_MIN_CHARS) {
+      findings.push(m.content.trim());
+    }
+  }
+  // v5 parity (audit C4): the next-step hint scans NEWEST-first; the join below is chronological.
+  const next = findings.find((f) => NEXT_STEP_RE.test(f)) ?? DEFAULT_NEXT_STEP;
+  findings.reverse();
+  const states: string[] = [];
+  for (let i = history.length - 1; i >= 0 && states.length < STATE_MAX; i--) {
+    const m = history[i];
+    if (m.role === "user" && m.content.includes(STATE_NEEDLE)) {
+      states.push(m.content.trim());
+    }
+  }
+  states.reverse();
+
+  const querySlice = query.slice(0, QUERY_CHARS);
+  const queryBlock = truncateMid(querySlice, Math.floor(handoffChars * 0.3));
+  const findingsBlock = truncateMid(findings.join("\n\n"), Math.floor(handoffChars * 0.35));
+  const stateBlock = truncateMid(states.join("\n\n"), Math.floor(handoffChars * 0.35));
+
+  return HANDOFF_TEMPLATE
+    .replace("{query}", queryBlock)
+    .replace("{findings}", findingsBlock)
+    .replace("{state}", stateBlock)
+    .replace("{next}", next);
+}
+
+/** The full continuation prompt: `[continuation n]` header + distilled handoff. */
+export function continuationPrompt(n: number, handoff: string): string {
+  return `[continuation ${n}]\n${handoff}`;
+}

package/src/core/compaction.ts

@@ -33,6 +33,52 @@ export function shouldCompact(history: ChatMsg[], deps: CompactionDeps): boolean
   return estimateMessageTokens(history) >= threshold;
 }
 
+/**
+ * v5 G1: elide old tool/repl payload bodies, keep the head (system) and the working-set tail
+ * intact. Runs BEFORE `shouldCompact` — v3 measured −97% tokens on coding tasks with this
+ * alone, often avoiding the summarizer entirely. Head-ONLY elision was a measured v3 bug
+ * (turns grew 3→8): the tail carries the current working set, so the last `keepTurns` turns
+ * are never touched.
+ */
+export function elideOldToolPayloads(
+  history: ChatMsg[],
+  keepTurns = 2,
+  toolChars = 1_500,
+): ChatMsg[] {
+  if (history.length === 0) return history;
+  // Find the assistant message that starts the keepTurns-th-from-last turn; everything from
+  // there on is the protected tail.
+  let tailStart = 0;
+  let seen = 0;
+  for (let i = history.length - 1; i >= 0; i--) {
+    if (history[i].role === "assistant") {
+      seen++;
+      if (seen >= keepTurns) {
+        tailStart = i;
+        break;
+      }
+    }
+  }
+  if (tailStart === 0) return history; // fewer turns than keepTurns — nothing to elide
+  let changed = false;
+  const marker = "\n…[elided v5-G1]…";
+  const out: ChatMsg[] = new Array<ChatMsg>(history.length); // pre-allocated
+  for (let i = 0; i < history.length; i++) {
+    const m = history[i];
+    if (
+      i < tailStart &&
+      m.role === "user" &&
+      m.content.length > toolChars
+    ) {
+      out[i] = { role: "user", content: m.content.slice(0, toolChars) + marker };
+      changed = true;
+    } else {
+      out[i] = m;
+    }
+  }
+  return changed ? out : history;
+}
+
 /**
  * Summarize the trajectory and return a compacted history: [system, summary(assistant),
  * continue(user)]. The caller continues appending turns from there.

package/src/core/engine.ts

@@ -16,19 +16,23 @@ import {
   createTaskRegistry,
   type Invocation,
 } from "../bridge/handlers/index.ts";
+import { TaskLedger, contextSig, taskKey } from "./ledger.ts";
+import { type MemoryStore, rootContextPaths } from "./memory.ts";
 import { type ChatMsg, modelComplete } from "../bridge/model.ts";
 import { buildRlmSystemPrompt } from "../prompts/system.ts";
 import { buildTurnPrompt, FINALIZE_PROMPT } from "../prompts/user.ts";
 import type { RlmEmitter } from "../tool/rlm-events.ts";
-import { PythonSandbox } from "../sandbox/sandbox.ts";
+import { PythonSandbox, SANDBOX_WATCHDOG_HEARTBEAT_MS } from "../sandbox/sandbox.ts";
 import { pinContext, type PinnedContext } from "../sandbox/context-file.ts";
 import { previewStdout, previewText } from "../text/preview.ts";
 import { contextLength, contextSizeStats, contextTypeLabel } from "../text/tokens.ts";
 import { finalAnswerOf, formatReplOutputs, latestAnswerContentOf, turnHadError } from "./answer.ts";
-import { compactHistory, shouldCompact } from "./compaction.ts";
+import { compactHistory, elideOldToolPayloads, shouldCompact } from "./compaction.ts";
 import { appendUserMessage } from "./history.ts";
 import { runTurn } from "./iteration.ts";
 import { type Limits, LimitError, LimitGuard } from "./limits.ts";
+import { continuationPrompt, distillTrajectory, resolveBudget, WRAP_UP_BUDGET } from "./budget.ts";
+import { ModelContextRegistry, modelsCachePath } from "./model-registry.ts";
 import type { RlmConfig, RlmInput, RlmResult, RunRlm, Sampling } from "./types.ts";
 import { createSubcallGates, type SubcallGates } from "../util/concurrency.ts";
 
@@ -38,6 +42,9 @@ import { createSubcallGates, type SubcallGates } from "../util/concurrency.ts";
  * hold a finished run open on work whose result nobody can receive.
  */
 const DETACHED_SETTLE_MS = 5_000;
+/** H6 (audit): root episodes snapshot at most this many real files — replay invalidation for
+ *  the disk-backed slice of the context without hashing an unbounded repository. */
+const ROOT_HASH_MAX = 64;
 
 
 export interface EngineDeps {
@@ -55,6 +62,8 @@ export interface EngineDeps {
   readonly onUsage?: (usage: Usage, role: "root" | "sub") => void;
   /** Test-only: override model completion (scripted multi-turn responses). */
   readonly complete?: import("./iteration.ts").CompleteFn;
+  /** v5: session-wide durable memory store (`.rlm/`); omitted → memory off for this engine. */
+  readonly memory?: MemoryStore;
 }
 
 /** Build a `runRlm` bound to the given deps. The returned function is reused for recursion. */
@@ -81,6 +90,17 @@ export function createEngine(deps: EngineDeps): RunRlm {
       maxTokens: deps.limits?.maxTokens,
     });
 
+    // v5 token budget: the primary run-length control. A continuation run carries its own
+    // budget in `input.budget`; a fresh run resolves one from the model's context window.
+    // ONE registry per run (audit M1): shared by budget resolution, and observed when the
+    // model metadata already knows the window so the disk cache populates for other callers.
+    const modelCtxRegistry = new ModelContextRegistry(modelsCachePath(runCwd));
+    const budget =
+      input.budget ??
+      (deps.config.enableTokenBudget
+        ? resolveBudget(contextWindowOrFallback(model, modelCtxRegistry), deps.config)
+        : undefined);
+
     // One Invocation for the whole run: this engine owns exactly one sandbox at one depth,
     // and its emitter and LimitGuard outlive every sub-call it services — including
     // detached ones, which is why the headless path needs no session registry.
@@ -105,6 +125,54 @@ export function createEngine(deps: EngineDeps): RunRlm {
     let detachedIdle: (() => void) | undefined;
     // One registry per run — unawaited task reminders share the same map as await handlers.
     const taskRegistry = createTaskRegistry();
+    // v5 TaskLedger: one blackboard per root run; children inherit the same instance via
+    // childRun (RlmInput.ledger — the one construction seam, DRY #6).
+    const runLedger = input.ledger ?? new TaskLedger();
+    if (deps.config.enableLedger) runLedger.beginRun(input.rootPrompt);
+
+    // v5 durable memory: read-only root replay — an identical prompt over an identical
+    // context answers for zero API calls (measured 10,051 → 0 tok in rlm_test).
+    const rootMemory =
+      deps.memory !== undefined && deps.config.enableMemory ? deps.memory : undefined;
+    const modelRefStr = `${model.provider}/${model.id}`;
+    const rootKey = taskKey("root", input.rootPrompt, [], modelRefStr, contextSig(input.context));
+    if (rootMemory !== undefined && input.depth === 0 && input.budget === undefined) {
+      const hit = rootMemory.replay(rootKey);
+      if (hit !== undefined) {
+        emitter.emitStatus("done");
+        return {
+          answer: hit.result,
+          iterations: 0,
+          costUsd: 0,
+          inputTokens: 0,
+          outputTokens: 0,
+          durationMs: 0,
+        };
+      }
+    }
+    const persistRoot = (
+      answer: string,
+      spend?: { readonly inputTokens: number; readonly outputTokens: number },
+    ): void => {
+      if (rootMemory === undefined || input.depth !== 0) return;
+      // H2 (audit): only clean root runs persist — a continuation leaf carries the ORIGINAL
+      // run's key (it persists the chain itself), and stopped/aborted partials must never
+      // replay as if they were real answers.
+      if (input.budget !== undefined) return;
+      if (answer === "" || answer === "(aborted)" || answer.startsWith("(stopped")) return;
+      const u = spend ?? limits.usage();
+      rootMemory.recordEpisode({
+        key: rootKey,
+        kind: "root",
+        model: modelRefStr,
+        prompt: input.rootPrompt,
+        paths: rootContextPaths(input.context, ROOT_HASH_MAX),
+        result: answer,
+        tokensIn: u.inputTokens,
+        tokensOut: u.outputTokens,
+      });
+    };
+
     const subcalls = createSubcallHandlers({
       resolve: () => invocation,
       gates: deps.gates
@@ -119,6 +187,8 @@ export function createEngine(deps: EngineDeps): RunRlm {
       // despite being wired before liveContext is assigned — children can only spawn from an
       // interrupt during runTurn, which is strictly after loadContext below.
       getChildContext: () => liveContext,
+      ledger: runLedger,
+      memory: rootMemory,
       trackDetached: async (task) => {
         detachedInFlight += 1;
         try {
@@ -139,6 +209,10 @@ export function createEngine(deps: EngineDeps): RunRlm {
       detachedIdle = undefined;
     };
     let sandbox: PythonSandbox | undefined;
+    const watchdogHeartbeat = setInterval(() => {
+      if (detachedInFlight > 0) sandbox?.refreshWatchdog();
+    }, SANDBOX_WATCHDOG_HEARTBEAT_MS);
+    watchdogHeartbeat.unref?.();
     /**
      * This run's live context: whatever was seeded plus every source added so far. Children
      * inherit it, so it must grow when add_context appends (see the handler's onLoaded below).
@@ -163,6 +237,9 @@ export function createEngine(deps: EngineDeps): RunRlm {
     let compactions = 0;
     let completedTurns = 0;
     let nodeStatus: "done" | "error" = "done";
+    // v5 budget cascade state: the wrap-up note fires for exactly ONE turn after crossing soft.
+    let softFired = false;
+    let softNoteTurn = -1;
 
     try {
       const meta = {
@@ -177,10 +254,13 @@ export function createEngine(deps: EngineDeps): RunRlm {
         maxPromptChars: deps.config.maxPromptChars,
         contextLoader: deps.config.contextLoader,
         child: input.depth > 0,
+        delegation: input.depth > 0 && deps.config.childSurface === "delegation",
         depth: input.depth,
       });
 
-      const contextHandlers = deps.config.contextLoader
+      // v5 (audit M5): a delegation child does not grow the world — add_context stays root-only.
+      const contextHandlers =
+        deps.config.contextLoader && (input.depth === 0 || deps.config.childSurface !== "delegation")
         ? buildAddContextHandler({
             cwd: runCwd,
             emitter,
@@ -198,6 +278,7 @@ export function createEngine(deps: EngineDeps): RunRlm {
 
       sandbox = await PythonSandbox.spawn({
         depth: input.depth,
+        surface: input.depth > 0 && deps.config.childSurface === "delegation" ? "child" : "root",
         execTimeoutS: deps.config.execTimeoutS,
         requestTimeoutMs: deps.config.requestTimeoutMs,
         python: deps.config.python,
@@ -205,7 +286,12 @@ export function createEngine(deps: EngineDeps): RunRlm {
         initTimeoutMs: deps.config.sandboxInitTimeoutMs,
         maxPromptChars: deps.config.maxPromptChars,
         awaitTimeoutS: Math.round(deps.config.requestTimeoutMs / 1000),
-        handlers: { ...subcalls, ...contextHandlers },
+        handlers: {
+          ...subcalls,
+          ...contextHandlers,
+          ledgerClaims: () => Promise.resolve(runLedger.listClaims()),
+          memoryOp: (op, args) => Promise.resolve(rootMemory?.serviceOp(op, args) ?? "memory off"),
+        },
       });
 
       let history: ChatMsg[] = [{ role: "system", content: system }];
@@ -221,6 +307,8 @@ export function createEngine(deps: EngineDeps): RunRlm {
         else emitter.emitTurn(i + 1, deps.config.maxIterations);
 
         if (deps.config.compaction) {
+          // v5 G1 first: elide old tool payloads head+tail — often avoids the summary entirely.
+          history = elideOldToolPayloads(history);
           const compactionDeps = {
             // Summarisation is done by the cheap worker model; the threshold stays on the
             // root model's context window (that is the window the history fills each turn).
@@ -249,7 +337,18 @@ export function createEngine(deps: EngineDeps): RunRlm {
           );
         }
 
-        appendUserMessage(history, buildTurnPrompt(i, deps.config.maxIterations));
+        // v5 [ledger] blackboard + [memory] notes — each silent ("") when it has nothing to say.
+        const ledgerBlock = deps.config.enableLedger ? runLedger.injectBlock() : "";
+        const memoryBlock = rootMemory !== undefined ? rootMemory.injectBlock(input.rootPrompt) : "";
+        const notes =
+          [
+            i === softNoteTurn ? WRAP_UP_BUDGET : undefined,
+            ledgerBlock === "" ? undefined : ledgerBlock,
+            memoryBlock === "" ? undefined : memoryBlock,
+          ]
+            .filter((s): s is string => s !== undefined)
+            .join("\n\n") || undefined;
+        appendUserMessage(history, buildTurnPrompt(i, deps.config.maxIterations, notes));
 
         // rootSampling fields win; smartReasoning is the default reasoning when not overridden.
         const rootSampling: Sampling = {
@@ -280,6 +379,7 @@ export function createEngine(deps: EngineDeps): RunRlm {
         const final = finalAnswerOf(turn.results);
         if (final != null) {
           const done = result(final, i + 1, limits);
+          persistRoot(done.answer);
           lastAnswer = done.answer;
           return done;
         }
@@ -287,9 +387,62 @@ export function createEngine(deps: EngineDeps): RunRlm {
         limits.observe(turnHadError(turn.results));
         history.push({ role: "assistant", content: turn.response });
         pendingReplOutputs = formatReplOutputs(turn.results, turn.skippedBlocks);
+
+        // ── v5 budget cascade ─────────────────────────────────────────────────────
+        // Content control lives here; wall-clock timeouts stay hang backstops. Whole-tree
+        // tokens (root + sub-LLM) reach `limits` through the invocation's addUsage/addRaw seams.
+        if (budget !== undefined) {
+          const u = limits.usage();
+          budget.observeTotal(u.inputTokens, u.outputTokens);
+          const bstate = budget.state();
+          if (bstate === "soft" && !softFired) {
+            softFired = true;
+            softNoteTurn = i + 1;
+            if (selfReportId) {
+              emitter.emitSubcallUpdated({ id: selfReportId, detail: `budget soft @ ${u.inputTokens + u.outputTokens}/${budget.soft} tok` });
+            }
+          }
+          if (bstate === "hard") {
+            if (budget.canContinue()) {
+              // Distill the trajectory and chain a fresh run with a fresh spend window —
+              // the v4 "finalize NOW" flaw fix: never abort mid-task, restructure-and-resume.
+              const handoff = distillTrajectory(history, input.rootPrompt, deps.config.budgetHandoffChars);
+              const cont = budget.nextContinuation();
+              if (selfReportId) {
+                emitter.emitSubcallUpdated({ id: selfReportId, detail: `budget hard → continuation ${cont.continuations}` });
+              }
+              const inner = await run({
+                ...input,
+                rootPrompt: continuationPrompt(cont.continuations, handoff),
+                context: liveContext, // H9: sources added mid-run reach the leaf
+                budget: cont,
+                remainingTimeoutMs: limits.remainingTimeoutMs(),
+              });
+              // H9: report the CHAIN's spend, not just the leaf's fresh guard.
+              const u = limits.usage();
+              const chained: RlmResult = {
+                ...inner,
+                iterations: inner.iterations + completedTurns,
+                inputTokens: inner.inputTokens + u.inputTokens,
+                outputTokens: inner.outputTokens + u.outputTokens,
+                costUsd: inner.costUsd + u.costUsd,
+              };
+              // H2: the ORIGINAL run persists the chain's answer under the ORIGINAL key —
+              // the next identical prompt must replay the full result, not miss.
+              // R2: lastAnswer must be set before return — `finally` emitAnswer reads it,
+              // and persist must store the CHAIN totals, not just the parent window.
+              lastAnswer = chained.answer;
+              persistRoot(chained.answer, chained);
+              return chained;
+            }
+            // Chain cap reached — finalize with the best partial (a budget never throws).
+            break;
+          }
+        }
       }
       if (pendingReplOutputs) appendUserMessage(history, pendingReplOutputs);
       const finalized = result(await finalize(history, model, deps, limits), deps.config.maxIterations, limits);
+      persistRoot(finalized.answer);
       lastAnswer = finalized.answer;
       return finalized;
     } catch (err) {
@@ -308,6 +461,7 @@ export function createEngine(deps: EngineDeps): RunRlm {
       nodeStatus = "error";
       throw err;
     } finally {
+      if (deps.config.enableLedger) runLedger.endRun();
       if (selfReportId) {
         emitter.emitSubcallUpdated({
           id: selfReportId,
@@ -319,6 +473,7 @@ export function createEngine(deps: EngineDeps): RunRlm {
         if (nodeStatus !== "error" && lastAnswer) emitter.emitAnswer(previewText(lastAnswer));
         emitter.emitStatus(nodeStatus === "error" ? "error" : "done");
       }
+      clearInterval(watchdogHeartbeat);
       // Settle detached work FIRST: a child still running may be about to pin this same payload.
       await settleDetached();
       await contextPin?.release();
@@ -333,6 +488,17 @@ function result(answer: string, iterations: number, limits: LimitGuard): RlmResu
   return { answer, iterations, costUsd: u.costUsd, inputTokens: u.inputTokens, outputTokens: u.outputTokens, durationMs: u.durationMs };
 }
 
+/** Model metadata window, else the offline registry fallback (disk cache → table → 32k). */
+/** Model metadata window, else the offline registry fallback (disk cache → table → 32k).
+ *  When metadata provides the window it is observed into the cache (fail-soft, audit M1). */
+function contextWindowOrFallback(model: Model<Api>, registry: ModelContextRegistry): number {
+  if (model.contextWindow !== undefined && model.contextWindow > 0) {
+    registry.observe(`${model.provider}/${model.id}`, model.contextWindow);
+    return model.contextWindow;
+  }
+  return registry.limitFor(`${model.provider}/${model.id}`);
+}
+
 /** Out of turns: ask the model for its best final answer (plain text). */
 async function finalize(history: ChatMsg[], model: Model<Api>, deps: EngineDeps, limits: LimitGuard): Promise<string> {
   const finalHistory = [...history];