@signalridge/pi-workflows 1.7.3 → 1.7.4

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.7.4
+### Patch Changes
+
+- 8190516: Clarify that keyword arming guides the model but is not an execution-time permission gate; direct workflow calls remain governed by the host's normal tool permissions.
+- 8190516: Extend the tested Pi host compatibility range through 0.87.x while retaining supported older hosts. Validate the published extensions against Pi 0.87.1 and adapt changed provider, session-context, and lifecycle contracts where necessary.
+- 8190516: Add Pi 0.99.1 to the supported host peer ranges while retaining Pi 0.84–0.87 compatibility. Align Pi development dependency pins with 0.99.1 for validation against the new host.
+- 8190516: Retain Pi's tree-navigation attempt signal for branch ownership and deduplication. Active child or workflow work now causes a non-destructive preflight veto rather than pre-veto quiescence; accepted tree changes fence late old-branch callbacks. A second attempt rechecks live work instead of reusing state from a canceled attempt. Pi still lacks an atomic post-veto, pre-leaf commit hook: work started during asynchronous summarization may need to be quarantined on commit.
+- 8190516: Skip the full Pi session-branch scan when the workflow journal's anchored leaf is still current. Keep the existing ancestry check when the leaf changes or cannot be reported, so navigated-away branches cannot receive old journal entries.
+- 8190516: Block session switches and tree navigation while subagents, workflows, or provider cleanup remain unsettled, without stopping work on a cancellable attempt. Confirmed shutdown coordinates workflow-owned cleanup before retiring the subagent RPC responder; confirmed tree changes fence stale callbacks and keep old terminal facts off the new branch. Pi's hook ordering still leaves a narrow, non-atomic interval between preflight and commit, so new work during summarization is quarantined on commit rather than guaranteed to finish.
+
 ## 1.7.3
 ### Patch Changes
 

package/README.md

@@ -198,6 +198,10 @@ tell the model the `workflow` tool is authorized for this turn.
 Arming **authorizes; it does not compel**. The annotation says the model may run
 a workflow and may still decline, so "how do workflows work?" stays an ordinary
 question with an ordinary answer. Nothing is swallowed and no UI opens.
+This is **model guidance, not an execution permission gate**: the extension does
+not enforce the keyword inside `workflow.execute`. Direct tool calls remain
+subject to Pi's ordinary tool permissions; do not use the trigger as a security
+boundary.
 
 Only a standalone word arms. A workflow is also a thing people write code about,
 so none of `myworkflow`, `workflow_name`, `WorkflowEngine`, `--workflow-id`,
@@ -392,4 +396,4 @@ used it.
 - **Agent registry and tier catalogue ownership.** `agentType` and the tier catalogue resolve in pi-subagents; the workflow package supplies only a tier key its own `strengths` table chose, avoiding a second model/thinking policy.
 - **Schema validation is client-side.** The managed request does not assume a structured-output tool; the runtime asks for JSON, parses, validates (including `additionalProperties`), and repairs across bounded attempts.
 
-State is persisted as `pi.appendEntry("pi-workflows:journal", ...)` custom entries (schema v4), including frozen invocation args, resolved tier identity, terminal result previews, script revisions, named nested-workflow result boundaries, and durable removals. Interrupted/provider-limited runs replay from the journal; pre-schema-v4 journals are quarantined rather than replayed. Foreground `AbortSignal`s stop owned children through explicit owner-scoped stop/quiescence, and dispose/branch replacement reject stale waiters.
+State is persisted as `pi.appendEntry("pi-workflows:journal", ...)` custom entries (schema v4), including frozen invocation args, resolved tier identity, terminal result previews, script revisions, named nested-workflow result boundaries, and durable removals. Interrupted/provider-limited runs replay from the journal; pre-schema-v4 journals are quarantined rather than replayed. Foreground `AbortSignal`s stop owned children through explicit owner-scoped stop/quiescence, and dispose/branch replacement reject stale waiters. For tree navigation, bus and native pre-tree notifications share quiescence within one host signal; a later attempt rechecks runs started since a veto, after any earlier cleanup settles. This only prevents reuse of stale quiescence: Pi does not provide a post-veto, precommit hook, so the initial canceled attempt can still interrupt active runs. Hosts without a pre-tree signal retain legacy deduplication.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-workflows",
-  "version": "1.7.3",
+  "version": "1.7.4",
   "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 || ^0.85.0",
-    "@earendil-works/pi-tui": "^0.84.0 || ^0.85.0",
+    "@earendil-works/pi-coding-agent": "^0.84.0 || ^0.85.0 || ^0.86.0 || ^0.87.0 || ^0.99.1",
+    "@earendil-works/pi-tui": "^0.84.0 || ^0.85.0 || ^0.86.0 || ^0.87.0 || ^0.99.1",
     "@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.3"
+  version: "1.7.4"
 ---
 
 # 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.3`
+Contract content / skill / extension: `1.7.4`
 
 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.3`
+Contract content / skill / extension: `1.7.4`
 
 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.3"
+  version: "1.7.4"
 ---
 
 # 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.3"
+  version: "1.7.4"
 ---
 
 # Workflow review

package/src/arming.ts

@@ -1,5 +1,6 @@
 /**
- * arming.ts — the keyword that authorizes the workflow tool for a turn.
+ * arming.ts — a keyword that tells the model a workflow is appropriate this turn.
+ * It is advisory prompt guidance, not an execution-time permission gate.
  *
  * Typing the bounded word `workflow` (or `workflows`, or a configured synonym)
  * in an ordinary message is an explicit opt-in to multi-agent orchestration, so

package/src/engine.ts

@@ -335,6 +335,9 @@ export class WorkflowEngine {
   private disposed = false;
   private lifecyclePaused = false;
   private branchQuiescePromise: Promise<WorkflowQuiesceResult> | undefined;
+  private branchEpoch = 0;
+  private admissionsClosed = false;
+  private pendingAdmissions = 0;
   private recoveryBranchGeneration = 0;
   private readonly journalRetries = new Map<string, { timer?: ReturnType<typeof setTimeout>; attempt: number }>();
   private readonly journalBlockedRuns = new Set<string>();
@@ -378,6 +381,38 @@ export class WorkflowEngine {
     return this.disposed;
   }
 
+  /** A synchronous snapshot for cancellable navigation, not an admission lock. */
+  hasUnsettledWork(): boolean {
+    return (
+      this.pendingAdmissions > 0 ||
+      this.branchQuiescePromise !== undefined ||
+      this.journalRetries.size > 0 ||
+      this.providerResumeTimers.size > 0 ||
+      [...this.runs.values()].some(
+        (state) =>
+          state.run.status === "running" ||
+          state.run.status === "pausing" ||
+          state.run.status === "stopping" ||
+          state.pendingSpawns.size > 0 ||
+          state.agentWaiters.size > 0 ||
+          state.pendingJournal.size > 0,
+      )
+    );
+  }
+
+  /** Pi has committed the new leaf: stop old callbacks without journaling there. */
+  fenceCommittedBranch(): void {
+    if (this.disposed || this.lifecyclePaused) return;
+    this.branchEpoch++;
+    this.admissionsClosed = true;
+    this.suspendLifecycle();
+    this.clearJournalRetries();
+    for (const state of this.runs.values()) {
+      state.lifecycleSuspended = true;
+      state.controller.abort(new DOMException("Workflow branch replaced", "AbortError"));
+    }
+  }
+
   private attachLifecycle(): () => void {
     const unsubs = [
       "subagents:created",
@@ -579,6 +614,7 @@ export class WorkflowEngine {
   async quiesceForBranchChange(): Promise<WorkflowQuiesceResult> {
     if (this.disposed) return { settled: true, pending: [] };
     if (this.branchQuiescePromise) return this.branchQuiescePromise;
+    this.admissionsClosed = true;
     this.clearJournalRetries();
 
     // Suspend and abort synchronously, before any await can let a stale runtime
@@ -661,8 +697,18 @@ export class WorkflowEngine {
    */
   async start(script: string, options: ScriptStartOptions = {}): Promise<ScriptStartResult> {
     if (this.disposed) throw new WorkflowEngineDisposedError();
-    const protocol = await this.awaitProtocol();
+    if (this.lifecyclePaused || this.admissionsClosed) throw new Error("Workflow branch is not ready");
+    const epoch = this.branchEpoch;
+    this.pendingAdmissions++;
+    let protocol: ManagedProtocolCheck;
+    try {
+      protocol = await this.awaitProtocol();
+    } finally {
+      this.pendingAdmissions--;
+    }
     if (this.disposed) throw new WorkflowEngineDisposedError();
+    if (epoch !== this.branchEpoch || this.lifecyclePaused || this.admissionsClosed)
+      throw new Error("Workflow branch changed before admission");
     const { meta } = parseWorkflowScript(script);
     const now = Date.now();
     const runId = randomUUID();
@@ -798,8 +844,18 @@ export class WorkflowEngine {
     replacementScript?: string,
   ): Promise<ScriptStartResult | undefined> {
     if (this.disposed) throw new WorkflowEngineDisposedError();
-    const protocol = await this.awaitProtocol();
+    if (this.lifecyclePaused || this.admissionsClosed) throw new Error("Workflow branch is not ready");
+    const epoch = this.branchEpoch;
+    this.pendingAdmissions++;
+    let protocol: ManagedProtocolCheck;
+    try {
+      protocol = await this.awaitProtocol();
+    } finally {
+      this.pendingAdmissions--;
+    }
     if (this.disposed) throw new WorkflowEngineDisposedError();
+    if (epoch !== this.branchEpoch || this.lifecyclePaused || this.admissionsClosed)
+      throw new Error("Workflow branch changed before admission");
     const state = this.runs.get(runId);
     if (!state) return undefined;
     if (state.lifecycleSuspended) return undefined;
@@ -1016,6 +1072,13 @@ 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 epoch = this.branchEpoch;
+    const isSameBranch = () =>
+      this.runs.get(runId) === state &&
+      state.executionGeneration === generation &&
+      this.branchEpoch === epoch &&
+      !this.disposed;
+    const isCurrent = () => isSameBranch() && !state.lifecycleSuspended && !this.lifecyclePaused;
     const executionSignal =
       !options.background && options.signal
         ? AbortSignal.any([state.controller.signal, options.signal])
@@ -1024,8 +1087,7 @@ export class WorkflowEngine {
     const cleanupTasks = new Set<Promise<void>>();
     const runner: WorkflowAgentRunner = {
       run: async (prompt: string, runOptions: AgentRunOptions = {}) => {
-        if (state.executionGeneration !== generation)
-          throw new WorkflowError("stale workflow execution", WorkflowErrorCode.WORKFLOW_ABORTED);
+        if (!isCurrent()) throw new WorkflowError("stale workflow execution", WorkflowErrorCode.WORKFLOW_ABORTED);
         const dispatch = this.dispatchAgent(runId, prompt, runOptions);
         const settled = dispatch.then(
           () => {},
@@ -1076,18 +1138,18 @@ export class WorkflowEngine {
         confirm: options.confirm,
         loadSavedWorkflow: options.loadSavedWorkflow,
         onAgentJournal: (entry) => {
-          if (state.executionGeneration !== generation) return;
+          if (!isCurrent()) return;
           // Nested workflow frames keep their own lifecycle visibility, but their
           // individual call facts are not top-level replay keys. The parent
           // workflow_result fact below owns the nested replay boundary.
           if (entry.runId === undefined || entry.runId === runId) this.journalCallResult(runId, entry);
         },
         onWorkflowJournal: (entry) => {
-          if (state.executionGeneration !== generation) return;
+          if (!isCurrent()) return;
           this.journalWorkflowResult(runId, entry);
         },
         onRuntimeEvent: (event) => {
-          if (state.executionGeneration !== generation) return;
+          if (!isCurrent()) return;
           try {
             this.events.emit("pi-workflows:runtime", { runId, event: cloneRuntimeEvent(event) });
           } catch {
@@ -1108,7 +1170,7 @@ export class WorkflowEngine {
       }
       const live = this.runs.get(runId);
       const run = live?.run;
-      if (run && state.executionGeneration === generation && !isTerminalWorkflow(run.status)) {
+      if (run && isSameBranch() && !isTerminalWorkflow(run.status)) {
         this.setWorkflowStatus(run, "completed", undefined, undefined, result.result);
         live.result = result.result;
       }
@@ -1116,7 +1178,7 @@ export class WorkflowEngine {
     } catch (error: unknown) {
       await runner.waitForCleanup?.();
       const run = this.runs.get(runId)?.run;
-      if (run && state.executionGeneration === generation && !isTerminalWorkflow(run.status)) {
+      if (run && isSameBranch() && !isTerminalWorkflow(run.status)) {
         const message = error instanceof Error ? error.message : String(error);
         const workflowError = error instanceof WorkflowError ? error : wrapError(error);
         if (workflowError.code === WorkflowErrorCode.PROVIDER_USAGE_LIMIT) {
@@ -1147,7 +1209,7 @@ export class WorkflowEngine {
     } finally {
       // Reject any waiters that never settled (agents left in flight).
       const run = this.runs.get(runId)?.run;
-      if (run && state.executionGeneration === generation) this.settleWaiters(runId, run);
+      if (run && isSameBranch()) this.settleWaiters(runId, run);
     }
   }
 
@@ -1168,6 +1230,7 @@ export class WorkflowEngine {
     }
     const run = state.run;
     const executionGeneration = state.executionGeneration;
+    const dispatchEpoch = this.branchEpoch;
     const callIndex = runOptions.callIndex ?? state.generations.size;
     const frameRunId = runOptions.runId ?? runId;
     const nested = frameRunId !== runId;
@@ -1282,6 +1345,10 @@ export class WorkflowEngine {
     const responseId = typeof response === "string" ? response : response.id;
     if (
       state.executionGeneration !== executionGeneration ||
+      this.runs.get(runId) !== state ||
+      this.branchEpoch !== dispatchEpoch ||
+      state.lifecycleSuspended ||
+      this.lifecyclePaused ||
       state.controller.signal.aborted ||
       externalSignal.aborted
     ) {
@@ -1399,6 +1466,14 @@ export class WorkflowEngine {
       externalSignal.removeEventListener("abort", waitAbort);
     });
 
+    if (
+      this.runs.get(runId) !== state ||
+      this.branchEpoch !== dispatchEpoch ||
+      state.lifecycleSuspended ||
+      this.lifecyclePaused
+    ) {
+      throw new WorkflowError("stale workflow terminal", WorkflowErrorCode.WORKFLOW_ABORTED, { recoverable: true });
+    }
     const snapshot = terminal.terminal;
     if (!snapshot)
       throw new WorkflowError("subagent settled without a terminal snapshot", WorkflowErrorCode.AGENT_EXECUTION_ERROR, {
@@ -1924,6 +1999,7 @@ export class WorkflowEngine {
     }
     this.rejectWaiters(new WorkflowWaitAbortedError());
     this.runs.clear();
+    this.admissionsClosed = false;
     this.recoveryBranchGeneration = branchGeneration;
     const runs = replayJournal(entries, {
       onInvalid: (diagnostic) => console.warn(`[pi-workflows] ${diagnostic}`),

package/src/index.ts

@@ -331,8 +331,11 @@ export default function piWorkflows(pi: ExtensionAPI): void {
   let active = false;
   let surfaceRegistered = false;
   const registeredWorkflowCommands = new Set<string>();
-  let branchQuiesce: Promise<{ settled: boolean; pending: string[]; diagnostic?: string }> | undefined;
+  let shutdownQuiesce: Promise<{ settled: boolean; pending: string[]; diagnostic?: string }> | undefined;
   let lifecycleGeneration = 0;
+  let deliveryGeneration = 0;
+  let handledTreeEvent: unknown;
+  let journalBranchAnchor: string | null | undefined;
   let protocolAbortController: AbortController | undefined;
   let sessionCwd = process.cwd();
   let workflowSettings = loadWorkflowSettings(sessionCwd);
@@ -356,6 +359,54 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     return engine;
   };
 
+  // Public bus requests are synchronous snapshots, not a lock across Pi's
+  // later summarization/leaf replacement. Both extensions can veto in any load
+  // order without importing one another's source.
+  pi.events.on("pi:navigation-preflight", (raw: unknown) => {
+    if (!active || !engine?.hasUnsettledWork()) return;
+    const report = (raw as { report?: unknown } | null)?.report;
+    if (typeof report === "function") report("workflows");
+  });
+  const navigationPreflight = (ctx: ExtensionContext): { cancel: true } | undefined => {
+    let busy = false;
+    pi.events.emit("pi:navigation-preflight", {
+      report: () => {
+        busy = true;
+      },
+    });
+    if (!busy) return undefined;
+    const notice =
+      "Navigation blocked while agents or workflows are active or cleaning up. Wait for them to finish, or stop them explicitly and retry.";
+    if (ctx.hasUI) ctx.ui.notify(notice, "warning");
+    else console.warn(`[pi-workflows] ${notice}`);
+    return { cancel: true };
+  };
+  const beginShutdownQuiesce = (): Promise<{ settled: boolean; pending: string[]; diagnostic?: string }> => {
+    if (shutdownQuiesce) return shutdownQuiesce;
+    const closingEngine = engine;
+    if (!closingEngine || closingEngine.isDisposed()) return Promise.resolve({ settled: true, pending: [] });
+    shutdownQuiesce = closingEngine.quiesceForBranchChange().catch((error: unknown) => ({
+      settled: false,
+      pending: [],
+      diagnostic: error instanceof Error ? error.message : String(error),
+    }));
+    return shutdownQuiesce;
+  };
+  // Subagents starts this handshake before retiring the owned-agent RPC. When
+  // workflows shuts down first, its native hook performs the same operation.
+  pi.events.on("pi-workflows:shutdown-quiesce", (raw: unknown) => {
+    if (!active || !engine) return;
+    const respond = (raw as { respond?: unknown } | null)?.respond;
+    if (typeof respond === "function") respond(beginShutdownQuiesce());
+  });
+  pi.events.on("subagents:session_tree_committed", (raw: unknown) => {
+    if (!active || !engine) return;
+    const event = (raw as { event?: unknown } | null)?.event;
+    if (!event || event === handledTreeEvent) return;
+    handledTreeEvent = event;
+    engine.fenceCommittedBranch();
+  });
+
   const clearWidget = (): void => {
     widgetUi?.setWidget("pi-workflows", undefined);
   };
@@ -1098,58 +1149,38 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       registeredWorkflowCommands.add(name);
     }
 
-    // Live progress widget refreshes through the current engine, so its timer
-    // and settlement callback remain safe across session replacement.
-    const beginBranchQuiesce = (): Promise<{ settled: boolean; pending: string[]; diagnostic?: string }> => {
-      if (!branchQuiesce) {
-        let workflowEngine: WorkflowEngine;
-        try {
-          workflowEngine = currentEngine();
-        } catch {
-          return Promise.resolve({ settled: true, pending: [] });
-        }
-        branchQuiesce = workflowEngine.quiesceForBranchChange().then((result) => {
-          if (!result.settled) {
-            console.warn(
-              `[pi-workflows] ${result.diagnostic ?? "branch quiescence did not settle; stale events are quarantined"}`,
-            );
-          }
-          return result;
-        });
-      }
-      return branchQuiesce;
-    };
-
-    pi.events.on("subagents:session_before_tree", () => {
-      void beginBranchQuiesce();
-    });
-
-    pi.on("session_before_tree", async () => {
-      await beginBranchQuiesce();
-    });
-    pi.on("session_tree", (_event, ctx) => {
-      let entries: SessionEntryLike[];
-      try {
-        entries = ctx.sessionManager.getBranch() as unknown as SessionEntryLike[];
-      } catch {
-        return;
-      }
+    // Neither before-event is a commit point. Pi can veto in a later handler,
+    // or summarization may abort after every handler has run.
+    pi.on("session_before_switch", (_event, ctx) => navigationPreflight(ctx));
+    pi.on("session_before_tree", (_event, ctx) => navigationPreflight(ctx));
+    pi.on("session_tree", (event, ctx) => {
       let workflowEngine: WorkflowEngine;
       try {
         workflowEngine = currentEngine();
       } catch {
         return;
       }
-      workflowEngine.suspendLifecycle();
+      if (handledTreeEvent !== event) {
+        // A controller abort can synchronously call stop-owned RPC. Detach the
+        // old subagent records first, regardless of extension load order, so its
+        // managed-stop tombstone cannot be appended on the committed new leaf.
+        pi.events.emit("pi-workflows:session_tree_committed", { event });
+        workflowEngine.fenceCommittedBranch();
+      }
+      handledTreeEvent = event;
+      deliveryGeneration++;
       try {
+        const entries = ctx.sessionManager.getBranch() as unknown as SessionEntryLike[];
+        journalBranchAnchor =
+          ctx.sessionManager.getLeafId?.() ?? (entries.at(-1) as { id?: string } | undefined)?.id ?? null;
         workflowEngine.restore(entries);
+        workflowEngine.resumeLifecycle();
       } catch (error: unknown) {
+        active = false; // never resume an old branch after a failed restore
         console.warn(
           `[pi-workflows] session tree recovery failed: ${error instanceof Error ? error.message : String(error)}`,
         );
       } finally {
-        workflowEngine.resumeLifecycle();
-        branchQuiesce = undefined;
         refreshWidget();
       }
     });
@@ -1170,8 +1201,9 @@ export default function piWorkflows(pi: ExtensionAPI): void {
 
   /** Background-run result delivery: fail-closed, session-bound (A10). */
   const deliverBackgroundResult = async (engine: WorkflowEngine, runId: string): Promise<void> => {
+    const generation = deliveryGeneration;
     const run = await engine.waitFor(runId).catch(() => undefined);
-    if (!run) return;
+    if (!run || generation !== deliveryGeneration) return;
     const header = `Workflow ${run.runId} ${run.status}`;
     const state = engine.getState(runId);
     const finalResult = state?.result ?? run.finalResult;
@@ -1283,6 +1315,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       protocolError = `${PROTOCOL_DIAGNOSTIC} Diagnostic: ${detail}`;
     });
 
+    journalBranchAnchor =
+      ctx.sessionManager.getLeafId?.() ?? (initialEntries.at(-1) as { id?: string } | undefined)?.id ?? null;
     let recoveredEngine: WorkflowEngine | undefined;
     let recoveryError: unknown;
     for (let attempt = 0; attempt < 3 && !recoveredEngine; attempt += 1) {
@@ -1291,7 +1325,24 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         client,
         {
           append(event) {
+            if (generation !== lifecycleGeneration) throw new Error("workflow session retired before journal append");
+            // Every append moves Pi's leaf. Remember the new leaf afterwards;
+            // unrelated appends beneath it remain valid, but a navigated-away
+            // branch must never receive an old terminal fact. Only traverse the
+            // branch when the leaf has moved (or the host cannot report it).
+            if (journalBranchAnchor && ctx.sessionManager.getLeafId?.() !== journalBranchAnchor) {
+              const branch = ctx.sessionManager.getBranch() as Array<{ id?: string }>;
+              if (!branch.some((entry) => entry.id === journalBranchAnchor)) {
+                throw new Error("workflow journal branch changed before append");
+              }
+            }
             pi.appendEntry(JOURNAL_ENTRY_TYPE, event);
+            // Some hosts cannot report a leaf ID. Read the new branch tip after
+            // every append rather than retaining the old (now-ancestor) anchor:
+            // a later run on a sibling would otherwise pass the ancestry check.
+            journalBranchAnchor =
+              ctx.sessionManager.getLeafId?.() ?? (ctx.sessionManager.getBranch() as Array<{ id?: string }>).at(-1)?.id;
+            if (!journalBranchAnchor) throw new Error("workflow journal leaf unavailable after append");
             // Journal writes precede some state mutations; refresh once applied.
             queueMicrotask(() => {
               if (generation === lifecycleGeneration) refreshWidget();
@@ -1421,7 +1472,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
   });
 
   pi.on("session_shutdown", async () => {
-    lifecycleGeneration += 1;
+    deliveryGeneration += 1;
     // Invalidate all long-lived command/tool/widget closures before awaiting
     // engine quiescence; the old session must not accept another run.
     active = false;
@@ -1433,13 +1484,26 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     }
     const closingEngine = engine;
     if (closingEngine) {
-      await closingEngine.quiesceForBranchChange().catch(() => undefined);
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const result = await Promise.race([
+        beginShutdownQuiesce(),
+        new Promise<undefined>((resolve) => {
+          timer = setTimeout(() => resolve(undefined), 6_000);
+        }),
+      ]);
+      if (timer) clearTimeout(timer);
+      if (!result?.settled) {
+        console.warn(
+          `[pi-workflows] shutdown quiescence timed out or failed; ${result?.diagnostic ?? `pending: ${result?.pending.join(", ") ?? "unknown"}`}; late callbacks fenced`,
+        );
+      }
     }
+    lifecycleGeneration += 1;
     protocolAbortController?.abort();
     protocolAbortController = undefined;
     closingEngine?.dispose();
     engine = undefined;
-    branchQuiesce = undefined;
+    shutdownQuiesce = undefined;
     protocolCheck = undefined;
     protocolProbe = undefined;
     protocolInFlight = undefined;