@hicaru/pi-rlm 0.3.0 → 0.3.2

package/src/sandbox/py/retrieval.py

@@ -15,7 +15,7 @@ from typing import Any
 
 
 _CHUNK_HEADER_OVERHEAD = 64
-_MAX_CHUNK_BATCH = 20          # fan-out per llm_query_batched call (matches prompt guidance)
+_MAX_CHUNK_BATCH = 20          # fan-out per llm_batch call (matches prompt guidance)
 _MAX_CHUNKS = 500              # ceiling: above this, force pre-filtering in Python
 _NUDGE_CHARS = 500_000         # str/bytes vars above this trigger a one-time stdout hint
 
@@ -167,11 +167,14 @@ class _Bm25Index:
         out: list[dict[str, Any]] = [None] * len(top)  # type: ignore[list-item]
         for i, (idx, score) in enumerate(top):
             text = self.texts[idx]
+            snip = text[:_SNIPPET_CHARS]
+            # Both `snippet` and `text` so agents never KeyError mixing search vs grep shapes.
             out[i] = {
                 "path": self.paths[idx],
                 "line": self.starts[idx],
                 "score": round(score, 3),
-                "snippet": text[:_SNIPPET_CHARS],
+                "snippet": snip,
+                "text": snip,
             }
         return out
 
@@ -179,8 +182,8 @@ class _Bm25Index:
 def search(entries: list[tuple[str, str]], index: _Bm25Index, query: str, k: int = 10, path_glob: str | None = None) -> list[dict[str, Any]]:
     """Rank `context` windows against a natural-language query (BM25).
 
-    Returns [{path, line, score, snippet}] — pointers, not bodies. Follow up by slicing the
-    named files out of `context` and delegating them to llm_query / map_files.
+    Returns [{path, line, score, snippet, text}] — pointers, not bodies.
+    `text` is an alias of `snippet` (same as grep_context hits).
     """
     terms = _tokenize(str(query))
     if not terms:
@@ -201,9 +204,9 @@ def grep_context(
 ) -> dict[str, Any]:
     """Regex over `context`, capped and shaped.
 
-    Returns {"hits": [{path, line, text}], "counts": {path: n}, "total": n, "truncated": bool}.
-    `counts` is complete even when `hits` is capped, so a wide pattern reports its shape
-    instead of flooding stdout.
+    Returns {"hits": [{path, line, text, snippet}], "counts": {path: n}, "total": n, "truncated": bool}.
+    `snippet` is an alias of `text` (same as search hits) to avoid KeyError footguns.
+    `counts` is complete even when `hits` is capped.
     """
     try:
         rx = re.compile(pattern)
@@ -234,7 +237,13 @@ def grep_context(
                 continue
             lo = max(0, i - pad_before)
             hi = min(len(lines), i + pad_after + 1)
-            hits.append({"path": path, "line": i + 1, "text": "\n".join(lines[lo:hi])[:_SNIPPET_CHARS]})
+            body = "\n".join(lines[lo:hi])[:_SNIPPET_CHARS]
+            hits.append({
+                "path": path,
+                "line": i + 1,
+                "text": body,
+                "snippet": body,
+            })
     return {"hits": hits, "counts": counts, "total": total, "truncated": total > len(hits)}
 
 def outline(entries: list[tuple[str, str]], path: str) -> str:

package/src/sandbox/py/tasks.py

@@ -42,7 +42,7 @@ def _reduce_batch(n: int):
 
 
 def _reduce_chunked(sizes: list[int], drop_empty: bool = True):
-    """Concatenate several llm_query_batched replies back into one flat chunk list.
+    """Concatenate several llm_batch replies back into one flat chunk list.
 
     drop_empty=True (llm_query_chunked): filter "" replies so results never degrade
     to blank entries; the flattened list may then be shorter than the chunk count,

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.
 """
@@ -44,6 +44,7 @@ from guards import (
     REAL_STDERR as _REAL_STDERR,
     REAL_STDIN as _REAL_STDIN,
 )
+from hostio import read_host_payload
 from retrieval import (
     _Bm25Index,
     _chunk_text,
@@ -99,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()
@@ -126,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
@@ -183,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
 
@@ -256,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, [])
@@ -279,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)
@@ -288,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.
 
@@ -333,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.
         """
@@ -360,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)
@@ -373,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) -----------------------
 
@@ -445,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
@@ -488,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.
 
@@ -533,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`.
 
@@ -591,8 +618,7 @@ class Worker:
         if not isinstance(path, str):
             return "Error: malformed add_context reply (no path)"
         try:
-            with io.open(path, "r") as f:
-                payload = json.load(f) if r.get("json") else f.read()
+            payload = read_host_payload(path, bool(r.get("json")))
         finally:
             try:
                 os.remove(path)  # worker owns temp-file cleanup (host does NOT unlink)
@@ -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 --------------------------------------------------------------
 
@@ -706,8 +733,7 @@ class Worker:
         `index` is accepted for protocol compatibility but ignored — there is only
         one context slot. Sources are merged on the host (or via add_context).
         """
-        with open(path, "r") as f:
-            payload = json.load(f) if is_json else f.read()
+        payload = read_host_payload(path, bool(is_json))
         self._context_payload = payload
         self.ns["context"] = payload
         # Drop legacy multi-slot names if present.
@@ -758,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]:
@@ -829,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;
 }
@@ -111,6 +111,11 @@ export class PythonSandbox {
     this.initTimeoutMs = opts.initTimeoutMs ?? 30_000;
     const python = opts.python ?? "python3";
     const workerArgs = [
+      // -X utf8=1: the scaffold states its own encoding explicitly (py/hostio.py), but MODEL
+      // code gets a real open() — guards.py exposes it deliberately — and on Windows that
+      // would default to cp1252 (issue #7). UTF-8 mode covers the whole interpreter; the
+      // scaffold's explicit encoding= still wins where PYTHONIOENCODING would override this.
+      "-X", "utf8=1",
       "-u", WORKER_PATH,
       "--depth", String(opts.depth ?? 1),
       "--timeout", String(opts.execTimeoutS ?? 600),
@@ -124,7 +129,9 @@ export class PythonSandbox {
     this.proc = spawn(
       python,
       workerArgs,
-      { stdio: ["pipe", "pipe", "pipe"], env: sanitizedEnv() },
+      // windowsHide: without it each sandbox flashes a console window on Windows (pi sets
+      // this on every spawn — bash.ts / shell.ts). Same Windows surface as issue #7.
+      { stdio: ["pipe", "pipe", "pipe"], env: sanitizedEnv(), windowsHide: true },
     ) as ChildProcessWithoutNullStreams;
 
     this.proc.stdout.setEncoding("utf8");

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,