@hicaru/pi-rlm 0.3.6 → 0.3.8

package/src/core/types.ts

@@ -15,9 +15,10 @@ export interface RlmConfig {
   readonly maxDepth: number;
   /** Max turns before the engine must finalize. */
   readonly maxIterations: number;
-  /** Per-`repl`-block wall-clock timeout inside the worker (seconds). */
+  /** Per-`repl`-block wall-clock timeout inside the worker (seconds).
+   *  v5 doctrine: content limits are the token budget's job — this is a HANG backstop only. */
   readonly execTimeoutS: number;
-  /** Parent-side watchdog per sandbox request (ms). */
+  /** Parent-side watchdog per sandbox request (ms). Hang backstop (see execTimeoutS). */
   readonly requestTimeoutMs: number;
   /** Concurrency pool for *_batched sub-calls. */
   readonly maxConcurrentSubcalls: number;
@@ -28,7 +29,10 @@ export interface RlmConfig {
   readonly maxPromptChars: number;
   /** Max wall-clock ms across the whole tree before the engine stops (undefined = no cap). */
   readonly maxTimeoutMs?: number;
-  /** Max total input+output tokens across the whole tree before the engine stops (undefined = no cap). */
+  /** Max total input+output tokens across the whole tree before the engine stops (undefined = no cap).
+ *  ⚠ HARD ABORT (audit H8): when set, exceeding this throws a LimitError mid-run and the run
+ *  ends with its best partial — NO wrap-up, NO continuation. The graceful path is the v5
+ *  token budget (`enableTokenBudget`); leave this unset unless a hard tree-wide stop is wanted. */
   readonly maxTokens?: number;
   /** Max consecutive error turns before the engine stops (undefined = no cap). */
   readonly maxErrors?: number;
@@ -61,6 +65,37 @@ export interface RlmConfig {
   readonly subSystemPrompt?: string;
   /** Sampling for sub-LLM (worker) calls. */
   readonly subSampling: Readonly<Sampling>;
+  /** v5 token budget: cap = budgetShare × contextWindow, clamped by budgetTaskCap. When on,
+   *  the budget is the PRIMARY run-length control (soft wrap-up → continuation chain). */
+  readonly enableTokenBudget: boolean;
+  /** Fraction of the model's context window that forms one run's token cap. */
+  readonly budgetShare: number;
+  /** Soft wrap-up fires at this fraction of the cap (one wrap-up turn). */
+  readonly budgetSoftFrac: number;
+  /** Absolute single-run ceiling; 0 = no clamp beyond the share. */
+  readonly budgetTaskCap: number;
+  /** Max continuation runs after a hard stop (chain ≤ 1 + this). */
+  readonly budgetMaxContinuations: number;
+  /** Char budget for the deterministic continuation handoff. */
+  readonly budgetHandoffChars: number;
+  /** v5 TaskLedger blackboard: claim coalescing + ancestor-echo reject + `[ledger]` injection. */
+  readonly enableLedger: boolean;
+  /** Real rlm spawns allowed before extra rlm_query demotes to llm_query (0 = never). */
+  readonly rlmBudget: number;
+  /** v5 durable memory: L1 episode replay + L2 BM25 notes under `<root>/.rlm/memory`. */
+  readonly enableMemory: boolean;
+  /** Char budget for the `[memory]` injection = tokens × 4. */
+  readonly injectNoteTokens: number;
+  /** Pending episodes per L2 consolidation batch (0 = never auto-consolidate). */
+  readonly evolveEvery: number;
+  /** Override the memory dir. `null` (default) = `<root>/.rlm/memory` — this field only
+ *  RELOCATES the store; the on/off switch is `enableMemory` (audit M3). */
+  readonly memoryDir: string | null;
+  /** v5: per-provider concurrent-request caps (e.g. `{ zai: 4 }`). Caps only lower limits. */
+  readonly providerMaxConcurrent?: Readonly<Record<string, number>>;
+  /** v5 doctrine: "delegation" = child engines get llm/memory/ledger only (no repo retrieval);
+   *  "legacy" keeps today's full child surface as a one-flip rollback. */
+  readonly childSurface: "delegation" | "legacy";
 }
 
 /** Input to a (headless) RLM run. */
@@ -75,6 +110,12 @@ export interface RlmInput {
   readonly parentNodeId?: string;
   /** Remaining timeout for this subtree (set by parent from its LimitGuard). */
   readonly remainingTimeoutMs?: number;
+  /** v5: budget for this run. Set only by the engine itself when chaining a continuation —
+   *  a fresh budget is resolved from config when omitted. */
+  readonly budget?: import("./budget.ts").TokenBudget;
+  /** v5: the shared TaskLedger blackboard. Children inherit the parent's instance —
+   *  set by childRun (the one child-RlmInput construction path); a fresh run gets a new one. */
+  readonly ledger?: import("./ledger.ts").TaskLedger;
 }
 
 /** Result of a completed RLM run. */

package/src/index.ts

@@ -4,6 +4,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Markdown } from "@earendil-works/pi-tui";
 import { registerRlmCommand } from "./commands/rlm.ts";
 import { registerRlmConfigCommand } from "./commands/rlm-config.ts";
+import type { RlmConfig } from "./core/types.ts";
 import { createRlmTool } from "./tool/rlm-tool.ts";
 import { createReplTool } from "./tool/repl-tool.ts";
 import { loadSettings, mergeConfig, resolveModelId } from "./config/settings.ts";
@@ -12,9 +13,12 @@ import { cheapestModel } from "./mode/llm-model.ts";
 import { postRlmGuide } from "./ui/intro.ts";
 import { setRlmModeStatus } from "./ui/status.ts";
 import { markdownTheme } from "./ui/theme-adapter.ts";
+import { SANDBOX_WATCHDOG_HEARTBEAT_MS } from "./sandbox/sandbox.ts";
 import { SandboxManager } from "./sandbox/sandbox-manager.ts";
-import { createSubcallGates } from "./util/concurrency.ts";
+import { buildSessionGates, type SubcallGates } from "./util/concurrency.ts";
 import { BackgroundTasks } from "./tool/background-tasks.ts";
+import { MemoryStore } from "./core/memory.ts";
+import { modelComplete } from "./bridge/model.ts";
 import { resolve } from "node:path";
 import { resolveSource } from "./context/resolve.ts";
 import { formatContextListing } from "./context/listing.ts";
@@ -38,8 +42,6 @@ export {
   processRlmDepth,
 } from "./mode/subagent.ts";
 
-/** How often to keep the parent sandbox's request watchdog alive during detached work. */
-const WATCHDOG_HEARTBEAT_MS = 30_000;
 /** 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"]));
 
@@ -62,7 +64,21 @@ export default function rlmExtension(pi: ExtensionAPI): void {
 
   // Init synchronously with defaults — ensures commands/tools/handlers register before session_start
   const config = mergeConfig({});
-  const controller = new RlmController(config);
+  // v5 durable memory: one store per session under <cwd>/.rlm/memory (L1 replay + L2 notes).
+  // NOTE (audit M4): this store IS shared by both composition roots, but the TaskLedger is
+  // NOT — the native repl() session and each headless rlm run each keep their own blackboard
+  // (v5 parity: per-run ledger). Claims/coalescing reset at that boundary, by design.
+  // The consolidation LLM + real workspace root are attached in session_start (setLlm/setRoot).
+  const memory = new MemoryStore(
+    process.cwd(),
+    {
+      dir: config.memoryDir ?? undefined,
+      injectNoteTokens: config.injectNoteTokens,
+      evolveEvery: config.evolveEvery,
+    },
+    config.enableMemory,
+  );
+  const controller = new RlmController(config, memory);
   let onSandboxDiscardExtra: (() => void) | undefined;
   const sandboxManager = new SandboxManager({
     execTimeoutS: config.execTimeoutS,
@@ -75,9 +91,8 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     awaitTimeoutS: Math.round(config.requestTimeoutMs / 1000),
     onSandboxDiscarded: () => { onSandboxDiscardExtra?.(); },
   });
-  // One admission gate for the whole session: spawn() lets the sandbox put many requests on
-  // the wire at once, so nothing smaller than session scope actually bounds fan-out.
-  const gates = createSubcallGates(config.maxConcurrentSubcalls, config.maxConcurrentChildren);
+  // v5: sub-call admission is built per session (see session_start) so provider concurrency
+  // caps resolve against the models actually in use.
   const background = new BackgroundTasks({
     maxTimeoutMs: config.maxTimeoutMs,
     maxTokens: config.maxTokens,
@@ -88,7 +103,7 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   // with it. Keep it alive while detached work is genuinely in flight.
   const watchdogHeartbeat = setInterval(() => {
     if (background.pending > 0) sandboxManager.refreshWatchdog();
-  }, WATCHDOG_HEARTBEAT_MS);
+  }, SANDBOX_WATCHDOG_HEARTBEAT_MS);
   watchdogHeartbeat.unref();
 
   /** Memoised cwd seed — one resolveSource(pathPrefix:"") per session. */
@@ -198,6 +213,40 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     const llmModel = controller.llmModel ?? cheapestModel(ctx.modelRegistry) ?? ctx.model;
     const model = ctx.model;
     if (llmModel && model) {
+      // Consolidation runs on the cheap worker model through the single completion entry point;
+      // the workspace root is only known once the session starts.
+      const consolidateModel = llmModel;
+      memory.setLlm((prompt) =>
+        modelComplete([{ role: "user", content: prompt }], { model: consolidateModel, registry: ctx.modelRegistry })
+          .then((r) => r.text));
+      memory.setRoot(ctx.cwd ?? process.cwd());
+      // v5 provider caps (audit C1/C6): ONE resolver shared by both composition roots — the
+      // repl() tool and RlmController.start admit through the same pool, each gate capped
+      // against the model that actually runs on it (leaves = worker, children = smart).
+      // Memoized on (config, providers) so /rlm-config changes apply without a restart.
+      let gatesMemo:
+        | { readonly config: RlmConfig; readonly smart: string; readonly worker: string; readonly gates: SubcallGates }
+        | undefined;
+      const resolveSessionGates = (): SubcallGates => {
+        const smart = model;
+        const worker = controller.llmModel ?? cheapestModel(ctx.modelRegistry) ?? model;
+        const workerProvider = worker.provider;
+        if (
+          gatesMemo === undefined ||
+          gatesMemo.config !== controller.config ||
+          gatesMemo.smart !== smart.provider ||
+          gatesMemo.worker !== workerProvider
+        ) {
+          gatesMemo = {
+            config: controller.config,
+            smart: smart.provider,
+            worker: workerProvider,
+            gates: buildSessionGates(controller.config, smart.provider, workerProvider),
+          };
+        }
+        return gatesMemo.gates;
+      };
+      controller.setSessionGates(resolveSessionGates);
       try {
         pi.registerTool(createReplTool({
           sandboxManager,
@@ -207,8 +256,10 @@ export default function rlmExtension(pi: ExtensionAPI): void {
           getLlmModel: () => controller.resolveModels(ctx)?.llm,
           registry: ctx.modelRegistry,
           getConfig: () => controller.config,
-          gates,
+          gates: resolveSessionGates(),
+          resolveGates: resolveSessionGates,
           background,
+          memory,
           registerDiscardHook: (reset) => { onSandboxDiscardExtra = reset; },
           registerContextBundle: (bundle) => {
             contextBundleRef = bundle;

package/src/mode/rlm-mode.ts

@@ -9,13 +9,16 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { modelRef, resolveModelId, saveSettings } from "../config/settings.ts";
-import { createEngine } from "../core/engine.ts";
+import { createEngine, type EngineDeps } from "../core/engine.ts";
 import { limitsFromConfig } from "../core/limits.ts";
 import type { RlmConfig, RlmResult } from "../core/types.ts";
 import { resolveSource } from "../context/resolve.ts";
 import { RlmEmitter } from "../tool/rlm-events.ts";
 import { formatError } from "../util/errors.ts";
 import { cheapestModel } from "./llm-model.ts";
+import type { MemoryStore } from "../core/memory.ts";
+import type { RunRlm } from "../core/types.ts";
+import type { SubcallGates } from "../util/concurrency.ts";
 
 export interface RunHandle {
   readonly abort: () => void;
@@ -33,8 +36,19 @@ export class RlmController {
   /** Set by applyLlmSelection when the user explicitly picks "cheapest (auto)". */
   explicitClearPin = false;
   private active: AbortController | null = null;
-
-  constructor(public config: RlmConfig) {}
+  /** v5: session admission gates (provider-capped), shared with the repl() tool — set at
+   *  session_start so BOTH composition roots admit through one pool (audit C1). */
+  private sessionGates: (() => SubcallGates) | undefined;
+
+  constructor(
+    public config: RlmConfig,
+    /** v5 durable memory — shared with the repl tool so child runs replay/persist too. */
+    public readonly memory?: MemoryStore,
+  ) {}
+
+  setSessionGates(getGates: () => SubcallGates): void {
+    this.sessionGates = getGates;
+  }
 
   get enabled(): boolean {
     return this.config.enabled;
@@ -83,6 +97,33 @@ export class RlmController {
     return { model, llm };
   }
 
+  /** Test seam (audit R7): intercept the exact object `createEngine` receives. */
+  protected spawnEngine(deps: EngineDeps): RunRlm {
+    return createEngine(deps);
+  }
+
+  /** The ONE engine construction path for this controller (DRY #6 — a second path that
+   *  forgets to grow is exactly how issue #4 and audit C1 happened). Protected so tests can
+   *  subclass and assert the wiring without touching the network. */
+  protected buildEngine(args: {
+    readonly ctx: ExtensionContext;
+    readonly models: { readonly model: Model<Api>; readonly llm: Model<Api> };
+    readonly signal: AbortSignal;
+    readonly emitter: RlmEmitter;
+  }): RunRlm {
+    return this.spawnEngine({
+      model: args.models.model,
+      llmModel: args.models.llm,
+      registry: args.ctx.modelRegistry,
+      config: this.config,
+      signal: args.signal,
+      emitter: args.emitter,
+      limits: limitsFromConfig(this.config),
+      memory: this.memory,
+      gates: this.sessionGates?.(),
+    });
+  }
+
   start(ctx: ExtensionContext, input: StartInput, emitter?: RlmEmitter): RunHandle {
     const models = this.resolveModels(ctx);
     if (!models) throw new Error("no model with configured auth is available");
@@ -102,14 +143,11 @@ export class RlmController {
           ? result.value.payload
           : formatError(`failed to pack repository — ${result.error}`);
       }
-      const engine = createEngine({
-        model: models.model,
-        llmModel: models.llm,
-        registry: ctx.modelRegistry,
-        config: this.config,
+      const engine = this.buildEngine({
+        ctx,
+        models,
         signal: abortController.signal,
         emitter: emitter ?? new RlmEmitter(),
-        limits: limitsFromConfig(this.config),
       });
       return await engine({ rootPrompt: input.rootPrompt, context: contextValue, depth: 0 });
     })().finally(() => {

package/src/prompts/glossary.ts

@@ -39,6 +39,16 @@ export const RETRIEVAL_GLOSSARY_LINES: readonly string[] = Object.freeze([
   "  Orient in ~200 chars instead of printing 20K. Matches exact path, then suffix, then glob.",
 ]);
 
+/** v5 delegation doctrine (audit C5): children have NO retrieval tools — their world is the
+ *  sliced `context` they were handed. This REPLACES the retrieval lines in child prompts so
+ *  the prompt and the runtime sandbox agree (a child taught to `search` burns turns on NameError). */
+export const DELEGATION_SURFACE_LINES: readonly string[] = Object.freeze([
+  "- **No `search` / `grep_context` / `outline` / `add_context` in this REPL** (delegation",
+  "  surface, v5 doctrine): your task arrived WITH its world in `context`. Explore it with",
+  "  Python (list comprehensions, string matching, slicing) and delegate slices to sub-LLMs —",
+  "  never re-ask the parent for retrieval.",
+]);
+
 /** One-line delegation helpers — orchestrating must be cheaper than solving. */
 export const DELEGATION_GLOSSARY_LINES: readonly string[] = Object.freeze([
   "- `map_files(files, prompt) -> Task`: always spawn. `await_task(t)` → dict[path, answer].",
@@ -57,12 +67,21 @@ export const CHUNKED_GLOSSARY_LINES: readonly string[] = Object.freeze([
 
 /** Non-blocking fan-out: spawn now, collect later (headless glossary). */
 export const SPAWN_GLOSSARY_LINES: readonly string[] = Object.freeze([
-  "- **ALWAYS SPAWN (Task + ↯bg):** `llm_query` / `llm_batch` / `rlm_query` / `rlm_batch` /",
+  "- **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.",
+  "  Collect with `await_task(t)`, `await_task([t1,t2,…])`, or `await_task()` (every still-running Task).",
+  "  If `await_task` returns `Error: sub-call still running`, call it again — do not respawn.",
+  "  `list_tasks()` → [{kind, label, done, var}]. Fire independent Tasks first, free work, then await.",
   "  Do NOT await after every independent spawn (serializes wall time). `task.done` when settled.",
+  "- `[ledger]` global state: the blackboard in your prompt lists inflight/done agent claims.",
+  "  NEVER `rlm_query` a task already on `[ledger]` (await it / reuse the result); ancestor",
+  "  echo is rejected with a stub. `list_claims()` shows the live table anytime.",
   "- `spawn(fn, *args) -> Task`: same as calling the always-spawn tools (not `llm_map_reduce`).",
   "- Only `llm_map_reduce` still blocks until done.",
+]);
+
+/** v5 (audit C5): the spawn worked example, retrieval flavor — root surface only. */
+export const SPAWN_EXAMPLE_RETRIEVAL: readonly string[] = Object.freeze([
   "",
   "  ```python",
   "  # Multi-area study: one rlm_batch (parallel workers), free locate, then await",
@@ -76,11 +95,20 @@ export const SPAWN_GLOSSARY_LINES: readonly string[] = Object.freeze([
   "  ```",
 ]);
 
-/**
- * What a parent must know about the child it is about to spawn. Without this the model writes
- * referential prompts ("read lib/x/src/…") on the assumption the child can go fetch them, which
- * is what made a missing child context degrade silently instead of failing (issue #4).
- */
+/** v5 (audit C5): the spawn worked example, delegation flavor — no retrieval, slice instead. */
+export const SPAWN_EXAMPLE_DELEGATION: readonly string[] = Object.freeze([
+  "",
+  "  ```python",
+  "  # Multi-area study: one rlm_batch (parallel workers), slice your world while they run",
+  "  t = rlm_batch([",
+  "      \"Answer from the FIRST half of the context only: paths + symbols for X.\",",
+  "      \"Answer from the SECOND half only: report how Y is configured.\",",
+  "  ])",
+  "  half = [f['path'] for f in context[:len(context)//2]]  # free work while Tasks run",
+  "  reports = await_task(t)",
+  "  # One-shot extracts: map_files / llm_batch also return Task → await_task",
+  "  ```",
+]);
 export const RECURSION_CONTEXT_LINES: readonly string[] = Object.freeze([
   "",
   "  **What a child sees:** it inherits YOUR `context` — every file you have loaded, including",
@@ -95,6 +123,19 @@ export const RECURSION_CONTEXT_LINES: readonly string[] = Object.freeze([
   "  this section disappears at the last recursive depth.",
 ]);
 
+/** v5 recursion section, delegation variant (audit C5): describes what a delegation child
+ *  receives — the narrowed pack as text, no retrieval of its own. */
+export const RECURSION_DELEGATION_LINES: readonly string[] = Object.freeze([
+  "",
+  "  **What a child sees:** it inherits YOUR `context` (narrowed by `paths=` when given) and works",
+  "  on it as text — it has NO retrieval tools, so put what matters in your prompt and `paths`,",
+  "  never file bodies you already share (that costs tokens twice and buys nothing).",
+  "  Inheritance is one-way: sources the child loads, and its whole REPL, die with it — only its",
+  "  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.",
+]);
+
 /**
  * Sub-RLM orientation. Emitted only at depth > 0, where `context` is the parent's world rather
  * than a repository the run packed for itself.
@@ -146,38 +187,52 @@ export const LARGE_FILE_RULE_NATIVE =
  * The paper is explicit (App. B) that one prompt does not port across models and that both
  * guardrails are needed; keep them both.
  */
-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. Sub-workers are competent: trust them; don't read for them.",
-  "",
-  "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 truncated stdout. Memoize.",
-  "",
-  "### Shape of a run",
-  "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 / 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");
+/** Decomposition doctrine. `delegation` drops retrieval names (audit R3) — children
+ *  have no `search` and must not be told to locate with it. */
+export function envTips(delegation = false): string {
+  const locate = delegation
+    ? "Your job: (1) slice `context` with Python (indexing, string matching, comprehensions),"
+    : "Your job: (1) free locate with `search` / `grep_context` / `outline`,";
+  const probe = delegation
+    ? "1. Probe: `print(len(context))`; locate targets with Python slicing / string matching. Do not print file bodies."
+    : "1. Probe: `print(len(context))`; locate targets with `search` when your surface has it, else\n   Python slicing / string matching. Do not print file bodies.";
+  return [
+    "## Decomposition doctrine",
+    "",
+    "**Orchestrate; don't solve.** A single chain of thought over a large repository drifts —",
+    "you lose partials and compound mistakes. Sub-workers are competent: trust them; don't read for them.",
+    "",
+    locate,
+    "(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 result isn't in `answers`, you have not memoized it.** Task handles are REPL vars —",
+    "`list_tasks()` / `SHOW_VARS()` find them. Do not trust truncated stdout. Memoize after await_task.",
+    "",
+    "### Shape of a run",
+    probe,
+    "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 / 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");
+}
+
+/** Root-surface doctrine (back-compat alias of `envTips(false)`). */
+export const ENV_TIPS = envTips(false);
 
 /** Native-mode variant of the doctrine — same rules, sized for the native prompt budget. */
 export const ENV_TIPS_CONDENSED = [
@@ -185,7 +240,7 @@ export const ENV_TIPS_CONDENSED = [
   "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.**",
+  "`answers`/`plan` persist collected results. Task handles are REPL vars (`list_tasks()` / `SHOW_VARS()`).",
   "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.",
@@ -204,6 +259,7 @@ export function replGlossary(
   recursion: boolean,
   contextLoader: boolean,
   child: boolean,
+  delegation = false,
 ): string {
   const lines = ["Available in the REPL:"];
   if (kind === "text") {
@@ -221,19 +277,36 @@ export function replGlossary(
       CONTEXT_EXCLUSION_NOTE,
     );
     if (child) lines.push(...CHILD_CONTEXT_LINES);
-    lines.push(
-      "",
-      "  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})",
-      '  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()})",
-      "  ```",
-    );
+    if (delegation) {
+      lines.push(
+        "",
+        "  Worked example — slice the world you were handed, then delegate it (Task + await):",
+        "  ```python",
+        "  slice = [f for f in context if f['path'].startswith('src/auth/')][:6]",
+        "  prompts = [f\"Answer from this file only.\\n\\n{f['content'][:4000]}\" for f in slice]",
+        "  t = llm_batch(prompts)",
+        "  answers.update(dict(zip([f['path'] for f in slice], await_task(t))))",
+        "  ```",
+      );
+    } else {
+      lines.push(
+        "",
+        "  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})",
+        '  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()})",
+        "  ```",
+      );
+    }
+  }
+  if (delegation) {
+    lines.push(...DELEGATION_SURFACE_LINES);
+  } else {
+    lines.push(...RETRIEVAL_GLOSSARY_LINES);
   }
-  lines.push(...RETRIEVAL_GLOSSARY_LINES);
   lines.push(
     "- `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`.",
@@ -241,9 +314,10 @@ export function replGlossary(
     "  await_task → ordered list[str]. NEVER pass bare file paths as if the worker can open them.",
     ...CHUNKED_GLOSSARY_LINES,
     ...SPAWN_GLOSSARY_LINES,
+    ...(delegation ? SPAWN_EXAMPLE_DELEGATION : SPAWN_EXAMPLE_RETRIEVAL),
     ...DELEGATION_GLOSSARY_LINES,
   );
-  if (contextLoader) {
+  if (contextLoader && !delegation) {
     lines.push(
       "- `add_context(source: str) -> dict`: load a dir, file, document, or git URL and **APPEND its",
       "  files into `context`** (same shape: path/content/tokens). Documents (PDF, DOCX, XLSX, PPTX,",
@@ -264,21 +338,29 @@ export function replGlossary(
   }
   if (recursion) {
     lines.push(
-      "- `rlm_query(task, paths=None) -> Task` / `rlm_batch(tasks, paths=None) -> Task`:",
+      "- `rlm_query(task|prompt, paths=None) -> Task` / `rlm_batch(tasks|prompts, paths=None) -> Task`:",
       "  always spawn + ↯bg. await_task for the report string(s). Child REPL is private.",
+      "  Both spellings accepted; prefer `task`/`tasks`.",
       "",
       "  **Routing (api_v5):**",
       "  - `llm_query` / `llm_batch` / `map_files` — one-shot facts/extracts (fast).",
-      "  - `rlm_query` — one multi-step study (own search/outline loop).",
+      delegation
+        ? "  - `rlm_query` — one multi-step study (its own delegation loop; it cannot search either)."
+        : "  - `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,
+      ...(delegation ? RECURSION_DELEGATION_LINES : RECURSION_CONTEXT_LINES),
     );
   }
   lines.push(
     "- `answers` / `plan`: two dicts that persist across turns. Memoize every",
     "  verified result in `answers` — see the decomposition doctrine below.",
-    "- `SHOW_VARS() -> str`: list every variable currently in the REPL.",
+    "- `SHOW_VARS() -> str`: list every variable currently in the REPL (Task handles show as `<Task …>`).",
+    "- `list_tasks()`: every Task this REPL created — [{kind, label, done, var}].",
+    "- `memory.query(q) -> str` / `memory.add(text, paths=…, tags=…)`: durable notes under `.rlm/`",
+    "  that survive across sessions. Query before re-studying a known area; add concise findings",
+    "  (facts, locations, decisions) — never secrets or API keys (notes persist on disk).",
+    "- `list_claims()`: the live `[ledger]` table of inflight/done agent work.",
     '- `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.**',

package/src/prompts/native.ts

@@ -32,19 +32,23 @@ function nativeReplGlossary(): string {
     "| `llm_batch(prompts)` | list[str] | many cheap facts in **parallel** | multi-step research |",
     "| `map_files(files, prompt)` | dict[path,str] | same question over many files | multi-step per file |",
     "| `llm_query_chunked(text, prompt)` | list[str] | one huge text, auto-chunked | structured data |",
-    "| `rlm_query(task, paths=None)` | str | **one** multi-step study | ≥2 independent studies |",
-    "| `rlm_batch(tasks, paths=None)` | list[str] | **≥2 independent studies in parallel** | trivia / one-shots |",
+    "| `rlm_query(task|prompt, paths=None)` | str | **one** multi-step study | ≥2 independent studies |",
+    "| `rlm_batch(tasks|prompts, paths=None)` | list[str] | **≥2 independent studies in parallel** | trivia / one-shots |",
     "",
-    "Collect: `await_task(t)` or `await_task([t1,t2,…])`. `task.done` when settled.",
+    "Collect: `await_task(t)` / `await_task([…])` / `await_task()` (all running). `list_tasks()` finds lost handles. `task.done` when settled.",
+    "If a spawn call raises, the assignment did NOT run — the variable is undefined in later cells. Re-spawn with the corrected signature from the error message.",
     "The child inherits your `context`; send instructions + optional `paths=['src/auth/']` prefixes — never paste file bodies. **Children are sandboxed — they cannot mutate your `answers`, `plan`, or REPL variables.**",
     CHUNKED_GLOSSARY_LINE_NATIVE,
     "- `llm_map_reduce(...)` **blocks** (map then reduce) — prefer Tasks when you can interleave free work.",
     "- `spawn(fn, *args) -> Task` optional alias for always-spawn tools (not llm_map_reduce).",
     "",
     "### Memo / finalize",
-    "- `answers` / `plan` — persistent dicts. **If a value isn't in `answers`, it doesn't exist.**",
+    "- `answers` / `plan` — persistent dicts for **collected** results. Task handles are REPL vars (`t`), not `answers` keys.",
     "- `add_context(source) -> dict` — append external dir/file/doc/git under `ctx/<id>/…` (metadata only).",
-    "- `SHOW_VARS()` — list REPL vars. `answer[\"ready\"]=True` only for headless finalize (native: write a normal message).",
+    "- `memory.query(q)` / `memory.add(text, paths=…, tags=…)` — durable notes under `.rlm/` that survive",
+    "  sessions. Query before re-studying a known area; add concise findings — never secrets or API",
+    "  keys (notes persist on disk). `list_claims()` — the live `[ledger]` table of agent work.",
+    "- `SHOW_VARS()` — list REPL vars (Tasks as `<Task …>`). `list_tasks()` finds Task handles. `answer[\"ready\"]=True` only for headless finalize (native: write a normal message).",
     "",
     ENV_TIPS_CONDENSED,
     "",
@@ -87,8 +91,9 @@ export function buildNativeSystemPrompt(): string {
     "<contract>",
     "Inside `repl({code})`, EVERY heavy call returns a Task immediately (not the answer):",
     "  llm_query | llm_batch | map_files | llm_query_chunked | rlm_query | rlm_batch  →  Task",
-    "ONLY `await_task(t)` / `await_task([…])` returns content. Fan-out runs detached (↯bg) and outlives the cell.",
-    "If you printed a Task and did not await_task, you do **not** know the answer yet.",
+    "ONLY `await_task(t)` / `await_task([…])` / `await_task()` returns content. Fan-out runs detached (↯bg) and outlives the cell.",
+    "If `await_task` returns `Error: sub-call still running`, call it again — do not respawn.",
+    "If you printed a Task and did not await_task, you do **not** know the answer yet. A Task handle is a REPL variable, not an `answers[]` key.",
     "Fire independent Tasks first → free `search`/`grep_context`/`outline` → then await_task.",
     "Do NOT await after every independent spawn (that serializes wall time).",
     "</contract>",