@hicaru/pi-rlm 0.2.0 → 0.2.2

package/src/tool/rlm-events.ts

@@ -45,10 +45,6 @@ export interface SubcallUpdatedEvent {
   readonly totalCount?: number;
 }
 
-export interface WarningsEvent {
-  readonly warnings: readonly string[];
-}
-
 export interface TurnEvent {
   readonly current: number;
   readonly max: number;
@@ -76,18 +72,26 @@ export interface RootPromptEvent {
 /**
  * Typed wrapper around a Node.js EventEmitter for RLM lifecycle events.
  *
- * Auto-generates monotonic subcall IDs (`s1`, `s2`, …) via `emitSubcallCreated()`.
+ * Auto-generates monotonic subcall IDs (`s1`, `s2`, …) via `emitSubcallCreated()`, with a
+ * configurable prefix so a second emitter's IDs cannot collide with the default ones.
  * Provides typed `on*` methods that return unsubscribe functions.
  */
 export class RlmEmitter {
   private readonly ee = new EventEmitter();
   private seq = 0;
 
+  /**
+   * `idPrefix` namespaces generated IDs. The counter is per-instance, so two emitters
+   * would both start at `s1`; a distinct prefix is what lets one emitter's subcalls be
+   * merged into another's tree without colliding IDs or corrupting parentId links.
+   */
+  constructor(private readonly idPrefix = "s") {}
+
   // ── Emit ──
 
   /** Create a new sub-call entry. Returns the auto-generated ID. */
   emitSubcallCreated(init: Omit<SubcallCreatedEvent, "id">): string {
-    const id = `s${++this.seq}`;
+    const id = `${this.idPrefix}${++this.seq}`;
     const event: SubcallCreatedEvent = { id, ...init };
     this.ee.emit("subcall:created", event);
     return id;
@@ -113,11 +117,6 @@ export class RlmEmitter {
     this.ee.emit("answer", { text } satisfies AnswerEvent);
   }
 
-  /** Set advisory warnings (root-only; never a failure). */
-  emitWarnings(warnings: readonly string[]): void {
-    this.ee.emit("warnings", { warnings } satisfies WarningsEvent);
-  }
-
   /** Set the root run status (done/error/aborted). */
   emitStatus(status: RlmRunStatus): void {
     this.ee.emit("status", { status } satisfies StatusEvent);
@@ -155,11 +154,6 @@ export class RlmEmitter {
     return () => { this.ee.off("answer", handler); };
   }
 
-  onWarnings(handler: (event: WarningsEvent) => void): () => void {
-    this.ee.on("warnings", handler);
-    return () => { this.ee.off("warnings", handler); };
-  }
-
   onStatus(handler: (event: StatusEvent) => void): () => void {
     this.ee.on("status", handler);
     return () => { this.ee.off("status", handler); };

package/src/tool/rlm-tool.ts

@@ -8,7 +8,6 @@
 import { type Theme, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Spacer, Text, type Component } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import { createPiInteractiveDeps } from "../bridge/pi-interactive.ts";
 import type { RlmController, StartInput } from "../mode/rlm-mode.ts";
 import { spinnerFrame } from "../ui/theme.ts";
 import { markdownTheme } from "../ui/theme-adapter.ts";
@@ -82,15 +81,10 @@ export function createRlmTool(controller: RlmController): ToolDefinition<typeof
 
       try {
         const input: StartInput = {
-          kind: "fresh",
           rootPrompt: params.prompt,
           context: params.context ?? undefined,
         };
-        const interactive = createPiInteractiveDeps(ctx);
-        const { done } = controller.start(ctx, input, emitter, {
-          onAskUserQuestion: controller.config.askUserQuestion ? interactive.onAskUserQuestion : undefined,
-          onTodo: controller.config.todo ? interactive.onTodo : undefined,
-        });
+        const { done } = controller.start(ctx, input, emitter);
         const result = await done;
 
         emitter.emitAnswer(result.answer);
@@ -152,11 +146,6 @@ function renderExpanded(details: RlmDetails, theme: Theme): Component {
     container.addChild(new Markdown(details.answer, 0, 0, markdownTheme(theme)));
   }
 
-  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));
-  }
-
   return container;
 }
 

package/src/tool/subcall-render.ts

@@ -52,11 +52,21 @@ export function cardStatsLine(
   totals: { readonly costUsd: number; readonly tokens: number },
   theme: Theme,
   extra?: string,
+  backgroundPending?: number,
 ): string {
   const parts: string[] = [formatCost(totals.costUsd)];
   if (totals.tokens > 0) parts.push(`${formatTokens(totals.tokens)} tok`);
   if (extra) parts.push(extra);
-  return theme.fg("dim", parts.join(" · "));
+  const line = theme.fg("dim", parts.join(" · "));
+  // The one thing no tree can show: spawned work that may outlive this block.
+  return backgroundPending !== undefined && backgroundPending > 0
+    ? `${line} ${theme.fg("warning", `↯${backgroundPending} bg`)}`
+    : line;
+}
+
+/** Detached nodes carry BackgroundTasks' "bg" id prefix (RlmEmitter("bg")). */
+function backgroundTag(sc: RlmSubcall, theme: Theme): string {
+  return sc.id.startsWith("bg") ? ` ${theme.fg("warning", "↯bg")}` : "";
 }
 
 /** `<glyph> <TITLE> <stats>` — the first line of both tools' collapsed and expanded views. */
@@ -128,7 +138,8 @@ export function renderCollapsedSubcallTree(
       const branch = isLast ? "└─" : "├─";
       const gGlyph = subcallStatusGlyph(sc, theme);
       const gStats = subcallStatsLine(sc);
-      lines.push(`${prefix}${branch} ${sc.label}  ${gGlyph}  ${gStats}`);
+      const gBg = backgroundTag(sc, theme);
+      lines.push(`${prefix}${branch} ${sc.label}  ${gGlyph}  ${gStats}${gBg}`);
       const childPrefix = prefix + (isLast ? "   " : "│  ");
       lines.push(...walk(sc.id, childPrefix));
     }
@@ -155,7 +166,8 @@ export function renderExpandedSubcallTree(
     const sKind = theme.fg("muted", sc.label);
     const sModel = sc.model ? theme.fg("dim", ` ${sc.model}`) : "";
     const sStats = sc.endedAt ? `  ${theme.fg("dim", subcallStatsLine(sc))}` : "";
-    let line = `${pad}${sGlyph} ${sKind}${sModel}${sStats}`;
+    const sBg = backgroundTag(sc, theme);
+    let line = `${pad}${sGlyph} ${sKind}${sModel}${sStats}${sBg}`;
 
     if (sc.args) {
       line += `\n${pad}  ${theme.fg("dim", previewText(sc.args, ARGS_PREVIEW_CHARS))}`;

package/src/tool/subcall-store.ts

@@ -7,13 +7,19 @@
  * subcall accumulation logic.
  */
 import type { RlmEmitter, SubcallCreatedEvent, SubcallUpdatedEvent } from "./rlm-events.ts";
-import type { RlmSubcall } from "./rlm-details.ts";
+import type { RlmSubcall, SubcallStatus } from "./rlm-details.ts";
 import { EmitterListener } from "./emitter-listener.ts";
 
 type MutableSubcall = {
   -readonly [Key in keyof RlmSubcall]: RlmSubcall[Key];
 };
 
+/** Accumulated cost/tokens, shared by getTotals() and takeSettledSubtrees(). */
+export interface SubcallTotals {
+  readonly costUsd: number;
+  readonly tokens: number;
+}
+
 export class SubcallStore extends EmitterListener {
   private readonly subcalls = new Map<string, MutableSubcall>();
 
@@ -82,6 +88,56 @@ export class SubcallStore extends EmitterListener {
     return { costUsd: this.totalCostUsd, tokens: this.totalTokens };
   }
 
+  /**
+   * Remove and return every fully-settled root subtree, with its cost/tokens subtracted
+   * from the running totals so the caller can add them without double-counting.
+   *
+   * A root whose subtree still has a running node stays put. That matters because
+   * `renderCollapsedSubcallTree` walks down from `parentId === undefined`: a subcall handed
+   * over without its parent has no path from a root and is silently dropped from the tree.
+   * Handing over whole subtrees is what keeps adopted nodes renderable.
+   */
+  takeSettledSubtrees(): { readonly subcalls: readonly RlmSubcall[]; readonly totals: SubcallTotals } {
+    const children = new Map<string | undefined, MutableSubcall[]>();
+    for (const sc of this.subcalls.values()) {
+      const siblings = children.get(sc.parentId);
+      if (siblings === undefined) children.set(sc.parentId, [sc]);
+      else siblings.push(sc);
+    }
+
+    // Collect a root's subtree, or undefined when any node in it is still running.
+    const settledSubtree = (root: MutableSubcall): MutableSubcall[] | undefined => {
+      const collected: MutableSubcall[] = [];
+      const stack: MutableSubcall[] = [root];
+      while (stack.length > 0) {
+        const node = stack.pop();
+        if (node === undefined) continue;
+        if (node.status === "running") return undefined;
+        collected.push(node);
+        const kids = children.get(node.id);
+        if (kids !== undefined) stack.push(...kids);
+      }
+      return collected;
+    };
+
+    const taken: RlmSubcall[] = [];
+    let costUsd = 0;
+    let tokens = 0;
+    for (const root of children.get(undefined) ?? []) {
+      const subtree = settledSubtree(root);
+      if (subtree === undefined) continue;
+      for (const node of subtree) {
+        costUsd += node.costUsd;
+        tokens += node.tokens;
+        taken.push(Object.freeze({ ...node, status: node.status as SubcallStatus }));
+        this.subcalls.delete(node.id);
+      }
+    }
+    this.totalCostUsd -= costUsd;
+    this.totalTokens -= tokens;
+    return { subcalls: taken, totals: { costUsd, tokens } };
+  }
+
   // ── Root usage (delegated from RlmEventAggregator) ──
 
   /** Accumulate root-level usage into shared totals. Called by aggregator. */

package/src/ui/config-panel.ts

@@ -9,21 +9,17 @@ const CHOICES = Object.freeze({
   maxDepth: Object.freeze(["1", "2", "3", "4"]),
   maxIterations: Object.freeze(["10", "20", "30", "50"]),
   execTimeoutS: Object.freeze(["30", "60", "120", "300"]),
-  maxConcurrentSubcalls: Object.freeze(["2", "4", "8", "16"]),
-  maxBudgetUsd: Object.freeze(["none", "0.50", "1", "5"]),
+  maxConcurrentSubcalls: Object.freeze(["2", "4", "8", "16", "32"]),
+  maxConcurrentChildren: Object.freeze(["1", "2", "3", "4", "6", "8"]),
   maxTimeoutMs: Object.freeze(["none", "60", "120", "300"]),
   maxTokens: Object.freeze(["none", "10000", "50000", "100000"]),
   maxErrors: Object.freeze(["3", "5", "10", "none"]),
   orchestrator: Object.freeze(["on", "off"]),
-  pipeline: Object.freeze(["on", "off"]),
-  maxBackwardJumps: Object.freeze(["0", "1", "2", "3"]),
   compaction: Object.freeze(["on", "off"]),
   compactionThresholdPct: Object.freeze(["50", "65", "80", "90"]),
   rootSamplingMaxTokens: Object.freeze(["4096", "8192", "16384", "32768"]),
   sandboxInitTimeoutMs: Object.freeze(["10000", "30000", "60000", "120000"]),
   requestTimeoutMs: Object.freeze(["2", "5", "10", "20"]),
-  askUserQuestion: Object.freeze(["on", "off"]),
-  todo: Object.freeze(["on", "off"]),
   libraryLoader: Object.freeze(["on", "off"]),
 });
 
@@ -43,20 +39,16 @@ export async function showConfigPanel(ctx: ExtensionContext, config: RlmConfig):
     item("maxIterations", "Max iterations", String(config.maxIterations), CHOICES.maxIterations, "Maximum root REPL turns before RLM asks the model for a final answer."),
     item("execTimeoutS", "REPL block timeout (s)", String(config.execTimeoutS), CHOICES.execTimeoutS, "Wall-clock limit for one model-authored Python REPL block."),
     item("maxConcurrentSubcalls", "Max concurrent sub-calls", String(config.maxConcurrentSubcalls), CHOICES.maxConcurrentSubcalls, "Concurrency pool size for llm_query_batched and rlm_query_batched."),
-    item("maxBudgetUsd", "Budget ceiling (USD)", config.maxBudgetUsd != null ? String(config.maxBudgetUsd) : "none", CHOICES.maxBudgetUsd, "Total spend cap for the whole recursive tree; none disables the cap."),
+    item("maxConcurrentChildren", "Max concurrent children", String(config.maxConcurrentChildren), CHOICES.maxConcurrentChildren, "Concurrent rlm_query child engines per depth. Each is a Python process holding its own copy of the inherited context."),
     item("maxTimeoutMs", "Wall-clock ceiling (min)", config.maxTimeoutMs != null ? String(Math.round(config.maxTimeoutMs / 60_000)) : "none", CHOICES.maxTimeoutMs, "Total runtime cap for the whole recursive tree; none disables the cap."),
     item("maxTokens", "Token ceiling", config.maxTokens != null ? String(config.maxTokens) : "none", CHOICES.maxTokens, "Total input+output token cap for the whole recursive tree."),
     item("maxErrors", "Max consecutive errors", config.maxErrors != null ? String(config.maxErrors) : "none", CHOICES.maxErrors, "Stop after this many consecutive failing turns; none disables the guard."),
     item("orchestrator", "Orchestrator addendum", config.orchestrator ? "on" : "off", CHOICES.orchestrator, "Append extra divide-and-conquer guidance to the root model system prompt."),
-    item("pipeline", "Phase pipeline", config.pipeline ? "on" : "off", CHOICES.pipeline, "Enable artifact-gated phases: clarify→research→blueprint→validate (read-only plan pipeline; clarify needs Ask user on)."),
-    item("maxBackwardJumps", "Max validate→blueprint loops", String(config.maxBackwardJumps), CHOICES.maxBackwardJumps, "Bounded corrective re-entries when validation reports blockers_count > 0."),
     item("compaction", "Trajectory compaction", config.compaction ? "on" : "off", CHOICES.compaction, "Summarize old turns when history approaches the model context window."),
     item("compactionThresholdPct", "Compaction threshold (%)", String(Math.round(config.compactionThresholdPct * 100)), CHOICES.compactionThresholdPct, "Compact once estimated history tokens reach this share of the root model's context window."),
     item("rootSamplingMaxTokens", "Root model output cap (tok)", String(config.rootSampling?.maxTokens ?? 16384), CHOICES.rootSamplingMaxTokens, "Max output tokens per root-model turn. Lower values keep each turn lean."),
     item("sandboxInitTimeoutMs", "Sandbox init timeout", String(config.sandboxInitTimeoutMs), CHOICES.sandboxInitTimeoutMs, "How long to wait for the Python worker to start."),
     item("requestTimeoutMs", "Sandbox request timeout (min)", String(Math.round(config.requestTimeoutMs / 60_000)), CHOICES.requestTimeoutMs, "Parent-side watchdog per sandbox request; on breach the Python worker is killed."),
-    item("askUserQuestion", "[Interactive] Ask user", config.askUserQuestion ? "on" : "off", CHOICES.askUserQuestion, "Allow root REPL code to present structured ask_user_question dialogs."),
-    item("todo", "[Interactive] Todo", config.todo ? "on" : "off", CHOICES.todo, "Allow REPL code to manage a visible todo task list."),
     item("libraryLoader", "Library loader", config.libraryLoader ? "on" : "off", CHOICES.libraryLoader,
       "Allow load_library() to pull an external dir, file, or git repo into the shared context list."),
     item("__save__", "Save & close", "↵", ["↵"], "Save these settings and close (Esc also saves)."),
@@ -101,21 +93,17 @@ export function applySetting(config: RlmConfig, id: string, value: string): RlmC
     case "maxIterations": return Object.freeze({ ...config, maxIterations: Number(value) });
     case "execTimeoutS": return Object.freeze({ ...config, execTimeoutS: Number(value) });
     case "maxConcurrentSubcalls": return Object.freeze({ ...config, maxConcurrentSubcalls: Number(value) });
-    case "maxBudgetUsd": return Object.freeze({ ...config, maxBudgetUsd: optionalNumber(value) });
+    case "maxConcurrentChildren": return Object.freeze({ ...config, maxConcurrentChildren: Number(value) });
     case "maxTimeoutMs": return Object.freeze({ ...config, maxTimeoutMs: optionalNumber(value, 60_000) });
     case "maxTokens": return Object.freeze({ ...config, maxTokens: optionalNumber(value) });
     case "maxErrors": return Object.freeze({ ...config, maxErrors: optionalNumber(value) });
     case "orchestrator": return Object.freeze({ ...config, orchestrator: value === "on" });
-    case "pipeline": return Object.freeze({ ...config, pipeline: value === "on" });
-    case "maxBackwardJumps": return Object.freeze({ ...config, maxBackwardJumps: Number(value) });
     case "compaction": return Object.freeze({ ...config, compaction: value === "on" });
     case "compactionThresholdPct": return Object.freeze({ ...config, compactionThresholdPct: Number(value) / 100 });
     case "rootSamplingMaxTokens":
       return Object.freeze({ ...config, rootSampling: Object.freeze({ ...config.rootSampling, maxTokens: Number(value) }) });
     case "sandboxInitTimeoutMs": return Object.freeze({ ...config, sandboxInitTimeoutMs: Number(value) });
     case "requestTimeoutMs": return Object.freeze({ ...config, requestTimeoutMs: Number(value) * 60_000 });
-    case "askUserQuestion": return Object.freeze({ ...config, askUserQuestion: value === "on" });
-    case "todo": return Object.freeze({ ...config, todo: value === "on" });
     case "libraryLoader": return Object.freeze({ ...config, libraryLoader: value === "on" });
     default: return config;
   }

package/src/ui/intro.ts

@@ -11,9 +11,8 @@ export const RLM_GUIDE = `# RLM mode
 ## Commands
 
 - \`/rlm\` — toggle RLM mode (shortcut: Ctrl+Shift+R). Turning it OFF also stops a running query.
-- \`/rlm-config\` — choose models, reasoning, and budget limits
+- \`/rlm-config\` — choose models, reasoning, and run limits
 - \`/rlm-stop\` — cancel the current run but stay in RLM mode (use /rlm or Ctrl+Shift+R to leave)
-- \`/rlm-help\` — show this guide again
 
 When RLM mode is ON, \`read\`/\`grep\` are disabled and the agent reads the repository through the
 \`repl\` tool, delegating bulk analysis to sub-LLMs. The footer/status line shows the current state.`;

package/src/ui/model-picker.ts

@@ -1,10 +1,11 @@
 /** Model picker TUI — choose a model and, when supported, a thinking level. */
 
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext, ModelRegistry } from "@earendil-works/pi-coding-agent";
 import { DynamicBorder } from "@earendil-works/pi-coding-agent";
 import type { Api, Model, ThinkingLevel } from "@earendil-works/pi-ai";
 import { Container, type Component, type SelectItem, SelectList, Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { formatCost } from "./theme.ts";
+import { compareLlm } from "../mode/llm-model.ts";
 
 export interface ModelSelection {
   readonly model: Model<Api>;
@@ -16,15 +17,38 @@ type SelectableThinkingLevel = (typeof LEVELS)[number];
 
 const CHEAPEST_VALUE = "__rlm_cheapest__";
 
-function items(models: Model<Api>[], includeCheapest = false): SelectItem[] {
-  const modelItems = models.map((m) => ({
-    value: `${m.provider}/${m.id}`,
-    label: `${m.provider}/${m.id}`,
-    description: `in ${formatCost(m.cost.input)}/Mtok · out ${formatCost(m.cost.output)}/Mtok${m.reasoning ? " · reasoning" : ""}`,
-  }));
+/**
+ * Models Pi itself would offer for this session, cheapest-first.
+ *
+ * Mirrors the built-in model switcher:
+ *   - if the session has scoped models (`--models` / enabledModels) → those only
+ *   - else → `getAvailable()` (providers with configured auth)
+ *
+ * Deliberately NOT `getAll()`: the full catalog dumps every provider's catalog entry and is
+ * not what the user sees in Pi natively. See Pi extension docs on `ctx.scopedModels`.
+ */
+export function pickableModels(
+  registry: ModelRegistry,
+  scoped?: readonly { readonly model: Model<Api> }[],
+): readonly Model<Api>[] {
+  const source = scoped !== undefined && scoped.length > 0
+    ? scoped.map((s) => s.model)
+    : registry.getAvailable();
+  return [...source].sort(compareLlm);
+}
+
+function items(models: readonly Model<Api>[], includeCheapest: boolean): SelectItem[] {
+  const modelItems = models.map((m) => {
+    const price = `in ${formatCost(m.cost.input)}/Mtok · out ${formatCost(m.cost.output)}/Mtok`;
+    return {
+      value: `${m.provider}/${m.id}`,
+      label: `${m.provider}/${m.id}`,
+      description: `${price}${m.reasoning ? " · reasoning" : ""}`,
+    };
+  });
   if (!includeCheapest) return modelItems;
   return [
-    { value: CHEAPEST_VALUE, label: "⟳ cheapest (auto)", description: "Always use the cheapest available model" },
+    { value: CHEAPEST_VALUE, label: "⟳ cheapest (auto)", description: "Always use the cheapest model with a configured key" },
     ...modelItems,
   ];
 }
@@ -79,12 +103,12 @@ async function selectThinkingLevel(
 export async function selectModel(
   ctx: ExtensionContext,
   title: string,
-  models: Model<Api>[],
+  models: readonly Model<Api>[],
   current?: Model<Api>,
   currentThinking?: ThinkingLevel,
 ): Promise<ModelSelection | null | undefined> {
   if (models.length === 0) {
-    ctx.ui.notify("RLM: no models with configured auth", "warning");
+    ctx.ui.notify("RLM: no models available (add a provider key in Pi, or widen --models / enabledModels)", "warning");
     return undefined;
   }
   if (ctx.mode !== "tui") {

package/src/ui/status.ts

@@ -12,18 +12,14 @@ export function modelLabel(model: Model<Api> | undefined, fallback: string): str
 
 export function formatRlmStateLine(controller: RlmController, contextUsage?: ContextUsage): string {
   if (!controller.enabled) return "○ RLM OFF";
-  const worker = modelLabel(controller.workerModel, controller.savedWorkerRef ?? "cheapest");
-  const workerSuffix = controller.config.subSampling.reasoning ? `:${controller.config.subSampling.reasoning}` : "";
+  const llm = modelLabel(controller.llmModel, controller.savedLlmRef ?? "cheapest");
+  const llmSuffix = controller.config.subSampling.reasoning ? `:${controller.config.subSampling.reasoning}` : "";
   // `percent` is null right after a compaction, before the next assistant response reports usage.
   const percent = contextUsage?.percent;
   const ctxSuffix = percent === null || percent === undefined ? "" : ` · ctx ${Math.round(percent)}%`;
-  return `● RLM ON · worker=${worker}${workerSuffix}${ctxSuffix}`;
+  return `● RLM ON · llm=${llm}${llmSuffix}${ctxSuffix}`;
 }
 
 export function setRlmModeStatus(ui: ExtensionUIContext, controller: RlmController, contextUsage?: ContextUsage): void {
   ui.setStatus(KEY, formatRlmStateLine(controller, contextUsage));
 }
-
-export function clearRlmStatus(ui: ExtensionUIContext): void {
-  ui.setStatus(KEY, undefined);
-}

package/src/util/concurrency.ts

@@ -1,15 +1,93 @@
-/** Fixed-size concurrency pool: run `fn` over `items` with at most `limit` in flight, preserving order. */
-export async function mapPool<T, R>(items: readonly T[], limit: number, fn: (item: T, idx: number) => Promise<R>): Promise<R[]> {
-  const out = new Array<R>(items.length);
-  let next = 0;
-  const worker = async (): Promise<void> => {
-    while (true) {
-      const index = next;
-      next += 1;
-      if (index >= items.length) return;
-      out[index] = await fn(items[index], index);
+/**
+ * Sub-call admission control.
+ *
+ * `spawn()` lets the sandbox put many requests on the wire at once, so a per-call pool no
+ * longer bounds anything: one `llm_query_chunked` over a large file posts every batch
+ * simultaneously, and each batch fans out again. The bound has to be session-wide, which is
+ * what `SubcallGates` is — constructed once at the composition root and shared by every
+ * handler.
+ */
+
+/**
+ * Counting semaphore: at most `limit` holders at once, FIFO.
+ *
+ * NOT re-entrant. A leaf completion takes exactly ONE slot, in `complete1`; wrapping a batch in
+ * a second acquisition of this same gate deadlocks as soon as the batch reaches `limit`
+ * prompts — the outer holders fill the gate and each waits for an inner slot nothing can free.
+ *
+ * FIFO means a large fan-out is not starved, but also that it is not preempted: a
+ * 500-prompt `llm_query_chunked` holds the queue until it drains, so an interactive
+ * `llm_query` issued behind it waits for the whole thing. Acceptable while sub-calls are
+ * uniform in priority; revisit if an interactive tier is ever added.
+ */
+export class Semaphore {
+  private active = 0;
+  private readonly waiters: Array<() => void> = [];
+
+  constructor(private readonly limit: number) {}
+
+  /** Hold a slot for the duration of `fn`. */
+  async run<T>(fn: () => Promise<T>): Promise<T> {
+    // `while`, not `if`: a caller arriving between the decrement below and a woken waiter's
+    // resumption would otherwise slip past the limit.
+    while (this.active >= this.limit) {
+      await new Promise<void>((resolve) => { this.waiters.push(resolve); });
     }
-  };
-  await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
-  return out;
+    this.active += 1;
+    try {
+      return await fn();
+    } finally {
+      this.active -= 1;
+      this.waiters.shift()?.();
+    }
+  }
+
+  /** In-flight holders. Exposed for tests asserting the bound. */
+  get inFlight(): number {
+    return this.active;
+  }
+}
+
+/**
+ * One semaphore per recursion depth.
+ *
+ * A single shared gate would deadlock: `limit` rlm_query children holding every slot, each
+ * blocked waiting for a grandchild that can never be admitted. Splitting by depth breaks the
+ * cycle — a holder at depth k only ever waits on depth k+1. Leaf LLM calls are terminal and
+ * never re-enter, so they safely share one process-wide gate.
+ */
+export class DepthGates {
+  private readonly gates = new Map<number, Semaphore>();
+
+  constructor(private readonly limit: number) {}
+
+  at(depth: number): Semaphore {
+    let gate = this.gates.get(depth);
+    if (gate === undefined) {
+      gate = new Semaphore(this.limit);
+      this.gates.set(depth, gate);
+    }
+    return gate;
+  }
+}
+
+/** Session-wide sub-call admission. Construct once; pass explicitly — never default one in. */
+export interface SubcallGates {
+  /** llm_query / llm_query_batched completions — terminal, so one shared gate. */
+  readonly leaf: Semaphore;
+  /** Recursive child engines — one gate per depth, see DepthGates. */
+  readonly rlm: DepthGates;
+}
+
+/**
+ * Worst case is `(maxDepth - 1) × childLimit` concurrent child engines — the cap short-circuits
+ * at `childDepth >= maxDepth`, so engines exist at depths 1..maxDepth-1 — plus `leafLimit` leaf
+ * completions.
+ *
+ * Children get their own, smaller bound because they are far heavier than leaves: each owns a
+ * Python subprocess AND its own copy of the context it inherited from its parent, where a leaf
+ * is one HTTP request. See DEFAULT_CONFIG.maxConcurrentChildren.
+ */
+export function createSubcallGates(leafLimit: number, childLimit: number = leafLimit): SubcallGates {
+  return Object.freeze({ leaf: new Semaphore(leafLimit), rlm: new DepthGates(childLimit) });
 }

package/src/util/trace.ts

@@ -0,0 +1,42 @@
+/**
+ * RLM trace — one JSONL line per interesting event, for the E2E harness and for post-mortem of
+ * a hung run. Off unless RLM_TRACE_FILE is set; when off, every call costs one boolean check.
+ *
+ * Purely observational: it subscribes to the RlmEmitter that already exists and to the sandbox
+ * frames that already cross the pipe. No behaviour is duplicated here.
+ */
+import { appendFileSync } from "node:fs";
+import type { RlmEmitter } from "../tool/rlm-events.ts";
+
+const FILE = process.env.RLM_TRACE_FILE;
+
+/** Check this before building payloads on hot paths. */
+export const traceEnabled: boolean = typeof FILE === "string" && FILE.length > 0;
+
+const START = Date.now();
+
+/** Append one event. Fail-soft: tracing must never break a run (state/writes.ts convention). */
+export function trace(kind: string, data: Record<string, unknown> = {}): void {
+  if (!traceEnabled || FILE === undefined) return;
+  const now = Date.now();
+  try {
+    appendFileSync(FILE, `${JSON.stringify({ t: now, rel: now - START, pid: process.pid, kind, ...data })}\n`);
+  } catch {
+    /* ignore */
+  }
+}
+
+/** Mirror one emitter's sub-call lifecycle into the trace. Returns an unsubscribe fn. */
+export function attachTracer(emitter: RlmEmitter, scope: "turn" | "background"): () => void {
+  if (!traceEnabled) return () => {};
+  // Rename e.kind → subcallKind so it does not overwrite the outer event kind
+  // (`subcall.created` / `subcall.updated`) when `trace` spreads `data` after `kind`.
+  const offs = [
+    emitter.onSubcallCreated((e) => {
+      const { kind: subcallKind, ...rest } = e;
+      trace("subcall.created", { scope, subcallKind, ...rest });
+    }),
+    emitter.onSubcallUpdated((e) => trace("subcall.updated", { scope, ...e })),
+  ];
+  return () => { for (const off of offs) off(); };
+}