@hicaru/pi-rlm 0.1.0

package/src/prompts/system.ts

@@ -0,0 +1,278 @@
+/**
+ * RLM system prompt (ported from rlm/utils/prompts.py).
+ *
+ * The root model runs Python by writing fenced ```repl``` blocks (headless engine). The REPL
+ * exposes `context`, the sub-LLM functions, and the `answer` dict the model flips to submit.
+ */
+import type { ContextSizeStats } from "../text/tokens.ts";
+
+export interface PromptMeta {
+  readonly contextType: string;
+  readonly contextChars: number;
+  readonly contextStats?: ContextSizeStats;
+  readonly rootPrompt?: string;
+}
+
+export interface SystemPromptOptions {
+  readonly orchestrator?: boolean;
+  readonly recursion?: boolean;
+  readonly askUserQuestion?: boolean;
+  readonly todo?: boolean;
+}
+
+function howToRunCode(): string {
+  return [
+    "To run Python, write a fenced ```repl``` block. The REPL **persists** across turns. Only",
+    "`print(...)` output (stdout) is returned; a bare expression on the last line is discarded, so",
+    "always wrap inspections in `print(...)`.",
+  ].join(" ");
+}
+
+function replGlossary(recursion: boolean, askUserQuestion: boolean, todo: boolean): string {
+  const lines = [
+    "Available in the REPL:",
+    "- `context`: list[dict] — a pre-packed JSON array of every file in the repository. Each dict has",
+    "  keys: `path` (relative file path, str), `content` (file text, str), `tokens` (estimated count, int).",
+    "  For large repos, chunk `context` into batches and delegate to sub-LLMs — never dump raw file",
+    "  bodies into your own output.",
+    "",
+    "  Chunking example:",
+    "  ```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",
+    "      ])",
+    "  ```",
+    "- `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.",
+  ];
+  if (askUserQuestion) {
+    lines.push(
+      "- `ask_user_question(questions: list[dict]) -> list[dict]`: pause and present the user",
+      "  with 1-4 structured questions. Each question: {question, header, options: [{label, description}],",
+      "  multiSelect?}. Returns list of {question, selected: [label], custom?}.",
+      "  Use when you have 2-4 concrete options from your analysis and need a decision before proceeding.",
+      "  DO NOT ask open-ended chat questions — use concrete options grounded in code/data.",
+      "  Only valid at root depth; returns an error inside rlm_query sub-calls.",
+    );
+  }
+  if (todo) {
+    lines.push(
+      "- `todo(action, **kwargs) -> str`: manage a task list visible to the user.",
+      "  Actions: create(subject, description?, status='pending'), update(id, status?, activeForm?),",
+      "  list(filterStatus?), get(id), delete(id), clear().",
+      "  Status flow: pending → in_progress → completed.",
+      "  Use to plan multi-step work before starting, then mark tasks as you complete them.",
+    );
+  }
+  if (recursion) {
+    lines.push(
+      "- `rlm_query(prompt, model=None)` / `rlm_query_batched(prompts, model=None)`: recursive RLM",
+      "  sub-calls. Each child runs a full REPL loop internally — its entire conversation is PRIVATE",
+      "  and never enters your history. Only the final answer (a short string) is returned.",
+      "",
+      "  **Choosing between `llm_query` and `rlm_query`:**",
+      "  - `llm_query` for simple one-shot tasks — summarize a chunk, extract a fact, answer a direct",
+      "    question. It is a single LLM call: fast and cheap. Prefer it by default, and fan out with",
+      "    `llm_query_batched` for parallel one-shots.",
+      "  - `rlm_query` only when a sub-task genuinely needs iterative reasoning with its own code",
+      "    execution (e.g. a sub-context large enough to need its own chunking, or a multi-step",
+      "    reasoning chain). It is slower and more expensive — reserve it for cases `llm_query` cannot",
+      "    handle. Avoid excessive recursive sub-calls when a batched one-shot would suffice.",
+    );
+  }
+  lines.push(
+    "- `advance_phase(phase: str, summary=None) -> str`: transition the root RLM pipeline to the next phase.",
+    "  Valid phases in order: 'research' → 'blueprint' → 'implement' → 'validate'. You must advance forward",
+    "  one phase at a time. Only callable at the root depth; returns an error in sub-RLM contexts.",
+  );
+  lines.push(
+    "- `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`.',
+  );
+  return lines.join("\n");
+}
+
+const ORCHESTRATOR_ADDENDUM = [
+  "As an RLM you are an **orchestrator, not a solver**. After you probe `context` and understand the",
+  "task, pause and plan: state how the task decomposes into sub-LLM / REPL steps, then execute one step",
+  "at a time, printing a small sample of each result to verify before moving on.",
+  "",
+  "Your own context window is small. Push every long-context operation — reading, summarizing,",
+  "classifying, answering sub-questions — into `llm_query` / `llm_query_batched` instead of pulling raw",
+  "text into your own message stream. Conversely, if a Python keyword/regex search over `context` would",
+  "already pin the answer, just read it directly. Aggregate the small results back in Python.",
+  "",
+  "Sub-call budget is finite on two axes: (1) per-prompt capacity — keep each sub-prompt modestly sized",
+  "(a useful ceiling is ~100K characters), packing a chunk of many items per call; (2) batch fan-out —",
+  "keep batches to roughly ~20 prompts. Fat prompts in small batches beat thousands of tiny prompts.",
+  "If the workload exceeds both at once, filter aggressively in Python first, then batch the survivors.",
+  "",
+  "Reserve your own tokens for high-level decisions: what to ask next, how to combine sub-LM outputs,",
+  "when to finalize. Delegate everything else. Do not submit a final answer before inspecting `context`.",
+].join("\n");
+
+const INTRO = [
+  "You are a Recursive Language Model (RLM): a language model with a prompt and a very important",
+  "context stored in a Python REPL. You interact with the REPL turn-by-turn until you have an answer.",
+].join(" ");
+
+/** Build the full RLM system prompt. */
+export function buildRlmSystemPrompt(meta: PromptMeta, opts: SystemPromptOptions = {}): string {
+  const recursion = opts.recursion ?? false;
+  const parts = [
+    INTRO,
+    "",
+    howToRunCode(),
+    "",
+    replGlossary(recursion, opts.askUserQuestion ?? false, opts.todo ?? false),
+    "",
+    "REPL stdout over ~800 characters is truncated to a short excerpt — large results stay in your",
+    "REPL variables as buffers. Re-print only the slice you need (e.g. `print(result[:500])`); never",
+    "dump a whole sub-LLM result. The full content persists across turns in REPL variables (call `SHOW_VARS()`).",
+    "",
+    "Start by probing `context` (print a few lines, count items). Then build up an answer to the query.",
+  ];
+  if (opts.orchestrator ?? true) {
+    parts.push("", ORCHESTRATOR_ADDENDUM);
+  }
+  parts.push("", buildMetadataLine(meta));
+  return parts.join("\n");
+}
+
+/** Adapts the REPL glossary for native mode — agent calls `repl({code})` instead of writing ```repl``` blocks. */
+function nativeReplGlossary(): string {
+  return [
+    "## RLM Native Mode — Persistent Python REPL",
+    "",
+    "Call `repl({code: \"...\"})` to execute Python in a **persistent** sandbox. Variables, imports,",
+    "and state survive across calls — you build up results incrementally. Only `print()` output is",
+    "returned, so always wrap inspections in `print(...)`.",
+    "",
+    "### REPL Environment",
+    "- `context`: list[dict] — every file in the repository. Each dict: `path` (str), `content` (str), `tokens` (int).",
+    "- `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.",
+    "- `rlm_query(prompt, model=None) -> str` — recursive RLM with its own REPL for complex sub-tasks needing iterative reasoning.",
+    "- `rlm_query_batched(prompts, model=None) -> list[str]` — concurrent recursive RLM calls.",
+    "",
+    "**Choosing between `llm_query` and `rlm_query`:** default to `llm_query` (fast/cheap) for one-shot tasks",
+    "and fan out with `llm_query_batched`; reach for `rlm_query` only when a sub-task needs its own iterative",
+    "reasoning. Avoid excessive recursive sub-calls when a batched one-shot suffices.",
+    "- `todo(action, **kwargs) -> str` — manage a task list. Actions: create, update, list, get, delete, clear. Statuses: pending → in_progress → completed.",
+    "- `SHOW_VARS() -> str` — list all variables currently in the REPL.",
+    "- `answer`: dict `{\"content\": \"\", \"ready\": False}`. To submit: `answer[\"content\"] = \"...\"; answer[\"ready\"] = True`.",
+    "",
+    "### 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.",
+    "",
+    "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",
+    "```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",
+    "```",
+    "- Keep sub-prompts ~100K characters; batch ~20 prompts per call. Fat prompts in small batches > thousands of tiny prompts.",
+    "- If your `context` is small enough (<20 files), you CAN read files directly via `read` / `grep` / `zebra-mcp`.",
+    "- For medium/large repos, delegate to sub-LLMs via the REPL.",
+    "",
+    "### Choosing Between Tools",
+    "| Tool | When |",
+    "|------|------|",
+    "| `repl({code})` | Need to chunk/delegate `context` to sub-LLMs; need Python scripting; need REPL state across calls |",
+    "| `read` / `grep` | Inspect a few specific files directly; small codebase |",
+    "| `zebra-mcp` | Semantic search over the codebase |",
+    "| `apply_diff({diff})` | Apply a unified diff to any file — shows patch preview before writing |",
+    "| `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 |",
+    "",
+    "### 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**: Set `answer[\"content\"]` and `answer[\"ready\"] = True`, or just write your final answer as a normal message.",
+    "",
+    "### Task-Specific Patterns",
+    "",
+    "**Architecture analysis / \"learn this project\" / diagram**:",
+    "1. Probe → `repl()` to list all files grouped by directory",
+    "2. Chunk → split files into module batches (~10-15 files each)",
+    "3. **DELEGATE ALL** → `llm_query_batched` on EVERY module: \"Summarize each file's role, what it exports, and how it connects\". Send ALL batches.",
+    "4. Aggregate → collect all sub-LLM summaries, synthesize diagram from them.",
+    "5. If sub-LLM credits exhausted → report to user: \"Credits exhausted after N batches. Results so far: ...\"",
+    "",
+    "**Bug investigation / \"find the issue\"**:",
+    "1. `repl()` → grep context for keywords (use Python re/in operators)",
+    "2. `llm_query` on matching files: \"Is there a bug here? What could cause X?\"",
+    "",
+    "**Full code review / audit**:",
+    "1. `repl()` → chunk all files, delegate ALL to `llm_query_batched` with review criteria",
+    "2. Aggregate findings, report to user",
+    "",
+    "CRITICAL: Never read files directly. If sub-LLMs fail → report, don't fall back to read.",
+    "",
+    "### Handling Sub-LLM Failures",
+    "Sub-LLM calls can fail (credit limits, rate limits, timeouts). Handle gracefully:",
+    "",
+    "| Failure | Action |",
+    "|---------|--------|",
+    "| `llm_query_batched` all fail | Reduce batch size (try 3-5 instead of 10+). If still failing, use individual `llm_query` calls. |",
+    "| Individual `llm_query` fails | Check error message. If credit/rate-limit, wait and retry once. If still failing, read files directly with `read`/`grep`. |",
+    "| `rlm_query` fails | Fall back to `llm_query` — it's a one-shot call that uses fewer resources. |",
+    "| All sub-LLMs exhausted | Read key files directly. For small repos (<20 files), direct reading is fine. For large repos, prioritize the most important files. |",
+    "",
+    "Reserve your own tokens for high-level decisions: what to ask next, how to combine sub-LLM outputs, when to finalize.",
+    "Delegate everything else. Do not submit a final answer before inspecting `context`.",
+  ].join("\n");
+}
+
+/** Build the native-mode system prompt for the main Pi agent. */
+export function buildNativeSystemPrompt(): string {
+  return [
+    "╔══════════════════════════════════════════════════════════════════╗",
+    "║  NATIVE RLM MODE — YOU ARE AN ORCHESTRATOR, NOT A READER      ║",
+    "╚══════════════════════════════════════════════════════════════════╝",
+    "",
+    "ABSOLUTE RESTRICTION: Do NOT use `read`, `grep`, or `bash` to access files.",
+    "All file content is pre-loaded in the REPL `context` variable. Use ONLY `repl({code})`.",
+    "You may read at most 2 hub files directly (README.md, package.json) for quick orientation.",
+    "If sub-LLM credits are exhausted → report the error to the user and stop.",
+    "",
+    "ABSOLUTE RESTRICTION: Do NOT use `write` or `edit` to modify files directly.",
+    "All file modifications MUST go through apply_diff({diff}).",
+    "The diff MUST be a complete unified diff with --- a/<path> / +++ b/<path> header and @@ hunk markers.",
+    "",
+    nativeReplGlossary(),
+  ].join("\n");
+}
+
+/** Exported for tests — prompt length without context metadata (which is injected separately). */
+export const NATIVE_PROMPT_STATIC = buildNativeSystemPrompt();
+
+/** The one-line context metadata, also reused by the per-turn prompt in headless mode. */
+export function buildMetadataLine(meta: PromptMeta): string {
+  const contextDesc = `Your context is a JSON array of ${meta.contextChars.toLocaleString()} total characters — list[dict] where each dict has keys "path" (str), "content" (str), and "tokens" (int). Use Python list slicing to chunk it into batches for sub-LLM delegation.`;
+  const tail = "Each sub-LLM call can handle roughly ~100k tokens at once.";
+  const dist = meta.contextStats
+    ? ` Your context has ${meta.contextStats.files} files; per-file tokens run min ${meta.contextStats.min.toLocaleString()} / median ${meta.contextStats.median.toLocaleString()} / max ${meta.contextStats.max.toLocaleString()} — use this to gauge how many files fit per batch.`
+    : "";
+  const body = `${contextDesc} ${tail}${dist}`;
+  return meta.rootPrompt ? `Answer the following: ${meta.rootPrompt}\n\n${body}` : body;
+}

package/src/prompts/user.ts

@@ -0,0 +1,21 @@
+/**
+ * Per-turn user prompts for the headless engine (ported from prompts.py `build_user_prompt`).
+ * Native mode does not use these — pi's own loop supplies the turns.
+ */
+
+export function buildTurnPrompt(iteration: number, maxIterations: number, gateMessage?: string): string {
+  const body = `Turn ${iteration + 1}/${maxIterations}:`;
+  const gate = gateMessage ? `\n${gateMessage}\n\n` : "";
+  if (iteration === 0) {
+    return (
+      "You have not interacted with the REPL or seen your context yet. Look at the context first; " +
+      `do not provide a final answer yet.\n\n${gate}${body}`
+    );
+  }
+  return `${gate}${body}`;
+}
+
+/** Asked once when the engine runs out of turns without a submitted answer. */
+export const FINALIZE_PROMPT =
+  "You are out of turns. Provide your best final answer now based on everything you have gathered, " +
+  'by setting `answer["content"]` and `answer["ready"] = True` (fenced ```repl```), or as plain text.';

package/src/sandbox/protocol.ts

@@ -0,0 +1,191 @@
+/**
+ * Wire protocol for the RLM Python sandbox.
+ *
+ * Newline-delimited JSON over the worker's stdin/stdout — no sockets, no HTTP.
+ * Parent -> worker: requests (exec/load_context/shutdown) and llm replies.
+ * Worker -> parent: request responses and mid-exec sub-LLM interrupts.
+ */
+
+/** Requests the parent sends to the worker. */
+export type WorkerRequest =
+  | { readonly id: string; readonly type: "exec"; readonly code: string }
+  | { readonly id: string; readonly type: "load_context"; readonly path: string; readonly index?: number; readonly json: boolean }
+  | { readonly id: string; readonly type: "snapshot"; readonly path: string; readonly nonce: string }
+  | { readonly id: string; readonly type: "restore"; readonly path: string; readonly nonce: string }
+  | { readonly id: string; readonly type: "shutdown" };
+
+/** Reply the parent sends to satisfy a sub-LLM interrupt. */
+export interface LlmReply {
+  readonly type: "llm_reply";
+  readonly rid: string;
+  readonly response?: string;
+  readonly responses?: readonly string[];
+  readonly answers?: readonly AskAnswer[];
+  readonly error?: string;
+}
+
+export type ParentMessage = WorkerRequest | LlmReply;
+
+export interface ProposedEdit {
+  readonly path: string;
+  readonly oldText: string;
+  readonly newText: string;
+}
+
+export interface ProposedDiffEdit {
+  readonly diff: string;
+}
+
+/** A normal response to a request (keyed by the request `id`). */
+export interface WorkerResponse {
+  readonly id: string;
+  readonly ok: boolean;
+  readonly error?: string;
+  // exec result fields:
+  readonly stdout?: string;
+  readonly stderr?: string;
+  readonly final_answer?: string | null;
+  readonly answer_content?: string;
+  readonly edits?: readonly ProposedEdit[];
+  readonly diffs?: readonly ProposedDiffEdit[];
+  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. */
+export type InterruptKind =
+  | "llm_query"
+  | "llm_query_batched"
+  | "rlm_query"
+  | "rlm_query_batched"
+  | "advance_phase"
+  | "ask_user_question"
+  | "todo";
+
+export interface AskOption {
+  readonly label: string;
+  readonly description?: string;
+  readonly preview?: string;
+}
+
+export interface AskQuestion {
+  readonly question: string;
+  readonly header: string;
+  readonly multiSelect?: boolean;
+  readonly options: readonly AskOption[];
+}
+
+export interface AskAnswer {
+  readonly question: string;
+  readonly selected: readonly string[];
+  readonly custom?: string;
+}
+
+export interface AskUserQuestionReply {
+  readonly answers: readonly AskAnswer[];
+}
+
+interface InterruptBase {
+  readonly rid: string;
+  readonly depth: number;
+}
+
+interface PromptInterrupt extends InterruptBase {
+  readonly type: "llm_query" | "rlm_query";
+  readonly prompt?: string;
+  readonly model?: string | null;
+}
+
+interface BatchedPromptInterrupt extends InterruptBase {
+  readonly type: "llm_query_batched" | "rlm_query_batched";
+  readonly prompts?: readonly string[];
+  readonly model?: string | null;
+}
+
+interface AdvancePhaseInterrupt extends InterruptBase {
+  readonly type: "advance_phase";
+  readonly phase?: string;
+  readonly summary?: string;
+}
+
+export interface AskUserQuestionInterrupt extends InterruptBase {
+  readonly type: "ask_user_question";
+  readonly questions: readonly AskQuestion[];
+}
+
+export interface TodoInterrupt extends InterruptBase {
+  readonly type: "todo";
+  readonly action: "create" | "update" | "list" | "get" | "delete" | "clear";
+  readonly id?: number;
+  readonly subject?: string;
+  readonly description?: string;
+  readonly status?: "pending" | "in_progress" | "completed" | "deleted";
+  readonly activeForm?: string;
+  readonly blockedBy?: readonly number[];
+  readonly addBlockedBy?: readonly number[];
+  readonly removeBlockedBy?: readonly number[];
+  readonly owner?: string;
+  readonly filterStatus?: string;
+  readonly includeDeleted?: boolean;
+}
+
+/** A mid-exec sub-LLM/tool request from the worker. */
+export type WorkerInterrupt =
+  | PromptInterrupt
+  | BatchedPromptInterrupt
+  | AdvancePhaseInterrupt
+  | AskUserQuestionInterrupt
+  | TodoInterrupt;
+
+export type WorkerMessage = WorkerResponse | WorkerInterrupt;
+
+export const INTERRUPT_KINDS = Object.freeze(new Set<InterruptKind>([
+  "llm_query",
+  "llm_query_batched",
+  "rlm_query",
+  "rlm_query_batched",
+  "advance_phase",
+  "ask_user_question",
+  "todo",
+]));
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isWorkerResponse(value: unknown): value is WorkerResponse {
+  return isRecord(value) && typeof value.id === "string" && typeof value.ok === "boolean";
+}
+
+export function isInterrupt(msg: unknown): msg is WorkerInterrupt {
+  return isRecord(msg)
+    && typeof msg.type === "string"
+    && INTERRUPT_KINDS.has(msg.type as InterruptKind)
+    && typeof msg.rid === "string"
+    && typeof msg.depth === "number";
+}
+
+export function isWorkerMessage(msg: unknown): msg is WorkerMessage {
+  return isWorkerResponse(msg) || isInterrupt(msg);
+}
+
+/** Result of a single `repl` block execution, surfaced to the engine/tool. */
+export interface ReplResult {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly finalAnswer: string | null;
+  readonly answerContent: string;
+  readonly edits: readonly ProposedEdit[];
+  readonly diffs: readonly ProposedDiffEdit[];
+  readonly raised: boolean;
+  readonly executionTimeMs: number;
+  /** User-created variable names after this exec (builtins/context filtered out). */
+  readonly varNames: readonly string[];
+}

package/src/sandbox/sandbox-manager.ts

@@ -0,0 +1,143 @@
+/**
+ * SandboxManager — persistent singleton owning one PythonSandbox across
+ * multiple repl() calls. Handles lazy creation, death-recreate, serialized
+ * execution via a promise queue, and idempotent disposal.
+ */
+
+import { PythonSandbox, type SubLlmHandlers } from "./sandbox.ts";
+import type { ReplResult } from "./protocol.ts";
+
+/** Static configuration for sandbox creation — set once, reused across getOrCreate calls. */
+export interface SandboxManagerConfig {
+  readonly execTimeoutS: number;
+  readonly requestTimeoutMs: number;
+  readonly python: string;
+  readonly sandboxInitTimeoutMs: number;
+  readonly signal?: AbortSignal;
+}
+
+export class SandboxManager {
+  private sandbox: PythonSandbox | null = null;
+  private disposed = false;
+  private initPromise: Promise<PythonSandbox> | null = null;
+  /** Serialized execution queue — concurrent repl() calls wait for predecessor. */
+  private execQueue: Promise<void> = Promise.resolve();
+  private pendingExecCount = 0;
+  /** Context payload to load on first sandbox creation. Set externally before getOrCreate. */
+  contextPayload: unknown = null;
+  /** True once contextPayload has been loaded into the sandbox (prevents reload + race fix). */
+  private contextLoaded = false;
+
+  constructor(private readonly config: SandboxManagerConfig) {}
+
+  /**
+   * Lazy get-or-create the sandbox. On first call, spawns PythonSandbox with the
+   * given handlers. Subsequent calls return the existing sandbox immediately.
+   * Deduplicates concurrent calls via initPromise.
+   *
+   * The caller is responsible for calling loadContext() on the returned sandbox
+   * before first use.
+   */
+  async getOrCreate(handlers: Partial<SubLlmHandlers>): Promise<PythonSandbox> {
+    if (this.disposed) throw new Error("SandboxManager disposed");
+    if (this.sandbox) {
+      // RACE FIX: contextPayload may arrive after the sandbox was created (the
+      // "context" event's async packRepository resolves after the first repl() call).
+      // Load it into the live sandbox now if still pending.
+      if (this.contextPayload !== null && !this.contextLoaded) {
+        this.contextLoaded = true;
+        try { await this.sandbox.loadContext(this.contextPayload); } catch { /* best-effort */ }
+      }
+      return this.sandbox;
+    }
+
+    if (this.initPromise) return this.initPromise;
+
+    this.initPromise = PythonSandbox.spawn({
+      execTimeoutS: this.config.execTimeoutS,
+      requestTimeoutMs: this.config.requestTimeoutMs,
+      python: this.config.python,
+      signal: this.config.signal,
+      initTimeoutMs: this.config.sandboxInitTimeoutMs,
+      handlers,
+    }).then(async (s) => {
+      // Load context on first creation if available
+      if (this.contextPayload !== null) {
+        this.contextLoaded = true;
+        try { await s.loadContext(this.contextPayload); } catch { /* best-effort */ }
+      }
+      this.sandbox = s;
+      this.initPromise = null;
+      return s;
+    }).catch((err) => {
+      this.initPromise = null;
+      throw err;
+    });
+
+    return this.initPromise;
+  }
+
+  /**
+   * 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).
+   */
+  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.
+   */
+  async execWithSetup(code: string, setup: () => void): Promise<ReplResult> {
+    return this.execQueued(code, setup);
+  }
+
+  private async execQueued(code: string, setup?: () => void): Promise<ReplResult> {
+    if (!this.sandbox) throw new Error("Sandbox not initialized — call getOrCreate first");
+
+    // Serialize: queue behind any in-flight execution
+    const prev = this.execQueue;
+    let resolveNext: () => void = () => {};
+    this.execQueue = new Promise<void>((r) => { resolveNext = r; });
+    this.pendingExecCount++;
+    await prev;
+
+    try {
+      const sandbox = this.sandbox;
+      if (!sandbox) throw new Error("Sandbox not initialized — previous execution disposed it");
+      setup?.();
+      return await sandbox.exec(code);
+    } catch (err) {
+      // Death-recreate: worker died — nullify so next repl() recreates
+      if (this.sandbox) {
+        // Best-effort dispose of the dead sandbox
+        try { await this.sandbox.dispose(); } catch { /* already dead */ }
+        this.sandbox = null;
+      }
+      throw err;
+    } finally {
+      this.pendingExecCount--;
+      resolveNext();
+    }
+  }
+
+  /** True if the sandbox is alive and not disposed. */
+  get isAlive(): boolean {
+    return this.sandbox !== null && !this.disposed;
+  }
+
+  /** True if a repl() execution is currently in-flight or queued. */
+  get isExecuting(): boolean {
+    return this.pendingExecCount > 0;
+  }
+
+  /** Idempotent dispose. Safe to call multiple times. */
+  async dispose(): Promise<void> {
+    if (this.disposed) return;
+    this.disposed = true;
+    await this.sandbox?.dispose();
+    this.sandbox = null;
+  }
+}