@hicaru/pi-rlm 0.2.1 → 0.2.2

package/src/sandbox/sandbox-manager.ts

@@ -6,6 +6,7 @@
 
 import { PythonSandbox, type SubLlmHandlers } from "./sandbox.ts";
 import type { ReplResult } from "./protocol.ts";
+import { mergeLibraryIntoContext } from "../context/library-context.ts";
 
 /** Static configuration for sandbox creation — set once, reused across getOrCreate calls. */
 export interface SandboxManagerConfig {
@@ -34,6 +35,18 @@ export class SandboxManager {
 
   constructor(private readonly config: SandboxManagerConfig) {}
 
+  /**
+   * Append a library payload to the context this manager replays on death-recreate.
+   *
+   * The live worker has ALREADY appended it in-process (worker.py `_append_library`), so this
+   * deliberately does not reload — it only keeps the host's replay copy truthful. Without it a
+   * recreate silently rolls the sandbox back to a repo-only context, and any child inheriting
+   * this payload would never see the library. Dedups by `lib/<id>/` prefix.
+   */
+  appendLibrary(payload: unknown): void {
+    this.contextPayload = mergeLibraryIntoContext(this.contextPayload, payload);
+  }
+
   /**
    * Lazy get-or-create the sandbox. On first call, spawns PythonSandbox with the
    * given handlers. Subsequent calls return the existing sandbox immediately.

package/src/sandbox/sandbox.ts

@@ -8,60 +8,23 @@
  */
 
 import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
-import { writeFile, unlink } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { once } from "node:events";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   isInterrupt,
   isWorkerMessage,
-  type AskAnswer,
-  type AskQuestion,
   type ParentMessage,
   type ReplResult,
-  type WorkerInterrupt,
   type WorkerMessage,
   type WorkerRequest,
   type WorkerResponse,
 } from "./protocol.ts";
-import { errorMessage, formatError } from "../util/errors.ts";
+import { pinContext, type PinnedContext } from "./context-file.ts";
+import { REJECT, serviceInterrupt, type ReplyBody, type SubLlmHandlers } from "./interrupts.ts";
 import { trace, traceEnabled } from "../util/trace.ts";
 
-/** Result of a host-side library pack requested by `load_library`. */
-export interface LibraryLoadResult {
-  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;
-}
-
-/**
- * Per-interrupt routing context for the sub-LLM handlers.
- *
- * Only the four sub-call kinds can be spawned, so only they carry it; the interactive and
- * pipeline handlers are always synchronous within one exec.
- */
-export interface SubcallOpts {
-  /** Started via `spawn()` — route to session-scoped state, not the current invocation. */
-  readonly detached: boolean;
-}
-
-/** Handlers the bridge installs to service sub-LLM interrupts. Return the reply payload. */
-export interface SubLlmHandlers {
-  llmQuery(prompt: string, model: string | null, depth: number, opts: SubcallOpts): Promise<string>;
-  llmQueryBatched(prompts: readonly string[], model: string | null, depth: number, opts: SubcallOpts): Promise<string[]>;
-  rlmQuery(prompt: string, model: string | null, depth: number, opts: SubcallOpts): Promise<string>;
-  rlmQueryBatched(prompts: readonly string[], model: string | null, depth: number, opts: SubcallOpts): Promise<string[]>;
-  advancePhase(phase: string, summary: string | undefined, depth: number): Promise<string>;
-  saveArtifact(kind: string, content: string, depth: number): Promise<string>;
-  askUserQuestion(questions: readonly AskQuestion[], depth: number): Promise<AskAnswer[]>;
-  todo(action: string, params: Record<string, unknown>, depth: number): Promise<string>;
-  loadLibrary(source: string, depth: number): Promise<LibraryLoadResult>;
-}
+export type { LibraryLoadResult, SubcallOpts, SubLlmHandlers } from "./interrupts.ts";
 
 export interface SandboxOptions {
   /** Sandbox recursion depth label (passed to the worker, used in interrupt routing). */
@@ -80,11 +43,6 @@ 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;
   /**
    * Max seconds the worker will wait for a host reply while parked in `_drain_until`
    * (rlm_await / sync sub-call). Defaults to the worker's own RLM_AWAIT_TIMEOUT_S (600).
@@ -92,9 +50,10 @@ export interface SandboxOptions {
   readonly awaitTimeoutS?: number;
 }
 
-const WORKER_PATH = join(dirname(fileURLToPath(import.meta.url)), "worker.py");
+const WORKER_PATH = join(dirname(fileURLToPath(import.meta.url)), "py", "worker.py");
 const STDERR_TAIL_CHARS = 8_192;
-const TODO_PROTO_KEYS = new Set(["type", "rid", "depth", "action"]);
+/** How long dispose() waits for a clean worker exit before escalating to SIGKILL. */
+const SHUTDOWN_GRACE_MS = 50;
 
 // The sandbox runs untrusted model-authored code; it must never inherit provider secrets.
 const SENSITIVE_ENV = /API[_-]?KEY|ACCESS[_-]?KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL|ANTHROPIC|OPENAI|_KEY$/i;
@@ -107,22 +66,6 @@ function sanitizedEnv(): NodeJS.ProcessEnv {
   return env;
 }
 
-const REJECT: SubLlmHandlers = {
-  llmQuery: async () => formatError("sub-LLM bridge not configured"),
-  llmQueryBatched: async (p) => p.map(() => formatError("sub-LLM bridge not configured")),
-  rlmQuery: async () => formatError("sub-LLM bridge not configured"),
-  rlmQueryBatched: async (p) => p.map(() => formatError("sub-LLM bridge not configured")),
-  advancePhase: async () => formatError("phase advancement not available"),
-  saveArtifact: async () => formatError("save_artifact not available"),
-  askUserQuestion: async (questions) => questions.map((q) => ({
-    question: q.question,
-    selected: [],
-    custom: formatError("ask_user_question not configured"),
-  })),
-  todo: async () => formatError("todo not configured"),
-  loadLibrary: async () => { throw new Error("load_library not configured"); },
-};
-
 /** Distributive omit so each union member keeps its own fields (plain Omit collapses to shared keys). */
 type RequestBody = WorkerRequest extends infer T ? (T extends { id: string } ? Omit<T, "id"> : never) : never;
 
@@ -175,9 +118,6 @@ export class PythonSandbox {
     if (opts.maxPromptChars !== undefined) {
       workerArgs.push("--max-prompt-chars", String(opts.maxPromptChars));
     }
-    if (opts.readOnly) {
-      workerArgs.push("--read-only");
-    }
     if (opts.awaitTimeoutS !== undefined) {
       workerArgs.push("--await-timeout", String(opts.awaitTimeoutS));
     }
@@ -191,11 +131,30 @@ export class PythonSandbox {
     this.proc.stdout.on("data", (chunk: string) => this.onData(chunk));
     this.proc.stderr.setEncoding("utf8");
     this.proc.stderr.on("data", (chunk: string) => this.appendStderr(chunk));
+
+    // A dead worker's pipe fails the write ASYNCHRONOUSLY: node emits 'error' on the stream, and
+    // an EventEmitter 'error' with no listener is an uncaughtException — which no try/catch
+    // around send() and no `await dispose().catch()` can intercept. Without these three
+    // listeners a worker dying mid-exec took the entire pi process down with it (EPIPE from the
+    // shutdown frame dispose() writes after the watchdog SIGKILLs).
+    // Record and swallow: the real reason is already surfaced by failAll on 'exit'.
+    const swallowPipeError = (stream: string) => (err: NodeJS.ErrnoException): void => {
+      this.appendStderr(`[rlm] worker ${stream} ${err.code ?? "error"}: ${err.message}\n`);
+    };
+    this.proc.stdin.on("error", swallowPipeError("stdin"));
+    this.proc.stdout.on("error", swallowPipeError("stdout"));
+    this.proc.stderr.on("error", swallowPipeError("stderr"));
+
     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}`));
     });
-    this.proc.on("exit", () => this.failAll(new Error(`worker exited; stderr=${this.stderr.trim()}`)));
+    // Name the cause: a SIGKILL (watchdog, abort, OOM killer) reads very differently from a
+    // Python-level crash, and this message is what reaches the user as `REPL error: …`.
+    this.proc.on("exit", (code, signal) => this.failAll(new Error(
+      `worker exited (${signal !== null ? `signal ${signal}` : `code ${code}`}); `
+      + `stderr=${this.stderr.trim()}`,
+    )));
 
     this.ready = this.waitForInit();
 
@@ -224,31 +183,27 @@ export class PythonSandbox {
     return sandbox;
   }
 
+  /**
+   * Load a payload whose pin this sandbox does not own — it acquires and releases one itself.
+   * Used by SandboxManager and tests; the engine owns its run's pin and calls the pinned form.
+   */
   async loadContext(payload: unknown): Promise<number> {
-    const isJson = typeof payload !== "string";
-    let path: string | undefined;
+    const pinned = await pinContext(payload);
     try {
-      path = await this.writeContextFile(payload, 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;
+      return await this.loadContextPinned(pinned);
     } finally {
-      if (path) await unlink(path).catch(() => {});
+      await pinned.release();
     }
   }
 
-  private async writeContextFile(payload: unknown, isJson: boolean): Promise<string> {
-    const file = join(
-      tmpdir(),
-      `rlm-ctx-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.${isJson ? "json" : "txt"}`,
-    );
-    try {
-      await writeFile(file, isJson ? JSON.stringify(payload) : (payload as string));
-    } catch (e) {
-      await unlink(file).catch(() => {});
-      throw e;
-    }
-    return file;
+  /**
+   * Load from a pin the CALLER owns and will release. Keeping ownership outside means a run and
+   * every child that inherits its payload share one serialization and one file.
+   */
+  async loadContextPinned(pinned: PinnedContext): Promise<number> {
+    const res = await this.request({ type: "load_context", path: pinned.path, json: pinned.json });
+    if (!res.ok) throw new Error(res.error ?? "load_context failed");
+    return res.index ?? 0;
   }
 
   async exec(code: string, signal?: AbortSignal): Promise<ReplResult> {
@@ -268,38 +223,22 @@ export class PythonSandbox {
   async dispose(): Promise<void> {
     if (this.disposed) return;
     this.disposed = true;
-    try {
+    // Handshake only a live worker. The watchdog SIGKILLs before SandboxManager's catch calls
+    // dispose(), and writing the shutdown frame to a process that is already dead is exactly
+    // what produced the EPIPE that killed the host. Skipping it also drops a pointless 50ms
+    // wait from every dead-worker teardown.
+    if (this.workerAlive) {
       this.send({ id: "_shutdown", type: "shutdown" });
-    } catch {
-      /* pipe may already be gone */
+      // Wait for the worker to actually go rather than sleeping a fixed 50ms: this returns the
+      // instant it exits (the common case) and still gives up promptly if it never will, in
+      // which case the SIGKILL below finishes the job.
+      await once(this.proc, "exit", { signal: AbortSignal.timeout(SHUTDOWN_GRACE_MS) })
+        .catch(() => { /* did not exit in time — SIGKILL below */ });
     }
-    await new Promise((r) => setTimeout(r, 50));
     if (this.proc.exitCode === null) this.proc.kill("SIGKILL");
     this.failAll(new Error("sandbox disposed"));
   }
 
-  /** Pickle the worker's user namespace atomically to path (rename .tmp \u2192 final inside worker). */
-  async snapshot(path: string, nonce: string): Promise<boolean> {
-    try {
-      const res = await this.request({ type: "snapshot", path, nonce });
-      if (!res.ok) return false;
-      return res.ok;
-    } catch {
-      return false;
-    }
-  }
-
-  /** Restore user variables. Worker verifies session nonce before deserializing. */
-  async restore(path: string, nonce: string): Promise<boolean> {
-    try {
-      const res = await this.request({ type: "restore", path, nonce });
-      if (!res.ok) return false;
-      return res.ok;
-    } catch {
-      return false;
-    }
-  }
-
   // ---- internals ------------------------------------------------------------------------
 
   private waitForInit(): Promise<void> {
@@ -320,6 +259,13 @@ export class PythonSandbox {
   private request(payload: RequestBody, signal?: AbortSignal): Promise<WorkerResponse> {
     if (this.disposed) return Promise.reject(new Error("sandbox disposed"));
     if (signal?.aborted) return Promise.reject(new Error("repl execution aborted"));
+    // Reject before registering the pending entry: `send` no-ops for a dead worker, so a request
+    // queued here would otherwise sit until the watchdog fired instead of failing now.
+    if (!this.workerAlive) {
+      return Promise.reject(new Error(
+        `worker is not running (${this.exitDescription()}); request '${payload.type}' not sent`,
+      ));
+    }
     const id = `r${++this.seq}`;
     return new Promise<WorkerResponse>((resolve, reject) => {
       const timer = this.createWatchdog(id, payload.type, reject);
@@ -375,9 +321,47 @@ export class PythonSandbox {
         rid: "rid" in msg ? msg.rid : undefined,
       });
     }
+    // Never write to a corpse. The write would fail asynchronously and, historically, take the
+    // host process with it; even with the stdin 'error' listener in place there is nothing to
+    // gain. MUST NOT throw — `reply()` calls this from serviceInterrupt's catch, where a throw
+    // would become an unhandled rejection, trading one crash for another.
+    if (!this.workerAlive) {
+      this.appendStderr(`[rlm] dropped '${msg.type}' frame: worker ${this.exitDescription()}\n`);
+      return;
+    }
     this.proc.stdin.write(`${JSON.stringify(msg)}\n`);
   }
 
+  /**
+   * Listener counts on the worker's stdio pipes. Exposed for tests.
+   *
+   * The `'error'` listener on each is load-bearing: an EventEmitter `'error'` with no listener is
+   * an uncaughtException, so a failed write to a dead worker's stdin kills the HOST process. That
+   * cannot be behaviour-tested reliably — whether the write reaches the syscall depends on
+   * whether node has reaped the child yet — so the invariant is asserted structurally.
+   */
+  get pipeErrorListenerCounts(): Readonly<Record<"stdin" | "stdout" | "stderr", number>> {
+    return Object.freeze({
+      stdin: this.proc.stdin.listenerCount("error"),
+      stdout: this.proc.stdout.listenerCount("error"),
+      stderr: this.proc.stderr.listenerCount("error"),
+    });
+  }
+
+  /** False once the worker is gone — exited, signalled, or its stdin torn down. */
+  private get workerAlive(): boolean {
+    return this.proc.exitCode === null
+      && this.proc.signalCode === null
+      && this.proc.stdin.writable;
+  }
+
+  /** How the worker went away, for diagnostics. */
+  private exitDescription(): string {
+    if (this.proc.signalCode !== null) return `killed by ${this.proc.signalCode}`;
+    if (this.proc.exitCode !== null) return `exited with code ${this.proc.exitCode}`;
+    return "stdin closed";
+  }
+
   private onData(chunk: string): void {
     this.buf += chunk;
     let nl: number;
@@ -419,7 +403,7 @@ export class PythonSandbox {
     }
     if (isInterrupt(msg)) {
       this.touchPending();
-      void this.serviceInterrupt(msg);
+      void serviceInterrupt(msg, this.handlers, (rid, body) => this.reply(rid, body));
       return;
     }
     const p = this.pending.get(msg.id);
@@ -429,85 +413,7 @@ export class PythonSandbox {
     p.resolve(msg);
   }
 
-  private async serviceInterrupt(msg: WorkerInterrupt): Promise<void> {
-    const h = this.handlers;
-    const d = msg.depth;
-    const opts: SubcallOpts = { detached: msg.detached === true };
-    try {
-      if (msg.type === "llm_query") {
-        const response = await h.llmQuery(msg.prompt ?? "", msg.model ?? null, d, opts);
-        this.reply(msg.rid, { response });
-      } else if (msg.type === "rlm_query") {
-        const response = await h.rlmQuery(msg.prompt ?? "", msg.model ?? null, d, opts);
-        this.reply(msg.rid, { response });
-      } else if (msg.type === "llm_query_batched") {
-        const responses = await h.llmQueryBatched(msg.prompts ?? [], msg.model ?? null, d, opts);
-        this.reply(msg.rid, { responses });
-      } else if (msg.type === "rlm_query_batched") {
-        const responses = await h.rlmQueryBatched(msg.prompts ?? [], msg.model ?? null, d, opts);
-        this.reply(msg.rid, { responses });
-      } else if (msg.type === "advance_phase") {
-        const response = await h.advancePhase(msg.phase ?? "", msg.summary, d);
-        this.reply(msg.rid, { response });
-      } else if (msg.type === "save_artifact") {
-        const response = await h.saveArtifact(msg.artifactKind ?? "", msg.content ?? "", d);
-        this.reply(msg.rid, { response });
-      } else if (msg.type === "ask_user_question") {
-        const answers = await h.askUserQuestion(msg.questions ?? [], d);
-        this.reply(msg.rid, { answers });
-      } else if (msg.type === "todo") {
-        const params = Object.fromEntries(
-          Object.entries(msg).filter(([key]) => !TODO_PROTO_KEYS.has(key)),
-        );
-        const response = await h.todo(msg.action ?? "list", params, d);
-        this.reply(msg.rid, { response });
-      } else if (msg.type === "load_library") {
-        const lib = await h.loadLibrary(msg.source ?? "", d);
-        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: errorMessage(err) });
-    }
-  }
-
-  private reply(rid: string, body: {
-    response?: string;
-    responses?: string[];
-    answers?: AskAnswer[];
-    path?: string;
-    json?: boolean;
-    index?: number;
-    files?: number;
-    chars?: number;
-    source_id?: string;
-    path_prefix?: string;
-    already_loaded?: boolean;
-    error?: string;
-  }): void {
+  private reply(rid: string, body: ReplyBody): void {
     if (!this.disposed) this.send({ type: "llm_reply", rid, ...body });
   }
 

package/src/text/tokens.ts

@@ -21,11 +21,37 @@ export function estimateMessageTokens(messages: { content: string }[]): number {
   return estimateTokens(chars);
 }
 
-/** Total character length of a context payload (string or list of strings). */
+/**
+ * Character length of one context entry. `ContextFile`-shaped entries report their content
+ * length; anything else falls back to its serialized form.
+ *
+ * Deliberately does NOT import `isContextFile` from context/library-context.ts: that module
+ * imports `estimateTokens` from here, so the reverse import would be a cycle. `in`-narrowing
+ * needs no type guard and no cast.
+ */
+function entryLength(entry: unknown): number {
+  if (typeof entry === "string") return entry.length;
+  if (entry !== null && typeof entry === "object" && "content" in entry) {
+    const content: unknown = entry.content;
+    if (typeof content === "string") return content.length;
+  }
+  return JSON.stringify(entry ?? "").length;
+}
+
+/**
+ * Total character length of a context payload (string, file bundle, or arbitrary value).
+ *
+ * The array branch must read each entry's `content`: `String(fileEntry)` yields
+ * "[object Object]" (15 chars), which under-reported a packed repository by ~200x. This number
+ * is what buildMetadataLine tells the model to size its batches against, and it is replayed
+ * into the system prompt, so it has to be real.
+ */
 export function contextLength(context: unknown): number {
   if (typeof context === "string") return context.length;
-  if (Array.isArray(context)) return context.reduce<number>((n, x) => n + String(x).length, 0);
-  return JSON.stringify(context ?? "").length;
+  if (!Array.isArray(context)) return JSON.stringify(context ?? "").length;
+  let total = 0; // running sum — no intermediate array, no per-entry closure
+  for (let i = 0; i < context.length; i++) total += entryLength(context[i]);
+  return total;
 }
 
 /** Human label for a context payload's type, used in the metadata prompt. */

package/src/tool/repl-details.ts

@@ -2,7 +2,7 @@
  * ReplDetails — structured payload for the repl() tool's AgentToolResult<T>.
  *
  * Mirrors RlmDetails but scoped to a single code execution. Sub-calls (llm_query,
- * rlm_query, todo, ask_user_question) triggered during sandbox execution are
+ * rlm_query, load_library) triggered during sandbox execution are
  * accumulated into the subcalls array for tree rendering.
  */
 
@@ -16,7 +16,7 @@ export interface ReplDetails {
   readonly stderr: string;
   /** Wall-clock execution time in milliseconds. */
   readonly executionTimeMs: number;
-  /** Sub-calls triggered during this execution (llm_query, rlm_query, todo, etc.). */
+  /** Sub-calls triggered during this execution (llm_query, rlm_query, etc.). */
   readonly subcalls: readonly RlmSubcall[];
   /** Running totals for this repl() call (cost + tokens from sub-LLM calls). */
   readonly totals: { readonly costUsd: number; readonly tokens: number };

package/src/tool/repl-render.ts

@@ -0,0 +1,58 @@
+/** repl() tool TUI views — collapsed one-liner card and the expanded output/sub-call tree. */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import type { ReplDetails } from "./repl-details.ts";
+import { cardHeader, cardStatsLine, renderCollapsedCard, renderExpandedSubcallTree } from "./subcall-render.ts";
+
+/** Chars of stdout/stderr shown in the expanded view. */
+const EXPANDED_STDOUT_CHARS = 2_000;
+const EXPANDED_STDERR_CHARS = 500;
+
+// ── Collapsed view ──
+
+export function replStats(details: ReplDetails, theme: Theme): string {
+  const elapsed = details.executionTimeMs > 0 ? `${details.executionTimeMs}ms` : undefined;
+  return cardStatsLine(details.totals, theme, elapsed, details.backgroundPending);
+}
+
+export function renderReplCollapsed(details: ReplDetails, theme: Theme): Text {
+  return renderCollapsedCard("REPL", details.status, replStats(details, theme), details.subcalls, theme);
+}
+
+// ── Expanded view ──
+
+export function renderReplExpanded(details: ReplDetails, theme: Theme): Container {
+  const container = new Container();
+
+  container.addChild(new Text(cardHeader("REPL", details.status, replStats(details, theme), theme), 0, 0));
+
+  // Output
+  if (details.output) {
+    container.addChild(new Spacer(1));
+    const out = details.output.length > EXPANDED_STDOUT_CHARS
+      ? `${details.output.slice(0, EXPANDED_STDOUT_CHARS)}…`
+      : details.output;
+    container.addChild(new Text(out, 0, 0));
+  }
+
+  if (details.warnings && details.warnings.length > 0) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("muted", details.warnings.join("\n")), 0, 0));
+  }
+
+  // Stderr
+  if (details.stderr) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("error", details.stderr.slice(0, EXPANDED_STDERR_CHARS)), 0, 0));
+  }
+
+  // Sub-call tree
+  if (details.subcalls.length > 0) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("muted", "─── Sub-calls ───"), 0, 0));
+    container.addChild(renderExpandedSubcallTree(details.subcalls, theme));
+  }
+
+  return container;
+}

package/src/tool/repl-result.ts

@@ -0,0 +1,70 @@
+/**
+ * Model-visible text assembly for a repl() result, plus the advisory diagnostics derived from
+ * its sub-calls. Split out of repl-tool.ts: this is pure string/array work with no sandbox,
+ * emitter, or TUI dependency, and both halves are asserted directly by test/phase-guards.ts.
+ */
+
+import type { RlmSubcall } from "./rlm-details.ts";
+import { capReplResultText, replDelegationNudge } from "../mode/native-guards.ts";
+
+/** Model-visible text assembled from a repl() result. */
+export interface ReplResultText {
+  readonly text: string;
+}
+
+/**
+ * Assemble the model-visible text for a repl() result: cap stdout, append a zero-subcall
+ * delegation nudge when a bulk read went undelegated, and report tasks still running.
+ *
+ * The pending line is the model's only signal that `spawn()`ed work is outstanding — without
+ * it a model that spawned and moved on has no way to know it should still collect.
+ *
+ * `varNames` covers the opposite failure: a block that stores its results in `answers` and
+ * prints nothing reads as a bare "(no output)", so the model concludes the block did nothing
+ * and re-runs it — paying twice for the same sub-calls. The headless engine already answers
+ * this with the same hint (core/answer.ts); native mode was the only path missing it.
+ */
+export function buildReplResultText(
+  stdout: string,
+  finalAnswer: string | undefined,
+  subcalls: readonly RlmSubcall[],
+  backgroundPending = 0,
+  varNames: readonly string[] = [],
+): ReplResultText {
+  const answerSubmitted = finalAnswer !== undefined;
+  const noOutput = !answerSubmitted && !stdout;
+  const varsHint = noOutput && varNames.length > 0
+    ? ` — the block ran fine and these REPL vars are defined: ${varNames.join(", ")}. `
+      + "Do NOT re-run it; read them in the next block."
+    : "";
+  const rawText = answerSubmitted
+    ? `ANSWER_SUBMITTED (${finalAnswer.length} chars) — delivered to user. Do not restate it.`
+    : stdout || `(no output)${varsHint}`;
+  // Model-visible text is capped; the caller keeps full stdout in `details` for the TUI.
+  const cappedText = capReplResultText(rawText) ?? rawText;
+  const delegated = subcalls.some((s) => s.kind === "llm" || s.kind === "batch" || s.kind === "rlm");
+  const nudge = answerSubmitted ? undefined : replDelegationNudge(rawText.length, delegated);
+  const failedBg = subcalls.filter((s) => s.id.startsWith("bg") && s.status === "error").length;
+  const pendingLine = backgroundPending > 0
+    ? `\n\n[rlm] ${backgroundPending} background task(s) still running — rlm_await_all(tasks) to collect.`
+    : "";
+  const failedLine = failedBg > 0
+    ? `\n[rlm] ${failedBg} background sub-call(s) FAILED — their rlm_await value is an "Error: …" string, not data.`
+    : "";
+  return { text: cappedText + (nudge ?? "") + pendingLine + failedLine };
+}
+
+/** Advisory diagnostics derived from a completed invocation's sub-calls. */
+export function collectReplWarnings(subcalls: readonly RlmSubcall[]): readonly string[] | undefined {
+  let failed = 0;
+  let total = 0;
+  for (let i = 0; i < subcalls.length; i++) {
+    const call = subcalls[i];
+    if (call.status !== "error") continue;
+    // A batch subcall stands for many prompts; a single call stands for one.
+    failed += call.failedCount ?? 1;
+    total += call.totalCount ?? 1;
+  }
+  if (failed === 0) return undefined;
+  return Object.freeze([`${failed}/${total} sub-call(s) failed — results may be incomplete`]);
+}