@hicaru/pi-rlm 0.1.8 → 0.1.9

package/src/core/gates.ts

@@ -78,6 +78,35 @@ export function countHeadingsOutsideFences(content: string, re: RegExp): number
   return count;
 }
 
+/** Count newlines without materialising a line array. */
+export function lineCountOf(text: string): number {
+  let count = 1;
+  for (let i = 0; i < text.length; i++) if (text.charCodeAt(i) === 10) count++;
+  return count;
+}
+
+/** Names of `## Phase N:` sections that contain no `### Success Criteria` heading. */
+export function phasesMissingSuccessCriteria(content: string): readonly string[] {
+  const missing: string[] = [];
+  let currentPhase: string | undefined;
+  let sawCriteria = false;
+  const flush = (): void => {
+    if (currentPhase !== undefined && !sawCriteria) missing.push(currentPhase);
+  };
+  forEachLineOutsideFences(content, (line) => {
+    const phase = /^## Phase (\d+):/.exec(line);
+    if (phase) {
+      flush();
+      currentPhase = `Phase ${phase[1] ?? "?"}`;
+      sawCriteria = false;
+      return;
+    }
+    if (currentPhase !== undefined && /^### Success Criteria/.test(line)) sawCriteria = true;
+  });
+  flush();
+  return Object.freeze(missing);
+}
+
 /**
  * Fence-aware count of top-level (column-0) `- ` bullets under a `## <heading>` section.
  * Nested/indented sub-bullets are ignored. The next `## ` heading ends the section.
@@ -207,7 +236,7 @@ export function verifyCitations(body: string, cwd: string): GateResult<undefined
     }
     let lineCount: number;
     try {
-      lineCount = readFileSync(abs, "utf-8").split("\n").length;
+      lineCount = lineCountOf(readFileSync(abs, "utf-8"));
     } catch {
       errors.push(`unbacked citation ${key} — file could not be read`);
       continue;

package/src/core/pipeline.ts

@@ -1,11 +1,14 @@
 /**
  * RLM pipeline stage graph — data-driven transitions with deterministic gates.
  *
- * Stages: clarify → research → blueprint → implement → validate
+ * Stages: clarify → research → blueprint → validate
  * (clarify skipped when askUserQuestion is off).
  * The root RLM writes artifacts via save_artifact(); advance_phase() is gated by
  * TypeScript floors (never LLM judgment). Validate routes on measured
  * blockers_count with a bounded corrective loop back to blueprint.
+ * The pipeline is read-only by design: it produces a validated plan and does not
+ * write source. Accidental sandbox writes are blocked (open/pathlib/os.open);
+ * this is steering, not a hard security boundary.
  */
 import {
   checkStatusReady,
@@ -19,16 +22,31 @@ import {
   verifyCitations,
 } from "./gates.ts";
 
-export type Phase = "clarify" | "research" | "blueprint" | "implement" | "validate";
+export type Phase = "clarify" | "research" | "blueprint" | "validate";
 
 export const PHASES = Object.freeze([
   "clarify",
   "research",
   "blueprint",
-  "implement",
   "validate",
 ] as const satisfies readonly Phase[]);
 
+const PHASE_SET: ReadonlySet<string> = Object.freeze(new Set<string>(PHASES));
+
+export function isPhase(value: unknown): value is Phase {
+  return typeof value === "string" && PHASE_SET.has(value);
+}
+
+/**
+ * Map a persisted phase name onto the current graph. Trails written before the
+ * implement phase was retired resume at `blueprint` — the last phase whose
+ * artifact is still meaningful.
+ */
+export function reconcilePhase(persisted: unknown): Phase {
+  if (isPhase(persisted)) return persisted;
+  return "blueprint";
+}
+
 /** Kind string the model passes to save_artifact(kind, content). */
 export type ArtifactKind = "clarification" | "research" | "plan" | "validation";
 
@@ -37,8 +55,7 @@ export type StageGateData =
   | { readonly kind: "clarification"; readonly clarification: ClarificationGateData }
   | { readonly kind: "research" }
   | { readonly kind: "plan"; readonly plan: PlanGateData }
-  | { readonly kind: "validation"; readonly validation: ValidationGateData }
-  | { readonly kind: "side-effect" };
+  | { readonly kind: "validation"; readonly validation: ValidationGateData };
 
 export interface StageDef {
   readonly phase: Phase;
@@ -90,13 +107,6 @@ export const STAGES: Readonly<Record<Phase, StageDef>> = Object.freeze({
   clarify: { phase: "clarify", artifactDir: "clarifications", artifactKind: "clarification", gate: clarifyGate },
   research: { phase: "research", artifactDir: "research", artifactKind: "research", gate: researchGate },
   blueprint: { phase: "blueprint", artifactDir: "plans", artifactKind: "plan", gate: blueprintGate },
-  // implement is a side-effect stage; exit is engine-driven (serial fanout).
-  implement: {
-    phase: "implement",
-    artifactDir: "",
-    artifactKind: "",
-    gate: (): GateResult<StageGateData> => ({ ok: true, value: { kind: "side-effect" } }),
-  },
   validate: { phase: "validate", artifactDir: "validations", artifactKind: "validation", gate: validateGate },
 });
 
@@ -115,12 +125,27 @@ export function stageForArtifactKind(kind: string): StageDef | undefined {
   return undefined;
 }
 
+/** An artifact path plus its lifecycle status — append-only, never deleted. */
+export interface ArtifactRef {
+  readonly path: string;
+  readonly status: "active" | "superseded";
+  /** Path of the artifact that superseded this one (the rejecting validation). */
+  readonly supersededBy?: string;
+}
+
+/** The latest artifact saved for a stage, plus its gate result when it passed. */
+export interface SavedArtifact {
+  readonly path: string;
+  /** Gate payload when the artifact passed; undefined ⇒ advance_phase must re-gate. */
+  readonly gateData?: StageGateData;
+}
+
 export interface PhaseState {
   readonly current: Phase;
   readonly advancedAt: number;
   readonly summary?: string;
   /** Artifact each completed stage produced — the named channels. */
-  readonly artifacts: Readonly<Partial<Record<Phase, string>>>;
+  readonly artifacts: Readonly<Partial<Record<Phase, ArtifactRef>>>;
   /** Corrective validate→blueprint re-entries taken so far. */
   readonly backwardJumps: number;
 }

package/src/core/types.ts

@@ -1,7 +1,7 @@
 /** Shared configuration + runtime types for the RLM engine. */
 
 import type { ThinkingLevel } from "@earendil-works/pi-ai";
-import type { AskAnswer, AskQuestion, ProposedEdit } from "../sandbox/protocol.ts";
+import type { AskAnswer, AskQuestion } from "../sandbox/protocol.ts";
 import type { ReconstructResult } from "../state/resume.ts";
 
 export interface Sampling {
@@ -105,8 +105,6 @@ export interface RlmInput {
 /** Result of a completed RLM run. */
 export interface RlmResult {
   readonly answer: string;
-  /** Legacy anchor edits retained for compatibility while older run-state rows exist. */
-  readonly edits?: readonly ProposedEdit[];
   readonly iterations: number;
   readonly costUsd: number;
   readonly inputTokens: number;

package/src/index.ts

@@ -7,8 +7,6 @@ import { registerRlmCommand } from "./commands/rlm.ts";
 import { registerRlmConfigCommand } from "./commands/rlm-config.ts";
 import { createRlmTool } from "./tool/rlm-tool.ts";
 import { createReplTool } from "./tool/repl-tool.ts";
-import { createApplyEditsTool } from "./tool/apply-edits-tool.ts";
-import { EditRegistry } from "./registry/edit-registry.ts";
 import { loadSettings, mergeConfig, resolveModelId } from "./config/settings.ts";
 import { RlmController, cheapestModel } from "./mode/rlm-mode.ts";
 import { postRlmGuide } from "./ui/intro.ts";
@@ -26,7 +24,6 @@ export default function rlmExtension(pi: ExtensionAPI): void {
   // Init synchronously with defaults — ensures commands/tools/handlers register before session_start
   const config = mergeConfig({});
   const controller = new RlmController(config);
-  const editRegistry = new EditRegistry();
   let onSandboxDiscardExtra: (() => void) | undefined;
   const sandboxManager = new SandboxManager({
     execTimeoutS: config.execTimeoutS,
@@ -34,10 +31,7 @@ export default function rlmExtension(pi: ExtensionAPI): void {
     python: config.python,
     sandboxInitTimeoutMs: config.sandboxInitTimeoutMs,
     maxPromptChars: config.maxPromptChars,
-    onSandboxDiscarded: () => {
-      editRegistry.clear();
-      onSandboxDiscardExtra?.();
-    },
+    onSandboxDiscarded: () => { onSandboxDiscardExtra?.(); },
   });
   let packedContextText: string | undefined;
   let contextPackPromise: Promise<string | undefined> | undefined;
@@ -85,7 +79,6 @@ export default function rlmExtension(pi: ExtensionAPI): void {
 
   // ── Tool registration ──
   pi.registerTool(createRlmTool(controller));
-  pi.registerTool(createApplyEditsTool(editRegistry));
   let guidePosted = false;
 
   pi.on("session_start", async (_event, ctx) => {
@@ -109,7 +102,6 @@ export default function rlmExtension(pi: ExtensionAPI): void {
           getModel: () => controller.resolveModels(ctx)?.model,
           getWorkerModel: () => controller.resolveModels(ctx)?.worker,
           registry: ctx.modelRegistry,
-          editRegistry,
           config: controller.config,
           registerDiscardHook: (reset) => { onSandboxDiscardExtra = reset; },
           ensureContext: async () => {

package/src/mode/native-guards.ts

@@ -86,7 +86,7 @@ export function replDelegationNudge(stdoutChars: number, delegated: boolean): st
   if (delegated || stdoutChars <= NUDGE_STDOUT_CHARS) return undefined;
   return (
     `\n[RLM: this repl() printed ${stdoutChars.toLocaleString()} chars with 0 sub-LLM calls — ` +
-    "delegate semantic reading via llm_query / llm_query_batched / llm_query_chunked instead of " +
-    "reading output yourself.]"
+    "if you were READING, delegate via llm_query / llm_query_batched / llm_query_chunked. " +
+    "Authoring an edit body yourself is correct and needs no delegation.]"
   );
 }

package/src/prompts/phases.ts

@@ -3,7 +3,6 @@
  * Injected at each phase boundary; the only channel between phases is durable
  * artifacts under .rlm/artifacts/.
  */
-import type { PhaseRecord } from "../core/gates.ts";
 import type { Phase } from "../core/pipeline.ts";
 
 const CLARIFY_GUIDANCE = Object.freeze([
@@ -48,7 +47,7 @@ const RESEARCH_GUIDANCE = Object.freeze([
   "Probe the repository, delegate long reads via `llm_query_batched` / `llm_query_chunked`.",
   "Every factual claim about the code MUST be cited as `path/file.ext:LINE` (or `LINE-LINE`).",
   "The engine VERIFIES citations against the working tree — unbacked citations reject advance.",
-  "When research is complete, write ONE research document and call:",
+  "When research is complete, write ONE research document with a `## Findings` section and call:",
   '  `save_artifact("research", content)`  # frontmatter must include `status: ready`',
   '  `advance_phase("blueprint", summary)`',
   "Do not implement code in this phase.",
@@ -59,39 +58,37 @@ const BLUEPRINT_GUIDANCE = Object.freeze([
   "Read the clarifications artifact (if present) and plan only within recorded Decisions;",
   "Open Questions that would block the design must be re-asked via ask_user_question, not assumed.",
   'Produce ONE plan document and save it with `save_artifact("plan", content)`.',
+  "This pipeline is read-only: it produces a plan a human or a native-mode agent executes;",
+  "do not write source files here (sandbox write modes are blocked).",
+  "Write changes as exact, copy-pasteable before/after code — never as prose instructions.",
   "The ENGINE derive-checks the document — these are hard gates, not suggestions:",
   "- frontmatter: `status: ready`, `phase_count: N`, `phases: [{n: 1, title: ...}, ...]`",
   "- `phases:` / `phase_count` MUST match the `## Phase N:` body headings exactly (fenced examples ignored)",
   "- every `file:line` citation MUST resolve against the working tree at this revision",
   "Each `## Phase N: <title>` section contains:",
-  "- `### Changes Required` — per file: path + exact intended change (code from research)",
+  "- `### Changes Required` — per file: path + the exact intended change",
   "- `### Success Criteria` — `#### Automated Verification:` (runnable commands) and",
   "  `#### Manual Verification:` checklists",
-  "Phases are executed by ISOLATED workers, one at a time, in order: each phase must be",
-  "independently implementable, leave the tree working, and never share a file with a",
-  "later phase unless that phase only EDITS what an earlier phase CREATED.",
-  'When ready: `advance_phase("implement", summary)` — the engine runs implement fanout itself.',
-].join("\n"));
-
-const IMPLEMENT_GUIDANCE = Object.freeze([
-  "## Implement phase",
-  "The engine drives serial child-RLM workers over each plan phase — you do not implement",
-  "here. If you were re-entered into implement unexpectedly, call",
-  '`advance_phase("validate")` only after the fanout has already completed.',
+  "Phases must be independently implementable in order, each leaving the tree working.",
+  'When ready: `advance_phase("validate", summary)`.',
 ].join("\n"));
 
 const VALIDATE_GUIDANCE = Object.freeze([
-  "## Validate phase",
+  "## Validate phase (adversarial plan review)",
+  "Nothing has been implemented — you are reviewing the PLAN, not a diff.",
   "Read the goal artifact (verbatim brief), the clarifications artifact (recorded Decisions),",
-  "and the plan. Check each phase's Success Criteria against the working tree.",
-  "Exclude paths listed in the baseline JSON (pre-existing dirt).",
-  "Open Questions are not silently resolved — a blocking one surfaces via ask_user_question.",
-  "Write ONE validation document via `save_artifact(\"validation\", content)` with frontmatter:",
+  "and the plan. For each plan phase check against the working tree:",
+  "- every cited `file:line` still resolves and says what the plan claims",
+  "- every file the phase edits exists (or is created by an earlier phase)",
+  "- no phase contradicts a recorded Decision or silently resolves an Open Question",
+  "- the Success Criteria are actually runnable and actually prove the change",
+  "- phases are independently implementable in the stated order",
+  "Write ONE review via `save_artifact(\"validation\", content)` with frontmatter:",
   "- `status: ready`",
-  "- `blockers_count: <int ≥ 0>`  # MEASURED — routing key; not prose",
+  "- `blockers_count: <int >= 0>`  # MEASURED — routing key; not prose",
   "- `verdict: pass | fail`  # pass requires blockers_count === 0",
   "Each blocker needs a resolvable `file:line` citation.",
-  "Then finalize: `answer[\"content\"] = <report>; answer[\"ready\"] = True`.",
+  "Then finalize: `answer[\"content\"] = <the reviewed plan + review summary>; answer[\"ready\"] = True`.",
   "If `blockers_count > 0`, the engine re-enters blueprint (bounded by maxBackwardJumps).",
 ].join("\n"));
 
@@ -99,27 +96,9 @@ const GUIDANCE: Readonly<Record<Phase, string>> = Object.freeze({
   clarify: CLARIFY_GUIDANCE,
   research: RESEARCH_GUIDANCE,
   blueprint: BLUEPRINT_GUIDANCE,
-  implement: IMPLEMENT_GUIDANCE,
   validate: VALIDATE_GUIDANCE,
 });
 
 export function phaseGuidance(phase: Phase): string {
   return GUIDANCE[phase];
 }
-
-/** Single-phase implement prompt for an isolated child RLM (serial fanout unit). */
-export function buildImplementPhasePrompt(planPath: string, r: PhaseRecord): string {
-  return [
-    `Implement ONLY Phase ${r.n} (${r.title}) of the plan at ${planPath} (${r.index + 1}/${r.total}).`,
-    `Read the plan from the REPL (open("${planPath}").read()).`,
-    "Hard rules (you are one unit of a sequenced run):",
-    "- CRITICAL: `context` is a STALE snapshot from run start. Always `open(path).read()` any file",
-    "  you will edit BEFORE computing stage_edit anchors — earlier phases may have already changed them.",
-    "- Touch ONLY the files this phase's ### Changes Required lists.",
-    "- Earlier phases have already landed; a missing prerequisite file is a HARD ERROR —",
-    "  finalize with 'Error: prerequisite missing: <path>' instead of creating it.",
-    "- Stage every change via stage_edit(path, old_text, new_text); never defer your own edits.",
-    "- Run only THIS phase's '#### Automated Verification:' commands; whole-plan checks are validate's job.",
-    `Finalize with a short summary of what landed for Phase ${r.n}.`,
-  ].join("\n");
-}

package/src/prompts/system.ts

@@ -141,13 +141,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 +180,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.",
@@ -262,9 +270,8 @@ function nativeReplGlossary(): string {
     "- `rlm_query_batched(prompts, model=None) -> list[str]` — concurrent recursive RLM calls.",
     "",
     "- `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",
@@ -293,18 +300,19 @@ function nativeReplGlossary(): string {
     "|------|------|",
     "| `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) |",
+    "| `edit` | Change an existing file. Compose oldText/newText yourself; exact match required |",
+    "| `write` | Create a new file |",
     "| `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.",
+    "4. **Finalize**: For file changes, call the native `edit` / `write` tools directly — you",
+    "   author the change, and Pi validates the anchor and renders the diff. For analysis tasks,",
+    "   write a normal message.",
     "",
     "### Task-Specific Patterns",
     LARGE_FILE_RULE_NATIVE,
@@ -336,9 +344,11 @@ export function buildNativeSystemPrompt(): string {
     "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");
@@ -357,7 +367,9 @@ export const NATIVE_TURN_REMINDER = [
   "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.]",
+  "slice, json) is free. 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 to a sub-LLM.",
+  "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/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,7 +46,6 @@ 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
@@ -201,7 +197,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.ts

@@ -28,10 +28,14 @@ import { 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,6 +68,11 @@ 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");
@@ -132,6 +141,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,
@@ -212,7 +224,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 ?? [],
@@ -299,7 +310,7 @@ 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
+   * Used during long mid-exec work that does not
    * produce additional worker interrupts on this sandbox.
    */
   refreshWatchdog(): void {
@@ -381,11 +392,31 @@ 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) });
@@ -401,6 +432,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 });