@hicaru/pi-rlm 0.3.1 → 0.3.3

package/src/core/types.ts

@@ -55,7 +55,7 @@ export interface RlmConfig {
    *  Keeps each turn short so the next turn's input stays manageable.
    *  `reasoning` is read from `smartReasoning` if omitted here. */
   readonly rootSampling?: Readonly<Sampling>;
-  /** System prompt injected into every llm_query / llm_query_batched sub-call.
+  /** System prompt injected into every llm_query / llm_batch sub-call.
    *  Instructs the worker model to respond concisely.
    *  undefined = no system prompt (raw completion). */
   readonly subSystemPrompt?: string;
@@ -73,8 +73,6 @@ export interface RlmInput {
   readonly depth: number;
   /** AgentTree node to attach this run's node under (set when recursing). */
   readonly parentNodeId?: string;
-  /** "provider/id" — overrides the root model for this run (set by recursive rlm_query). */
-  readonly modelOverride?: string;
   /** Remaining timeout for this subtree (set by parent from its LimitGuard). */
   readonly remainingTimeoutMs?: number;
 }

package/src/index.ts

@@ -18,9 +18,10 @@ import { BackgroundTasks } from "./tool/background-tasks.ts";
 import { resolve } from "node:path";
 import { resolveSource } from "./context/resolve.ts";
 import { formatContextListing } from "./context/listing.ts";
+import { extractEditPaths, readDiskFile } from "./context/refresh.ts";
 import type { AddContextHandlerBundle } from "./bridge/add-context.ts";
-import { buildNativeSystemPrompt, NATIVE_TURN_REMINDER } from "./prompts/native.ts";
-import { bashCommandFromInput, isFileReadingCommand, capToolResultText, BASH_BLOCK_REASON } from "./mode/native-guards.ts";
+import { buildNativeSystemPrompt } from "./prompts/native.ts";
+import { capToolResultText } from "./mode/native-guards.ts";
 import {
   isSubagentChildBypass,
   commitSubagentForceActivation,
@@ -37,14 +38,13 @@ export {
   processRlmDepth,
 } from "./mode/subagent.ts";
 
-const BLOCKED_NATIVE_TOOLS = Object.freeze(new Set(["read", "grep"]));
 /** How often to keep the parent sandbox's request watchdog alive during detached work. */
 const WATCHDOG_HEARTBEAT_MS = 30_000;
-const CAPPED_RESULT_TOOLS = Object.freeze(new Set(["bash", "find", "ls"]));
+/** Soft token guard — cap bulk tool stdout; do NOT hard-block read/grep/bash readers. */
+const CAPPED_RESULT_TOOLS = Object.freeze(new Set(["bash", "find", "ls", "read", "grep"]));
 
 export default function rlmExtension(pi: ExtensionAPI): void {
-  // Subagent children run a native tool flow; RLM's contract is the opposite
-  // (block read/grep, route through repl). Env fast path: full bypass when
+  // Subagent children may bypass full RLM registration. Env fast path when
   // PI_SUBAGENT_CHILD=1 (unless force-in under the depth cap). See mode/subagent.ts.
   if (isSubagentChildBypass()) {
     if (traceEnabled) {
@@ -124,16 +124,6 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     await seedPromise;
   };
 
-  // Load persisted settings async — applied before session_start handler reads controller state
-  const settingsReady = loadSettings()
-    .then((persisted) => {
-      controller.config = mergeConfig(persisted.config);
-      controller.savedLlmRef = persisted.llm;
-    })
-    .catch((err) => {
-      console.warn(`[rlm] settings load failed: ${errorMessage(err)}`);
-    });
-
   // ── Message renderers ──
   // Markdown themes are derived from the injected `theme`, never pi's module-global
   // `getMarkdownTheme()` — under jiti that global can be undefined inside a plugin.
@@ -162,8 +152,11 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   let guidePosted = false;
 
   pi.on("session_start", async (_event, ctx) => {
-    // Wait for persisted settings before reading controller state
-    await settingsReady;
+    // Re-read settings fresh from disk each session so a pin or config change
+    // made during a previous session takes effect.
+    const persisted = await loadSettings();
+    controller.config = mergeConfig(persisted.config);
+    controller.savedLlmRef = persisted.llm ?? undefined;
 
     // An explicit --rlm flag wins over the persisted setting for this session.
     const flag = pi.getFlag("rlm");
@@ -182,7 +175,23 @@ export default function rlmExtension(pi: ExtensionAPI): void {
 
     if (controller.savedLlmRef) {
       const resolved = resolveModelId(ctx.modelRegistry, controller.savedLlmRef);
-      if (resolved) controller.llmModel = resolved;
+      if (resolved) {
+        controller.llmModel = resolved;
+      } else {
+        // Keep the pin on disk/controller — do not fall back permanently. Runtime uses
+        // cheapest until the catalog has the model again; surface that once per session.
+        console.warn(
+          `[rlm] pinned sub-LLM ${controller.savedLlmRef} not in registry; using cheapest until it reappears`,
+        );
+        try {
+          ctx.ui.notify(
+            `RLM: pinned llm=${controller.savedLlmRef} unavailable — using cheapest until it is`,
+            "warning",
+          );
+        } catch {
+          // Some hosts have no UI at session_start.
+        }
+      }
     }
 
     // Re-register repl tool each session to pick up model provider changes
@@ -254,7 +263,7 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     const filtered = event.messages.filter(
       (message) =>
         !(message.role === "custom" && message.customType === "rlm-intro")
-        && !(message.role === "user" && typeof message.content === "string" && message.content === NATIVE_TURN_REMINDER),
+
     );
     if (!nativeTradeHolds()) return { messages: filtered };
 
@@ -266,11 +275,11 @@ export default function rlmExtension(pi: ExtensionAPI): void {
       listingPayloadRef = payload;
       const listing = formatContextListing(payload);
       const instruction = [
-        "ANALYZE with repl({code}) — read/grep are DISABLED.",
-        "Files you have loaded live in the Python REPL `context` variable (starts empty; cwd seeds on first repl()).",
-        "Locate with search()/grep_context()/outline() (free), then delegate bulk reading to",
-        "map_files()/llm_query_batched(). Use add_context(path) for external dirs/files/docs/git URLs.",
-        "If credits exhausted → report and stop.",
+        "Prefer repl({code}) for bulk analysis: free search/grep/outline, then fan-out Tasks.",
+        "Multi-module work → rlm_batch (or rlm_query); one-shot extracts → map_files/llm_batch.",
+        "Always-spawn returns Task (↯bg); only await_task has content — fire-all then await.",
+        "Large tool/repl outputs are capped. Files live in REPL `context` (cwd seeds first repl()).",
+        "add_context(path) for external dirs/files/docs/git. Credits exhausted → report and stop.",
         "",
       ].join("\n");
       filtered.unshift({
@@ -280,42 +289,38 @@ export default function rlmExtension(pi: ExtensionAPI): void {
       } as PiMessage);
     }
 
-    // Per-turn last-position reminder (not persisted — context hook rebuilds every request)
-    filtered.push({
-      role: "user" as const,
-      content: NATIVE_TURN_REMINDER,
-      timestamp: 0,
-    } as PiMessage);
 
     return { messages: filtered };
   });
 
-  // ── Native mode restrictions: keep bulk file content out of root-model context ──
-  // `edit`/`write` stay unblocked so the agent modifies files through Pi's native
-  // tool flow (visible to all plugins, +/- diff preview). File reading/searching
-  // belongs in the REPL, and bash output is capped as a backstop.
-  // Fail-open when repl is not active (e.g. --tools allowlist without repl): never
-  // confiscate readers without a working substitute (RLM paper §2 trade).
-  pi.on("tool_call", async (event) => {
-    if (!nativeTradeHolds()) {
-      if (traceEnabled && controller.enabled) {
-        trace("native.block_skip", { toolName: event.toolName, reason: "no_active_repl" });
+  // Soft token guard only — never hard-block read/grep/bash. Large tool results are capped.
+  // After edit/write, re-read disk into RLM context so search/llm see fresh content.
+  const MUTATING_FILE_TOOLS = Object.freeze(new Set(["edit", "write"]));
+
+  pi.on("tool_result", async (event, ctx) => {
+    // ── Keep RLM context fresh after native file mutations ──
+    if (
+      nativeTradeHolds()
+      && MUTATING_FILE_TOOLS.has(event.toolName)
+      && event.isError !== true
+    ) {
+      const cwd = resolve(ctx?.cwd ?? process.cwd());
+      const paths = extractEditPaths(event.input);
+      for (const p of paths) {
+        const body = await readDiskFile(p, cwd);
+        if (body === null) continue;
+        try {
+          await sandboxManager.refreshFileFromDisk(p, body, cwd);
+          // Listing must re-inject if we rewrote payload identity
+          listingPayloadRef = undefined;
+        } catch (err) {
+          if (traceEnabled) {
+            trace("context.refresh_fail", { path: p, error: errorMessage(err) });
+          }
+        }
       }
-      return;
-    }
-    if (BLOCKED_NATIVE_TOOLS.has(event.toolName)) {
-      return {
-        block: true,
-        reason: "RLM mode active. Use repl({code}) to read files and search the repository — loaded files live in the REPL `context` variable (cwd seeds on first call). Use `edit`/`write` for file changes. If sub-LLM credits are exhausted, report to the user.",
-      };
     }
-    const bashCommand = event.toolName === "bash" ? bashCommandFromInput(event.input) : undefined;
-    if (bashCommand !== undefined && isFileReadingCommand(bashCommand)) {
-      return { block: true, reason: BASH_BLOCK_REASON };
-    }
-  });
 
-  pi.on("tool_result", async (event) => {
     if (!nativeTradeHolds() || !CAPPED_RESULT_TOOLS.has(event.toolName)) return;
     let changed = false;
     const content = event.content.map((c) => {

package/src/mode/native-guards.ts

@@ -43,7 +43,7 @@ export function isFileReadingCommand(command: string): boolean {
 export const BASH_BLOCK_REASON =
   "RLM mode: reading files via bash is blocked — that dumps file content into the root model's " +
   "context. All files are pre-loaded in the REPL `context` variable: use repl({code}) with Python " +
-  "string/regex search, and delegate bulk analysis to llm_query / llm_query_batched / " +
+  "string/regex search, and delegate bulk analysis to llm_query / llm_batch / " +
   "llm_query_chunked. bash is for RUNNING things (tests, builds, git).";
 
 /** Max chars of tool output forwarded to the root model (≈1K tokens). */
@@ -51,12 +51,12 @@ export const TOOL_RESULT_CAP = 4_000;
 
 const CAP_NOTE =
   `\n[RLM: tool output capped at ${TOOL_RESULT_CAP.toLocaleString()} chars to protect the root ` +
-  "model's context — route bulk text through repl() + llm_query_chunked / llm_query_batched.]";
+  "model's context — route bulk text through repl() + llm_query_chunked / llm_batch.]";
 
 const REPL_CAP_NOTE =
   `\n[RLM: repl() stdout capped at ${TOOL_RESULT_CAP.toLocaleString()} chars — printing bulk text ` +
   "is useless. Keep results in REPL variables and delegate semantic reading to llm_query / " +
-  "llm_query_batched / llm_query_chunked.]";
+  "llm_batch / llm_query_chunked.]";
 
 /** Shared truncation core. Returns undefined when under the cap (leave the text untouched). */
 function capText(text: string, note: string): string | undefined {
@@ -86,7 +86,7 @@ export function replDelegationNudge(stdoutChars: number, delegated: boolean): st
   if (delegated || stdoutChars <= NUDGE_STDOUT_CHARS) return undefined;
   return (
     `\n[RLM: this repl() printed ${stdoutChars.toLocaleString()} chars with 0 sub-LLM calls — ` +
-    "if you were READING, delegate via llm_query / llm_query_batched / llm_query_chunked. " +
+    "if you were READING, delegate via llm_query / llm_batch / llm_query_chunked. " +
     "Authoring an edit body yourself is correct and needs no delegation.]"
   );
 }

package/src/mode/rlm-mode.ts

@@ -30,6 +30,8 @@ export interface StartInput {
 export class RlmController {
   llmModel: Model<Api> | undefined;
   savedLlmRef: string | undefined;
+  /** Set by applyLlmSelection when the user explicitly picks "cheapest (auto)". */
+  explicitClearPin = false;
   private active: AbortController | null = null;
 
   constructor(public config: RlmConfig) {}
@@ -58,7 +60,10 @@ export class RlmController {
   async persist(): Promise<boolean> {
     return await saveSettings({
       config: this.config,
-      llm: modelRef(this.llmModel) ?? this.savedLlmRef,
+      // null → explicit clear; undefined → merge from disk; string → set pin
+      llm: this.explicitClearPin
+        ? null
+        : (modelRef(this.llmModel) ?? this.savedLlmRef),
     });
   }
 

package/src/mode/subagent.ts

@@ -6,7 +6,7 @@
  *   2. Capability gate — never confiscate native readers unless `repl` is in the
  *      active tool set (paper trade: scaffold only if the REPL substitute exists).
  *
- * In-process rlm_query depth is handled by subcall-handlers.childRun; this module
+ * In-process rlm_query depth is handled by bridge/handlers childRun; this module
  * only covers OS-process children (pi subagents), which restart at depth 0.
  */
 import { DEFAULT_CONFIG } from "../config/defaults.ts";

package/src/prompts/glossary.ts

@@ -29,10 +29,10 @@ export function promptCapTokensK(maxPromptChars: number): number {
  */
 export const RETRIEVAL_GLOSSARY_LINES: readonly string[] = Object.freeze([
   "- `search(query: str, k=10, path_glob=None)`: BM25 ranking over `context`. Returns",
-  "  [{path, line, score, snippet}] — POINTERS, not bodies. **Start here.** It is free:",
-  "  no sub-LLM call, no tokens. Use it before you guess at filenames or write regex.",
+  "  [{path, line, score, snippet, text}] — POINTERS, not bodies (`text` aliases `snippet`).",
+  "  **Start here.** Free: no sub-LLM call. Use before guessing filenames.",
   "- `grep_context(pattern, k=50, path_glob=None, before=0, after=0) -> dict`: regex over",
-  "  `context`. Returns {hits: [{path, line, text}], counts: {path: n}, total, truncated} —",
+  "  `context`. Returns {hits: [{path, line, text, snippet}], counts, total, truncated} —",
   "  `counts` is complete even when `hits` is capped, so a wide pattern reports its shape",
   "  instead of flooding you. Use for exact lexical needles; use `search` for meaning.",
   "- `outline(path) -> str`: definition/heading skeleton of one file with line numbers.",
@@ -41,37 +41,38 @@ export const RETRIEVAL_GLOSSARY_LINES: readonly string[] = Object.freeze([
 
 /** One-line delegation helpers — orchestrating must be cheaper than solving. */
 export const DELEGATION_GLOSSARY_LINES: readonly string[] = Object.freeze([
-  "- `map_files(files, prompt, model=None) -> dict[path, str]`: ask `prompt` of every file and",
-  "  get back {path: answer}. Accepts context entries or paths, packs them into cap-sized",
-  "  batched sub-calls, and splits oversized files automatically. **This is the default way to",
-  "  read many files** — prefer it over hand-rolling a chunk loop.",
-  "- `llm_map_reduce(items, map_prompt, reduce_prompt, model=None) -> str`: map over items in",
-  "  one batch, then reduce the partial answers with a single call. The paper's canonical",
-  "  strategy (query per chunk → aggregate the buffers) as one call.",
+  "- `map_files(files, prompt) -> Task`: always spawn. `await_task(t)` → dict[path, answer].",
+  "  Accepts context entries or paths; packs into cap-sized batches; splits oversized files.",
+  "  **Default way to read many files** — fire independent `map_files` Tasks, free work, then await.",
+  "- `llm_map_reduce(items, map_prompt, reduce_prompt) -> str`: **blocks** (map then reduce).",
+  "  Prefer separate `map_files` / `llm_batch` Tasks when you can do free work between fan-out and collect.",
 ]);
 
 /** Shared glossary entry for the chunked-query helper (headless + native). */
 export const CHUNKED_GLOSSARY_LINES: readonly string[] = Object.freeze([
-  "- `llm_query_chunked(text: str, prompt: str, model=None) -> list[str]`: auto-splits `text` into",
-  "  chunks that fit the sub-LLM prompt cap, fans them out concurrently (order preserved), and",
-  "  returns one answer per chunk. Use it for ANY text too large for a single `llm_query` — a file",
-  "  you open()ed, an oversized sub-result, or several concatenated context files.",
+  "- `llm_query_chunked(text: str, prompt: str) -> Task`: always spawn. `await_task(t)` → list[str]",
+  "  (one answer per chunk, order preserved). Auto-splits text to the sub-LLM prompt cap.",
+  "  Use for ANY text too large for a single `llm_query` — open()ed files, oversized sub-results.",
 ]);
 
 /** Non-blocking fan-out: spawn now, collect later (headless glossary). */
 export const SPAWN_GLOSSARY_LINES: readonly string[] = Object.freeze([
-  "- `spawn(fn, *args) -> Task`: start `llm_query`, `llm_query_batched`, `llm_query_chunked`,",
-  "  `map_files`, `rlm_query` or `rlm_query_batched` WITHOUT waiting. Returns immediately.",
-  "  (Not `llm_map_reduce` — its reduce step depends on its own map results.)",
-  "- `rlm_await(task)` / `rlm_await_all(tasks) -> list`: collect results; order matches input.",
-  "  Tasks survive across turns, so spawn the slow work first, keep doing useful things, and",
-  "  await only when you actually need the results. `task.done` tells you if it has landed.",
+  "- **ALWAYS SPAWN (Task + ↯bg):** `llm_query` / `llm_batch` / `rlm_query` / `rlm_batch` /",
+  "  `map_files` / `llm_query_chunked`. Never treat the return as the answer.",
+  "  Collect with `await_task(t)` or `await_task([t1,t2,…])`. Fire independent Tasks first, free work, then await.",
+  "  Do NOT await after every independent spawn (serializes wall time). `task.done` when settled.",
+  "- `spawn(fn, *args) -> Task`: same as calling the always-spawn tools (not `llm_map_reduce`).",
+  "- Only `llm_map_reduce` still blocks until done.",
   "",
   "  ```python",
-  "  # start the slow sub-agents, then keep working while they run",
-  "  tasks = [spawn(rlm_query, f\"Audit {area} end to end\") for area in areas]",
-  "  hits = [f for f in context if \"TODO\" in f[\"content\"]]   # overlaps with the sub-agents",
-  "  reports = rlm_await_all(tasks)",
+  "  # Multi-area study: one rlm_batch (parallel workers), free locate, then await",
+  "  t = rlm_batch([",
+  "      \"Study module A — NO edits. Paths + symbols for X.\",",
+  "      \"Study module B — NO edits. Report how Y is configured.\",",
+  "  ])",
+  "  hits = search(\"X OR Y\", k=10)",
+  "  reports = await_task(t)",
+  "  # One-shot extracts: map_files / llm_batch also return Task → await_task",
   "  ```",
 ]);
 
@@ -89,7 +90,7 @@ export const RECURSION_CONTEXT_LINES: readonly string[] = Object.freeze([
   "  Narrow its world with `rlm_query(prompt, paths=['src/auth/', 'ctx/x-9f3a/'])` — path PREFIXES,",
   "  not globs. Omit `paths` to hand over everything.",
   "  Inheritance is one-way: sources the child loads, and its whole REPL, die with it — only its",
-  "  final answer string returns.",
+  "  final answer string returns. The child cannot write to your `answers` or `plan`.",
   "  At the depth cap `rlm_query` degrades to a plain sub-LLM call with NO context, which is why",
   "  this section disappears at the last recursive depth.",
 ]);
@@ -118,15 +119,15 @@ export const LARGE_FILE_RULE_LINES: readonly string[] = Object.freeze([
   '1. Load in Python: `raw = open("dhat-heap.json").read()` — loading into a variable is fine.',
   "2. Deterministic processing in Python (`json.load`, `re`, counting, aggregation) is fine and preferred.",
   "3. The moment you need MEANING from raw text (summarize, explain, find anomalies), do NOT read it",
-  "   yourself — call `llm_query_chunked(raw, question)`, or slice + `llm_query_batched`.",
+  "   yourself — call `llm_query_chunked(raw, question)` (Task → await_task), or slice + `llm_batch`.",
   "4. Never print more than a small probe (~2K chars) of raw content.",
-  'Example: `parts = llm_query_chunked(raw, "Extract top allocation sites with byte totals")`, then',
-  "aggregate `parts` in Python or with one final `llm_query`.",
+  'Example: `t = llm_query_chunked(raw, "Extract top allocation sites with byte totals"); parts = await_task(t)`, then',
+  "aggregate `parts` in Python or with one final `llm_query` + await_task.",
 ]);
 
 /** Concise native-mode glossary line for the chunked helper (native prompt has a 6K budget). */
 export const CHUNKED_GLOSSARY_LINE_NATIVE =
-  "- `llm_query_chunked(text, prompt, model=None) -> list[str]` — auto-splits oversized text into cap-sized chunks, fans out concurrently; one answer per chunk.";
+  "- `llm_query_chunked(text, prompt) -> Task` — always spawn; await_task → list[str] (one answer per chunk). Auto-splits oversized text.";
 
 /** Concise native-mode large-file rule (folds in the context-exclusion note; native 6K budget). */
 export const LARGE_FILE_RULE_NATIVE =
@@ -149,47 +150,45 @@ export const ENV_TIPS = [
   "## Decomposition doctrine",
   "",
   "**Orchestrate; don't solve.** A single chain of thought over a large repository drifts —",
-  "you lose partials and compound mistakes. Your sub-LLMs are competent readers: given a",
-  "self-contained prompt and the text, they will extract, locate, classify, and summarize",
-  "reliably. Trust them; don't do their reading yourself.",
+  "you lose partials and compound mistakes. Sub-workers are competent: trust them; don't read for them.",
   "",
-  "Your job: (1) find the relevant slice with `search` / `grep_context` / `outline`,",
-  "(2) delegate all semantic reading to `map_files` / `llm_query_batched` / `llm_map_reduce`,",
-  "(3) memoize every result you will reuse in `answers`, (4) sanity-check an answer before",
-  "another step depends on it, (5) assemble the final answer from `answers` by lookup.",
+  "Your job: (1) free locate with `search` / `grep_context` / `outline`,",
+  "(2) fan out: **multi-step areas → `rlm_batch` / `rlm_query`**; one-shot extracts →",
+  "  `map_files` / `llm_batch` (all return Task — `await_task` for content),",
+  "(3) memoize into `answers`, (4) sanity-check before dependents, (5) assemble from `answers`.",
   "Your own compute is: pointers, dict lookups, string formatting, and decisions.",
   "",
   "### The only state that matters",
   "`answers` and `plan` are dicts that persist across every turn.",
-  "**If a value isn't in `answers`, it doesn't exist.** Do not trust a number from your own",
-  "earlier reasoning or from truncated stdout — context drifts. Memoize everything you reuse.",
+  "**If a value isn't in `answers`, it doesn't exist.** Do not trust truncated stdout. Memoize.",
   "",
   "### Shape of a run",
-  "1. Probe: `print(len(context))`, `search(<the user's question>)`. Do not print file bodies.",
-  "2. Plan: write the sub-questions into `plan`; each must be answerable from a named slice.",
-  "3. Fan out: one `map_files` / `llm_query_batched` per independent group, not one call per",
-  "   file. Store results into `answers` keyed by path or sub-question.",
-  "4. Assemble: build the answer from `answers`. Delegate the aggregation too if it is large.",
+  "1. Probe: `print(len(context))`, `search(<question>)`. Do not print file bodies.",
+  "2. Plan: sub-questions into `plan` (each from a named slice / module).",
+  "3. Fan out **in parallel**: one `rlm_batch` for independent multi-step studies, or",
+  "   `map_files` / `llm_batch` for one-shot reads — not one serial call per file.",
+  "4. Assemble from `answers`.",
   "",
   "### Red flags — you are off track",
-  "- Printing file bodies to read them yourself → stop, delegate to `map_files`.",
-  "- Writing regex to *infer meaning* (naming conventions, intent, correctness) → that is a",
-  "  sub-LLM job. Regex is for exact lexical needles only.",
-  "- Two turns in with zero sub-LLM calls on an analysis task → you are solving it yourself.",
-  "- About to reuse a value that is not in `answers` → re-derive it and store it.",
-  "- One sub-call per file over dozens of files → batch them; fat prompts in small batches win.",
+  "- Printing file bodies / native bulk read → stop; use map_files or rlm_*.",
+  "- `llm_query(\"Read src/foo.ts…\")` with only a path — sub-LLM has **no disk**; use map_files/rlm_*.",
+  "- Multi-module task with zero `rlm_batch`/`rlm_query`/`map_files` → under-delegating.",
+  "- Await after every independent spawn → serializes wall time; fire-all-then-await.",
+  "- Treating Task as the answer without `await_task`.",
+  "- Regex used to *infer meaning* → sub-LLM job. Regex is for exact needles only.",
+  "- Two turns with zero sub-LLM calls on analysis → solving it yourself.",
 ].join("\n");
 
 /** Native-mode variant of the doctrine — same rules, sized for the native prompt budget. */
 export const ENV_TIPS_CONDENSED = [
-  "### Decomposition doctrine (paper App. C.3 — worth +69.5% there)",
-  "Orchestrate; don't solve. Loop: `search`/`grep_context`/`outline` to find the slice →",
-  "`map_files` / `llm_query_batched` to read it → memoize into `answers` → assemble by lookup.",
-  "`answers` and `plan` persist across every turn: **if a value isn't in `answers`, it",
-  "doesn't exist** — never reuse a number from your own earlier reasoning or truncated stdout.",
-  "Red flags: printing file bodies to read them; regex used to infer meaning rather than match",
-  "a literal; two turns into an analysis with zero sub-LLM calls; one sub-call per file instead",
-  "of one batch. Exception — AUTHORING is not reading: you write every edit body yourself.",
+  "### Decomposition doctrine",
+  "Orchestrate; don't solve. Free locate → fan-out Tasks → await_task → memoize in `answers`.",
+  "Multi-module / multi-step areas: **`rlm_batch` (or rlm_query)** — not serial native read.",
+  "One-shot extracts: `map_files` / `llm_batch`. Always Task → await_task; fire-all then await.",
+  "`answers`/`plan` persist: **if it isn't in `answers`, it doesn't exist.**",
+  "Red flags: bulk file dumps; llm_query with path-only (no content — no disk!); zero rlm_*/map_files",
+  "on multi-area tasks; await after each spawn; Task treated as answer.",
+  "AUTHORING: you write every edit body yourself.",
 ].join("\n");
 
 export function howToRunCode(): string {
@@ -224,21 +223,22 @@ export function replGlossary(
     if (child) lines.push(...CHILD_CONTEXT_LINES);
     lines.push(
       "",
-      "  Worked example — find the slice, then delegate it:",
+      "  Worked example — find the slice, then delegate it (Task + await):",
       "  ```python",
       '  hits = search("where is the retry/backoff policy configured?", k=8)',
       "  paths = sorted({h['path'] for h in hits})",
-      '  answers.update(map_files(paths, "Describe any retry/backoff policy in this file, with line numbers. Say NONE if absent."))',
+      '  t = map_files(paths, "Describe any retry/backoff policy in this file, with line numbers. Say NONE if absent.")',
+      "  answers.update(await_task(t))",
       "  print({p: a[:80] for p, a in answers.items()})",
       "  ```",
     );
   }
   lines.push(...RETRIEVAL_GLOSSARY_LINES);
   lines.push(
-    "- `llm_query(prompt: str, model=None) -> str`: a single sub-LLM completion. Use for extraction,",
-    "  summarization, or Q&A over a chunk of text.",
-    "- `llm_query_batched(prompts: list[str], model=None) -> list[str]`: run several sub-LLM calls",
-    "  concurrently; output order matches input order.",
+    "- `llm_query(prompt: str) -> Task`: spawn one sub-LLM (await_task for str). The prompt must",
+    "  **contain the text** to analyze — this call has no filesystem and no `context`.",
+    "- `llm_batch(prompts: list[str]) -> Task`: many parallel one-shots (same rule: embed text).",
+    "  await_task → ordered list[str]. NEVER pass bare file paths as if the worker can open them.",
     ...CHUNKED_GLOSSARY_LINES,
     ...SPAWN_GLOSSARY_LINES,
     ...DELEGATION_GLOSSARY_LINES,
@@ -264,18 +264,14 @@ export function replGlossary(
   }
   if (recursion) {
     lines.push(
-      "- `rlm_query(prompt, model=None)` / `rlm_query_batched(prompts, model=None)`: recursive RLM",
-      "  sub-calls. Each child runs a full REPL loop internally — its entire conversation is PRIVATE",
-      "  and never enters your history. Only the final answer (a short string) is returned.",
+      "- `rlm_query(task, paths=None) -> Task` / `rlm_batch(tasks, paths=None) -> Task`:",
+      "  always spawn + ↯bg. await_task for the report string(s). Child REPL is private.",
       "",
-      "  **Choosing between `llm_query` and `rlm_query`:**",
-      "  - `llm_query` for simple one-shot tasks — summarize a chunk, extract a fact, answer a direct",
-      "    question. It is a single LLM call: fast and cheap. Prefer it by default, and fan out with",
-      "    `llm_query_batched` for parallel one-shots.",
-      "  - `rlm_query` only when a sub-task genuinely needs iterative reasoning with its own code",
-      "    execution (e.g. a sub-context large enough to need its own chunking, or a multi-step",
-      "    reasoning chain). It is slower and more expensive — reserve it for cases `llm_query` cannot",
-      "    handle. Avoid excessive recursive sub-calls when a batched one-shot would suffice.",
+      "  **Routing (api_v5):**",
+      "  - `llm_query` / `llm_batch` / `map_files` — one-shot facts/extracts (fast).",
+      "  - `rlm_query` — one multi-step study (own search/outline loop).",
+      "  - `rlm_batch` — ≥2 independent multi-step studies in **parallel** (prefer over N× rlm_query).",
+      "  Always Task → await_task. Fire independent work first; never serial-await between peers.",
       ...RECURSION_CONTEXT_LINES,
     );
   }
@@ -285,6 +281,7 @@ export function replGlossary(
     "- `SHOW_VARS() -> str`: list every variable currently in the REPL.",
     '- `answer`: a dict initialized to {"content": "", "ready": False}. To submit your final answer,',
     '  set `answer["content"]` to the answer text and `answer["ready"] = True`.',
+    '  **You MUST flip `answer["ready"] = True` — runs that never finalize are discarded.**',
   );
   return lines.join("\n");
 }