@bastani/atomic 0.9.9 → 0.9.10-alpha.1

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

@@ -88,6 +88,9 @@ export interface WorkflowRuntimeConfig {
     readonly statusFile: boolean;
     readonly statusFilePath?: string;
     readonly resumeInFlight: "ask" | "auto" | "never";
+    readonly worktree?: {
+        readonly symlinkDirectories: readonly string[];
+    };
 }
 export interface WorkflowWorktreeInputBinding {
     readonly gitWorktreeDir: string;
@@ -191,6 +194,8 @@ export interface WorkflowDetails extends WorkflowSerializableObject {
     readonly controlEvents?: readonly WorkflowControlEvent[];
     readonly intercom?: WorkflowIntercomSummary;
     readonly warnings?: readonly string[];
+    /** Actionable user guidance for accepted background execution. */
+    readonly message?: string;
     readonly error?: string;
     /** True when the run reached its terminal status through ctx.exit(). */
     readonly exited?: boolean;

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

@@ -148,6 +148,9 @@ export interface WorkflowRuntimeConfig {
   readonly statusFile: boolean;
   readonly statusFilePath?: string;
   readonly resumeInFlight: "ask" | "auto" | "never";
+  readonly worktree?: {
+    readonly symlinkDirectories: readonly string[];
+  };
 }
 
 export interface WorkflowWorktreeInputBinding {
@@ -268,6 +271,8 @@ export interface WorkflowDetails extends WorkflowSerializableObject {
   readonly controlEvents?: readonly WorkflowControlEvent[];
   readonly intercom?: WorkflowIntercomSummary;
   readonly warnings?: readonly string[];
+  /** Actionable user guidance for accepted background execution. */
+  readonly message?: string;
   readonly error?: string;
   /** True when the run reached its terminal status through ctx.exit(). */
   readonly exited?: boolean;

package/dist/builtin/workflows/src/shared/intercom-group.ts

@@ -0,0 +1,51 @@
+import { randomUUID } from "node:crypto";
+import type { StageOptions } from "./types.js";
+
+/** The implicit group shared by every ungrouped session. */
+export const DEFAULT_INTERCOM_GROUP = "default";
+
+/** Normalize authored or agent-serialized auto-group sentinels without changing real group names. */
+export function normalizeAutoGroupSentinel(group: string | true): string | true {
+  if (group === true) return true;
+  const sentinel = group.trim().toLowerCase();
+  return sentinel === "true" || sentinel === "auto" ? true : group;
+}
+
+/** Trim; empty/undefined collapses to the shared default group. */
+export function normalizeGroup(value?: string | null): string {
+  if (typeof value !== "string") return DEFAULT_INTERCOM_GROUP;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : DEFAULT_INTERCOM_GROUP;
+}
+
+/**
+ * Resolve a stage's `group` option to a concrete home-group string, or undefined
+ * when the stage did not request a group (so the intercom layer falls back to
+ * env/config/default). A named string is trimmed; a bare `true` that survives to
+ * this point (a single, non-parallel stage) mints one fresh UUID for that stage.
+ * Parallel sets resolve `true` to one shared UUID upstream, so it never reaches
+ * here as `true`.
+ */
+export function resolveStageGroup(stageOptions?: { group?: string | true }): string | undefined {
+  if (!stageOptions) return undefined;
+  const group = stageOptions.group;
+  if (group === undefined) return undefined;
+  if (group === true) return randomUUID();
+  const trimmed = group.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+/**
+ * Whether a stage session will actually have an intercom tool available. Group
+ * assignment is skipped for stages without intercom access so an agent is never
+ * placed into an isolated group it cannot use.
+ */
+export function stageHasIntercomAccess(stageOptions?: StageOptions): boolean {
+  if (!stageOptions) return true;
+  if (stageOptions.noTools === "all" || stageOptions.noTools === "builtin") return false;
+  const tools = stageOptions.tools;
+  if (Array.isArray(tools) && !tools.includes("intercom")) return false;
+  const excluded = stageOptions.excludedTools;
+  if (Array.isArray(excluded) && excluded.includes("intercom")) return false;
+  return true;
+}

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

@@ -357,6 +357,7 @@ export function restoreTerminalRuns(entries: readonly SessionEntry[], store: Sto
       ...(runMeta.rootRunId !== undefined ? { rootRunId: runMeta.rootRunId } : {}),
       ...(runMeta.resumedFromRunId !== undefined ? { resumedFromRunId: runMeta.resumedFromRunId } : {}),
       ...(runMeta.resumeFromStageId !== undefined ? { resumeFromStageId: runMeta.resumeFromStageId } : {}),
+      ...(runMeta.accumulatedDurationMs !== undefined ? { accumulatedDurationMs: runMeta.accumulatedDurationMs } : {}),
     });
 
     const error = end["error"];
@@ -425,6 +426,7 @@ export function findRunStartMetadata(
   readonly rootRunId?: string;
   readonly resumedFromRunId?: string;
   readonly resumeFromStageId?: string;
+  readonly accumulatedDurationMs?: number;
 } {
   for (const entry of entries) {
     if (entry.type !== "workflow.run.start" || entry.payload["runId"] !== runId) continue;
@@ -433,12 +435,16 @@ export function findRunStartMetadata(
     const rootRunId = entry.payload["rootRunId"];
     const resumedFromRunId = entry.payload["resumedFromRunId"];
     const resumeFromStageId = entry.payload["resumeFromStageId"];
+    const accumulatedDurationMs = entry.payload["accumulatedDurationMs"];
     return {
       ...(typeof parentRunId === "string" ? { parentRunId } : {}),
       ...(typeof parentStageId === "string" ? { parentStageId } : {}),
       ...(typeof rootRunId === "string" ? { rootRunId } : {}),
       ...(typeof resumedFromRunId === "string" ? { resumedFromRunId } : {}),
       ...(typeof resumeFromStageId === "string" ? { resumeFromStageId } : {}),
+      ...(typeof accumulatedDurationMs === "number" && Number.isFinite(accumulatedDurationMs) && accumulatedDurationMs > 0
+        ? { accumulatedDurationMs }
+        : {}),
     };
   }
   return {};

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

@@ -55,6 +55,7 @@ export function normalizeSessionEntries(entries: readonly SessionEntry[]): reado
 
 /** Structural type for pi's sessionManager (optional — degrades gracefully). */
 export interface SessionManager {
+  getCwd?: () => string;
   getEntries?: () => SessionEntry[] | readonly SessionEntry[];
   getSessionDir?: () => string;
   usesDefaultSessionDir?: () => boolean;
@@ -210,6 +211,7 @@ export function restoreOnSessionStart(
         ...(runMeta.rootRunId !== undefined ? { rootRunId: runMeta.rootRunId } : {}),
         ...(runMeta.resumedFromRunId !== undefined ? { resumedFromRunId: runMeta.resumedFromRunId } : {}),
         ...(runMeta.resumeFromStageId !== undefined ? { resumeFromStageId: runMeta.resumeFromStageId } : {}),
+        ...(runMeta.accumulatedDurationMs !== undefined ? { accumulatedDurationMs: runMeta.accumulatedDurationMs } : {}),
       };
       store.recordRunStart(runSnapshot);
       store.recordRunBlocked(run.runId, blockedMeta.error, {
@@ -240,6 +242,7 @@ export function restoreOnSessionStart(
         ...(runMeta.rootRunId !== undefined ? { rootRunId: runMeta.rootRunId } : {}),
         ...(runMeta.resumedFromRunId !== undefined ? { resumedFromRunId: runMeta.resumedFromRunId } : {}),
         ...(runMeta.resumeFromStageId !== undefined ? { resumeFromStageId: runMeta.resumeFromStageId } : {}),
+        ...(runMeta.accumulatedDurationMs !== undefined ? { accumulatedDurationMs: runMeta.accumulatedDurationMs } : {}),
       };
       store.recordRunStart(runSnapshot);
       callbacks.onResume?.(run);
@@ -261,6 +264,7 @@ export function restoreOnSessionStart(
         ...(runMeta.rootRunId !== undefined ? { rootRunId: runMeta.rootRunId } : {}),
         ...(runMeta.resumedFromRunId !== undefined ? { resumedFromRunId: runMeta.resumedFromRunId } : {}),
         ...(runMeta.resumeFromStageId !== undefined ? { resumeFromStageId: runMeta.resumeFromStageId } : {}),
+        ...(runMeta.accumulatedDurationMs !== undefined ? { accumulatedDurationMs: runMeta.accumulatedDurationMs } : {}),
       };
       store.recordRunStart(runSnapshot);
       store.recordRunEnd(run.runId, "failed");

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

@@ -43,6 +43,8 @@ export interface RunStartPayload {
   readonly rootRunId?: string;
   readonly resumedFromRunId?: string;
   readonly resumeFromStageId?: string;
+  /** Elapsed ms inherited from prior sessions of a resumed run. */
+  readonly accumulatedDurationMs?: number;
   readonly ts: number;
 }
 
@@ -150,6 +152,7 @@ export function appendRunStart(api: PersistenceAPI, payload: RunStartPayload): v
     ...(payload.rootRunId !== undefined ? { rootRunId: payload.rootRunId } : {}),
     ...(payload.resumedFromRunId !== undefined ? { resumedFromRunId: payload.resumedFromRunId } : {}),
     ...(payload.resumeFromStageId !== undefined ? { resumeFromStageId: payload.resumeFromStageId } : {}),
+    ...(payload.accumulatedDurationMs !== undefined ? { accumulatedDurationMs: payload.accumulatedDurationMs } : {}),
     ts: payload.ts,
   });
   if (entryId && typeof api.setLabel === "function") {

package/dist/builtin/workflows/src/shared/prompt-callsite-context.ts

@@ -0,0 +1,13 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const promptCallerStacks = new AsyncLocalStorage<string>();
+
+/** Preserve the workflow-author stack across durable writes before a prompt delegates. */
+export function withPromptCallerStack<T>(stack: string | undefined, delegate: () => T): T {
+  if (stack === undefined) return delegate();
+  return promptCallerStacks.run(stack, delegate);
+}
+
+export function currentPromptCallerStack(): string | undefined {
+  return promptCallerStacks.getStore();
+}

package/dist/builtin/workflows/src/shared/returned-run-status.ts

@@ -73,8 +73,9 @@ export function structuredRecoverableWorkflowFailureText(
 }
 
 export function effectiveRunStatus(run: RunSnapshot): RunStatus {
+  if ((run.status === "running" || run.status === "completed")
+    && structuredRecoverableWorkflowFailure(run) !== undefined) return "blocked";
   if (run.status !== "completed") return run.status;
-  if (structuredRecoverableWorkflowFailure(run) !== undefined) return "blocked";
   const returnedStatus = normalizeReturnedWorkflowStatus(run.result?.["status"]);
   if (returnedStatus === "failed") return "failed";
   if (returnedStatus !== undefined && isReturnedBlockedWorkflowStatus(returnedStatus)) return "blocked";

package/dist/builtin/workflows/src/shared/session-transcript.ts

@@ -0,0 +1,74 @@
+/**
+ * Shared retained-session transcript validation.
+ *
+ * A stage snapshot's `sessionFile` is only reopenable as a post-mortem chat
+ * when the referenced path is an existing, readable, regular file whose JSONL
+ * contents parse into a genuine Atomic session with at least one usable
+ * context-bearing message. This guards the completed-workflow catalog and the
+ * post-mortem stage-chat resolver against blank / missing / truncated
+ * transcripts, and prevents `SessionManager.open()` from turning a missing path
+ * into an empty session.
+ *
+ * cross-ref:
+ *   - src/durable/completed-catalog.ts (catalog eligibility)
+ *   - src/runs/foreground/postmortem-stage-chat.ts (revival eligibility)
+ */
+import { readFileSync, statSync } from "node:fs";
+
+interface SessionTranscriptEntry {
+  readonly type?: string;
+  readonly id?: string;
+  readonly timestamp?: string;
+  readonly message?: {
+    readonly role?: string;
+    readonly content?: string | object;
+  };
+}
+
+/**
+ * True when `path` points at a readable regular file containing a parseable
+ * Atomic session header plus at least one usable context message.
+ */
+export function isReopenableSessionTranscript(path: string): boolean {
+  try {
+    const stats = statSync(path);
+    if (!stats.isFile() || stats.size === 0) return false;
+    const lines = readFileSync(path, "utf8").split("\n").filter((line) => line.trim().length > 0);
+    if (lines.length < 2) return false;
+    const entries: SessionTranscriptEntry[] = [];
+    for (const line of lines) {
+      const parsed = JSON.parse(line) as object;
+      if (typeof parsed !== "object" || parsed === null) return false;
+      entries.push(parsed as SessionTranscriptEntry);
+    }
+    const header = entries[0];
+    return header?.type === "session" && typeof header.id === "string" && entries.some(isUsableContextMessage);
+  } catch {
+    return false;
+  }
+}
+
+function isUsableContextMessage(entry: SessionTranscriptEntry): boolean {
+  return entry.type === "message"
+    && typeof entry.id === "string"
+    && typeof entry.timestamp === "string"
+    && typeof entry.message?.role === "string"
+    && hasUsableMessageContent(entry.message.content);
+}
+
+function hasUsableMessageContent(content: string | object | undefined): boolean {
+  if (typeof content === "string") return content.trim().length > 0;
+  return Array.isArray(content) && content.some(hasUsableContentBlock);
+}
+
+function hasUsableContentBlock(block: object): boolean {
+  if (typeof block !== "object" || block === null) return false;
+  const contentBlock = block as {
+    readonly text?: string;
+    readonly thinking?: string;
+    readonly data?: string;
+    readonly name?: string;
+  };
+  return [contentBlock.text, contentBlock.thinking, contentBlock.data, contentBlock.name]
+    .some((value) => typeof value === "string" && value.trim().length > 0);
+}

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

@@ -286,6 +286,7 @@ export function createStageStoreMethods(context: StoreContext): StageStoreMethod
     recordStageResumed(runId: string, stageId: string, resumedAt?: number): boolean {
       const run = context.findRun(runId);
       if (!run) return false;
+      if (TERMINAL_STATUSES.has(run.status)) return false;
       const stage = context.findStage(run, stageId);
       if (!stage) return false;
       if (stage.status !== "paused" && stage.status !== "blocked") return false;

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

@@ -142,6 +142,8 @@ export interface StageSnapshot {
    * refreshes parents, so do not cache this reference across store updates.
    */
   parentIds: readonly string[];
+  /** Set when durable inspection cannot safely determine the original stage lineage. */
+  topologyState?: "unavailable";
   startedAt?: number;
   endedAt?: number;
   durationMs?: number;
@@ -238,6 +240,12 @@ export interface RunSnapshot {
   startedAt: number;
   endedAt?: number;
   durationMs?: number;
+  /**
+   * Elapsed milliseconds inherited from prior sessions of this run. Seeded on
+   * durable/continuation resume so `elapsedRunMs` reports prior + current
+   * elapsed instead of restarting the total workflow duration at zero.
+   */
+  accumulatedDurationMs?: number;
   /** Milliseconds spent paused across completed pause intervals. */
   pausedDurationMs?: number;
   /** Timestamp set when a controlled pause begins; cleared on resume. */

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

@@ -12,6 +12,8 @@ interface RunTimerSnapshot {
   readonly durationMs?: number;
   readonly pausedDurationMs?: number;
   readonly pausedAt?: number;
+  /** Elapsed ms inherited from prior sessions of a resumed durable run. */
+  readonly accumulatedDurationMs?: number;
 }
 
 function nonNegative(ms: number): number {
@@ -52,5 +54,6 @@ export function elapsedStageMs(stage: StageTimerSnapshot, now = Date.now()): num
 export function elapsedRunMs(run: RunTimerSnapshot, now = Date.now()): number {
   if (run.durationMs !== undefined) return nonNegative(run.durationMs);
   const effectiveNow = run.endedAt ?? now;
-  return elapsedFromStart(run.startedAt, effectiveNow, run.pausedDurationMs, run.pausedAt);
+  return nonNegative(run.accumulatedDurationMs ?? 0)
+    + elapsedFromStart(run.startedAt, effectiveNow, run.pausedDurationMs, run.pausedAt);
 }

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

@@ -216,6 +216,8 @@ export interface StageExecutionMeta {
   signal?: AbortSignal;
   /** Runtime execution mode for policy-aware child sessions. */
   executionMode?: WorkflowExecutionMode;
+  /** Internal stage-generation context reused across model-fallback sessions. */
+  orchestrationContext?: CreateAgentSessionOptions["orchestrationContext"];
 }
 
 export interface CompleteStageOpts extends WorkflowModelFallbackFields {
@@ -289,12 +291,6 @@ export type WorkflowAction = AuthoringContract.WorkflowAction;
 export type WorkflowDetails = Mutable<AuthoringContract.WorkflowDetails>;
 export type WorkflowTaskSessionFields = Mutable<AuthoringContract.WorkflowTaskSessionFields>;
 export type WorkflowTaskSessionOptions = StageOptions & WorkflowTaskSessionFields;
-export interface WorkflowDirectTaskItem extends WorkflowTaskOptions, Omit<Mutable<AuthoringContract.WorkflowDirectTaskItem>, keyof AuthoringContract.WorkflowTaskOptions> {}
-export interface WorkflowParallelChainStep extends Omit<AuthoringContract.WorkflowParallelChainStep, "parallel"> {
-  readonly parallel: readonly WorkflowDirectTaskItem[];
-}
-export type WorkflowChainStep = WorkflowDirectTaskItem | WorkflowParallelChainStep;
-export interface WorkflowDirectOptions extends StageOptions, Omit<Mutable<AuthoringContract.WorkflowDirectOptions>, keyof AuthoringContract.StageOptions> {}
 
 // ---------------------------------------------------------------------------
 // Stage context (provided to ctx.stage() calls)

package/dist/builtin/workflows/src/tui/chat-surface-message.ts

@@ -27,7 +27,7 @@
 
 import type { ExtensionAPI } from "../extension/index.js";
 import type { RunDetail } from "../runs/background/status.js";
-import type { RunSnapshot, RunStatus } from "../shared/store-types.js";
+import type { RunSnapshot } from "../shared/store-types.js";
 import type { WorkflowInputValues } from "../shared/types.js";
 import type { GraphTheme } from "./graph-theme.js";
 import type { WorkflowListEntry } from "./workflow-list.js";
@@ -35,7 +35,6 @@ import { renderDispatchConfirm } from "./dispatch-confirm.js";
 import { renderRunDetail } from "./run-detail.js";
 import { renderStatusList } from "./status-list.js";
 import { renderWorkflowList } from "./workflow-list.js";
-import { renderWorkflowKilledNotice } from "./session-confirm.js";
 
 /** Custom message type wired to {@link registerChatSurfaceRenderer}. */
 export const CHAT_SURFACE_CUSTOM_TYPE = "workflows:chat-surface";
@@ -82,19 +81,11 @@ export interface DetailPayload {
   detail: RunDetail;
 }
 
-/** Inline notice after a workflow run is killed and retained for inspection. */
-export interface KilledPayload {
-  kind: "killed";
-  run: RunSnapshot;
-  previousStatus: RunStatus;
-}
-
 export type ChatSurfacePayload =
   | DispatchPayload
   | StatusPayload
   | ListPayload
-  | DetailPayload
-  | KilledPayload;
+  | DetailPayload;
 
 // ---------------------------------------------------------------------------
 // Renderer registration
@@ -218,16 +209,6 @@ export function renderChatSurfacePlainText(
       }
       return lines.join("\n");
     }
-    case "killed":
-      if (options.theme !== undefined) {
-        return renderWorkflowKilledNotice({
-          width: width ?? 80,
-          theme: options.theme,
-          run: payload.run,
-          previousStatus: payload.previousStatus,
-        }).join("\n");
-      }
-      return renderKilledPlainText(payload);
   }
 }
 
@@ -274,20 +255,6 @@ function formatWorkflowEntryPlain(entry: WorkflowListEntry): string {
   return `workflow: ${entry.name} · description: ${entry.description} · ${inputSummary}`;
 }
 
-function renderKilledPlainText(payload: KilledPayload): string {
-  const run = payload.run;
-  const stageCount = run.stages.length;
-  const runningStages = run.stages.filter((stage) => stage.status === "running").length;
-  return [
-    "Workflow killed",
-    `workflow: ${run.name}`,
-    `run id: ${run.id}`,
-    `status: ${payload.previousStatus} → killed`,
-    `active stages: ${runningStages}/${stageCount}`,
-    `inspect: /workflow status ${run.id}`,
-  ].join("\n");
-}
-
 function formatPlainRecord(record: Readonly<WorkflowInputValues>): string {
   const entries = Object.entries(record);
   if (entries.length === 0) return "(none)";
@@ -353,12 +320,5 @@ function renderPayload(
       return renderWorkflowList(payload.entries, { theme, width });
     case "detail":
       return renderRunDetail(payload.detail, { theme, width, now });
-    case "killed":
-      return renderWorkflowKilledNotice({
-        width,
-        theme,
-        run: payload.run,
-        previousStatus: payload.previousStatus,
-      }).join("\n");
   }
 }

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

@@ -8,7 +8,7 @@
  *      title: runId8 · workflowName · ● running
  *      body: compact `k=v · k=v · +N more` input summary when present
  *  - One compact next-step hint:
- *      ▸ /workflow connect <id>  watch, attach & steer
+ *      ▸ /workflow connect <id>  see agents working · chat with and steer each stage
  *
  * What we deliberately do NOT emit (was in the legacy 7-row layout):
  *  - the `✓ submitted · /workflow <name>` echo line — pi already shows
@@ -143,7 +143,7 @@ export function renderDispatchConfirm(opts: RenderDispatchConfirmOpts): string {
   const titleLine = ` ●  ${tag}  ${opts.workflowName}  ${trailing.text} `;
 
   const hints = renderHintRows([
-    { command: `/workflow connect ${tag}`, hint: "watch, attach & steer" },
+    { command: `/workflow connect ${tag}`, hint: "see agents working · chat with and steer each stage" },
   ], theme)
     .split("\n")
     .map((line) => ` ${line} `);

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

@@ -1,9 +1,13 @@
 export const HINT_KEYS: Array<{ key: string; label: string }> = [
+  { key: "ctrl+x", label: "return to main chat" },
+  { key: "↵", label: "open stage chat" },
   { key: "↑↓←→", label: "navigate" },
-  { key: "↵", label: "attach" },
   { key: "/", label: "stages" },
-  { key: "ctrl+d", label: "detach" },
-  { key: "q", label: "quit" },
+];
+
+export const COMPACT_HINT_KEYS: Array<{ key: string; label: string }> = [
+  { key: "ctrl+x", label: "return to main chat" },
+  { key: "↵", label: "stage chat" },
 ];
 
 /**

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

@@ -5,6 +5,11 @@ import {
 } from "./graph-view-constants.js";
 import { GraphViewRenderer } from "./graph-view-render.js";
 import { isKeybindingsLike, type KeybindingsLike } from "./keybindings-adapter.js";
+import {
+  isTerminalLeftMousePress,
+  parseTerminalMouseInput,
+  terminalMouseWheelDirection,
+} from "./mouse-input.js";
 import {
   defaultResponseFor,
   handlePromptCardInput,
@@ -12,12 +17,6 @@ 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";
-}
 
 interface MouseWheelDelta {
   cols: number;
@@ -28,6 +27,10 @@ interface MouseWheelDelta {
 export abstract class GraphViewInputController extends GraphViewRenderer {
   /** Returns true if consumed. */
   handleInput(data: string): boolean {
+    if (this._isReturnToMainChatInput(data)) {
+      this._returnToMainChat();
+      return true;
+    }
     if (this.switcherOpen) {
       return this._handleSwitcherInput(data);
     }
@@ -52,7 +55,16 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
   }
 
   private _isNonTextGraphControlBeforePrompt(data: string): boolean {
-    return this._mouseWheelDelta(data) !== null || matchesKey(data, Key.ctrl("d"));
+    return this._mouseWheelDelta(data) !== null;
+  }
+
+  private _isReturnToMainChatInput(data: string): boolean {
+    return matchesKey(data, Key.ctrl("x"));
+  }
+
+  private _returnToMainChat(): void {
+    if (this.onDetach) this.onDetach();
+    else this.onHide?.();
   }
 
   private _handlePromptInput(data: string): boolean {
@@ -138,27 +150,6 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
       this._activateFocusedNode();
       return true;
     }
-    // `ctrl+d` detaches the whole popup (host hides the overlay). This
-    // is the graph-mode counterpart of the in-chat back affordance.
-    if (matchesKey(data, Key.ctrl("d"))) {
-      if (this.onDetach) {
-        this.onDetach();
-      } else if (this.onHide) {
-        this.onHide();
-      }
-      return true;
-    }
-    // `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();
-      if (run && run.endedAt === undefined && this.onQuit) {
-        this.onQuit(run.id);
-      }
-      this.onClose?.();
-      return true;
-    }
     if (matchesKey(data, "h") && this.onHide) {
       this.onHide();
       return true;
@@ -336,52 +327,23 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
     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 };
+    const event = parseTerminalMouseInput(data);
+    if (!event || event.protocol !== "sgr" || !isTerminalLeftMousePress(event)) return null;
+    return { col: event.col, row: event.row };
   }
 
   private _mouseWheelDelta(data: string): MouseWheelDelta | null {
-    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);
-    }
+    const event = parseTerminalMouseInput(data);
+    if (!event) return null;
+    const direction = terminalMouseWheelDirection(event);
+    if (direction === "up") return { cols: 0, rows: -GRAPH_SCROLL_STEP_ROWS };
+    if (direction === "down") return { cols: 0, rows: GRAPH_SCROLL_STEP_ROWS };
+    if (direction === "left") return { cols: -GRAPH_SCROLL_STEP_COLS, rows: 0 };
+    if (direction === "right") return { cols: GRAPH_SCROLL_STEP_COLS, rows: 0 };
     return null;
   }
 
-  private _wheelDeltaForButtonCode(code: number): MouseWheelDelta | null {
-    if ((code & 64) === 0) return null;
-    const direction = code & 3;
-    if (direction === 0) return { cols: 0, rows: -GRAPH_SCROLL_STEP_ROWS };
-    if (direction === 1) return { cols: 0, rows: GRAPH_SCROLL_STEP_ROWS };
-    if (direction === 2) return { cols: -GRAPH_SCROLL_STEP_COLS, rows: 0 };
-    return { cols: GRAPH_SCROLL_STEP_COLS, rows: 0 };
-  }
-
   // ---- test seams ----
   get _focusedIndex(): number {
     return this.focusedIndex;

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

@@ -1,5 +1,6 @@
 import { GraphCanvas } from "./graph-canvas.js";
 import {
+  COMPACT_HINT_KEYS,
   HINT_KEYS,
   MODE_PILL_LABEL,
   OVERLAY_LINE_COUNT,
@@ -105,22 +106,26 @@ export abstract class GraphViewRenderHelpers extends GraphViewState {
       bot,
       visibleWidth: pillW,
     } = renderOutlinePill(MODE_PILL_LABEL, t.accent, chromeBg);
-
-    // Hints — `<key> <label>` separated by `  ·  `. When other extensions
-    // publish status text (for example the async subagent widget), include it
-    // ahead of the controls so fullscreen workflow overlays do not hide it.
+    // Hints use `<key> <label>` segments. Keep the hierarchy transition first,
+    // followed by extension status and secondary graph controls, so width
+    // pressure never hides the way back to main chat.
     const sep = `${chromeBg}  ${dim}·${RESET}${chromeBg}  `;
+    const leftEdgePad = 1;
+    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
+      : COMPACT_HINT_KEYS;
     const statusText = this._externalStatusText();
     const statusSegment = statusText ? [`${accent}${statusText}${RESET}${chromeBg}`] : [];
-    const hintSegments = HINT_KEYS.map(
+    const hintSegments = hintKeys.map(
       ({ key, label }) =>
         `${text}${BOLD}${key}${RESET}${chromeBg} ${muted}${label}${RESET}${chromeBg}`,
     );
-    const hintsStyledRaw = [...statusSegment, ...hintSegments].join(sep);
-
-    const leftEdgePad = 1;
-    const rightEdgePad = 2;
-    const hintsBudget = Math.max(0, width - leftEdgePad - pillW - rightEdgePad);
+    const hintsStyledRaw = [hintSegments[0], ...statusSegment, ...hintSegments.slice(1)]
+      .filter((segment): segment is string => segment !== undefined)
+      .join(sep);
     const hintsStyled = truncateToWidth(hintsStyledRaw, hintsBudget, "");
     const hintsVisibleLen = visibleWidth(hintsStyled);
     const fillerVisible = Math.max(0, hintsBudget - hintsVisibleLen);