@signalridge/pi-workflows 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 1.7.1
+### Patch Changes
+
+- 1f586f8: Preserve resumable cancellation when a workflow pauses during successful timeout cleanup, and retain finalized subagent output alongside observer failures. Avoid retaining descendant-owned mouse gestures in bordered components. Track successful writes using final rewritten paths, and distinguish uncertain changes observed during failed calls from confirmed agent modifications while keeping both discoverable in file browsing. Preserve exact filesystem paths and lazy-directory scan state when discovering session-observed changes, including changes injected during an active scan.
+- 1f586f8: - Bound workflow cancellation drains and durably fence unconfirmed cleanup, aborting sibling agents and releasing foreground callers.
+  - Await managed timeout cleanup before script continuation and terminal publication.
+  - Keep failed retry text and length responses discarded by overflow-compaction retry out of successful subagent fallbacks, while retaining valid pre-compaction and non-retried length output.
+  - Account for native prompts spanning reporter activation without dropping out-of-order wait debt.
+  - Reconcile settlement after observer-triggered manual compaction with run/session ownership.
+  - Preserve clipped overlay hit ranges and native container ancestry for editor autocomplete focus.
+  - Reconcile errored writes and edits against pre/post mutation evidence, retaining invocation cwd and releasing evidence when blocked or aborted preflight bypasses tool results.
+- d9219d4: Correct shipped documentation that contradicted the code or the manifest.
+  
+  - `pi-subagents`: the summary line still advertised protocol-v3 spawning while
+    the feature list and the managed-spawn section described v4.
+  - `pi-worktree`: the workspace-switching section named `/tree`; the registered
+    command is `/worktree`.
+  - `pi-workflows`: removed an orphaned sentence fragment left behind by an edit
+    to the saved-workflow paragraph.
+  - `pi-plan-mode`, `pi-goal`, `pi-usage-extension`: the stated Pi floor
+    (`0.80.6`, `0.42.4+`) contradicted the declared `^0.84.0` peer range, which
+    resolves to `0.84.x`. `pi-usage-extension` also carried a "Last updated"
+    stamp from a version that predates the workspace baseline.
+  - `pi-welcome`: the example card was a real session capture. It is now a
+    generic sample, and Install moved above the configuration sections instead of
+    sitting below them.
+- 1f586f8: Preserve Codex opaque checkpoints across Pi's retry-only assistant-tail removal using optional, fingerprint-verified version-1 proof plus explicit lifecycle provenance. Preserve that provenance across same-runtime reload without confusing a new identical assistant response with the persisted tail; persisted rebuilds reset it and unknown provenance fails closed. Bound BTW context and tool-argument construction, including suffix-key storage for wide JSON-shaped objects (enumeration remains linear). Balance out-of-order native UI waiting notifications without affecting manual blocked ownership. Foreground workflow cancellation waits for exact-owner quiescence even when stop is unavailable or rejects after reconciliation already stopped the child, including cancelled spawn allocation recovery; unconfirmed cleanup becomes durably non-resumable with a diagnostic retaining any stop error. Background execution remains detached.
+  
+  These are corrective changes: existing checkpoint fields, exports, and cross-extension protocols remain compatible, so no protocol or major-version bump is required.
+- 1f586f8: Expand Pi peer support to `^0.84.0 || ^0.85.0`, retaining 0.84 compatibility while admitting 0.85 releases. The previous zero-major caret range excluded Pi 0.85.1. Update existing Pi development dependency pins to 0.85.1.
+- 1f586f8: Keep goal iteration and continuation numbering correct when Pi compacts between tool results and the next response within one run. Preserve existing response limits and manual/post-run compaction handling.
+  
+  Capture subagent invocation results from finalized assistant events with bounded message retention so compaction cannot hide a final error or mix in historical output. Recognize explicitly selected PowerShell when the host provides it, without requiring its export on older Pi versions or expanding default wildcard tools.
+  
+  Use real session contexts for workflow replay and live TUI progress, release widget bindings on shutdown, and allow foreground checkpoint dialogs in RPC mode while retaining print-mode defaults. Cancel unanswered dialogs with their owning execution on tool abort, pause, stop, disposal, or fatal failure without journaling cancelled answers.
+
 ## 1.7.0
 ### Minor Changes
 

package/README.md

@@ -208,7 +208,6 @@ sentence-ending dot is not a filename dot: "please run a workflow." arms, and
 turn it off entirely with `/workflows-trigger off`.
 
 Saved workflows use project scope first and a user scope fallback; writes are atomic and names are path-safe.
-written atomically with a backup.
 
 ## Model routing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-workflows",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Deterministic JavaScript orchestration workflows backed by pi-subagents managed spawning.",
   "type": "module",
   "license": "MIT",
@@ -15,8 +15,8 @@
     "lifecycle": "stable"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.0",
-    "@earendil-works/pi-tui": "^0.84.0",
+    "@earendil-works/pi-coding-agent": "^0.84.0 || ^0.85.0",
+    "@earendil-works/pi-tui": "^0.84.0 || ^0.85.0",
     "@signalridge/pi-subagents": ">=1.9.0"
   },
   "dependencies": {

package/skills/workflow-authoring/SKILL.md

@@ -2,7 +2,7 @@
 name: workflow-authoring
 description: Design, write, review, and debug Pi JavaScript workflows that coordinate multiple subagents. Use when a request needs named dependencies, bounded fan-out, per-item pipelines, quality gates, saved or nested workflows, pause/resume, or workflow progress; do not use it merely to run an existing named workflow.
 metadata:
-  version: "1.7.0"
+  version: "1.7.1"
 ---
 
 # Workflow authoring

package/skills/workflow-authoring/references/capabilities.md

@@ -2,7 +2,7 @@
 # Workflow capability index
 
 Contract format: `2.0.0`<br>
-Contract content / skill / extension: `1.7.0`
+Contract content / skill / extension: `1.7.1`
 
 This compact generated index covers supported runtime globals and workflow-tool inputs. For constraints, compatibility behavior, internal boundaries, and dynamic-reference ownership, follow the [exhaustive generated facts](capability-details.md).
 

package/skills/workflow-authoring/references/capability-details.md

@@ -2,7 +2,7 @@
 # Exhaustive workflow capability facts
 
 Contract format: `2.0.0`<br>
-Contract content / skill / extension: `1.7.0`
+Contract content / skill / extension: `1.7.1`
 
 Every exact fact below is projected from the installed extension's capability contract. Explanatory judgment belongs in the hand-written references next to this file.
 

package/skills/workflow-patterns/SKILL.md

@@ -2,7 +2,7 @@
 name: workflow-patterns
 description: Choose and run one of Pi's built-in multi-agent workflows for research, adversarial review, code review, multi-perspective analysis, or codebase auditing. Use when the request matches a named pattern; use workflow-authoring instead for a new script or custom topology.
 metadata:
-  version: "1.7.0"
+  version: "1.7.1"
 ---
 
 # Built-in workflow patterns

package/skills/workflow-review/SKILL.md

@@ -2,7 +2,7 @@
 name: workflow-review
 description: Audit an existing Pi JavaScript workflow for topology, prompt/data flow, limits, failure handling, cancellation, resume safety, and publication compatibility. Use when reviewing or debugging a workflow script or saved run; do not use to run a standard named workflow.
 metadata:
-  version: "1.7.0"
+  version: "1.7.1"
 ---
 
 # Workflow review

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;
@@ -754,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(() => {});
@@ -771,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 };
     }
@@ -795,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);
@@ -862,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 };
     }
   }
@@ -896,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}`);
       }
@@ -1017,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 {
@@ -1043,7 +1065,7 @@ export class WorkflowEngine {
         agentRetries: options.agentRetries,
         tokenBudget: options.tokenBudget,
         agentTimeoutMs: options.agentTimeoutMs,
-        signal: state.controller.signal,
+        signal: executionSignal,
         maxAgents: options.maxAgents,
         runId,
         executionNonce: `${generation}-${randomUUID()}`,
@@ -1078,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)) {
@@ -1086,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);
@@ -1094,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);
@@ -1119,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,
       });
@@ -1220,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);
@@ -1231,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,
@@ -1294,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 }),
+          );
+        });
       }
     };
 
@@ -1532,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";
@@ -157,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");
@@ -337,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())
@@ -345,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);
@@ -375,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;
 
   /**
@@ -435,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
@@ -509,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,
@@ -525,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,
               );
@@ -1116,6 +1114,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       } finally {
         workflowEngine.resumeLifecycle();
         branchQuiesce = undefined;
+        refreshWidget();
       }
     });
   };
@@ -1257,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();
+            });
           },
         },
         () => {
@@ -1288,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
@@ -1382,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;

package/src/rpc-client.ts

@@ -380,7 +380,7 @@ export function createManagedSpawnClient(
           agentId,
           owner,
         },
-        sessionSignal,
+        undefined,
       );
     },
     async reconcileManaged(spawnKey, owner) {
@@ -403,10 +403,15 @@ export function createManagedSpawnClient(
           ...(owners ? { owners } : {}),
           timeoutMs,
         },
-        sessionSignal,
+        undefined,
         timeoutMs + 1_000,
       );
-      if (!isRecord(data) || typeof data.settled !== "boolean" || !Array.isArray(data.pending)) {
+      if (
+        !isRecord(data) ||
+        typeof data.settled !== "boolean" ||
+        !Array.isArray(data.pending) ||
+        !data.pending.every((id) => typeof id === "string" && id.length > 0)
+      ) {
         throw new Error("subagents quiescence returned an invalid response");
       }
       const pending = data.pending.filter((id): id is string => typeof id === "string");

package/src/runtime.ts

@@ -116,6 +116,8 @@ export type Limiter = <T>(fn: () => Promise<T>) => Promise<T>;
 /** The dispatch boundary the engine implements over spawn-managed RPC. */
 export interface WorkflowAgentRunner {
   run(prompt: string, options?: AgentRunOptions): Promise<unknown>;
+  /** Managed runners bound and confirm cleanup of aborted dispatches. */
+  waitForCleanup?(): Promise<void>;
 }
 
 export interface AgentRunOptions {
@@ -300,7 +302,7 @@ export interface WorkflowRunOptions {
   sharedStore?: SharedStore;
   /** Resolve a nested `workflow(name)` reference to the script it names. */
   loadSavedWorkflow?: (name: string) => string | undefined;
-  confirm?: (promptText: string, options: CheckpointOptions) => Promise<unknown>;
+  confirm?: (promptText: string, options: CheckpointOptions, signal?: AbortSignal) => Promise<unknown>;
   onLog?: (message: string) => void;
   onPhase?: (title: string) => void;
   onRuntimeEvent?: (event: WorkflowRuntimeEvent) => void;
@@ -921,6 +923,7 @@ async function withTimeout<T>(
    * must degrade to the old behaviour, not to an agent that can hang forever.
    */
   onArm?: (restart: () => void) => void,
+  waitForCleanup?: () => Promise<void>,
 ): Promise<T> {
   if (ms === null) {
     onArm?.(() => {});
@@ -934,9 +937,11 @@ async function withTimeout<T>(
   // finished agent long after the fact, so settlement makes it inert here
   // rather than relying on every holder to guard its own call.
   let settled = false;
+  let timedOut = false;
 
   const timeoutPromise = new Promise<never>((_, reject) => {
     const fire = () => {
+      timedOut = true;
       try {
         onTimeout?.();
       } catch {
@@ -963,6 +968,9 @@ async function withTimeout<T>(
   } finally {
     settled = true;
     if (timeoutId) clearTimeout(timeoutId);
+    // The timeout wins the race immediately, but managed cleanup must settle
+    // (or durably fence the run) before script continuation and journal output.
+    if (timedOut) await waitForCleanup?.();
   }
 }
 
@@ -1722,6 +1730,7 @@ export async function runWorkflow<T = unknown>(
               (restart) => {
                 restartTimeout = restart;
               },
+              options.agent?.waitForCleanup,
             );
 
             throwIfAborted();
@@ -1789,6 +1798,18 @@ export async function runWorkflow<T = unknown>(
             });
             return result;
           } catch (error) {
+            // A timeout waits for managed cleanup before reaching this catch.
+            // Explicit cancellation may arrive during that await; it wins only
+            // over this recoverable timeout, never over a fatal cleanup fence.
+            if (
+              options.signal?.aborted &&
+              !shared.runFatalController.signal.aborted &&
+              error instanceof WorkflowError &&
+              error.recoverable &&
+              error.code === WorkflowErrorCode.AGENT_TIMEOUT
+            ) {
+              throwIfAborted();
+            }
             if (isAborted()) throw error;
 
             const workflowError = wrapError(error, { agentLabel: label });
@@ -2285,7 +2306,34 @@ export async function runWorkflow<T = unknown>(
 
     let reply: unknown;
     if (options.confirm) {
-      reply = await options.confirm(promptText, checkpointOptions);
+      // Host-only cancellation must not affect author options or replay hashes.
+      const signal = options.signal
+        ? AbortSignal.any([options.signal, shared.runFatalController.signal])
+        : shared.runFatalController.signal;
+      const confirm = options.confirm;
+      let onAbort: (() => void) | undefined;
+      try {
+        const cancelled = new Promise<never>((_resolve, reject) => {
+          onAbort = () => {
+            try {
+              throwIfAborted();
+            } catch (error) {
+              reject(error);
+            }
+          };
+          signal.addEventListener("abort", onAbort, { once: true });
+          if (signal.aborted) onAbort();
+        });
+        // Older host callbacks may ignore the optional signal. Still release
+        // the runtime wait, and observe any eventual callback rejection.
+        const answer = Promise.resolve().then(() => {
+          throwIfAborted();
+          return confirm(promptText, checkpointOptions, signal);
+        });
+        reply = await Promise.race([answer, cancelled]);
+      } finally {
+        if (onAbort) signal.removeEventListener("abort", onAbort);
+      }
     } else if (checkpointOptions.headless === "abort") {
       throw new WorkflowError(
         `checkpoint "${promptText}" needs human input but none is available (headless run)`,