@signalridge/pi-workflows 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.10.0
+### Minor Changes
+
+- a4dc1de: Expose optional session/branch-owned status navigation to the existing workflow navigator and add compact run-authoritative footer counts without changing execution or widget behavior.
+
 ## 1.9.0
 ### Minor Changes
 

package/README.md

@@ -544,3 +544,21 @@ used it.
 - **Schema validation is client-side.** The managed request does not assume a structured-output tool; the runtime asks for JSON, parses, validates (including `additionalProperties`), and repairs across bounded attempts.
 
 State is persisted as `pi.appendEntry("pi-workflows:journal", ...)` custom entries (schema v4), including frozen invocation args, resolved tier identity, terminal result previews, script revisions, named nested-workflow result boundaries, and durable removals. Interrupted/provider-limited runs replay from the journal; pre-schema-v4 journals are quarantined rather than replayed. Foreground `AbortSignal`s stop owned children through explicit owner-scoped stop/quiescence, and dispose/branch replacement reject stale waiters. Navigation preflight vetoes while agents or workflows are active or cleaning up, without interrupting them. An accepted tree commit fences old callbacks in either extension load order and restores only the committed branch; preflight itself is not a commit point.
+
+## Status navigation
+
+With a compatible status selector, **Ctrl+Alt+S**, choose **Workflow runs**, then
+**Enter** opens this package's existing workflow navigator. `/workflows` and its
+watch/detail paths remain unchanged. Querying this optional TUI-only endpoint
+never opens a screen, starts/resumes a run, or sends a model/user message. Each
+selection belongs to one live session/branch surface; navigation and reload
+retire it rather than redirecting an old selection to another owner. Only
+bounded identifiers and labels cross this presentation wire, not execution
+controls, source, logs, or callbacks.
+
+The compact `pi-workflows` footer reports `A` active runs (pending, running,
+pausing, stopping) and `P` paused/interrupted runs. With only retained terminal
+runs it reports `C` completed, `F` failed, and `S` stopped counts; an empty run
+list clears it. Counts reflect run status, never inferred child completion.
+This uses the existing progress refresh cadence without adding another widget
+or taking focus.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-workflows",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Deterministic JavaScript orchestration workflows backed by pi-subagents managed spawning.",
   "type": "module",
   "license": "MIT",

package/skills/workflow-authoring/SKILL.md

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

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

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

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

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

package/skills/workflow-patterns/SKILL.md

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

package/skills/workflow-review/SKILL.md

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

package/src/index.ts

@@ -17,6 +17,7 @@ import {
   queryChildSessionContextImmediate,
 } from "./rpc-client.js";
 import { listSavedWorkflows, loadSavedWorkflow, saveWorkflow } from "./saved-workflows.js";
+import { guardStatusMount, StatusActions, type StatusSurface, workflowStatusSummary } from "./status-actions.js";
 import {
   defaultStrengthTable,
   isWorkflowStrength,
@@ -379,6 +380,16 @@ export default function piWorkflows(pi: ExtensionAPI): void {
   let workflowUiBridge: WorkflowUiBridge | undefined;
   let workflowUiSurfaceId = randomUUID();
   let refreshQueued = false;
+  let statusActions: StatusActions | undefined;
+  let statusSource: (() => StatusSurface | undefined) | undefined;
+  const navigatorOpen = new Map<string, number>();
+  const retireStatusActions = (): void => {
+    const hadStatus = !!statusSource;
+    statusActions?.dispose();
+    statusActions = undefined;
+    statusSource = undefined;
+    if (hadStatus && deliveryContext?.mode === "tui") deliveryContext.ui.setStatus("pi-workflows", undefined);
+  };
 
   const currentEngine = (): WorkflowEngine => {
     if (!active || !engine || engine.isDisposed())
@@ -409,6 +420,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     return { cancel: true };
   };
   const invalidateDelivery = (): void => {
+    navigatorOpen.delete(workflowUiSurfaceId);
+    retireStatusActions();
     workflowUiBridge?.retire(workflowUiSurfaceId);
     workflowUiSurfaceId = randomUUID();
     deliveryGeneration++;
@@ -482,6 +495,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       .list()
       .map((summary) => workflowEngine.getRun(String(summary.runId)))
       .filter((run): run is NonNullable<typeof run> => run !== undefined);
+    if (statusSource?.()) tui.setStatus("pi-workflows", workflowStatusSummary(runs));
     const hasActive = runs.some((run) => !["completed", "failed", "stopped"].includes(run.status));
     const surfaceId = workflowUiSurfaceId;
     tui.setWidget(
@@ -578,7 +592,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     throw new Error("Provide either `script` or `name`.");
   };
 
-  const showNavigator = async (ctx: ExtensionContext, initialRunId?: string): Promise<void> => {
+  const showNavigator = async (ctx: ExtensionContext, initialRunId?: string, guard?: () => void): Promise<void> => {
+    guard?.();
     if (ctx.mode !== "tui" || !ctx.hasUI) {
       await showWorkflowNavigator(ctx, currentEngine, { initialRunId });
       return;
@@ -588,6 +603,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     const manager = ctx.sessionManager;
     const sessionId = manager.getSessionId();
     const resolve = (): WorkflowEngine => {
+      guard?.(); // Keep a mounted status navigator bound to its exact source.
       if (
         surfaceId !== workflowUiSurfaceId ||
         selectedEngine !== currentEngine() ||
@@ -598,38 +614,104 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         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;
-            }
-          },
-        );
-      },
-    });
+    navigatorOpen.set(surfaceId, (navigatorOpen.get(surfaceId) ?? 0) + 1);
+    try {
+      await showWorkflowNavigator(guard ? guardStatusMount(ctx, guard) : 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;
+              }
+            },
+          );
+        },
+      });
+    } finally {
+      // An obsolete factory cannot hold or release a replacement surface's slot.
+      const remaining = (navigatorOpen.get(surfaceId) ?? 0) - 1;
+      if (remaining > 0) navigatorOpen.set(surfaceId, remaining);
+      else navigatorOpen.delete(surfaceId);
+    }
+  };
+
+  const registerStatusActions = (): void => {
+    const ctx = deliveryContext;
+    if (!active || !engine || ctx?.mode !== "tui" || !ctx.hasUI) return;
+    const selectedEngine = currentEngine();
+    const surfaceId = workflowUiSurfaceId;
+    const manager = ctx.sessionManager;
+    const sessionId = manager.getSessionId();
+    let branchIds = manager.getBranch().map((entry) => entry.id);
+    let retired = false;
+    const source = (): StatusSurface | undefined => {
+      if (retired) return;
+      let valid = false;
+      try {
+        const branch = manager.getBranch().map((entry) => entry.id);
+        valid =
+          active &&
+          engine === selectedEngine &&
+          !selectedEngine.isDisposed() &&
+          workflowUiSurfaceId === surfaceId &&
+          deliveryContext?.sessionManager === manager &&
+          manager.getSessionId() === sessionId &&
+          ctx.mode === "tui" &&
+          ctx.hasUI &&
+          ownsDeliveryBranch() &&
+          branchIds.every((id, index) => branch[index] === id);
+        if (valid) branchIds = branch;
+      } catch {
+        // A disposed context permanently retires this presentation surface.
+      }
+      if (!valid) {
+        retired = true;
+        if (statusSource === source) retireStatusActions();
+        return;
+      }
+      return {
+        owner: selectedEngine,
+        surfaceId,
+        sessionId,
+        busy: () => (navigatorOpen.get(surfaceId) ?? 0) > 0,
+        open: () =>
+          showNavigator(ctx, undefined, () => {
+            if (!source()) throw new Error("Workflow status surface is retired.");
+          }),
+      };
+    };
+    statusSource = source;
+    statusActions = new StatusActions(
+      pi.events,
+      { providerId: "pi-workflows", statusKey: "pi-workflows", actionId: "runs", label: "Workflow runs" },
+      source,
+    );
+    if (source())
+      ctx.ui.setStatus(
+        "pi-workflows",
+        workflowStatusSummary(selectedEngine.list().map((run) => ({ status: String(run.status) }))),
+      );
   };
 
   const workflowUiSurface = (): WorkflowUiSurface | undefined => {
@@ -1452,6 +1534,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         workflowEngine.resumeLifecycle();
         deliveryContext = ctx;
         deliveryBranchAnchor = journalBranchAnchor;
+        registerStatusActions();
         hydratePendingDeliveries(entries);
         schedulePendingDeliveries();
       } catch (error: unknown) {
@@ -1799,6 +1882,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     // ownership, not a captured function value, provide session affinity.
     deliveryContext = ctx;
     deliveryBranchAnchor = journalBranchAnchor;
+    registerStatusActions();
     workflowUiBridge ??= new WorkflowUiBridge(pi.events, workflowUiSurface);
     workflowUiBridge.publish();
     inputPreparing = false;

package/src/status-actions.ts

@@ -0,0 +1,143 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const STATUS_QUERY = "pi-ui:status-actions:v1:query";
+export const STATUS_OPEN = "pi-ui:status-actions:v1:open";
+const FAILURE = "Status action is unavailable.";
+
+export interface StatusSurface {
+  surfaceId: string;
+  sessionId: string;
+  /** Private identity, never placed on the wire. */
+  owner: object;
+  busy(): boolean;
+  open(): Promise<void>;
+}
+
+/** Inspect descriptors, never values on an untrusted object (including getters). */
+function request(raw: unknown, keys: readonly string[]): Record<string, unknown> | undefined {
+  try {
+    if (!raw || typeof raw !== "object") return;
+    const prototype = Object.getPrototypeOf(raw);
+    if (prototype !== Object.prototype && prototype !== null) return;
+    const descriptors = Object.getOwnPropertyDescriptors(raw);
+    if (Reflect.ownKeys(descriptors).length !== keys.length) return;
+    const values: Record<string, unknown> = Object.create(null);
+    for (const key of keys) {
+      const descriptor = descriptors[key];
+      if (!descriptor || !("value" in descriptor)) return;
+      const value: unknown = descriptor.value;
+      if (key === "version" ? value !== 1 : typeof value !== "string" || value.length < 1 || value.length > 128) return;
+      values[key] = value;
+    }
+    return values;
+  } catch {
+    return;
+  }
+}
+
+/** Optional presentation-only endpoint; the source must fail closed on live divergence. */
+export class StatusActions {
+  private readonly unsubscribe: Array<() => void>;
+  private disposed = false;
+  private opening = false;
+  private readonly admitted = new Set<string>();
+
+  constructor(
+    private readonly events: ExtensionAPI["events"],
+    private readonly descriptor: { providerId: string; statusKey: string; actionId: string; label: string },
+    private readonly source: () => StatusSurface | undefined,
+  ) {
+    this.unsubscribe = [
+      events.on(STATUS_QUERY, (raw: unknown) => this.query(raw)),
+      events.on(STATUS_OPEN, (raw: unknown) => this.open(raw)),
+    ];
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    for (const unsubscribe of this.unsubscribe) unsubscribe();
+    this.admitted.clear();
+  }
+
+  private query(raw: unknown): void {
+    if (this.disposed) return;
+    const parsed = request(raw, ["version", "requestId", "sessionId"]);
+    if (!parsed) return;
+    const surface = this.source();
+    if (!surface || parsed.sessionId !== surface.sessionId || this.disposed) return;
+    this.events.emit(`${STATUS_QUERY}:reply:${parsed.requestId}`, {
+      success: true,
+      data: {
+        version: 1,
+        providerId: this.descriptor.providerId,
+        surfaceId: surface.surfaceId,
+        sessionId: surface.sessionId,
+        entries: [
+          { statusKey: this.descriptor.statusKey, actionId: this.descriptor.actionId, label: this.descriptor.label },
+        ],
+      },
+    });
+  }
+
+  private open(raw: unknown): void {
+    if (this.disposed) return;
+    const parsed = request(raw, ["version", "requestId", "providerId", "surfaceId", "sessionId", "actionId"]);
+    if (!parsed || parsed.providerId !== this.descriptor.providerId) return;
+    const surface = this.source();
+    if (!surface || this.disposed || parsed.sessionId !== surface.sessionId || parsed.surfaceId !== surface.surfaceId)
+      return; // Other owners, including duplicate providers, may share this bus.
+    const channel = `${STATUS_OPEN}:reply:${parsed.requestId}`;
+    const id = String(parsed.requestId);
+    if (parsed.actionId !== this.descriptor.actionId || this.opening || surface.busy() || this.admitted.has(id)) {
+      this.events.emit(channel, { success: false, error: FAILURE });
+      return;
+    }
+    this.admitted.add(id);
+    if (this.admitted.size > 256) this.admitted.delete(this.admitted.values().next().value as string);
+    this.opening = true;
+    // Admission is synchronous; the selector can relinquish focus before mount.
+    this.events.emit(channel, { success: true, data: { accepted: true } });
+    void Promise.resolve()
+      .then(() => {
+        if (this.disposed) return;
+        const current = this.source();
+        if (
+          this.disposed ||
+          !current ||
+          current.owner !== surface.owner ||
+          current.surfaceId !== surface.surfaceId ||
+          current.sessionId !== surface.sessionId
+        )
+          return;
+        return surface.open();
+      })
+      .catch(() => {
+        // Admission does not promise successful mount. Never redirect to another owner.
+      })
+      .finally(() => {
+        this.opening = false;
+      });
+  }
+}
+
+/** The host may defer a custom factory after admission; fence that boundary too. */
+export function guardStatusMount(ctx: ExtensionContext, guard: () => void): ExtensionContext {
+  const custom: ExtensionContext["ui"]["custom"] = (factory, options) =>
+    ctx.ui.custom((...args) => {
+      guard();
+      return factory(...args);
+    }, options);
+  return { ...ctx, ui: { ...ctx.ui, custom } };
+}
+
+/** Count run authority only; child completion cannot establish run completion. */
+export function workflowStatusSummary(runs: ReadonlyArray<{ status: string }>): string | undefined {
+  if (!runs.length) return undefined;
+  const count = (statuses: string[]) => runs.filter((run) => statuses.includes(run.status)).length;
+  const active = count(["pending", "running", "pausing", "stopping"]);
+  const paused = count(["paused", "interrupted"]);
+  return active || paused
+    ? `Workflows · A${active} P${paused}`
+    : `Workflows · C${count(["completed"])} F${count(["failed"])} S${count(["stopped"])}`;
+}