@hicaru/pi-rlm 0.3.8 → 0.3.13

package/README.md

@@ -18,8 +18,8 @@
 
 **The ONLY Recursive Language Model plugin for Pi.** No new agent to learn, no
 separate CLI, no YAML workflows — just `/rlm` and your existing Pi session becomes a
-recursive orchestration engine that saves **99% tokens** by delegating work to cheap
-worker models.
+recursive orchestration engine — your best model orchestrates, cheap worker models
+do the reading.
 
 > **One install. One toggle. Infinite context.**
 
@@ -156,8 +156,7 @@ on `poolside/laguna-xs-2.1:free` (a free ~32B model):
 | Coding (retry fix) | orchestrator | **correct** (file edited) |
 | Live smoke needle | classic RLM | **hit** (~5k tokens) |
 
-> On a *free* model. Frontier models do even better. See `rlm_test/RESULTS_AGENT.md`
-> and `rlm_test/RESULTS.md` for full methodology.
+> On a *free* model. Frontier models do even better.
 
 ## Security
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hicaru/pi-rlm",
-	"version": "0.3.8",
+	"version": "0.3.13",
 	"author": "hicaru",
 	"repository": {
 		"type": "git",

package/src/bridge/handlers/completion.ts

@@ -12,6 +12,7 @@ import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import { type ChatMsg, modelComplete } from "../model.ts";
 import { checkResourceLimits } from "../../core/resource-limits.ts";
 import { errorMessage, formatError } from "../../util/errors.ts";
+import { retryPolicy } from "../../util/retry.ts";
 import type { Semaphore } from "../../util/concurrency.ts";
 import type { Invocation, SubcallConfig } from "./types.ts";
 
@@ -33,6 +34,7 @@ export async function complete1(
   prompt: string,
   track: (usage: Usage) => void,
   deps: Complete1Deps,
+  hooks?: { readonly onThrottlePark?: (ms: number) => void; readonly onThrottleRelease?: () => void },
 ): Promise<string> {
   const config = deps.getConfig();
   const limitError = checkResourceLimits({
@@ -55,6 +57,9 @@ export async function complete1(
         maxTokens: config.subSampling?.maxTokens,
         temperature: config.subSampling?.temperature,
         reasoning: config.subSampling?.reasoning,
+        retry: retryPolicy(config),
+        onThrottlePark: hooks?.onThrottlePark,
+        onThrottleRelease: hooks?.onThrottleRelease,
         signal: deps.signal,
       }),
     );

package/src/bridge/handlers/emitting.ts

@@ -8,6 +8,7 @@
 import type { Usage } from "@earendil-works/pi-ai";
 import { isErrorText } from "../../util/errors.ts";
 import { previewText } from "../../text/preview.ts";
+import type { SubcallPhase } from "../../tool/rlm-details.ts";
 import type { Invocation } from "./types.ts";
 
 export interface EmitOpts {
@@ -24,14 +25,19 @@ export interface EmitSummary {
   readonly total?: number;
 }
 
+/** Targeted update for THIS node — the 2nd arg every `fn` handed to emitting() receives. */
+export type EmitNote = (u: { readonly phase?: SubcallPhase; readonly detail?: string }) => void;
+
 /**
  * Create a subcall node, run `fn`, then update the node with status/cost/preview.
  * `fn` should not throw for soft failures (prefer Error: strings). Hard throws mark error.
+ * The `note` arg lets `fn` surface live per-node state — e.g. parking on the rate-limit
+ * cooldown (throttleHooks below).
  */
 export async function emitting<T>(
   inv: Invocation,
   opts: EmitOpts,
-  fn: (track: (usage: Usage) => void) => Promise<T>,
+  fn: (track: (usage: Usage) => void, note: EmitNote) => Promise<T>,
   summarize: (out: T) => EmitSummary,
 ): Promise<T> {
   const id = inv.emitter.emitSubcallCreated({
@@ -42,6 +48,11 @@ export async function emitting<T>(
     args: opts.args,
     depth: inv.depth,
   });
+  // Leaf nodes spend their whole lifetime waiting on the model — say so from birth.
+  inv.emitter.emitSubcallUpdated({ id, phase: "waiting" });
+  const note: EmitNote = (u): void => {
+    inv.emitter.emitSubcallUpdated({ id, ...u });
+  };
 
   let costUsd = 0;
   let tokens = 0;
@@ -51,7 +62,7 @@ export async function emitting<T>(
   };
 
   try {
-    const out = await fn(track);
+    const out = await fn(track, note);
     const summary = summarize(out);
     inv.emitter.emitSubcallUpdated({
       id,
@@ -78,27 +89,26 @@ export async function emitting<T>(
   }
 }
 
-/** Summarize a batch result for the emitter. */
-export function summarizeBatch(out: readonly string[]): EmitSummary {
-  let failed = 0;
-  let firstError: string | undefined;
-  for (const s of out) {
-    if (isErrorText(s)) {
-      failed += 1;
-      firstError ??= s;
-    }
-  }
-  const first = previewText(out[0] ?? "");
-  const error =
-    failed === 0
-      ? undefined
-      : failed === out.length
-        ? `all ${out.length} sub-calls failed — reduce batch size or try llm_query individually`
-        : `${failed}/${out.length} sub-calls failed`;
+/** Summarize a single leaf answer for the emitter — shared by llm_query and every llm_batch item. */
+export function summarizeLeaf(out: string): EmitSummary {
+  return { preview: previewText(out), error: isErrorText(out) ? out : undefined };
+}
+
+/**
+ * Wire a leaf's `note` into modelComplete's throttle callbacks: parked → "queued" with the
+ * pending seconds in detail; released → back to plain "waiting". One helper so every leaf
+ * call site reports the queue state identically.
+ */
+export function throttleHooks(note: EmitNote): {
+  readonly onThrottlePark: (ms: number) => void;
+  readonly onThrottleRelease: () => void;
+} {
   return {
-    preview: out.length > 1 ? `${first}  (+${out.length - 1} more)` : first,
-    error: error ?? firstError,
-    failed,
-    total: out.length,
+    onThrottlePark: (ms): void => {
+      note({ phase: "queued", detail: `rate limit — waiting ${Math.max(1, Math.round(ms / 1000))}s` });
+    },
+    onThrottleRelease: (): void => {
+      note({ phase: "waiting" });
+    },
   };
 }

package/src/bridge/handlers/index.ts

@@ -43,6 +43,6 @@ export type {
 } from "./types.ts";
 
 export { limitsFromRemaining } from "./types.ts";
-export { summarizeBatch } from "./emitting.ts";
+export { summarizeLeaf } from "./emitting.ts";
 export { createTaskRegistry, SPAWN_HINT } from "./task-registry.ts";
 export type { TaskRegistry, SpawnDeps, AwaitDeps } from "./task-registry.ts";

package/src/bridge/handlers/llm-query.ts

@@ -5,8 +5,8 @@
 import type { Usage } from "@earendil-works/pi-ai";
 import { modelRef } from "../../config/settings.ts";
 import { complete1, type Complete1Deps } from "./completion.ts";
-import { emitting, summarizeBatch } from "./emitting.ts";
-import { formatError, isErrorText, errorMessage } from "../../util/errors.ts";
+import { emitting, summarizeLeaf, throttleHooks } from "./emitting.ts";
+import { formatError, errorMessage } from "../../util/errors.ts";
 import { previewText } from "../../text/preview.ts";
 import type { SpawnResult, SubcallHandlerDeps } from "./types.ts";
 import type { SubcallOpts } from "../../sandbox/interrupts.ts";
@@ -106,11 +106,8 @@ export function createLlmQueryHandler(
           args: `prompt: ${previewText(prompt)}`,
           model: displayModel(deps),
         },
-        (track: (u: Usage) => void) => complete1(inv, prompt, track, cdeps),
-        (out) => ({
-          preview: previewText(out),
-          error: isErrorText(out) ? out : undefined,
-        }),
+        (track: (u: Usage) => void, note) => complete1(inv, prompt, track, cdeps, throttleHooks(note)),
+        summarizeLeaf,
       );
     // v5 TaskLedger for leaves: identical prompts coalesce onto one completion (key has no
     // context — a leaf's entire world is the prompt text itself).
@@ -153,31 +150,33 @@ export function createLlmBatchHandler(
       sd,
       "llm_batch",
       prompts.length,
+      // One visible node per prompt — no collapsed "×N" row, no hidden failures: each item
+      // reports its own status/tokens/error (UI parity with pi: every concurrent call renders).
       () =>
-        emitting(
-          inv,
-          {
-            kind: "batch",
-            label: `llm_batch ×${prompts.length}`,
-            args: `prompt: ${previewText(prompts[0] ?? "")}`,
-            model: displayModel(deps),
-          },
-          // NO outer gate — complete1 takes the single leaf slot per prompt.
-          // v5 (audit H3): every item routes through the ledger — duplicate prompts inside
-          // one batch (or twins of other in-flight leaves) coalesce instead of paying N times.
-          (track: (u: Usage) => void) =>
-            Promise.all(
-              prompts.map((p) =>
+        Promise.all(
+          prompts.map((p) =>
+            emitting(
+              inv,
+              {
+                kind: "llm",
+                label: "llm_query",
+                args: `prompt: ${previewText(p)}`,
+                model: displayModel(deps),
+              },
+              // NO outer gate — complete1 takes the single leaf slot per prompt.
+              // v5 (audit H3): every item routes through the ledger — duplicate prompts inside
+              // one batch (or twins of other in-flight leaves) coalesce instead of paying N times.
+              (track: (u: Usage) => void, note) =>
                 runClaimedLeaf(
                   ledger,
                   ledger === undefined ? undefined : leafClaimKey(deps, p),
                   p,
                   inv.depth,
-                  () => complete1(inv, p, track, cdeps),
+                  () => complete1(inv, p, track, cdeps, throttleHooks(note)),
                 ),
-              ),
+              summarizeLeaf,
             ),
-          summarizeBatch,
+          ),
         ),
       deps.trackDetached,
       opts.detached,

package/src/bridge/handlers/rlm-query.ts

@@ -15,8 +15,7 @@ import type { Invocation, SpawnResult, SubcallHandlerDeps } from "./types.ts";
 import type { SubcallOpts } from "../../sandbox/interrupts.ts";
 import { SPAWN_HINT, spawnAndRun, type SpawnDeps } from "./task-registry.ts";
 import { complete1, type Complete1Deps } from "./completion.ts";
-import { emitting } from "./emitting.ts";
-import { isErrorText } from "../../util/errors.ts";
+import { emitting, summarizeLeaf, throttleHooks } from "./emitting.ts";
 import { leafClaimKey, runClaimedLeaf } from "./llm-query.ts";
 
 const UNWIRED = formatError("RLM bridge not wired for this invocation");
@@ -159,6 +158,7 @@ async function childRun(
     detail: prompt.slice(0, 60),
     depth: childDepth,
   });
+  inv.emitter.emitSubcallUpdated({ id: subId, phase: "spawning" });
 
   if (decision?.type === "echo") {
     inv.emitter.emitSubcallUpdated({ id: subId, status: "done", resultPreview: ECHO_STUB.slice(0, 80) });
@@ -265,11 +265,8 @@ export function createRlmQueryHandler(deps: SubcallHandlerDeps, sd: SpawnDeps) {
                   label: "rlm_query→llm (demoted)",
                   args: previewText(task),
                 },
-                (track) => complete1(inv, task, track, completeDeps(deps)),
-                (out) => ({
-                  preview: previewText(out),
-                  error: isErrorText(out) ? out : undefined,
-                }),
+                (track, note) => complete1(inv, task, track, completeDeps(deps), throttleHooks(note)),
+                summarizeLeaf,
               ),
           ),
         deps.trackDetached,
@@ -311,36 +308,17 @@ export function createRlmBatchHandler(deps: SubcallHandlerDeps, sd: SpawnDeps) {
     }
 
     const pathArg = opts.paths;
-    const id = inv.emitter.emitSubcallCreated({
-      kind: "batch",
-      parentId: inv.parentId,
-      label: `rlm_batch ×${tasks.length}`,
-      args: previewText(tasks[0] ?? ""),
-      depth: inv.depth,
-    });
-
+    // No wrapper "rlm_batch ×N" node: every task already gets its own rlm_query node from
+    // childRun (DRY #2), parented to the caller — the batch is spawn fan-out, not a UI row.
     return spawnAndRun(
       sd,
       "rlm_batch",
       tasks.length,
       async () => {
-        try {
-          const results = await Promise.all(
-            tasks.map((t) => childRun(deps, inv, t, pathArg)),
-          );
-          const answers = results.map((r) => r.answer);
-          inv.emitter.emitSubcallUpdated({
-            id,
-            status: "done",
-            resultPreview: previewText(answers[0] ?? ""),
-            totalCount: answers.length,
-          });
-          return answers;
-        } catch (err: unknown) {
-          const msg = errorMessage(err);
-          inv.emitter.emitSubcallUpdated({ id, status: "error", detail: msg });
-          throw err;
-        }
+        const results = await Promise.all(
+          tasks.map((t) => childRun(deps, inv, t, pathArg)),
+        );
+        return results.map((r) => r.answer);
       },
       deps.trackDetached,
       opts.detached,

package/src/bridge/handlers/types.ts

@@ -3,7 +3,7 @@
  *
  * Every subcall (llm_query, llm_batch, rlm_query, rlm_batch) returns a SpawnResult
  * immediately with a task_id. The model must call await(task_id) to collect the
- * real answer. This contract is proven in rlm_test (api_v5 + batch, scores 0.89–1.0).
+ * real answer. This contract is proven in bake-off runs (api_v5 + batch, scores 0.89–1.0).
  */
 
 import type { Api, Model, Usage } from "@earendil-works/pi-ai";
@@ -93,6 +93,13 @@ export interface SubcallConfig {
   readonly rlmBudget?: number;
   /** v5 durable memory gates (optional; omitted → memory off). */
   readonly enableMemory?: boolean;
+  /** v5.1 retry knobs — structural slice of RlmConfig so retryPolicy() can read them. */
+  readonly retryMaxAttempts?: number;
+  readonly rateLimitMaxAttempts?: number;
+  readonly retryBaseDelayMs?: number;
+  readonly retryMaxDelayMs?: number;
+  readonly throttleBaseMs?: number;
+  readonly throttleMaxMs?: number;
 }
 
 export interface SubcallHandlerDeps {

package/src/bridge/model.ts

@@ -2,12 +2,16 @@
  * modelComplete — a single, serverless, in-process LLM completion.
  *
  * This is the one place that talks to a provider. It resolves the API key from pi's
- * ModelRegistry (keys live here, never in the sandbox) and calls pi-ai's `completeSimple`.
- * Used both for `llm_query` (one user prompt) and for the headless RLM root (full history).
+ * ModelRegistry (keys live here, never in the sandbox) and calls pi-ai's `completeSimple`,
+ * wrapped in completeWithRetry: transient 429/5xx get exponential backoff (honoring
+ * `retry-after` via the onResponse hook) and rate limits additionally cool the shared
+ * per-provider throttle. Used both for `llm_query` (one user prompt) and for the headless
+ * RLM root (full history).
  */
 
 import { type Api, completeSimple, type Message, type Model, type ThinkingLevel, type Usage } from "@earendil-works/pi-ai/compat";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { completeWithRetry, DEFAULT_RETRY_POLICY, type RetryPolicy } from "../util/retry.ts";
 
 export type Role = "system" | "user" | "assistant";
 export interface ChatMsg {
@@ -23,6 +27,11 @@ export interface CompleteOptions {
   readonly temperature?: number;
   readonly reasoning?: ThinkingLevel;
   readonly signal?: AbortSignal;
+  /** Retry + adaptive throttle for transient 429/5xx; defaults apply when omitted. */
+  readonly retry?: RetryPolicy;
+  /** v5.1 UX: fired while parked on the rate-limit cooldown ("queued") / when released. */
+  readonly onThrottlePark?: (ms: number) => void;
+  readonly onThrottleRelease?: () => void;
 }
 
 export interface CompleteResult {
@@ -78,20 +87,29 @@ export async function modelComplete(messages: readonly ChatMsg[], opts: Complete
       : opts.system
     : built.systemPrompt;
 
-  const msg = await completeSimple(
-    opts.model,
-    { systemPrompt, messages: built.messages },
-    {
-      apiKey: auth.apiKey,
-      headers: auth.headers,
-      maxTokens: opts.maxTokens,
-      temperature: opts.temperature,
-      reasoning: opts.reasoning,
-      signal: opts.signal,
+  const msg = await completeWithRetry(
+    async (note) => {
+      const response = await completeSimple(
+        opts.model,
+        { systemPrompt, messages: built.messages },
+        {
+          apiKey: auth.apiKey,
+          headers: auth.headers,
+          maxTokens: opts.maxTokens,
+          temperature: opts.temperature,
+          reasoning: opts.reasoning,
+          signal: opts.signal,
+          onResponse: (res) => { note(res.status, res.headers); },
+        },
+      );
+      // pi-ai folds provider failures into the message: "error"/"aborted" + errorMessage.
+      // Throwing here puts every completion failure onto ONE path — the retry classifier.
+      if (response.stopReason === "error" || response.stopReason === "aborted") {
+        throw new Error(response.errorMessage ?? response.stopReason);
+      }
+      return response;
     },
+    { policy: opts.retry ?? DEFAULT_RETRY_POLICY, provider: opts.model.provider, signal: opts.signal, onPark: opts.onThrottlePark, onRelease: opts.onThrottleRelease },
   );
-  if (msg.stopReason === "error" || msg.stopReason === "aborted") {
-    throw new Error(msg.errorMessage ?? msg.stopReason);
-  }
   return { text: extractText(msg.content), usage: msg.usage };
 }

package/src/commands/pins.ts

@@ -0,0 +1,51 @@
+/**
+ * pins — apply model-picker selections to controller pin state.
+ *
+ * One function per role; both follow the same contract:
+ *   `undefined` → ESC, no change · `null` → the role's top option (unpin) ·
+ *   `ModelSelection` → pin model + its thinking level into the matching sampling slot.
+ */
+
+import { modelRef } from "../config/settings.ts";
+import type { RlmController } from "../mode/rlm-mode.ts";
+import type { ModelSelection } from "../ui/model-picker.ts";
+
+export function applyLlmSelection(controller: RlmController, llm: ModelSelection | null | undefined): void {
+  if (llm === undefined) return;
+  if (llm === null) {
+    controller.llmModel = undefined;
+    controller.savedLlmRef = undefined;
+    controller.explicitClearPin = true;
+    return;
+  }
+  controller.llmModel = llm.model;
+  controller.savedLlmRef = modelRef(llm.model);
+  controller.explicitClearPin = false;
+  controller.setConfig(Object.freeze({
+    ...controller.config,
+    subSampling: Object.freeze({
+      ...controller.config.subSampling,
+      reasoning: llm.thinkingLevel,
+    }),
+  }));
+}
+
+export function applyRlmSelection(controller: RlmController, rlm: ModelSelection | null | undefined): void {
+  if (rlm === undefined) return;
+  if (rlm === null) {
+    controller.rlmModel = undefined;
+    controller.savedRlmRef = undefined;
+    controller.explicitClearRlmPin = true;
+    return;
+  }
+  controller.rlmModel = rlm.model;
+  controller.savedRlmRef = modelRef(rlm.model);
+  controller.explicitClearRlmPin = false;
+  controller.setConfig(Object.freeze({
+    ...controller.config,
+    rootSampling: Object.freeze({
+      ...(controller.config.rootSampling ?? {}),
+      reasoning: rlm.thinkingLevel,
+    }),
+  }));
+}

package/src/commands/rlm-config.ts

@@ -1,104 +1,20 @@
-/** `/rlm-config` — choose the sub-LLM model, reasoning level, and run settings.
- *  The root model is always pi's active model; only the sub-LLM is configurable here. */
+/** `/rlm-config` — run settings only. Model pins live in `/rlm-llm` and `/rlm-rlm`. */
 
-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 { cheapestModel } from "../mode/llm-model.ts";
 import { setRlmModeStatus } from "../ui/status.ts";
 import { showConfigPanel } from "../ui/config-panel.ts";
-import { pickableModels, selectModel, type ModelSelection } from "../ui/model-picker.ts";
-
-/** Newer Pi hosts expose session-scoped models; 0.79 peers do not — duck-type safely. */
-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;
-}
-
-/**
- * Apply a model-picker result to controller pin state.
- *
- * - `null` → explicit "cheapest (auto)" (clear pin; leave reasoning alone)
- * - `ModelSelection` → pin that model (and its thinking level, which may be undefined)
- * - `undefined` → ESC / no change
- */
-export function applyLlmSelection(
-  controller: RlmController,
-  llm: ModelSelection | null | undefined,
-): void {
-  if (llm === undefined) return;
-  if (llm === null) {
-    controller.llmModel = undefined;
-    controller.savedLlmRef = undefined;
-    controller.explicitClearPin = true;
-    return;
-  }
-  controller.llmModel = llm.model;
-  controller.savedLlmRef = modelRef(llm.model);
-  controller.explicitClearPin = false;
-  controller.setConfig(Object.freeze({
-    ...controller.config,
-    subSampling: Object.freeze({
-      ...controller.config.subSampling,
-      reasoning: llm.thinkingLevel,
-    }),
-  }));
-}
-
-export async function runRlmConfig(controller: RlmController, ctx: ExtensionContext): Promise<boolean> {
-  // Match Pi's native list: refresh so a just-added key appears, then use scoped models when
-  // the session narrowed them, else every available (auth-configured) model. Never getAll().
-  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 llm = await selectModel(
-    ctx,
-    "LLM model (sub-calls: llm_query / map_files / rlm_query)",
-    models,
-    controller.llmModel,
-    controller.config.subSampling.reasoning,
-    controller.savedLlmRef,
-  );
-  // Only an explicit choice touches the pin. ESC leaves model + reasoning alone.
-  // Choosing cheapest must NOT wipe subSampling.reasoning (null !== undefined used to).
-  applyLlmSelection(controller, llm);
-
-  // Persist model choice immediately — if showConfigPanel throws or process exits before it
-  // returns, the pin survives (Root Cause #2, v0.3.2).
-  if (llm !== undefined) {
-    const saved = await controller.persist();
-    if (!saved) ctx.ui.notify("RLM: failed to save llm setting", "error");
-  }
 
+async function runRlmConfig(controller: RlmController, ctx: ExtensionContext): Promise<void> {
   controller.setConfig(await showConfigPanel(ctx, controller.config));
-
   const persisted = await controller.persist();
   if (!persisted) ctx.ui.notify("RLM: failed to save settings to ~/.pi/agent/rlm.json", "error");
-  setRlmModeStatus(ctx.ui, controller, ctx.getContextUsage());
-
-  // Name the model that actually resolved, not "(cheapest)" — otherwise there is no way to
-  // tell whether the free model in the catalog was the one picked.
-  const pinned = controller.llmModel;
-  const effective = pinned ?? cheapestModel(ctx.modelRegistry);
-  const reasoning = controller.config.subSampling.reasoning;
-  ctx.ui.notify(
-    `RLM: llm=${modelRef(effective) ?? "(none available)"}`
-    + `${pinned ? "" : " (cheapest, auto)"}${reasoning ? `/${reasoning}` : ""}`,
-    "info",
-  );
-  return llm !== undefined;
+  setRlmModeStatus(ctx, controller, ctx.getContextUsage());
 }
 
 export function registerRlmConfigCommand(pi: ExtensionAPI, controller: RlmController): void {
   pi.registerCommand("rlm-config", {
-    description: "Configure the RLM sub-LLM model and run settings.",
+    description: "Configure RLM run settings (models: /rlm-llm, /rlm-rlm).",
     handler: async (_args, ctx) => {
       await runRlmConfig(controller, ctx);
     },

package/src/commands/rlm-llm.ts

@@ -0,0 +1,59 @@
+/** `/rlm-llm` — pin the leaf-LLM model (llm_query / llm_batch / map_files). */
+
+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 { cheapestModel } from "../mode/llm-model.ts";
+import type { RlmController } from "../mode/rlm-mode.ts";
+import { pickableModels, selectModel } from "../ui/model-picker.ts";
+import { setRlmModeStatus } from "../ui/status.ts";
+import { applyLlmSelection } from "./pins.ts";
+
+/** Newer Pi hosts expose session-scoped models; 0.79 peers do not — duck-type safely. */
+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 runRlmLlm(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 llm = await selectModel(
+    ctx,
+    "llm",
+    models,
+    controller.llmModel,
+    controller.config.subSampling.reasoning,
+    controller.savedLlmRef,
+  );
+  applyLlmSelection(controller, llm);
+  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());
+
+  // Name the model that actually resolved, not "(cheapest)" — otherwise there is no way to
+  // tell whether the free model in the catalog was the one picked.
+  const pinned = controller.llmModel;
+  const effective = pinned ?? cheapestModel(ctx.modelRegistry);
+  const reasoning = controller.config.subSampling.reasoning;
+  ctx.ui.notify(
+    `RLM: llm=${modelRef(effective) ?? "(none available)"}`
+    + `${pinned ? "" : " (cheapest, auto)"}${reasoning ? `/${reasoning}` : ""}`,
+    "info",
+  );
+}
+
+export function registerRlmLlmCommand(pi: ExtensionAPI, controller: RlmController): void {
+  pi.registerCommand("rlm-llm", {
+    description: "Pin the LLM model used by llm_query / llm_batch / map_files sub-calls.",
+    handler: async (_args, ctx) => {
+      await runRlmLlm(controller, ctx);
+    },
+  });
+}