@signalridge/pi-workflows 1.7.5 → 1.9.0

package/src/index.ts

@@ -1,14 +1,11 @@
 import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
 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 { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { sanitizeDisplayText } from "@signalridge/pi-ui";
 import { Type } from "@sinclair/typebox";
-import {
-  DEFAULT_TRIGGER_WORD,
-  deduplicateWorkflowDirective,
-  hasTriggerWord,
-  WORKFLOW_ARMED_DIRECTIVE,
-} from "./arming.js";
+import { DEFAULT_TRIGGER_WORD, hasTriggerWord, WORKFLOW_ARMING_MESSAGE_TYPE, WorkflowTurnArming } from "./arming.js";
 import { BUILTIN_WORKFLOWS, validateBuiltinArgs } from "./builtins.js";
 import { type CommandResult, resolveCodeReviewScope } from "./code-review-scope.js";
 import { type ScriptStartOptions, type ScriptStartResult, WorkflowEngine, WorkflowWaitAbortedError } from "./engine.js";
@@ -28,6 +25,7 @@ import {
   type WorkflowStrengthTable,
 } from "./strengths.js";
 import { liveWidgetLines, showWorkflowNavigator } from "./ui.js";
+import { buildWorkflowUiSnapshot, openOwnedConversation, WorkflowUiBridge, type WorkflowUiSurface } from "./ui-bus.js";
 import {
   loadProjectWorkflowSettings,
   loadWorkflowSettings,
@@ -114,6 +112,15 @@ function textResult(text: string, details: unknown = {}) {
   };
 }
 
+/** Bounded display copies; command notifications never render stored control bytes. */
+function notifyWorkflow(
+  ctx: Pick<ExtensionContext, "ui">,
+  message: string,
+  type: "info" | "warning" | "error" = "info",
+): void {
+  ctx.ui.notify(sanitizeDisplayText(message.slice(0, 8_000), { multiline: true }).slice(0, 4_000), type);
+}
+
 /**
  * Run one command for diff discovery. argv array, never a shell string — a
  * branch name or path reaches this from user input.
@@ -335,6 +342,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
   let shutdownQuiesce: Promise<{ settled: boolean; pending: string[]; diagnostic?: string }> | undefined;
   let lifecycleGeneration = 0;
   let deliveryGeneration = 0;
+  const deliveryObservers = new Map<string, string>();
   let handledTreeEvent: unknown;
   let journalBranchAnchor: string | null | undefined;
   let protocolAbortController: AbortController | undefined;
@@ -343,9 +351,24 @@ export default function piWorkflows(pi: ExtensionAPI): void {
   let effortLevel: "off" | "high" | "ultra" = workflowSettings.effort;
   let triggerKeyword: string | undefined = workflowSettings.keywordTriggerWord;
   let keywordTriggerEnabled = workflowSettings.keywordTriggerEnabled;
-  /** Per-session delivery endpoint for background-run results (A10 fail-closed). */
-  let deliverResult: ((text: string, details?: unknown) => void) | undefined;
-  /** Pending deliveries for runs that settled before a session endpoint was bound (A10). */
+  /** Public sends are void: acceptance is checked against the owning branch. */
+  let deliveryContext: ExtensionContext | undefined;
+  let deliveryTimer: ReturnType<typeof setTimeout> | undefined;
+  let inputPreparing = false;
+  const turnArming = new WorkflowTurnArming();
+  let compacting = false;
+  let navigating = false;
+  let deliveryBranchAnchor: string | null | undefined;
+  const DELIVERY_WAKE_PREFIX = "[pi-workflows:wake:";
+  const DELIVERY_WAKE_TEXT = "Workflow results are ready in the preceding context.";
+  const MAX_WAKE_ADMISSIONS = 256;
+  // Private, one-use admissions survive an earlier awaited input handler, not
+  // a lifecycle retirement. Missing/evicted IDs fail closed without tombstones.
+  const wakeAdmissions = new Map<
+    string,
+    { generation: number; context: ExtensionContext; engine: WorkflowEngine; anchor: string | null | undefined }
+  >();
+  /** Pending deliveries for completed runs, including durable recovery (A10). */
   const pendingDeliveryMarkers = new Map<string, { text: string; timestamp: number }>();
   const PENDING_DELIVERY_TYPE = "pi-workflows:pending-delivery";
   const PENDING_DELIVERY_ACK_TYPE = "pi-workflows:pending-delivery-ack";
@@ -353,6 +376,9 @@ export default function piWorkflows(pi: ExtensionAPI): void {
   const PENDING_DELIVERY_TTL_MS = 7 * 24 * 60 * 60 * 1_000;
   let widgetTimer: ReturnType<typeof setInterval> | undefined;
   let widgetUi: ExtensionContext["ui"] | undefined;
+  let workflowUiBridge: WorkflowUiBridge | undefined;
+  let workflowUiSurfaceId = randomUUID();
+  let refreshQueued = false;
 
   const currentEngine = (): WorkflowEngine => {
     if (!active || !engine || engine.isDisposed())
@@ -378,25 +404,52 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     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");
+    if (ctx.hasUI) notifyWorkflow(ctx, notice, "warning");
     else console.warn(`[pi-workflows] ${notice}`);
     return { cancel: true };
   };
+  const invalidateDelivery = (): void => {
+    workflowUiBridge?.retire(workflowUiSurfaceId);
+    workflowUiSurfaceId = randomUUID();
+    deliveryGeneration++;
+    deliveryObservers.clear();
+    turnArming.retire();
+    wakeAdmissions.clear();
+    if (deliveryTimer) clearTimeout(deliveryTimer);
+    deliveryTimer = undefined;
+  };
   const beginShutdownQuiesce = (): Promise<{ settled: boolean; pending: string[]; diagnostic?: string }> => {
     if (shutdownQuiesce) return shutdownQuiesce;
+    // Retire admission and delivery BEFORE aborting children, including when
+    // subagents initiates shutdown first. Journal cleanup retains its separate
+    // lifecycle generation until the native shutdown hook finishes quiescence.
+    active = false;
+    invalidateDelivery();
+    deliveryContext = undefined;
     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),
-    }));
+    if (!closingEngine || closingEngine.isDisposed()) {
+      shutdownQuiesce = Promise.resolve({ settled: true, pending: [] });
+      return shutdownQuiesce;
+    }
+    // Publish the handshake promise before abort can synchronously re-enter
+    // the bus through an owned-child cleanup callback.
+    let settle: (result: { settled: boolean; pending: string[]; diagnostic?: string }) => void = () => {};
+    shutdownQuiesce = new Promise((resolve) => {
+      settle = resolve;
+    });
+    void closingEngine.quiesceForBranchChange().then(settle, (error: unknown) => {
+      settle({
+        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;
+    if (!engine) return;
     const respond = (raw as { respond?: unknown } | null)?.respond;
     if (typeof respond === "function") respond(beginShutdownQuiesce());
   });
@@ -405,6 +458,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     const event = (raw as { event?: unknown } | null)?.event;
     if (!event || event === handledTreeEvent) return;
     handledTreeEvent = event;
+    invalidateDelivery();
+    pendingDeliveryMarkers.clear();
     engine.fenceCommittedBranch();
   });
 
@@ -427,16 +482,55 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       .list()
       .map((summary) => workflowEngine.getRun(String(summary.runId)))
       .filter((run): run is NonNullable<typeof run> => run !== undefined);
-    const lines = liveWidgetLines(runs, workflowSettings.progressMode, workflowSettings.maxAgentsShown);
-    tui.setWidget("pi-workflows", lines.length > 0 ? lines : undefined);
-    if (lines.length > 0 && !widgetTimer) {
+    const hasActive = runs.some((run) => !["completed", "failed", "stopped"].includes(run.status));
+    const surfaceId = workflowUiSurfaceId;
+    tui.setWidget(
+      "pi-workflows",
+      hasActive
+        ? (host, theme) => ({
+            render(width) {
+              if (
+                !active ||
+                engine !== workflowEngine ||
+                workflowEngine.isDisposed() ||
+                workflowUiSurfaceId !== surfaceId ||
+                !Number.isFinite(width) ||
+                width < 1
+              )
+                return [];
+              const height = Number.isFinite(host.terminal.rows) ? Math.max(0, host.terminal.rows) : 24;
+              const rowBudget = Math.max(1, Math.min(12, Math.floor(height / 4)));
+              return liveWidgetLines(
+                runs,
+                workflowSettings.progressMode,
+                workflowSettings.maxAgentsShown,
+                rowBudget,
+              ).map((line, index) =>
+                truncateToWidth(theme.fg(index === 0 ? "accent" : "muted", line), Math.floor(width)),
+              );
+            },
+            invalidate() {},
+          })
+        : undefined,
+    );
+    workflowUiBridge?.publish();
+    if (hasActive && !widgetTimer) {
       widgetTimer = setInterval(refreshWidget, 2_000);
-    } else if (lines.length === 0 && widgetTimer) {
+    } else if (!hasActive && widgetTimer) {
       clearInterval(widgetTimer);
       widgetTimer = undefined;
     }
   };
-  const notifyRunChanged = (): void => refreshWidget();
+  const notifyRunChanged = (): void => {
+    if (refreshQueued) return;
+    refreshQueued = true;
+    const surfaceId = workflowUiSurfaceId;
+    queueMicrotask(() => {
+      refreshQueued = false;
+      if (surfaceId !== workflowUiSurfaceId) return;
+      refreshWidget();
+    });
+  };
 
   const DEFAULT_EXCLUDED_TOOLS = ["workflow", "workflow_control"] as const;
 
@@ -484,17 +578,98 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     throw new Error("Provide either `script` or `name`.");
   };
 
+  const showNavigator = async (ctx: ExtensionContext, initialRunId?: string): Promise<void> => {
+    if (ctx.mode !== "tui" || !ctx.hasUI) {
+      await showWorkflowNavigator(ctx, currentEngine, { initialRunId });
+      return;
+    }
+    const selectedEngine = currentEngine();
+    const surfaceId = workflowUiSurfaceId;
+    const manager = ctx.sessionManager;
+    const sessionId = manager.getSessionId();
+    const resolve = (): WorkflowEngine => {
+      if (
+        surfaceId !== workflowUiSurfaceId ||
+        selectedEngine !== currentEngine() ||
+        manager !== deliveryContext?.sessionManager ||
+        manager.getSessionId() !== sessionId ||
+        !ownsDeliveryBranch()
+      )
+        throw new Error("Workflow inspector belongs to a retired session or branch.");
+      return selectedEngine;
+    };
+    await showWorkflowNavigator(ctx, resolve, {
+      initialRunId,
+      getPresentation: (runId) => resolve().getInspection(runId),
+      openConversation: async (runId, callIndex) => {
+        const current = resolve();
+        if (!/^(?:0|[1-9]\d*)$/u.test(callIndex)) throw new Error("This call has no retained root conversation.");
+        const state = current.getState(runId);
+        const run = state?.run;
+        const agentId = run?.agentIds[callIndex];
+        const attempt = run?.attempts[callIndex];
+        if (!state || !run || !agentId || !Number.isInteger(attempt) || (attempt ?? 0) < 1)
+          throw new Error("No retained conversation is available for this call.");
+        const executionGeneration = state.executionGeneration;
+        await openOwnedConversation(
+          pi.events,
+          agentId,
+          { extension: "pi-workflows", runId, nodeId: `call-${callIndex}`, attemptId: `attempt-${attempt}` },
+          () => {
+            try {
+              return (
+                resolve().getState(runId) === state &&
+                state.executionGeneration === executionGeneration &&
+                run.agentIds[callIndex] === agentId &&
+                run.attempts[callIndex] === attempt
+              );
+            } catch {
+              return false;
+            }
+          },
+        );
+      },
+    });
+  };
+
+  const workflowUiSurface = (): WorkflowUiSurface | undefined => {
+    const ctx = deliveryContext;
+    if (!active || !engine || engine.isDisposed() || ctx?.mode !== "tui" || !ctx.hasUI || !ownsDeliveryBranch())
+      return undefined;
+    return {
+      snapshot: buildWorkflowUiSnapshot(engine, workflowUiSurfaceId),
+      open: (runId) => showNavigator(ctx, runId),
+      notifyError: (message) => notifyWorkflow(ctx, message, "error"),
+    };
+  };
+
   const registerSurface = (): void => {
     if (active) return;
     active = true;
     const workflowEngine = currentEngine();
     workflowEngine.onRunSettled = notifyRunChanged;
+    workflowEngine.onBackgroundExecution = (runId) => void deliverBackgroundResult(workflowEngine, runId);
     workflowEngine.onRuntimeEvent = notifyRunChanged;
+    workflowEngine.onInspectionChanged = notifyRunChanged;
+    if (typeof pi.registerMessageRenderer === "function") {
+      pi.registerMessageRenderer("pi-workflows:delivery", (message, { expanded }, theme) => {
+        const original =
+          typeof message.content === "string"
+            ? message.content
+            : message.content
+                .filter((part) => part.type === "text")
+                .map((part) => part.text)
+                .join("\n");
+        const display = sanitizeDisplayText(original, { multiline: true });
+        return new Text(theme.fg("toolOutput", display.slice(0, expanded ? 8000 : 2000)), 0, 0);
+      });
+    }
     // `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
     // re-run every finished call untabled.
     workflowEngine.strengths = () => workflowSettings.strengths;
+    workflowEngine.loadSavedWorkflow = resolveNestedWorkflow;
     // Command/tool registrations persist across session replacement, but the
     // widget belongs to the newly restored engine and must be refreshed too.
     refreshWidget();
@@ -519,11 +694,13 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         ],
         parameters: WorkflowToolSchema,
         renderCall(args, theme) {
-          const label = args.name ?? (args.script !== undefined ? "script" : "");
+          const label = sanitizeDisplayText(args.name ?? (args.script !== undefined ? "script" : ""));
           return new Text(theme.fg("toolTitle", theme.bold(`Workflow ${label}`)), 0, 0);
         },
         renderResult(result, { expanded, isPartial }, theme) {
-          const text = result.content[0]?.type === "text" ? result.content[0].text : "";
+          const text = sanitizeDisplayText(result.content[0]?.type === "text" ? result.content[0].text : "", {
+            multiline: true,
+          });
           if (isPartial) return new Text(theme.fg("warning", "Workflow running…"), 0, 0);
           const preview = expanded ? text.slice(0, 8_000) : text.split("\n").slice(0, 4).join("\n");
           return new Text(
@@ -585,7 +762,6 @@ export default function piWorkflows(pi: ExtensionAPI): void {
                 replacement,
               );
               if (!resumed) return textResult(`Workflow run not found: ${params.resumeFromRunId}`);
-              if (resumed.background) void deliverBackgroundResult(workflowEngine, resumed.runId);
               return textResult(formatStart(resumed), resumed);
             }
             const result = await workflowEngine.start(script, options);
@@ -610,10 +786,16 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           "List, inspect, pause, resume, stop, or remove workflow runs with bounded machine-readable output.",
         parameters: ControlSchema,
         renderCall(args, theme) {
-          return new Text(theme.fg("toolTitle", theme.bold(`Workflow control: ${args.action ?? ""}`)), 0, 0);
+          return new Text(
+            theme.fg("toolTitle", theme.bold(`Workflow control: ${sanitizeDisplayText(args.action ?? "")}`)),
+            0,
+            0,
+          );
         },
         renderResult(result, { expanded }, theme) {
-          const text = result.content[0]?.type === "text" ? result.content[0].text : "";
+          const text = sanitizeDisplayText(result.content[0]?.type === "text" ? result.content[0].text : "", {
+            multiline: true,
+          });
           return new Text(theme.fg("dim", expanded ? text.slice(0, 8_000) : text.slice(0, 1_000)), 0, 0);
         },
         async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
@@ -651,21 +833,21 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           try {
             return currentEngine();
           } catch (error: unknown) {
-            ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+            notifyWorkflow(ctx, error instanceof Error ? error.message : String(error), "error");
             return undefined;
           }
         };
         if (!subcommand) {
-          await showWorkflowNavigator(ctx, currentEngine);
+          await showNavigator(ctx);
           return;
         }
         if (subcommand === "run") {
           if (!restArgs) {
-            ctx.ui.notify("/workflows run <prompt-or-script>", "warning");
+            notifyWorkflow(ctx, "/workflows run <prompt-or-script>", "warning");
             return;
           }
           const runId = await runWorkflowFromPrompt(ctx, restArgs);
-          if (runId) ctx.ui.notify(`Workflow started in background: ${runId}`, "info");
+          if (runId) notifyWorkflow(ctx, `Workflow started in background: ${runId}`, "info");
           return;
         }
         if (subcommand === "status") {
@@ -674,14 +856,15 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           if (restArgs) {
             const run = workflowEngine.getRun(restArgs);
             if (!run) {
-              ctx.ui.notify(`Workflow run not found: ${restArgs}`, "warning");
+              notifyWorkflow(ctx, `Workflow run not found: ${restArgs}`, "warning");
               return;
             }
-            ctx.ui.notify(`${run.runId} · ${run.status} · ${String(run.meta?.name ?? run.runId)}`, "info");
+            notifyWorkflow(ctx, `${run.runId} · ${run.status} · ${String(run.meta?.name ?? run.runId)}`, "info");
             return;
           }
           const runs = workflowEngine.list();
-          ctx.ui.notify(
+          notifyWorkflow(
+            ctx,
             runs.length === 0
               ? "No workflow runs."
               : runs.map((r) => `${r.runId} · ${r.status} · ${String(r.name)}`).join("\n"),
@@ -694,11 +877,16 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           if (!workflowEngine) return;
           const runId = restArgs || String(workflowEngine.list()[0]?.runId ?? "");
           if (!runId) {
-            ctx.ui.notify("No workflow runs to watch.", "warning");
+            notifyWorkflow(ctx, "No workflow runs to watch.", "warning");
+            return;
+          }
+          const run = workflowEngine.getRun(runId);
+          if (!run) {
+            notifyWorkflow(ctx, `Workflow run not found: ${runId}`, "warning");
             return;
           }
-          const run = await workflowEngine.waitFor(runId).catch(() => undefined);
-          if (run) ctx.ui.notify(`${run.runId} settled as ${run.status}`, "info");
+          if (ctx.mode === "tui" && ctx.hasUI) await showNavigator(ctx, runId);
+          else notifyWorkflow(ctx, `${run.runId} · ${run.status} — use workflow_control outside TUI.`, "info");
           return;
         }
         if (subcommand === "stop" || subcommand === "pause" || subcommand === "resume" || subcommand === "rm") {
@@ -712,7 +900,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           );
           if (!runId) {
             const destructive = subcommand === "stop" || subcommand === "rm";
-            ctx.ui.notify(
+            notifyWorkflow(
+              ctx,
               destructive
                 ? `/workflows ${subcommand} <runId> — a run id is required; /workflows status lists them`
                 : `/workflows ${subcommand} <runId>`,
@@ -725,16 +914,16 @@ export default function piWorkflows(pi: ExtensionAPI): void {
             if (!workflowEngine) return;
             await workflowEngine.control(subcommand, runId);
             if (subcommand === "resume") void deliverBackgroundResult(workflowEngine, runId);
-            ctx.ui.notify(`Workflow ${subcommand} requested: ${runId}`, "info");
+            notifyWorkflow(ctx, `Workflow ${subcommand} requested: ${runId}`, "info");
           } catch (error: unknown) {
-            ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+            notifyWorkflow(ctx, error instanceof Error ? error.message : String(error), "error");
           }
           return;
         }
         if (subcommand === "save") {
           const name = rest[0] ?? "";
           if (!name) {
-            ctx.ui.notify("/workflows save <name> [runId]", "warning");
+            notifyWorkflow(ctx, "/workflows save <name> [runId]", "warning");
             return;
           }
           const workflowEngine = engineForCommand();
@@ -742,13 +931,13 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           // Fallback to most recent run when runId omitted — matches upstream runs.find(r=>r.script)
           const runId = rest[1] ?? String(workflowEngine.list()[0]?.runId ?? "");
           if (!runId) {
-            ctx.ui.notify("No workflow runs to save.", "warning");
+            notifyWorkflow(ctx, "No workflow runs to save.", "warning");
             return;
           }
           try {
             await saveWorkflowFromRun(ctx, name, runId);
           } catch (error: unknown) {
-            ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+            notifyWorkflow(ctx, error instanceof Error ? error.message : String(error), "error");
           }
           return;
         }
@@ -820,15 +1009,19 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           };
           const [strength, target] = rest;
           if (strength === undefined) {
-            ctx.ui.notify(describe(), "info");
+            notifyWorkflow(ctx, describe(), "info");
             return;
           }
           if (!isWorkflowStrength(strength)) {
-            ctx.ui.notify(`"${strength}" is not a workflow strength. Use one of ${WORKFLOW_STRENGTH_LIST}.`, "warning");
+            notifyWorkflow(
+              ctx,
+              `"${strength}" is not a workflow strength. Use one of ${WORKFLOW_STRENGTH_LIST}.`,
+              "warning",
+            );
             return;
           }
           if (target === undefined || rest.length !== 2) {
-            ctx.ui.notify(`/workflows strength [<${WORKFLOW_STRENGTHS.join("|")}> <tier>|off]`, "warning");
+            notifyWorkflow(ctx, `/workflows strength [<${WORKFLOW_STRENGTHS.join("|")}> <tier>|off]`, "warning");
             return;
           }
           // `off` reads as "unset" unless the host really defines a tier by
@@ -837,7 +1030,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           // to clear one.
           const unset = target === "off" && catalogue?.includes("off") !== true;
           if (!unset && catalogue && !catalogue.includes(target)) {
-            ctx.ui.notify(
+            notifyWorkflow(
+              ctx,
               `"${target}" is not a tier this host defines. Available: ${catalogue.join(", ") || "(none)"}. ` +
                 "Define it in /agents → Model tiers first.",
               "warning",
@@ -850,7 +1044,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
             // table, and this key replaces rather than merges — so the other two
             // strengths would go from routed to unmapped as a side effect of
             // setting this one. Refusing costs a retry; writing costs a run.
-            ctx.ui.notify(
+            notifyWorkflow(
+              ctx,
               "The tier catalogue is unavailable, so the current table cannot be read. " +
                 "Retry once the managed peer is reachable.",
               "warning",
@@ -870,7 +1065,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           try {
             persistWorkflowSetting({ strengths: unset ? others : { ...others, [strength]: target } });
           } catch (error: unknown) {
-            ctx.ui.notify(
+            notifyWorkflow(
+              ctx,
               `Could not save workflow strength routing: ${error instanceof Error ? error.message : String(error)}`,
               "warning",
             );
@@ -897,10 +1093,10 @@ export default function piWorkflows(pi: ExtensionAPI): void {
                 "than as the clear keyword. To leave a strength unmapped here, remove its entry from the " +
                 "`strengths` object in this project's settings.json."
               : "";
-          ctx.ui.notify(`${describe()}${shadowed}`, "info");
+          notifyWorkflow(ctx, `${describe()}${shadowed}`, "info");
           return;
         }
-        ctx.ui.notify(`Unknown /workflows subcommand: ${subcommand}`, "warning");
+        notifyWorkflow(ctx, `Unknown /workflows subcommand: ${subcommand}`, "warning");
       },
     });
 
@@ -911,7 +1107,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         const tokens = args.trim().split(/\s+/).filter(Boolean);
         const action = tokens[0] ?? "status";
         if (action === "status") {
-          ctx.ui.notify(
+          notifyWorkflow(
+            ctx,
             `Workflow progress: ${workflowSettings.progressMode}, max agents shown: ${workflowSettings.maxAgentsShown}`,
             "info",
           );
@@ -923,23 +1120,25 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         } else if (action === "max") {
           const max = Number(tokens[1]);
           if (!Number.isInteger(max) || max < 1 || max > 32) {
-            ctx.ui.notify("Usage: /workflows-progress max <1-32>", "warning");
+            notifyWorkflow(ctx, "Usage: /workflows-progress max <1-32>", "warning");
             return;
           }
           patch = { maxAgentsShown: max };
         } else {
-          ctx.ui.notify("Usage: /workflows-progress compact|detailed|status|max <N>", "warning");
+          notifyWorkflow(ctx, "Usage: /workflows-progress compact|detailed|status|max <N>", "warning");
           return;
         }
         try {
           persistWorkflowSetting(patch);
           refreshWidget();
-          ctx.ui.notify(
+          notifyWorkflow(
+            ctx,
             `Workflow progress set to ${workflowSettings.progressMode}, max ${workflowSettings.maxAgentsShown}.`,
             "info",
           );
         } catch (error: unknown) {
-          ctx.ui.notify(
+          notifyWorkflow(
+            ctx,
             `Could not save workflow progress settings: ${error instanceof Error ? error.message : String(error)}`,
             "warning",
           );
@@ -950,7 +1149,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     // /workflows-trigger: keyword arming (A5). Typing the bounded word
     // `workflow`/`workflows` — or a configured synonym — in an ordinary message
     // counts as an explicit opt-in to multi-agent orchestration, and the message
-    // is annotated to say so. Arming AUTHORIZES the tool; it never forces a run,
+    // receives hidden model guidance. Arming AUTHORIZES the tool; it never forces a run,
     // and it never opens UI. A user asking a question about workflows still gets
     // an ordinary answer.
     const TRIGGER_WORD_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/u;
@@ -968,24 +1167,25 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         if (token === "off") {
           keywordTriggerEnabled = false;
           persistTriggerSettings();
-          ctx.ui.notify("Workflow keyword trigger disabled.", "info");
+          notifyWorkflow(ctx, "Workflow keyword trigger disabled.", "info");
           return;
         }
         if (token === "on") {
           keywordTriggerEnabled = true;
           persistTriggerSettings();
-          ctx.ui.notify(`Workflow keyword trigger armed on "${triggerKeyword ?? DEFAULT_TRIGGER_WORD}".`, "info");
+          notifyWorkflow(ctx, `Workflow keyword trigger armed on "${triggerKeyword ?? DEFAULT_TRIGGER_WORD}".`, "info");
           return;
         }
         if (token === "reset") {
           triggerKeyword = undefined;
           keywordTriggerEnabled = true;
           persistTriggerSettings();
-          ctx.ui.notify(`Workflow keyword trigger reset to default "${DEFAULT_TRIGGER_WORD}".`, "info");
+          notifyWorkflow(ctx, `Workflow keyword trigger reset to default "${DEFAULT_TRIGGER_WORD}".`, "info");
           return;
         }
         if (token === "status") {
-          ctx.ui.notify(
+          notifyWorkflow(
+            ctx,
             `Workflow keyword trigger: ${keywordTriggerEnabled ? "armed" : "disabled"} on "${triggerKeyword ?? DEFAULT_TRIGGER_WORD}"`,
             "info",
           );
@@ -993,87 +1193,80 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         }
         const keyword = token === "set" ? (args.trim().split(/\s+/)[1] ?? "") : token;
         if (!TRIGGER_WORD_PATTERN.test(keyword)) {
-          ctx.ui.notify("Usage: /workflows-trigger set <one-word-keyword> | off | on | reset | status", "warning");
+          notifyWorkflow(
+            ctx,
+            "Usage: /workflows-trigger set <one-word-keyword> | off | on | reset | status",
+            "warning",
+          );
           return;
         }
         triggerKeyword = keyword.toLowerCase();
         keywordTriggerEnabled = true;
         persistTriggerSettings();
-        ctx.ui.notify(`Workflow keyword trigger armed on "${keyword}".`, "info");
+        notifyWorkflow(ctx, `Workflow keyword trigger armed on "${keyword}".`, "info");
       },
     });
 
-    // Keyword arming input hook (A5). The message is annotated rather than
-    // acted on: the model is told it may use the `workflow` tool and may still
+    // Keyword arming input hook (A5). Record provenance, never append model
+    // guidance to native user text: the model may use `workflow` and may still
     // decline, which is what keeps "how do workflows work?" an ordinary
     // question. Nothing is swallowed and no UI opens.
-    pi.on("input", (event) => {
-      if (event.source === "extension") return { action: "continue" as const };
-      const deduplicatedText = deduplicateWorkflowDirective(event.text);
-      if (deduplicatedText !== event.text) {
+    pi.on("input", (event, ctx) => {
+      const ownWake = event.source === "extension" && event.text.startsWith(DELIVERY_WAKE_PREFIX);
+      if (ownWake) {
+        const admission = wakeAdmissions.get(event.text);
+        wakeAdmissions.delete(event.text); // exact, one-use ownership, even on rejection
+        if (
+          !admission ||
+          admission.generation !== deliveryGeneration ||
+          admission.context !== deliveryContext ||
+          admission.engine !== engine ||
+          !canDeliver()
+        ) {
+          turnArming.retire();
+          return { action: "handled" as const };
+        }
+        try {
+          if (
+            admission.anchor &&
+            !admission.context.sessionManager.getBranch().some((entry) => entry.id === admission.anchor)
+          ) {
+            turnArming.retire();
+            return { action: "handled" as const };
+          }
+        } catch {
+          turnArming.retire();
+          return { action: "handled" as const };
+        }
+      }
+      inputPreparing = true;
+      navigating = false; // a fresh prompt supersedes an uncommitted navigation
+      if (deliveryTimer) clearTimeout(deliveryTimer);
+      deliveryTimer = undefined;
+      const text = event.text;
+      const explicitTrigger = keywordTriggerEnabled && hasTriggerWord(text, triggerKeyword);
+      const substantive = effortLevel !== "off" && text.trim().length >= 16 && !text.trim().startsWith("/");
+      turnArming.observe(
+        { ...event, text },
+        ctx,
+        active && (explicitTrigger || substantive),
+        effortLevel,
+        explicitTrigger,
+      );
+      if (ownWake)
         return {
           action: "transform" as const,
-          text: deduplicatedText,
+          text: DELIVERY_WAKE_TEXT,
           ...(event.images ? { images: event.images } : {}),
         };
-      }
-      const explicitTrigger = keywordTriggerEnabled && hasTriggerWord(event.text, triggerKeyword);
-      const substantive = effortLevel !== "off" && event.text.trim().length >= 16 && !event.text.trim().startsWith("/");
-      if (!explicitTrigger && !substantive) return { action: "continue" as const };
-      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. 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."
-            : "";
-      return {
-        action: "transform" as const,
-        text: `${event.text}\n\n${WORKFLOW_ARMED_DIRECTIVE}${effortDirective ? `\n${effortDirective}` : ""}`,
-        ...(event.images ? { images: event.images } : {}),
-      };
+      return { action: "continue" as const };
     });
 
-    // Input transforms can be chained with handlers loaded after this package.
-    // Normalize only our own repeated marker again at the final context boundary;
-    // unrelated plugin content and hooks remain untouched.
-    pi.on("context", (event) => {
-      type UserMessage = Extract<(typeof event.messages)[number], { role: "user" }>;
-      let lastUserIndex = -1;
-      let lastUserMessage: UserMessage | undefined;
-      for (let index = 0; index < event.messages.length; index += 1) {
-        const message = event.messages[index];
-        if (message && "role" in message && message.role === "user") {
-          lastUserIndex = index;
-          lastUserMessage = message;
-        }
-      }
-      const message = lastUserMessage;
-      if (lastUserIndex < 0 || !message || !("content" in message)) return;
-      let seen = false;
-      const deduplicate = (text: string): string =>
-        text.replaceAll(WORKFLOW_ARMED_DIRECTIVE, (directive) => {
-          if (seen) return "";
-          seen = true;
-          return directive;
-        });
-      const content =
-        typeof message.content === "string"
-          ? deduplicate(message.content)
-          : message.content.map((part) => {
-              if (part.type !== "text") return part;
-              const text = deduplicate(part.text);
-              return text === part.text ? part : { ...part, text };
-            });
-      if (
-        content === message.content ||
-        (Array.isArray(content) && content.every((part, index) => part === message.content[index]))
-      )
-        return;
-      const messages = event.messages.slice();
-      messages[lastUserIndex] = { ...message, content };
-      return { messages };
-    });
+    // Hidden guidance is turn-local, including on reload and after later hooks
+    // navigate while before_agent_start is awaiting. Never edit native history.
+    // Request-local overlays never enter native history or summarization.
+    pi.on("message_start", (event, ctx) => turnArming.messageStarted(event, ctx));
+    pi.on("context", (event, ctx) => turnArming.filterContext(event, ctx));
 
     // Standing effort mode mirrors the reference: it auto-arms substantive
     // interactive messages but remains guidance, not an inferred spend ceiling.
@@ -1082,7 +1275,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       handler: async (args: string, ctx: ExtensionCommandContext) => {
         const level = args.trim().toLowerCase();
         if (level !== "off" && level !== "high" && level !== "ultra") {
-          ctx.ui.notify(`Effort is currently "${effortLevel}". Usage: /effort off|high|ultra`, "info");
+          notifyWorkflow(ctx, `Effort is currently "${effortLevel}". Usage: /effort off|high|ultra`, "info");
           return;
         }
         effortLevel = level;
@@ -1091,7 +1284,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         } catch {
           /* warning is non-fatal */
         }
-        ctx.ui.notify(
+        notifyWorkflow(
+          ctx,
           level === "off"
             ? "Effort off — messages are no longer auto-armed."
             : `Effort ${level} enabled for substantive messages.`,
@@ -1108,7 +1302,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         } catch {
           /* warning is non-fatal */
         }
-        ctx.ui.notify(
+        notifyWorkflow(
+          ctx,
           effortLevel === "off"
             ? "Ultracode off."
             : "Ultracode on — substantive messages use exhaustive workflow guidance.",
@@ -1136,7 +1331,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           if (name === "code-review") {
             const cwd = ctx.cwd;
             const scope = resolveCodeReviewScope(text, (file, argv) => runCommand(file, argv, cwd));
-            for (const notice of scope.notices) ctx.ui.notify(notice, "warning");
+            for (const notice of scope.notices) notifyWorkflow(ctx, notice, "warning");
             if (!scope.diff.trim()) return;
             scriptArgs = { diff: scope.diff, diffSource: scope.diffSource };
           } else {
@@ -1145,7 +1340,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           try {
             validateBuiltinArgs(name, scriptArgs);
           } catch (error: unknown) {
-            ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+            notifyWorkflow(ctx, error instanceof Error ? error.message : String(error), "warning");
             return;
           }
           const options: ScriptStartOptions = {
@@ -1160,9 +1355,9 @@ export default function piWorkflows(pi: ExtensionAPI): void {
             const workflowEngine = currentEngine();
             const result = await workflowEngine.start(descriptor.script, options);
             void deliverBackgroundResult(workflowEngine, result.runId);
-            ctx.ui.notify(`Workflow ${name} started in background: ${result.runId}`, "info");
+            notifyWorkflow(ctx, `Workflow ${name} started in background: ${result.runId}`, "info");
           } catch (error: unknown) {
-            ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+            notifyWorkflow(ctx, error instanceof Error ? error.message : String(error), "error");
           }
         },
       });
@@ -1171,8 +1366,64 @@ export default function piWorkflows(pi: ExtensionAPI): void {
 
     // 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));
+    const beforeNavigation = (ctx: ExtensionContext): { cancel: true } | undefined => {
+      turnArming.retire();
+      const veto = navigationPreflight(ctx);
+      if (!veto) {
+        navigating = true;
+        if (deliveryTimer) clearTimeout(deliveryTimer);
+        deliveryTimer = undefined;
+      }
+      return veto;
+    };
+    pi.on("session_before_switch", (_event, ctx) => beforeNavigation(ctx));
+    pi.on("session_before_tree", (event, ctx) => {
+      // The public preparation array is mutable; remove only legacy owned
+      // custom guidance, never quoted user content or stored history.
+      const entries = event.preparation?.entriesToSummarize ?? [];
+      for (let index = entries.length - 1; index >= 0; index--) {
+        const entry = entries[index];
+        if (entry?.type === "custom_message" && entry.customType === WORKFLOW_ARMING_MESSAGE_TYPE)
+          entries.splice(index, 1);
+      }
+      return beforeNavigation(ctx);
+    });
+    pi.on("session_before_fork", (_event, ctx) => beforeNavigation(ctx));
+    pi.on("before_agent_start", (event, ctx) => {
+      inputPreparing = true;
+      if (deliveryTimer) clearTimeout(deliveryTimer);
+      deliveryTimer = undefined;
+      return turnArming.consume(event, ctx);
+    });
+    pi.on("agent_start", () => {
+      inputPreparing = false;
+    });
+    pi.on("session_before_compact", (event) => {
+      for (const messages of [
+        event.preparation?.messagesToSummarize ?? [],
+        event.preparation?.turnPrefixMessages ?? [],
+      ]) {
+        for (let index = messages.length - 1; index >= 0; index--) {
+          const message = messages[index];
+          if (message?.role === "custom" && message.customType === WORKFLOW_ARMING_MESSAGE_TYPE)
+            messages.splice(index, 1);
+        }
+      }
+      compacting = true;
+      if (deliveryTimer) clearTimeout(deliveryTimer);
+      deliveryTimer = undefined;
+    });
+    const afterCompact = (): void => {
+      compacting = false;
+      schedulePendingDeliveries();
+    };
+    pi.on("session_compact", afterCompact);
+    pi.on("session_compact_failed", afterCompact);
+    pi.on("agent_settled", () => {
+      turnArming.retire();
+      inputPreparing = false;
+      schedulePendingDeliveries();
+    });
     pi.on("session_tree", (event, ctx) => {
       let workflowEngine: WorkflowEngine;
       try {
@@ -1180,6 +1431,11 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       } catch {
         return;
       }
+      invalidateDelivery();
+      pendingDeliveryMarkers.clear();
+      inputPreparing = false;
+      compacting = false;
+      navigating = false;
       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
@@ -1188,13 +1444,16 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         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();
+        deliveryContext = ctx;
+        deliveryBranchAnchor = journalBranchAnchor;
+        hydratePendingDeliveries(entries);
+        schedulePendingDeliveries();
       } catch (error: unknown) {
         active = false; // never resume an old branch after a failed restore
         console.warn(
@@ -1220,12 +1479,28 @@ 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 deliverBackgroundResult = async (workflowEngine: WorkflowEngine, runId: string): Promise<void> => {
     const generation = deliveryGeneration;
-    const run = await engine.waitFor(runId).catch(() => undefined);
-    if (!run || generation !== deliveryGeneration) return;
+    const executionGeneration = workflowEngine.getState(runId)?.executionGeneration;
+    const observerKey = `${generation}:${executionGeneration}`;
+    if (deliveryObservers.get(runId) === observerKey) return;
+    deliveryObservers.set(runId, observerKey);
+    while (deliveryObservers.size > 256) {
+      const oldest = deliveryObservers.keys().next().value;
+      if (oldest === undefined) break;
+      deliveryObservers.delete(oldest);
+    }
+    const run = await workflowEngine.waitFor(runId).catch(() => undefined);
+    if (
+      !run ||
+      generation !== deliveryGeneration ||
+      workflowEngine !== engine ||
+      executionGeneration !== workflowEngine.getState(runId)?.executionGeneration ||
+      !["completed", "failed", "stopped"].includes(run.status)
+    )
+      return;
     const header = `Workflow ${run.runId} ${run.status}`;
-    const state = engine.getState(runId);
+    const state = workflowEngine.getState(runId);
     const finalResult = state?.result ?? run.finalResult;
     const body =
       run.error ??
@@ -1233,42 +1508,154 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         ? `completed with ${Object.keys(run.callResults).length} agent call(s).`
         : `result:\n${typeof finalResult === "string" ? finalResult : (JSON.stringify(finalResult, null, 2) ?? String(finalResult))}`);
     const text = `${header}: ${body}`;
-    if (deliverResult) {
-      try {
-        deliverResult(text);
-      } catch {
-        // Endpoint suspended or send failed — leave pending for next bind (fail-closed).
-        rememberPendingDelivery(runId, text);
-        try {
-          pi.appendEntry(PENDING_DELIVERY_TYPE, { runId, text, status: run.status, timestamp: Date.now() });
-        } catch {
-          // appendEntry is best-effort; in-memory marker still ensures flush on next bind
-        }
-      }
-    } else {
-      // No bound session endpoint — fail-closed: persist a pending marker and
-      // flush it when a session binds, never fall back to shared pi.sendMessage.
-      rememberPendingDelivery(runId, text);
-      try {
-        pi.appendEntry(PENDING_DELIVERY_TYPE, { runId, text, status: run.status, timestamp: Date.now() });
-      } catch {
-        // best-effort persistence; in-memory marker still ensures retry
-      }
+    if (!ownsDeliveryBranch()) return;
+    rememberPendingDelivery(runId, text);
+    try {
+      pi.appendEntry(PENDING_DELIVERY_TYPE, {
+        runId,
+        text: text.slice(0, 8_000),
+        status: run.status,
+        timestamp: Date.now(),
+      });
+      advanceDeliveryAnchor();
+    } catch {
+      // Best-effort persistence; the in-memory marker remains retryable.
     }
+    schedulePendingDeliveries();
   };
 
+  const ownsDeliveryBranch = (): boolean => {
+    if (!active || !deliveryContext || !engine || engine.isDisposed()) return false;
+    try {
+      const branch = deliveryContext.sessionManager.getBranch();
+      return [deliveryBranchAnchor, journalBranchAnchor].every(
+        (anchor) => !anchor || branch.some((entry) => entry.id === anchor),
+      );
+    } catch {
+      return false;
+    }
+  };
+  const advanceDeliveryAnchor = (): void => {
+    if (!deliveryContext) return;
+    deliveryBranchAnchor =
+      deliveryContext.sessionManager.getLeafId?.() ?? deliveryContext.sessionManager.getBranch().at(-1)?.id ?? null;
+  };
+  const canDeliver = (): boolean => {
+    if (!ownsDeliveryBranch() || inputPreparing || compacting || navigating) return false;
+    try {
+      return deliveryContext?.isIdle() === true && deliveryContext.hasPendingMessages() === false;
+    } catch {
+      return false;
+    }
+  };
+  const hydratePendingDeliveries = (entries: SessionEntryLike[]): void => {
+    pendingDeliveryMarkers.clear();
+    for (const entry of entries) {
+      const shaped = entry as { type?: unknown; customType?: unknown; data?: unknown };
+      if (shaped.type !== "custom") continue;
+      const data = shaped.data as Record<string, unknown> | undefined;
+      if (typeof data?.runId !== "string") continue;
+      if (shaped.customType === PENDING_DELIVERY_ACK_TYPE) pendingDeliveryMarkers.delete(data.runId);
+      else if (shaped.customType === PENDING_DELIVERY_TYPE && typeof data.text === "string") {
+        rememberPendingDelivery(
+          data.runId,
+          data.text,
+          typeof data.timestamp === "number" ? data.timestamp : Date.now(),
+        );
+      }
+    }
+  };
   const flushPendingDeliveries = (): void => {
-    if (!deliverResult || pendingDeliveryMarkers.size === 0) return;
-    for (const [runId, pending] of [...pendingDeliveryMarkers]) {
-      try {
-        deliverResult(pending.text);
+    if (!canDeliver() || !deliveryContext || pendingDeliveryMarkers.size === 0) return;
+    if (typeof pi.sendMessage !== "function" || typeof pi.sendUserMessage !== "function") return;
+    const ctx = deliveryContext;
+    const generation = deliveryGeneration;
+    // Bounded batches coalesce simultaneous completions without model polling.
+    const batch = [...pendingDeliveryMarkers].slice(0, 8);
+    const isCurrent = (): boolean => generation === deliveryGeneration && ctx === deliveryContext && canDeliver();
+    const persisted = (runId: string): boolean =>
+      ctx.sessionManager.getBranch().some((entry) => {
+        const shaped = entry as {
+          type?: string;
+          customType?: string;
+          content?: unknown;
+          details?: { runIds?: unknown };
+        };
+        const ids = shaped.details?.runIds;
+        return (
+          shaped.type === "custom_message" &&
+          shaped.customType === "pi-workflows:delivery" &&
+          typeof shaped.content === "string" &&
+          Array.isArray(ids) &&
+          ids.length > 0 &&
+          ids.length <= 8 &&
+          ids.every((id) => typeof id === "string" && id.length > 0 && id.length <= 128) &&
+          new Set(ids).size === ids.length &&
+          ids.includes(runId)
+        );
+      });
+    try {
+      if (!isCurrent()) return;
+      // Never use a custom-message triggerTurn: that skips input preparation
+      // and before_agent_start. The void API is NOT an acceptance promise.
+      const missing = batch.filter(([runId]) => !persisted(runId));
+      if (missing.length > 0)
+        pi.sendMessage(
+          {
+            content: missing.map(([, marker]) => marker.text).join("\n\n"),
+            display: true,
+            customType: "pi-workflows:delivery",
+            details: { runIds: missing.map(([runId]) => runId) },
+          },
+          { triggerTurn: false },
+        );
+      if (!isCurrent() || !batch.every(([runId]) => persisted(runId))) return;
+      advanceDeliveryAnchor();
+      for (const [runId] of batch) {
+        if (!isCurrent()) return;
+        const priorEntryIds = new Set(ctx.sessionManager.getBranch().map((entry) => entry.id));
         pi.appendEntry(PENDING_DELIVERY_ACK_TYPE, { runId, timestamp: Date.now() });
+        if (!isCurrent()) return;
+        const acknowledged = ctx.sessionManager.getBranch().some((entry) => {
+          const shaped = entry as { type?: string; customType?: string; data?: { runId?: unknown } };
+          return (
+            !priorEntryIds.has(entry.id) &&
+            shaped.type === "custom" &&
+            shaped.customType === PENDING_DELIVERY_ACK_TYPE &&
+            shaped.data?.runId === runId
+          );
+        });
+        if (!acknowledged) return;
+        advanceDeliveryAnchor();
         pendingDeliveryMarkers.delete(runId);
-      } catch {
-        // Keep pending until both delivery and its durable acknowledgement succeed.
       }
+      // An earlier input hook can await while the same manager navigates. Keep
+      // exact owner evidence until our input hook consumes this private wake.
+      if (isCurrent() && engine) {
+        const wake = `${DELIVERY_WAKE_PREFIX}${randomUUID()}] ${DELIVERY_WAKE_TEXT}`;
+        wakeAdmissions.set(wake, { generation, context: ctx, engine, anchor: deliveryBranchAnchor });
+        while (wakeAdmissions.size > MAX_WAKE_ADMISSIONS) {
+          const oldest = wakeAdmissions.keys().next().value;
+          if (oldest === undefined) break;
+          wakeAdmissions.delete(oldest);
+        }
+        // Disable commands/templates explicitly for internal notification input.
+        pi.sendUserMessage(wake, { deliverAs: "followUp", expandPromptTemplates: false });
+      }
+    } catch {
+      // Retain unacknowledged markers. Retry only at a later lifecycle boundary.
     }
   };
+  const schedulePendingDeliveries = (): void => {
+    if (deliveryTimer || pendingDeliveryMarkers.size === 0 || !ownsDeliveryBranch()) return;
+    const generation = deliveryGeneration;
+    // Defer handoff out of our notification-only agent_settled handler;
+    // later handlers may navigate or start compaction in either load order.
+    deliveryTimer = setTimeout(() => {
+      deliveryTimer = undefined;
+      if (generation === deliveryGeneration) flushPendingDeliveries();
+    }, 0);
+  };
 
   /** Build a script from a natural-language prompt and run it in background. */
   const runWorkflowFromPrompt = async (ctx: ExtensionCommandContext, prompt: string): Promise<string | undefined> => {
@@ -1286,7 +1673,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       void deliverBackgroundResult(workflowEngine, result.runId);
       return result.runId;
     } catch (error: unknown) {
-      ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+      notifyWorkflow(ctx, error instanceof Error ? error.message : String(error), "error");
       return undefined;
     }
   };
@@ -1297,10 +1684,11 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       throw new Error(`Workflow run not found: ${runId ?? "(none)"}`);
     }
     saveWorkflow(name, state.run.script, sessionCwd);
-    ctx.ui.notify(`Saved workflow "${name}" (${state.run.script.length} chars).`, "info");
+    notifyWorkflow(ctx, `Saved workflow "${name}" (${state.run.script.length} chars).`, "info");
   };
 
   pi.on("session_start", async (_event, ctx) => {
+    turnArming.retire();
     if (active || engine) return;
     const generation = ++lifecycleGeneration;
     sessionCwd = ctx.cwd ?? process.cwd();
@@ -1407,56 +1795,21 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     widgetUi = ctx.mode === "tui" ? ctx.ui : undefined;
     registerSurface();
 
-    // Bind per-session delivery endpoint (A10): capture the session-bound send
-    // at this moment so completions deliver to the originating session, not
-    // whichever session happens to be current later. Never fall back to the
-    // shared pi.sendMessage — a missing or suspended endpoint leaves the
-    // result pending and flushes on the next successful bind (fail-closed).
-    try {
-      const capturedSend = pi.sendMessage;
-      if (typeof capturedSend === "function") {
-        deliverResult = (text: string) => {
-          // Use the captured function value for session affinity; if the
-          // captured function is itself a shared accessor, the flush is still
-          // fail-closed (delivery only when bound).
-          (capturedSend as unknown as (message: unknown, options: unknown) => unknown).call(
-            pi,
-            {
-              content: text,
-              display: true,
-              customType: "pi-workflows:delivery",
-            },
-            { deliverAs: "followUp", triggerTurn: true },
-          );
-        };
-      }
-    } catch {
-      // binding is best-effort; pending stays buffered
-    }
-    // Hydrate any pending markers persisted before this bind (e.g. runs that
-    // settled before the first session_start) — scan the branch for
-    // PENDING_DELIVERY_TYPE entries that have no in-memory counterpart.
+    // Public API methods target the current session: generation + branch
+    // ownership, not a captured function value, provide session affinity.
+    deliveryContext = ctx;
+    deliveryBranchAnchor = journalBranchAnchor;
+    workflowUiBridge ??= new WorkflowUiBridge(pi.events, workflowUiSurface);
+    workflowUiBridge.publish();
+    inputPreparing = false;
+    compacting = false;
+    navigating = false;
     try {
-      const acknowledged = new Set<string>();
-      for (const entry of initialEntries) {
-        const shaped = entry as { type?: unknown; customType?: unknown; data?: unknown };
-        if (shaped.type !== "custom" || typeof shaped.customType !== "string") continue;
-        const data = shaped.data as Record<string, unknown> | undefined;
-        const entryRunId = typeof data?.runId === "string" ? data.runId : undefined;
-        if (!entryRunId) continue;
-        if (shaped.customType === PENDING_DELIVERY_ACK_TYPE) {
-          acknowledged.add(entryRunId);
-        } else if (shaped.customType === PENDING_DELIVERY_TYPE) {
-          const pendingText = typeof data?.text === "string" ? data.text : undefined;
-          const timestamp = typeof data?.timestamp === "number" ? data.timestamp : Date.now();
-          if (pendingText && !acknowledged.has(entryRunId)) rememberPendingDelivery(entryRunId, pendingText, timestamp);
-        }
-      }
-      for (const runId of acknowledged) pendingDeliveryMarkers.delete(runId);
+      hydratePendingDeliveries(ctx.sessionManager.getBranch() as unknown as SessionEntryLike[]);
     } catch {
-      // scan is best-effort
+      pendingDeliveryMarkers.clear(); // fail closed on an unreadable branch
     }
-    flushPendingDeliveries();
+    schedulePendingDeliveries();
 
     // Saved workflow commands register at session_start (Pi cannot unregister
     // or replace command metadata, so factory-time registration would freeze the
@@ -1482,9 +1835,9 @@ export default function piWorkflows(pi: ExtensionAPI): void {
             };
             const result = await workflowEngine.start(script, options);
             void deliverBackgroundResult(workflowEngine, result.runId);
-            commandCtx.ui.notify(`Workflow ${savedName} started in background: ${result.runId}`, "info");
+            notifyWorkflow(commandCtx, `Workflow ${savedName} started in background: ${result.runId}`, "info");
           } catch (error: unknown) {
-            commandCtx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+            notifyWorkflow(commandCtx, error instanceof Error ? error.message : String(error), "error");
           }
         },
       });
@@ -1493,10 +1846,10 @@ export default function piWorkflows(pi: ExtensionAPI): void {
   });
 
   pi.on("session_shutdown", async () => {
-    deliveryGeneration += 1;
-    // Invalidate all long-lived command/tool/widget closures before awaiting
-    // engine quiescence; the old session must not accept another run.
-    active = false;
+    // This synchronous boundary is shared with the bus-first shutdown path.
+    const quiescence = beginShutdownQuiesce();
+    workflowUiBridge?.dispose();
+    workflowUiBridge = undefined;
     clearWidget();
     widgetUi = undefined;
     if (widgetTimer) {
@@ -1507,7 +1860,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     if (closingEngine) {
       let timer: ReturnType<typeof setTimeout> | undefined;
       const result = await Promise.race([
-        beginShutdownQuiesce(),
+        quiescence,
         new Promise<undefined>((resolve) => {
           timer = setTimeout(() => resolve(undefined), 6_000);
         }),
@@ -1529,7 +1882,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     protocolProbe = undefined;
     protocolInFlight = undefined;
     protocolError = undefined;
-    deliverResult = undefined;
+    deliveryContext = undefined;
   });
 }