@bastani/atomic 0.9.11-alpha.5 → 0.9.11-alpha.7

package/dist/builtin/workflows/src/shared/persistence-restore-helpers.ts

@@ -6,6 +6,7 @@ import type {
   RunStatus,
   StageSnapshot,
   StageStatus,
+  ToolNodeSnapshot,
   WorkflowFailureCode,
   WorkflowFailureDisposition,
   WorkflowFailureKind,
@@ -263,6 +264,29 @@ function numericDuration(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
 }
 
+function restoreFailedToolNode(value: unknown): ToolNodeSnapshot | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const node = value as Partial<ToolNodeSnapshot>;
+  if (node.kind !== "tool" || typeof node.id !== "string" || typeof node.name !== "string"
+    || typeof node.argsHash !== "string" || typeof node.ordinal !== "number" || !Number.isInteger(node.ordinal)
+    || !Array.isArray(node.parentIds) || !node.parentIds.every((parentId) => typeof parentId === "string")
+    || node.status !== "failed" || typeof node.error !== "string") return undefined;
+  return {
+    kind: "tool",
+    id: node.id,
+    name: node.name,
+    argsHash: node.argsHash,
+    ordinal: node.ordinal,
+    parentIds: Object.freeze([...node.parentIds]),
+    status: "failed",
+    ...(typeof node.executionOrder === "number" && Number.isFinite(node.executionOrder) ? { executionOrder: node.executionOrder } : {}),
+    ...(numericTimestamp(node.startedAt) !== undefined ? { startedAt: node.startedAt } : {}),
+    ...(numericTimestamp(node.endedAt) !== undefined ? { endedAt: node.endedAt } : {}),
+    error: node.error,
+    attachable: false,
+  };
+}
+
 export function findRunBlockedMetadata(
   entries: readonly SessionEntry[],
   runId: string,
@@ -342,6 +366,8 @@ export function restoreTerminalRuns(entries: readonly SessionEntry[], store: Sto
     const exited = end["exited"];
     const exitReason = end["exitReason"];
     const resumable = end["resumable"];
+    const failedToolNodeId = end["failedToolNodeId"];
+    const failedToolNode = restoreFailedToolNode(end["failedToolNode"]);
     const restoredAuthorExit = isWorkflowExitTerminalStatus(status) &&
       (exited === true || typeof exitReason === "string");
     if (status === "completed" && !restoredAuthorExit && stages.some((stage) => stage.status !== "completed")) continue;
@@ -351,6 +377,9 @@ export function restoreTerminalRuns(entries: readonly SessionEntry[], store: Sto
       inputs: start.inputs,
       status: "running",
       stages,
+      ...(typeof failedToolNodeId === "string" && failedToolNode?.id === failedToolNodeId
+        ? { toolNodes: [failedToolNode] }
+        : {}),
       startedAt: start.startTs,
       ...(runMeta.parentRunId !== undefined ? { parentRunId: runMeta.parentRunId } : {}),
       ...(runMeta.parentStageId !== undefined ? { parentStageId: runMeta.parentStageId } : {}),
@@ -384,6 +413,7 @@ export function restoreTerminalRuns(entries: readonly SessionEntry[], store: Sto
         ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
         ...(typeof failureMessage === "string" ? { failureMessage } : {}),
         ...(typeof failedStageId === "string" ? { failedStageId } : {}),
+        ...(typeof failedToolNodeId === "string" ? { failedToolNodeId } : {}),
         ...(typeof resumable === "boolean" ? { resumable } : isWorkflowExitTerminalStatus(status) && restoredAuthorExit ? { resumable: false } : {}),
         ...(restoredAuthorExit && isWorkflowExitTerminalStatus(status) ? { exited: true } : {}),
         ...(typeof exitReason === "string" ? { exitReason } : {}),

package/dist/builtin/workflows/src/shared/persistence-session-entries.ts

@@ -11,6 +11,7 @@ import type {
   WorkflowFailureCode,
   WorkflowFailureDisposition,
   WorkflowFailureKind,
+  ToolNodeSnapshot,
 } from "./store-types.js";
 
 // ---------------------------------------------------------------------------
@@ -112,6 +113,8 @@ export interface RunEndPayload {
   readonly failureDisposition?: string;
   readonly failureMessage?: string;
   readonly failedStageId?: string;
+  readonly failedToolNodeId?: string;
+  readonly failedToolNode?: ToolNodeSnapshot;
   readonly resumable?: boolean;
   readonly retryAfterMs?: number;
   readonly endedAt?: number;
@@ -257,6 +260,8 @@ export function appendRunEnd(api: PersistenceAPI, payload: RunEndPayload): void
     ...(terminalPayload.failureDisposition !== undefined ? { failureDisposition: terminalPayload.failureDisposition } : {}),
     ...(terminalPayload.failureMessage !== undefined ? { failureMessage: terminalPayload.failureMessage } : {}),
     ...(terminalPayload.failedStageId !== undefined ? { failedStageId: terminalPayload.failedStageId } : {}),
+    ...(terminalPayload.failedToolNodeId !== undefined ? { failedToolNodeId: terminalPayload.failedToolNodeId } : {}),
+    ...(terminalPayload.failedToolNode !== undefined ? { failedToolNode: terminalPayload.failedToolNode } : {}),
     ...(terminalPayload.resumable !== undefined ? { resumable: terminalPayload.resumable } : {}),
     ...(terminalPayload.retryAfterMs !== undefined ? { retryAfterMs: terminalPayload.retryAfterMs } : {}),
     ...(terminalPayload.endedAt !== undefined ? { endedAt: terminalPayload.endedAt } : {}),

package/dist/builtin/workflows/src/shared/render-inputs-schema.ts

@@ -22,13 +22,13 @@
  * The layout in pretty mode mirrors bastani-inc/atomic's `renderInputsText` so a
  * dev moving between the atomic CLI and the pi extension feels at home:
  *
- *     INPUTS FOR ralph
+ *     INPUTS FOR repository-audit
  *
  *     prompt          text · required
- *       The high-level task to plan and execute.
+ *       The repository area to inspect.
  *
  *     iterations      number · optional
- *       Loop budget before bailing out.
+ *       Loop budget before stopping.
  *       default: 5
  *
  *     focus           select · required

package/dist/builtin/workflows/src/shared/store-factory.ts

@@ -3,12 +3,14 @@ import { createStoreContext } from "./store-internal.js";
 import { createPromptStoreMethods } from "./store-prompt-methods.js";
 import { createRunStoreMethods } from "./store-run-methods.js";
 import { createStageStoreMethods } from "./store-stage-methods.js";
+import { createToolNodeStoreMethods } from "./store-tool-node-methods.js";
 
 export function createStore(): Store {
   const context = createStoreContext();
   return {
     ...createRunStoreMethods(context),
     ...createStageStoreMethods(context),
+    ...createToolNodeStoreMethods(context),
     ...createPromptStoreMethods(context),
   };
 }

package/dist/builtin/workflows/src/shared/store-internal.ts

@@ -27,6 +27,11 @@ export const TERMINAL_STATUSES: ReadonlySet<RunStatus> = new Set([
   "blocked",
 ]);
 
+/** Shared executor/store authority for terminal workflow lifecycle states. */
+export function isTerminalRunStatus(status: RunStatus): boolean {
+  return TERMINAL_STATUSES.has(status);
+}
+
 export interface ResolverEntry {
   readonly promptId: string;
   readonly resolve: (response: unknown) => void;
@@ -86,6 +91,7 @@ export function clearRunFailureMetadata(run: RunSnapshot): void {
   delete run.failureDisposition;
   delete run.failureMessage;
   delete run.failedStageId;
+  delete run.failedToolNodeId;
   delete run.resumable;
   delete run.retryAfterMs;
   delete run.blockedAt;
@@ -100,6 +106,7 @@ export function clearStaleBlockedRunMetadata(run: RunSnapshot, metadata: RunEndM
   if (metadata?.failureDisposition === undefined) delete run.failureDisposition;
   if (metadata?.failureMessage === undefined) delete run.failureMessage;
   if (metadata?.failedStageId === undefined) delete run.failedStageId;
+  if (metadata?.failedToolNodeId === undefined) delete run.failedToolNodeId;
   if (metadata?.resumable === undefined) delete run.resumable;
   if (metadata?.retryAfterMs === undefined) delete run.retryAfterMs;
   if (metadata?.exited === undefined) delete run.exited;
@@ -114,6 +121,7 @@ export function applyRunEndMetadata(run: RunSnapshot, metadata: RunEndMetadata):
   if (metadata.retryAfterMs !== undefined) run.retryAfterMs = metadata.retryAfterMs;
   if (metadata.failureMessage !== undefined) run.failureMessage = metadata.failureMessage;
   if (metadata.failedStageId !== undefined) run.failedStageId = metadata.failedStageId;
+  if (metadata.failedToolNodeId !== undefined) run.failedToolNodeId = metadata.failedToolNodeId;
   if (metadata.resumable !== undefined) run.resumable = metadata.resumable;
   if (metadata.exited !== undefined) run.exited = metadata.exited;
   if (metadata.exitReason !== undefined) run.exitReason = metadata.exitReason;

package/dist/builtin/workflows/src/shared/store-public-types.ts

@@ -8,6 +8,7 @@ import type {
   StageNotice,
   StoreSnapshot,
   ToolEvent,
+  ToolNodeSnapshot,
   RunStatus,
   WorkflowFailureKind,
   WorkflowFailureCode,
@@ -24,6 +25,8 @@ export interface RunEndMetadata {
   readonly failureDisposition?: WorkflowFailureDisposition;
   readonly failureMessage?: string;
   readonly failedStageId?: string;
+  /** Tool node whose rejection supplied the selected terminal failure. */
+  readonly failedToolNodeId?: string;
   readonly resumable?: boolean;
   readonly retryAfterMs?: number;
   readonly exited?: boolean;
@@ -73,7 +76,12 @@ export interface Store {
   notices(): readonly WorkflowNotice[];
   activeRunId(): string | null;
   recordRunStart(run: RunSnapshot): void;
+  /** Compare-and-swap a cached child run's owning boundary during durable replay. */
+  reconcileRunParentStage(runId: string, expectedParentStageId: string, parentStageId: string): boolean;
   recordStageStart(runId: string, stage: StageSnapshot): void;
+  recordToolNodeStart(runId: string, node: ToolNodeSnapshot): boolean;
+  recordToolNodeRunning(runId: string, nodeId: string, startedAt: number): boolean;
+  recordToolNodeEnd(runId: string, nodeId: string, update: Pick<ToolNodeSnapshot, "status"> & Partial<Pick<ToolNodeSnapshot, "endedAt" | "resultSummary" | "error">>): boolean;
   /** Link a workflow boundary stage to its live child run before that child completes. */
   recordStageWorkflowChildRun(runId: string, stageId: string, ref: WorkflowChildRunRef): boolean;
   recordToolStart(runId: string, stageId: string, evt: ToolEvent): void;

package/dist/builtin/workflows/src/shared/store-run-methods.ts

@@ -17,6 +17,7 @@ type RunStoreMethods = Pick<
   | "notices"
   | "activeRunId"
   | "recordRunStart"
+  | "reconcileRunParentStage"
   | "recordRunEnd"
   | "recordRunBlocked"
   | "removeRun"
@@ -65,6 +66,14 @@ export function createRunStoreMethods(context: StoreContext): RunStoreMethods {
       context.bumpAndNotify();
     },
 
+    reconcileRunParentStage(runId: string, expectedParentStageId: string, parentStageId: string): boolean {
+      const run = context.findRun(runId);
+      if (run?.parentStageId !== expectedParentStageId || parentStageId === expectedParentStageId) return false;
+      run.parentStageId = parentStageId;
+      context.bumpAndNotify();
+      return true;
+    },
+
     recordRunEnd(
       runId: string,
       status: RunStatus,

package/dist/builtin/workflows/src/shared/store-stage-methods.ts

@@ -7,6 +7,7 @@ import type {
   WorkflowChildRunRef,
 } from "./store-types.js";
 import { accumulatePausedDurationMs } from "./timing.js";
+import { nextExecutionOrder } from "./store-tool-node-methods.js";
 import {
   cannotAwaitInput,
   cannotBlock,
@@ -41,6 +42,7 @@ export function createStageStoreMethods(context: StoreContext): StageStoreMethod
     recordStageStart(runId: string, stage: StageSnapshot): void {
       const run = context.findRun(runId);
       if (!run) return;
+      if (stage.executionOrder === undefined) stage.executionOrder = nextExecutionOrder(run);
       if (!run.stages.some((s) => s.id === stage.id)) {
         run.stages.push(stage);
       }

package/dist/builtin/workflows/src/shared/store-tool-node-methods.ts

@@ -0,0 +1,46 @@
+import type { Store } from "./store-public-types.js";
+import type { RunSnapshot, ToolNodeSnapshot } from "./store-types.js";
+import { TERMINAL_STATUSES, type StoreContext } from "./store-internal.js";
+
+type ToolNodeStoreMethods = Pick<Store, "recordToolNodeStart" | "recordToolNodeRunning" | "recordToolNodeEnd">;
+
+export function nextExecutionOrder(run: RunSnapshot): number {
+  const stageOrders = run.stages.map((stage) => stage.executionOrder ?? 0);
+  const toolOrders = (run.toolNodes ?? []).map((node) => node.executionOrder ?? 0);
+  return Math.max(0, ...stageOrders, ...toolOrders) + 1;
+}
+
+export function createToolNodeStoreMethods(context: StoreContext): ToolNodeStoreMethods {
+  return {
+    recordToolNodeStart(runId, node): boolean {
+      const run = context.findRun(runId);
+      if (run === undefined || TERMINAL_STATUSES.has(run.status)) return false;
+      const mutableRun = run as RunSnapshot & { toolNodes: ToolNodeSnapshot[] };
+      if (mutableRun.toolNodes === undefined) mutableRun.toolNodes = [];
+      const nodes = mutableRun.toolNodes;
+      if (nodes.some((candidate) => candidate.id === node.id)) return false;
+      if (node.executionOrder === undefined) node.executionOrder = nextExecutionOrder(run);
+      nodes.push(node);
+      context.bumpAndNotify();
+      return true;
+    },
+    recordToolNodeRunning(runId, nodeId, startedAt): boolean {
+      const node = context.findRun(runId)?.toolNodes?.find((candidate) => candidate.id === nodeId);
+      if (node === undefined || node.status !== "pending") return false;
+      node.status = "running";
+      node.startedAt = startedAt;
+      context.bumpAndNotify();
+      return true;
+    },
+    recordToolNodeEnd(runId, nodeId, update): boolean {
+      const node = context.findRun(runId)?.toolNodes?.find((candidate) => candidate.id === nodeId);
+      if (node === undefined || node.status === "completed" || node.status === "failed" || node.status === "cached" || node.status === "cancelled") return false;
+      node.status = update.status;
+      if (update.endedAt !== undefined) node.endedAt = update.endedAt;
+      if (update.resultSummary !== undefined) node.resultSummary = update.resultSummary;
+      if (update.error !== undefined) node.error = update.error;
+      context.bumpAndNotify();
+      return true;
+    },
+  };
+}

package/dist/builtin/workflows/src/shared/store-types.ts

@@ -16,6 +16,30 @@ export type StageStatus =
   | "failed"
   | "skipped";
 
+export type ToolNodeStatus = "pending" | "running" | "completed" | "failed" | "cached" | "cancelled";
+
+/** First-class, durable graph node created for each ctx.tool invocation. */
+export interface ToolNodeSnapshot {
+  readonly kind: "tool";
+  readonly id: string;
+  readonly name: string;
+  readonly argsHash: string;
+  readonly ordinal: number;
+  readonly parentIds: readonly string[];
+  status: ToolNodeStatus;
+  /** Set when a legacy checkpoint lacks persisted topology. */
+  topologyState?: "unavailable";
+  /** True when the callback was skipped in favor of a durable checkpoint. */
+  replayed?: boolean;
+  /** Shared admission order with stages in this run. */
+  executionOrder?: number;
+  startedAt?: number;
+  endedAt?: number;
+  resultSummary?: string;
+  error?: string;
+  readonly attachable: false;
+}
+
 export type WorkflowFailureKind = "auth" | "rate_limit" | "provider" | "cancelled" | "unknown";
 export type WorkflowFailureRecoverability = "recoverable" | "non_recoverable" | "unknown";
 export type WorkflowFailureDisposition = "active_blocked" | "terminal_killed" | "terminal_failed";
@@ -142,6 +166,12 @@ export interface StageSnapshot {
    * refreshes parents, so do not cache this reference across store updates.
    */
   parentIds: readonly string[];
+  /** Shared admission order with tool nodes in this run. */
+  executionOrder?: number;
+  /** View-only graph discriminator; authored stages omit this or use "stage". */
+  nodeKind?: "stage" | "tool";
+  /** Original tool state when a tool node is projected into stage-compatible graph rendering. */
+  toolStatus?: ToolNodeStatus;
   /** Set when durable inspection cannot safely determine the original stage lineage. */
   topologyState?: "unavailable";
   startedAt?: number;
@@ -237,6 +267,8 @@ export interface RunSnapshot {
   readonly inputs: Readonly<WorkflowInputValues>;
   status: RunStatus;
   readonly stages: StageSnapshot[];
+  /** Durable ctx.tool execution nodes. Optional only for legacy/restored snapshots. */
+  readonly toolNodes?: ToolNodeSnapshot[];
   startedAt: number;
   endedAt?: number;
   durationMs?: number;
@@ -273,6 +305,8 @@ export interface RunSnapshot {
   /** Original unsanitized error text when different from `error`. */
   failureMessage?: string;
   failedStageId?: string;
+  /** Tool node whose rejection supplied the selected terminal failure. */
+  failedToolNodeId?: string;
   resumable?: boolean;
   /** Parent workflow run when this snapshot is an internal child workflow run. Hidden from top-level status lists. */
   parentRunId?: string;

package/dist/builtin/workflows/src/shared/types.ts

@@ -193,6 +193,10 @@ export interface StageOptions<TSchemaDef extends TSchema | undefined = TSchema |
   durableReplayKey?: string;
   /** Internal durable timing baseline accumulated before a process-boundary resume. */
   durableAccumulatedDurationMs?: number;
+  /** Internal durable source identity reused when an active stage session is reopened. */
+  durableStageId?: string;
+  /** Internal durable source parents reused with `durableStageId`. */
+  durableParentIds?: readonly string[];
 }
 
 // ---------------------------------------------------------------------------
@@ -206,6 +210,8 @@ export interface StageOptions<TSchemaDef extends TSchema | undefined = TSchema |
 export interface StageExecutionMeta {
   /** Run ID of the containing workflow execution. */
   runId: string;
+  /** Runtime-owned home group shared by this top-level workflow invocation. */
+  workflowIntercomGroup?: string;
   /** Stage ID of the current stage. */
   stageId: string;
   /** Human-readable stage name. */
@@ -418,30 +424,14 @@ export interface WorkflowRunContext<
   readonly models?: WorkflowModelCatalogPort;
 }
 
-/**
- * `ctx.tool` primitive signature. Runs an async function and caches the result
- * durably via the durable workflow backend.
- */
-export interface WorkflowToolPrimitive {
-  <TValue extends WorkflowSerializableValue>(
-    name: string,
-    args: Readonly<Record<string, WorkflowSerializableValue>>,
-    fn: () => Promise<TValue>,
-    options?: WorkflowToolOptions,
-  ): Promise<TValue>;
-}
-
-/** Options for `ctx.tool`. */
-export interface WorkflowToolOptions {
-  /** When true, the tool function is retried on failure. Default false. */
-  readonly retriesAllowed?: boolean;
-  /** Max retry attempts when retriesAllowed is true. Default 3. */
-  readonly maxAttempts?: number;
-  /** Initial retry interval in ms. Default 1000. */
-  readonly intervalMs?: number;
-  /** Backoff multiplier. Default 2. */
-  readonly backoffRate?: number;
-}
+export type WorkflowToolError = AuthoringContract.WorkflowToolError;
+export type WorkflowToolFailure = AuthoringContract.WorkflowToolFailure;
+export type WorkflowToolOptions = AuthoringContract.WorkflowToolOptions;
+export type WorkflowToolOutcome<TValue extends WorkflowSerializableValue> = AuthoringContract.WorkflowToolOutcome<TValue>;
+export type WorkflowToolPrimitive = AuthoringContract.WorkflowToolPrimitive;
+export type WorkflowToolReturnOptions = AuthoringContract.WorkflowToolReturnOptions;
+export type WorkflowToolSuccess<TValue extends WorkflowSerializableValue> = AuthoringContract.WorkflowToolSuccess<TValue>;
+export type WorkflowToolThrowOptions = AuthoringContract.WorkflowToolThrowOptions;
 
 // ---------------------------------------------------------------------------
 // WorkflowRuntimeConfig — resolved runtime tunables injected at composition root

package/dist/builtin/workflows/src/shared/workflow-failures-classifier.ts

@@ -29,6 +29,8 @@ import {
   errorMessage,
   errorName,
   field,
+  hasProcessFailureEvidence,
+  selectProcessFailureError,
   nestedProviderError,
   normalizeCode,
   redactSensitiveText,
@@ -252,15 +254,19 @@ function failureForDecision(decision: WorkflowFailureDecision, message: string,
 }
 
 export function classifyWorkflowFailure(error: unknown): WorkflowFailure {
-  const message = errorMessage(error);
+  const displayError = selectProcessFailureError(error);
+  const message = errorMessage(displayError);
+  const hasProcessFailure = displayError !== error || hasProcessFailureEvidence(error);
   const structured = structuredClassification(error);
-  if (structured !== undefined) {
-    const structuredMessage = structured.message ?? message;
+  if (structured !== undefined && !(hasProcessFailure && structured.decision.code === "cancelled")) {
+    const structuredMessage = hasProcessFailure ? message : structured.message ?? message;
     return failureForDecision(structured.decision, structuredMessage, error);
   }
 
-  const fallback = fallbackDecisionFromMessage(message, errorName(error));
-  if (fallback !== undefined) return failureForDecision(fallback, message, error);
+  const fallback = fallbackDecisionFromMessage(message, errorName(displayError));
+  if (fallback !== undefined && !(hasProcessFailure && fallback.code === "cancelled")) {
+    return failureForDecision(fallback, message, error);
+  }
 
   return failureForDecision(unknownDecision(), message, error);
 }

package/dist/builtin/workflows/src/shared/workflow-failures-signals.ts

@@ -13,6 +13,64 @@ export function field(value: unknown, key: string): unknown {
   return asRecord(value)?.[key];
 }
 
+function safeField(value: unknown, key: string): unknown {
+  try {
+    return field(value, key);
+  } catch {
+    return undefined;
+  }
+}
+
+function nonZeroExitCode(value: unknown): boolean {
+  if (typeof value === "number") return Number.isFinite(value) && value !== 0;
+  if (typeof value !== "string") return false;
+  const parsed = Number(value.trim());
+  return Number.isFinite(parsed) && parsed !== 0;
+}
+
+function nonEmptyProcessOutput(value: unknown): boolean {
+  if (typeof value === "string") return value.length > 0;
+  if (value instanceof ArrayBuffer) return value.byteLength > 0;
+  return ArrayBuffer.isView(value) && value.byteLength > 0;
+}
+
+function findProcessFailureError(value: unknown, seen: Set<object>, depth: number): unknown | undefined {
+  if (value === null || typeof value !== "object" || depth >= 8 || seen.has(value)) return undefined;
+  seen.add(value);
+  if (nonZeroExitCode(safeField(value, "exitCode"))) return value;
+  if (nonEmptyProcessOutput(safeField(value, "stdout"))) return value;
+  if (nonEmptyProcessOutput(safeField(value, "stderr"))) return value;
+
+  for (const key of ["cause", "error", "response", "body"] as const) {
+    const selected = findProcessFailureError(safeField(value, key), seen, depth + 1);
+    if (selected !== undefined) return selected;
+  }
+  const diagnostics = safeField(value, "diagnostics");
+  if (Array.isArray(diagnostics)) {
+    for (const diagnostic of diagnostics) {
+      const selected = findProcessFailureError(safeField(diagnostic, "error") ?? diagnostic, seen, depth + 1);
+      if (selected !== undefined) return selected;
+    }
+  }
+  const errors = safeField(value, "errors");
+  if (!Array.isArray(errors)) return undefined;
+  for (const error of errors) {
+    const selected = findProcessFailureError(error, seen, depth + 1);
+    if (selected !== undefined) return selected;
+  }
+  return undefined;
+}
+
+/** Select the first nested value that proves a process command failed. */
+export function selectProcessFailureError(error: unknown): unknown {
+  return findProcessFailureError(error, new Set<object>(), 0) ?? error;
+}
+
+/** A nonzero exit or nonempty process output outranks cancellation-like wrapper fields. */
+export function hasProcessFailureEvidence(error: unknown): boolean {
+  return findProcessFailureError(error, new Set<object>(), 0) !== undefined;
+}
+
 function stringField(value: unknown, key: string): string | undefined {
   const raw = field(value, key);
   return typeof raw === "string" && raw.length > 0 ? raw : undefined;

package/dist/builtin/workflows/src/shared/workflow-run-ownership.ts

@@ -0,0 +1,53 @@
+import type { RunSnapshot, StageSnapshot } from "./store-types.js";
+
+/** Child run selected by a boundary's status-authoritative ownership metadata. */
+export function authoritativeWorkflowChildRunId(
+  stage: StageSnapshot | undefined,
+): string | undefined {
+  if (stage === undefined || stage.status === "failed" || stage.status === "skipped") {
+    return undefined;
+  }
+  if (stage.status === "completed") {
+    return stage.workflowChild?.runId ?? stage.workflowChildRun?.runId;
+  }
+  return stage.workflowChildRun?.runId;
+}
+
+/**
+ * Resolve a run's top-level owner through complete reciprocal parent-boundary
+ * links. Omitted root ids are compatible unknown metadata; present root ids
+ * must agree with the reached top-level run.
+ */
+export function reciprocalWorkflowRootRunId(
+  runById: ReadonlyMap<string, RunSnapshot>,
+  runId: string,
+): string | undefined {
+  const visited = new Set<string>();
+  const declaredRoots: string[] = [];
+  let current = runById.get(runId);
+
+  while (current !== undefined) {
+    const currentId = current.id;
+    if (visited.has(currentId)) return undefined;
+    visited.add(currentId);
+    if (current.rootRunId !== undefined) declaredRoots.push(current.rootRunId);
+
+    const parentRunId = current.parentRunId;
+    const parentStageId = current.parentStageId;
+    if ((parentRunId === undefined) !== (parentStageId === undefined)) return undefined;
+    if (parentRunId === undefined || parentStageId === undefined) {
+      return declaredRoots.every((declared) => declared === currentId)
+        ? currentId
+        : undefined;
+    }
+
+    const parent = runById.get(parentRunId);
+    const boundary = parent?.stages.find((stage) => stage.id === parentStageId);
+    if (parent === undefined || authoritativeWorkflowChildRunId(boundary) !== currentId) {
+      return undefined;
+    }
+    current = parent;
+  }
+
+  return undefined;
+}

package/dist/builtin/workflows/src/tui/graph-view-input.ts

@@ -1,4 +1,3 @@
-import { expandedStageTarget } from "../shared/expanded-workflow-graph.js";
 import {
   GRAPH_SCROLL_STEP_COLS,
   GRAPH_SCROLL_STEP_ROWS,
@@ -279,13 +278,8 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
 
   private _attachFocusedStage(): boolean {
     if (!this.onStageAttach) return false;
-    const node = this.cachedLayout[this.focusedIndex];
-    const run = this._getCurrentRun();
-    if (!node || !run) return false;
-    const target = expandedStageTarget(this.expandedGraph, node.stage.id) ?? {
-      runId: run.id,
-      stageId: node.stage.id,
-    };
+    const target = this._focusedStageChatTarget();
+    if (!target) return false;
     this.onStageAttach(target.runId, target.stageId);
     return true;
   }

package/dist/builtin/workflows/src/tui/graph-view-render-helpers.ts

@@ -6,7 +6,7 @@ import {
   OVERLAY_LINE_COUNT,
   OVERLAY_VERTICAL_MARGIN_ROWS,
 } from "./graph-view-constants.js";
-import { WORKFLOW_STATUS_KEY } from "./workflow-status.js";
+import { OVERLAY_HIDDEN_STATUS_KEYS, WORKFLOW_STATUS_KEY } from "./workflow-status.js";
 import { GraphViewState } from "./graph-view-state.js";
 import { renderOutlinePill } from "./header.js";
 import { NODE_H, NODE_W } from "./layout.js";
@@ -85,7 +85,8 @@ export abstract class GraphViewRenderHelpers extends GraphViewState {
       .filter(([key, value]) => (
         value.trim().length > 0 &&
         key !== WORKFLOW_STATUS_KEY &&
-        !key.startsWith(`${WORKFLOW_STATUS_KEY}:`)
+        !key.startsWith(`${WORKFLOW_STATUS_KEY}:`) &&
+        !OVERLAY_HIDDEN_STATUS_KEYS.has(key)
       ))
       .sort(([a], [b]) => a.localeCompare(b));
     if (entries.length === 0) return null;
@@ -114,9 +115,15 @@ export abstract class GraphViewRenderHelpers extends GraphViewState {
     const rightEdgePad = 2;
     const hintsBudget = Math.max(0, width - leftEdgePad - pillW - rightEdgePad);
     const fullHierarchyHint = "ctrl+x return to main chat";
-    const hintKeys = hintsBudget >= visibleWidth(fullHierarchyHint)
-      ? HINT_KEYS
+    const availableHintKeys = this._focusedStageChatTarget() === undefined
+      ? HINT_KEYS.filter(({ key }) => key !== "↵")
+      : HINT_KEYS;
+    const availableCompactHintKeys = this._focusedStageChatTarget() === undefined
+      ? COMPACT_HINT_KEYS.filter(({ key }) => key !== "↵")
       : COMPACT_HINT_KEYS;
+    const hintKeys = hintsBudget >= visibleWidth(fullHierarchyHint)
+      ? availableHintKeys
+      : availableCompactHintKeys;
     const statusText = this._externalStatusText();
     const statusSegment = statusText ? [`${accent}${statusText}${RESET}${chromeBg}`] : [];
     const hintSegments = hintKeys.map(

package/dist/builtin/workflows/src/tui/graph-view-render.ts

@@ -139,6 +139,7 @@ export abstract class GraphViewRenderer extends GraphViewGraphRenderer {
     const switcherLines = renderSwitcher(this._displayStages(run), this.switcherState, {
       width: switcherWidth,
       theme: this.graphTheme,
+      canOpenStageChat: (stage) => this._stageChatTarget(stage) !== undefined,
     });
     const insertAt = Math.max(bodyStart, bodyStart + Math.min(2, Math.floor((bodyTarget - switcherLines.length) / 3)));
     const switcherLeft = Math.max(2, Math.floor((frameWidth - switcherWidth) / 2));