@bastani/atomic 0.8.19 → 0.8.20-0

package/dist/builtin/workflows/src/extension/index.ts

@@ -15,9 +15,8 @@ import { restoreOnSessionStart } from "../shared/persistence-restore.js";
 import type { SessionManager } from "../shared/persistence-restore.js";
 import { installCompactionHook } from "../shared/persistence-compaction-policy.js";
 import {
+  killRun,
   killAllRuns,
-  destroyRun,
-  destroyAllRuns,
   resumeRun,
   pauseRun,
   pauseAllRuns,
@@ -65,6 +64,15 @@ import {
   WORKFLOW_CONFIG_DEFAULTS,
   withWorkflowDefaults,
 } from "./config-loader.js";
+import {
+  createWorkflowLifecycleNotificationState,
+  installWorkflowLifecycleNotifications,
+  registerLifecycleNoticeRenderer,
+  resetWorkflowLifecycleNotificationState,
+  seedWorkflowLifecycleNotificationState,
+  withWorkflowLifecycleNotificationsSuppressed,
+} from "./lifecycle-notifications.js";
+import type { WorkflowLifecycleNotificationConfig } from "./lifecycle-notifications.js";
 import type { ConfigLoadResult } from "./config-loader.js";
 import type {
   WorkflowPersistencePort,
@@ -85,7 +93,7 @@ import type { StatusWriter } from "./status-writer.js";
 import { setMcpScope, clearMcpScope } from "./mcp.js";
 import type { PiMcpExtensionAPI, PiEventBus } from "./mcp.js";
 import type { StageSessionRuntime } from "../runs/foreground/stage-runner.js";
-import type { CreateAgentSessionOptions } from "@bastani/atomic";
+import { WORKFLOW_STAGE_SUBAGENT_GUARD_ENV, getEnvValue, type CreateAgentSessionOptions } from "@bastani/atomic";
 
 // ---------------------------------------------------------------------------
 // Minimal ExtensionAPI structural types
@@ -114,6 +122,13 @@ export interface PiRenderComponent {
   includes(searchString: string): boolean;
 }
 
+export interface PiMessageRenderComponent {
+  render(width: number): string[];
+  invalidate?: () => void;
+}
+
+export type PiMessageRendererResult = string | PiMessageRenderComponent | undefined;
+
 function textRenderComponent(text: string): PiRenderComponent {
   return dynamicTextRenderComponent(() => text);
 }
@@ -180,6 +195,11 @@ export interface PiCommandContext extends PiModelContext {
   ui: {
     notify: (message: string, type?: "info" | "warning" | "error") => void;
   } & PiUISurface;
+  /**
+   * False when the host bound a no-op UI surface (print/JSON `-p` modes).
+   * Absent on older hosts and unit-test stubs; treat absence as interactive.
+   */
+  hasUI?: boolean;
 }
 
 /** CLI flag registration options. Mirrors the inline options on `ExtensionAPI.registerFlag`. */
@@ -240,6 +260,7 @@ export interface PiExecuteContext extends PiModelContext {
   sessionId?: string;
   ui?: PiUISurface;
   hasUI?: boolean;
+  orchestrationContext?: CreateAgentSessionOptions["orchestrationContext"];
   sessionManager?: SessionManager & {
     getSessionFile?: () => string | undefined;
   };
@@ -273,7 +294,7 @@ export interface ExtensionAPI {
   registerCommand?: (name: string, options: PiCommandOptions) => void;
   registerMessageRenderer?: (
     event: string,
-    renderer: (payload: unknown) => string,
+    renderer: (payload: unknown) => PiMessageRendererResult,
   ) => void;
   /**
    * Inject a custom message into chat history. Used by inline workflow surfaces
@@ -306,6 +327,17 @@ export interface ExtensionAPI {
       handler: (ctx?: PiCommandContext) => void | Promise<void>;
     },
   ) => void;
+  /**
+   * Read the model's currently-active tool names. Present on pi's ExtensionAPI;
+   * absent on older runtimes.
+   */
+  getActiveTools?: () => string[];
+  /**
+   * Replace the model's active tool set by name. Used to drop the `workflow`
+   * tool in non-interactive sessions. Present on pi's ExtensionAPI; absent on
+   * older runtimes.
+   */
+  setActiveTools?: (toolNames: string[]) => void;
   /**
    * Sets the current session name. Present on pi's ExtensionAPI.
    */
@@ -896,6 +928,10 @@ function snapshotTranscriptEntries(
   return sortTranscriptEntriesChronologically(entries);
 }
 
+function formatAlreadyEndedRetainedMessage(runId: string): string {
+  return `Run ${runId.slice(0, 8)} already ended; retained for inspection.`;
+}
+
 function stageFailureMessage(
   runId: string,
   resultReason: string,
@@ -937,6 +973,49 @@ function reloadFailureMessage(error: unknown): string {
   return `Reload failed: ${error instanceof Error ? error.message : String(error)}`;
 }
 
+function hasWorkflowStageSubagentGuardEnv(): boolean {
+  return getEnvValue(WORKFLOW_STAGE_SUBAGENT_GUARD_ENV) === "1";
+}
+
+function isWorkflowStageToolContext(ctx: PiExecuteContext): boolean {
+  return hasWorkflowStageSubagentGuardEnv() || ctx.orchestrationContext?.kind === "workflow-stage";
+}
+
+/** Tool name registered for workflow execution; shared by the de-advertise guard. */
+const WORKFLOW_TOOL_NAME = "workflow";
+
+/**
+ * User-facing message shown when the `/workflow` command is invoked in a
+ * non-interactive (`-p` / `--print` / `--mode json`) session. Such sessions
+ * bind a no-op UI surface (`ctx.hasUI === false`) and cannot drive workflow
+ * pickers, the graph overlay, or human-in-the-loop prompts.
+ *
+ * The `workflow` tool is removed from the model's tool set in these sessions
+ * (see `deAdvertiseWorkflowToolWhenHeadless`). The slash command has no
+ * advertise layer and is still reachable via `atomic -p "/workflow …"` (print
+ * mode dispatches leading-slash commands through `session.prompt`), so it is
+ * refused here instead.
+ */
+export const WORKFLOW_NON_INTERACTIVE_MESSAGE =
+  "Workflows are disabled in non-interactive (-p) mode; run Atomic interactively to use workflows.";
+
+/**
+ * Remove the `workflow` tool from the model's active tool set in non-interactive
+ * (`-p` / `--mode json`) sessions, which bind a no-op UI (`ctx.hasUI === false`)
+ * and cannot drive workflow prompts or the graph overlay. Invoked from
+ * `session_start`, which the host awaits before the first prompt, so the tool is
+ * gone before the model's first turn. Interactive and RPC modes bind a real UI
+ * context (`hasUI: true`) and keep the tool. No-ops on hosts that predate the
+ * `getActiveTools`/`setActiveTools` extension API.
+ */
+function deAdvertiseWorkflowToolWhenHeadless(pi: ExtensionAPI, hasUI: boolean | undefined): void {
+  if (hasUI !== false) return;
+  if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+  const active = pi.getActiveTools();
+  if (!active.includes(WORKFLOW_TOOL_NAME)) return;
+  pi.setActiveTools(active.filter((name) => name !== WORKFLOW_TOOL_NAME));
+}
+
 // ---------------------------------------------------------------------------
 // Tool execute — dispatch with real registry for list/inputs/run (Phase E)
 //                + real status/interrupt/resume (Phase D)
@@ -953,6 +1032,19 @@ export function makeExecuteWorkflowTool(
   ): Promise<WorkflowToolResult> {
     const action = args.action ?? "run";
     const runId = args.runId ?? "";
+    if (isWorkflowStageToolContext(ctx)) {
+      // Workflow stages must not invoke the workflow tool at all, including
+      // read-only inspection actions. The tool is normally excluded from stage
+      // sessions; this guard is a defense-in-depth fallback for stale or
+      // hand-crafted registrations.
+      return {
+        action: "run",
+        runId,
+        status: "failed",
+        error: "workflows cannot invoke workflows from workflow stages",
+        stages: [],
+      };
+    }
     const activeRuntime =
       typeof runtime === "function" ? runtime(ctx) : runtime;
 
@@ -998,9 +1090,9 @@ export function makeExecuteWorkflowTool(
             error: `run not found: ${target}`,
           };
         }
-        // List mode — emit live snapshots; the renderer produces the
+        // List mode — emit all retained snapshots; the renderer produces the
         // canonical band + card surface.
-        const snapshots = store.runs().filter((r) => r.endedAt === undefined);
+        const snapshots = store.runs();
         return {
           action: "status",
           snapshots: snapshots.map((snapshot) => structuredClone(snapshot)),
@@ -1319,7 +1411,7 @@ export function makeExecuteWorkflowTool(
               message: allStageConflictMessage("kill"),
             };
           }
-          const results = destroyAllRuns({
+          const results = killAllRuns({
             cancellation: cancellationRegistry,
             persistence: getPersistence(),
           });
@@ -1330,7 +1422,7 @@ export function makeExecuteWorkflowTool(
             status: killed > 0 ? "killed" : "noop",
             message:
               killed > 0
-                ? `Killed and removed ${killed} run(s).`
+                ? `Killed and retained ${killed} run(s) for inspection.`
                 : "No in-flight runs to kill.",
           };
         }
@@ -1340,7 +1432,7 @@ export function makeExecuteWorkflowTool(
         if (target.kind === "not_found") {
           return { action, runId: target.target, status: "noop", message: target.message };
         }
-        const result = destroyRun(target.runId, {
+        const result = killRun(target.runId, {
           cancellation: cancellationRegistry,
           persistence: getPersistence(),
         });
@@ -1349,14 +1441,17 @@ export function makeExecuteWorkflowTool(
             action,
             runId: result.runId,
             status: "killed",
-            message: `Run ${result.runId} killed and removed (was ${result.previousStatus}).`,
+            message: `Run ${result.runId} killed and retained for inspection (was ${result.previousStatus}).`,
           };
         }
         return {
           action,
           runId: target.runId,
           status: "noop",
-          message: `Run not found: ${target.runId}`,
+          message: result.reason === "already_ended"
+            ? formatAlreadyEndedRetainedMessage(target.runId)
+            // Defensive fallback: resolveRunTarget already found this run, and killRun no longer removes runs.
+            : `Run not found: ${target.runId}`,
         };
       }
 
@@ -1908,7 +2003,7 @@ function factory(pi: ExtensionAPI): void {
   const overlay: GraphOverlayPort = buildGraphOverlayAdapter(pi, store, {
     onKillRun: (runId) => {
       const run = store.runs().find((r) => r.id === runId);
-      const result = destroyRun(runId, {
+      const result = killRun(runId, {
         cancellation: cancellationRegistry,
         persistence: persistenceRef.current,
       });
@@ -1917,7 +2012,6 @@ function factory(pi: ExtensionAPI): void {
           kind: "killed",
           run,
           previousStatus: result.previousStatus,
-          wasInFlight: result.wasInFlight,
         });
       }
     },
@@ -1950,6 +2044,32 @@ function factory(pi: ExtensionAPI): void {
     store,
     runtimeConfigRef.current,
   );
+  let lifecycleNotificationsUnsubscribe: (() => void) | null = null;
+  let lifecycleNotificationsActive = false;
+  const lifecycleNotificationState = createWorkflowLifecycleNotificationState();
+  const lifecycleNotificationConfigRef: { current: WorkflowLifecycleNotificationConfig } = {
+    current: WORKFLOW_CONFIG_DEFAULTS.workflowNotifications,
+  };
+  registerLifecycleNoticeRenderer({
+    rendererHost: pi,
+    registerMessageRenderer: pi.registerMessageRenderer
+      ? (event, renderer) => pi.registerMessageRenderer?.(event, renderer)
+      : undefined,
+  });
+  const reinstallLifecycleNotifications = (): void => {
+    lifecycleNotificationsUnsubscribe?.();
+    lifecycleNotificationsUnsubscribe = null;
+    if (!lifecycleNotificationsActive) return;
+    lifecycleNotificationsUnsubscribe = installWorkflowLifecycleNotifications({
+      store,
+      config: lifecycleNotificationConfigRef.current,
+      state: lifecycleNotificationState,
+      seedExisting: true,
+      sendMessage: pi.sendMessage
+        ? (message, options) => pi.sendMessage?.(message, options)
+        : undefined,
+    });
+  };
   let intercomParentSession: string | null = null;
   const intercomPort = {
     emit:
@@ -2100,6 +2220,8 @@ function factory(pi: ExtensionAPI): void {
       statusFile: effectiveConfig.statusFile,
       resumeInFlight: effectiveConfig.resumeInFlight,
     };
+    lifecycleNotificationConfigRef.current = effectiveConfig.workflowNotifications;
+    reinstallLifecycleNotifications();
 
     // Replace status writer with one that reflects the resolved config.
     // Unsubscribe the prior (no-op) writer before creating the new one.
@@ -2182,7 +2304,7 @@ function factory(pi: ExtensionAPI): void {
    *   connect [runId|prefix]              no arg → picker overlay; arg → attach to graph
    *   attach  [runId|prefix [stageId]]    open the in-place attach pane on a stage
    *   interrupt [runId|prefix|--all] [-y] confirmation overlay unless -y
-   *   kill      [runId|prefix|--all] [-y] kill and remove from history/status
+   *   kill      [runId|prefix|--all] [-y] kill and retain for inspection
    *   pause     [runId|prefix [stageId]]    pause a run or specific stage
    *   resume  [runId|prefix [stageId] …]  resume paused work or reopen snapshot
    */
@@ -2201,7 +2323,7 @@ function factory(pi: ExtensionAPI): void {
         const ui = ctx.ui;
         if (!ui || typeof ui.custom !== "function") {
           print(
-            `${renderSessionList(store.runs(), { theme, includeAll: false })}\n\nPicker requires a UI surface. Pass a runId: /workflow connect <id>`,
+            `${renderSessionList(store.runs(), { theme, includeAll: true })}\n\nPicker requires a UI surface. Pass a runId: /workflow connect <id>`,
           );
           return true;
         }
@@ -2217,6 +2339,10 @@ function factory(pi: ExtensionAPI): void {
             print(`Run not found: ${result.runId}`);
             return true;
           }
+          if (run.endedAt !== undefined) {
+            print(formatAlreadyEndedRetainedMessage(result.runId));
+            return true;
+          }
           const confirmed = await openKillConfirm(ui, run, theme);
           if (!confirmed) {
             print(
@@ -2224,7 +2350,7 @@ function factory(pi: ExtensionAPI): void {
             );
             return true;
           }
-          const killed = destroyRun(result.runId, {
+          const killed = killRun(result.runId, {
             cancellation: cancellationRegistry,
             persistence: persistenceRef.current,
           });
@@ -2233,13 +2359,14 @@ function factory(pi: ExtensionAPI): void {
               kind: "killed",
               run,
               previousStatus: killed.previousStatus,
-              wasInFlight: killed.wasInFlight,
             });
           }
           print(
             killed.ok
-              ? `Run ${killed.runId.slice(0, 8)} killed and removed.`
-              : `Run not found: ${result.runId.slice(0, 8)}.`,
+              ? `Run ${killed.runId.slice(0, 8)} killed and retained for inspection.`
+              : killed.reason === "already_ended"
+                ? formatAlreadyEndedRetainedMessage(killed.runId)
+                : `Run not found: ${result.runId.slice(0, 8)}.`,
           );
           return true;
         }
@@ -2367,7 +2494,7 @@ function factory(pi: ExtensionAPI): void {
         }
         if (!yes && ctx.ui && typeof ctx.ui.confirm === "function") {
           const ok = await ctx.ui.confirm(
-            `Kill and remove all ${inFlight.length} in-flight workflow runs?`,
+            `Kill ${inFlight.length} in-flight workflow runs? Killed runs are retained for inspection.`,
             `Aborts: ${inFlight.map((r) => `${r.name} (${r.id.slice(0, 8)})`).join(", ")}`,
           );
           if (!ok) {
@@ -2375,14 +2502,14 @@ function factory(pi: ExtensionAPI): void {
             return true;
           }
         }
-        const results = destroyAllRuns({
+        const results = killAllRuns({
           cancellation: cancellationRegistry,
           persistence: persistenceRef.current,
         });
         const killed = results.filter((r) => r.ok).length;
         print(
           killed > 0
-            ? `Killed and removed ${killed} run(s).`
+            ? `Killed and retained ${killed} run(s) for inspection.`
             : "No in-flight runs to kill.",
         );
         return true;
@@ -2401,6 +2528,10 @@ function factory(pi: ExtensionAPI): void {
         return true;
       }
       const run = store.runs().find((r) => r.id === resolved.runId);
+      if (run?.endedAt !== undefined) {
+        print(formatAlreadyEndedRetainedMessage(resolved.runId));
+        return true;
+      }
       if (!yes && run && ctx.ui) {
         const confirmed = await openKillConfirm(ctx.ui, run, theme);
         if (!confirmed) {
@@ -2410,7 +2541,7 @@ function factory(pi: ExtensionAPI): void {
           return true;
         }
       }
-      const result = destroyRun(resolved.runId, {
+      const result = killRun(resolved.runId, {
         cancellation: cancellationRegistry,
         persistence: persistenceRef.current,
       });
@@ -2420,14 +2551,17 @@ function factory(pi: ExtensionAPI): void {
             kind: "killed",
             run,
             previousStatus: result.previousStatus,
-            wasInFlight: result.wasInFlight,
           });
         }
         print(
-          `Run ${result.runId.slice(0, 8)} killed and removed (was ${result.previousStatus}).`,
+          `Run ${result.runId.slice(0, 8)} killed and retained for inspection (was ${result.previousStatus}).`,
         );
       } else {
-        print(`Run not found: ${target}`);
+        print(
+          result.reason === "already_ended"
+            ? formatAlreadyEndedRetainedMessage(result.runId)
+            : `Run not found: ${target}`,
+        );
       }
       return true;
     }
@@ -2440,7 +2574,7 @@ function factory(pi: ExtensionAPI): void {
         const ui = ctx.ui;
         if (!ui || typeof ui.custom !== "function") {
           print(
-            `${renderSessionList(store.runs(), { theme, includeAll: false })}\n\nPicker requires a UI surface. Pass a runId: /workflow attach <id> [stageId]`,
+            `${renderSessionList(store.runs(), { theme, includeAll: true })}\n\nPicker requires a UI surface. Pass a runId: /workflow attach <id> [stageId]`,
           );
           return true;
         }
@@ -2657,6 +2791,13 @@ function factory(pi: ExtensionAPI): void {
       description:
         "Run or inspect pi workflows. Usage: /workflow <name> [key=value…] | /workflow [list|status|connect|attach|interrupt|kill|pause|resume|inputs|reload] [args]",
       handler: async (args: string, ctx: PiCommandContext) => {
+        // Print/JSON (`-p`) sessions cannot drive workflow pickers, the graph
+        // overlay, or human-in-the-loop prompts. Refuse before parsing so the
+        // command surface matches the disabled `workflow` tool.
+        if (ctx.hasUI === false) {
+          ctx.ui.notify(WORKFLOW_NON_INTERACTIVE_MESSAGE, "warning");
+          return;
+        }
         const print = (msg: string): void => ctx.ui.notify(msg, "info");
         // Quote-aware split so `prompt="map the codebase"` stays a single
         // token. Plain `.split(/\s+/)` would mangle quoted multi-word values
@@ -2702,9 +2843,8 @@ function factory(pi: ExtensionAPI): void {
 
         // -----------------------------------------------------------------------
         // status — band-header rich list, or per-run detail when an id is
-        // supplied. `/workflow status` lists everything in-flight (`--all`
-        // includes ended runs older than an hour); `/workflow status <id>`
-        // drills into a single run via the inspectRun detail block.
+        // supplied. `/workflow status` lists all retained snapshots; `/workflow
+        // status <id>` drills into a single run via the inspectRun detail block.
         // -----------------------------------------------------------------------
         if (subcommand === "status") {
           const target = parts[1];
@@ -2730,13 +2870,12 @@ function factory(pi: ExtensionAPI): void {
             emitChatSurface(pi, { kind: "detail", detail: inspected.detail });
             return;
           }
-          // Mirror renderSessionList's filter: keep `--all` semantics, then
-          // hand the already-filtered snapshot to the chat-surface renderer.
-          const includeAll = parts.includes("--all");
+          // Status lists all retained snapshots by default; --all remains
+          // accepted as a compatibility no-op.
           const rows = selectRunsForPicker(
             store.runs(),
             "",
-            includeAll,
+            true,
             Date.now(),
           );
           emitChatSurface(pi, { kind: "status", runs: rows.map((r) => r.run) });
@@ -2782,7 +2921,7 @@ function factory(pi: ExtensionAPI): void {
         }
 
         // -----------------------------------------------------------------------
-        // kill — destructive fast path: abort and remove from history/status.
+        // kill — abort in-flight work, mark killed, and retain for inspection.
         // -----------------------------------------------------------------------
         if (subcommand === "kill") {
           const killArgs = parts.slice(1);
@@ -3061,7 +3200,7 @@ function factory(pi: ExtensionAPI): void {
           {
             value: "status ",
             label: "status",
-            description: "List in-flight runs",
+            description: "List current-session active and retained terminal runs",
           },
           {
             value: "interrupt ",
@@ -3071,7 +3210,7 @@ function factory(pi: ExtensionAPI): void {
           {
             value: "kill ",
             label: "kill",
-            description: "Kill and remove a run",
+            description: "Kill and retain a run for inspection",
           },
           {
             value: "pause ",
@@ -3109,14 +3248,7 @@ function factory(pi: ExtensionAPI): void {
         }
 
         if (subcommand === "status") {
-          return completeToken(partial, [
-            {
-              value: "--all ",
-              label: "--all",
-              description: "Include recently ended runs",
-            },
-            ...runIdItems(),
-          ]);
+          return completeToken(partial, runIdItems());
         }
 
         if (subcommand === "connect") {
@@ -3132,7 +3264,7 @@ function factory(pi: ExtensionAPI): void {
         }
 
         if (subcommand === "interrupt" || subcommand === "kill") {
-          const verb = subcommand === "kill" ? "Kill and remove" : "Interrupt";
+          const verb = subcommand === "kill" ? "Kill and retain" : "Interrupt";
           return completeToken(partial, [
             {
               value: "--all ",
@@ -3256,18 +3388,60 @@ function factory(pi: ExtensionAPI): void {
   // 4. Persistence: session_start restore + session_before_compact hook (§5.6, Phase D)
   // -------------------------------------------------------------------------
   if (typeof pi.on === "function") {
+    pi.on("session_before_switch", async (event, ctx) => {
+      const reason = typeof event === "object" && event !== null && "reason" in event
+        ? (event as { readonly reason?: string }).reason
+        : undefined;
+      if (reason !== "new" && reason !== "resume") return undefined;
+
+      // "In-flight" intentionally includes paused runs: session_start kills any run
+      // without endedAt, so warn for the same set that would be stopped by the switch.
+      const inFlightWorkflowCount = inFlightRunCount();
+      if (inFlightWorkflowCount === 0) return undefined;
+
+      const confirmSessionSwitch = ctx?.ui?.confirm;
+      // Headless/non-interactive callers intentionally fail open so automation cannot wedge.
+      if (typeof confirmSessionSwitch !== "function") return undefined;
+
+      const workflowNoun = inFlightWorkflowCount === 1 ? "workflow" : "workflows";
+      const actionLabel = reason === "new" ? "Start a new session" : "Resume another session";
+      const messageLabel = reason === "new" ? "Starting a new session" : "Resuming another session";
+      const promptTitle = `${actionLabel} and stop ${inFlightWorkflowCount} in-flight ${workflowNoun}?`;
+      const promptMessage =
+        `${messageLabel} will stop/kill ${inFlightWorkflowCount} in-flight ${workflowNoun} and clear workflow history tied to the current session.`;
+      let shouldSwitchSession: boolean | undefined;
+      try {
+        shouldSwitchSession = await confirmSessionSwitch(promptTitle, promptMessage);
+      } catch {
+        // Keep headless/failed UI behavior fail-open so session automation cannot wedge.
+        return undefined;
+      }
+      if (shouldSwitchSession) return undefined;
+
+      const cancelledLabel = reason === "new" ? "New session" : "Resume";
+      ctx?.ui?.notify?.(`${cancelledLabel} cancelled; in-flight workflows were left unchanged.`, "info");
+      return { cancel: true };
+    });
+
     pi.on("session_start", async (_event, ctx) => {
+      // Non-interactive (`-p` / `--mode json`) sessions cannot drive workflow
+      // prompts or the graph overlay; drop the `workflow` tool from the model's
+      // tool set before the first turn. The host awaits this handler during
+      // bindExtensions, ahead of the initial prompt.
+      deAdvertiseWorkflowToolWhenHeadless(pi, ctx?.hasUI);
+
       // Workflow lifecycle is scoped to the originating chat session.
-      // A new session inherits a clean store; any leftover runs from a
+      // A new session inherits a clean store; any leftover live runs from a
       // previous session in the same pi process are killed (subprocess
-      // aborted) and dropped. `restoreOnSessionStart` below then loads
-      // *this* session's persisted runs from disk.
+      // aborted), then all stale snapshots are cleared. `restoreOnSessionStart`
+      // below loads *this* session's persisted runs from disk.
       killAllRuns({
         store,
         cancellation: cancellationRegistry,
         persistence: persistenceRef.current,
       });
       store.clear();
+      resetWorkflowLifecycleNotificationState(lifecycleNotificationState);
       stageControlRegistry.clear();
 
       // pi-intercom session naming lives here so we don't trip the
@@ -3278,6 +3452,8 @@ function factory(pi: ExtensionAPI): void {
       // Ensure config+discovery are ready before restoring in-flight runs —
       // tunables must be resolved first.
       await discoveryPromise;
+      lifecycleNotificationsActive = true;
+      reinstallLifecycleNotifications();
       if (ctx?.ui) {
         const diagnostics = formatStartupDiagnostics(configLoadRef.current, discoveryRef.current);
         if (diagnostics !== null) {
@@ -3290,13 +3466,25 @@ function factory(pi: ExtensionAPI): void {
       const sessionManager = ctx?.sessionManager ?? pi.sessionManager;
       if (sessionManager) {
         const cfg = configLoadRef.current?.config;
-        restoreOnSessionStart(
-          sessionManager,
-          {
-            resumeInFlight: cfg?.resumeInFlight ?? "ask",
-            persistRuns: cfg?.persistRuns ?? true,
+        withWorkflowLifecycleNotificationsSuppressed(
+          lifecycleNotificationState,
+          () => {
+            restoreOnSessionStart(
+              sessionManager,
+              {
+                resumeInFlight: cfg?.resumeInFlight ?? "ask",
+                persistRuns: cfg?.persistRuns ?? true,
+              },
+              store,
+            );
+            // The suppressed subscriber observes restore replay and marks matching
+            // notices delivered. Seed explicitly as a defensive backstop for
+            // runtimes without a lifecycle-notification subscriber installed.
+            seedWorkflowLifecycleNotificationState(
+              lifecycleNotificationState,
+              store.snapshot(),
+            );
           },
-          store,
         );
       }
     });
@@ -3320,6 +3508,9 @@ function factory(pi: ExtensionAPI): void {
       }
       storeWidgetUnsubscribe?.();
       storeWidgetUnsubscribe = null;
+      lifecycleNotificationsActive = false;
+      lifecycleNotificationsUnsubscribe?.();
+      lifecycleNotificationsUnsubscribe = null;
     });
   }