@hicaru/pi-rlm 0.3.1 → 0.3.2

package/src/sandbox/py/worker.py

@@ -6,8 +6,8 @@ This is NOT a security sandbox: __import__ and open are available, so code can i
 
 Protocol (parent -> worker):  {"id","type":"exec"|"load_context"|"shutdown", ...}
 Protocol (worker -> parent):  {"id","ok",...result}            # response to a request
-                              {"type":"llm_query"|"llm_query_batched"|"rlm_query"|
-                               "rlm_query_batched"|"add_context","rid",...}
+                              {"type":"llm_query"|"llm_batch"|"rlm_query"|
+                               "rlm_batch"|"add_context","rid",...}
                                                                 # mid-exec helper request
 When sandbox code calls llm_query/rlm_query/add_context, the worker writes a
 request line and BLOCKS reading stdin until the matching {"type":"llm_reply","rid",...} arrives.
@@ -15,7 +15,7 @@ The parent services the request in-process (it holds API keys).
 
 Requests and replies are decoupled: `_post` writes a request and returns its rid without
 waiting, and replies are parked in `_inbox` keyed by rid until something asks for them. That
-is what makes `spawn()` / `rlm_await()` / `rlm_await_all()` possible — many requests can be
+is what makes `spawn()` / `await_task()` / `await_task()` possible — many requests can be
 in flight at once (the parent already services interrupts concurrently), and a task may be
 awaited in a LATER exec than the one that started it.
 """
@@ -100,12 +100,13 @@ class Worker:
         # Replies parked by rid until something awaits them. Unbounded by design: a task
         # the model spawns and never awaits keeps its entry for the life of the process.
         # Bounded in practice by session length; evicting would silently hang a later
-        # rlm_await, which is strictly worse than the memory.
+        # await_task, which is strictly worse than the memory.
         self.inbox: dict[str, dict[str, Any]] = {}
         self._inflight: set[str] = set()
         # Requests (exec/shutdown) that arrived mid-exec; main() replays them.
         self._deferred: list[Any] = []
-        # True only while spawn() runs a builder — marks requests that may outlive this exec.
+        # Kept for spawn() compatibility; sub-LLM kinds always post detached=true so fan-out
+        # outlives the repl cell and shows ↯bg (see _post).
         self._detached = False
         self.ns: dict[str, Any] = {}
         self._setup()
@@ -127,13 +128,13 @@ class Worker:
         # Re-inject any scaffolding the user code clobbered.
         ns = self.ns
         ns["llm_query"] = self._llm_query
-        ns["llm_query_batched"] = self._llm_query_batched
+        ns["llm_batch"] = self._llm_batch
         ns["llm_query_chunked"] = self._llm_query_chunked
         ns["rlm_query"] = self._rlm_query
-        ns["rlm_query_batched"] = self._rlm_query_batched
+        ns["rlm_batch"] = self._rlm_batch
         ns["spawn"] = self._spawn
-        ns["rlm_await"] = self._await_task
-        ns["rlm_await_all"] = self._await_all
+        # One collect API: await_task(Task) or await_task([Task, ...])
+        ns["await_task"] = self._await_task
         ns["map_files"] = self._map_files
         ns["llm_map_reduce"] = self._llm_map_reduce
         ns["search"] = self._search
@@ -184,14 +185,19 @@ class Worker:
 
     # ---- sub-LLM bridge over stdio --------------------------------------------------------
 
+    # Sub-LLM fan-out always runs detached (session BG registry + ↯bg), whether called
+    # as llm_batch(...) or via map_files internals — not only when wrapped in spawn().
+    _DETACHED_KINDS = frozenset({"llm_query", "llm_batch", "rlm_query", "rlm_batch"})
+
     def _post(self, kind: str, payload: dict[str, Any]) -> str:
         """Write one parent request and return its rid WITHOUT waiting for the reply."""
         self._rid += 1
         rid = f"q{self._rid}"
         # Register only after the write succeeds — a broken pipe must not leave an
         # _inflight entry that nothing will ever settle.
+        detached = self._detached or kind in self._DETACHED_KINDS
         _send({"type": kind, "rid": rid, "depth": self.depth,
-               "detached": self._detached, **payload})
+               "detached": detached, **payload})
         self._inflight.add(rid)
         return rid
 
@@ -257,21 +263,21 @@ class Worker:
 
     # ---- spawn / await ---------------------------------------------------------------------
 
-    def _start_prompt(self, kind: str, prompt, model, paths=None) -> Task:
+    def _start_prompt(self, kind: str, prompt, paths=None) -> Task:
         text = str(prompt)
         # A sub-LLM asked nothing answers something: the confabulation then sits in `answers`
         # looking exactly like data. Refuse instead of spending a call on it.
         if not text.strip():
             return Task.resolved(self, kind, _surfaced_error(
                 f"{kind}() got an empty prompt — a sub-LLM would confabulate an answer to nothing"))
-        payload: dict[str, Any] = {"prompt": text, "model": model}
+        payload: dict[str, Any] = {"prompt": text}
         clean = _clean_paths(paths)
         if clean is not None:
             payload["paths"] = clean
         rid = self._post(kind, payload)
         return Task(self, kind, (rid,), _reduce_one, text[:40])
 
-    def _start_prompts(self, kind: str, prompts, model, paths=None) -> Task:
+    def _start_prompts(self, kind: str, prompts, paths=None) -> Task:
         prompts = [str(p) for p in prompts]
         if not prompts:
             return Task.resolved(self, kind, [])
@@ -280,7 +286,7 @@ class Worker:
             return Task.resolved(self, kind, [
                 _surfaced_error(f"{kind}() got only empty prompts")
             ] * len(prompts))
-        payload: dict[str, Any] = {"prompts": prompts, "model": model}
+        payload: dict[str, Any] = {"prompts": prompts}
         # One prefix set for the whole batch: a per-prompt aligned list is an API nobody uses
         # correctly, and every prompt in a batch is asking about the same slice anyway.
         clean = _clean_paths(paths)
@@ -289,23 +295,23 @@ class Worker:
         rid = self._post(kind, payload)
         return Task(self, kind, (rid,), _reduce_batch(len(prompts)), f"×{len(prompts)}")
 
-    def _start_llm_query(self, prompt, model: str | None = None) -> Task:
-        return self._start_prompt("llm_query", prompt, model)
+    def _start_llm_query(self, prompt) -> Task:
+        return self._start_prompt("llm_query", prompt)
 
-    def _start_rlm_query(self, prompt, model: str | None = None, paths=None) -> Task:
-        return self._start_prompt("rlm_query", prompt, model, paths)
+    def _start_rlm_query(self, prompt, paths=None) -> Task:
+        return self._start_prompt("rlm_query", prompt, paths)
 
-    def _start_llm_query_batched(self, prompts, model: str | None = None) -> Task:
-        return self._start_prompts("llm_query_batched", prompts, model)
+    def _start_llm_batch(self, prompts) -> Task:
+        return self._start_prompts("llm_batch", prompts)
 
-    def _start_rlm_query_batched(self, prompts, model: str | None = None, paths=None) -> Task:
-        return self._start_prompts("rlm_query_batched", prompts, model, paths)
+    def _start_rlm_batch(self, prompts, paths=None) -> Task:
+        return self._start_prompts("rlm_batch", prompts, paths)
 
-    def _start_llm_query_chunked(self, text, prompt: str, model: str | None = None) -> Task:
+    def _start_llm_query_chunked(self, text, prompt: str) -> Task:
         """Split oversized text into cap-sized chunks and post EVERY batch at once.
 
         One answer per chunk, order preserved. No exceptions escape: errors come back as
-        "Error: ..." strings per chunk (same contract as llm_query_batched). Because all
+        "Error: ..." strings per chunk (same contract as llm_batch). Because all
         batches go on the wire together, a large input costs one round-trip of latency
         rather than one per 20 chunks.
 
@@ -334,26 +340,25 @@ class Worker:
                 f"{prompt}\n\n[chunk {i + j + 1}/{total} of the input]\n{c}"
                 for j, c in enumerate(chunks[i:i + _MAX_CHUNK_BATCH])
             ]
-            rids.append(self._post("llm_query_batched", {"prompts": batch, "model": model}))
+            rids.append(self._post("llm_batch", {"prompts": batch}))
             sizes.append(len(batch))
         return Task(self, "llm_query_chunked", tuple(rids), _reduce_chunked(sizes), f"{total} chunks")
-
     def _builder_for(self, name: str):
         # llm_map_reduce is deliberately absent: its reduce step is a SECOND sub-LLM call that
         # depends on its own map results, so it cannot be one (rids, pure reduce) Task.
         return {
             "llm_query": self._start_llm_query,
-            "llm_query_batched": self._start_llm_query_batched,
+            "llm_batch": self._start_llm_batch,
             "llm_query_chunked": self._start_llm_query_chunked,
             "map_files": self._start_map_files,
             "rlm_query": self._start_rlm_query,
-            "rlm_query_batched": self._start_rlm_query_batched,
+            "rlm_batch": self._start_rlm_batch,
         }.get(name)
 
     def _spawn(self, fn, *args, **kwargs) -> Task:
         """Start a sub-call without waiting for it. `fn` is the scaffold function itself.
 
-        Returns a Task for rlm_await / rlm_await_all, possibly in a later ```repl``` block.
+        Returns a Task for await_task, possibly in a later ```repl``` block.
         Misuse returns an already-resolved error Task rather than raising, matching the
         "Error: ..." contract of the synchronous helpers.
         """
@@ -361,11 +366,10 @@ class Worker:
         builder = self._builder_for(name) if isinstance(name, str) else None
         if builder is None:
             return Task.resolved(self, "spawn", _surfaced_error(
-                "spawn() takes llm_query, llm_query_batched, llm_query_chunked, map_files, "
-                "rlm_query or rlm_query_batched — not llm_map_reduce, whose reduce step depends "
+                "spawn() takes llm_query, llm_batch, llm_query_chunked, map_files, "
+                "rlm_query or rlm_batch — not llm_map_reduce, whose reduce step depends "
                 "on its own map results and so cannot be a single Task"))
-        # Mark every request this builder posts as detached: the parent routes them to its
-        # session-scoped registry, since they may outlive the exec that started them.
+        # Sub-LLM kinds already post detached via _post; keep the flag for clarity / future kinds.
         self._detached = True
         try:
             return builder(*args, **kwargs)
@@ -374,34 +378,48 @@ class Worker:
         finally:
             self._detached = False
 
-    def _await_task(self, task) -> Any:
-        """Block until `task` has its result. Idempotent — the value is memoized."""
-        if not isinstance(task, Task):
-            return _surfaced_error(
-                f"rlm_await expects a Task from spawn(), got {type(task).__name__}"
-            )
+    def _await_one(self, task: Task) -> Any:
+        """Block until one Task has its result. Idempotent — the value is memoized."""
         if not task._settled:
             self._drain_until(task._rids)
             task._value = task._reduce(self._take(task._rids))
             task._settled = True
         return task._value
 
-    def _await_all(self, tasks) -> list:
-        """Block until every task has its result. Order matches the input."""
-        tasks = list(tasks)
-        # One union drain so the tasks overlap instead of settling one after another.
-        union: list[str] = []
-        seen: set[str] = set()
-        for t in tasks:
-            if not isinstance(t, Task) or t._settled:
-                continue
-            for rid in t._rids:
-                if rid not in seen:
-                    seen.add(rid)
-                    union.append(rid)
-        if union:
-            self._drain_until(union)
-        return [self._await_task(t) for t in tasks]
+    def _await_task(self, task_or_tasks) -> Any:
+        """Collect result(s). Accepts a single Task or a list/tuple of Tasks.
+
+        Canonical name for the model: await_task(...). (bare `await` is a Python keyword.)
+        """
+        if isinstance(task_or_tasks, Task):
+            return self._await_one(task_or_tasks)
+        if isinstance(task_or_tasks, (list, tuple)):
+            tasks = list(task_or_tasks)
+            union: list[str] = []
+            seen: set[str] = set()
+            for t in tasks:
+                if not isinstance(t, Task) or t._settled:
+                    continue
+                for rid in t._rids:
+                    if rid not in seen:
+                        seen.add(rid)
+                        union.append(rid)
+            if union:
+                self._drain_until(union)
+            out: list[Any] = []
+            for t in tasks:
+                if isinstance(t, Task):
+                    out.append(self._await_one(t))
+                else:
+                    out.append(
+                        _surfaced_error(
+                            f"await_task expects Task items, got {type(t).__name__}"
+                        )
+                    )
+            return out
+        return _surfaced_error(
+            f"await_task expects a Task or list of Tasks, got {type(task_or_tasks).__name__}"
+        )
 
     # ---- deterministic retrieval (no sub-LLM calls, no root tokens) -----------------------
 
@@ -446,7 +464,7 @@ class Worker:
 
     # ---- one-line delegation (structural: orchestrating must be easier than solving) -------
 
-    def _start_map_files(self, files: Any, prompt: str, model: str | None = None) -> Task:
+    def _start_map_files(self, files: Any, prompt: str) -> Task:
         """Post every batch map_files needs, WITHOUT waiting. Contract: see _map_files.
 
         All batches go on the wire together, so a 100-file map costs one round-trip of latency
@@ -489,27 +507,27 @@ class Worker:
         sizes: list[int] = []
         for i in range(0, len(requests), _MAX_CHUNK_BATCH):
             batch = requests[i:i + _MAX_CHUNK_BATCH]
-            rids.append(self._post("llm_query_batched", {"prompts": batch, "model": model}))
+            rids.append(self._post("llm_batch", {"prompts": batch}))
             sizes.append(len(batch))
         return Task(self, "map_files", tuple(rids),
                     _reduce_map_files(sizes, spans), f"{len(by_path)} files")
 
     @_spawnable("map_files")
-    def _map_files(self, files: Any, prompt: str, model: str | None = None) -> dict[str, str]:
-        """Ask `prompt` of every given file, batched, and return {path: answer}.
+    def _map_files(self, files: Any, prompt: str) -> Task:
+        """Always spawn. Collect with await_task(t) → dict[path, answer].
 
         `files` accepts context entries (dicts), paths (strings), or a mix — the whole
         chunk/batch/collect loop the system prompt used to spell out, as one call.
         Oversized files are split and their per-chunk answers joined.
+        Posts are detached (↯bg) so fan-out outlives the repl cell.
         """
-        return self._await_task(self._start_map_files(files, prompt, model))
+        return self._start_map_files(files, prompt)
 
     def _llm_map_reduce(
         self,
         items: Any,
         map_prompt: str,
         reduce_prompt: str,
-        model: str | None = None,
     ) -> str:
         """Map `map_prompt` over `items` in one batch, then reduce the answers with one call.
 
@@ -534,28 +552,36 @@ class Worker:
                 f"{map_prompt}\n\n[{labels[i + j]}]\n{t}"
                 for j, t in enumerate(texts[i:i + _MAX_CHUNK_BATCH])
             ]
-            mapped.extend(self._llm_query_batched(batch, model))
+            # Core tools always return Task — helpers must await explicitly.
+            part = self._await_task(self._start_llm_batch(batch))
+            mapped.extend(part if isinstance(part, list) else [str(part)])
         joined = "\n\n".join(f"[{labels[i]}]\n{a}" for i, a in enumerate(mapped))
-        return self._llm_query(f"{reduce_prompt}\n\nPartial answers:\n{joined}", model)
+        reduced = self._await_task(
+            self._start_llm_query(f"{reduce_prompt}\n\nPartial answers:\n{joined}")
+        )
+        return str(reduced)
 
-    # ---- sync helpers: await(start(...)), so there is exactly one code path -----------------
+    # ---- Core tools: ALWAYS spawn (return Task). Collect with await_task only. ------------
 
     @_spawnable("llm_query")
-    def _llm_query(self, prompt: str, model: str | None = None) -> str:
-        return self._await_task(self._start_llm_query(prompt, model))
+    def _llm_query(self, prompt: str) -> Task:
+        """Always spawn. Collect with await_task(t). Never auto-awaits."""
+        return self._start_llm_query(prompt)
 
-    @_spawnable("llm_query_batched")
-    def _llm_query_batched(self, prompts, model: str | None = None) -> list[str]:
-        return self._await_task(self._start_llm_query_batched(prompts, model))
+    @_spawnable("llm_batch")
+    def _llm_batch(self, prompts) -> Task:
+        """Always spawn. Collect with await_task(t) → ordered list[str]."""
+        return self._start_llm_batch(prompts)
 
     @_spawnable("llm_query_chunked")
-    def _llm_query_chunked(self, text, prompt: str, model: str | None = None) -> list[str]:
-        return self._await_task(self._start_llm_query_chunked(text, prompt, model))
+    def _llm_query_chunked(self, text, prompt: str) -> Task:
+        """Always spawn. Collect with await_task(t) → list[str] (one answer per chunk)."""
+        return self._start_llm_query_chunked(text, prompt)
 
     @_spawnable("rlm_query")
-    def _rlm_query(self, prompt: str, model: str | None = None, paths=None) -> str:
-        return self._await_task(self._start_rlm_query(prompt, model, paths))
-
+    def _rlm_query(self, prompt: str, paths=None) -> Task:
+        """Always spawn. Collect with await_task(t)."""
+        return self._start_rlm_query(prompt, paths)
     def _add_context(self, source: str) -> dict[str, Any] | str:
         """Pack an external dir/file/git-URL on the host and append it into `context`.
 
@@ -694,9 +720,10 @@ class Worker:
                 out.append(item)
         return out
 
-    @_spawnable("rlm_query_batched")
-    def _rlm_query_batched(self, prompts, model: str | None = None, paths=None) -> list[str]:
-        return self._await_task(self._start_rlm_query_batched(prompts, model, paths))
+    @_spawnable("rlm_batch")
+    def _rlm_batch(self, prompts, paths=None) -> Task:
+        """Always spawn. Collect with await_task(t) → ordered list of reports."""
+        return self._start_rlm_batch(prompts, paths)
 
     # ---- context + execution --------------------------------------------------------------
 
@@ -757,7 +784,7 @@ class Worker:
             return []
         return [
             f"[rlm] huge raw-text variable(s): {', '.join(names)} — do NOT analyze them yourself; "
-            'delegate with llm_query_chunked(name, "your question") or slice + llm_query_batched.'
+            'delegate with llm_query_chunked(name, "your question") or slice + llm_batch.'
         ]
 
     def execute(self, code: str) -> dict[str, Any]:
@@ -828,7 +855,7 @@ def main() -> None:
                 _send({"id": "?", "ok": False, "error": f"bad json: {e}"})
                 continue
         # A task spawned in an earlier exec settling while the worker is idle. Park it for
-        # a later rlm_await; without this it would fall through to "unknown type" and the
+        # a later await_task; without this it would fall through to "unknown type" and the
         # result would be lost.
         if worker.park_reply(req):
             continue

package/src/sandbox/sandbox-manager.ts

@@ -7,6 +7,10 @@
 import { PythonSandbox, type SubLlmHandlers } from "./sandbox.ts";
 import type { ReplResult } from "./protocol.ts";
 import { mergeIntoContext } from "../context/merge.ts";
+import {
+  patchContextExecCode,
+  upsertContextFile,
+} from "../context/refresh.ts";
 
 /** Static configuration for sandbox creation — set once, reused across getOrCreate calls. */
 export interface SandboxManagerConfig {
@@ -15,7 +19,7 @@ export interface SandboxManagerConfig {
   readonly python: string;
   readonly sandboxInitTimeoutMs: number;
   readonly maxPromptChars: number;
-  /** Max seconds the worker waits for a host reply while parked in rlm_await. */
+  /** Max seconds the worker waits for a host reply while parked in await_task. */
   readonly awaitTimeoutS: number;
   readonly signal?: AbortSignal;
   readonly onSandboxDiscarded?: () => void;
@@ -50,6 +54,27 @@ export class SandboxManager {
     this.contextPayload = mergeIntoContext(this.contextPayload, payload);
   }
 
+  /**
+   * After native edit/write: replace file body in the host snapshot **and** the live worker.
+   * Rebuilds a new context list so BM25 index stamps invalidate.
+   */
+  async refreshFileFromDisk(
+    filePath: string,
+    content: string,
+    cwd: string,
+  ): Promise<void> {
+    this.contextPayload = upsertContextFile(this.contextPayload, filePath, content, cwd);
+    if (!this.sandbox || this.disposed) return;
+    // Avoid interleaving with an in-flight repl exec: queue like exec().
+    const code = patchContextExecCode(filePath, content, cwd);
+    try {
+      await this.execQueued(code);
+    } catch {
+      // Worker may be dead; next getOrCreate reloads contextPayload.
+      this.contextLoaded = false;
+    }
+  }
+
   /**
    * Lazy get-or-create the sandbox. On first call, spawns PythonSandbox with the
    * given handlers. Subsequent calls return the existing sandbox immediately.

package/src/sandbox/sandbox.ts

@@ -45,7 +45,7 @@ export interface SandboxOptions {
   readonly maxPromptChars?: number;
   /**
    * Max seconds the worker will wait for a host reply while parked in `_drain_until`
-   * (rlm_await / sync sub-call). Defaults to the worker's own RLM_AWAIT_TIMEOUT_S (600).
+   * (await_task / sync sub-call). Defaults to the worker's own RLM_AWAIT_TIMEOUT_S (600).
    */
   readonly awaitTimeoutS?: number;
 }

package/src/tool/background-tasks.ts

@@ -15,7 +15,7 @@ import { RlmEmitter } from "./rlm-events.ts";
 import { SubcallStore, type SubcallTotals } from "./subcall-store.ts";
 import type { RlmSubcall } from "./rlm-details.ts";
 import { LimitGuard, type Limits } from "../core/limits.ts";
-import type { Invocation } from "../bridge/subcall-handlers.ts";
+import type { Invocation } from "../bridge/handlers/index.ts";
 import { trace, traceEnabled } from "../util/trace.ts";
 
 /** What a drain hands to the turn that is reporting it. */

package/src/tool/repl-result.ts

@@ -46,10 +46,10 @@ export function buildReplResultText(
   const nudge = answerSubmitted ? undefined : replDelegationNudge(rawText.length, delegated);
   const failedBg = subcalls.filter((s) => s.id.startsWith("bg") && s.status === "error").length;
   const pendingLine = backgroundPending > 0
-    ? `\n\n[rlm] ${backgroundPending} background task(s) still running — rlm_await_all(tasks) to collect.`
+    ? `\n\n[rlm] ${backgroundPending} background task(s) still running — await_task(tasks) to collect.`
     : "";
   const failedLine = failedBg > 0
-    ? `\n[rlm] ${failedBg} background sub-call(s) FAILED — their rlm_await value is an "Error: …" string, not data.`
+    ? `\n[rlm] ${failedBg} background sub-call(s) FAILED — their await_task value is an "Error: …" string, not data.`
     : "";
   return { text: cappedText + (nudge ?? "") + pendingLine + failedLine };
 }

package/src/tool/repl-tool.ts

@@ -6,7 +6,7 @@
  * and collects sub-calls manually from emitter events. No RlmEventAggregator is used
  * (ReplDetails ≠ RlmDetails structural mismatch).
  *
- * Sub-call handling itself lives in bridge/subcall-handlers.ts; this file only supplies the
+ * Sub-call handling lives in bridge/handlers/ (createSubcallHandlers); this file only supplies the
  * per-invocation Invocation those handlers resolve against, swapping it inside the
  * serialized exec slot so a queued repl() cannot claim the running one's emitter.
  *
@@ -27,7 +27,7 @@ import { LimitGuard, limitsFromConfig } from "../core/limits.ts";
 import type { RlmConfig, RlmInput, RlmResult } from "../core/types.ts";
 import { SandboxManager } from "../sandbox/sandbox-manager.ts";
 import type { SubcallOpts } from "../sandbox/sandbox.ts";
-import { createSubcallHandlers, type Invocation } from "../bridge/subcall-handlers.ts";
+import { createSubcallHandlers, type Invocation } from "../bridge/handlers/index.ts";
 import { BackgroundTasks } from "./background-tasks.ts";
 import type { ReplResult } from "../sandbox/protocol.ts";
 import { RlmEmitter } from "./rlm-events.ts";
@@ -202,20 +202,19 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
     name: "repl",
     label: "REPL",
     description:
-      "PRIMARY tool for ALL repository reading and analysis (read/grep are disabled in RLM mode). " +
-      "Persistent Python sandbox with loaded files in `context` (starts empty; cwd seeds on first " +
-      "call). Locate first with the free primitives search(query) / grep_context(pattern) / " +
-      "outline(path), then delegate the semantic reading to map_files / llm_query / " +
-      "llm_query_batched / llm_query_chunked (rlm_query for iterative sub-tasks) — stdout " +
-      "returned to you is hard-capped at 4K chars, so printing file bodies is useless. " +
-      "Variables, imports, and the `answers`/`plan` memo persist across calls. Also supports " +
-      "add_context for external dirs/files/git URLs and document conversion.",
+      "PRIMARY tool for bulk repository analysis (orchestrator). " +
+      "Persistent Python sandbox: free locate with search/grep_context/outline, then ALWAYS-SPAWN " +
+      "fan-out — llm_query/llm_batch/map_files/llm_query_chunked/rlm_query/rlm_batch return Task " +
+      "immediately (↯bg); collect with await_task. Prefer rlm_batch for ≥2 independent multi-step " +
+      "module studies; map_files/llm_batch for one-shot extracts. Fire independent Tasks first, " +
+      "free work, then await — never treat Task as the answer. Stdout hard-capped ~4K (no file dumps). " +
+      "`answers`/`plan` persist. add_context for external dirs/files/git/docs.",
     promptSnippet:
-      "repl: run Python in a persistent sandbox holding loaded files in `context`; " +
-      "search/grep_context/outline to locate, map_files/llm_query* to read.",
+      "repl: free search/outline; fire rlm_batch|map_files|llm_batch as Task (BG); await_task for results.",
     promptGuidelines: [
-      "In RLM mode, read the repository through `repl` only — `read`/`grep` and bash readers are blocked.",
-      "Inside `repl`, locate with search()/grep_context()/outline() before delegating bulk reading to map_files()/llm_query_batched().",
+      "Multi-area analysis: rlm_batch([...]) or map_files(paths, q); free search; await_task — not serial native read.",
+      "Always-spawn tools return Task; only await_task has content. Fire-all independent work before await.",
+      "llm_query/llm_batch have no disk — never 'Read path/to/file.ts'; use map_files or rlm_* (see context).",
     ],
     parameters: ReplToolParams,
 

package/src/ui/config-panel.ts

@@ -39,7 +39,7 @@ export async function showConfigPanel(ctx: ExtensionContext, config: RlmConfig):
     item("maxDepth", "Max recursion depth", String(config.maxDepth), CHOICES.maxDepth, "rlm_query past this depth degrades to plain llm_query (1 = no recursion)."),
     item("maxIterations", "Max iterations", String(config.maxIterations), CHOICES.maxIterations, "Maximum root REPL turns before RLM asks the model for a final answer."),
     item("execTimeoutS", "REPL block timeout (s)", String(config.execTimeoutS), CHOICES.execTimeoutS, "Wall-clock limit for one model-authored Python REPL block."),
-    item("maxConcurrentSubcalls", "Max concurrent sub-calls", String(config.maxConcurrentSubcalls), CHOICES.maxConcurrentSubcalls, "Concurrency pool size for llm_query_batched and rlm_query_batched."),
+    item("maxConcurrentSubcalls", "Max concurrent sub-calls", String(config.maxConcurrentSubcalls), CHOICES.maxConcurrentSubcalls, "Concurrency pool size for llm_batch and rlm_batch."),
     item("maxConcurrentChildren", "Max concurrent children", String(config.maxConcurrentChildren), CHOICES.maxConcurrentChildren, "Concurrent rlm_query child engines per depth. Each is a Python process holding its own copy of the inherited context."),
     item("maxTimeoutMs", "Wall-clock ceiling (min)", config.maxTimeoutMs != null ? String(Math.round(config.maxTimeoutMs / 60_000)) : "none", CHOICES.maxTimeoutMs, "Total runtime cap for the whole recursive tree; none disables the cap."),
     item("maxTokens", "Token ceiling", config.maxTokens != null ? String(config.maxTokens) : "none", CHOICES.maxTokens, "Total input+output token cap for the whole recursive tree."),

package/src/ui/intro.ts

@@ -12,10 +12,7 @@ export const RLM_GUIDE = `# RLM mode
 
 - \`/rlm\` — toggle RLM mode (shortcut: Ctrl+Shift+R). Turning it OFF also stops a running query.
 - \`/rlm-config\` — choose models, reasoning, and run limits
-- \`/rlm-stop\` — cancel the current run but stay in RLM mode (use /rlm or Ctrl+Shift+R to leave)
-
-When RLM mode is ON, \`read\`/\`grep\` are disabled and the agent reads the repository through the
-\`repl\` tool, delegating bulk analysis to sub-LLMs. The footer/status line shows the current state.`;
+- \`/rlm-stop\` — cancel the current run but stay in RLM mode (use /rlm or Ctrl+Shift+R to leave)`;
 
 export function postRlmGuide(pi: ExtensionAPI, controller: RlmController): void {
   const content = RLM_GUIDE.replace("{state}", formatRlmStateLine(controller));

package/src/ui/model-picker.ts

@@ -15,7 +15,8 @@ export interface ModelSelection {
 const LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
 type SelectableThinkingLevel = (typeof LEVELS)[number];
 
-const CHEAPEST_VALUE = "__rlm_cheapest__";
+/** Sentinel SelectList value for "always use cheapest available". */
+export const CHEAPEST_VALUE = "__rlm_cheapest__";
 
 /**
  * Models Pi itself would offer for this session, cheapest-first.
@@ -53,6 +54,24 @@ function items(models: readonly Model<Api>[], includeCheapest: boolean): SelectI
   ];
 }
 
+/**
+ * Index to pre-select in the model list (with cheapest row at 0 when included).
+ * Without this, the list always opens on "cheapest (auto)" and Enter silently unpins.
+ */
+export function initialModelPickerIndex(
+  models: readonly Model<Api>[],
+  current?: Model<Api>,
+  currentRef?: string,
+  includeCheapest = true,
+): number {
+  const offset = includeCheapest ? 1 : 0;
+  const ref = current ? `${current.provider}/${current.id}` : currentRef;
+  if (!ref) return 0;
+  const idx = models.findIndex((m) => `${m.provider}/${m.id}` === ref);
+  if (idx < 0) return 0;
+  return idx + offset;
+}
+
 function supportedThinkingLevels(model: Model<Api>): SelectableThinkingLevel[] {
   if (!model.reasoning) return [];
   const map = model.thinkingLevelMap;
@@ -106,6 +125,7 @@ export async function selectModel(
   models: readonly Model<Api>[],
   current?: Model<Api>,
   currentThinking?: ThinkingLevel,
+  currentRef?: string,
 ): Promise<ModelSelection | null | undefined> {
   if (models.length === 0) {
     ctx.ui.notify("RLM: no models available (add a provider key in Pi, or widen --models / enabledModels)", "warning");
@@ -114,7 +134,11 @@ export async function selectModel(
   if (ctx.mode !== "tui") {
     const fallback = models[0];
     if (!fallback) return undefined;
-    const model = current ?? fallback;
+    // Prefer an explicit pin (resolved model or saved ref) over "first = cheapest".
+    const fromRef = currentRef
+      ? models.find((m) => `${m.provider}/${m.id}` === currentRef)
+      : undefined;
+    const model = current ?? fromRef ?? fallback;
     return { model, thinkingLevel: await selectThinkingLevel(ctx, model, currentThinking) };
   }
 
@@ -134,6 +158,8 @@ export async function selectModel(
       scrollInfo: (t) => theme.fg("dim", t),
       noMatch: (t) => theme.fg("warning", t),
     });
+    const initial = initialModelPickerIndex(models, current, currentRef, true);
+    if (initial > 0) list.setSelectedIndex(initial);
     const isFilterText = (s: string): boolean => {
       const sanitized = s.replace(/ /g, "");
       return sanitized.length > 0 && Array.from(sanitized).every((char) => char >= " " && char !== "\x7f");

package/src/util/concurrency.ts

@@ -73,7 +73,7 @@ export class DepthGates {
 
 /** Session-wide sub-call admission. Construct once; pass explicitly — never default one in. */
 export interface SubcallGates {
-  /** llm_query / llm_query_batched completions — terminal, so one shared gate. */
+  /** llm_query / llm_batch completions — terminal, so one shared gate. */
   readonly leaf: Semaphore;
   /** Recursive child engines — one gate per depth, see DepthGates. */
   readonly rlm: DepthGates;