pi-workflow-engine 0.12.0 → 1.0.0

package/.pi/extensions/pi-workflow-engine/src/options.ts

@@ -56,9 +56,9 @@ export function resolveWorkflowRunOptions(
   input: WorkflowRunOptions = {},
   env: Record<string, string | undefined> = process.env,
 ): ResolvedWorkflowRunOptions {
-  const concurrency = clampInteger(input.concurrency ?? parseInteger(env.PI_WORKFLOW_CONCURRENCY), 1, 64, defaultConcurrency());
+  const concurrency = clampInteger(input.concurrency ?? parseWorkflowIntegerString(env.PI_WORKFLOW_CONCURRENCY), 1, 64, defaultConcurrency());
   const parallelSubmissionLimit = optionalClampedInteger(
-    input.parallelSubmissionLimit ?? parseInteger(env.PI_WORKFLOW_PARALLEL_SUBMISSION_LIMIT),
+    input.parallelSubmissionLimit ?? parseWorkflowIntegerString(env.PI_WORKFLOW_PARALLEL_SUBMISSION_LIMIT),
     1,
     10_000,
   );
@@ -80,7 +80,7 @@ export function resolveWorkflowRunOptions(
     WORKFLOW_AGENT_RETRIES_MAX,
     DEFAULT_WORKFLOW_AGENT_RETRIES,
   );
-  const budget = resolveBudget(input.budget, env.PI_WORKFLOW_BUDGET);
+  const budget = input.budget !== undefined ? normalizeExplicitBudget(input.budget) : parseWorkflowBudgetString(env.PI_WORKFLOW_BUDGET);
   const usageLimitMaxAttempts = clampInteger(
     input.usageLimitMaxAttempts ?? parseWorkflowIntegerString(env.PI_WORKFLOW_USAGE_LIMIT_MAX_ATTEMPTS),
     WORKFLOW_USAGE_LIMIT_ATTEMPTS_MIN,
@@ -129,23 +129,12 @@ function clampInteger(value: number | undefined, min: number, max: number, fallb
   return Math.min(max, Math.max(min, Math.trunc(value)));
 }
 
-function parseInteger(value: string | undefined): number | undefined {
-  if (value === undefined || value.trim() === "") return undefined;
-  const parsed = Number(value);
-  return Number.isFinite(parsed) ? Math.trunc(parsed) : undefined;
-}
-
 export function parseWorkflowIntegerString(value: string | undefined): number | undefined {
   if (value === undefined || value.trim() === "") return undefined;
   const parsed = Number(value);
   return Number.isSafeInteger(parsed) ? parsed : undefined;
 }
 
-function resolveBudget(inputBudget: number | undefined, envBudget: string | undefined): number | undefined {
-  if (inputBudget !== undefined) return normalizeExplicitBudget(inputBudget);
-  return envBudget === undefined ? undefined : parseWorkflowBudgetString(envBudget);
-}
-
 function normalizeExplicitBudget(value: number): number {
   if (!Number.isFinite(value) || !Number.isInteger(value) || value < WORKFLOW_BUDGET_MIN || value > WORKFLOW_BUDGET_MAX) {
     throw new RangeError(`Workflow budget must be an integer between ${WORKFLOW_BUDGET_MIN} and ${WORKFLOW_BUDGET_MAX}.`);
@@ -153,10 +142,102 @@ function normalizeExplicitBudget(value: number): number {
   return value;
 }
 
-export function parseWorkflowBudgetString(value: string): number | undefined {
-  const trimmed = value.trim();
+export function parseWorkflowBudgetString(value: string | undefined): number | undefined {
+  const trimmed = value?.trim() ?? "";
   if (!/^\d+$/.test(trimmed)) return undefined;
   const parsed = Number(trimmed);
   if (!Number.isSafeInteger(parsed) || parsed < WORKFLOW_BUDGET_MIN || parsed > WORKFLOW_BUDGET_MAX) return undefined;
   return parsed;
 }
+
+function parseRunIdString(value: string | undefined): string | undefined {
+  return value === undefined || value === "" || value.startsWith("--") ? undefined : value;
+}
+
+/** A `/workflow <name> [flags] [args]` command line with its flags lifted into run options. */
+export interface WorkflowInvocation {
+  readonly name: string;
+  readonly args: string;
+  readonly options: WorkflowRunOptions;
+  readonly refreshDiscovery: boolean;
+  readonly optionErrors: readonly string[];
+}
+
+type WorkflowValueOptions = Pick<
+  WorkflowRunOptions,
+  "concurrency" | "parallelSubmissionLimit" | "maxAgents" | "agentTimeoutMs" | "agentRetries" | "budget" | "resumeFromRunId"
+>;
+
+interface WorkflowValueFlag<K extends keyof WorkflowValueOptions> {
+  readonly flag: string;
+  readonly key: K;
+  readonly parse: (value: string | undefined) => WorkflowValueOptions[K] | undefined;
+  readonly error: string;
+}
+
+type AnyWorkflowValueFlag = { [K in keyof WorkflowValueOptions]-?: WorkflowValueFlag<K> }[keyof WorkflowValueOptions];
+
+/** `--flag=V` or `--flag V`; the next token is consumed only when it parses, so a following flag or argument survives. */
+const WORKFLOW_VALUE_FLAGS: readonly AnyWorkflowValueFlag[] = [
+  { flag: "--concurrency", key: "concurrency", parse: parseWorkflowIntegerString, error: "--concurrency requires an integer" },
+  { flag: "--parallel-limit", key: "parallelSubmissionLimit", parse: parseWorkflowIntegerString, error: "--parallel-limit requires an integer" },
+  { flag: "--max-agents", key: "maxAgents", parse: parseWorkflowIntegerString, error: "--max-agents requires an integer" },
+  { flag: "--agent-timeout-ms", key: "agentTimeoutMs", parse: parseWorkflowIntegerString, error: "--agent-timeout-ms requires an integer" },
+  { flag: "--agent-retries", key: "agentRetries", parse: parseWorkflowIntegerString, error: "--agent-retries requires an integer" },
+  { flag: "--budget", key: "budget", parse: parseWorkflowBudgetString, error: "--budget requires a positive integer output-token count" },
+  { flag: "--resume", key: "resumeFromRunId", parse: parseRunIdString, error: "--resume requires a workflow run id" },
+];
+
+const WORKFLOW_SWITCH_FLAGS = new Map<string, Partial<WorkflowRunOptions>>([
+  ["--inspect", { inspect: true }],
+  ["--perf", { perf: true }],
+  ["--resume-edited", { resumeEditedWorkflow: true }],
+  ["--result-viewer", { resultViewer: "open" }],
+  ["--review-viewer", { resultViewer: "open" }],
+  ["--no-result-viewer", { resultViewer: "skip" }],
+  ["--no-review-viewer", { resultViewer: "skip" }],
+]);
+
+export function parseWorkflowInvocation(input: string): WorkflowInvocation {
+  const [name = "", ...tokens] = input.split(/\s+/).filter(Boolean);
+  const kept: string[] = [];
+  const options: WorkflowRunOptions = {};
+  const optionErrors: string[] = [];
+  let refreshDiscovery = false;
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token === "--refresh") {
+      refreshDiscovery = true;
+      continue;
+    }
+    const switched = WORKFLOW_SWITCH_FLAGS.get(token);
+    if (switched) {
+      Object.assign(options, switched);
+      continue;
+    }
+    const valueFlag = WORKFLOW_VALUE_FLAGS.find(({ flag }) => token === flag || token.startsWith(`${flag}=`));
+    if (!valueFlag) {
+      kept.push(token);
+      continue;
+    }
+    const inline = token !== valueFlag.flag;
+    if (applyValueFlag(options, valueFlag, inline ? token.slice(valueFlag.flag.length + 1) : tokens[i + 1])) {
+      if (!inline) i++;
+    } else {
+      optionErrors.push(valueFlag.error);
+    }
+  }
+  if (options.resumeEditedWorkflow && !options.resumeFromRunId) optionErrors.push("--resume-edited requires --resume <run-id>");
+  return { name, args: kept.join(" "), options, refreshDiscovery, optionErrors };
+}
+
+function applyValueFlag<K extends keyof WorkflowValueOptions>(
+  options: WorkflowValueOptions,
+  valueFlag: WorkflowValueFlag<K>,
+  value: string | undefined,
+): boolean {
+  const parsed = valueFlag.parse(value);
+  if (parsed === undefined) return false;
+  options[valueFlag.key] = parsed;
+  return true;
+}

package/.pi/extensions/pi-workflow-engine/src/perf.ts

@@ -1,14 +1,5 @@
 import { performance } from "node:perf_hooks";
 
-export type PerfTags = Record<string, string | number>;
-
-export interface PerfSample {
-  readonly name: string;
-  readonly durationMs?: number;
-  readonly value?: number;
-  readonly tags?: PerfTags;
-}
-
 export interface PerfAggregate {
   readonly name: string;
   readonly count: number;
@@ -22,118 +13,98 @@ export interface PerfAggregate {
 
 export interface PerfSnapshot {
   readonly enabled: boolean;
-  readonly startedAt: number;
-  readonly samples: readonly PerfSample[];
   readonly aggregates: readonly PerfAggregate[];
 }
 
 export interface PerfSink {
-  time<T>(name: string, fn: () => Promise<T>, tags?: PerfTags): Promise<T>;
-  timeSync<T>(name: string, fn: () => T, tags?: PerfTags): T;
-  observe(name: string, value: number, tags?: PerfTags): void;
-  counter(name: string, delta?: number, tags?: PerfTags): void;
+  time<T>(name: string, fn: () => Promise<T>): Promise<T>;
+  timeSync<T>(name: string, fn: () => T): T;
+  observe(name: string, value: number): void;
+  counter(name: string, delta?: number): void;
   snapshot(): PerfSnapshot;
 }
 
 export class PerfRecorder implements PerfSink {
-  private readonly samples: PerfSample[] = [];
-
-  constructor(private readonly startedAt = Date.now()) {}
+  /** Finite observed values per metric, in first-observation order. */
+  private readonly values = new Map<string, number[]>();
 
-  async time<T>(name: string, fn: () => Promise<T>, tags?: PerfTags): Promise<T> {
+  async time<T>(name: string, fn: () => Promise<T>): Promise<T> {
     const start = performance.now();
     try {
       return await fn();
     } finally {
-      this.observeDuration(name, performance.now() - start, tags);
+      this.observe(name, performance.now() - start);
     }
   }
 
-  timeSync<T>(name: string, fn: () => T, tags?: PerfTags): T {
+  timeSync<T>(name: string, fn: () => T): T {
     const start = performance.now();
     try {
       return fn();
     } finally {
-      this.observeDuration(name, performance.now() - start, tags);
+      this.observe(name, performance.now() - start);
     }
   }
 
-  observe(name: string, value: number, tags?: PerfTags): void {
+  observe(name: string, value: number): void {
     if (!Number.isFinite(value)) return;
-    this.samples.push({ name, value, tags });
+    const values = this.values.get(name);
+    if (values) values.push(value);
+    else this.values.set(name, [value]);
   }
 
-  counter(name: string, delta = 1, tags?: PerfTags): void {
-    this.observe(name, delta, tags);
+  counter(name: string, delta = 1): void {
+    this.observe(name, delta);
   }
 
   snapshot(): PerfSnapshot {
-    return {
-      enabled: true,
-      startedAt: this.startedAt,
-      samples: this.samples.map((sample) => ({ ...sample, tags: sample.tags ? { ...sample.tags } : undefined })),
-      aggregates: aggregateSamples(this.samples),
-    };
-  }
-
-  private observeDuration(name: string, durationMs: number, tags?: PerfTags): void {
-    if (!Number.isFinite(durationMs)) return;
-    this.samples.push({ name, durationMs, tags });
+    return { enabled: true, aggregates: [...this.values].map(([name, values]) => aggregate(name, values)) };
   }
 }
 
 export class NoopPerfRecorder implements PerfSink {
-  constructor(private readonly startedAt = Date.now()) {}
-
-  async time<T>(_name: string, fn: () => Promise<T>, _tags?: PerfTags): Promise<T> {
+  async time<T>(_name: string, fn: () => Promise<T>): Promise<T> {
     return await fn();
   }
 
-  timeSync<T>(_name: string, fn: () => T, _tags?: PerfTags): T {
+  timeSync<T>(_name: string, fn: () => T): T {
     return fn();
   }
 
-  observe(_name: string, _value: number, _tags?: PerfTags): void {}
+  observe(): void {}
 
-  counter(_name: string, _delta?: number, _tags?: PerfTags): void {}
+  counter(): void {}
 
   snapshot(): PerfSnapshot {
-    return { enabled: false, startedAt: this.startedAt, samples: [], aggregates: [] };
+    return { enabled: false, aggregates: [] };
   }
 }
 
-export function createPerfRecorder(enabled: boolean, startedAt?: number): PerfSink {
-  return enabled ? new PerfRecorder(startedAt) : new NoopPerfRecorder(startedAt);
+export function createPerfRecorder(enabled: boolean): PerfSink {
+  return enabled ? new PerfRecorder() : new NoopPerfRecorder();
 }
 
-function aggregateSamples(samples: readonly PerfSample[]): PerfAggregate[] {
-  const byName = new Map<string, number[]>();
-  for (const sample of samples) {
-    const value = sample.durationMs ?? sample.value;
-    if (value === undefined || !Number.isFinite(value)) continue;
-    const values = byName.get(sample.name) ?? [];
-    values.push(value);
-    byName.set(sample.name, values);
-  }
+export function formatPerfSummary(aggregates: readonly PerfAggregate[]): string {
+  const parts = aggregates.slice(0, 4).map((aggregate) => `${aggregate.name} ${Math.round(aggregate.total)}ms`);
+  return parts.length > 0 ? `Perf: ${parts.join(" · ")}` : "Perf: no samples";
+}
 
-  return [...byName.entries()].map(([name, rawValues]) => {
-    const values = [...rawValues].sort((a, b) => a - b);
-    const total = values.reduce((sum, value) => sum + value, 0);
-    return {
-      name,
-      count: values.length,
-      total,
-      min: values[0] ?? 0,
-      max: values[values.length - 1] ?? 0,
-      mean: values.length === 0 ? 0 : total / values.length,
-      p50: percentile(values, 0.5),
-      p95: percentile(values, 0.95),
-    };
-  });
+/** `observed` is never empty: a metric is recorded with its first value. */
+function aggregate(name: string, observed: readonly number[]): PerfAggregate {
+  const values = [...observed].sort((a, b) => a - b);
+  const total = values.reduce((sum, value) => sum + value, 0);
+  return {
+    name,
+    count: values.length,
+    total,
+    min: values[0],
+    max: values[values.length - 1],
+    mean: total / values.length,
+    p50: percentile(values, 0.5),
+    p95: percentile(values, 0.95),
+  };
 }
 
 function percentile(sortedValues: readonly number[], p: number): number {
-  if (sortedValues.length === 0) return 0;
-  const index = Math.min(sortedValues.length - 1, Math.max(0, Math.ceil(sortedValues.length * p) - 1));
-  return sortedValues[index] ?? 0;
+  return sortedValues[Math.ceil(sortedValues.length * p) - 1];
 }

package/.pi/extensions/pi-workflow-engine/src/process-runner.ts

@@ -1,5 +1,6 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { performance } from "node:perf_hooks";
+import { StringDecoder } from "node:string_decoder";
 import { unknownErrorMessage } from "./unknown-error.ts";
 
 export interface BoundedProcessOptions {
@@ -102,6 +103,13 @@ export async function runBoundedProcess(
   let stdout = "";
   let stderr = "";
   let bytes = 0;
+  // Pipe chunks can split a multi-byte UTF-8 sequence; streaming decoders carry the tail forward.
+  const stdoutDecoder = new StringDecoder("utf8");
+  const stderrDecoder = new StringDecoder("utf8");
+  const flushDecoders = () => {
+    stdout += stdoutDecoder.end();
+    stderr += stderrDecoder.end();
+  };
   let pendingFailure: BoundedProcessFailure | undefined;
   const child = spawn(options.file, [...options.args], {
     cwd: options.cwd,
@@ -127,6 +135,7 @@ export async function runBoundedProcess(
       if (settled) return;
       settled = true;
       cleanup();
+      flushDecoders();
       const base = { stdout, stderr, durationMs: performance.now() - start, bytes };
       if (!failure) {
         resolve({ ...base, ok: true });
@@ -216,7 +225,7 @@ export async function runBoundedProcess(
     const onAbort = () => terminate({ kind: "abort", message: options.abortError });
     const timeout = setTimeout(() => terminate({ kind: "timeout", message: options.timeoutError }), options.timeoutMs);
 
-    const captureChunk = (chunk: Buffer, append: (text: string) => void) => {
+    const captureChunk = (chunk: Buffer, decoder: StringDecoder, append: (text: string) => void) => {
       if (pendingFailure) return;
       bytes += chunk.length;
       if (options.maxBufferBytes !== undefined && bytes > options.maxBufferBytes) {
@@ -226,10 +235,10 @@ export async function runBoundedProcess(
         });
         return;
       }
-      append(chunk.toString("utf8"));
+      append(decoder.write(chunk));
     };
-    child.stdout?.on("data", (chunk: Buffer) => captureChunk(chunk, (text) => (stdout += text)));
-    child.stderr?.on("data", (chunk: Buffer) => captureChunk(chunk, (text) => (stderr += text)));
+    child.stdout?.on("data", (chunk: Buffer) => captureChunk(chunk, stdoutDecoder, (text) => (stdout += text)));
+    child.stderr?.on("data", (chunk: Buffer) => captureChunk(chunk, stderrDecoder, (text) => (stderr += text)));
     child.on("error", (spawnError) => {
       if (!pendingFailure) finish({ kind: "spawn", message: spawnError.message });
     });
@@ -242,6 +251,7 @@ export async function runBoundedProcess(
         finish();
         return;
       }
+      flushDecoders();
       const message = options.exitError(stderr, code, signal);
       finish({ kind: "exit", message, code, signal });
     });

package/.pi/extensions/pi-workflow-engine/src/progress-types.ts

@@ -40,6 +40,8 @@ export interface WorkflowProgressSnapshot {
   readonly startedAt: number;
   readonly doneAt?: number;
   readonly currentPhase: string;
+  /** Phase titles the workflow declared in `meta.phases`; live surfaces list the ones not reached yet. */
+  readonly plannedPhases?: readonly string[];
   readonly phases: readonly PhaseSnapshot[];
   readonly counters: readonly WorkflowCounterSnapshot[];
   readonly summary: readonly [string, string | number][];

package/.pi/extensions/pi-workflow-engine/src/progress.ts

@@ -1,20 +1,16 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
 import type { WorkflowProgressEvent } from "./types.ts";
 import type { AgentRowStatus, WorkflowLaneItemStatus, WorkflowProgressSnapshot } from "./progress-types.ts";
-import { formatWorkflowUsageLine, type WorkflowUsageSnapshot } from "./usage.ts";
+import type { WorkflowUsageSnapshot } from "./usage.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 import { statusTextFromCounts, type WorkflowStatusCounts } from "./ui/workflow-format.ts";
-import { renderWorkflowWidgetLines } from "./ui/workflow-widget.ts";
-
-export type {
-  AgentRowSnapshot,
-  AgentRowStatus,
-  PhaseSnapshot,
-  WorkflowCounterSnapshot,
-  WorkflowLaneItemSnapshot,
-  WorkflowLaneItemStatus,
-  WorkflowProgressSnapshot,
-} from "./progress-types.ts";
+import {
+  renderBackgroundWorkflowLine,
+  renderWorkflowWidget,
+  STRING_WIDGET_WIDTH,
+  WidthAwareWidget,
+} from "./ui/workflow-widget.ts";
 
 interface AgentRow {
   id: number;
@@ -51,6 +47,16 @@ const LOG_LIMIT = 24;
 const WIDGET_REFRESH_INTERVAL_MS = 1_000;
 export const DEFAULT_LANE_ITEM_LIMIT = 200;
 
+export interface ProgressTrackerOptions {
+  /** Phase titles from the workflow's `meta.phases`, shown as upcoming until the run reaches them. */
+  readonly plannedPhases?: readonly string[];
+  /**
+   * `live` (default) draws the full progress widget and a footer status; `background` draws one
+   * summary line per run so a run the user sent to the background never takes over the screen.
+   */
+  readonly display?: "live" | "background";
+}
+
 /**
  * Tracks live workflow state for widgets, footer/status text, result renderers,
  * and headless stderr breadcrumbs.
@@ -73,14 +79,24 @@ export class ProgressTracker {
   private usageSnapshot: WorkflowUsageSnapshot | undefined;
   private widgetRefreshInterval: ReturnType<typeof setInterval> | undefined;
   private readonly surfaceKey: string;
+  private readonly plannedPhases: readonly string[] | undefined;
+  private readonly display: "live" | "background";
+  /** Latest published snapshot; the TUI widget renders it at whatever width the terminal has. */
+  private latest: WorkflowProgressSnapshot | undefined;
+  /** Set once the TUI has instantiated this run's widget component. */
+  private tui: Pick<TUI, "requestRender"> | undefined;
+  private widgetRegistered = false;
 
   constructor(
     private readonly ctx: ExtensionContext,
     private readonly title: string,
     private readonly runId: string,
     private readonly onSnapshot?: (snapshot: WorkflowProgressSnapshot) => void,
+    options: ProgressTrackerOptions = {},
   ) {
     this.surfaceKey = `workflow:${runId}`;
+    this.plannedPhases = options.plannedPhases?.length ? [...options.plannedPhases] : undefined;
+    this.display = options.display ?? "live";
     this.ensurePhase(this.currentPhase);
   }
 
@@ -152,29 +168,18 @@ export class ProgressTracker {
     return id;
   }
 
-  agentStart(phase: string | undefined, label: string, id?: number): void {
-    const row = id === undefined ? undefined : this.findRowById(id);
+  agentStart(id: number): void {
+    const row = this.rowsById.get(id);
     if (row) {
       this.transitionAgentStatus(row, "running");
       row.startedAt = Date.now();
       row.error = undefined;
-    } else {
-      const nextRow = {
-        label,
-        id: this.nextAgentId++,
-        status: "running" as const,
-        startedAt: Date.now(),
-        toolUses: 0,
-      };
-      this.ensurePhase(phase ?? this.currentPhase).agents.push(nextRow);
-      this.rowsById.set(nextRow.id, nextRow);
-      this.agentCounts.running++;
     }
     this.publish();
   }
 
-  agentTool(label: string, tool: string, id?: number): void {
-    const row = this.findRow(label, id);
+  agentTool(id: number, tool: string): void {
+    const row = this.rowsById.get(id);
     if (row) {
       row.lastTool = tool;
       row.toolUses += 1;
@@ -182,8 +187,8 @@ export class ProgressTracker {
     this.publish();
   }
 
-  agentDone(label: string, id?: number): void {
-    const row = this.findRow(label, id);
+  agentDone(id: number): void {
+    const row = this.rowsById.get(id);
     if (row && row.status !== "failed") {
       this.transitionAgentStatus(row, "done");
       row.doneAt = Date.now();
@@ -191,8 +196,8 @@ export class ProgressTracker {
     this.publish();
   }
 
-  agentFailed(label: string, error: unknown, id?: number): void {
-    const row = this.findRow(label, id);
+  agentFailed(id: number, error: unknown): void {
+    const row = this.rowsById.get(id);
     if (row) {
       this.transitionAgentStatus(row, "failed");
       row.doneAt = Date.now();
@@ -213,6 +218,7 @@ export class ProgressTracker {
       startedAt: this.startedAt,
       doneAt: this.doneAt,
       currentPhase: this.currentPhase,
+      plannedPhases: this.plannedPhases,
       phases: this.phases.map((phase) => ({
         title: phase.title,
         agents: phase.agents.map((agent) => ({ ...agent })),
@@ -227,10 +233,6 @@ export class ProgressTracker {
   }
 
   statusCounts(): WorkflowStatusCounts {
-    return this.statusCountsSnapshot();
-  }
-
-  private statusCountsSnapshot(): WorkflowStatusCounts {
     return {
       queued: this.agentCounts.queued,
       running: this.agentCounts.running,
@@ -248,51 +250,59 @@ export class ProgressTracker {
   }
 
   private pruneLane(laneName: string, lane: WorkflowLaneItem[]): void {
-    if (this.laneItemLimit <= 0) return;
     while (lane.length > this.laneItemLimit) {
       lane.shift();
       this.laneOverflow.set(laneName, (this.laneOverflow.get(laneName) ?? 0) + 1);
     }
   }
 
-  private findRow(label: string, id?: number): AgentRow | undefined {
-    if (id !== undefined) return this.findRowById(id);
-    for (let i = this.phases.length - 1; i >= 0; i--) {
-      const running = this.phases[i].agents.find(
-        (agent) => agent.label === label && (agent.status === "running" || agent.status === "queued"),
-      );
-      if (running) return running;
-    }
-    for (let i = this.phases.length - 1; i >= 0; i--) {
-      const matching = this.phases[i].agents.find((agent) => agent.label === label);
-      if (matching) return matching;
-    }
-    return undefined;
-  }
-
-  private findRowById(id: number): AgentRow | undefined {
-    return this.rowsById.get(id);
-  }
-
   private publish(): void {
-    this.publishSnapshot();
-    if (!this.ctx.hasUI) return;
-    this.publishWidget();
+    const snapshot = this.snapshot();
+    this.onSnapshot?.(snapshot);
+    // Agents that outlive a fatal drain still report after done(); record them without reviving live surfaces.
+    if (!this.ctx.hasUI || this.doneAt !== undefined) return;
+    this.latest = snapshot;
+    this.publishWidget(snapshot);
     this.startWidgetRefresh();
-    this.publishStatus();
+    this.publishStatus(snapshot);
   }
 
-  private publishWidget(): void {
+  /**
+   * In the TUI the widget is a width-aware component registered once and redrawn on demand; surfaces
+   * that only take strings (RPC) get lines pre-rendered at a nominal width on every publish.
+   */
+  private publishWidget(snapshot: WorkflowProgressSnapshot): void {
+    if (this.ctx.mode !== "tui") {
+      this.ctx.ui.setWidget(this.surfaceKey, this.renderWidget(snapshot, STRING_WIDGET_WIDTH, this.ctx.ui.theme), { placement: "aboveEditor" });
+      return;
+    }
+    if (this.widgetRegistered) {
+      this.tui?.requestRender();
+      return;
+    }
+    this.widgetRegistered = true;
     this.ctx.ui.setWidget(
       this.surfaceKey,
-      renderWorkflowWidgetLines(this.snapshot(), this.ctx.ui.theme),
+      (tui, theme) => {
+        this.tui = tui;
+        return new WidthAwareWidget((width) => (this.latest ? this.renderWidget(this.latest, width, theme) : []));
+      },
       { placement: "aboveEditor" },
     );
   }
 
+  private renderWidget(snapshot: WorkflowProgressSnapshot, width: number, theme: ExtensionContext["ui"]["theme"]): string[] {
+    return this.display === "background" ? renderBackgroundWorkflowLine(snapshot, width, theme) : renderWorkflowWidget(snapshot, width, theme);
+  }
+
+  /** Elapsed time ticks even when no agent reports, so redraw the widget and status once a second. */
   private startWidgetRefresh(): void {
     if (this.widgetRefreshInterval !== undefined) return;
-    this.widgetRefreshInterval = setInterval(() => this.publishWidget(), WIDGET_REFRESH_INTERVAL_MS);
+    this.widgetRefreshInterval = setInterval(() => {
+      if (!this.latest) return;
+      this.publishWidget(this.latest);
+      this.publishStatus(this.latest);
+    }, WIDGET_REFRESH_INTERVAL_MS);
   }
 
   private stopWidgetRefresh(): void {
@@ -301,19 +311,10 @@ export class ProgressTracker {
     this.widgetRefreshInterval = undefined;
   }
 
-  private publishStatus(): void {
-    const status = statusTextFromCounts(
-      {
-        title: this.title,
-        doneAt: this.doneAt,
-        currentPhase: this.currentPhase,
-        counters: [...this.counters.values()].map((counter) => ({ ...counter })),
-      },
-      this.statusCountsSnapshot(),
-      this.ctx.ui.theme,
-    );
-    const usage = formatWorkflowUsageLine(this.usageSnapshot);
-    const next = usage ? `${status} · ${usage}` : status;
+  /** Background runs are summarised by their widget line alone. */
+  private publishStatus(snapshot: WorkflowProgressSnapshot): void {
+    if (this.display === "background") return;
+    const next = statusTextFromCounts(snapshot, this.statusCounts(), this.ctx.ui.theme);
     if (next === this.lastStatusText) return;
     this.ctx.ui.setStatus(this.surfaceKey, next);
     this.lastStatusText = next;
@@ -323,15 +324,13 @@ export class ProgressTracker {
   done(): void {
     this.doneAt = Date.now();
     this.stopWidgetRefresh();
-    this.publishSnapshot();
+    this.onSnapshot?.(this.snapshot());
     if (!this.ctx.hasUI) return;
     this.ctx.ui.setWidget(this.surfaceKey, undefined);
     this.ctx.ui.setStatus(this.surfaceKey, undefined);
     this.lastStatusText = undefined;
-  }
-
-  private publishSnapshot(): void {
-    this.onSnapshot?.(this.snapshot());
+    this.latest = undefined;
+    this.tui = undefined;
   }
 }