@hicaru/pi-rlm 0.1.9 → 0.2.1

package/src/tool/repl-tool.ts

@@ -6,9 +6,13 @@
  * and collects sub-calls manually from emitter events. No RlmEventAggregator is used
  * (ReplDetails ≠ RlmDetails structural mismatch).
  *
- * Sandbox handlers (llm_query, rlm_query, todo, ask_user_question) use mutable refs
- * so the tool can swap per-invocation state (emitter, depth, limits) without recreating
- * the sandbox — preserving REPL variable state across calls.
+ * Sub-call handling itself lives in bridge/subcall-handlers.ts; this file only supplies the
+ * per-invocation Invocation those handlers resolve against, swapping it inside the
+ * serialized exec slot so a queued repl() cannot claim the running one's emitter.
+ *
+ * Work started with `spawn()` may still be running when the call returns, so it resolves to
+ * the session-scoped BackgroundTasks registry instead and is drained back into whichever
+ * turn is reporting next.
  */
 
 import { Type } from "typebox";
@@ -16,33 +20,39 @@ import type { Theme, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Container, Spacer, Text } from "@earendil-works/pi-tui";
 import type { Model, Usage, Api } from "@earendil-works/pi-ai";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
-import { modelRef, resolveModelId } from "../config/settings.ts";
 import { buildInteractiveHandlers } from "../bridge/interactive.ts";
 import { buildLibraryHandler } from "../bridge/library.ts";
 import { createPiInteractiveDeps } from "../bridge/pi-interactive.ts";
-import { type ChatMsg, modelComplete } from "../bridge/model.ts";
-import { previewText } from "../text/preview.ts";
-import { mapPool } from "../util/concurrency.ts";
-import { LimitGuard } from "../core/limits.ts";
-import { checkResourceLimits } from "../core/resource-limits.ts";
-import type { InteractiveDeps, RlmConfig, Sampling } from "../core/types.ts";
+import type { SubcallGates } from "../util/concurrency.ts";
+import { LimitGuard, limitsFromConfig } from "../core/limits.ts";
+import type { InteractiveDeps, RlmConfig, RlmInput, RlmResult } from "../core/types.ts";
 import { SandboxManager } from "../sandbox/sandbox-manager.ts";
-import type { SubLlmHandlers } from "../sandbox/sandbox.ts";
+import type { SubcallOpts } from "../sandbox/sandbox.ts";
+import { createSubcallHandlers, type Invocation } from "../bridge/subcall-handlers.ts";
+import { BackgroundTasks } from "./background-tasks.ts";
 import type { ReplResult } from "../sandbox/protocol.ts";
 import { RlmEmitter } from "./rlm-events.ts";
 import { SubcallStore } from "./subcall-store.ts";
 import type { ReplDetails } from "./repl-details.ts";
 import type { RlmSubcall } from "./rlm-details.ts";
 import { createEngine } from "../core/engine.ts";
-import { formatCost, formatTokens, spinnerFrame } from "../ui/theme.ts";
-import { errorMessage, formatError, isErrorText } from "../util/errors.ts";
+import { spinnerFrame } from "../ui/theme.ts";
+import { previewText } from "../text/preview.ts";
+import { errorMessage } from "../util/errors.ts";
 import {
-  headlineStatusGlyph,
-  renderCollapsedSubcallTree,
+  cardHeader,
+  cardStatsLine,
+  renderCollapsedCard,
   renderExpandedSubcallTree,
 } from "./subcall-render.ts";
 import { createProgressNotifier, validateToolParams } from "./tool-utils.ts";
 import { capReplResultText, replDelegationNudge } from "../mode/native-guards.ts";
+import { attachTracer, trace, traceEnabled } from "../util/trace.ts";
+
+/** Chars of code shown on the tool call line, and of stdout in the expanded view. */
+const CALL_PREVIEW_CHARS = 80;
+const EXPANDED_STDOUT_CHARS = 2_000;
+const EXPANDED_STDERR_CHARS = 500;
 
 // ── Parameter schema ──
 
@@ -50,29 +60,61 @@ export const ReplToolParams = Object.freeze(Type.Object({
   code: Type.String({ description: "Python code to execute in the persistent REPL sandbox" }),
 }));
 
+/** Last non-empty line of a Python traceback — the `TypeError: …` line, not the frames. */
+function lastLine(text: string): string {
+  const lines = text.trimEnd().split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]?.trim();
+    if (line) return line.slice(0, 200);
+  }
+  return "";
+}
+
 /** 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 and append a
- * zero-subcall delegation nudge when a bulk read went undelegated.
+ * 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)";
+    : 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);
-  return { text: cappedText + (nudge ?? "") };
+  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. */
@@ -93,226 +135,41 @@ export function collectReplWarnings(subcalls: readonly RlmSubcall[]): readonly s
 // ── Mutable bridge state (handler indirection) ──
 
 /**
- * Holds per-invocation mutable state that sandbox handlers dereference.
- * The sandbox is created once with handlers that read from this object's
- * current fields, so the tool can swap emitter/depth/limits between calls
- * without recreating the sandbox (preserving REPL variable state).
+ * Holds per-invocation state that the sandbox handlers resolve against.
+ *
+ * The sandbox is created once, so the tool swaps the current Invocation between repl()
+ * calls rather than rebuilding handlers (which would lose REPL variable state). Handlers
+ * capture the Invocation synchronously at interrupt entry and never re-read it — with
+ * spawn() a sub-call can outlive its exec, and a later read would attribute it to whichever
+ * turn happened to be current when it resumed.
+ *
+ * Detached work resolves to the session-scoped background Invocation instead, whose emitter
+ * and LimitGuard are not torn down at the end of a turn.
  */
 class NativeBridgeState {
-  currentEmitter: RlmEmitter | null = null;
-  currentParentId: string | undefined;
-  currentDepth = 0;
-  currentLimits: LimitGuard | null = null;
-  currentInteractive: InteractiveDeps | null = null;
-
-  swap(inv: { emitter: RlmEmitter; parentId?: string; depth: number; limits: LimitGuard; interactive: InteractiveDeps }): void {
-    this.currentEmitter = inv.emitter;
-    this.currentParentId = inv.parentId;
-    this.currentDepth = inv.depth;
-    this.currentLimits = inv.limits;
-    this.currentInteractive = inv.interactive;
-  }
+  private current: Invocation | null = null;
+  /** Interactive callbacks for the turn in progress; child engines inherit them. */
+  interactive: InteractiveDeps | null = null;
 
-  buildLlmHandlers(deps: {
-    workerModel: Model<Api>;
-    getWorkerModel?: () => Model<Api> | undefined;
-    registry: ModelRegistry;
-    maxPromptChars: number;
-    maxConcurrent: number;
-    sampling?: Sampling;
-    subSystem?: string;
-    signal?: AbortSignal;
-  }): Pick<SubLlmHandlers, "llmQuery" | "llmQueryBatched"> {
-    const state = this;
-
-    const workerModel = (): Model<Api> => deps.getWorkerModel?.() ?? deps.workerModel;
-    const displayModel = (model: string | null): string =>
-      modelRef(model ? (resolveModelId(deps.registry, model) ?? workerModel()) : workerModel()) ?? workerModel().id;
-
-    async function complete1(prompt: string, model: string | null, track: (u: Usage) => void): Promise<string> {
-      const limits = state.currentLimits;
-      if (limits) {
-        const limitError = checkResourceLimits({ budgetUsd: limits.remainingBudgetUsd(), timeoutMs: limits.remainingTimeoutMs() });
-        if (limitError !== undefined) return limitError;
-      }
-      if (prompt.length > deps.maxPromptChars) {
-        return formatError(`sub-LLM prompt exceeded size limit (${prompt.length.toLocaleString()} chars > ${deps.maxPromptChars.toLocaleString()})`);
-      }
-      const resolved = model ? resolveModelId(deps.registry, model) : undefined;
-      if (model && !resolved) return formatError(`unknown model override '${model}'`);
-      try {
-        const messages: ChatMsg[] = [{ role: "user", content: prompt }];
-        const res = await modelComplete(messages, {
-          model: resolved ?? workerModel(),
-          registry: deps.registry,
-          system: deps.subSystem,
-          maxTokens: deps.sampling?.maxTokens,
-          temperature: deps.sampling?.temperature,
-          reasoning: deps.sampling?.reasoning,
-          signal: deps.signal,
-        });
-        limits?.addUsage(res.usage);
-        track(res.usage);
-        return res.text;
-      } catch (err) {
-        const msg = errorMessage(err);
-        const hint = /credit|402|payment|quota|rate.limit/i.test(msg)
-          ? " — try smaller batches or individual llm_query calls"
-          : "";
-        return formatError(`${msg}${hint}`);
-      }
-    }
-
-    return {
-      async llmQuery(prompt, model, _depth) {
-        const id = state.currentEmitter?.emitSubcallCreated({
-          kind: "llm", parentId: state.currentParentId, label: "llm_query",
-          model: displayModel(model), args: `prompt: ${previewText(prompt)}`,
-          depth: state.currentDepth,
-        });
-        let cost = 0; let tokens = 0;
-        const out = await complete1(prompt, model, (u) => { cost += u.cost.total; tokens += u.totalTokens; });
-        if (id) state.currentEmitter?.emitSubcallUpdated({ id,
-          status: isErrorText(out) ? "error" : "done",
-          costUsd: cost, tokens, resultPreview: previewText(out),
-          detail: isErrorText(out) ? out : undefined,
-        });
-        return out;
-      },
-
-      async llmQueryBatched(prompts: readonly string[], model, _depth): Promise<string[]> {
-        const id = state.currentEmitter?.emitSubcallCreated({
-          kind: "batch", parentId: state.currentParentId, label: `llm_query ×${prompts.length}`,
-          model: displayModel(model), args: `prompt: ${previewText(prompts[0] ?? "")}`,
-          depth: state.currentDepth,
-        });
-        let cost = 0; let tokens = 0;
-        const out: string[] = await mapPool(prompts, deps.maxConcurrent, (p) =>
-          complete1(p, model, (u) => { cost += u.cost.total; tokens += u.totalTokens; }),
-        );
-        const failed = out.filter(isErrorText).length;
-        const allFailed = failed === out.length;
-        const error = allFailed
-          ? `all ${out.length} sub-calls failed — reduce batch size or try llm_query individually`
-          : failed > 0 ? `${failed}/${out.length} sub-calls failed` : undefined;
-        if (id) state.currentEmitter?.emitSubcallUpdated({ id,
-          status: error ? "error" : "done", costUsd: cost, tokens,
-          resultPreview: previewText(out[0] ?? ""), detail: error,
-          failedCount: failed, totalCount: out.length,
-        });
-        return out;
-      },
-    };
-  }
+  constructor(private readonly background: BackgroundTasks) {}
 
-  /**
-   * Build real recursive rlm_query / rlm_query_batched handlers that spawn
-   * child RLM engines (each with its own sandbox and turn loop) rather than
-   * falling back to a one-shot llm_query.
-   *
-   * At the maxDepth cap the handler degrades to a plain llm_query via the
-   * already-wired llmHandlers (which read from the same mutable state).
-   */
-  buildRlmHandlers(deps: {
-    model: Model<Api>;
-    workerModel: Model<Api>;
-    getModel?: () => Model<Api> | undefined;
-    getWorkerModel?: () => Model<Api> | undefined;
-    registry: ModelRegistry;
-    config: RlmConfig;
-    signal?: AbortSignal;
-    onUsage?: (usage: Usage, role: "sub") => void;
-    llmHandlers: Pick<SubLlmHandlers, "llmQuery" | "llmQueryBatched">;
-  }): Pick<SubLlmHandlers, "rlmQuery" | "rlmQueryBatched"> {
-    const state = this;
-
-    async function rlmQueryImpl(prompt: string, model: string | null, depth: number): Promise<string> {
-      const emitter = state.currentEmitter;
-      const limits = state.currentLimits;
-      if (!emitter || !limits) return formatError("RLM bridge not wired for this invocation");
-
-      const childDepth = state.currentDepth + 1;
-
-      // Depth cap: degrade to a one-shot llm_query.
-      if (childDepth >= deps.config.maxDepth) {
-        return deps.llmHandlers.llmQuery(prompt, model, depth);
-      }
-
-      const remBudget = limits.remainingBudgetUsd();
-      const remTimeout = limits.remainingTimeoutMs();
-      const limitError = checkResourceLimits({ budgetUsd: remBudget, timeoutMs: remTimeout });
-      if (limitError) return limitError;
-
-      const rootModel = deps.getModel?.() ?? deps.model;
-      const workerModel = deps.getWorkerModel?.() ?? deps.workerModel;
-      const resolvedOverride = model ? resolveModelId(deps.registry, model) : undefined;
-      const subId = emitter.emitSubcallCreated({
-        kind: "rlm", parentId: state.currentParentId, label: "rlm_query",
-        model: model ? (modelRef(resolvedOverride) ?? `unknown/${model}`) : (modelRef(rootModel) ?? rootModel.id),
-        detail: prompt.slice(0, 60),
-        depth: childDepth,
-      });
-
-      // Per-call engine creation with the visible emitter — child llm_query subcalls,
-      // turn progress, and cost deltas land on the per-invocation emitter, visible to
-      // SubcallStore and the live visual tree.
-      const runRlm = createEngine({
-        model: rootModel,
-        workerModel,
-        registry: deps.registry,
-        config: deps.config,
-        signal: deps.signal,
-        emitter: emitter,
-        onUsage: deps.onUsage as ((usage: Usage, role: "root" | "sub") => void) | undefined,
-        limits: {
-          maxBudgetUsd: deps.config.maxBudgetUsd,
-          maxTimeoutMs: deps.config.maxTimeoutMs,
-          maxTokens: deps.config.maxTokens,
-          maxErrors: deps.config.maxErrors,
-        },
-        onTodo: state.currentInteractive?.onTodo,
-        onAskUserQuestion: state.currentInteractive?.onAskUserQuestion,
-      });
-
-      try {
-        const res = await runRlm({
-          rootPrompt: "",
-          context: prompt,
-          depth: childDepth,
-          parentNodeId: subId,
-          modelOverride: model ?? undefined,
-          remainingBudgetUsd: remBudget,
-          remainingTimeoutMs: remTimeout,
-        });
-
-        // Debit parent limit guard for the entire child run.
-        limits.addRaw(res.costUsd, res.inputTokens, res.outputTokens);
-
-        // Child engine emits live usage deltas via the shared emitter — SubcallStore
-        // accumulates them. No final aggregate costUsd/tokens to prevent double-counting
-        // (matches canonical rlm-query.ts:60-63).
-        emitter.emitSubcallUpdated({
-          id: subId,
-          status: "done",
-          resultPreview: res.answer.slice(0, 200),
-        });
+  swap(inv: Invocation, interactive: InteractiveDeps): void {
+    this.current = Object.freeze({ ...inv });
+    this.interactive = interactive;
+  }
 
-        return res.answer;
-      } catch (err) {
-        const msg = errorMessage(err);
-        emitter.emitSubcallUpdated({ id: subId, status: "error", detail: msg });
-        return formatError(`child RLM failed - ${msg}`);
-      }
-    }
+  /** Detached ⇒ session registry; otherwise the turn that is currently executing. */
+  resolve(opts: SubcallOpts): Invocation | null {
+    return opts.detached ? this.background.invocation : this.current;
+  }
 
-    return {
-      rlmQuery: rlmQueryImpl,
-      rlmQueryBatched: (prompts, model, depth) =>
-        mapPool(prompts, deps.config.maxConcurrentSubcalls, (p) => rlmQueryImpl(p, model, depth)),
-    };
+  /** The turn emitter, for library-load reporting. Null between repl() calls. */
+  get currentEmitter(): RlmEmitter | null {
+    return this.current?.emitter ?? null;
   }
 }
 
+
 // ── Tool factory ──
 
 export interface ReplToolDeps {
@@ -322,7 +179,12 @@ export interface ReplToolDeps {
   readonly getModel?: () => Model<Api> | undefined;
   readonly getWorkerModel?: () => Model<Api> | undefined;
   readonly registry: ModelRegistry;
-  readonly config: RlmConfig;
+  /** Live accessor — `/rlm-config` replaces the config object, so never capture the value. */
+  readonly getConfig: () => RlmConfig;
+  /** Session-wide sub-call admission, shared with every child engine this tool spawns. */
+  readonly gates: SubcallGates;
+  /** Session-scoped home for detached spawn() work. */
+  readonly background: BackgroundTasks;
   readonly signal?: AbortSignal;
   readonly onUsage?: (usage: Usage, role: "sub") => void;
   readonly ensureContext?: () => Promise<void>;
@@ -331,40 +193,51 @@ export interface ReplToolDeps {
 }
 
 export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplToolParams, ReplDetails> {
-  const { sandboxManager, workerModel, registry, config, signal, onUsage } = deps;
-  const bridgeState = new NativeBridgeState();
+  const { sandboxManager, workerModel, registry, getConfig, signal, onUsage, background } = deps;
+  const bridgeState = new NativeBridgeState(background);
 
   // Late-bound cwd — getOrCreate installs handlers only at spawn; never rebuild the closure.
   let sessionCwd = process.cwd();
 
-  // Build handlers once — llm/rlm/library use late-bound deps so the same closures stay correct
-  // across repl() calls; counter resets when the sandbox is discarded and re-spawned.
-  const llmHandlers = bridgeState.buildLlmHandlers({
-    workerModel,
-    getWorkerModel: deps.getWorkerModel,
+  const getWorkerModel = (): Model<Api> => deps.getWorkerModel?.() ?? workerModel;
+  const getModel = (): Model<Api> => deps.getModel?.() ?? deps.model;
+
+  // Each rlm_query spawns a child RLM with its own sandbox and turn loop, not a flat
+  // one-shot llm_query. The engine is created per call so the child's subcalls, turn
+  // progress and cost deltas land on the emitter the parent invocation is using.
+  const runChild = (input: RlmInput, inv: Invocation): Promise<RlmResult> => createEngine({
+    model: getModel(),
+    workerModel: getWorkerModel(),
     registry,
-    maxPromptChars: config.maxPromptChars,
-    maxConcurrent: config.maxConcurrentSubcalls,
-    sampling: config.subSampling,
-    subSystem: config.subSystemPrompt,
+    config: getConfig(),
     signal,
-  });
-
-  // Real recursive rlm_query via createEngine — each call spawns a child RLM
-  // with its own sandbox and turn loop, not a flat one-shot llm_query.
-  const rlmHandlers = bridgeState.buildRlmHandlers({
-    model: deps.model,
-    workerModel,
-    getModel: deps.getModel,
-    getWorkerModel: deps.getWorkerModel,
+    gates: deps.gates,
+    // Same emitter the parent subcall node lives on — see SubcallHandlerDeps.runChild.
+    emitter: inv.emitter,
+    // Everything a child engine spends is sub-work from this tool's perspective, including
+    // the child's own root turns — so fold both roles into "sub" rather than casting.
+    onUsage: onUsage === undefined ? undefined : (usage: Usage) => onUsage(usage, "sub"),
+    limits: limitsFromConfig(getConfig()),
+    onTodo: bridgeState.interactive?.onTodo,
+    onAskUserQuestion: bridgeState.interactive?.onAskUserQuestion,
+  })(input);
+
+  // Built once: the same closures stay correct across repl() calls because everything
+  // per-invocation is reached through bridgeState.resolve, not captured here.
+  const subcallHandlers = createSubcallHandlers({
+    resolve: (opts) => bridgeState.resolve(opts),
+    gates: deps.gates,
     registry,
-    config,
+    getWorkerModel,
+    getModel,
+    getConfig,
     signal,
     onUsage,
-    llmHandlers,
+    runChild,
+    trackDetached: (task) => background.track(task),
   });
 
-  const libraryBundle = config.libraryLoader
+  const libraryBundle = getConfig().libraryLoader
     ? buildLibraryHandler({
         getCwd: () => sessionCwd,
         getEmitter: () => bridgeState.currentEmitter,
@@ -380,14 +253,22 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
     label: "REPL",
     description:
       "PRIMARY tool for ALL repository reading and analysis (read/grep are disabled in RLM mode). " +
-      "Persistent Python sandbox with every file pre-loaded in `context`. You are an orchestrator: " +
-      "chunk `context` and delegate semantic work to llm_query / llm_query_batched / " +
-      "llm_query_chunked / rlm_query — stdout returned to you is hard-capped at 4K chars, so " +
-      "printing file bodies is useless. Variables, imports, and state persist across calls. " +
-      "Also supports todo, ask_user_question, and load_library inside the sandbox.",
+      "Persistent Python sandbox with every file pre-loaded in `context`. Locate first with the " +
+      "free primitives search(query) / grep_context(pattern) / outline(path), then delegate the " +
+      "semantic reading to map_files / llm_query / llm_query_batched / llm_query_chunked " +
+      "(rlm_query for iterative sub-tasks) — stdout returned to you is hard-capped at 4K chars, " +
+      "so printing file bodies is useless. Variables, imports, and the `answers`/`plan` memo " +
+      "persist across calls. Also supports todo, ask_user_question, and load_library.",
+    promptSnippet:
+      "repl: run Python in a persistent sandbox holding the whole repository in `context`; " +
+      "search/grep_context/outline to locate, map_files/llm_query* to read.",
+    promptGuidelines: [
+      "In RLM mode, read the repository through `repl` only — `read`/`grep` and bash readers are blocked.",
+      "Inside `repl`, locate with search()/grep_context()/outline() before delegating bulk reading to map_files()/llm_query_batched().",
+    ],
     parameters: ReplToolParams,
 
-    async execute(_toolCallId, rawParams, _execSignal, onUpdate, ctx) {
+    async execute(_toolCallId, rawParams, execSignal, onUpdate, ctx) {
       const validation = validateToolParams(ReplToolParams, rawParams, "REPL", (errors): ReplDetails => ({
         status: "error",
         output: "",
@@ -405,24 +286,31 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
       let capturedStderr = "";
       let progressStatus: ReplDetails["status"] = "running";
       const startedAt = Date.now();
-      const limits = new LimitGuard({
-        maxBudgetUsd: config.maxBudgetUsd,
-        maxTimeoutMs: config.maxTimeoutMs,
-        maxTokens: config.maxTokens,
-        maxErrors: config.maxErrors,
-      });
+      const limits = new LimitGuard(limitsFromConfig(getConfig()));
+
+      const detachTracers = traceEnabled
+        ? [attachTracer(emitter, "turn"), attachTracer(background.emitter, "background")]
+        : [];
 
       // ── Progressive rendering: spinner + live sub-call tree ──
       const progress = createProgressNotifier<ReplDetails>({
         onUpdate,
-        getDetails: () => ({
-          status: progressStatus,
-          output: capturedStdout,
-          stderr: capturedStderr,
-          executionTimeMs: Date.now() - startedAt,
-          subcalls: store.getSubcalls(),
-          totals: store.getTotals(),
-        }),
+        getDetails: () => {
+          // Detached spawn() nodes live on the SESSION emitter, so without this merge the card
+          // stays empty for the entire time background work is running.
+          const live = background.liveSubcalls();
+          const bg = background.liveTotals();
+          const own = store.getTotals();
+          return {
+            status: progressStatus,
+            output: capturedStdout,
+            stderr: capturedStderr,
+            executionTimeMs: Date.now() - startedAt,
+            subcalls: live.length > 0 ? [...store.getSubcalls(), ...live] : store.getSubcalls(),
+            totals: { costUsd: own.costUsd + bg.costUsd, tokens: own.tokens + bg.tokens },
+            backgroundPending: background.pending > 0 ? background.pending : undefined,
+          };
+        },
         isRunning: (details) => details.status === "running",
         renderText: (details) => details.output.slice(0, 500) || (details.status === "running" ? `${spinnerFrame()} Running…` : "(no output)"),
       });
@@ -442,7 +330,7 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
         // Build interactive handlers (session-stable callbacks)
         const interactive = createPiInteractiveDeps(ctx);
         const interactiveHandlers = buildInteractiveHandlers({
-          onAskUserQuestion: config.askUserQuestion ? interactive.onAskUserQuestion : undefined,
+          onAskUserQuestion: getConfig().askUserQuestion ? interactive.onAskUserQuestion : undefined,
           onTodo: interactive.onTodo,
           onTodoRow: undefined,
           emitter,
@@ -454,8 +342,7 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
 
         await deps.ensureContext?.();
         await sandboxManager.getOrCreate({
-          ...llmHandlers,
-          ...rlmHandlers,
+          ...subcallHandlers,
           askUserQuestion: interactiveHandlers.askUserQuestion,
           todo: interactiveHandlers.todo,
           ...(libraryBundle?.handlers ?? {}),
@@ -470,19 +357,46 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
           });
         }
 
+        if (traceEnabled) {
+          trace("repl.exec.start", { chars: params.code.length, code: params.code.slice(0, 400) });
+        }
+
         const start = Date.now();
         const result: ReplResult = await sandboxManager.execWithSetup(params.code, () => {
           // Wire per-invocation mutable state only after the serialized exec slot
           // is active. Swapping earlier would let queued repl() calls overwrite
           // emitter/limits for the currently running REPL execution.
-          bridgeState.swap({ emitter, parentId: undefined, depth: 0, limits, interactive });
-        });
+          bridgeState.swap({ emitter, parentId: undefined, depth: 0, limits }, interactive);
+        }, execSignal);
         const elapsed = Date.now() - start;
         capturedStdout = result.stdout;
         capturedStderr = result.stderr;
         progressStatus = "done";
 
-        const totals = store.getTotals();
+        if (traceEnabled) {
+          trace("repl.exec.end", {
+            ms: elapsed,
+            stdout: result.stdout.length,
+            raised: result.raised,
+            pending: background.pending,
+            // A block that raised delegated nothing; without the exception the trace shows a
+            // silent turn and the reason is only in the TUI card.
+            error: result.raised ? lastLine(result.stderr) : undefined,
+          });
+        }
+
+        // Adopt every background subtree that has settled, whether or not this turn awaited
+        // it — otherwise a spawn the model never collects would never reach the user's cost
+        // totals. IDs are "bg"-prefixed, so they cannot collide with this turn's.
+        // (drain() removes what it hands over, so live view + accounted view never double-count.)
+        const adopted = background.drain();
+        const subcalls: readonly RlmSubcall[] = adopted.subcalls.length > 0
+          ? [...store.getSubcalls(), ...adopted.subcalls]
+          : store.getSubcalls();
+        const totals = {
+          costUsd: store.getTotals().costUsd + adopted.totals.costUsd,
+          tokens: store.getTotals().tokens + adopted.totals.tokens,
+        };
         const subUsage: Usage = {
           input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: totals.tokens,
           cost: { total: totals.costUsd, input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
@@ -495,7 +409,9 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
         const { text: resultText } = buildReplResultText(
           result.stdout,
           finalAnswer,
-          store.getSubcalls(),
+          subcalls,
+          background.pending,
+          result.varNames,
         );
 
         const details: ReplDetails = {
@@ -503,10 +419,11 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
           output: result.stdout,
           stderr: result.stderr,
           executionTimeMs: elapsed,
-          subcalls: store.getSubcalls(),
-          totals: store.getTotals(),
+          subcalls,
+          totals,
           finalAnswer,
-          warnings: collectReplWarnings(store.getSubcalls()),
+          backgroundPending: background.pending > 0 ? background.pending : undefined,
+          warnings: collectReplWarnings(subcalls),
         };
         const progressText = finalAnswer !== undefined
           ? `ANSWER_SUBMITTED (${finalAnswer.length} chars)`
@@ -517,13 +434,20 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
       } catch (e) {
         progressStatus = "error";
         const msg = errorMessage(e);
+        // Drain here too: a failing turn must not swallow the cost of background work that
+        // settled during it, or a run that keeps erroring would never report any of it.
+        const adopted = background.drain();
         const details: ReplDetails = {
           status: "error",
           output: "",
           stderr: msg,
           executionTimeMs: 0,
-          subcalls: store.getSubcalls(),
-          totals: store.getTotals(),
+          subcalls: [...store.getSubcalls(), ...adopted.subcalls],
+          totals: {
+            costUsd: store.getTotals().costUsd + adopted.totals.costUsd,
+            tokens: store.getTotals().tokens + adopted.totals.tokens,
+          },
+          backgroundPending: background.pending > 0 ? background.pending : undefined,
         };
         onUpdate?.({ content: [{ type: "text", text: `REPL error: ${msg}` }], details });
         return {
@@ -532,16 +456,15 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
         };
       } finally {
         progress.stop();
+        for (const off of detachTracers) off();
         store.dispose();
         emitter.shutdown();
       }
     },
 
     renderCall(args, theme) {
-      const preview = args.code.length > 80 ? `${args.code.slice(0, 80)}...` : args.code;
       return new Text(
-        theme.fg("toolTitle", theme.bold("repl ")) +
-        theme.fg("dim", preview.replace(/\n/g, " ")),
+        theme.fg("toolTitle", theme.bold("repl ")) + theme.fg("dim", previewText(args.code, CALL_PREVIEW_CHARS)),
         0, 0,
       );
     },
@@ -560,26 +483,13 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
 
 // ── Collapsed view ──
 
-function renderReplCollapsed(details: ReplDetails, theme: Theme): Text {
-  const glyph = details.status === "running"
-    ? headlineStatusGlyph("running", theme)
-    : details.status === "error" ? theme.fg("error", "✗") : theme.fg("success", "✓");
-
-  const parts: string[] = [];
-  parts.push(formatCost(details.totals.costUsd));
-  if (details.totals.tokens > 0) parts.push(`${formatTokens(details.totals.tokens)} tok`);
-  if (details.executionTimeMs > 0) parts.push(`${details.executionTimeMs}ms`);
-  const stats = parts.length > 0 ? ` ${theme.fg("dim", parts.join(" · "))}` : "";
-
-  const header = `${glyph} ${theme.fg("toolTitle", theme.bold("REPL"))}${stats}`;
-
-  let body = "";
-  if (details.subcalls.length > 0) {
-    body = `\n${renderCollapsedSubcallTree(details.subcalls, theme)}`;
-  }
+function replStats(details: ReplDetails, theme: Theme): string {
+  const elapsed = details.executionTimeMs > 0 ? `${details.executionTimeMs}ms` : undefined;
+  return cardStatsLine(details.totals, theme, elapsed, details.backgroundPending);
+}
 
-  const expandHint = details.status === "running" ? "" : `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
-  return new Text(`${header}${body}${expandHint}`, 0, 0);
+function renderReplCollapsed(details: ReplDetails, theme: Theme): Text {
+  return renderCollapsedCard("REPL", details.status, replStats(details, theme), details.subcalls, theme);
 }
 
 // ── Expanded view ──
@@ -587,19 +497,14 @@ function renderReplCollapsed(details: ReplDetails, theme: Theme): Text {
 function renderReplExpanded(details: ReplDetails, theme: Theme): Container {
   const container = new Container();
 
-  // Header: status + stats
-  const glyph = details.status === "error" ? theme.fg("error", "✗") : theme.fg("success", "✓");
-  const parts: string[] = [];
-  parts.push(formatCost(details.totals.costUsd));
-  if (details.totals.tokens > 0) parts.push(`${formatTokens(details.totals.tokens)} tok`);
-  if (details.executionTimeMs > 0) parts.push(`${details.executionTimeMs}ms`);
-  const stats = parts.length > 0 ? ` · ${theme.fg("dim", parts.join(" · "))}` : "";
-  container.addChild(new Text(`${glyph} ${theme.fg("toolTitle", theme.bold("REPL"))}${stats}`, 0, 0));
+  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 > 2000 ? `${details.output.slice(0, 2000)}...` : details.output;
+    const out = details.output.length > EXPANDED_STDOUT_CHARS
+      ? `${details.output.slice(0, EXPANDED_STDOUT_CHARS)}…`
+      : details.output;
     container.addChild(new Text(out, 0, 0));
   }
 
@@ -611,7 +516,7 @@ function renderReplExpanded(details: ReplDetails, theme: Theme): Container {
   // Stderr
   if (details.stderr) {
     container.addChild(new Spacer(1));
-    container.addChild(new Text(theme.fg("error", details.stderr.slice(0, 500)), 0, 0));
+    container.addChild(new Text(theme.fg("error", details.stderr.slice(0, EXPANDED_STDERR_CHARS)), 0, 0));
   }
 
   // Sub-call tree