@cr1ms0n/pi-subagent 0.8.1

package/src/model-policy.ts

@@ -0,0 +1,157 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export const MODEL_POLICY_CONFIG_FILE = path.join(os.homedir(), ".pi", "subagent.json");
+
+export interface ModelRoute {
+  model: string;
+  /** Immutable order owned by the user configuration. */
+  fallbackModels: readonly string[];
+}
+
+export interface ModelPolicySnapshot {
+  default: ModelRoute;
+  agents: ReadonlyMap<string, ModelRoute>;
+  source: string;
+}
+
+export interface ModelPolicyValidation {
+  route?: ModelRoute;
+  error?: string;
+}
+
+const AGENT_NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+
+function invalid(source: string, message: string): never {
+  throw new Error(`Invalid modelPolicy in ${source}: ${message}`);
+}
+
+function modelId(value: unknown, pathName: string, source: string): string {
+  if (typeof value !== "string") invalid(source, `${pathName}.model must be a string in provider/model-id form`);
+  const model = value.trim();
+  const slash = model.indexOf("/");
+  if (!model || slash <= 0 || slash === model.length - 1 || /[\x00-\x1f\s]/.test(model)) {
+    invalid(source, `${pathName}.model must be a non-empty provider/model-id without whitespace`);
+  }
+  return model;
+}
+
+function route(value: unknown, pathName: string, source: string): ModelRoute {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    invalid(source, `${pathName} must be an object`);
+  }
+  const record = value as Record<string, unknown>;
+  const unknown = Object.keys(record).filter((key) => key !== "model" && key !== "fallbackModels");
+  if (unknown.length) invalid(source, `${pathName} has unknown field(s): ${unknown.join(", ")}`);
+  const model = modelId(record.model, pathName, source);
+  const rawFallbacks = record.fallbackModels === undefined ? [] : record.fallbackModels;
+  if (!Array.isArray(rawFallbacks)) invalid(source, `${pathName}.fallbackModels must be an array`);
+  const fallbackModels = rawFallbacks.map((value, index) => modelId(value, `${pathName}.fallbackModels[${index}]`, source));
+  if (new Set(fallbackModels).size !== fallbackModels.length) invalid(source, `${pathName}.fallbackModels must not contain duplicates`);
+  if (fallbackModels.includes(model)) invalid(source, `${pathName}.fallbackModels must not repeat the primary model`);
+  return Object.freeze({ model, fallbackModels: Object.freeze([...fallbackModels]) });
+}
+
+/** Parse only the modelPolicy subtree; no provider catalog or credentials are read. */
+export function parseModelPolicy(raw: unknown, source = MODEL_POLICY_CONFIG_FILE): ModelPolicySnapshot {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    invalid(source, "modelPolicy must be an object");
+  }
+  const record = raw as Record<string, unknown>;
+  const unknown = Object.keys(record).filter((key) => key !== "default" && key !== "agents");
+  if (unknown.length) invalid(source, `modelPolicy has unknown field(s): ${unknown.join(", ")}`);
+  if (!("default" in record)) invalid(source, "modelPolicy.default is required");
+  const defaultRoute = route(record.default, "modelPolicy.default", source);
+  const agents = new Map<string, ModelRoute>();
+  const rawAgents = record.agents === undefined ? {} : record.agents;
+  if (!rawAgents || typeof rawAgents !== "object" || Array.isArray(rawAgents)) {
+    invalid(source, "modelPolicy.agents must be an object");
+  }
+  for (const [name, value] of Object.entries(rawAgents as Record<string, unknown>)) {
+    const normalized = name.trim().toLowerCase();
+    if (!AGENT_NAME.test(normalized)) invalid(source, `modelPolicy.agents key ${JSON.stringify(name)} is not a valid agent name`);
+    if (agents.has(normalized)) invalid(source, `modelPolicy.agents contains duplicate agent ${normalized}`);
+    agents.set(normalized, route(value, `modelPolicy.agents.${normalized}`, source));
+  }
+  return Object.freeze({ default: defaultRoute, agents, source });
+}
+
+/** Read the raw config only far enough to validate modelPolicy. */
+export async function readModelPolicyFile(file = MODEL_POLICY_CONFIG_FILE): Promise<ModelPolicySnapshot> {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(await fs.readFile(file, "utf8"));
+  } catch (error: any) {
+    if (error?.code === "ENOENT") throw new Error(`Model policy is not configured. Create ${file} using the model policy template.`);
+    throw new Error(`Could not read ${file} as JSON; model policy was not loaded.`);
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw) || !("modelPolicy" in (raw as Record<string, unknown>))) {
+    throw new Error(`Model policy is missing from ${file}. Add modelPolicy.default using the model policy template.`);
+  }
+  return parseModelPolicy((raw as Record<string, unknown>).modelPolicy, file);
+}
+
+export function resolveModelRoute(policy: ModelPolicySnapshot, agent?: string): ModelRoute {
+  const name = agent?.trim().toLowerCase();
+  return (name && policy.agents.get(name)) || policy.default;
+}
+
+/** Validate the caller-owned fields against the immutable configured route. */
+export function validateModelRequest(
+  policy: ModelPolicySnapshot,
+  options: { agent?: string; model?: string; fallbackModels?: string[]; fallbackModelsProvided?: boolean },
+): ModelPolicyValidation {
+  const route = resolveModelRoute(policy, options.agent);
+  const actualModel = options.model?.trim();
+  if (!actualModel) return { error: `model is required; expected configured model ${route.model}` };
+  if (actualModel !== route.model) {
+    return { error: `model ${JSON.stringify(actualModel)} does not match the configured model ${JSON.stringify(route.model)}${options.agent ? ` for agent ${options.agent}` : ""}` };
+  }
+  if (options.fallbackModelsProvided) {
+    const requested = (options.fallbackModels ?? []).map((model) => model.trim());
+    if (requested.length !== route.fallbackModels.length || requested.some((model, index) => model !== route.fallbackModels[index])) {
+      return {
+        error: `fallback_models must exactly match the configured order for ${actualModel}: [${route.fallbackModels.join(", ")}]`,
+      };
+    }
+  }
+  return { route };
+}
+
+export function formatModelPolicyPrompt(policy: ModelPolicySnapshot | undefined, error?: string): string {
+  if (!policy) {
+    return [
+      "## Subagent model policy",
+      error || `No valid model policy is configured at ${MODEL_POLICY_CONFIG_FILE}.`,
+      "Management actions (status/wait/cancel/steer/diff/apply/discard) remain available, but every new task/tasks[] spawn and plan request is rejected until modelPolicy is configured.",
+      "Use the package model-policy template; do not invent model IDs or fallback models.",
+    ].join("\n");
+  }
+  const lines = [
+    "## Subagent model policy",
+    "Every new task/tasks[] spawn must pass model explicitly and it must exactly match this mapping. Management actions do not need model.",
+    `default (agentless and unmapped agents): model=${policy.default.model}; fallback_models=[${policy.default.fallbackModels.join(", ")}]`,
+  ];
+  for (const [agent, route] of [...policy.agents.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    lines.push(`agent:${agent}: model=${route.model}; fallback_models=[${route.fallbackModels.join(", ")}]`);
+  }
+  lines.push(
+    "If fallback_models is omitted, the configured list is used. If it is supplied, it must match the configured list exactly, including order.",
+    "Do not use model/fallback_models from agent frontmatter, taskDefaults, or the parent session; those legacy fields are ignored.",
+  );
+  return lines.join("\n");
+}
+
+export function modelPolicyTemplate(): string {
+  return JSON.stringify({
+    modelPolicy: {
+      default: { model: "<provider/model-id>", fallbackModels: [] },
+      agents: { "<agent-name>": { model: "<provider/model-id>", fallbackModels: [] } },
+    },
+  }, null, 2);
+}
+
+export function modelPolicySource(file = MODEL_POLICY_CONFIG_FILE): string {
+  return path.normalize(file);
+}

package/src/notifications.ts

@@ -0,0 +1,106 @@
+/**
+ * Background-run completion notifications.
+ *
+ * When an async run reaches a terminal state, the parent LLM is notified with
+ * a followUp message (delivered when the agent is idle / between turns) so it
+ * can react without polling status/wait. Matches the notification-as-delivery
+ * semantics of `wait`: whichever path delivers first wins via markDelivered.
+ *
+ * Batching: successes completing within a short window group into a single
+ * message (no notification spam in fanouts). Failures bypass batching and
+ * flush immediately, carrying any held successes with them.
+ */
+
+export interface CompletionBatcherOptions {
+  /** Quiet window after the most recent completion before flushing. */
+  debounceMs?: number;
+  /** Hard cap measured from the first held completion; nothing waits longer. */
+  maxWaitMs?: number;
+}
+
+export class CompletionBatcher {
+  private readonly debounceMs: number;
+  private readonly maxWaitMs: number;
+  private pending: string[] = [];
+  private timer?: NodeJS.Timeout;
+  private firstHeldAt?: number;
+  private disposed = false;
+
+  constructor(
+    private readonly onFlush: (runIds: string[]) => void,
+    options: CompletionBatcherOptions = {},
+  ) {
+    this.debounceMs = options.debounceMs ?? 2_000;
+    this.maxWaitMs = options.maxWaitMs ?? 10_000;
+  }
+
+  add(runId: string, isFailure: boolean): void {
+    if (this.disposed) return;
+    if (!this.pending.includes(runId)) this.pending.push(runId);
+    if (isFailure) {
+      // Failure signals are never delayed; held successes ride along.
+      this.flushNow();
+      return;
+    }
+    const now = Date.now();
+    this.firstHeldAt ??= now;
+    const remainingCap = Math.max(0, this.firstHeldAt + this.maxWaitMs - now);
+    const wait = Math.min(this.debounceMs, remainingCap);
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => this.flushNow(), wait);
+    this.timer.unref?.();
+  }
+
+  flushNow(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = undefined;
+    this.firstHeldAt = undefined;
+    if (!this.pending.length) return;
+    const batch = this.pending;
+    this.pending = [];
+    this.onFlush(batch);
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = undefined;
+    this.pending = [];
+  }
+}
+
+/** Compact renderer-facing payload for one completed task in a run. */
+export interface CompletionDetailsTask {
+  label: string;
+  state: string;
+  preview: string;
+  turns: number;
+  tokens: number;
+  cost: number;
+  model?: string;
+  attemptedModels?: string[];
+  pointers: string[];
+}
+
+/** Compact renderer-facing payload for one completed run. */
+export interface CompletionDetailsRun {
+  id: string;
+  label: string;
+  state: string;
+  preview: string;
+  turns: number;
+  tokens: number;
+  cost: number;
+  durationMs: number;
+  /** Kept for single-task consumers; parallel consumers must use tasks[]. */
+  model?: string;
+  attemptedModels?: string[];
+  pointers: string[];
+  tasks: CompletionDetailsTask[];
+}
+
+export interface CompletionDetails {
+  runs: CompletionDetailsRun[];
+}
+
+export const COMPLETION_MESSAGE_TYPE = "subagent-completion";

package/src/orchestrator.ts

@@ -0,0 +1,247 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { defaultConfig } from "./config.js";
+import { createGetPiCommand } from "./launch.js";
+import type { ProcessLockManager } from "./process-lock.js";
+import { ChildRunner, type GetPiCommand } from "./runner.js";
+import { Semaphore } from "./semaphore.js";
+import type { RunMode, RunState, TaskResult, TaskSpec } from "./types.js";
+import { addUsage } from "./usage.js";
+import { WorktreeManager, type WorktreeHandle } from "./worktree.js";
+
+export interface OrchestratorDeps {
+  semaphore?: Semaphore;
+  getPiCommand?: GetPiCommand;
+  sessionDir?: string;
+  worktrees?: WorktreeManager;
+  killGraceMs?: number;
+  locks?: ProcessLockManager;
+  runId?: string;
+  parentSessionKey?: string;
+  onTaskProgress?: (index: number, partial: Partial<TaskResult>) => void;
+  /** Exposes each task's live runner (for mid-run steering). Re-fires per retry attempt. */
+  onRunnerCreated?: (index: number, runner: ChildRunner) => void;
+  /** Wrap-up grace turns after budget breach (per-spec graceTurns overrides). */
+  graceTurns?: number;
+  /** Stall watchdog windows (0 disables). */
+  stallAfterMs?: number;
+  stallKillAfterMs?: number;
+  /** Default extra attempts on transient failures (per-spec maxRetries overrides). */
+  maxRetries?: number;
+}
+
+/**
+ * Transient failures are infrastructure problems, not task problems: the same
+ * spec is safe to retry without duplicating side effects because no meaningful
+ * work happened (queued timeout) or the child died from environment causes
+ * (stall, provider error, spawn error, unexpected signal).
+ *
+ * Never retried: real task failures (nonzero exit with complete protocol),
+ * cancellations, budget stops, and running timeouts (work may be half-done).
+ */
+export function isTransientFailure(result: TaskResult): boolean {
+  if (result.state === "timeout" && result.timeoutPhase === "queued") return true;
+  if (result.stopReason === "stalled") return true;
+  if (result.stopReason === "spawn_error") return true;
+  // Provider/stream errors: stopReason "error" comes from provider-reported
+  // failure or the fatal RPC path; both are retry-with-fallback candidates.
+  if (result.state === "failed" && ["error", "protocol_error", "unexpected_signal"].includes(result.stopReason ?? "")) return true;
+  return false;
+}
+
+export interface OrchestratedRun {
+  mode: RunMode;
+  results: TaskResult[];
+  state: RunState;
+  summary: string;
+}
+
+function aggregateState(results: TaskResult[]): RunState {
+  if (results.every((r) => r.state === "completed")) return "completed";
+  // Budget-stopped / truncated tasks ("partial") carry useful output.
+  if (results.some((r) => r.state === "completed" || r.state === "partial")) return "partial";
+  if (results.every((r) => r.state === "cancelled")) return "cancelled";
+  if (results.every((r) => r.state === "timeout" || r.state === "cancelled")) return "timeout";
+  if (results.some((r) => r.state === "timeout") && results.every((r) => ["timeout", "cancelled", "failed"].includes(r.state))) {
+    return results.every((r) => r.state === "timeout") ? "timeout" : "failed";
+  }
+  return "failed";
+}
+
+function summarize(results: TaskResult[]): string {
+  return results.map((r) => {
+    const body = r.outputMode === "file-only"
+      ? r.outputFile ? `Output written to ${r.outputFile}` : "No output artifact"
+      : r.liveText || r.errorMessage || r.stderr || "(no output)";
+    return `[${r.label}] ${r.state}\n${body}`;
+  }).join("\n\n");
+}
+
+async function writeArtifact(spec: TaskSpec, result: TaskResult): Promise<void> {
+  if (!spec.output) return;
+  const text = result.liveText || result.errorMessage || result.stderr || "(no output)";
+  await fs.mkdir(path.dirname(spec.output), { recursive: true });
+  await fs.writeFile(spec.output, text, "utf8");
+  result.outputFile = spec.output;
+  result.outputMode = spec.outputMode;
+}
+
+export async function runTasks(
+  specs: TaskSpec[],
+  options: OrchestratorDeps & { signal?: AbortSignal } = {},
+): Promise<OrchestratedRun> {
+  const semaphore = options.semaphore ?? new Semaphore(defaultConfig.maxActiveProcesses, defaultConfig.maxQueuedTasks);
+  const worktrees = options.worktrees ?? new WorktreeManager();
+  const handles: Array<WorktreeHandle | undefined> = new Array(specs.length);
+  const prepared: TaskSpec[] = [];
+
+  try {
+    for (let index = 0; index < specs.length; index++) {
+      if (options.signal?.aborted) throw new Error("Subagent run cancelled before worktree setup");
+      const spec = { ...specs[index]! };
+      if (spec.isolation === "worktree") {
+        const handle = await worktrees.create(spec.cwd || process.cwd(), spec.task.slice(0, 20), options.signal, {
+          includeWip: spec.includeWip === true,
+        });
+        handles[index] = handle;
+        spec.cwd = handle.cwd;
+        // Announce the worktree immediately so live runs can shield it from GC sweeps.
+        options.onTaskProgress?.(index, {
+          worktree: { cwd: handle.cwd, branch: handle.branch, baseCommit: handle.baseCommit, changed: false },
+        });
+      }
+      prepared.push(spec);
+    }
+  } catch (error) {
+    // Setup failure: remove only unchanged worktrees. Preserve modified ones.
+    for (const handle of handles.filter((h): h is WorktreeHandle => !!h)) {
+      await worktrees.finalize(handle).catch(() => {});
+    }
+    if (options.signal?.aborted) {
+      const results = specs.map<TaskResult>((spec, index) => ({
+        label: `task-${index + 1}`,
+        task: spec.task,
+        model: spec.model,
+        state: "cancelled",
+        exitCode: 1,
+        messages: [],
+        stderr: "",
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, reasoning: 0, cost: 0, contextTokens: 0, turns: 0 },
+        stopReason: "cancelled",
+        errorMessage: error instanceof Error ? error.message : String(error),
+        thinking: spec.thinking,
+        profile: spec.profile,
+        canWrite: spec.canWrite,
+        outputFile: spec.output,
+        outputMode: spec.outputMode,
+        protocol: { headerSeen: false, assistantEndSeen: false, agentEndSeen: false, agentSettledSeen: false, validEvents: 0, parseErrors: 0 },
+      }));
+      return { mode: specs.length > 1 ? "parallel" : "single", results, state: "cancelled", summary: "Subagent run cancelled during setup" };
+    }
+    throw error;
+  }
+
+  const runOne = async (index: number): Promise<TaskResult> => {
+    const spec = prepared[index]!;
+    // Per-task durable id stays unique under a multi-task run by appending index.
+    const taskRunId = options.runId
+      ? (specs.length > 1 ? `${options.runId}:${index}` : options.runId)
+      : undefined;
+
+    // Retry with model fallback on transient failures. Attempt N uses the
+    // N-1th fallback model (attempt 1 = primary). Usage accumulates across
+    // attempts so the cost ledger reflects everything billed.
+    const fallbacks = spec.fallbackModels ?? [];
+    const maxRetries = spec.maxRetries ?? options.maxRetries ?? defaultConfig.maxRetries;
+    // Providing fallback models implies wanting them all tried; otherwise
+    // maxRetries bounds same-model retries.
+    const maxAttempts = 1 + Math.max(maxRetries, fallbacks.length);
+    const attemptedModels: string[] = [];
+    let priorUsage: ReturnType<typeof addUsage> | undefined;
+    let result!: TaskResult;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const model = attempt === 1 ? spec.model : (fallbacks[attempt - 2] ?? spec.model);
+      if (model) attemptedModels.push(model);
+      const attemptSpec: TaskSpec = { ...spec, model };
+      const runner = new ChildRunner(
+        semaphore,
+        options.getPiCommand ?? createGetPiCommand(),
+        options.sessionDir,
+        (partial) => options.onTaskProgress?.(index, {
+          ...partial,
+          attempts: attempt > 1 ? attempt : undefined,
+          usage: partial.usage && priorUsage ? addUsage(priorUsage, partial.usage) : partial.usage,
+        }),
+        options.killGraceMs,
+        options.locks,
+        taskRunId,
+        options.parentSessionKey,
+        undefined,
+        { graceTurns: options.graceTurns, stallAfterMs: options.stallAfterMs, stallKillAfterMs: options.stallKillAfterMs },
+      );
+      options.onRunnerCreated?.(index, runner);
+      result = await runner.run(attemptSpec, options.signal);
+      if (priorUsage) result.usage = addUsage(priorUsage, result.usage);
+
+      const canRetry = attempt < maxAttempts && !options.signal?.aborted && isTransientFailure(result);
+      if (!canRetry) break;
+      priorUsage = result.usage;
+      const nextModel = fallbacks[attempt - 1];
+      options.onTaskProgress?.(index, {
+        state: "queued",
+        model: nextModel ?? spec.model,
+        attempts: attempt + 1,
+        liveText: `Attempt ${attempt} ${result.stopReason ?? result.state}; retrying${nextModel ? ` on ${nextModel}` : ""}…`,
+      });
+    }
+
+    if (attemptedModels.length > 1) {
+      result.attempts = attemptedModels.length;
+      result.attemptedModels = attemptedModels;
+      if (result.errorMessage && (result.state === "failed" || result.state === "timeout")) {
+        result.errorMessage += ` (after ${attemptedModels.length} attempts: ${attemptedModels.join(" → ")})`;
+      }
+    }
+    result.index = index;
+    result.label = spec.label || `task-${index + 1}`;
+    result.outputMode = spec.outputMode;
+
+    try {
+      await writeArtifact(spec, result);
+    } catch (error: any) {
+      result.errorMessage = `${result.errorMessage ? `${result.errorMessage}; ` : ""}Artifact write failed: ${error?.message ?? error}`;
+      if (result.state === "completed") result.state = "partial";
+    }
+
+    const handle = handles[index];
+    if (handle) {
+      try {
+        // Finalize even on cancellation: it either preserves changed work or
+        // removes an unchanged worktree, and both are quick local git calls.
+        const final = await worktrees.finalize(handle);
+        if (final.changed) {
+          result.worktree = {
+            cwd: final.cwd,
+            branch: final.branch,
+            baseCommit: final.baseCommit,
+            changed: true,
+            diffSummary: final.diffSummary,
+          };
+        }
+      } catch (error: any) {
+        result.errorMessage = `${result.errorMessage ? `${result.errorMessage}; ` : ""}Worktree finalization failed: ${error?.message ?? error}`;
+        if (result.state === "completed") result.state = "partial";
+      }
+    }
+    return result;
+  };
+
+  const results = await Promise.all(prepared.map((_, index) => runOne(index)));
+  return {
+    mode: results.length > 1 ? "parallel" : "single",
+    results,
+    state: aggregateState(results),
+    summary: summarize(results),
+  };
+}

package/src/output.ts

@@ -0,0 +1,124 @@
+import { Buffer } from "node:buffer";
+import type { SubagentConfig } from "./config.js";
+import type { OutputMode, RunSnapshot, TaskResult } from "./types.js";
+
+export interface CappedDelivery {
+  text: string;
+  cappedResults: Array<Record<string, unknown>>;
+  totalBytes: number;
+  totalLines: number;
+}
+
+function finalAssistantText(messages: any[]): string | undefined {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
+    const text = message.content
+      .filter((part: any) => part?.type === "text" && typeof part.text === "string")
+      .map((part: any) => part.text)
+      .join("");
+    if (text) return text;
+  }
+  return undefined;
+}
+
+/** Truncate a string to UTF-8 bytes without splitting a code point. */
+function utf8Prefix(value: string, maxBytes: number): string {
+  if (maxBytes <= 0) return "";
+  const buffer = Buffer.from(value, "utf8");
+  if (buffer.length <= maxBytes) return value;
+  let end = maxBytes;
+  while (end > 0 && (buffer[end] & 0xc0) === 0x80) end--;
+  return buffer.subarray(0, end).toString("utf8");
+}
+
+function enforceBudget(value: string, maxBytes: number, maxLines: number, marker: string): string {
+  const safeLines = Math.max(1, maxLines);
+  let text = value.split("\n").slice(0, safeLines).join("\n");
+  const wasLineCapped = value.split("\n").length > safeLines;
+  const wasByteCapped = Buffer.byteLength(text, "utf8") > maxBytes;
+  if (!wasLineCapped && !wasByteCapped) return text;
+
+  const markerLines = marker.split("\n").length;
+  const contentLineBudget = Math.max(0, safeLines - markerLines);
+  text = text.split("\n").slice(0, contentLineBudget).join("\n");
+  const separator = text ? "\n" : "";
+  const reserved = Buffer.byteLength(separator + marker, "utf8");
+  text = utf8Prefix(text, Math.max(0, maxBytes - reserved));
+  return `${text}${text ? separator : ""}${marker}`;
+}
+
+export class OutputManager {
+  constructor(private readonly config: SubagentConfig) {}
+
+  makeStatusPreview(run: RunSnapshot, maxBytes = 200): string {
+    const base = `${run.id} [${run.state}] ${run.mode} (${run.results.length} tasks)`;
+    return utf8Prefix(base, maxBytes);
+  }
+
+  capOutputForDelivery(
+    results: TaskResult[] | RunSnapshot["results"],
+    isMultiWait = false,
+    requestedOutputMode?: OutputMode,
+  ): CappedDelivery {
+    const count = Math.max(1, results.length);
+    const sections: string[] = [];
+    const cappedResults: Array<Record<string, unknown>> = [];
+    const separator = "\n\n---\n\n";
+    const headerBytes = isMultiWait
+      ? results.reduce((sum, _, i) => sum + Buffer.byteLength(`## Run section ${i + 1}\n\n`, "utf8"), 0)
+      : 0;
+    const separatorBytes = Math.max(0, count - 1) * Buffer.byteLength(separator, "utf8");
+    const separatorLines = Math.max(0, count - 1) * 4;
+    const availableBytes = Math.max(0, this.config.maxResultBytes - headerBytes - separatorBytes);
+    const availableLines = Math.max(1, this.config.maxResultLines - separatorLines - (isMultiWait ? count * 2 : 0));
+    const perBytes = Math.max(1, Math.floor(availableBytes / count));
+    const perLines = Math.max(1, Math.floor(availableLines / count));
+
+    results.forEach((result: any, index) => {
+      const mode = requestedOutputMode ?? result.outputMode;
+      let raw: string;
+      if (mode === "file-only") {
+        raw = result.outputFile
+          ? `Output written to ${result.outputFile}${result.sessionId ? `\nSession: ${result.sessionId}` : ""}`
+          : result.errorMessage || "file-only output requested, but no artifact was produced";
+      } else if (result.structuredOutput !== undefined) {
+        // Validated structured result: deliver the machine-readable JSON, not
+        // the narrative preamble around the fenced block.
+        raw = JSON.stringify(result.structuredOutput, null, 2);
+      } else {
+        raw = result.finalOutput || finalAssistantText(result.messages || []) || result.liveText || result.errorMessage || result.stderr || "(no output)";
+      }
+      const artifact = result.outputFile ? ` Full output: ${result.outputFile}` : " Full output is in the child session transcript.";
+      const marker = `[Truncated.${artifact}]`;
+      const section = enforceBudget(raw, perBytes, perLines, marker);
+      const prefix = isMultiWait ? `## Run section ${index + 1}\n\n` : "";
+      sections.push(prefix + section);
+      cappedResults.push({
+        ...result,
+        finalOutput: section,
+        capped: section !== raw,
+        bytes: Buffer.byteLength(section, "utf8"),
+      });
+    });
+
+    let text = sections.join(separator);
+    // Defensive final enforcement includes the global marker inside both limits.
+    text = enforceBudget(
+      text,
+      this.config.maxResultBytes,
+      this.config.maxResultLines,
+      "[Global output cap reached. Full output remains in artifacts or child sessions.]",
+    ).trim();
+    return {
+      text,
+      cappedResults,
+      totalBytes: Buffer.byteLength(text, "utf8"),
+      totalLines: text ? text.split("\n").length : 0,
+    };
+  }
+
+  testUnicodeBytes(value: string): { bytes: number; lines: number } {
+    return { bytes: Buffer.byteLength(value, "utf8"), lines: value.split("\n").length };
+  }
+}