@hicaru/pi-rlm 0.1.8 → 0.2.0

package/src/prompts/system.ts

@@ -36,6 +36,36 @@ function promptCapTokensK(maxPromptChars: number): number {
   return Math.round(maxPromptChars / 4_000);
 }
 
+/**
+ * Deterministic retrieval over `context` (headless + native).
+ *
+ * The paper's trajectories retrieve with hand-written regex (App. E.1); frontier models do that
+ * well, small ones guess keywords badly, and the first decomposition disproportionately decides
+ * the outcome (§5, Fig. 4a). These cost no tokens and no sub-calls.
+ */
+const RETRIEVAL_GLOSSARY_LINES: readonly string[] = Object.freeze([
+  "- `search(query: str, k=10, path_glob=None)`: BM25 ranking over `context`. Returns",
+  "  [{path, line, score, snippet}] — POINTERS, not bodies. **Start here.** It is free:",
+  "  no sub-LLM call, no tokens. Use it before you guess at filenames or write regex.",
+  "- `grep_context(pattern, k=50, path_glob=None, before=0, after=0) -> dict`: regex over",
+  "  `context`. Returns {hits: [{path, line, text}], counts: {path: n}, total, truncated} —",
+  "  `counts` is complete even when `hits` is capped, so a wide pattern reports its shape",
+  "  instead of flooding you. Use for exact lexical needles; use `search` for meaning.",
+  "- `outline(path) -> str`: definition/heading skeleton of one file with line numbers.",
+  "  Orient in ~200 chars instead of printing 20K. Matches exact path, then suffix, then glob.",
+]);
+
+/** One-line delegation helpers — orchestrating must be cheaper than solving. */
+const DELEGATION_GLOSSARY_LINES: readonly string[] = Object.freeze([
+  "- `map_files(files, prompt, model=None) -> dict[path, str]`: ask `prompt` of every file and",
+  "  get back {path: answer}. Accepts context entries or paths, packs them into cap-sized",
+  "  batched sub-calls, and splits oversized files automatically. **This is the default way to",
+  "  read many files** — prefer it over hand-rolling a chunk loop.",
+  "- `llm_map_reduce(items, map_prompt, reduce_prompt, model=None) -> str`: map over items in",
+  "  one batch, then reduce the partial answers with a single call. The paper's canonical",
+  "  strategy (query per chunk → aggregate the buffers) as one call.",
+]);
+
 /** Shared glossary entry for the chunked-query helper (headless + native). */
 const CHUNKED_GLOSSARY_LINES: readonly string[] = Object.freeze([
   "- `llm_query_chunked(text: str, prompt: str, model=None) -> list[str]`: auto-splits `text` into",
@@ -69,6 +99,66 @@ const CHUNKED_GLOSSARY_LINE_NATIVE =
 const LARGE_FILE_RULE_NATIVE =
   "- Files >1MB or gitignored are NOT in `context`: open() + parse deterministically in Python is fine; ANY semantic reading of the raw text goes through llm_query_chunked. Never print >2K chars raw.";
 
+/**
+ * The decomposition doctrine, ported from the RLM paper's Appendix C.3 `<env_tips>` and
+ * retargeted from competition math to repository analysis.
+ *
+ * This block is the single highest-leverage prompt intervention the paper reports: +69.5% on
+ * LongCoT-mini over the same RLM without it (Table 2). Plain RLM prompting alone actually
+ * *regressed* two of the five categories; the doctrine is what fixed them. Its purpose is to
+ * counter under-delegation — the model doing the work itself in the REPL instead of fanning out.
+ *
+ * Note the counterweight: `orchestratorAddendum` carries the anti-OVER-recursion batching rule.
+ * The paper is explicit (App. B) that one prompt does not port across models and that both
+ * guardrails are needed; keep them both.
+ */
+const ENV_TIPS = [
+  "## Decomposition doctrine",
+  "",
+  "**Orchestrate; don't solve.** A single chain of thought over a large repository drifts —",
+  "you lose partials and compound mistakes. Your sub-LLMs are competent readers: given a",
+  "self-contained prompt and the text, they will extract, locate, classify, and summarize",
+  "reliably. Trust them; don't do their reading yourself.",
+  "",
+  "Your job: (1) find the relevant slice with `search` / `grep_context` / `outline`,",
+  "(2) delegate all semantic reading to `map_files` / `llm_query_batched` / `llm_map_reduce`,",
+  "(3) memoize every result you will reuse in `answers`, (4) sanity-check an answer before",
+  "another step depends on it, (5) assemble the final answer from `answers` by lookup.",
+  "Your 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 and survive snapshots.",
+  "**If a value isn't in `answers`, it doesn't exist.** Do not trust a number from your own",
+  "earlier reasoning or from truncated stdout — context drifts. Memoize everything you reuse.",
+  "",
+  "### Shape of a run",
+  "1. Probe: `print(len(context))`, `search(<the user's question>)`. Do not print file bodies.",
+  "2. Plan: write the sub-questions into `plan`; each must be answerable from a named slice.",
+  "3. Fan out: one `map_files` / `llm_query_batched` per independent group, not one call per",
+  "   file. Store results into `answers` keyed by path or sub-question.",
+  "4. Assemble: build the answer from `answers`. Delegate the aggregation too if it is large.",
+  "",
+  "### Red flags — you are off track",
+  "- Printing file bodies to read them yourself → stop, delegate to `map_files`.",
+  "- Writing regex to *infer meaning* (naming conventions, intent, correctness) → that is a",
+  "  sub-LLM job. Regex is for exact lexical needles only.",
+  "- Two turns in with zero sub-LLM calls on an analysis task → you are solving it yourself.",
+  "- About to reuse a value that is not in `answers` → re-derive it and store it.",
+  "- One sub-call per file over dozens of files → batch them; fat prompts in small batches win.",
+].join("\n");
+
+/** Native-mode variant of the doctrine — same rules, sized for the native prompt budget. */
+const ENV_TIPS_CONDENSED = [
+  "### Decomposition doctrine (paper App. C.3 — worth +69.5% there)",
+  "Orchestrate; don't solve. Loop: `search`/`grep_context`/`outline` to find the slice →",
+  "`map_files` / `llm_query_batched` to read it → memoize into `answers` → assemble by lookup.",
+  "`answers` and `plan` persist across turns and snapshots: **if a value isn't in `answers`, it",
+  "doesn't exist** — never reuse a number from your own earlier reasoning or truncated stdout.",
+  "Red flags: printing file bodies to read them; regex used to infer meaning rather than match",
+  "a literal; two turns into an analysis with zero sub-LLM calls; one sub-call per file instead",
+  "of one batch. Exception — AUTHORING is not reading: you write every edit body yourself.",
+].join("\n");
+
 function howToRunCode(): string {
   return [
     "To run Python, write a fenced ```repl``` block. The REPL **persists** across turns. Only",
@@ -100,24 +190,23 @@ function replGlossary(
       "  bodies into your own output.",
       CONTEXT_EXCLUSION_NOTE,
       "",
-      "  Chunking example:",
+      "  Worked example — find the slice, then delegate it:",
       "  ```python",
-      "  chunk_size = 5",
-      "  for i in range(0, len(context), chunk_size):",
-      "      batch = context[i:i+chunk_size]",
-      "      results = llm_query_batched([",
-      "          f\"Analyze {f['path']} ({f['tokens']} tok):\\n{f['content']}\"",
-      "          for f in batch",
-      "      ])",
+      '  hits = search("where is the retry/backoff policy configured?", k=8)',
+      "  paths = sorted({h['path'] for h in hits})",
+      '  answers.update(map_files(paths, "Describe any retry/backoff policy in this file, with line numbers. Say NONE if absent."))',
+      "  print({p: a[:80] for p, a in answers.items()})",
       "  ```",
     );
   }
+  lines.push(...RETRIEVAL_GLOSSARY_LINES);
   lines.push(
     "- `llm_query(prompt: str, model=None) -> str`: a single sub-LLM completion. Use for extraction,",
     "  summarization, or Q&A over a chunk of text.",
     "- `llm_query_batched(prompts: list[str], model=None) -> list[str]`: run several sub-LLM calls",
     "  concurrently; output order matches input order.",
     ...CHUNKED_GLOSSARY_LINES,
+    ...DELEGATION_GLOSSARY_LINES,
   );
   if (askUserQuestion) {
     lines.push(
@@ -141,13 +230,21 @@ function replGlossary(
   }
   if (libraryLoader) {
     lines.push(
-      "- `load_library(source: str) -> dict`: load an EXTERNAL library, source tree, or document into a",
-      "  NEW `context_N` REPL variable. `source` may be a local directory (repomix-packed to the same",
-      "  list[dict] shape as `context`), a single file path (loaded as a plain str), or an https/git@ URL",
-      "  (shallow-cloned, then packed). Returns {\"index\": N, \"var\": \"context_N\", \"files\", \"chars\"}",
-      "  on success or an \"Error: ...\" string. Use it when the task requires learning an external lib's",
-      "  API, structure, or docs that are not in `context`; then chunk `context_N` to sub-LLMs exactly like",
-      "  `context`. Do not re-load a source that is already in a slot.",
+      "- `load_library(source: str) -> dict`: load an EXTERNAL library, source tree, or document and",
+      "  **APPEND its files into the existing `context` list** (same shape: path/content/tokens).",
+      "  `source` may be a local directory (repomix-packed), a single file path, or an https/git@ URL",
+      "  (shallow-cloned, then packed). Paths are namespaced under `lib/<source_id>/…` so you can filter",
+      "  by prefix. Returns metadata only:",
+      "  {\"source\", \"source_id\", \"path_prefix\", \"files\", \"chars\", \"context_len\", \"already_loaded\"}",
+      "  or an \"Error: ...\" string. **Never treat the return value as the file list** — always search",
+      "  and chunk the single variable `context`. Do not invent `context_1` / aliases; do not call",
+      "  globals()/locals(). Idempotent: re-loading the same source is a no-op.",
+      "",
+      "  ```python",
+      "  info = load_library(\"/path/to/other-project\")",
+      "  # info is metadata; files are already in context under info[\"path_prefix\"]",
+      "  lib_files = [f for f in context if f[\"path\"].startswith(info[\"path_prefix\"])]",
+      "  ```",
     );
   }
   if (recursion) {
@@ -172,8 +269,8 @@ function replGlossary(
       "  Kinds: `'clarification'` | `'research'` | `'plan'` | `'validation'`. Must match the current phase.",
       "  Frontmatter must eventually include `status: ready` before `advance_phase` will accept the transition.",
       "- `advance_phase(phase: str, summary=None) -> str`: transition to the next pipeline phase.",
-      "  Order: 'clarify' → 'research' → 'blueprint' → 'implement' → 'validate' (one step at a time;",
-      "  clarify is skipped when ask_user_question is disabled).",
+      "  Order: 'clarify' → 'research' → 'blueprint' → 'validate' (one step at a time;",
+      "  clarify is skipped when ask_user_question is disabled). The pipeline is READ-ONLY.",
       "  **advance_phase is validated by the engine** — it measures the latest saved artifact",
       "  (status, structure, citations, blockers_count; clarify also requires ≥1 ask_user_question round).",
       "  A rejected transition returns the gate error for you to fix; the phase does NOT advance.",
@@ -181,6 +278,8 @@ function replGlossary(
     );
   }
   lines.push(
+    "- `answers` / `plan`: two dicts that persist across turns and snapshots. Memoize every",
+    "  verified result in `answers` — see the decomposition doctrine below.",
     "- `SHOW_VARS() -> str`: list every variable currently in the REPL.",
     '- `answer`: a dict initialized to {"content": "", "ready": False}. To submit your final answer,',
     '  set `answer["content"]` to the answer text and `answer["ready"] = True`.',
@@ -236,7 +335,9 @@ export function buildRlmSystemPrompt(meta: PromptMeta, opts: SystemPromptOptions
     "Start by probing `context` (print a few lines, count items). Then build up an answer to the query.",
   ];
   if (opts.orchestrator ?? true) {
-    parts.push("", orchestratorAddendum(maxPromptChars));
+    // Two counterweights, both required (paper App. B): the addendum bounds OVER-recursion
+    // (batching/cost), ENV_TIPS bounds UNDER-recursion (solving it yourself).
+    parts.push("", orchestratorAddendum(maxPromptChars), "", ENV_TIPS);
   }
   if (kind === "files") {
     parts.push("", LARGE_FILE_RULE_LINES.join("\n"));
@@ -255,61 +356,55 @@ function nativeReplGlossary(): string {
     "",
     "### REPL Environment",
     "- `context`: list[dict] — every file in the repository. Each dict: `path` (str), `content` (str), `tokens` (int).",
+    "",
+    "Retrieval — free (no sub-LLM call, no tokens). **Start here, before guessing filenames:**",
+    "- `search(query, k=10, path_glob=None) -> [{path, line, score, snippet}]` — BM25 over `context`. Returns pointers, not bodies.",
+    "- `grep_context(pattern, k=50, path_glob=None, before=0, after=0) -> {hits, counts, total, truncated}` — regex; `counts` stays complete when `hits` is capped. Lexical needles only.",
+    "- `outline(path) -> str` — definition/heading skeleton with line numbers. Orient in ~200 chars instead of printing 20K.",
+    "",
+    "Delegation — everything semantic goes through these:",
+    "- `map_files(files, prompt, model=None) -> {path: answer}` — ask `prompt` of many files; batches and splits oversized files for you. **The default way to read many files.**",
+    "- `llm_map_reduce(items, map_prompt, reduce_prompt, model=None) -> str` — map in one batch, then reduce with one call.",
     "- `llm_query(prompt, model=None) -> str` — one-shot sub-LLM. Use for extraction, summarization, Q&A over a chunk.",
     "- `llm_query_batched(prompts, model=None) -> list[str]` — concurrent sub-LLM calls; output order matches input order.",
     CHUNKED_GLOSSARY_LINE_NATIVE,
     "- `rlm_query(prompt, model=None) -> str` — recursive RLM with its own REPL for complex sub-tasks needing iterative reasoning. Prefer llm_query — rlm_query is slower and costlier.",
     "- `rlm_query_batched(prompts, model=None) -> list[str]` — concurrent recursive RLM calls.",
     "",
+    "",
+    "- `answers` / `plan` — dicts persisted across every repl() call and snapshot. Your memo.",
     "- `todo(action, **kwargs) -> str` — manage a task list. Actions: create, update, list, get, delete, clear. Statuses: pending → in_progress → completed.",
-    "- `load_library(source)` → `context_N` (external).",
+    "- `load_library(source) -> dict`: append external dir/file/git tree into `context` under `lib/<id>/…`. Return is metadata only — always use `context`.",
     "- `SHOW_VARS() -> str` — list all variables currently in the REPL.",
-    "- `stage_edit(path, old_text, new_text) -> str`: stages an edit and returns an edit ID; apply IDs with `apply_edits`.",
     "- `answer`: dict `{\"content\": \"\", \"ready\": False}`. Setting `answer[\"ready\"] = True` delivers it to the user; do not restate it.",
     "",
-    "### Orchestrator Pattern",
-    "You are an **orchestrator, not a solver**. After probing `context`, decompose the task into sub-LLM / REPL steps,",
-    "then execute one step at a time, printing samples of each result to verify before moving on.",
+    ENV_TIPS_CONDENSED,
     "",
-    "Push every long-context operation (reading, summarizing, classifying, answering sub-questions) into",
-    "`llm_query` / `llm_query_batched` — never dump raw file bodies into your own output. Aggregate small",
-    "results back in Python. Use Python string operations (`in`, `re.search`) over `context` for quick lookups.",
-    "",
-    "### Chunking Strategy",
+    "### Worked pattern",
     "```python",
-    "chunk_size = 10",
-    "for i in range(0, len(context), chunk_size):",
-    "    batch = context[i:i+chunk_size]",
-    "    results = llm_query_batched([",
-    "        f\"Analyze {f['path']} ({f['tokens']} tok):\\n{f['content']}\"",
-    "        for f in batch",
-    "    ])",
-    "    # aggregate results into a buffer",
+    'hits = search("where is retry/backoff configured?", k=8)',
+    "paths = sorted({h['path'] for h in hits})",
+    'answers.update(map_files(paths, "Describe any retry/backoff policy here, with line numbers. Say NONE if absent."))',
+    "print({p: a[:80] for p, a in answers.items()})",
     "```",
-    `- Keep sub-prompts under ${DEFAULT_PROMPT_CAP.toLocaleString()} characters (≈${promptCapTokensK(DEFAULT_PROMPT_CAP)}K tokens); batch ~20 prompts per call. Fat prompts in small batches > thousands of tiny prompts.`,
+    `- Sub-prompts cap at ${DEFAULT_PROMPT_CAP.toLocaleString()} chars (≈${promptCapTokensK(DEFAULT_PROMPT_CAP)}K tokens); ~20 prompts per batch. Fat prompts in small batches > thousands of tiny prompts.`,
     "",
     "### Choosing Between Tools",
     "| Tool | When |",
     "|------|------|",
-    "| `repl({code})` | Need to chunk/delegate `context` to sub-LLMs; need Python scripting; need REPL state across calls |",
-    "| `zebra-mcp` | Semantic search over the codebase |",
-    "| `edit` | Native Pi edit tool; prefer `stage_edit` + `apply_edits` from REPL for file changes in native RLM mode |",
-    "| `write` | Create a new file (native Pi flow, visible to all plugins) |",
-    "| `llm_query` (inside repl) | Extract, summarize, or classify a chunk of text |",
-    "| `rlm_query` (inside repl) | Complex sub-task needing iterative reasoning with its own REPL |",
-    "| `todo` (inside repl) | Track multi-step progress visibly to the user |",
-    "| `stage_edit(path, old, new)` (inside repl) | Stage exact edit params; apply returned IDs with `apply_edits` |",
-    "",
-    "### Workflow",
-    "1. **Plan**: Create todos for the multi-step analysis. Probe `context` — print length, inspect a few entries.",
-    "2. **Chunk & Delegate**: Slice `context` into batches, delegate each batch to sub-LLMs via `llm_query_batched`.",
-    "3. **Aggregate**: Collect results in Python, pass aggregated results to a final `llm_query` or produce the answer directly.",
-    "4. **Finalize**: For file changes, stage them inside repl() via `stage_edit(path, old, new)`, then apply the returned IDs with `apply_edits({ ids })`. Do not use the native `edit` tool directly for native RLM file changes unless explicitly asked. For analysis tasks, write a normal message.",
+    "| `repl({code})` | ALL repository reading, search, and analysis; Python scripting; state across calls |",
+    "| `edit` / `write` | Change or create a file. Compose oldText/newText yourself; exact match required |",
+    "| `search` / `grep_context` / `outline` (in repl) | Locate the relevant slice — free, do this first |",
+    "| `zebra-mcp` | Semantic/embedding search when lexical `search` misses the concept |",
+    "| `map_files` / `llm_query_batched` (in repl) | Read/extract/classify that slice |",
+    "| `rlm_query` (in repl) | Sub-task needing its own iterative reasoning and REPL |",
+    "| `todo` (in repl) | Track multi-step progress visibly to the user |",
     "",
     "### Task-Specific Patterns",
     LARGE_FILE_RULE_NATIVE,
-    "- Architecture/code review: chunk relevant files and delegate summaries or review to `llm_query_batched`.",
-    "- Bug investigation: use Python string/regex search over `context`; delegate matching files for analysis.",
+    "- Architecture/code review: `search` for the subsystem, then `map_files` the hits.",
+    "- Bug investigation: `grep_context` for the literal symbol/message, then `map_files` the matching files.",
+    "- Finalizing: for file changes call `edit`/`write` directly so Pi validates the anchor and renders the diff; for analysis, write a normal message.",
     "- If sub-LLM credits are exhausted, report partial results and stop — do not bypass REPL restrictions.",
     "",
     "Reserve your own tokens for high-level decisions: what to ask next, how to combine sub-LLM outputs, when to finalize.",
@@ -328,25 +423,30 @@ export function buildNativeSystemPrompt(): string {
     "- `read`/`grep` are blocked; bash readers (cat/sed/head/tail/awk/rg) are blocked; bash output is hard-capped at 4K chars.",
     "- repl() stdout returned to you is hard-capped at 4K chars — printing file bodies is USELESS; the text will not reach you.",
     "",
-    "DELEGATION RULE: if a step needs MEANING from more than ~4K chars of text, that reading MUST",
-    "be an llm_query / llm_query_batched / llm_query_chunked call (rlm_query for iterative",
-    "sub-tasks). Deterministic Python (search, count, slice, json, re) over `context` is free and",
+    "LOCATE-THEN-DELEGATE: `search(query)` / `grep_context(pattern)` / `outline(path)` cost nothing",
+    "— run them FIRST to find the relevant slice. Then, if a step needs MEANING from more than ~4K",
+    "chars, that reading MUST be a map_files / llm_query / llm_query_batched / llm_query_chunked",
+    "call (rlm_query for iterative sub-tasks). Deterministic Python over `context` is free and",
     "preferred for lookups. Semantic reading is always delegated.",
     "",
     "All file content is pre-loaded in the REPL `context` variable. Use ONLY `repl({code})`.",
     "If sub-LLM credits are exhausted → report the error to the user and stop.",
     "",
-    "For file changes, prefer `stage_edit()` inside repl(); it returns edit IDs and keeps edit bodies out of your output.",
-    "When repl() returns STAGED_EDITS, apply them with `apply_edits({ ids: [\"e1\", ...] })`.",
-    "Never re-type file paths, oldText, newText, file bodies, or `answer[\"content\"]` in your own output.",
+    "AUTHORING RULE: sub-LLMs (`llm_query` family) READ — they extract, locate, and summarize.",
+    "They never author code you will ship. Once you know WHAT to change, compose the exact",
+    "oldText / newText yourself and apply it with `edit`. Delegated code is written by a small",
+    "model with no view of the codebase; it is a research aid, never a patch.",
+    "Never re-type file bodies or `answer[\"content\"]` in your own output.",
     "",
     nativeReplGlossary(),
   ].join("\n");
 }
 
 /** Soft cap on the static native prompt. Leaves headroom for per-turn context injection
- *  without bloating the root model's system prompt. Exceeded → phase-guards.ts fails. */
-export const NATIVE_PROMPT_BUDGET = 6_000;
+ *  without bloating the root model's system prompt. Exceeded → phase-guards.ts fails.
+ *  Raised from 6K when the retrieval glossary and the condensed decomposition doctrine
+ *  landed; both buy far more than they cost (paper Table 2, Fig. 4a). */
+export const NATIVE_PROMPT_BUDGET = 7_500;
 
 /** Exported for tests — prompt length without context metadata (which is injected separately). */
 export const NATIVE_PROMPT_STATIC = buildNativeSystemPrompt();
@@ -355,9 +455,12 @@ export const NATIVE_PROMPT_STATIC = buildNativeSystemPrompt();
 export const NATIVE_TURN_REMINDER = [
   "[RLM orchestrator contract — enforced by the runtime, not optional:",
   "repl() stdout to you is hard-capped at 4K chars; read/grep and bash readers are blocked.",
-  "Any SEMANTIC reading of file/text content MUST go through llm_query / llm_query_batched /",
-  "llm_query_chunked (rlm_query for iterative sub-tasks). Deterministic Python (search, count,",
-  "slice, json) is free. Keep your own output to decisions and aggregation.]",
+  "LOCATE FIRST with search() / grep_context() / outline() — they cost nothing. Any SEMANTIC",
+  "reading MUST then go through map_files / llm_query / llm_query_batched / llm_query_chunked",
+  "(rlm_query for iterative sub-tasks). Memoize what you reuse in `answers`; a value not in",
+  "`answers` does not exist. AUTHORING IS NOT READING: you write every edit body yourself and",
+  "apply it with the native `edit` / `write` tools — never delegate code you will ship.",
+  "Keep your own output to decisions, authored edits, and aggregation.]",
 ].join("\n");
 
 /** The one-line context metadata, also reused by the per-turn prompt in headless mode. */

package/src/prompts/user.ts

@@ -7,12 +7,8 @@ export function buildTurnPrompt(
   iteration: number,
   maxIterations: number,
   gateMessage?: string,
-  phaseGuidanceText?: string,
 ): string {
-  const parts: string[] = [];
-  if (phaseGuidanceText) parts.push(phaseGuidanceText);
-  if (gateMessage) parts.push(gateMessage);
-  const prefix = parts.length > 0 ? `${parts.join("\n\n")}\n\n` : "";
+  const prefix = gateMessage ? `${gateMessage}\n\n` : "";
   const body = `Turn ${iteration + 1}/${maxIterations}:`;
   if (iteration === 0) {
     return (

package/src/sandbox/protocol.ts

@@ -21,24 +21,21 @@ export interface LlmReply {
   readonly response?: string;
   readonly responses?: readonly string[];
   readonly answers?: readonly AskAnswer[];
-  /** load_library reply: temp file with the packed payload + assigned slot. */
+  /** load_library reply: temp file with the packed payload (+ resume index / namespace). */
   readonly path?: string;
   readonly json?: boolean;
   readonly index?: number;
   readonly files?: number;
   readonly chars?: number;
+  readonly source_id?: string;
+  readonly path_prefix?: string;
+  /** Host-side idempotency: library already loaded — no path payload. */
+  readonly already_loaded?: boolean;
   readonly error?: string;
 }
 
 export type ParentMessage = WorkerRequest | LlmReply;
 
-export interface ProposedEdit {
-  readonly id: string;
-  readonly path: string;
-  readonly oldText: string;
-  readonly newText: string;
-}
-
 /** A normal response to a request (keyed by the request `id`). */
 export interface WorkerResponse {
   readonly id: string;
@@ -49,16 +46,12 @@ export interface WorkerResponse {
   readonly stderr?: string;
   readonly final_answer?: string | null;
   readonly answer_content?: string;
-  readonly edits?: readonly ProposedEdit[];
   readonly raised?: boolean;
   readonly execution_time?: number;
   // user-created variable names after this exec (filters builtins/context) — Metadata(stdout) for history orientation
   readonly var_names?: readonly string[];
   // load_context:
   readonly index?: number;
-  // snapshot/restore:
-  readonly skipped?: readonly string[];
-  readonly restored?: readonly string[];
 }
 
 /** Kinds of sub-LLM interrupt the worker can raise mid-exec. */
@@ -92,10 +85,6 @@ export interface AskAnswer {
   readonly custom?: string;
 }
 
-export interface AskUserQuestionReply {
-  readonly answers: readonly AskAnswer[];
-}
-
 interface InterruptBase {
   readonly rid: string;
   readonly depth: number;
@@ -201,7 +190,6 @@ export interface ReplResult {
   readonly stderr: string;
   readonly finalAnswer: string | null;
   readonly answerContent: string;
-  readonly edits: readonly ProposedEdit[];
   readonly raised: boolean;
   readonly executionTimeMs: number;
   /** User-created variable names after this exec (builtins/context filtered out). */

package/src/sandbox/sandbox-manager.ts

@@ -81,17 +81,17 @@ export class SandboxManager {
   }
 
   /**
-   * Execute code in the sandbox. Serializes concurrent calls via a promise queue
-   * (second call waits for first to complete, no interleaving). On failure,
-   * nullifies the sandbox so the next call recreates it (death-recreate).
+   * Execute code in the sandbox with no per-invocation setup. Serializes concurrent calls via
+   * a promise queue (second call waits for the first, no interleaving). On failure the sandbox
+   * is nullified so the next call recreates it (death-recreate).
    */
   async exec(code: string): Promise<ReplResult> {
     return this.execQueued(code);
   }
 
   /**
-   * Execute code after running setup inside the serialized execution slot.
-   * Use this for per-invocation handler state that must match the active REPL run.
+   * Execute code after running `setup` inside the serialized execution slot, so per-invocation
+   * handler state (emitter, limits, depth) always matches the active REPL run.
    */
   async execWithSetup(code: string, setup: () => void): Promise<ReplResult> {
     return this.execQueued(code, setup);

package/src/sandbox/sandbox.ts

@@ -24,14 +24,18 @@ import {
   type WorkerRequest,
   type WorkerResponse,
 } from "./protocol.ts";
-import { formatError } from "../util/errors.ts";
+import { errorMessage, formatError } from "../util/errors.ts";
 
 /** Result of a host-side library pack requested by `load_library`. */
 export interface LibraryLoadResult {
-  readonly payload: unknown;     // string (single file) or ContextFile[] (packed dir/repo)
-  readonly index: number;        // slot assigned by the host
+  readonly payload: unknown;     // always ContextFile[] under lib/<id>/
+  readonly index: number;        // resume-sidecar index (not a REPL var name); -1 if alreadyLoaded
   readonly files?: number;
   readonly chars: number;
+  readonly sourceId: string;
+  readonly pathPrefix: string;
+  /** Host already has this library — no pack, no sidecar, empty payload. */
+  readonly alreadyLoaded?: boolean;
 }
 
 /** Handlers the bridge installs to service sub-LLM interrupts. Return the reply payload. */
@@ -64,9 +68,15 @@ export interface SandboxOptions {
   readonly initTimeoutMs?: number;
   /** Sub-LLM prompt cap (chars) — sizes llm_query_chunked chunks inside the worker. */
   readonly maxPromptChars?: number;
+  /**
+   * When true, the worker rejects open() write modes (pipeline read-only runs).
+   * Native repl() data work leaves this false so scratch-file writes still work.
+   */
+  readonly readOnly?: boolean;
 }
 
 const WORKER_PATH = join(dirname(fileURLToPath(import.meta.url)), "worker.py");
+const STDERR_TAIL_CHARS = 8_192;
 const TODO_PROTO_KEYS = new Set(["type", "rid", "depth", "action"]);
 
 // The sandbox runs untrusted model-authored code; it must never inherit provider secrets.
@@ -115,7 +125,23 @@ export class PythonSandbox {
   private readonly handlers: SubLlmHandlers;
   private readonly requestTimeoutMs: number;
   private readonly initTimeoutMs: number;
-  private stderr = "";
+  /** Bounded stderr tail (chunks, newest last) — avoids rebuilding the buffer per chunk. */
+  private readonly stderrTail: string[] = [];
+  private stderrLen = 0;
+
+  /** Bounded tail of everything written to stderr, oldest chunks already dropped. */
+  private get stderr(): string {
+    return this.stderrTail.join("");
+  }
+
+  /** Record a diagnostic on the same bounded tail as real worker stderr. */
+  private appendStderr(text: string): void {
+    this.stderrTail.push(text);
+    this.stderrLen += text.length;
+    while (this.stderrLen > STDERR_TAIL_CHARS && this.stderrTail.length > 1) {
+      this.stderrLen -= (this.stderrTail.shift() ?? "").length;
+    }
+  }
   private disposed = false;
   private ready: Promise<void>;
 
@@ -132,6 +158,9 @@ export class PythonSandbox {
     if (opts.maxPromptChars !== undefined) {
       workerArgs.push("--max-prompt-chars", String(opts.maxPromptChars));
     }
+    if (opts.readOnly) {
+      workerArgs.push("--read-only");
+    }
     this.proc = spawn(
       python,
       workerArgs,
@@ -141,9 +170,7 @@ export class PythonSandbox {
     this.proc.stdout.setEncoding("utf8");
     this.proc.stdout.on("data", (chunk: string) => this.onData(chunk));
     this.proc.stderr.setEncoding("utf8");
-    this.proc.stderr.on("data", (chunk: string) => {
-      this.stderr = (this.stderr + chunk).slice(-8192);
-    });
+    this.proc.stderr.on("data", (chunk: string) => this.appendStderr(chunk));
     this.proc.on("error", (err: NodeJS.ErrnoException) => {
       const hint = err.code === "ENOENT" ? ` ('${python}' not found — is Python installed and on PATH?)` : "";
       this.failAll(new Error(`failed to start sandbox${hint}: ${err.message}`));
@@ -177,12 +204,12 @@ export class PythonSandbox {
     return sandbox;
   }
 
-  async loadContext(payload: unknown, index?: number): Promise<number> {
+  async loadContext(payload: unknown): Promise<number> {
     const isJson = typeof payload !== "string";
     let path: string | undefined;
     try {
       path = await this.writeContextFile(payload, isJson);
-      const res = await this.request({ type: "load_context", path, index, json: isJson });
+      const res = await this.request({ type: "load_context", path, json: isJson });
       if (!res.ok) throw new Error(res.error ?? "load_context failed");
       return res.index ?? 0;
     } finally {
@@ -212,7 +239,6 @@ export class PythonSandbox {
       stderr: res.stderr ?? "",
       finalAnswer: res.final_answer ?? null,
       answerContent: res.answer_content ?? "",
-      edits: res.edits ?? [],
       raised: res.raised ?? false,
       executionTimeMs: Math.round((res.execution_time ?? 0) * 1000),
       varNames: res.var_names ?? [],
@@ -297,15 +323,6 @@ export class PythonSandbox {
     }
   }
 
-  /**
-   * Refresh the parent-side request watchdog for every pending request.
-   * Used during long mid-exec work (e.g. serial implement fanout) that does not
-   * produce additional worker interrupts on this sandbox.
-   */
-  refreshWatchdog(): void {
-    this.touchPending();
-  }
-
   private send(msg: ParentMessage): void {
     this.proc.stdin.write(`${JSON.stringify(msg)}\n`);
   }
@@ -320,11 +337,11 @@ export class PythonSandbox {
         try {
           const message = JSON.parse(line) as unknown;
           if (isWorkerMessage(message)) this.dispatch(message);
-          else this.stderr = `${this.stderr}\n[protocol] skipped invalid stdout message: ${line.slice(0, 200)}`.slice(-8192);
+          else this.appendStderr(`\n[protocol] skipped invalid stdout message: ${line.slice(0, 200)}`);
         } catch {
           // Non-JSON line on the protocol stream — likely a subprocess writing to fd 1.
           // Skip it so a rogue write doesn't kill the pump, but retain a breadcrumb for watchdog errors.
-          this.stderr = `${this.stderr}\n[protocol] skipped non-JSON stdout line: ${line.slice(0, 200)}`.slice(-8192);
+          this.appendStderr(`\n[protocol] skipped non-JSON stdout line: ${line.slice(0, 200)}`);
         }
       }
     }
@@ -381,14 +398,34 @@ export class PythonSandbox {
         this.reply(msg.rid, { response });
       } else if (msg.type === "load_library") {
         const lib = await h.loadLibrary(msg.source ?? "", d);
-        const isJson = typeof lib.payload !== "string";
-        const path = await this.writeContextFile(lib.payload, isJson);
-        // Worker reads then unlinks (worker._load_library). Host must not unlink here —
-        // if the worker is SIGKILLed before os.remove, the temp file leaks in tmpdir (acceptable).
-        this.reply(msg.rid, { path, json: isJson, index: lib.index, files: lib.files, chars: lib.chars });
+        if (lib.alreadyLoaded) {
+          // No temp file — worker short-circuits on already_loaded.
+          this.reply(msg.rid, {
+            already_loaded: true,
+            index: lib.index,
+            files: 0,
+            chars: lib.chars,
+            source_id: lib.sourceId,
+            path_prefix: lib.pathPrefix,
+          });
+        } else {
+          const isJson = typeof lib.payload !== "string";
+          const path = await this.writeContextFile(lib.payload, isJson);
+          // Worker reads then unlinks (worker._load_library). Host must not unlink here —
+          // if the worker is SIGKILLed before os.remove, the temp file leaks in tmpdir (acceptable).
+          this.reply(msg.rid, {
+            path,
+            json: isJson,
+            index: lib.index,
+            files: lib.files,
+            chars: lib.chars,
+            source_id: lib.sourceId,
+            path_prefix: lib.pathPrefix,
+          });
+        }
       }
     } catch (err) {
-      this.reply(msg.rid, { error: err instanceof Error ? err.message : String(err) });
+      this.reply(msg.rid, { error: errorMessage(err) });
     }
   }
 
@@ -401,6 +438,9 @@ export class PythonSandbox {
     index?: number;
     files?: number;
     chars?: number;
+    source_id?: string;
+    path_prefix?: string;
+    already_loaded?: boolean;
     error?: string;
   }): void {
     if (!this.disposed) this.send({ type: "llm_reply", rid, ...body });