@hicaru/pi-rlm 0.3.8 → 0.3.13

package/src/commands/rlm-rlm.ts

@@ -0,0 +1,58 @@
+/** `/rlm-rlm` — pin the root/worker model for rlm_query / rlm_batch child engines.
+ *
+ * Unpinned (default), child engines follow pi's active session model — exactly
+ * the pre-pin behavior, now an explicit picker row.
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { modelRef } from "../config/settings.ts";
+import type { RlmController } from "../mode/rlm-mode.ts";
+import { pickableModels, selectModel } from "../ui/model-picker.ts";
+import { setRlmModeStatus } from "../ui/status.ts";
+import { applyRlmSelection } from "./pins.ts";
+
+function sessionScopedModels(
+  ctx: ExtensionContext,
+): readonly { readonly model: Model<Api> }[] | undefined {
+  const scoped: unknown = Reflect.get(ctx, "scopedModels");
+  return Array.isArray(scoped) ? scoped as readonly { readonly model: Model<Api> }[] : undefined;
+}
+
+async function runRlmRlm(controller: RlmController, ctx: ExtensionContext): Promise<void> {
+  try {
+    await ctx.modelRegistry.refresh();
+  } catch {
+    // Fail-soft: show the cached available snapshot rather than aborting config.
+  }
+  const models = pickableModels(ctx.modelRegistry, sessionScopedModels(ctx));
+  const rlm = await selectModel(
+    ctx,
+    "rlm",
+    models,
+    controller.rlmModel,
+    controller.config.rootSampling?.reasoning,
+    controller.savedRlmRef,
+  );
+  applyRlmSelection(controller, rlm);
+  const persisted = await controller.persist();
+  if (!persisted) ctx.ui.notify("RLM: failed to save settings to ~/.pi/agent/rlm.json", "error");
+  setRlmModeStatus(ctx, controller, ctx.getContextUsage());
+
+  const reasoning = controller.config.rootSampling?.reasoning;
+  ctx.ui.notify(
+    controller.rlmModel
+      ? `RLM: rlm=${modelRef(controller.rlmModel) ?? "(none)"}${reasoning ? `/${reasoning}` : ""}`
+      : "RLM: rlm follows session model",
+    "info",
+  );
+}
+
+export function registerRlmRlmCommand(pi: ExtensionAPI, controller: RlmController): void {
+  pi.registerCommand("rlm-rlm", {
+    description: "Pin the model used by rlm_query / rlm_batch child engines (default: session model).",
+    handler: async (_args, ctx) => {
+      await runRlmRlm(controller, ctx);
+    },
+  });
+}

package/src/commands/rlm.ts

@@ -9,7 +9,7 @@ export function registerRlmCommand(pi: ExtensionAPI, controller: RlmController):
     description: "Toggle persistent RLM mode (route plain prompts through the RLM engine).",
     handler: async (_args, ctx) => {
       const enabled = controller.toggle();
-      setRlmModeStatus(ctx.ui, controller, ctx.getContextUsage());
+      setRlmModeStatus(ctx, controller, ctx.getContextUsage());
       ctx.ui.notify(`RLM mode ${enabled ? "ON" : "OFF"}`, "info");
     },
   });
@@ -30,7 +30,7 @@ export function registerRlmCommand(pi: ExtensionAPI, controller: RlmController):
     description: "Toggle RLM mode (off also stops a running query)",
     handler: async (ctx) => {
       const enabled = controller.toggle();
-      setRlmModeStatus(ctx.ui, controller, ctx.getContextUsage());
+      setRlmModeStatus(ctx, controller, ctx.getContextUsage());
       ctx.ui.notify(`RLM mode ${enabled ? "ON" : "OFF"}`, "info");
     },
   });

package/src/config/defaults.ts

@@ -13,12 +13,22 @@ export const DEFAULT_CONFIG: Readonly<RlmConfig> = Object.freeze({
   execTimeoutS: 120,
   requestTimeoutMs: 15 * 60_000,
   // Session-wide, not per-batch: spawn() puts many requests on the wire at once, so this is
-  // the only thing bounding leaf fan-out.
-  maxConcurrentSubcalls: 16,
+  // the only thing bounding leaf fan-out. Default 8 — a sane rate for per-account limits
+  // (raise to 16/32 via /rlm-config when the provider allows).
+  maxConcurrentSubcalls: 8,
   // Children are bounded separately and lower: each is a Python subprocess holding its own copy
   // of the context it inherited, where a leaf is one HTTP request. Worst case is
-  // (maxDepth - 1) × this many concurrent child engines.
-  maxConcurrentChildren: 6,
+  // (maxDepth - 1) × this many concurrent child engines. Default 4.
+  maxConcurrentChildren: 4,
+  // v5.1 rate-limit resilience (util/retry.ts): 3 total attempts, 500ms→15s backoff,
+  // 2s→60s adaptive per-provider cooldown. All overridable in rlm.json.
+  retryMaxAttempts: 3,
+  // 429s park on the cooldown instead of dying — up to 8 windows (2s→4s→…≤60s ≈ 4 min).
+  rateLimitMaxAttempts: 8,
+  retryBaseDelayMs: 500,
+  retryMaxDelayMs: 15_000,
+  throttleBaseMs: 2_000,
+  throttleMaxMs: 60_000,
   maxPromptChars: 400_000,
   maxErrors: 5,
   orchestrator: true,

package/src/config/settings.ts

@@ -12,6 +12,9 @@ export interface PersistedSettings {
   /** "provider/id" of the pinned sub-LLM, or undefined for "cheapest (auto)".
    *  `null` = explicit "cheapest" clear (omit key on disk). */
   readonly llm?: string | null;
+  /** "provider/id" of the pinned rlm root/worker model, or undefined for "follow session".
+   *  `null` = explicit "follow session model" clear (omit key on disk). */
+  readonly rlm?: string | null;
 }
 
 type MutablePartialRlmConfig = { -readonly [K in keyof RlmConfig]?: RlmConfig[K] };
@@ -65,6 +68,19 @@ export function validateConfig(raw: unknown): Partial<RlmConfig> {
   if (maxConcurrentSubcalls !== undefined) out.maxConcurrentSubcalls = maxConcurrentSubcalls;
   const maxConcurrentChildren = validateNumber(r.maxConcurrentChildren, 1);
   if (maxConcurrentChildren !== undefined) out.maxConcurrentChildren = maxConcurrentChildren;
+  // v5.1 rate-limit resilience knobs
+  const retryMaxAttempts = validateNumber(r.retryMaxAttempts, 1);
+  if (retryMaxAttempts !== undefined) out.retryMaxAttempts = retryMaxAttempts;
+  const rateLimitMaxAttempts = validateNumber(r.rateLimitMaxAttempts, 1);
+  if (rateLimitMaxAttempts !== undefined) out.rateLimitMaxAttempts = rateLimitMaxAttempts;
+  const retryBaseDelayMs = validateNumber(r.retryBaseDelayMs, 0);
+  if (retryBaseDelayMs !== undefined) out.retryBaseDelayMs = retryBaseDelayMs;
+  const retryMaxDelayMs = validateNumber(r.retryMaxDelayMs, 100);
+  if (retryMaxDelayMs !== undefined) out.retryMaxDelayMs = retryMaxDelayMs;
+  const throttleBaseMs = validateNumber(r.throttleBaseMs, 0);
+  if (throttleBaseMs !== undefined) out.throttleBaseMs = throttleBaseMs;
+  const throttleMaxMs = validateNumber(r.throttleMaxMs, 100);
+  if (throttleMaxMs !== undefined) out.throttleMaxMs = throttleMaxMs;
   const maxPromptChars = validateNumber(r.maxPromptChars, 1000);
   if (maxPromptChars !== undefined) out.maxPromptChars = maxPromptChars;
   const maxTimeoutMs = validateNumber(r.maxTimeoutMs, 1000);
@@ -167,6 +183,7 @@ export async function loadSettings(): Promise<PersistedSettings> {
       config: validateConfig(r.config),
       // `worker` is the pre-rename key — still read so an existing pin survives the upgrade.
       llm: validateString(r.llm) ?? validateString(r.worker),
+      rlm: validateString(r.rlm),
     };
   } catch {
     return { config: {} };
@@ -178,13 +195,19 @@ export async function saveSettings(s: PersistedSettings): Promise<boolean> {
     const p = settingsPath();
     await mkdir(dirname(p), { recursive: true });
     const body: Record<string, unknown> = { config: s.config };
+    const mergeDisk = s.llm === undefined || s.rlm === undefined;
+    const existing = mergeDisk ? await loadSettings() : undefined;
     if (s.llm !== undefined) {
       // Explicit: string → write pin, null → omit key (cheapest).
       if (s.llm !== null) body.llm = s.llm;
-    } else {
+    } else if (existing?.llm) {
       // Merge: preserve existing disk pin so config-only saves never strip it.
-      const existing = await loadSettings();
-      if (existing.llm) body.llm = existing.llm;
+      body.llm = existing.llm;
+    }
+    if (s.rlm !== undefined) {
+      if (s.rlm !== null) body.rlm = s.rlm;
+    } else if (existing?.rlm) {
+      body.rlm = existing.rlm;
     }
     await writeFile(p, `${JSON.stringify(body, null, 2)}\n`);
     return true;

package/src/core/budget.ts

@@ -1,5 +1,5 @@
 /**
- * Token budget cascade (port of rlm_test v4/v5 `budget.py`).
+ * Token budget cascade (port of the v4/v5 `budget.py` engine).
  *
  * 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

package/src/core/compaction.ts

@@ -9,6 +9,7 @@
 import type { Api, Model, Usage } from "@earendil-works/pi-ai";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import { type ChatMsg, modelComplete } from "../bridge/model.ts";
+import type { RetryPolicy } from "../util/retry.ts";
 import { estimateMessageTokens } from "../text/tokens.ts";
 
 const DEFAULT_CONTEXT_WINDOW = 128_000;
@@ -24,6 +25,8 @@ export interface CompactionDeps {
   readonly contextWindow?: number;
   readonly thresholdPct?: number;
   readonly signal?: AbortSignal;
+  /** v5.1 retry policy for modelComplete; defaults apply when omitted. */
+  readonly retry?: RetryPolicy;
 }
 
 /** True if the history is at/over the compaction threshold. */
@@ -93,6 +96,7 @@ export async function compactHistory(
     model: deps.model,
     registry: deps.registry,
     signal: deps.signal,
+    retry: deps.retry,
   });
   onUsage?.(usage);
   const system = history.find((m) => m.role === "system");

package/src/core/engine.ts

@@ -22,12 +22,14 @@ 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 type { SubcallPhase } from "../tool/rlm-details.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, elideOldToolPayloads, shouldCompact } from "./compaction.ts";
+import { retryPolicy } from "../util/retry.ts";
 import { appendUserMessage } from "./history.ts";
 import { runTurn } from "./iteration.ts";
 import { type Limits, LimitError, LimitGuard } from "./limits.ts";
@@ -119,6 +121,12 @@ export function createEngine(deps: EngineDeps): RunRlm {
         },
       },
     };
+    // Live activity phase for the tree UI: child engines report on their own subcall
+    // node; the root engine has no node, so it reports via the root-phase channel.
+    const reportPhase = (phase: SubcallPhase): void => {
+      if (selfReportId !== undefined) emitter.emitSubcallUpdated({ id: selfReportId, phase });
+      else emitter.emitRootPhase(phase);
+    };
     // Detached work must not outlive the sandbox we dispose in `finally`: track it so the
     // run can settle or abort it first (a child engine left running would keep spending).
     let detachedInFlight = 0;
@@ -131,7 +139,7 @@ export function createEngine(deps: EngineDeps): RunRlm {
     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).
+    // context answers for zero API calls (measured 10,051 → 0 tok in bake-off runs).
     const rootMemory =
       deps.memory !== undefined && deps.config.enableMemory ? deps.memory : undefined;
     const modelRefStr = `${model.provider}/${model.id}`;
@@ -276,9 +284,12 @@ export function createEngine(deps: EngineDeps): RunRlm {
           }).handlers
         : {};
 
+      // v5 doctrine: one condition feeds BOTH the python surface and the memory scope —
+      // delegation children keep llm/memory-read/ledger, never repo retrieval or memory.add.
+      const surface = input.depth > 0 && deps.config.childSurface === "delegation" ? "child" : "root";
       sandbox = await PythonSandbox.spawn({
         depth: input.depth,
-        surface: input.depth > 0 && deps.config.childSurface === "delegation" ? "child" : "root",
+        surface,
         execTimeoutS: deps.config.execTimeoutS,
         requestTimeoutMs: deps.config.requestTimeoutMs,
         python: deps.config.python,
@@ -290,7 +301,10 @@ export function createEngine(deps: EngineDeps): RunRlm {
           ...subcalls,
           ...contextHandlers,
           ledgerClaims: () => Promise.resolve(runLedger.listClaims()),
-          memoryOp: (op, args) => Promise.resolve(rootMemory?.serviceOp(op, args) ?? "memory off"),
+          memoryOp: (op, args) =>
+            Promise.resolve(
+              rootMemory === undefined ? "memory off" : rootMemory.serviceOp(op, args, surface === "child" ? "child" : "root"),
+            ),
         },
       });
 
@@ -316,6 +330,7 @@ export function createEngine(deps: EngineDeps): RunRlm {
             registry: deps.registry,
             contextWindow: model.contextWindow,
             thresholdPct: deps.config.compactionThresholdPct,
+            retry: retryPolicy(deps.config),
             signal: deps.signal,
           };
           if (shouldCompact(history, compactionDeps)) {
@@ -328,7 +343,7 @@ export function createEngine(deps: EngineDeps): RunRlm {
           pendingReplOutputs = undefined;
         }
 
-        // Soft runtime nudge (rlm_test parity): remind the model to await pending host tasks.
+        // Soft runtime nudge (engine parity): remind the model to await pending host tasks.
         const pendingIds = taskRegistry.awaitDeps.unawaitedIds();
         if (pendingIds.length > 0) {
           appendUserMessage(
@@ -359,8 +374,10 @@ export function createEngine(deps: EngineDeps): RunRlm {
           model: model,
           registry: deps.registry,
           sampling: rootSampling,
+          retry: deps.complete === undefined ? retryPolicy(deps.config) : undefined,
           signal: deps.signal,
           complete: deps.complete,
+          onPhase: reportPhase,
         });
         const allBlocks = turn.blocks.length > 0
           ? turn.blocks.map((b) => previewText(b, 400)).join("\n")

package/src/core/iteration.ts

@@ -7,9 +7,11 @@
 import type { Api, Model, Usage } from "@earendil-works/pi-ai";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import { type ChatMsg, type CompleteOptions, type CompleteResult, modelComplete } from "../bridge/model.ts";
+import type { RetryPolicy } from "../util/retry.ts";
 import type { ReplResult } from "../sandbox/protocol.ts";
 import type { PythonSandbox } from "../sandbox/sandbox.ts";
 import { findReplBlocks } from "../text/parsing.ts";
+import type { SubcallPhase } from "../tool/rlm-details.ts";
 import type { Sampling } from "./types.ts";
 
 export interface Turn {
@@ -30,20 +32,30 @@ export interface TurnDeps {
   readonly signal?: AbortSignal;
   /** Test-only override for model completion (scripted responses). */
   readonly complete?: CompleteFn;
+  /** v5.1 retry policy for modelComplete (rate-limit resilience); defaults apply when omitted. */
+  readonly retry?: RetryPolicy;
+  /** Live activity reporting for the tree UI (thinking → repl/texting per turn). */
+  readonly onPhase?: (phase: SubcallPhase) => void;
 }
 
 export async function runTurn(history: readonly ChatMsg[], sandbox: PythonSandbox, deps: TurnDeps): Promise<Turn> {
   const complete = deps.complete ?? modelComplete;
+  deps.onPhase?.("thinking");
   const { text, usage } = await complete(history, {
     model: deps.model,
     registry: deps.registry,
     maxTokens: deps.sampling?.maxTokens,
     temperature: deps.sampling?.temperature,
     reasoning: deps.sampling?.reasoning,
+    retry: deps.retry,
+    // Rate-limit parking is a visible phase too — the root/child spinner says "queued".
+    onThrottlePark: deps.onPhase ? () => deps.onPhase?.("queued") : undefined,
+    onThrottleRelease: deps.onPhase ? () => deps.onPhase?.("thinking") : undefined,
     signal: deps.signal,
   });
 
   const blocks = findReplBlocks(text);
+  deps.onPhase?.(blocks.length > 0 ? "repl" : "texting");
   const results = new Array<ReplResult>(blocks.length);
   let executed = 0;
   for (let i = 0; i < blocks.length; i++) {

package/src/core/ledger.ts

@@ -1,5 +1,5 @@
 /**
- * TaskLedger — the session blackboard (port of rlm_test v5 `ledger.py`).
+ * TaskLedger — the session blackboard (port of the v5 `ledger.py` engine).
  *
  * One instance per root run (engine) or per session (native repl tool), threaded down to every
  * child through `SubcallHandlerDeps.ledger` / `RlmInput.ledger` — the same seam as
@@ -139,111 +139,10 @@ export function taskKey(
 }
 
 export const ECHO_STUB: string = Object.freeze(
-  "[ledger echo] this task restates an ancestor goal — the parent run already covers it. " +
-    "Do not spawn a duplicate; answer from what you already know or await the existing task.",
+  "[ledger: ancestor echo rejected. You are already doing this task. " +
+    "Use context / answers / the files already in scope. Do not rlm_query the parent task.]",
 );
 
-const RLM_CALL_OPEN = /\brlm_(?:query|batch)\s*\(/g;
-
-/**
- * Native `repl()` cells are Python, not a task (audit R1). Pull quoted
- * `rlm_query` / `rlm_batch` arguments so `beginRun` has a task-shaped ancestor
- * instead of `print` / `await_task` tokens. Falls back to the raw cell when no
- * such call is present. `paths=` keyword args are not tasks.
- */
-export function nativeRunAncestors(code: string): readonly string[] {
-  const found = extractRlmTaskPrompts(code);
-  return Object.freeze(found.length > 0 ? found : [code]);
-}
-
-function extractRlmTaskPrompts(code: string): readonly string[] {
-  const out: string[] = [];
-  RLM_CALL_OPEN.lastIndex = 0;
-  for (const m of code.matchAll(RLM_CALL_OPEN)) {
-    const start = (m.index ?? 0) + m[0].length;
-    const body = sliceCallBody(code, start);
-    const pathSplit = body.split(/\bpaths\s*=/);
-    const taskPart = pathSplit[0] ?? body;
-    const strings = quotedStrings(taskPart);
-    for (let i = 0; i < strings.length; i++) {
-      const s = strings[i];
-      if (s !== undefined && s.trim() !== "") out.push(s);
-    }
-  }
-  return out;
-}
-
-function sliceCallBody(src: string, start: number): string {
-  let depth = 1;
-  let i = start;
-  while (i < src.length && depth > 0) {
-    const c = src[i];
-    if (c === "'" || c === '"') {
-      i = skipPyString(src, i);
-      continue;
-    }
-    if (c === "#") {
-      const nl = src.indexOf("\n", i);
-      i = nl === -1 ? src.length : nl + 1;
-      continue;
-    }
-    if (c === "(") depth++;
-    else if (c === ")") depth--;
-    i++;
-  }
-  return src.slice(start, depth === 0 ? i - 1 : i);
-}
-
-function quotedStrings(src: string): readonly string[] {
-  const out: string[] = [];
-  let i = 0;
-  while (i < src.length) {
-    const c = src[i];
-    if (c === "'" || c === '"') {
-      const parsed = readPyString(src, i);
-      if (parsed.keep) out.push(parsed.value);
-      i = parsed.end;
-      continue;
-    }
-    i++;
-  }
-  return out;
-}
-
-function skipPyString(src: string, quoteAt: number): number {
-  return readPyString(src, quoteAt).end;
-}
-
-function readPyString(
-  src: string,
-  quoteAt: number,
-): { readonly value: string; readonly end: number; readonly keep: boolean } {
-  const quote = src[quoteAt] ?? '"';
-  const prefix = quoteAt > 0 ? src[quoteAt - 1] : "";
-  const keep = prefix !== "f" && prefix !== "F";
-  const triple = src.startsWith(quote + quote + quote, quoteAt);
-  const delimLen = triple ? 3 : 1;
-  const from = quoteAt + delimLen;
-  if (triple) {
-    const close = src.indexOf(quote + quote + quote, from);
-    if (close === -1) return { value: src.slice(from), end: src.length, keep };
-    return { value: src.slice(from, close), end: close + 3, keep };
-  }
-  const parts: string[] = [];
-  let j = from;
-  while (j < src.length) {
-    const ch = src[j];
-    if (ch === "\\") {
-      parts.push(src[j + 1] ?? "");
-      j += 2;
-      continue;
-    }
-    if (ch === quote) return { value: parts.join(""), end: j + 1, keep };
-    parts.push(ch ?? "");
-    j++;
-  }
-  return { value: parts.join(""), end: src.length, keep };
-}
 
 export class TaskLedger {
   private readonly claims = new Map<string, Claim>();
@@ -252,7 +151,11 @@ export class TaskLedger {
   private readonly hitCounts = { exact: 0, echo: 0, near: 0 };
   private rlmRuns = 0;
 
-  /** Engine marks the active run's root prompt — the ancestor chain for echo detection. */
+  /** Engine marks the active run's root prompt — the ancestor chain for echo detection.
+   *  v5 `begin_run` parity: the ONLY producer. `endRun` pops in the engine's finally, so a
+   *  stack entry exists exactly while that engine is RUNNING — v5's `status in (pending,
+   *  running)` filter is structural here. Native `repl()` cells never push ancestors: their
+   * spawns claim against an empty stack, so an originator can never echo against itself. */
   beginRun(rootPrompt: string): void {
     this.stack.push(normalizePrompt(rootPrompt));
   }
@@ -261,20 +164,6 @@ export class TaskLedger {
     this.stack.pop();
   }
 
-  /** Native `repl()` path (audit R1): push task-shaped ancestors extracted from the cell. */
-  beginNativeCell(code: string): number {
-    const ancestors = nativeRunAncestors(code);
-    for (let i = 0; i < ancestors.length; i++) {
-      const a = ancestors[i];
-      if (a !== undefined) this.beginRun(a);
-    }
-    return ancestors.length;
-  }
-
-  endNativeCell(n: number): void {
-    for (let i = 0; i < n; i++) this.endRun();
-  }
-
   /** A child prompt echoing any ancestor (exact or ≥ 0.8 Jaccard) is rejected as a stub. */
   detectEcho(prompt: string): boolean {
     const np = normalizePrompt(prompt);
@@ -410,11 +299,13 @@ export class TaskLedger {
     return Object.freeze({ ...this.hitCounts });
   }
 
-  /** Compact table for the sandbox's `list_claims()` REPL call. */
+  /** Compact table for the sandbox's `list_claims()` REPL call. Echo hits are appended —
+   *  a suppressed spawn must be visible from inside the session (audit BUG-1). */
   listClaims(): string {
-    if (this.claims.size === 0) return "ledger: no claims";
+    const echoNote = this.hitCounts.echo > 0 ? ` (echo_rejected=${this.hitCounts.echo})` : "";
+    if (this.claims.size === 0) return `ledger: no claims${echoNote}`;
     const lines: string[] = new Array<string>(this.claims.size + 1);
-    lines[0] = "ledger claims:";
+    lines[0] = `ledger claims:${echoNote}`;
     let n = 1;
     for (const c of this.claims.values()) {
       lines[n++] = `  ${c.key.slice(0, 8)} ${c.kind} ${c.status} depth=${c.depth} paths=${pathSig(c.paths) || "-"} '${c.prompt.slice(0, PROMPT_PREVIEW)}'`;
@@ -435,7 +326,8 @@ export class TaskLedger {
     if (inflight.length === 0 && done.length === 0 && stackN <= 1) return "";
     const lines: string[] = [
       "[ledger]",
-      `  depth_stack=${stackN} inflight=${inflight.length} done=${done.length}`,
+      `  depth_stack=${stackN} inflight=${inflight.length} done=${done.length}` +
+        (this.hitCounts.echo > 0 ? ` echo_rejected=${this.hitCounts.echo}` : ""),
       "  rlm_query only for a disjoint goal. ancestor echo is rejected.",
     ];
     if (inflight.length > 0) {

package/src/core/memory.ts

@@ -1,5 +1,5 @@
 /**
- * Durable memory (port of rlm_test v5 `memory/store.py`).
+ * Durable memory (port of the v5 `memory/store.py` engine).
  *
  * L1 episodes: content-addressed replay — a recorded child/root answer replays for ZERO
  * API calls while every file it touched still hashes to the recorded sha256.
@@ -15,6 +15,7 @@ import { createHash } from "node:crypto";
 import { closeSync, openSync, readSync } from "node:fs";
 import { readFileSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
+import { formatError } from "../util/errors.ts";
 
 const TOK = /[a-z0-9]{2,}/g;
 const EPISODE_CAP = 4_000;
@@ -123,6 +124,10 @@ export function rootContextPaths(context: unknown, max: number): readonly string
   return Object.freeze(out);
 }
 
+/** Who is calling serviceOp — delegation children read durable notes but never write them
+ *  (their findings persist via recordEpisode in the rlm_query handler, one per run). */
+export type MemoryScope = "root" | "child";
+
 export class MemoryStore {
   readonly enabled: boolean;
   private dir: string | undefined;
@@ -462,9 +467,16 @@ export class MemoryStore {
   serviceOp(
     op: "query" | "add" | "stats",
     args: { readonly query?: string; readonly k?: number; readonly content?: string; readonly paths?: readonly string[]; readonly tags?: readonly string[] },
+    scope: MemoryScope = "root",
   ): string {
     if (!this.enabled) return "memory disabled";
     if (op === "stats") return JSON.stringify(this.stats());
+    if (op === "add" && scope === "child") {
+      return formatError(
+        "memory.add is root-only — query durable notes with memory.query; " +
+          "your final answer is recorded as an episode automatically",
+      );
+    }
     if (op === "add") {
       const n = this.addNote({ content: args.content ?? "", paths: args.paths ?? [], tags: args.tags ?? [] });
       return n === undefined ? "add skipped (empty content)" : `ok note ${n.id}`;

package/src/core/model-registry.ts

@@ -1,5 +1,5 @@
 /**
- * Model context-window registry (port of rlm_test v4/v5 `models.py`).
+ * Model context-window registry (port of the v4/v5 `models.py` engine).
  *
  * The plugin already knows context windows from model metadata (`Model.contextWindow`); this
  * registry is the offline fallback for models whose metadata carries none: a conservative

package/src/core/types.ts

@@ -25,6 +25,20 @@ export interface RlmConfig {
   /** Concurrent recursive child engines admitted per depth. Lower than maxConcurrentSubcalls:
    *  each child is a Python subprocess holding its own copy of the inherited context. */
   readonly maxConcurrentChildren: number;
+  /** v5.1 rate-limit resilience (see util/retry.ts): transient 429/5xx are retried with
+   *  backoff, and rate limits additionally cool a shared per-provider throttle.
+   *  retryMaxAttempts counts TOTAL attempts per call (1 = never retry).
+   *  rateLimitMaxAttempts is the SEPARATE budget a 429 may burn while parking on the
+   *  cooldown — generous, because "come back later" is a queue, not a failure. */
+  readonly retryMaxAttempts?: number;
+  readonly rateLimitMaxAttempts?: number;
+  readonly retryBaseDelayMs?: number;
+  /** Cap for any single retry delay, including a parsed `retry-after`. */
+  readonly retryMaxDelayMs?: number;
+  /** First cooldown when a provider 429s without timing; doubles per consecutive strike. */
+  readonly throttleBaseMs?: number;
+  /** Ceiling for the adaptive per-provider cooldown. */
+  readonly throttleMaxMs?: number;
   /** Reject sub-LLM prompts larger than this many chars. */
   readonly maxPromptChars: number;
   /** Max wall-clock ms across the whole tree before the engine stops (undefined = no cap). */