@bastani/atomic 0.9.2 → 0.9.3-alpha.2

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

@@ -55,6 +55,18 @@ export interface WorkflowModelFallbackFields {
 }
 
 export type WorkflowModelValue = string | object;
+// Standalone authoring contract mirror of shared/types.ts StageUserMessageContent,
+// whose runtime source of truth is derived from AgentSession["sendUserMessage"].
+export interface StageTextContent {
+  readonly type: "text";
+  readonly text: string;
+}
+export interface StageImageContent {
+  readonly type: "image";
+  readonly data: string;
+  readonly mimeType: string;
+}
+export type StageUserMessageContent = string | readonly (StageTextContent | StageImageContent)[];
 export type WorkflowStageResult<TSchemaDef extends TSchema | undefined = undefined> = [TSchemaDef] extends [TSchema]
   ? Static<TSchemaDef>
   : string;
@@ -223,6 +235,7 @@ export interface WorkflowPersistencePort {
 
 export interface StageSessionRuntime {
   prompt(text: string, options?: PromptOptions): Promise<string | void>;
+  sendUserMessage?(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void>;
   steer(text: string): Promise<void>;
   followUp(text: string): Promise<void>;
   subscribe(listener: (event: never) => void): () => void;
@@ -284,10 +297,17 @@ export interface StageAdapters {
   readonly complete?: CompleteAdapter;
 }
 
+export type StageUserMessageDelivery = "steer" | "followUp";
+
+export interface StageSendUserMessageOptions {
+  readonly deliverAs?: StageUserMessageDelivery;
+}
+
 export interface StageContext<TSchemaDef extends TSchema | undefined = undefined> {
   readonly name: string;
   prompt(text: string, options?: StagePromptOptions): Promise<WorkflowStageResult<TSchemaDef>>;
   complete(text: string, options?: CompleteStageOpts): Promise<string>;
+  sendUserMessage(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void>;
   steer(text: string): Promise<void>;
   followUp(text: string): Promise<void>;
   subscribe(listener: (event: never) => void): () => void;

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

@@ -57,6 +57,28 @@ export interface WorkflowRunContext<TInputs extends WorkflowInputValues = Workfl
     parallel(steps: readonly WorkflowTaskStep[], options?: WorkflowParallelOptions): Promise<WorkflowTaskResult[]>;
     workflow<TChildInputs extends WorkflowInputValues, TChildOutputs extends WorkflowOutputValues, TChildRunInputs extends WorkflowInputValues = TChildInputs>(definition: WorkflowDefinition<TChildInputs, TChildOutputs, TChildRunInputs> & TDefinitionBrand, ...args: WorkflowRunChildArgs<TChildRunInputs>): Promise<WorkflowChildResult<TChildOutputs>>;
     readonly ui: WorkflowUIContext;
+    /**
+     * Durable cached tool execution. Runs arbitrary TypeScript code and caches
+     * the result durably so completed side effects are not repeated on resume.
+     * Only `ctx.*` blocks (tool, ui, stage, task, chain, parallel, workflow)
+     * produce durable checkpoints.
+     *
+     * cross-ref: issue #1498 — DBOS-backed cross-session resumability.
+     */
+    tool: WorkflowToolPrimitive;
+}
+/**
+ * `ctx.tool` primitive signature. Runs an async function and caches the result.
+ */
+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 {
+    readonly retriesAllowed?: boolean;
+    readonly maxAttempts?: number;
+    readonly intervalMs?: number;
+    readonly backoffRate?: number;
 }
 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 {
@@ -140,7 +162,7 @@ export interface RunOpts {
     readonly parentRun?: WorkflowParentRunLink;
     readonly onRunStart?: (snapshot: RunSnapshot) => void;
     readonly onStageStart?: (runId: string, snapshot: StageSnapshot) => void;
-    readonly onStageEnd?: (runId: string, snapshot: StageSnapshot) => void;
+    readonly onStageEnd?: (runId: string, snapshot: StageSnapshot) => unknown;
     readonly onRunEnd?: (runId: string, status: RunStatus, result?: WorkflowOutputValues, error?: string, exitReason?: string) => void;
 }
 export interface WorkflowProgressSummary extends WorkflowSerializableObject {

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

@@ -104,6 +104,35 @@ export interface WorkflowRunContext<
     ...args: WorkflowRunChildArgs<TChildRunInputs>
   ): Promise<WorkflowChildResult<TChildOutputs>>;
   readonly ui: WorkflowUIContext;
+  /**
+   * Durable cached tool execution. Runs arbitrary TypeScript code and caches
+   * the result durably so completed side effects are not repeated on resume.
+   * Only `ctx.*` blocks (tool, ui, stage, task, chain, parallel, workflow)
+   * produce durable checkpoints.
+   *
+   * cross-ref: issue #1498 — DBOS-backed cross-session resumability.
+   */
+  tool: WorkflowToolPrimitive;
+}
+
+/**
+ * `ctx.tool` primitive signature. Runs an async function and caches the result.
+ */
+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 {
+  readonly retriesAllowed?: boolean;
+  readonly maxAttempts?: number;
+  readonly intervalMs?: number;
+  readonly backoffRate?: number;
 }
 
 export type WorkflowRunFn<
@@ -206,7 +235,7 @@ export interface RunOpts {
   readonly parentRun?: WorkflowParentRunLink;
   readonly onRunStart?: (snapshot: RunSnapshot) => void;
   readonly onStageStart?: (runId: string, snapshot: StageSnapshot) => void;
-  readonly onStageEnd?: (runId: string, snapshot: StageSnapshot) => void;
+  readonly onStageEnd?: (runId: string, snapshot: StageSnapshot) => unknown;
   readonly onRunEnd?: (runId: string, status: RunStatus, result?: WorkflowOutputValues, error?: string, exitReason?: string) => void;
 }
 

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

@@ -30,6 +30,10 @@ export interface RunEndMetadata {
   readonly exitReason?: string;
 }
 
+export interface RunPauseMetadata {
+  readonly resumable?: boolean;
+  readonly exitReason?: string;
+}
 export interface RunBlockedMetadata extends RunEndMetadata {
   readonly failureRecoverability: "recoverable";
   readonly failedStageId: string;
@@ -204,8 +208,8 @@ export interface Store {
   recordStageBlocked(runId: string, stageId: string, blockedBy: string): boolean;
   recordStageUnblocked(runId: string, stageId: string): boolean;
   recordStageNotice(runId: string, stageId: string, notice: StageNotice): boolean;
-  /** Mark a run as `paused`. */
-  recordRunPaused(runId: string, pausedAt?: number): boolean;
+  /** Mark a run as `paused`. Optional metadata can annotate resumable quit/detach state. */
+  recordRunPaused(runId: string, pausedAt?: number, metadata?: RunPauseMetadata): boolean;
   /** Restore a run from `paused` back to `running`. */
   recordRunResumed(runId: string, resumedAt?: number): boolean;
   /** Drop every run and notice. */

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

@@ -1,5 +1,5 @@
 import type { WorkflowOutputValues } from "./types.js";
-import type { Store, RunBlockedMetadata, RunEndMetadata } from "./store-public-types.js";
+import type { Store, RunBlockedMetadata, RunEndMetadata, RunPauseMetadata } from "./store-public-types.js";
 import type { RunSnapshot, RunStatus, StoreSnapshot, WorkflowNotice } from "./store-types.js";
 import { accumulatePausedDurationMs, elapsedRunMs } from "./timing.js";
 import { isTopLevelWorkflowRun } from "./run-visibility.js";
@@ -164,14 +164,19 @@ export function createRunStoreMethods(context: StoreContext): RunStoreMethods {
       return true;
     },
 
-    recordRunPaused(runId: string, pausedAt?: number): boolean {
+    recordRunPaused(runId: string, pausedAt?: number, metadata?: RunPauseMetadata): boolean {
       const run = context.findRun(runId);
       if (!run) return false;
       if (TERMINAL_STATUSES.has(run.status)) return false;
-      if (run.status === "paused") return false;
-      run.status = "paused";
-      run.pausedAt = pausedAt ?? Date.now();
-      run.resumedAt = undefined;
+      const wasPaused = run.status === "paused";
+      if (!wasPaused) {
+        run.status = "paused";
+        run.pausedAt = pausedAt ?? Date.now();
+        run.resumedAt = undefined;
+      }
+      if (metadata?.resumable !== undefined) run.resumable = metadata.resumable;
+      if (metadata?.exitReason !== undefined) run.exitReason = metadata.exitReason;
+      if (wasPaused && metadata === undefined) return false;
       context.bumpAndNotify();
       return true;
     },
@@ -186,6 +191,7 @@ export function createRunStoreMethods(context: StoreContext): RunStoreMethods {
       run.pausedDurationMs = accumulatePausedDurationMs(run.pausedDurationMs, run.pausedAt, resumedTs);
       run.resumedAt = resumedTs;
       run.pausedAt = undefined;
+      delete run.exitReason;
       context.bumpAndNotify();
       return true;
     },

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

@@ -21,6 +21,15 @@ export type { TSchema };
 
 export type { AgentSessionEvent, ContextCompactionResult, ModelCycleResult, PromptOptions };
 
+export type StageUserMessageContent = Parameters<AgentSession["sendUserMessage"]>[0];
+
+export type StageUserMessageDelivery = "steer" | "followUp";
+
+export interface StageSendUserMessageOptions {
+  /** Delivery mode to use when the stage session is already streaming. Defaults to followUp. */
+  readonly deliverAs?: StageUserMessageDelivery;
+}
+
 export type WorkflowModelValue = NonNullable<CreateAgentSessionOptions["model"]> | string;
 export type WorkflowModelUsage = AuthoringContract.WorkflowModelUsage;
 export type WorkflowModelAttempt = AuthoringContract.WorkflowModelAttempt;
@@ -178,6 +187,10 @@ export interface StageOptions<TSchemaDef extends TSchema | undefined = TSchema |
   scopedModels?: CreateAgentSessionOptions["scopedModels"];
   sessionManager?: SessionManager;
   settingsManager?: SettingsManager;
+  /** Internal durable resume hook: reopen this exact Atomic/Pi session file instead of forking. */
+  resumeFromSessionFile?: string;
+  /** Internal durable replay key used to map a live LM session to durable resume state. */
+  durableReplayKey?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -299,6 +312,15 @@ export interface StageContext<TSchemaDef extends TSchema | undefined = undefined
   prompt(text: string, options?: StagePromptOptions): Promise<WorkflowStageResult<TSchemaDef>>;
   complete(text: string, options?: CompleteStageOpts): Promise<string>;
 
+  /**
+   * Send a user-authored follow-on message to this stage session.
+   *
+   * When the session is idle this starts a new user turn immediately. When the
+   * session is streaming, the message is queued as a follow-up by default, or
+   * as steering when `deliverAs: "steer"` is provided.
+   */
+  sendUserMessage(content: StageUserMessageContent, options?: StageSendUserMessageOptions): Promise<void>;
+
   /** Queue messages during streaming. */
   steer(text: string): Promise<void>;
   followUp(text: string): Promise<void>;
@@ -381,6 +403,39 @@ export interface WorkflowRunContext<
   ): Promise<WorkflowChildResult<TChildOutputs>>;
   /** HIL primitives for user interaction during a run. */
   readonly ui: WorkflowUIContext;
+  /**
+   * Durable cached tool execution. Runs arbitrary TypeScript code and caches
+   * the result so completed side effects are not repeated on resume.
+   * Only `ctx.*` blocks produce durable checkpoints.
+   *
+   * cross-ref: issue #1498 — DBOS-backed cross-session resumability.
+   */
+  tool: WorkflowToolPrimitive;
+}
+
+/**
+ * `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;
 }
 
 // ---------------------------------------------------------------------------

package/dist/builtin/workflows/src/tui/dispatch-confirm.ts

@@ -7,7 +7,8 @@
  *  - One status-coloured rounded run card:
  *      title: runId8 · workflowName · ● running
  *      body: compact `k=v · k=v · +N more` input summary when present
- *  - One hint row: ▸ /workflow connect <id>   attach & watch
+ *  - One compact next-step hint:
+ *      ▸ /workflow connect <id>  watch, attach & steer
  *
  * What we deliberately do NOT emit (was in the legacy 7-row layout):
  *  - the `✓ submitted · /workflow <name>` echo line — pi already shows
@@ -19,9 +20,9 @@
  *    an 8-char hex string visually communicates "identifier";
  *  - the `status starting…` body row — the `● running` badge on row 1
  *    occupies the same semantic slot;
- *  - the second hint row `▸ /workflow status` — that is a separate
- *    intent (list other in-flight runs), already discoverable from a
- *    bare `/workflow` invocation and the picker's confirm panel.
+ *  - the second hint row `▸ /workflow status` — that is a separate intent
+ *    (list other in-flight runs), already discoverable from a bare `/workflow`
+ *    invocation and the picker's confirm panel.
  *
  * Plain mode drops ANSI; the rounded panel/card layout shape is preserved.
  *
@@ -70,8 +71,7 @@ export interface RenderDispatchConfirmOpts {
 /**
  * Render the post-dispatch confirmation: one rounded panel containing a
  * rounded run card with runId, workflow name, inputs summary, and a
- * `● running` status badge, followed by one hint row pointing at
- * `/workflow connect <id>`.
+ * `● running` status badge, followed by a workflow-control hint.
  */
 export function renderDispatchConfirm(opts: RenderDispatchConfirmOpts): string {
   const width = effectiveWidth(opts.width);
@@ -142,10 +142,11 @@ export function renderDispatchConfirm(opts: RenderDispatchConfirmOpts): string {
     : [`   ${titleSuffix ?? "started in background"} `];
   const titleLine = ` ●  ${tag}  ${opts.workflowName}  ${trailing.text} `;
 
-  const hints = renderHintRows(
-    [{ command: `/workflow connect ${tag}`, hint: "attach & watch" }],
-    theme,
-  ).split("\n").map((line) => ` ${line} `);
+  const hints = renderHintRows([
+    { command: `/workflow connect ${tag}`, hint: "watch, attach & steer" },
+  ], theme)
+    .split("\n")
+    .map((line) => ` ${line} `);
 
   return renderRoundedBox({
     title: "DISPATCHED",

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

@@ -3,7 +3,7 @@ export const HINT_KEYS: Array<{ key: string; label: string }> = [
   { key: "↵", label: "attach" },
   { key: "/", label: "stages" },
   { key: "ctrl+d", label: "detach" },
-  { key: "q", label: "kill" },
+  { key: "q", label: "quit" },
 ];
 
 /**

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

@@ -16,6 +16,8 @@ export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
   protected _renderGraph(width: number): string[] {
     const run = this._getCurrentRun();
     if (!run || this.cachedLayout.length === 0) {
+      this.lastGraphViewport = null;
+      this.graphNodeHitRects = [];
       const dim = hexToAnsi(this.graphTheme.dim);
       return [
         this._centerCanvasContent(
@@ -40,6 +42,7 @@ export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
     );
     const viewportWidth = Math.max(1, width - leftMargin);
     const fullCanvasWidth = Math.max(canvasWidth, viewportWidth);
+    this.lastGraphViewport = { leftMargin, viewportWidth };
     this._clampGraphHorizontalScroll(fullCanvasWidth, viewportWidth);
     if (this.pendingEnsureFocusedVisible) {
       this._scrollFocusedColumnIntoView(viewportWidth, fullCanvasWidth);
@@ -129,6 +132,44 @@ export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
     });
   }
 
+  protected _recordGraphNodeHitRects(
+    graphStartRow: number,
+    visibleRowCount: number,
+  ): void {
+    const viewport = this.lastGraphViewport;
+    if (!viewport || visibleRowCount <= 0) {
+      this.graphNodeHitRects = [];
+      return;
+    }
+
+    const visibleTop = graphStartRow;
+    const visibleBottom = graphStartRow + visibleRowCount;
+    const viewportLeft = viewport.leftMargin;
+    const viewportRight = viewport.leftMargin + viewport.viewportWidth;
+    const rects: typeof this.graphNodeHitRects = [];
+
+    for (let index = 0; index < this.cachedLayout.length; index++) {
+      const node = this.cachedLayout[index]!;
+      const top = graphStartRow + node.y - this.graphScrollOffset;
+      const bottom = top + NODE_H;
+      const left = viewport.leftMargin + node.x - this.graphScrollColOffset;
+      const right = left + NODE_W;
+      const clippedTop = Math.max(visibleTop, top);
+      const clippedBottom = Math.min(visibleBottom, bottom);
+      const clippedLeft = Math.max(viewportLeft, left);
+      const clippedRight = Math.min(viewportRight, right);
+      if (clippedTop >= clippedBottom || clippedLeft >= clippedRight) continue;
+      rects.push({
+        index,
+        top: clippedTop,
+        bottom: clippedBottom,
+        left: clippedLeft,
+        right: clippedRight,
+      });
+    }
+    this.graphNodeHitRects = rects;
+  }
+
   protected _visibleGraphLines(
     graphLines: string[],
     frameWidth: number,

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

@@ -11,6 +11,13 @@ import {
 import { filterStages, type SwitcherState } from "./switcher.js";
 import { Key, matchesKey } from "./text-helpers.js";
 
+interface SgrMouseEvent {
+  buttonCode: number;
+  col: number;
+  row: number;
+  final: "M" | "m";
+}
+
 /** Keyboard, mouse, switcher, prompt, and focus navigation handling. */
 export abstract class GraphViewInputController extends GraphViewRenderer {
   /** Returns true if consumed. */
@@ -80,6 +87,15 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
       return true;
     }
 
+    const clickedNodeIndex = this._graphNodeIndexForClick(data);
+    if (clickedNodeIndex !== undefined) {
+      if (clickedNodeIndex !== null) {
+        this._setFocusedIndex(clickedNodeIndex);
+        this._activateFocusedNode();
+      }
+      return true;
+    }
+
     // Vertical-graph navigation: up/down step between depth levels
     // (col), left/right step between siblings at the same depth (row).
     // j/k preserved as a flat-order fallback for muscle memory.
@@ -115,12 +131,7 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
       return true;
     }
     if (matchesKey(data, Key.enter)) {
-      // Enter attaches the popup interior to the focused stage. The
-      // attach shell swaps in the stage-chat view without remounting
-      // the overlay; without a callback, fall back to the legacy
-      // expand/collapse toggle so non-attach hosts still work.
-      if (this._attachFocusedStage()) return true;
-      this.detailsExpanded = !this.detailsExpanded;
+      this._activateFocusedNode();
       return true;
     }
     // `ctrl+d` detaches the whole popup (host hides the overlay). This
@@ -133,16 +144,13 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
       }
       return true;
     }
-    // `q` kills the active run (no confirm). `h` hides the pane via
-    // the overlay's setHidden() flag (not unmount); Escape/Ctrl+C closes.
+    // `q` quits/detaches the orchestrator view without authoritatively
+    // killing the workflow. The workflow remains resumable via
+    // `/workflow resume`; use `/workflow kill` for non-resumable disposal.
     if (matchesKey(data, "q")) {
       const run = this._getCurrentRun();
-      const targetRunId = this._focusedStageTarget()?.runId ?? run?.id;
-      const targetRun = targetRunId !== undefined
-        ? this.currentSnapshot?.runs.find((candidate) => candidate.id === targetRunId)
-        : undefined;
-      if (targetRun && targetRun.endedAt === undefined && this.onKill) {
-        this.onKill(targetRun.id);
+      if (run && run.endedAt === undefined && this.onQuit) {
+        this.onQuit(run.id);
       }
       this.onClose?.();
       return true;
@@ -265,6 +273,15 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
     return true;
   }
 
+  private _activateFocusedNode(): void {
+    // Enter and direct node clicks attach the popup interior to the focused
+    // stage. The attach shell swaps in the stage-chat view without remounting
+    // the overlay; without a callback, fall back to the legacy expand/collapse
+    // toggle so non-attach hosts still work.
+    if (this._attachFocusedStage()) return;
+    this.detailsExpanded = !this.detailsExpanded;
+  }
+
   private _attachFocusedStage(): boolean {
     if (!this.onStageAttach) return false;
     const node = this.cachedLayout[this.focusedIndex];
@@ -278,13 +295,6 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
     return true;
   }
 
-  private _focusedStageTarget(): { runId: string; stageId: string } | undefined {
-    const node = this.cachedLayout[this.focusedIndex];
-    if (!node) return undefined;
-    const target = expandedStageTarget(this.expandedGraph, node.stage.id);
-    return target ? { runId: target.runId, stageId: target.stageId } : undefined;
-  }
-
   private _setFocusedIndex(index: number): void {
     const max = Math.max(0, this.cachedLayout.length - 1);
     const next = Math.max(0, Math.min(index, max));
@@ -298,10 +308,55 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
     this.graphScrollOffset = Math.max(0, this.graphScrollOffset + deltaRows);
   }
 
+  private _graphNodeIndexForClick(data: string): number | null | undefined {
+    const click = this._sgrLeftMousePress(data);
+    if (!click) return undefined;
+    if (this.mode !== "overlay") return undefined;
+    if (this.cachedLayout.length === 0) return null;
+
+    for (const rect of this.graphNodeHitRects) {
+      if (
+        click.row >= rect.top &&
+        click.row < rect.bottom &&
+        click.col >= rect.left &&
+        click.col < rect.right
+      ) {
+        return rect.index;
+      }
+    }
+    return null;
+  }
+
+  private _parseSgrMouse(data: string): SgrMouseEvent | null {
+    const sgr = data.match(/^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/);
+    if (!sgr) return null;
+    const oneBasedCol = Number.parseInt(sgr[2]!, 10);
+    const oneBasedRow = Number.parseInt(sgr[3]!, 10);
+    const final = sgr[4];
+    if (oneBasedCol < 1 || oneBasedRow < 1) return null;
+    if (final !== "M" && final !== "m") return null;
+    return {
+      buttonCode: Number.parseInt(sgr[1]!, 10),
+      col: oneBasedCol - 1,
+      row: oneBasedRow - 1,
+      final,
+    };
+  }
+
+  private _sgrLeftMousePress(data: string): { col: number; row: number } | null {
+    const sgr = this._parseSgrMouse(data);
+    if (!sgr || sgr.final !== "M") return null;
+    const buttonCode = sgr.buttonCode;
+    if ((buttonCode & 64) !== 0 || (buttonCode & 32) !== 0 || (buttonCode & 3) !== 0) {
+      return null;
+    }
+    return { col: sgr.col, row: sgr.row };
+  }
+
   private _mouseWheelDeltaRows(data: string): number {
-    const sgr = data.match(/^\x1b\[<(\d+);\d+;\d+M$/);
-    if (sgr) {
-      return this._wheelDeltaForButtonCode(Number.parseInt(sgr[1]!, 10));
+    const sgr = this._parseSgrMouse(data);
+    if (sgr && sgr.final === "M") {
+      return this._wheelDeltaForButtonCode(sgr.buttonCode);
     }
     if (data.startsWith("\x1b[M") && data.length >= 6) {
       return this._wheelDeltaForButtonCode(data.charCodeAt(3) - 32);
@@ -330,4 +385,7 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
   get _graphScrollOffset(): number {
     return this.graphScrollOffset;
   }
+  get _graphScrollColOffset(): number {
+    return this.graphScrollColOffset;
+  }
 }

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

@@ -37,6 +37,7 @@ export abstract class GraphViewRenderer extends GraphViewGraphRenderer {
 
   protected _renderOverlay(width: number): string[] {
     const frameWidth = Math.max(40, width);
+    this.lastOverlayFrameWidth = frameWidth;
     const lines: string[] = [];
     const run = this._getCurrentRun();
 
@@ -58,6 +59,10 @@ export abstract class GraphViewRenderer extends GraphViewGraphRenderer {
       frameWidth,
       bodyTarget,
     );
+    this._recordGraphNodeHitRects(
+      this._overlayVerticalMarginRows() + 3 + visibleGraph.topPad,
+      visibleGraph.lines.length,
+    );
     for (let i = 0; i < visibleGraph.topPad; i++)
       lines.push(this._blankRow(frameWidth));
     for (const line of visibleGraph.lines) {
@@ -78,6 +83,8 @@ export abstract class GraphViewRenderer extends GraphViewGraphRenderer {
   }
 
   protected _renderEmptyState(width: number): string[] {
+    this.graphNodeHitRects = [];
+    this.lastGraphViewport = null;
     const t = this.graphTheme;
     const muted = hexToAnsi(t.textMuted);
     const dim = hexToAnsi(t.dim);

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

@@ -34,6 +34,19 @@ export interface GraphStageCounts {
   skipped: number;
 }
 
+interface GraphNodeHitRect {
+  index: number;
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+
+interface GraphViewportGeometry {
+  leftMargin: number;
+  viewportWidth: number;
+}
+
 /** Expansion, focus, prompt, and store-backed layout state for GraphView. */
 export abstract class GraphViewState {
   protected mode: GraphViewMode;
@@ -41,7 +54,7 @@ export abstract class GraphViewState {
   protected store: Store;
   protected graphTheme: GraphTheme;
   protected onClose?: () => void;
-  protected onKill?: (runId: string) => void;
+  protected onQuit?: (runId: string) => void;
   protected onHide?: () => void;
   protected onPromptResolve?: (runId: string, promptId: string, response: unknown) => void;
   protected onStageAttach?: (runId: string, stageId: string) => void;
@@ -64,6 +77,9 @@ export abstract class GraphViewState {
   protected currentSnapshot: StoreSnapshot | null = null;
   protected graphScrollOffset = 0;
   protected graphScrollColOffset = 0;
+  protected graphNodeHitRects: GraphNodeHitRect[] = [];
+  protected lastGraphViewport: GraphViewportGeometry | null = null;
+  protected lastOverlayFrameWidth = 80;
   protected pendingEnsureFocusedVisible = true;
   protected lastAutoFocusedAwaitingInputKey: string | null = null;
 
@@ -77,7 +93,7 @@ export abstract class GraphViewState {
     this.store = opts.store;
     this.graphTheme = opts.graphTheme;
     this.onClose = opts.onClose;
-    this.onKill = opts.onKill;
+    this.onQuit = opts.onQuit;
     this.onHide = opts.onHide;
     this.onPromptResolve = opts.onPromptResolve;
     this.onStageAttach = opts.onStageAttach;
@@ -121,6 +137,8 @@ export abstract class GraphViewState {
       this.focusedIndex = 0;
       this.graphScrollOffset = 0;
       this.graphScrollColOffset = 0;
+      this.graphNodeHitRects = [];
+      this.lastGraphViewport = null;
       this.pendingEnsureFocusedVisible = true;
       this.promptState = null;
       return;
@@ -130,6 +148,8 @@ export abstract class GraphViewState {
     const graphStages = this._graphStages(run);
     const nextLayout = computeLayout(graphStages, { orientation: "vertical" });
     this.cachedLayout = nextLayout;
+    this.graphNodeHitRects = [];
+    this.lastGraphViewport = null;
 
     let focusNeedsReveal = this.pendingEnsureFocusedVisible;
     // One-shot: if the host passed `initialFocusedStageId`, snap the

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

@@ -10,12 +10,11 @@ export interface GraphViewOpts {
   graphTheme: GraphTheme;
   onClose?: () => void;
   /**
-   * Invoked when the user presses `q` inside the pane on an in-flight
-   * run. Fires immediately (no confirm) per the toggle-driven UX:
-   * `h` hides without quitting; `q` is reserved for terminating the
-   * current run.
+   * Invoked when the user presses `q` inside the pane. This quits/detaches
+   * the orchestrator view and leaves the workflow resumable; it must not use
+   * the `/workflow kill` terminal path.
    */
-  onKill?: (runId: string) => void;
+  onQuit?: (runId: string) => void;
   /**
    * Invoked when the user presses `h` inside the pane. Hides without
    * unmounting (overlay-adapter calls `setHidden(true)`). Re-open via