@signalridge/pi-workflows 1.4.0 → 1.6.0

package/src/index.ts

@@ -8,10 +8,27 @@ 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";
 import { JOURNAL_ENTRY_TYPE, type SessionEntryLike } from "./journal.js";
-import { createManagedSpawnClient, PROTOCOL_DIAGNOSTIC, queryChildSessionContextImmediate } from "./rpc-client.js";
+import {
+  createManagedSpawnClient,
+  type ManagedProtocolCheck,
+  PROTOCOL_DIAGNOSTIC,
+  queryChildSessionContextImmediate,
+} from "./rpc-client.js";
 import { listSavedWorkflows, loadSavedWorkflow, saveWorkflow } from "./saved-workflows.js";
+import {
+  defaultStrengthTable,
+  isWorkflowStrength,
+  WORKFLOW_STRENGTH_LIST,
+  WORKFLOW_STRENGTHS,
+  type WorkflowStrengthTable,
+} from "./strengths.js";
 import { liveWidgetLines, showWorkflowNavigator } from "./ui.js";
-import { loadWorkflowSettings, saveWorkflowSettings } from "./workflow-settings.js";
+import {
+  loadProjectWorkflowSettings,
+  loadWorkflowSettings,
+  saveWorkflowSettings,
+  type WorkflowSettings,
+} from "./workflow-settings.js";
 
 const WorkflowToolSchema = Type.Object(
   {
@@ -124,6 +141,7 @@ export function buildAdHocWorkflowScript(prompt: string): string {
 const originalPrompt = ${JSON.stringify(prompt)};
 const plan = await agent("Design a bounded execution plan for this user task. Return 1-8 independent or dependency-linked tasks. Use unique short ids, concise descriptions, exact worker prompts, and only dependencies that appear in the task list. Prefer independent tasks when possible. User task:\\n\\n" + originalPrompt, {
   label: "planner",
+  strength: "medium",
   schema: {
     type: "object",
     properties: {
@@ -152,7 +170,7 @@ const graph = await orchestrate(plan.tasks.map((task) => ({
   id: task.id,
   description: task.description,
   dependsOn: task.dependsOn || [],
-  run: ({ results, statuses }) => agent(task.prompt + "\\n\\nDependency results (null means unavailable):\\n" + JSON.stringify({ results, statuses }), { label: task.id }),
+  run: ({ results, statuses }) => agent(task.prompt + "\\n\\nDependency results (null means unavailable):\\n" + JSON.stringify({ results, statuses }), { label: task.id, strength: "low" }),
 })), { onError: "continue" });
 const SYNTHESIS_CONTEXT_LIMIT = 78000;
 function renderContextValue(value) {
@@ -226,21 +244,61 @@ while (synthesisJson.length > SYNTHESIS_CONTEXT_LIMIT && (valuePreviewBudget > 1
   synthesisJson = JSON.stringify(synthesisContext);
 }
 if (synthesisJson.length > SYNTHESIS_CONTEXT_LIMIT) throw new Error("Unable to fit the synthesis context within its managed prompt budget");
-return await agent("Synthesize the worker results into a direct answer to the original task. Mention incomplete or failed coverage explicitly.\\n\\nOriginal task, execution plan, and graph ledger:\\n" + synthesisJson, { label: "synthesizer" });`;
+return await agent("Synthesize the worker results into a direct answer to the original task. Mention incomplete or failed coverage explicitly.\\n\\nOriginal task, execution plan, and graph ledger:\\n" + synthesisJson, { label: "synthesizer", strength: "medium" });`;
 }
 
 export default function piWorkflows(pi: ExtensionAPI): void {
   let engine: WorkflowEngine | undefined;
   let protocolError: string | undefined;
-  let protocolCheck: Promise<void> = Promise.resolve();
+  let protocolCheck: Promise<ManagedProtocolCheck> | undefined;
+  let protocolProbe: (() => Promise<ManagedProtocolCheck>) | undefined;
+  let protocolInFlight: Promise<ManagedProtocolCheck> | undefined;
+  /**
+   * Track one in-flight probe so concurrent starts share it, and release it the
+   * moment it settles.
+   *
+   * Releasing matters: the catalogue is read live on the peer's side, so the
+   * next start or resume must issue a *new* ping. Holding a settled promise
+   * here would pin every later run to the routing policy as it stood at session
+   * start, and a tier defined since then would be rejected pre-dispatch as
+   * unknown.
+   */
+  const trackProbe = (check: Promise<ManagedProtocolCheck>): Promise<ManagedProtocolCheck> => {
+    protocolInFlight = check;
+    const release = () => {
+      if (protocolInFlight === check) protocolInFlight = undefined;
+    };
+    void check.then(release, release);
+    return check;
+  };
+  const awaitProtocol = async (): Promise<ManagedProtocolCheck> => {
+    let check = protocolInFlight;
+    if (!check) {
+      if (protocolProbe) protocolError = undefined;
+      check = protocolProbe?.() ?? protocolCheck;
+      if (!check) throw new Error(`${PROTOCOL_DIAGNOSTIC} Diagnostic: no active protocol probe`);
+      trackProbe(check);
+    }
+    try {
+      const result = await check;
+      protocolError = undefined;
+      return result;
+    } catch (error: unknown) {
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new Error(protocolError ?? `${PROTOCOL_DIAGNOSTIC} Diagnostic: ${detail}`);
+    }
+  };
   let active = false;
-  let unsubscribeTreeSignal: (() => void) | undefined;
+  let surfaceRegistered = false;
+  const registeredWorkflowCommands = new Set<string>();
   let branchQuiesce: Promise<{ settled: boolean; pending: string[]; diagnostic?: string }> | undefined;
   let lifecycleGeneration = 0;
   let protocolAbortController: AbortController | undefined;
   let sessionCwd = process.cwd();
   let workflowSettings = loadWorkflowSettings(sessionCwd);
   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). */
@@ -252,10 +310,42 @@ export default function piWorkflows(pi: ExtensionAPI): void {
   let widgetTimer: ReturnType<typeof setInterval> | undefined;
 
   const currentEngine = (): WorkflowEngine => {
-    if (!engine) throw new Error("pi-workflows is not active in this session context");
+    if (!active || !engine || engine.isDisposed())
+      throw new Error("pi-workflows is not active in this session context");
     return engine;
   };
 
+  const clearWidget = (): void => {
+    const tui = (pi as unknown as { ui?: { setWidget?: (key: string, content: string[] | undefined) => void } }).ui;
+    tui?.setWidget?.("pi-workflows", undefined);
+  };
+  const refreshWidget = (): void => {
+    const tui = (pi as unknown as { ui?: { setWidget?: (key: string, content: string[] | undefined) => void } }).ui;
+    if (!tui?.setWidget) return;
+    const workflowEngine = engine;
+    if (!active || !workflowEngine || workflowEngine.isDisposed()) {
+      tui.setWidget("pi-workflows", undefined);
+      if (widgetTimer) {
+        clearInterval(widgetTimer);
+        widgetTimer = undefined;
+      }
+      return;
+    }
+    const runs = workflowEngine
+      .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) {
+      widgetTimer = setInterval(refreshWidget, 2_000);
+    } else if (lines.length === 0 && widgetTimer) {
+      clearInterval(widgetTimer);
+      widgetTimer = undefined;
+    }
+  };
+  const notifyRunChanged = (): void => refreshWidget();
+
   const branchEntries = (): SessionEntryLike[] => {
     const ctx = (pi as unknown as { currentSessionManager?: { getBranch?: () => unknown } }).currentSessionManager;
     try {
@@ -267,6 +357,26 @@ export default function piWorkflows(pi: ExtensionAPI): void {
 
   const DEFAULT_EXCLUDED_TOOLS = ["workflow", "workflow_control"] as const;
 
+  /**
+   * Persist one settings change into this project's own file.
+   *
+   * `workflowSettings` is the merged view — defaults, then global, then project
+   * — while `saveWorkflowSettings` replaces the project file with whatever it
+   * is handed. Handing it the merged view would copy every global value and
+   * every default into the project on the first edit, and the project would
+   * stop tracking the global file from then on. So the patch lands on project
+   * scope and the merged view is re-derived from what actually landed, which is
+   * also what makes it safe to report the result rather than the intent.
+   */
+  const persistWorkflowSetting = (patch: WorkflowSettings): void => {
+    saveWorkflowSettings({ ...loadProjectWorkflowSettings(sessionCwd), ...patch }, sessionCwd);
+    workflowSettings = loadWorkflowSettings(sessionCwd);
+  };
+
+  /** Resolve a nested `workflow(name)` reference; a saved file shadows a built-in. */
+  const resolveNestedWorkflow = (name: string): string | undefined =>
+    loadSavedWorkflow(name, sessionCwd) ?? BUILTIN_WORKFLOWS[name]?.script;
+
   const resolveScript = (
     script: string | undefined,
     name: string | undefined,
@@ -295,6 +405,17 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     if (active) return;
     active = true;
     const workflowEngine = currentEngine();
+    workflowEngine.onRunSettled = notifyRunChanged;
+    // `control("resume")` and the provider-limit retry start executions with no
+    // caller to pass options for them, and the strength table is deliberately
+    // never frozen onto a run. Without this they would resume with no table and
+    // re-run every finished call untabled.
+    workflowEngine.strengths = () => workflowSettings.strengths;
+    // Command/tool registrations persist across session replacement, but the
+    // widget belongs to the newly restored engine and must be refreshed too.
+    refreshWidget();
+    if (surfaceRegistered) return;
+    surfaceRegistered = true;
 
     pi.registerTool(
       defineTool({
@@ -330,62 +451,67 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         },
         async execute(_toolCallId, params, signal, _onUpdate, ctx) {
           try {
-            await protocolCheck;
+            const workflowEngine = currentEngine();
+            const resolved =
+              params.resumeFromRunId && params.script === undefined && params.name === undefined
+                ? (() => {
+                    const prior = workflowEngine.getRun(params.resumeFromRunId);
+                    if (!prior) throw new Error(`Workflow run not found: ${params.resumeFromRunId}`);
+                    // Resume replays the stored script; only the shared shape
+                    // has to be satisfied here.
+                    return { script: prior.script, source: "resume", toolset: prior.toolset };
+                  })()
+                : resolveScript(params.script, params.name, params.args);
+            const { script, source, toolset } = resolved;
+            const options: ScriptStartOptions = {
+              args: params.args,
+              background: params.background ?? true,
+              maxAgents: params.maxAgents,
+              concurrency: params.concurrency,
+              agentRetries: params.agentRetries,
+              tokenBudget: params.tokenBudget,
+              agentTimeoutMs: params.agentTimeoutMs,
+              toolset,
+              excludeTools: [...DEFAULT_EXCLUDED_TOOLS],
+              signal,
+              mainModel: ctx?.model?.id,
+              // Foreground checkpoint confirmation only when the run is not
+              // background — background runs are headless by contract.
+              confirm:
+                params.background === false && ctx?.hasUI && ctx.mode === "tui"
+                  ? async (promptText, checkpointOptions) => {
+                      if (checkpointOptions.kind === "input")
+                        return ctx.ui.input(promptText, String(checkpointOptions.default ?? ""));
+                      if (checkpointOptions.kind === "select")
+                        return ctx.ui.select(promptText, checkpointOptions.choices ?? []);
+                      return ctx.ui.confirm(promptText, promptText);
+                    }
+                  : undefined,
+              loadSavedWorkflow: resolveNestedWorkflow,
+              strengths: workflowSettings.strengths,
+            };
+            if (params.resumeFromRunId) {
+              const replacement = params.script !== undefined || params.name !== undefined ? script : undefined;
+              const resumed = await workflowEngine.resume(
+                params.resumeFromRunId,
+                branchEntries(),
+                options,
+                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);
+            if (result.background) {
+              // The engine resolves the script's meta name for the delivery header.
+              void source;
+              void deliverBackgroundResult(workflowEngine, result.runId);
+            }
+            return textResult(formatStart(result), result);
           } catch (error: unknown) {
-            return textResult(
-              protocolError ??
-                `${PROTOCOL_DIAGNOSTIC} Diagnostic: ${error instanceof Error ? error.message : String(error)}`,
-            );
+            return textResult(error instanceof Error ? error.message : String(error));
           }
-          const resolved =
-            params.resumeFromRunId && params.script === undefined && params.name === undefined
-              ? (() => {
-                  const prior = workflowEngine.getRun(params.resumeFromRunId);
-                  if (!prior) throw new Error(`Workflow run not found: ${params.resumeFromRunId}`);
-                  return { script: prior.script, source: "resume", toolset: prior.toolset };
-                })()
-              : resolveScript(params.script, params.name, params.args);
-          const { script, source, toolset } = resolved;
-          const options: ScriptStartOptions = {
-            args: params.args,
-            background: params.background ?? true,
-            maxAgents: params.maxAgents,
-            concurrency: params.concurrency,
-            agentRetries: params.agentRetries,
-            tokenBudget: params.tokenBudget,
-            agentTimeoutMs: params.agentTimeoutMs,
-            toolset,
-            excludeTools: [...DEFAULT_EXCLUDED_TOOLS],
-            signal,
-            mainModel: ctx?.model?.id,
-            // Foreground checkpoint confirmation only when the run is not
-            // background — background runs are headless by contract.
-            confirm:
-              params.background === false && ctx?.hasUI && ctx.mode === "tui"
-                ? async (promptText, checkpointOptions) => {
-                    if (checkpointOptions.kind === "input")
-                      return ctx.ui.input(promptText, String(checkpointOptions.default ?? ""));
-                    if (checkpointOptions.kind === "select")
-                      return ctx.ui.select(promptText, checkpointOptions.choices ?? []);
-                    return ctx.ui.confirm(promptText, promptText);
-                  }
-                : undefined,
-            loadSavedWorkflow: (name) => loadSavedWorkflow(name, sessionCwd) ?? BUILTIN_WORKFLOWS[name]?.script,
-          };
-          if (params.resumeFromRunId) {
-            const replacement = params.script !== undefined || params.name !== undefined ? script : undefined;
-            const resumed = await workflowEngine.resume(params.resumeFromRunId, branchEntries(), options, 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);
-          if (result.background) {
-            // The engine resolves the script's meta name for the delivery header.
-            void source;
-            void deliverBackgroundResult(workflowEngine, result.runId);
-          }
-          return textResult(formatStart(result), result);
         },
       }),
     );
@@ -405,33 +531,46 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           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) {
-          const rawAction = params.action as string;
-          const action = (rawAction === "status" ? "get" : rawAction) as
-            | "list"
-            | "get"
-            | "pause"
-            | "resume"
-            | "stop"
-            | "rm";
-          if (!["list", "get", "pause", "resume", "stop", "rm"].includes(action)) {
-            throw new Error(`unknown workflow_control action: ${params.action}`);
+          try {
+            const rawAction = params.action as string;
+            const action = (rawAction === "status" ? "get" : rawAction) as
+              | "list"
+              | "get"
+              | "pause"
+              | "resume"
+              | "stop"
+              | "rm";
+            if (!["list", "get", "pause", "resume", "stop", "rm"].includes(action)) {
+              throw new Error(`unknown workflow_control action: ${params.action}`);
+            }
+            const runId = normalizeControlRunId(params as unknown as Record<string, unknown>);
+            const workflowEngine = currentEngine();
+            const result = await workflowEngine.control(action, runId);
+            return textResult(JSON.stringify(result), result);
+          } catch (error: unknown) {
+            return textResult(error instanceof Error ? error.message : String(error));
           }
-          const runId = normalizeControlRunId(params as unknown as Record<string, unknown>);
-          const result = await workflowEngine.control(action, runId);
-          return textResult(JSON.stringify(result), result);
         },
       }),
     );
 
     // /workflows: navigator + run/status/watch/stop/pause/resume/rm/save subcommands
     pi.registerCommand("workflows", {
-      description: "Workflow runs: open the navigator, or run/status/watch/stop/pause/resume/rm/save",
+      description: "Workflow runs: navigator, or run/status/watch/stop/pause/resume/rm/save/strength",
       handler: async (args: string, ctx: ExtensionCommandContext) => {
         const tokens = args.trim().split(/\s+/).filter(Boolean);
         const [subcommand, ...rest] = tokens;
         const restArgs = rest.join(" ").trim();
+        const engineForCommand = (): WorkflowEngine | undefined => {
+          try {
+            return currentEngine();
+          } catch (error: unknown) {
+            ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+            return undefined;
+          }
+        };
         if (!subcommand) {
-          await showWorkflowNavigator(ctx, workflowEngine);
+          await showWorkflowNavigator(ctx, currentEngine);
           return;
         }
         if (subcommand === "run") {
@@ -444,6 +583,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           return;
         }
         if (subcommand === "status") {
+          const workflowEngine = engineForCommand();
+          if (!workflowEngine) return;
           if (restArgs) {
             const run = workflowEngine.getRun(restArgs);
             if (!run) {
@@ -463,6 +604,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           return;
         }
         if (subcommand === "watch") {
+          const workflowEngine = engineForCommand();
+          if (!workflowEngine) return;
           const runId = restArgs || String(workflowEngine.list()[0]?.runId ?? "");
           if (!runId) {
             ctx.ui.notify("No workflow runs to watch.", "warning");
@@ -473,7 +616,9 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           return;
         }
         if (subcommand === "stop" || subcommand === "pause" || subcommand === "resume" || subcommand === "rm") {
-          const firstListed = workflowEngine.list()[0]?.runId;
+          const listedEngine = engineForCommand();
+          if (!listedEngine) return;
+          const firstListed = listedEngine.list()[0]?.runId;
           const runId = resolveControlTarget(
             subcommand,
             restArgs,
@@ -490,6 +635,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
             return;
           }
           try {
+            const workflowEngine = engineForCommand();
+            if (!workflowEngine) return;
             await workflowEngine.control(subcommand, runId);
             if (subcommand === "resume") void deliverBackgroundResult(workflowEngine, runId);
             ctx.ui.notify(`Workflow ${subcommand} requested: ${runId}`, "info");
@@ -504,6 +651,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
             ctx.ui.notify("/workflows save <name> [runId]", "warning");
             return;
           }
+          const workflowEngine = engineForCommand();
+          if (!workflowEngine) return;
           // 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) {
@@ -517,23 +666,158 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           }
           return;
         }
+        if (subcommand === "strength") {
+          // The Agent tier catalogue is owned by pi-subagents and still is (A8:
+          // no second tier config file). What this edits is narrower and is
+          // genuinely ours: which Agent tier each workflow strength runs on.
+          //
+          // A subcommand rather than a command of its own, because the reason
+          // to surface it at all is the three-part view below — two lines of
+          // which come from this package and one from the other — and that is
+          // a page to read, not a mode to be in.
+          //
+          // The catalogue lives on the managed peer, so it can legitimately be
+          // unreachable here. Status still has its other two parts, and a set
+          // made against a table that already exists is stored unvalidated: the
+          // run-start check reports a tier this host does not define and drops
+          // that entry, which costs the redirect rather than the run. A set made
+          // with no table at all is refused instead — see below, where the seed
+          // is read.
+          const catalogue = await (async (): Promise<string[] | undefined> => {
+            try {
+              return Object.keys((await awaitProtocol()).routingPolicy.profiles).sort();
+            } catch {
+              return undefined;
+            }
+          })();
+          const knownTiers = catalogue ? new Set(catalogue) : undefined;
+          // What a run would resolve, by the same rule the runtime uses: a
+          // configured table if there is one, else the shipped default. Shown
+          // rather than the configured table alone, because an unconfigured
+          // machine is not an unrouted one and a row reading "(unset)" there
+          // would describe something other than what the next run does.
+          const effective = (): { table: WorkflowStrengthTable; shipped: boolean } => {
+            const configured = workflowSettings.strengths;
+            return configured === undefined
+              ? { table: defaultStrengthTable(knownTiers), shipped: true }
+              : { table: configured, shipped: false };
+          };
+          const describe = (): string => {
+            const { table, shipped } = effective();
+            const rows = WORKFLOW_STRENGTHS.map((name) => {
+              // The default is derived from the catalogue, so without one there
+              // is nothing honest to print: the run will still route these, and
+              // "(unset)" would claim it will not.
+              if (shipped && knownTiers === undefined) return `  ${name} → (default; needs the tier catalogue)`;
+              if (table[name] === undefined) return `  ${name} → (unset; the agent's own default)`;
+              return `  ${name} → ${table[name]}${shipped ? " (default)" : ""}`;
+            });
+            // The shipped default is identity, so on a stock install workflow
+            // work rides the same profiles every ordinary spawn does — the
+            // coupling this indirection exists to let you break, but does not
+            // break on its own. Saying so here is the only place the two steps
+            // out of it are visible together.
+            const decouple = shipped
+              ? "\nThis is the shipped default: each strength on the tier of the same name, so " +
+                "workflow work shares the tiers your ordinary spawns use (Explore among them). " +
+                "To price workflow work on its own, define a tier in /agents → Model tiers, then " +
+                "point a strength at it here."
+              : "";
+            return (
+              `Workflow strengths and the Agent tier each runs on:\n${rows.join("\n")}\n` +
+              `Tiers this host defines: ${catalogue?.join(", ") ?? "(unavailable)"}\n` +
+              "Edits apply to this project; for a machine-wide table edit " +
+              "<agent dir>/workflows/settings.json. The tiers themselves live in " +
+              "/agents → Model tiers; this only says which one a strength uses." +
+              decouple
+            );
+          };
+          const [strength, target] = rest;
+          if (strength === undefined) {
+            ctx.ui.notify(describe(), "info");
+            return;
+          }
+          if (!isWorkflowStrength(strength)) {
+            ctx.ui.notify(`"${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");
+            return;
+          }
+          // `off` reads as "unset" unless the host really defines a tier by
+          // that name, in which case the user's own catalogue outranks our
+          // keyword — a tier you cannot point at is worse than a clumsier way
+          // to clear one.
+          const unset = target === "off" && catalogue?.includes("off") !== true;
+          if (!unset && catalogue && !catalogue.includes(target)) {
+            ctx.ui.notify(
+              `"${target}" is not a tier this host defines. Available: ${catalogue.join(", ") || "(none)"}. ` +
+                "Define it in /agents → Model tiers first.",
+              "warning",
+            );
+            return;
+          }
+          const { table: current, shipped } = effective();
+          if (shipped && knownTiers === undefined) {
+            // Seeding from a default we cannot compute would write a one-entry
+            // 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(
+              "The tier catalogue is unavailable, so the current table cannot be read. " +
+                "Retry once the managed peer is reachable.",
+              "warning",
+            );
+            return;
+          }
+          // Seeded from the table a run would use, not from this project's file.
+          // Every level of this key replaces the one below rather than merging
+          // into it, so a patch built on project scope would silently drop
+          // whatever the level below contributed: adding one entry would discard
+          // an inherited global table, and `off` against an entry this project
+          // never wrote would write nothing and leave the mapping standing. The
+          // seed does freeze the current table into the project, which is what a
+          // replace-wholesale key costs — the entries a partial file left out
+          // would be unmapped, not inherited.
+          const { [strength]: _cleared, ...others } = current;
+          try {
+            persistWorkflowSetting({ strengths: unset ? others : { ...others, [strength]: target } });
+          } catch (error: unknown) {
+            ctx.ui.notify(
+              `Could not save workflow strength routing: ${error instanceof Error ? error.message : String(error)}`,
+              "warning",
+            );
+            return;
+          }
+          // Show the resolved result rather than echoing the write. The
+          // settings layer can drop what it was handed, and `off` against the
+          // last remaining entry stores an explicit empty table — "map nothing",
+          // which is not the same as the shipped default an absent key would
+          // mean — so a message announcing the write would describe something
+          // other than what the next run will do. Runs already in flight keep
+          // what they started with; the table is read fresh at each start and
+          // resume.
+          //
+          // The one case the table alone cannot explain: the host defines a tier
+          // named `off`, so the keyword lost to it above and this mapped rather
+          // than cleared. The catalogue outranking our keyword is the right call
+          // — a tier you cannot point at is worse than a clumsier way to clear
+          // one — but a user who typed the documented keyword and got a mapping
+          // has to be told which reading won, and where the other one lives.
+          const shadowed =
+            target === "off" && !unset
+              ? '\n\nNote: this host defines a tier named "off", so `off` was read as that tier rather ' +
+                "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");
+          return;
+        }
         ctx.ui.notify(`Unknown /workflows subcommand: ${subcommand}`, "warning");
       },
     });
 
-    // /workflows-models: tier configuration is owned by pi-subagents; this
-    // command documents the delegation (A8: no second tier config file).
-    pi.registerCommand("workflows-models", {
-      description: "Workflow tier routing: tiers are configured in pi-subagents /agents → Model tiers",
-      handler: async (_args: string, ctx: ExtensionCommandContext) => {
-        ctx.ui.notify(
-          "Workflow tiers (small/medium/large) route through pi-subagents' workflow.tiers settings. " +
-            "Use /agents → Model tiers to configure them.",
-          "info",
-        );
-      },
-    });
-
     // /workflows-progress: persistent compact/detailed live-panel settings.
     pi.registerCommand("workflows-progress", {
       description: "Workflow progress panel: compact|detailed|status|max <N>",
@@ -547,21 +831,22 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           );
           return;
         }
+        let patch: WorkflowSettings;
         if (action === "compact" || action === "detailed") {
-          workflowSettings = { ...workflowSettings, progressMode: action };
+          patch = { progressMode: action };
         } 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");
             return;
           }
-          workflowSettings = { ...workflowSettings, maxAgentsShown: max };
+          patch = { maxAgentsShown: max };
         } else {
           ctx.ui.notify("Usage: /workflows-progress compact|detailed|status|max <N>", "warning");
           return;
         }
         try {
-          saveWorkflowSettings(workflowSettings, sessionCwd);
+          persistWorkflowSetting(patch);
           refreshWidget();
           ctx.ui.notify(
             `Workflow progress set to ${workflowSettings.progressMode}, max ${workflowSettings.maxAgentsShown}.`,
@@ -582,13 +867,10 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     // is annotated to say so. 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.
-    let triggerKeyword: string | undefined = workflowSettings.keywordTriggerWord;
-    let keywordTriggerEnabled = workflowSettings.keywordTriggerEnabled;
     const TRIGGER_WORD_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/u;
     const persistTriggerSettings = (): void => {
-      workflowSettings = { ...workflowSettings, keywordTriggerWord: triggerKeyword, keywordTriggerEnabled };
       try {
-        saveWorkflowSettings(workflowSettings, sessionCwd);
+        persistWorkflowSetting({ keywordTriggerWord: triggerKeyword, keywordTriggerEnabled });
       } catch {
         /* setting changes remain active in memory */
       }
@@ -647,7 +929,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       if (event.text.includes(WORKFLOW_ARMED_DIRECTIVE)) return { action: "continue" as const };
       const effortDirective =
         effortLevel === "ultra"
-          ? "Effort: ULTRA. Be exhaustive: use broad parallel review, verification, and completeness checks; choose the large tier where useful."
+          ? 'Effort: ULTRA. Be exhaustive: use broad parallel review, verification, and completeness checks; give the deepest steps strength: "high".'
           : effortLevel === "high"
             ? "Effort: HIGH. Be thorough: use several independent reviewers and an adversarial verification pass."
             : "";
@@ -669,9 +951,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           return;
         }
         effortLevel = level;
-        workflowSettings = { ...workflowSettings, effort: effortLevel };
         try {
-          saveWorkflowSettings(workflowSettings, sessionCwd);
+          persistWorkflowSetting({ effort: effortLevel });
         } catch {
           /* warning is non-fatal */
         }
@@ -687,9 +968,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       description: "Ultracode: toggle exhaustive workflow effort",
       handler: async (args: string, ctx: ExtensionCommandContext) => {
         effortLevel = args.trim().toLowerCase() === "off" ? "off" : "ultra";
-        workflowSettings = { ...workflowSettings, effort: effortLevel };
         try {
-          saveWorkflowSettings(workflowSettings, sessionCwd);
+          persistWorkflowSetting({ effort: effortLevel });
         } catch {
           /* warning is non-fatal */
         }
@@ -708,7 +988,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     // unregister or replace a command, so clobbering one is permanent.
     const claimedCommands = new Set((pi.getCommands?.() ?? []).map((command) => command.name));
     for (const name of Object.keys(BUILTIN_WORKFLOWS)) {
-      if (claimedCommands.has(name)) continue;
+      if (claimedCommands.has(name) || registeredWorkflowCommands.has(name)) continue;
       const descriptor = BUILTIN_WORKFLOWS[name];
       pi.registerCommand(name, {
         description: `Run the ${name} workflow`,
@@ -737,53 +1017,32 @@ export default function piWorkflows(pi: ExtensionAPI): void {
             background: true,
             toolset: descriptor.toolset,
             excludeTools: [...DEFAULT_EXCLUDED_TOOLS],
-            loadSavedWorkflow: (savedName) =>
-              loadSavedWorkflow(savedName, sessionCwd) ?? BUILTIN_WORKFLOWS[savedName]?.script,
+            loadSavedWorkflow: resolveNestedWorkflow,
+            strengths: workflowSettings.strengths,
           };
-          const result = await workflowEngine.start(descriptor.script, options);
-          void deliverBackgroundResult(workflowEngine, result.runId);
-          ctx.ui.notify(`Workflow ${name} started in background: ${result.runId}`, "info");
+          try {
+            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");
+          } catch (error: unknown) {
+            ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+          }
         },
       });
+      registeredWorkflowCommands.add(name);
     }
 
-    // Live progress widget (A10): renders only while runs are active, then
-    // clears itself. The widget is TUI-only; headless sessions skip it.
-    const refreshWidget = () => {
-      const tui = (pi as unknown as { ui?: { setWidget?: (key: string, content: string[] | undefined) => void } }).ui;
-      if (!tui?.setWidget) return;
-      const runs = workflowEngine
-        .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) {
-        widgetTimer = setInterval(() => {
-          if (!tui?.setWidget) return;
-          const current = workflowEngine
-            .list()
-            .map((summary) => workflowEngine.getRun(String(summary.runId)))
-            .filter((run): run is NonNullable<typeof run> => run !== undefined);
-          const next = liveWidgetLines(current, workflowSettings.progressMode, workflowSettings.maxAgentsShown);
-          tui.setWidget("pi-workflows", next.length > 0 ? next : undefined);
-          if (next.length === 0 && widgetTimer) {
-            clearInterval(widgetTimer);
-            widgetTimer = undefined;
-          }
-        }, 2_000);
-      } else if (lines.length === 0 && widgetTimer) {
-        clearInterval(widgetTimer);
-        widgetTimer = undefined;
-      }
-    };
-    // Refresh after any control action and on run settlement.
-    const notifyRunChanged = () => refreshWidget();
-    workflowEngine.onRunSettled = notifyRunChanged;
-    void notifyRunChanged;
-
+    // 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(
@@ -796,7 +1055,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       return branchQuiesce;
     };
 
-    unsubscribeTreeSignal = pi.events.on("subagents:session_before_tree", () => {
+    pi.events.on("subagents:session_before_tree", () => {
       void beginBranchQuiesce();
     });
 
@@ -810,6 +1069,12 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       } catch {
         return;
       }
+      let workflowEngine: WorkflowEngine;
+      try {
+        workflowEngine = currentEngine();
+      } catch {
+        return;
+      }
       workflowEngine.suspendLifecycle();
       try {
         workflowEngine.restore(entries);
@@ -894,18 +1159,22 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     // while the graph validates dependencies before dispatching any workers.
     const script = buildAdHocWorkflowScript(prompt);
     try {
-      await protocolCheck;
-      const result = await currentEngine().start(script, { background: true, mainModel: ctx.model?.id });
-      void deliverBackgroundResult(currentEngine(), result.runId);
+      const workflowEngine = currentEngine();
+      const result = await workflowEngine.start(script, {
+        background: true,
+        strengths: workflowSettings.strengths,
+        mainModel: ctx.model?.id,
+      });
+      void deliverBackgroundResult(workflowEngine, result.runId);
       return result.runId;
     } catch (error: unknown) {
-      ctx.ui.notify(protocolError ?? (error instanceof Error ? error.message : String(error)), "error");
+      ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
       return undefined;
     }
   };
 
   const saveWorkflowFromRun = async (ctx: ExtensionCommandContext, name: string, runId?: string): Promise<void> => {
-    const state = engine?.getState(runId ?? "");
+    const state = currentEngine().getState(runId ?? "");
     if (!state) {
       throw new Error(`Workflow run not found: ${runId ?? "(none)"}`);
     }
@@ -919,6 +1188,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     sessionCwd = ctx.cwd ?? process.cwd();
     workflowSettings = loadWorkflowSettings(sessionCwd);
     effortLevel = workflowSettings.effort;
+    triggerKeyword = workflowSettings.keywordTriggerWord;
+    keywordTriggerEnabled = workflowSettings.keywordTriggerEnabled;
     let initialEntries: SessionEntryLike[];
     try {
       initialEntries = ctx.sessionManager.getBranch() as unknown as SessionEntryLike[];
@@ -936,6 +1207,15 @@ export default function piWorkflows(pi: ExtensionAPI): void {
 
     protocolAbortController = new AbortController();
     const client = createManagedSpawnClient(pi.events, protocolAbortController.signal, protocolAbortController.signal);
+    protocolError = undefined;
+    protocolProbe = () =>
+      client.checkProtocol?.() ?? Promise.reject(new Error("managed protocol check is unavailable"));
+    protocolCheck = trackProbe(protocolProbe());
+    void protocolCheck.catch((error: unknown) => {
+      if (generation !== lifecycleGeneration) return;
+      const detail = error instanceof Error ? error.message : String(error);
+      protocolError = `${PROTOCOL_DIAGNOSTIC} Diagnostic: ${detail}`;
+    });
 
     let recoveredEngine: WorkflowEngine | undefined;
     let recoveryError: unknown;
@@ -955,6 +1235,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
             return [];
           }
         },
+        awaitProtocol,
       );
       try {
         const entries =
@@ -1036,36 +1317,40 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     // name clashes first — never overwrite another extension's command.
     const existingCommands = new Set((pi.getCommands?.() ?? []).map((command) => command.name));
     for (const savedName of listSavedWorkflows(sessionCwd)) {
-      if (existingCommands.has(savedName)) continue;
-      const script = loadSavedWorkflow(savedName, sessionCwd);
-      if (!script) continue;
+      if (existingCommands.has(savedName) || registeredWorkflowCommands.has(savedName)) continue;
+      if (!loadSavedWorkflow(savedName, sessionCwd)) continue;
       pi.registerCommand(savedName, {
         description: `Run the saved workflow ${savedName}`,
         handler: async (args: string, commandCtx: ExtensionCommandContext) => {
-          const options: ScriptStartOptions = {
-            args: args.trim() ? { prompt: args.trim() } : undefined,
-            background: true,
-            mainModel: commandCtx?.model?.id,
-            loadSavedWorkflow: (name) => loadSavedWorkflow(name, sessionCwd) ?? BUILTIN_WORKFLOWS[name]?.script,
-          };
-          const result = await recoveredEngine.start(script, options);
-          void deliverBackgroundResult(recoveredEngine, result.runId);
-          commandCtx.ui.notify(`Workflow ${savedName} started in background: ${result.runId}`, "info");
+          try {
+            const workflowEngine = currentEngine();
+            const script = loadSavedWorkflow(savedName, sessionCwd) ?? BUILTIN_WORKFLOWS[savedName]?.script;
+            if (!script) throw new Error(`Saved workflow "${savedName}" is no longer available.`);
+            const options: ScriptStartOptions = {
+              args: args.trim() ? { prompt: args.trim() } : undefined,
+              background: true,
+              mainModel: commandCtx?.model?.id,
+              loadSavedWorkflow: resolveNestedWorkflow,
+              strengths: workflowSettings.strengths,
+            };
+            const result = await workflowEngine.start(script, options);
+            void deliverBackgroundResult(workflowEngine, result.runId);
+            commandCtx.ui.notify(`Workflow ${savedName} started in background: ${result.runId}`, "info");
+          } catch (error: unknown) {
+            commandCtx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+          }
         },
       });
+      registeredWorkflowCommands.add(savedName);
     }
-
-    protocolError = undefined;
-    protocolCheck = client.checkProtocol?.() ?? Promise.reject(new Error("managed protocol check is unavailable"));
-    void protocolCheck.catch((error: unknown) => {
-      if (generation !== lifecycleGeneration) return;
-      const detail = error instanceof Error ? error.message : String(error);
-      protocolError = `${PROTOCOL_DIAGNOSTIC} Diagnostic: ${detail}`;
-    });
   });
 
   pi.on("session_shutdown", async () => {
     lifecycleGeneration += 1;
+    // Invalidate all long-lived command/tool/widget closures before awaiting
+    // engine quiescence; the old session must not accept another run.
+    active = false;
+    clearWidget();
     if (widgetTimer) {
       clearInterval(widgetTimer);
       widgetTimer = undefined;
@@ -1076,13 +1361,12 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     }
     protocolAbortController?.abort();
     protocolAbortController = undefined;
-    unsubscribeTreeSignal?.();
-    unsubscribeTreeSignal = undefined;
     closingEngine?.dispose();
     engine = undefined;
-    active = false;
     branchQuiesce = undefined;
-    protocolCheck = Promise.resolve();
+    protocolCheck = undefined;
+    protocolProbe = undefined;
+    protocolInFlight = undefined;
     protocolError = undefined;
     deliverResult = undefined;
   });