@bastani/atomic 0.8.28-alpha.2 → 0.8.28-alpha.3

package/dist/builtin/workflows/src/shared/authoring-contract.d.ts

@@ -6,7 +6,7 @@
  * modules here. Public custom-TUI types are type-only imports from the same
  * extension-compatible surfaces used by Atomic extension UI.
  */
-import type { KeybindingsManager, Theme } from "@bastani/atomic";
+import type { BashCommandPolicy, KeybindingsManager, Theme } from "@bastani/atomic";
 import type { Component, OverlayHandle, OverlayOptions, TUI } from "@earendil-works/pi-tui";
 import type { Static, TOptional, TSchema } from "typebox";
 export type { Static, TSchema };
@@ -31,10 +31,16 @@ export type WorkflowOutputMode = "inline" | "file-only";
 export type WorkflowContextMode = "fresh" | "fork";
 export type WorkflowThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
 export type WorkflowExecutionMode = "interactive" | "non_interactive";
-export type RunStatus = "pending" | "running" | "paused" | "completed" | "failed" | "killed";
+export type WorkflowExitStatus = "completed" | "skipped" | "cancelled" | "blocked";
+export type RunStatus = "pending" | "running" | "paused" | WorkflowExitStatus | "failed" | "killed";
 export type WorkflowDetailsMode = "named" | "single" | "parallel" | "chain" | "inspection" | "control";
-export type WorkflowDetailsStatus = "accepted" | "running" | "completed" | "failed" | "killed" | "noop";
+export type WorkflowDetailsStatus = "accepted" | "running" | WorkflowExitStatus | "failed" | "killed" | "noop";
 export type WorkflowAction = "list" | "get" | "inputs" | "run" | "status" | "interrupt" | "resume";
+export interface WorkflowExitOptions<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> {
+    readonly status?: WorkflowExitStatus;
+    readonly reason?: string;
+    readonly outputs?: Partial<TOutputs>;
+}
 export interface WorkflowModelFallbackFields {
     /** Ordered model IDs to try after `model` fails; entries may use `:off|minimal|low|medium|high|xhigh` reasoning suffixes. */
     readonly fallbackModels?: readonly string[];
@@ -112,6 +118,7 @@ export interface StageOptions extends WorkflowModelFallbackFields {
     readonly noTools?: "all" | "builtin";
     readonly excludedTools?: readonly string[];
     readonly customTools?: readonly WorkflowCustomToolDefinition[];
+    readonly bashPolicy?: BashCommandPolicy;
     readonly cwd?: string;
     readonly agentDir?: string;
     readonly scopedModels?: readonly WorkflowScopedModel[];
@@ -332,12 +339,22 @@ export interface WorkflowRunChildOptions<TInputs extends WorkflowInputValues = W
     readonly inputs?: TInputs;
     readonly stageName?: string;
 }
-export interface WorkflowChildResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> extends WorkflowSerializableObject {
+export interface WorkflowCompletedChildResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> extends WorkflowSerializableObject {
     readonly workflow: string;
     readonly runId: string;
     readonly status: "completed";
+    readonly exited: false;
     readonly outputs: TOutputs;
 }
+export interface WorkflowExitedChildResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> extends WorkflowSerializableObject {
+    readonly workflow: string;
+    readonly runId: string;
+    readonly status: WorkflowExitStatus;
+    readonly exited: true;
+    readonly outputs: Partial<TOutputs>;
+    readonly exitReason?: string;
+}
+export type WorkflowChildResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> = WorkflowCompletedChildResult<TOutputs> | WorkflowExitedChildResult<TOutputs>;
 export type WorkflowCustomUiComponent = Component & {
     dispose?(): void;
 };
@@ -379,9 +396,10 @@ export interface WorkflowUIAdapter {
     editor(initial?: string): Promise<string>;
     custom?<T>(factory: WorkflowCustomUiFactory<T>, options?: WorkflowCustomUiOptions): Promise<T>;
 }
-export interface WorkflowRunContext<TInputs extends WorkflowInputValues = WorkflowInputValues, TDefinitionBrand extends object = {}> {
+export interface WorkflowRunContext<TInputs extends WorkflowInputValues = WorkflowInputValues, TDefinitionBrand extends object = {}, TOutputs extends WorkflowOutputValues = WorkflowOutputValues> {
     readonly inputs: Readonly<TInputs>;
     readonly cwd?: string;
+    exit(options?: WorkflowExitOptions<TOutputs>): never;
     stage(name: string, options?: StageOptions): StageContext;
     task(name: string, options: WorkflowTaskOptions): Promise<WorkflowTaskResult>;
     chain(steps: readonly WorkflowTaskStep[], options?: WorkflowChainOptions): Promise<WorkflowTaskResult[]>;
@@ -389,7 +407,7 @@ export interface WorkflowRunContext<TInputs extends WorkflowInputValues = Workfl
     workflow<TChildInputs extends WorkflowInputValues, TChildOutputs extends WorkflowOutputValues>(definition: WorkflowDefinition<TChildInputs, TChildOutputs> & TDefinitionBrand, options?: WorkflowRunChildOptions<TChildInputs>): Promise<WorkflowChildResult<TChildOutputs>>;
     readonly ui: WorkflowUIContext;
 }
-export type WorkflowRunFn<TInputs extends WorkflowInputValues = WorkflowInputValues, TOutputs extends WorkflowOutputValues = WorkflowOutputValues, TDefinitionBrand extends object = {}> = (ctx: WorkflowRunContext<TInputs, TDefinitionBrand>) => Promise<TOutputs> | TOutputs;
+export type WorkflowRunFn<TInputs extends WorkflowInputValues = WorkflowInputValues, TOutputs extends WorkflowOutputValues = WorkflowOutputValues, TDefinitionBrand extends object = {}> = (ctx: WorkflowRunContext<TInputs, TDefinitionBrand, TOutputs>) => Promise<TOutputs> | TOutputs;
 export interface WorkflowRuntimeConfig {
     readonly maxDepth: number;
     readonly defaultConcurrency: number;
@@ -414,7 +432,7 @@ export interface WorkflowDefinition<TInputs extends WorkflowInputValues = Workfl
     readonly inputs: WorkflowInputSchemaMap;
     readonly outputs?: WorkflowOutputSchemaMap;
     readonly inputBindings?: WorkflowInputBindings;
-    run(ctx: WorkflowRunContext<TInputs, TDefinitionBrand>): Promise<TOutputs> | TOutputs;
+    run(ctx: WorkflowRunContext<TInputs, TDefinitionBrand, TOutputs>): Promise<TOutputs> | TOutputs;
 }
 type DeclaredResolvedEntry<K extends string, S extends TSchema> = S extends TOptional<TSchema> ? {
     readonly [P in K]?: Static<S>;
@@ -437,7 +455,7 @@ export interface WorkflowBuilder<TInputs extends WorkflowInputValues = {}, TOutp
     input<K extends string, S extends TSchema>(key: K, schema: S): WorkflowBuilder<Simplify<TInputs & DeclaredResolvedEntry<K, S>>, TOutputs, Simplify<TRunInputs & DeclaredProvidedEntry<K, S>>, TDefinitionBrand, WorkflowDefinition<Simplify<TInputs & DeclaredResolvedEntry<K, S>>, TOutputs, Simplify<TRunInputs & DeclaredProvidedEntry<K, S>>, TDefinitionBrand> & TDefinitionBrand>;
     output<K extends string, S extends TSchema>(key: K, schema: S): WorkflowBuilder<TInputs, Simplify<TOutputs & (DeclaredResolvedEntry<K, S> & WorkflowOutputValues)>, TRunInputs, TDefinitionBrand, WorkflowDefinition<TInputs, Simplify<TOutputs & (DeclaredResolvedEntry<K, S> & WorkflowOutputValues)>, TRunInputs, TDefinitionBrand> & TDefinitionBrand>;
     worktreeFromInputs(binding: WorkflowWorktreeInputBinding): WorkflowBuilder<TInputs, TOutputs, TRunInputs, TDefinitionBrand, TCompiledDefinition>;
-    run<TActualOutputs extends TOutputs>(fn: (ctx: WorkflowRunContext<TInputs, TDefinitionBrand>) => Promise<NoExtraOutputs<TOutputs, TActualOutputs>> | NoExtraOutputs<TOutputs, TActualOutputs>): CompletedWorkflowBuilder<TInputs, TOutputs, TRunInputs, TDefinitionBrand, TCompiledDefinition>;
+    run<TActualOutputs extends TOutputs>(fn: (ctx: WorkflowRunContext<TInputs, TDefinitionBrand, TOutputs>) => Promise<NoExtraOutputs<TOutputs, TActualOutputs>> | NoExtraOutputs<TOutputs, TActualOutputs>): CompletedWorkflowBuilder<TInputs, TOutputs, TRunInputs, TDefinitionBrand, TCompiledDefinition>;
 }
 export interface CompletedWorkflowBuilder<TInputs extends WorkflowInputValues = {}, TOutputs extends WorkflowOutputValues = {}, TRunInputs extends WorkflowInputValues = TInputs, TDefinitionBrand extends object = {}, TCompiledDefinition extends WorkflowDefinition<TInputs, TOutputs, TRunInputs, TDefinitionBrand> = WorkflowDefinition<TInputs, TOutputs, TRunInputs, TDefinitionBrand>> extends WorkflowBuilder<TInputs, TOutputs, TRunInputs, TDefinitionBrand, TCompiledDefinition> {
     description(text: string): CompletedWorkflowBuilder<TInputs, TOutputs, TRunInputs, TDefinitionBrand, TCompiledDefinition>;
@@ -501,7 +519,7 @@ export interface RunOpts {
     readonly onRunStart?: (snapshot: RunSnapshot) => void;
     readonly onStageStart?: (runId: string, snapshot: StageSnapshot) => void;
     readonly onStageEnd?: (runId: string, snapshot: StageSnapshot) => void;
-    readonly onRunEnd?: (runId: string, status: RunStatus, result?: WorkflowOutputValues, error?: string) => void;
+    readonly onRunEnd?: (runId: string, status: RunStatus, result?: WorkflowOutputValues, error?: string, exitReason?: string) => void;
 }
 export interface WorkflowProgressSummary extends WorkflowSerializableObject {
     readonly completed?: number;
@@ -530,6 +548,9 @@ export interface WorkflowDetails extends WorkflowSerializableObject {
     readonly intercom?: WorkflowIntercomSummary;
     readonly warnings?: readonly string[];
     readonly error?: string;
+    /** True when the run reached its terminal status through ctx.exit(). */
+    readonly exited?: boolean;
+    readonly exitReason?: string;
 }
 export type StageStatus = RunStatus | "skipped" | "awaiting_input" | "blocked";
 export interface StageSnapshot extends WorkflowSerializableObject {
@@ -542,8 +563,11 @@ export interface StageSnapshot extends WorkflowSerializableObject {
 export interface RunResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> extends WorkflowSerializableObject {
     readonly runId: string;
     readonly status: RunStatus;
-    readonly result?: TOutputs;
+    readonly result?: Partial<TOutputs>;
     readonly error?: string;
+    /** True when the run reached its terminal status through ctx.exit(). */
+    readonly exited?: boolean;
+    readonly exitReason?: string;
     readonly stages: readonly StageSnapshot[];
 }
 export type ResolvedInputs<TInputs extends WorkflowInputValues = WorkflowInputValues> = Readonly<TInputs> & WorkflowSerializableObject;

package/dist/builtin/workflows/src/shared/expanded-workflow-graph.ts

@@ -29,12 +29,20 @@ function virtualStageId(runId: string, stageId: string, isRootRun: boolean): str
   return isRootRun ? stageId : `${runId}:${stageId}`;
 }
 
+function isTerminalNonCompletedBoundary(stage: StageSnapshot): boolean {
+  return stage.status === "failed" || stage.status === "skipped";
+}
+
 function childRunIdFor(stage: StageSnapshot): string | undefined {
-  return stage.workflowChildRun?.runId ?? stage.workflowChild?.runId;
+  if (isTerminalNonCompletedBoundary(stage)) return undefined;
+  if (stage.status === "completed") return stage.workflowChild?.runId ?? stage.workflowChildRun?.runId;
+  return stage.workflowChildRun?.runId;
 }
 
 function childAliasFor(stage: StageSnapshot): string | undefined {
-  return stage.workflowChildRun?.alias ?? stage.workflowChild?.alias;
+  if (isTerminalNonCompletedBoundary(stage)) return undefined;
+  if (stage.status === "completed") return stage.workflowChild?.alias ?? stage.workflowChildRun?.alias;
+  return stage.workflowChildRun?.alias;
 }
 
 function localTerminalStageIds(stages: readonly StageSnapshot[]): readonly string[] {

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

@@ -9,14 +9,14 @@
 import type { Store } from "./store.js";
 import type {
   RunSnapshot,
+  RunStatus,
   StageSnapshot,
   StageStatus,
-  WorkflowChildReplaySnapshot,
   WorkflowFailureCode,
   WorkflowFailureDisposition,
   WorkflowFailureKind,
 } from "./store-types.js";
-import type { WorkflowInputValues, WorkflowOutputValues } from "./types.js";
+import type { WorkflowExitStatus, WorkflowInputValues, WorkflowOutputValues } from "./types.js";
 import { workflowSerializableObjectSchema } from "./serializable.js";
 import { Value } from "typebox/value";
 import {
@@ -429,11 +429,12 @@ function serializableObjectOrEmpty(value: unknown): WorkflowOutputValues {
   return serializableObject(value) ?? {};
 }
 
-function isWorkflowChildReplayStatus(status: unknown): status is WorkflowChildReplaySnapshot["status"] {
-  return status === "completed";
+function isWorkflowChildReplayStatus(status: unknown): status is WorkflowExitStatus {
+  return status === "completed" || status === "skipped" || status === "cancelled" || status === "blocked";
 }
 
 function workflowChildMetadata(payload: Record<string, unknown>): Pick<StageSnapshot, "workflowChild"> {
+  if (payload["status"] !== "completed") return {};
   const workflowChild = payload["workflowChild"];
   if (!isRecord(workflowChild)) return {};
   const alias = workflowChild["alias"];
@@ -441,6 +442,8 @@ function workflowChildMetadata(payload: Record<string, unknown>): Pick<StageSnap
   const childRunId = workflowChild["runId"];
   const status = workflowChild["status"];
   const outputs = workflowChild["outputs"];
+  const exited = workflowChild["exited"];
+  const exitReason = workflowChild["exitReason"];
   if (
     typeof alias !== "string" ||
     typeof workflow !== "string" ||
@@ -470,7 +473,9 @@ function workflowChildMetadata(payload: Record<string, unknown>): Pick<StageSnap
       workflow,
       runId: childRunId,
       status,
+      ...(typeof exited === "boolean" ? { exited } : status !== "completed" || typeof exitReason === "string" ? { exited: true } : {}),
       outputs: clonedOutputs,
+      ...(typeof exitReason === "string" ? { exitReason } : {}),
     },
   };
 }
@@ -567,7 +572,12 @@ function restoreTerminalRuns(entries: readonly SessionEntry[], store: Store): vo
 
     const runMeta = findRunStartMetadata(entries, runId);
     const stages = _buildStageSnapshots(entries, runId);
-    if (status === "completed" && stages.some((stage) => stage.status !== "completed")) continue;
+    const exited = end["exited"];
+    const exitReason = end["exitReason"];
+    const resumable = end["resumable"];
+    const restoredAuthorExit = isWorkflowExitTerminalStatus(status) &&
+      (exited === true || status !== "completed" || typeof exitReason === "string" || resumable === false);
+    if (status === "completed" && !restoredAuthorExit && stages.some((stage) => stage.status !== "completed")) continue;
     store.recordRunStart({
       id: runId,
       name: start.name,
@@ -583,6 +593,7 @@ function restoreTerminalRuns(entries: readonly SessionEntry[], store: Store): vo
     });
 
     const error = end["error"];
+    const result = serializableObject(end["result"]);
     const failureKind = end["failureKind"];
     const failureCode = end["failureCode"];
     const failureRecoverability = end["failureRecoverability"];
@@ -590,11 +601,10 @@ function restoreTerminalRuns(entries: readonly SessionEntry[], store: Store): vo
     const retryAfterMs = numericRetryAfterMs(end["retryAfterMs"]);
     const failureMessage = end["failureMessage"];
     const failedStageId = end["failedStageId"];
-    const resumable = end["resumable"];
     store.recordRunEnd(
       runId,
       status,
-      undefined,
+      result,
       typeof error === "string" ? error : undefined,
       {
         ...(typeof failureKind === "string" && isWorkflowFailureKind(failureKind) ? { failureKind } : {}),
@@ -604,15 +614,24 @@ function restoreTerminalRuns(entries: readonly SessionEntry[], store: Store): vo
         ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
         ...(typeof failureMessage === "string" ? { failureMessage } : {}),
         ...(typeof failedStageId === "string" ? { failedStageId } : {}),
-        ...(typeof resumable === "boolean" ? { resumable } : {}),
+        ...(typeof resumable === "boolean" ? { resumable } : isWorkflowExitTerminalStatus(status) && restoredAuthorExit ? { resumable: false } : {}),
+        ...(restoredAuthorExit && isWorkflowExitTerminalStatus(status) ? { exited: true } : {}),
+        ...(typeof exitReason === "string" ? { exitReason } : {}),
       },
     );
   }
 }
 
-function restoreTerminalRunStatus(status: unknown): "completed" | "failed" | "killed" | undefined {
+function isWorkflowExitTerminalStatus(status: RunStatus): status is WorkflowExitStatus {
+  return status === "completed" || status === "skipped" || status === "cancelled" || status === "blocked";
+}
+
+function restoreTerminalRunStatus(status: unknown): RunStatus | undefined {
   switch (status) {
     case "completed":
+    case "skipped":
+    case "cancelled":
+    case "blocked":
     case "failed":
     case "killed":
       return status;

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

@@ -6,7 +6,7 @@
  * through gracefully when the runtime doesn't support the method.
  */
 
-import type { WorkflowInputValues, WorkflowOutputValues } from "./types.js";
+import type { WorkflowExitStatus, WorkflowInputValues, WorkflowOutputValues } from "./types.js";
 import type {
   WorkflowFailureCode,
   WorkflowFailureDisposition,
@@ -69,8 +69,10 @@ export interface WorkflowChildReplayPayload {
   readonly alias: string;
   readonly workflow: string;
   readonly runId: string;
-  readonly status: "completed";
+  readonly status: WorkflowExitStatus;
+  readonly exited?: boolean;
   readonly outputs: WorkflowOutputValues;
+  readonly exitReason?: string;
 }
 
 export interface StageEndPayload {
@@ -98,6 +100,8 @@ export interface RunEndPayload {
   readonly status: string;
   readonly result?: WorkflowOutputValues;
   readonly error?: string;
+  readonly exited?: boolean;
+  readonly exitReason?: string;
   readonly failureKind?: string;
   readonly failureCode?: string;
   readonly failureRecoverability?: string;
@@ -201,7 +205,7 @@ export function appendStageEnd(
     ...(payload.replayKey !== undefined ? { replayKey: payload.replayKey } : {}),
     ...(payload.replayedFromStageId !== undefined ? { replayedFromStageId: payload.replayedFromStageId } : {}),
     ...(payload.replayed !== undefined ? { replayed: payload.replayed } : {}),
-    ...(payload.workflowChild !== undefined ? { workflowChild: payload.workflowChild } : {}),
+    ...(payload.status === "completed" && payload.workflowChild !== undefined ? { workflowChild: payload.workflowChild } : {}),
   });
   if (opts?.emitMessage === true && payload.summary && typeof api.appendCustomMessageEntry === "function") {
     api.appendCustomMessageEntry(
@@ -236,6 +240,8 @@ export function appendRunEnd(api: PersistenceAPI, payload: RunEndPayload): void
     status: terminalPayload.status,
     ...(terminalPayload.result !== undefined ? { result: terminalPayload.result } : {}),
     ...(terminalPayload.error !== undefined ? { error: terminalPayload.error } : {}),
+    ...(terminalPayload.exited !== undefined ? { exited: terminalPayload.exited } : {}),
+    ...(terminalPayload.exitReason !== undefined ? { exitReason: terminalPayload.exitReason } : {}),
     ...(terminalPayload.failureKind !== undefined ? { failureKind: terminalPayload.failureKind } : {}),
     ...(terminalPayload.failureCode !== undefined ? { failureCode: terminalPayload.failureCode } : {}),
     ...(terminalPayload.failureRecoverability !== undefined ? { failureRecoverability: terminalPayload.failureRecoverability } : {}),

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

@@ -3,9 +3,9 @@
  * cross-ref: spec §5.5
  */
 
-import type { WorkflowInputValues, WorkflowOutputValues } from "./types.js";
+import type { WorkflowExitStatus, WorkflowInputValues, WorkflowOutputValues } from "./types.js";
 
-export type RunStatus = "pending" | "running" | "paused" | "completed" | "failed" | "killed";
+export type RunStatus = "pending" | "running" | "paused" | WorkflowExitStatus | "failed" | "killed";
 export type StageStatus =
   | "pending"
   | "running"
@@ -125,8 +125,11 @@ export interface WorkflowChildReplaySnapshot {
   readonly alias: string;
   readonly workflow: string;
   readonly runId: string;
-  readonly status: "completed";
+  readonly status: WorkflowExitStatus;
+  /** True when the child reached this terminal status through ctx.exit(). */
+  readonly exited?: boolean;
   readonly outputs: WorkflowOutputValues;
+  readonly exitReason?: string;
 }
 
 export interface StageSnapshot {
@@ -243,6 +246,10 @@ export interface RunSnapshot {
   resumedAt?: number;
   result?: WorkflowOutputValues;
   error?: string;
+  /** True when the run reached its terminal status through ctx.exit(). */
+  exited?: boolean;
+  /** Optional author-supplied reason from ctx.exit(). */
+  exitReason?: string;
   /** Structured workflow failure category for failed runs. */
   failureKind?: WorkflowFailureKind;
   /** Specific additive workflow failure code within `failureKind`. */

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

@@ -25,8 +25,16 @@ import type {
 import { accumulatePausedDurationMs, elapsedRunMs } from "./timing.js";
 import { isTopLevelWorkflowRun } from "./run-visibility.js";
 
-/** Statuses that represent a terminal run state — cannot be overwritten. */
-const TERMINAL_STATUSES: ReadonlySet<RunStatus> = new Set(["completed", "failed", "killed"]);
+/**
+ * Statuses that represent a terminal run state — cannot be overwritten.
+ *
+ * Note on `"blocked"`: here it is an author-selected `ctx.exit({ status: "blocked" })`
+ * outcome — terminal and non-resumable. This is deliberately distinct from retry-blocking,
+ * which does NOT use this run status: `recordRunBlocked()` keeps `run.status = "running"`
+ * and records the block via `blockedAt` / `failureDisposition: "active_blocked"` (resumable).
+ * The two never collide despite the shared word.
+ */
+const TERMINAL_STATUSES: ReadonlySet<RunStatus> = new Set(["completed", "failed", "killed", "skipped", "cancelled", "blocked"]);
 
 function isTerminalStageStatus(status: StageStatus): boolean {
   return status === "completed" || status === "failed" || status === "skipped";
@@ -53,6 +61,8 @@ export interface RunEndMetadata {
   readonly failedStageId?: string;
   readonly resumable?: boolean;
   readonly retryAfterMs?: number;
+  readonly exited?: boolean;
+  readonly exitReason?: string;
 }
 
 export interface RunBlockedMetadata extends RunEndMetadata {
@@ -73,6 +83,8 @@ function clearRunFailureMetadata(run: RunSnapshot): void {
   delete run.resumable;
   delete run.retryAfterMs;
   delete run.blockedAt;
+  delete run.exited;
+  delete run.exitReason;
 }
 
 function clearStaleBlockedRunMetadata(run: RunSnapshot, metadata: RunEndMetadata | undefined): void {
@@ -84,6 +96,8 @@ function clearStaleBlockedRunMetadata(run: RunSnapshot, metadata: RunEndMetadata
   if (metadata?.failedStageId === undefined) delete run.failedStageId;
   if (metadata?.resumable === undefined) delete run.resumable;
   if (metadata?.retryAfterMs === undefined) delete run.retryAfterMs;
+  if (metadata?.exited === undefined) delete run.exited;
+  if (metadata?.exitReason === undefined) delete run.exitReason;
 }
 
 function applyRunEndMetadata(run: RunSnapshot, metadata: RunEndMetadata): void {
@@ -95,6 +109,8 @@ function applyRunEndMetadata(run: RunSnapshot, metadata: RunEndMetadata): void {
   if (metadata.failureMessage !== undefined) run.failureMessage = metadata.failureMessage;
   if (metadata.failedStageId !== undefined) run.failedStageId = metadata.failedStageId;
   if (metadata.resumable !== undefined) run.resumable = metadata.resumable;
+  if (metadata.exited !== undefined) run.exited = metadata.exited;
+  if (metadata.exitReason !== undefined) run.exitReason = metadata.exitReason;
 }
 
 export type StagePromptAnswerSource = "workflow_ui" | "workflow_tool";
@@ -138,8 +154,8 @@ export interface Store {
   /**
    * Records the end of a run.
    * Returns `true` if state changed, `false` if the run was not found or
-   * already in a terminal state (completed | failed | killed).
-   * `result` is only applied for status "completed".
+   * already in a terminal state (completed | failed | killed | skipped | cancelled | blocked).
+   * `result` is applied for intentional success/exit statuses (completed | skipped | cancelled | blocked).
    * `error` is only applied for status "failed" | "killed".
    */
   recordRunEnd(
@@ -531,8 +547,13 @@ export function createStore(): Store {
       if (stage.promptAnswerState !== undefined) existing.promptAnswerState = stage.promptAnswerState;
       if (stage.replayedFromStageId !== undefined) existing.replayedFromStageId = stage.replayedFromStageId;
       if (stage.replayed !== undefined) existing.replayed = stage.replayed;
-      if (stage.workflowChildRun !== undefined) existing.workflowChildRun = { ...stage.workflowChildRun };
-      if (stage.workflowChild !== undefined) existing.workflowChild = structuredClone(stage.workflowChild);
+      if (stage.status === "completed") {
+        if (stage.workflowChildRun !== undefined) existing.workflowChildRun = { ...stage.workflowChildRun };
+        if (stage.workflowChild !== undefined) existing.workflowChild = structuredClone(stage.workflowChild);
+      } else {
+        delete existing.workflowChildRun;
+        delete existing.workflowChild;
+      }
       delete existing.awaitingInputSince;
       delete existing.inputRequest;
       rejectStagePrompt(runId, existing, `atomic-workflows: stage ${stage.id} ended before prompt resolved`);
@@ -564,11 +585,12 @@ export function createStore(): Store {
       run.durationMs = elapsedRunMs(run, run.endedAt);
       const wasBlocked = run.blockedAt !== undefined || run.failureDisposition === "active_blocked";
       delete run.blockedAt;
-      if (status === "completed") {
+      if (status === "completed" || status === "skipped" || status === "cancelled" || status === "blocked") {
         if (result !== undefined) {
           run.result = result;
         }
         clearRunFailureMetadata(run);
+        if (metadata !== undefined) applyRunEndMetadata(run, metadata);
       } else {
         if (wasBlocked && error === undefined) delete run.error;
         if ((status === "failed" || status === "killed") && error !== undefined) {

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

@@ -47,6 +47,8 @@ export type WorkflowSerializableValue = AuthoringContract.WorkflowSerializableVa
 export type WorkflowInputValues = AuthoringContract.WorkflowInputValues;
 export type WorkflowOutputValues = AuthoringContract.WorkflowOutputValues;
 export type WorkflowRunOutput = AuthoringContract.WorkflowRunOutput;
+export type WorkflowExitStatus = AuthoringContract.WorkflowExitStatus;
+export type WorkflowExitOptions<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> = AuthoringContract.WorkflowExitOptions<TOutputs>;
 
 // ---------------------------------------------------------------------------
 // Workflow input / output schemas
@@ -98,14 +100,9 @@ export interface WorkflowRunChildOptions<TInputs extends WorkflowInputValues = W
   readonly stageName?: string;
 }
 
-export interface WorkflowChildResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues>
-  extends WorkflowSerializableObject {
-  readonly workflow: string;
-  readonly runId: string;
-  readonly status: "completed";
-  /** Child outputs, typed from the child workflow's declared `.output(...)` contract. */
-  readonly outputs: TOutputs;
-}
+export type WorkflowCompletedChildResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> = AuthoringContract.WorkflowCompletedChildResult<TOutputs>;
+export type WorkflowExitedChildResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> = AuthoringContract.WorkflowExitedChildResult<TOutputs>;
+export type WorkflowChildResult<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> = AuthoringContract.WorkflowChildResult<TOutputs>;
 
 // ---------------------------------------------------------------------------
 // HIL (human-in-the-loop) primitives available inside run functions
@@ -329,11 +326,16 @@ export interface StageContext {
 // Workflow run context (top-level ctx passed to the run function)
 // ---------------------------------------------------------------------------
 
-export interface WorkflowRunContext<TInputs extends WorkflowInputValues = WorkflowInputValues> {
+export interface WorkflowRunContext<
+  TInputs extends WorkflowInputValues = WorkflowInputValues,
+  TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
+> {
   /** Typed inputs provided by the caller, validated against the input schema. */
   readonly inputs: TInputs;
   /** Invocation working directory for workflow-owned artifacts. Defaults to the host process cwd when omitted. */
   readonly cwd?: string;
+  /** Intentionally end this workflow run from any call depth. */
+  exit(options?: WorkflowExitOptions<TOutputs>): never;
   /**
    * Create and register a named stage synchronously. Stage work starts when
    * a stage method such as prompt() or complete() is awaited; the executor
@@ -383,7 +385,7 @@ export type WorkflowRuntimeConfig = AuthoringContract.WorkflowRuntimeConfig;
 export type WorkflowRunFn<
   TInputs extends WorkflowInputValues = WorkflowInputValues,
   TOutputs extends WorkflowOutputValues = WorkflowOutputValues,
-> = (ctx: WorkflowRunContext<TInputs>) => ReturnType<AuthoringContract.WorkflowRunFn<TInputs, TOutputs>>;
+> = (ctx: WorkflowRunContext<TInputs, TOutputs>) => ReturnType<AuthoringContract.WorkflowRunFn<TInputs, TOutputs>>;
 
 // ---------------------------------------------------------------------------
 // Compiled workflow definition

package/dist/builtin/workflows/src/tui/run-detail.ts

@@ -185,6 +185,9 @@ function summaryRows(detail: RunDetail, now: number): Array<[string, string | un
   } else {
     rows.push(["elapsed", fmtDuration(duration)]);
   }
+  if (detail.exitReason) {
+    rows.push(["reason", detail.exitReason]);
+  }
   if (detail.error) {
     rows.push(["error", detail.error.split("\n")[0] ?? ""]);
   }
@@ -303,6 +306,12 @@ function stateBadges(detail: RunDetail, theme: GraphTheme): FlatBandBadge[] {
       return [{ text: "❚❚ paused", fg: theme.warning }];
     case "completed":
       return [{ text: "✓ completed", fg: theme.success }];
+    case "skipped":
+      return [{ text: "⊘ skipped", fg: theme.dim }];
+    case "cancelled":
+      return [{ text: "⊘ cancelled", fg: theme.dim }];
+    case "blocked":
+      return [{ text: "↑ blocked", fg: theme.dim }];
     case "failed":
       return [{ text: "✗ failed", fg: theme.error }];
     case "killed":
@@ -318,6 +327,9 @@ function stateLabel(detail: RunDetail): string {
     case "running": return "● running";
     case "paused": return "❚❚ paused";
     case "completed": return "✓ completed";
+    case "skipped": return "⊘ skipped";
+    case "cancelled": return "⊘ cancelled";
+    case "blocked": return "↑ blocked";
     case "failed": return "✗ failed";
     case "killed": return "⊘ killed";
     case "pending":

package/dist/builtin/workflows/src/tui/status-helpers.ts

@@ -30,6 +30,8 @@ export function statusColor(
       return theme.dim;
     case "skipped":
       return theme.dim;
+    case "cancelled":
+      return theme.dim;
     case "pending":
     default:
       return theme.dim;
@@ -47,6 +49,8 @@ export function statusIcon(status: StageStatus | RunStatus): string {
       return "↑";
     case "skipped":
       return "⊘";
+    case "cancelled":
+      return "⊘";
     case "running":
       return "●";
     case "paused":

package/dist/builtin/workflows/src/tui/status-list.ts

@@ -161,6 +161,9 @@ function runAccent(run: RunSnapshot, theme?: GraphTheme): string {
     case "completed": return theme.success;
     case "running":   return theme.warning;
     case "paused":    return theme.warning;
+    case "skipped":   return theme.dim;
+    case "cancelled": return theme.dim;
+    case "blocked":   return theme.dim;
     case "failed":    return theme.error;
     case "killed":    return theme.error;
     case "pending":
@@ -173,6 +176,9 @@ function runTrailing(run: RunSnapshot, theme?: GraphTheme): { text: string; fg?:
     case "completed": return { text: "✓ completed", fg: theme?.success };
     case "running":   return { text: "● running", fg: theme?.warning };
     case "paused":    return { text: "❚❚ paused", fg: theme?.warning };
+    case "skipped":   return { text: "⊘ skipped", fg: theme?.dim };
+    case "cancelled": return { text: "⊘ cancelled", fg: theme?.dim };
+    case "blocked":   return { text: "↑ blocked", fg: theme?.dim };
     case "failed":    return { text: "✗ failed", fg: theme?.error };
     case "killed":    return { text: "⊘ killed", fg: theme?.error };
     case "pending":
@@ -226,7 +232,8 @@ function runCardMeta(run: RunSnapshot, now: number): string {
     return parts.join(" · ");
   }
 
-  if (run.status === "completed") {
+  if (run.status === "completed" || run.status === "skipped" || run.status === "cancelled" || run.status === "blocked") {
+    if (run.exitReason !== undefined && run.exitReason.length > 0) parts.push(run.exitReason);
     if (!isChain && run.stages[0]) parts.push(run.stages[0].name);
     const dur = lastStageDuration(run, now);
     if (dur) parts.push(dur);
@@ -280,6 +287,9 @@ function stageCells(run: RunSnapshot): Array<{ status: StageStatus }> {
 function stageStatusFromRun(run: RunSnapshot): StageStatus {
   switch (run.status) {
     case "completed": return "completed";
+    case "skipped":   return "skipped";
+    case "cancelled": return "skipped";
+    case "blocked":   return "blocked";
     case "running":   return "running";
     case "paused":    return "paused";
     case "failed":    return "failed";
@@ -320,6 +330,7 @@ function countBuckets(runs: readonly RunSnapshot[]): Counts {
       else if (r.status === "completed") c.completed++;
       else c.failed++;
     } else if (r.status === "completed") c.completed++;
+    else if (r.status === "skipped" || r.status === "cancelled" || r.status === "blocked") c.completed++;
     else c.failed++;
   }
   return c;
@@ -372,6 +383,9 @@ function emptyStateLine(theme?: GraphTheme): string {
 function statusIconForRun(run: RunSnapshot): string {
   switch (run.status) {
     case "completed": return "✓";
+    case "skipped": return "⊘";
+    case "cancelled": return "⊘";
+    case "blocked": return "↑";
     case "running": return "●";
     case "paused": return "❚❚";
     case "failed": return "✗";

package/dist/builtin/workflows/src/tui/store-widget-installer.ts

@@ -171,7 +171,7 @@ export function installToolExecutionHooks(pi: LiveWidgetAPI, storeInstance: Stor
     readonly startedAt: number;
   }
 
-  const terminalRunStatuses = new Set(["completed", "failed", "killed"]);
+  const terminalRunStatuses = new Set(["completed", "failed", "killed", "skipped", "cancelled", "blocked"]);
   const terminalStageStatuses = new Set(["completed", "failed", "skipped"]);
   const activeToolCalls = new Map<string, ActiveToolCall>();