@signalridge/pi-workflows 1.6.0 → 1.7.1

package/src/engine.ts

@@ -66,6 +66,9 @@ import type { WorkflowStrengthTable } from "./strengths.js";
 export const MAX_ATTEMPTS_PER_NODE = 3;
 
 const BRANCH_QUIESCE_TIMEOUT_MS = 8_000;
+// Internal deadline, longer than exact-owner RPC cleanup. Scripts can await
+// arbitrary promises, so cancellation cannot rely on cooperative JS unwinding.
+export const EXECUTION_DRAIN_TIMEOUT_MS = 10_000;
 const MAX_WAITERS = 256;
 const JOURNAL_RETRY_INITIAL_DELAY_MS = 25;
 const JOURNAL_RETRY_MAX_DELAY_MS = 2_000;
@@ -116,6 +119,7 @@ export interface ScriptStartOptions {
       choices?: string[];
       timeoutMs?: number;
     },
+    signal?: AbortSignal,
   ) => Promise<unknown>;
   /** Resolve a nested `workflow(name)` reference to the script it names. */
   loadSavedWorkflow?: (name: string) => string | undefined;
@@ -136,12 +140,32 @@ interface AgentLifecycleWaiter {
   generation: number;
   onUsage?: (usage: AgentUsage) => void;
   onHistory?: (history: unknown[]) => void;
+  /** Told once when the host reports this agent left the queue and started. */
+  onRunning?: () => void;
+  startedNotified: boolean;
   executionGeneration: number;
   resolve: (response: ManagedSpawnResponse) => void;
   reject: (error: unknown) => void;
   settled: boolean;
 }
 
+/**
+ * Tell a waiter once that its agent started.
+ *
+ * Once, because the wall clock is restarted from this point: a repeated report
+ * — a duplicate event, or a reply that raced its own lifecycle event — would
+ * keep pushing the deadline out and quietly turn the timeout off.
+ */
+function notifyAgentRunning(waiter: AgentLifecycleWaiter): void {
+  if (waiter.startedNotified || waiter.settled) return;
+  waiter.startedNotified = true;
+  try {
+    waiter.onRunning?.();
+  } catch {
+    /* the clock is best effort; never fail a live agent over it */
+  }
+}
+
 interface AgentTerminalDelivery {
   response: ManagedSpawnResponse;
   usage?: AgentUsage;
@@ -432,6 +456,10 @@ export class WorkflowEngine {
     if (updateCallTierIdentity(state, callNodeId, data.tier)) {
       this.persistCallTierIdentity(state, callNodeId);
     }
+    // A start is the moment the host admitted this agent from its queue. It is
+    // the only signal that separates waiting for a slot from doing the work, so
+    // the call's wall clock is restarted here rather than at dispatch.
+    if (eventName === "subagents:started" && waiterMatches && waiter) notifyAgentRunning(waiter);
     // Created/started lifecycle facts carry managed identity before the RPC
     // reply is necessarily available. They are observation-only here; terminal
     // ownership is handled below once a completion/failure fact arrives.
@@ -730,6 +758,7 @@ export class WorkflowEngine {
     this.setWorkflowStatus(run, "running");
     state.executionGeneration += 1;
     state.execution = this.execute(runId, script, startOptions, undefined, state.executionGeneration, protocol);
+    const execution = state.execution;
     // A run-fatal abort/stop already journals its terminal state; never let a
     // leftover rejection become an unhandled promise rejection.
     void state.execution.catch(() => {});
@@ -747,6 +776,10 @@ export class WorkflowEngine {
       };
     } catch (error: unknown) {
       if (!(error instanceof WorkflowWaitAbortedError)) throw error;
+      // Foreground cancellation owns execution, not just this waiter. Do not
+      // advertise resumability until runtime children and checkpoint UI unwind.
+      state.controller.abort();
+      await this.drainExecution(state, execution);
       const current = this.runs.get(runId)?.run ?? run;
       return { runId: current.runId, status: current.status, background: false, waitAborted: true };
     }
@@ -771,6 +804,7 @@ export class WorkflowEngine {
     if (!state) return undefined;
     if (state.lifecycleSuspended) return undefined;
     const run = state.run;
+    if (run.status === "running" || run.status === "pausing" || run.status === "stopping") return undefined;
     const providerTimer = this.providerResumeTimers.get(runId);
     if (providerTimer) {
       clearTimeout(providerTimer);
@@ -838,13 +872,16 @@ export class WorkflowEngine {
       state.executionGeneration,
       protocol,
     );
-    void state.execution.catch(() => {});
+    const execution = state.execution;
+    void execution.catch(() => {});
     if (options.background) return { runId, status: run.status, background: true };
     try {
       const settled = await this.waitFor(runId, options.signal);
       return { runId, status: settled.status, background: false };
     } catch (error: unknown) {
       if (!(error instanceof WorkflowWaitAbortedError)) throw error;
+      state.controller.abort();
+      await this.drainExecution(state, execution);
       return { runId, status: run.status, background: false, waitAborted: true };
     }
   }
@@ -872,21 +909,7 @@ export class WorkflowEngine {
         // resumed from the journal. The script's in-flight agents are stopped by
         // the runtime's abort signal via the dispatch waiters.
         state.controller.abort();
-        this.persist(runId, "pause-recovery", () =>
-          this.write({
-            kind: "run_recovery",
-            schemaVersion: JOURNAL_SCHEMA_VERSION,
-            runId,
-            status: "interrupted",
-            branchGeneration: this.recoveryBranchGeneration,
-            rotations: [],
-            recoveryId: deriveRecoveryId({ runId, rotations: [], timestamp: Date.now() }),
-            timestamp: Date.now(),
-          }),
-        );
-        run.status = "interrupted";
-        run.updatedAt = Date.now();
-        this.settleWaiters(runId, run);
+        await this.drainExecution(state, state.execution);
       } else if (run.status !== "paused" && run.status !== "interrupted") {
         throw new Error(`cannot pause workflow in state ${run.status}`);
       }
@@ -993,11 +1016,34 @@ export class WorkflowEngine {
     const state = this.runs.get(runId);
     if (!state) throw new Error(`workflow run not found: ${runId}`);
     const generation = executionGeneration ?? state.executionGeneration;
+    const executionSignal =
+      !options.background && options.signal
+        ? AbortSignal.any([state.controller.signal, options.signal])
+        : state.controller.signal;
 
+    const cleanupTasks = new Set<Promise<void>>();
     const runner: WorkflowAgentRunner = {
       run: async (prompt: string, runOptions: AgentRunOptions = {}) => {
-        return this.dispatchAgent(runId, prompt, runOptions);
+        if (state.executionGeneration !== generation)
+          throw new WorkflowError("stale workflow execution", WorkflowErrorCode.WORKFLOW_ABORTED);
+        const dispatch = this.dispatchAgent(runId, prompt, runOptions);
+        const settled = dispatch.then(
+          () => {},
+          () => {},
+        );
+        const trackCleanup = () => {
+          cleanupTasks.add(settled);
+          void settled.then(() => cleanupTasks.delete(settled));
+        };
+        runOptions.signal?.addEventListener("abort", trackCleanup, { once: true });
+        if (runOptions.signal?.aborted) trackCleanup();
+        try {
+          return await dispatch;
+        } finally {
+          runOptions.signal?.removeEventListener("abort", trackCleanup);
+        }
       },
+      waitForCleanup: () => this.drainExecution(state, Promise.all([...cleanupTasks])),
     };
 
     try {
@@ -1010,12 +1056,16 @@ export class WorkflowEngine {
           : {
               routingPolicy: protocol.routingPolicy,
               routingPolicyFingerprint: protocol.routingPolicyFingerprint,
+              // Read live at each start and resume, never frozen onto the run:
+              // the pool is a host setting the user can change between them, and
+              // a run that outlived a narrowing would dispatch into a queue.
+              ...(protocol.maxConcurrent === undefined ? {} : { hostMaxConcurrent: protocol.maxConcurrent }),
             }),
         concurrency: options.concurrency,
         agentRetries: options.agentRetries,
         tokenBudget: options.tokenBudget,
         agentTimeoutMs: options.agentTimeoutMs,
-        signal: state.controller.signal,
+        signal: executionSignal,
         maxAgents: options.maxAgents,
         runId,
         executionNonce: `${generation}-${randomUUID()}`,
@@ -1050,6 +1100,12 @@ export class WorkflowEngine {
           }
         },
       });
+      await runner.waitForCleanup?.();
+      if (executionSignal.aborted) {
+        throw new WorkflowError("workflow execution aborted", WorkflowErrorCode.WORKFLOW_ABORTED, {
+          recoverable: true,
+        });
+      }
       const live = this.runs.get(runId);
       const run = live?.run;
       if (run && state.executionGeneration === generation && !isTerminalWorkflow(run.status)) {
@@ -1058,6 +1114,7 @@ export class WorkflowEngine {
       }
       return result;
     } catch (error: unknown) {
+      await runner.waitForCleanup?.();
       const run = this.runs.get(runId)?.run;
       if (run && state.executionGeneration === generation && !isTerminalWorkflow(run.status)) {
         const message = error instanceof Error ? error.message : String(error);
@@ -1066,8 +1123,21 @@ export class WorkflowEngine {
           this.setWorkflowStatus(run, "paused", message);
           this.cleanupAgents(runId);
           this.scheduleProviderResume(runId, workflowError.resetHint);
-        } else if (workflowError.code === WorkflowErrorCode.WORKFLOW_ABORTED && state.controller.signal.aborted) {
-          this.setWorkflowStatus(run, "interrupted");
+        } else if (workflowError.code === WorkflowErrorCode.WORKFLOW_ABORTED && executionSignal.aborted) {
+          this.persist(runId, "abort-recovery", () =>
+            this.write({
+              kind: "run_recovery",
+              schemaVersion: JOURNAL_SCHEMA_VERSION,
+              runId,
+              status: "interrupted",
+              branchGeneration: this.recoveryBranchGeneration,
+              rotations: [],
+              recoveryId: deriveRecoveryId({ runId, rotations: [], timestamp: Date.now() }),
+              timestamp: Date.now(),
+            }),
+          );
+          run.status = "interrupted";
+          run.updatedAt = Date.now();
         } else {
           this.setWorkflowStatus(run, "failed", message);
           this.cleanupAgents(runId);
@@ -1091,7 +1161,7 @@ export class WorkflowEngine {
     if (this.disposed) throw new WorkflowEngineDisposedError();
     const state = this.runs.get(runId);
     if (!state) throw new Error(`workflow run not found: ${runId}`);
-    if (state.lifecycleSuspended || state.controller.signal.aborted) {
+    if (state.lifecycleSuspended || state.controller.signal.aborted || runOptions.signal?.aborted) {
       throw new WorkflowError("workflow branch is quiescing", WorkflowErrorCode.WORKFLOW_ABORTED, {
         recoverable: true,
       });
@@ -1192,6 +1262,19 @@ export class WorkflowEngine {
     let response: ManagedSpawnResponse | string;
     try {
       response = await this.client.spawn(task, runId, spawnNodeId, spawnAttemptId, externalSignal);
+    } catch (error: unknown) {
+      if (externalSignal.aborted) {
+        const reconciled = await this.client.reconcileManaged?.(spawnKey, owner).catch(() => undefined);
+        const id = typeof reconciled === "string" ? reconciled : reconciled?.id;
+        await this.stopAndQuiesce(
+          state,
+          id ?? spawnKey,
+          owner,
+          executionGeneration,
+          id ? undefined : "cancelled spawn allocation could not be confirmed",
+        );
+      }
+      throw error;
     } finally {
       externalSignal.removeEventListener("abort", onPendingAbort);
       state.pendingSpawns.delete(spawnKey);
@@ -1203,9 +1286,7 @@ export class WorkflowEngine {
       externalSignal.aborted
     ) {
       state.bufferedTerminals.delete(spawnKey);
-      await this.client
-        .stopOwned?.(responseId, { extension: "pi-workflows", runId, nodeId: spawnNodeId, attemptId: spawnAttemptId })
-        .catch(() => {});
+      await this.stopAndQuiesce(state, responseId, owner, executionGeneration);
       throw new WorkflowError(
         "workflow dispatch became stale during pause/resume",
         WorkflowErrorCode.WORKFLOW_ABORTED,
@@ -1266,15 +1347,12 @@ export class WorkflowEngine {
         waiter.settled = true;
         state.agentWaiters.delete(pendingId);
         state.bufferedTerminals.delete(spawnKey);
-        void this.client
-          .stopOwned?.(pendingId, {
-            extension: "pi-workflows",
-            runId,
-            nodeId: spawnNodeId,
-            attemptId: spawnAttemptId,
-          })
-          .catch(() => {});
-        waiter.reject(new WorkflowError("workflow aborted", WorkflowErrorCode.WORKFLOW_ABORTED, { recoverable: true }));
+        // Stop acknowledges cancellation, not provider/tool finally completion.
+        void this.stopAndQuiesce(state, pendingId, owner, executionGeneration).then(() => {
+          waiter.reject(
+            new WorkflowError("workflow aborted", WorkflowErrorCode.WORKFLOW_ABORTED, { recoverable: true }),
+          );
+        });
       }
     };
 
@@ -1287,11 +1365,17 @@ export class WorkflowEngine {
         executionGeneration,
         onUsage: runOptions.onUsage,
         onHistory: runOptions.onHistory,
+        onRunning: runOptions.onRunning,
+        startedNotified: false,
         settled: false,
         resolve,
         reject,
       };
       state.agentWaiters.set(pendingId, waiter);
+      // A spawn that was admitted straight away is already running, and its
+      // `subagents:started` event fired before this waiter existed. Only a
+      // reply that says "queued" still has a start to wait for.
+      if (typeof response !== "string" && response.state !== "queued") notifyAgentRunning(waiter);
       externalSignal.addEventListener("abort", waitAbort, { once: true });
       if (externalSignal.aborted) {
         waitAbort();
@@ -1498,6 +1582,99 @@ export class WorkflowEngine {
     }
   }
 
+  private async stopAndQuiesce(
+    state: ScriptRunState,
+    agentId: string,
+    owner: WorkflowOwner,
+    executionGeneration: number,
+    unconfirmed?: string,
+  ): Promise<void> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let stopError: unknown;
+    try {
+      if (unconfirmed) throw new Error(unconfirmed);
+      await Promise.race([
+        (async () => {
+          try {
+            if (!this.client.stopOwned) throw new Error("owned stop RPC unavailable");
+            await this.client.stopOwned(agentId, owner);
+          } catch (error: unknown) {
+            // Reconciliation may already have stopped the record. Only exact-owner
+            // quiescence confirms that provider/tool cleanup has actually settled.
+            stopError = error;
+          }
+          if (!this.client.quiesceOwned) throw new Error("owned cleanup RPC unavailable");
+          const result = await this.client.quiesceOwned(owner.runId, [agentId], BRANCH_QUIESCE_TIMEOUT_MS, [owner]);
+          if (!result?.settled || result.pending.length !== 0) throw new Error("owned agents are not quiescent");
+        })(),
+        new Promise<never>((_resolve, reject) => {
+          timer = setTimeout(() => reject(new Error("owned cleanup timed out")), BRANCH_QUIESCE_TIMEOUT_MS + 1_000);
+        }),
+      ]);
+    } catch (error: unknown) {
+      // Never turn uncertain cleanup into a resumable interruption. Existing
+      // terminal recovery facts durably fence this run without a protocol change.
+      if (this.runs.get(owner.runId) !== state || state.executionGeneration !== executionGeneration) return;
+      const stopDiagnostic = stopError === undefined ? "" : `; stop failed: ${String(stopError)}`;
+      const diagnostic = `Owned cleanup unconfirmed for ${agentId}: ${error instanceof Error ? error.message : String(error)}${stopDiagnostic}; run is non-resumable`;
+      this.fenceExecution(state, executionGeneration, diagnostic);
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
+    }
+  }
+
+  private async drainExecution(state: ScriptRunState, execution?: Promise<unknown>): Promise<void> {
+    if (!execution) return;
+    const generation = state.executionGeneration;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        execution.catch(() => {}),
+        new Promise<void>((resolve) => {
+          timer = setTimeout(() => {
+            this.fenceExecution(state, generation, "Workflow execution cleanup timed out; run is non-resumable");
+            resolve();
+          }, EXECUTION_DRAIN_TIMEOUT_MS);
+        }),
+      ]);
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
+    }
+  }
+
+  private fenceExecution(state: ScriptRunState, generation: number, diagnostic: string): void {
+    const run = state.run;
+    if (this.runs.get(run.runId) !== state || state.executionGeneration !== generation) return;
+    if (run.nonResumable && run.status === "stopped") return;
+    run.nonResumable = true;
+    const blockedNodeIds = Object.keys(run.callStatus).filter((nodeId) => run.callStatus[nodeId] !== "completed");
+    for (const nodeId of blockedNodeIds) run.callStatus[nodeId] = "stopped";
+    run.status = "stopped";
+    run.error = diagnostic;
+    run.terminalIntent = "stop";
+    run.updatedAt = Date.now();
+    const event: TerminalRecoveryEvent = {
+      kind: "terminal_recovery",
+      schemaVersion: JOURNAL_SCHEMA_VERSION,
+      runId: run.runId,
+      status: "stopped",
+      terminalIntent: "stop",
+      branchGeneration: this.recoveryBranchGeneration,
+      terminalResults: [],
+      blockedNodeIds,
+      error: diagnostic,
+      recoveryId: deriveRecoveryId({ runId: run.runId, rotations: [], timestamp: Date.now() }),
+      timestamp: Date.now(),
+    };
+    this.persist(run.runId, "cleanup-unconfirmed", () => this.write(event));
+    // Fence before aborting: synchronous abort handlers may re-enter cleanup.
+    // Exact-owner cleanup continues, but no later result may revive this run.
+    state.executionGeneration += 1;
+    state.controller.abort();
+    this.cleanupAgents(run.runId);
+    this.settleWaiters(run.runId, run);
+  }
+
   private async stop(state: ScriptRunState): Promise<void> {
     const run = state.run;
     if (isTerminalWorkflow(run.status)) return;

package/src/index.ts

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
@@ -36,11 +36,40 @@ const WorkflowToolSchema = Type.Object(
     name: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
     args: Type.Optional(Type.Any()),
     background: Type.Optional(Type.Boolean()),
-    maxAgents: Type.Optional(Type.Number({ minimum: 1 })),
-    concurrency: Type.Optional(Type.Number({ minimum: 1 })),
-    agentRetries: Type.Optional(Type.Number({ minimum: 0, maximum: 3 })),
-    tokenBudget: Type.Optional(Type.Number({ minimum: 1 })),
-    agentTimeoutMs: Type.Optional(Type.Number({ minimum: 1 })),
+    maxAgents: Type.Optional(
+      Type.Number({
+        minimum: 1,
+        description:
+          "Cap on real agent dispatches for this run. Default 1000, which no ordinary script reaches. Omit it: a value below what the script dispatches stops the run partway with AGENT_LIMIT_EXCEEDED.",
+      }),
+    ),
+    concurrency: Type.Optional(
+      Type.Number({
+        minimum: 1,
+        description:
+          "Agents in flight at once. Defaults to the host's own subagent pool size, which is also the ceiling. Omit it: a lower number runs the same work more slowly and buys nothing, and a higher one is clamped.",
+      }),
+    ),
+    agentRetries: Type.Optional(
+      Type.Number({
+        minimum: 0,
+        maximum: 3,
+        description: "Retries for a recoverable agent failure. Default 0; a failed call returns null to the script.",
+      }),
+    ),
+    tokenBudget: Type.Optional(
+      Type.Number({
+        minimum: 1,
+        description: "Soft token ceiling for the whole run. Default unlimited; exhausting a set budget aborts the run.",
+      }),
+    ),
+    agentTimeoutMs: Type.Optional(
+      Type.Number({
+        minimum: 1,
+        description:
+          "Wall clock per agent, there to bound a hang. Default 1800000 (30min), and it counts from when the agent actually starts, not from dispatch. An agent's real budget is the host's turn, tool and token ceiling. Omit it: a short value fails an entire fan-out as timeouts.",
+      }),
+    ),
     resumeFromRunId: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
   },
   { additionalProperties: false },
@@ -128,8 +157,14 @@ function formatStart(result: ScriptStartResult): string {
     `Workflow ${result.background ? "started in background" : result.status}: ${result.runId}`,
     `status=${result.status}`,
   ];
-  if (result.waitAborted)
-    lines.push("wait_aborted=true", "The workflow run continues; retrieve it with workflow_control.");
+  if (result.waitAborted) {
+    lines.push(
+      "wait_aborted=true",
+      result.background
+        ? "Only the wait was cancelled; retrieve the detached run with workflow_control."
+        : "Foreground execution was cancelled; inspect its status with workflow_control before resuming.",
+    );
+  }
   if (result.result) lines.push("", result.result.slice(0, 8_000));
   if (result.error) lines.push("", `error=${result.error.slice(0, 2_000)}`);
   return lines.join("\n");
@@ -139,7 +174,7 @@ function formatStart(result: ScriptStartResult): string {
 export function buildAdHocWorkflowScript(prompt: string): string {
   return `export const meta = { name: "ad-hoc", description: "Plan, execute, and synthesize a bounded multi-agent task graph" };
 const originalPrompt = ${JSON.stringify(prompt)};
-const plan = await agent("Design a bounded execution plan for this user task. Return 1-8 independent or dependency-linked tasks. Use unique short ids, concise descriptions, exact worker prompts, and only dependencies that appear in the task list. Prefer independent tasks when possible. User task:\\n\\n" + originalPrompt, {
+const plan = await agent("Design a bounded execution plan for this user task. Return 1-24 independent or dependency-linked tasks. Use unique short ids, concise descriptions, exact worker prompts, and only dependencies that appear in the task list. Prefer independent tasks when possible, and prefer narrow tasks over few broad ones: a task asked one question is read further into than a task asked four. User task:\\n\\n" + originalPrompt, {
   label: "planner",
   strength: "medium",
   schema: {
@@ -148,14 +183,14 @@ const plan = await agent("Design a bounded execution plan for this user task. Re
       tasks: {
         type: "array",
         minItems: 1,
-        maxItems: 8,
+        maxItems: 24,
         items: {
           type: "object",
           properties: {
             id: { type: "string", minLength: 1, maxLength: 64 },
             description: { type: "string", minLength: 1, maxLength: 500 },
             prompt: { type: "string", minLength: 1, maxLength: 8000 },
-            dependsOn: { type: "array", maxItems: 8, items: { type: "string", minLength: 1, maxLength: 64 } },
+            dependsOn: { type: "array", maxItems: 24, items: { type: "string", minLength: 1, maxLength: 64 } },
           },
           required: ["id", "description", "prompt"],
           additionalProperties: false,
@@ -308,6 +343,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
   const MAX_PENDING_DELIVERIES = 256;
   const PENDING_DELIVERY_TTL_MS = 7 * 24 * 60 * 60 * 1_000;
   let widgetTimer: ReturnType<typeof setInterval> | undefined;
+  let widgetUi: ExtensionContext["ui"] | undefined;
 
   const currentEngine = (): WorkflowEngine => {
     if (!active || !engine || engine.isDisposed())
@@ -316,12 +352,11 @@ export default function piWorkflows(pi: ExtensionAPI): void {
   };
 
   const clearWidget = (): void => {
-    const tui = (pi as unknown as { ui?: { setWidget?: (key: string, content: string[] | undefined) => void } }).ui;
-    tui?.setWidget?.("pi-workflows", undefined);
+    widgetUi?.setWidget("pi-workflows", undefined);
   };
   const refreshWidget = (): void => {
-    const tui = (pi as unknown as { ui?: { setWidget?: (key: string, content: string[] | undefined) => void } }).ui;
-    if (!tui?.setWidget) return;
+    const tui = widgetUi;
+    if (!tui) return;
     const workflowEngine = engine;
     if (!active || !workflowEngine || workflowEngine.isDisposed()) {
       tui.setWidget("pi-workflows", undefined);
@@ -346,15 +381,6 @@ export default function piWorkflows(pi: ExtensionAPI): void {
   };
   const notifyRunChanged = (): void => refreshWidget();
 
-  const branchEntries = (): SessionEntryLike[] => {
-    const ctx = (pi as unknown as { currentSessionManager?: { getBranch?: () => unknown } }).currentSessionManager;
-    try {
-      return (ctx?.getBranch?.() as SessionEntryLike[] | undefined) ?? [];
-    } catch {
-      return [];
-    }
-  };
-
   const DEFAULT_EXCLUDED_TOOLS = ["workflow", "workflow_control"] as const;
 
   /**
@@ -406,6 +432,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     active = true;
     const workflowEngine = currentEngine();
     workflowEngine.onRunSettled = notifyRunChanged;
+    workflowEngine.onRuntimeEvent = notifyRunChanged;
     // `control("resume")` and the provider-limit retry start executions with no
     // caller to pass options for them, and the strength table is deliberately
     // never frozen onto a run. Without this they would resume with no table and
@@ -427,9 +454,11 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         promptGuidelines: [
           "Provide either a full `script` (raw JavaScript with the meta contract first) or a `name` of a saved/built-in workflow.",
           "Use orchestrate([{ id, dependsOn, run }]) for named dependency graphs; use parallel(() => agent(...), ...) for a simple fan-out and pipeline(items, ...stages) for sequential per-item stages.",
+          "Size the fan-out to the work: one agent per independent piece of evidence the task actually has. Ten to thirty agents is an ordinary review or audit, and a script that splits a broad task four ways is usually four agents each doing one agent's job. The gain is coverage, not speed — how many run at once is the host's pool, not the script's choice.",
+          "Pass script/name/args/background and nothing else unless the user named a specific limit. maxAgents, concurrency, agentRetries, tokenBudget and agentTimeoutMs already default to tuned values, and each one stops or fails the run when it is set too low.",
           "Use background: true for long runs; retrieve results with workflow_control.",
           "Use resumeFromRunId with an edited script to replay the unchanged prefix from cache and re-run the rest live.",
-          "Do not include model, thinking, concurrency, retry, timeout, or turn-limit settings beyond the declared options.",
+          "Inside the script, never name a model, a thinking level, or a turn limit: `strength` is the only routing a call may express.",
         ],
         parameters: WorkflowToolSchema,
         renderCall(args, theme) {
@@ -478,13 +507,13 @@ export default function piWorkflows(pi: ExtensionAPI): void {
               // Foreground checkpoint confirmation only when the run is not
               // background — background runs are headless by contract.
               confirm:
-                params.background === false && ctx?.hasUI && ctx.mode === "tui"
-                  ? async (promptText, checkpointOptions) => {
+                params.background === false && ctx?.hasUI
+                  ? async (promptText, checkpointOptions, signal) => {
                       if (checkpointOptions.kind === "input")
-                        return ctx.ui.input(promptText, String(checkpointOptions.default ?? ""));
+                        return ctx.ui.input(promptText, String(checkpointOptions.default ?? ""), { signal });
                       if (checkpointOptions.kind === "select")
-                        return ctx.ui.select(promptText, checkpointOptions.choices ?? []);
-                      return ctx.ui.confirm(promptText, promptText);
+                        return ctx.ui.select(promptText, checkpointOptions.choices ?? [], { signal });
+                      return ctx.ui.confirm(promptText, promptText, { signal });
                     }
                   : undefined,
               loadSavedWorkflow: resolveNestedWorkflow,
@@ -494,7 +523,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
               const replacement = params.script !== undefined || params.name !== undefined ? script : undefined;
               const resumed = await workflowEngine.resume(
                 params.resumeFromRunId,
-                branchEntries(),
+                ctx.sessionManager.getBranch(),
                 options,
                 replacement,
               );
@@ -929,7 +958,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       if (event.text.includes(WORKFLOW_ARMED_DIRECTIVE)) return { action: "continue" as const };
       const effortDirective =
         effortLevel === "ultra"
-          ? 'Effort: ULTRA. Be exhaustive: use broad parallel review, verification, and completeness checks; give the deepest steps strength: "high".'
+          ? 'Effort: ULTRA. Be exhaustive: use broad parallel review, verification, and completeness checks. Width is where the exhaustiveness goes: keep steps at strength: "medium" and reserve "high" for a step whose error is expensive to reverse, if the run has one at all.'
           : effortLevel === "high"
             ? "Effort: HIGH. Be thorough: use several independent reviewers and an adversarial verification pass."
             : "";
@@ -1085,6 +1114,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       } finally {
         workflowEngine.resumeLifecycle();
         branchQuiesce = undefined;
+        refreshWidget();
       }
     });
   };
@@ -1226,6 +1256,10 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         {
           append(event) {
             pi.appendEntry(JOURNAL_ENTRY_TYPE, event);
+            // Journal writes precede some state mutations; refresh once applied.
+            queueMicrotask(() => {
+              if (generation === lifecycleGeneration) refreshWidget();
+            });
           },
         },
         () => {
@@ -1257,7 +1291,12 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       return;
     }
 
+    if (generation !== lifecycleGeneration) {
+      recoveredEngine.dispose();
+      return;
+    }
     engine = recoveredEngine;
+    widgetUi = ctx.mode === "tui" ? ctx.ui : undefined;
     registerSurface();
 
     // Bind per-session delivery endpoint (A10): capture the session-bound send
@@ -1351,6 +1390,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     // engine quiescence; the old session must not accept another run.
     active = false;
     clearWidget();
+    widgetUi = undefined;
     if (widgetTimer) {
       clearInterval(widgetTimer);
       widgetTimer = undefined;