@bastani/atomic 0.9.13-alpha.1 → 0.9.13-alpha.2

package/dist/builtin/workflows/src/runs/foreground/executor-exit-manager.ts

@@ -127,7 +127,10 @@ export function createWorkflowExitManager(input: {
 			runWorkflowExitCleanups(selectedExit.reason);
 			throw selectedExit;
 		};
-		const rawOptions = options as Pick<WorkflowExitOptions, "status" | "reason" | "outputs"> | null | undefined;
+		const rawOptions = options as
+			| Pick<WorkflowExitOptions, "status" | "reason" | "resumable" | "outputs">
+			| null
+			| undefined;
 		let validationError: Error | undefined;
 		const captureValidationError = (error: Error): void => {
 			validationError ??= error;
@@ -141,7 +144,7 @@ export function createWorkflowExitManager(input: {
 		} else if (!isWorkflowExitStatus(rawStatus)) {
 			captureValidationError(
 				new TypeError(
-					`atomic-workflows: ctx.exit() status must be one of completed, skipped, cancelled, blocked; got ${describeWorkflowExitOptionValue(rawStatus)}`,
+					`atomic-workflows: ctx.exit() status must be one of completed, skipped, cancelled, blocked, failed; got ${describeWorkflowExitOptionValue(rawStatus)}`,
 				),
 			);
 		}
@@ -161,6 +164,26 @@ export function createWorkflowExitManager(input: {
 		}
 		const reason = typeof rawReason === "string" ? rawReason : undefined;
 
+		const resumableRead = readWorkflowExitOption(rawOptions, "resumable");
+		throwNestedSelectedExit();
+		const rawResumable = resumableRead.ok ? resumableRead.value : undefined;
+		if (!resumableRead.ok) {
+			captureValidationError(resumableRead.error);
+		} else if (rawResumable !== undefined && typeof rawResumable !== "boolean") {
+			captureValidationError(
+				new TypeError(
+					`atomic-workflows: ctx.exit() resumable must be a boolean when provided; got ${workflowSerializableTypeName(rawResumable)}`,
+				),
+			);
+		} else if (rawResumable !== undefined && rawStatus !== "failed") {
+			captureValidationError(
+				new TypeError(
+					`atomic-workflows: ctx.exit() resumable is only valid with status failed; got ${describeWorkflowExitOptionValue(rawStatus)}`,
+				),
+			);
+		}
+		const resumable = status === "failed" && rawResumable === true;
+
 		const outputsRead = readWorkflowExitOption(rawOptions, "outputs");
 		throwNestedSelectedExit();
 		const outputSnapshot = !outputsRead.ok
@@ -175,6 +198,7 @@ export function createWorkflowExitManager(input: {
 				scope: input.exitScope,
 				status,
 				...(reason !== undefined ? { reason } : {}),
+				...(status === "failed" ? { resumable } : {}),
 				...(outputSnapshot !== undefined ? { outputSnapshot } : {}),
 				...(validationError !== undefined ? { validationError } : {}),
 			}),

package/dist/builtin/workflows/src/runs/foreground/executor-run-finalizers.ts

@@ -81,8 +81,9 @@ export function createRunFinalizers(input: {
 			return finalizeWorkflowExitValidationFailure(err, signal.reason);
 		}
 
+		const resumable = signal.status === "failed" && signal.resumable === true;
 		const metadata = {
-			resumable: false,
+			resumable,
 			exited: true,
 			...(signal.reason !== undefined ? { exitReason: signal.reason } : {}),
 		} as const;
@@ -93,7 +94,7 @@ export function createRunFinalizers(input: {
 			result: outputs,
 			exited: true,
 			...(signal.reason !== undefined ? { exitReason: signal.reason } : {}),
-			resumable: false,
+			resumable,
 			ts: Date.now(),
 		});
 		return reconcileTerminalRunResult(

package/dist/builtin/workflows/src/runs/shared/worktree-git-runner.ts

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { createGitEnvironment } from "@bastani/atomic";
+import { createChildProcessEnvironment, createGitEnvironment } from "@bastani/atomic";
 import type { GitResult } from "./worktree-types.js";
 
 const DISABLED_GIT_HOOKS_PATH = process.platform === "win32" ? "NUL" : "/dev/null";
@@ -27,7 +27,10 @@ function spawnGit(cwd: string, args: readonly string[], plain: boolean): GitResu
 	const result = spawnSync("git", plain ? args : gitCommandArgs(args), {
 		cwd,
 		encoding: "utf-8",
-		env: createGitEnvironment({ GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0", GCM_INTERACTIVE: "never" }),
+		env: createGitEnvironment(
+			{ GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0", GCM_INTERACTIVE: "never" },
+			createChildProcessEnvironment(),
+		),
 		timeout: GIT_COMMAND_TIMEOUT_MS,
 	});
 	return {

package/dist/builtin/workflows/src/runs/shared/worktree-setup.ts

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { createChildProcessEnvironment } from "@bastani/atomic";
 import { runGit, runGitChecked } from "./worktree-git.js";
 import { performPostCreationSetup } from "./worktree-post-create.js";
 import { findCanonicalGitRoot } from "./worktree-root.js";
@@ -219,6 +220,7 @@ function runWorktreeSetupHook(hook: ResolvedWorktreeSetupHook, input: WorktreeSe
 		cwd: input.worktreePath,
 		encoding: "utf-8",
 		input: JSON.stringify(input),
+		env: createChildProcessEnvironment(),
 		timeout: hook.timeoutMs,
 		shell: false,
 	});

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

@@ -22,15 +22,15 @@ export type WorkflowOutputMode = "inline" | "file-only";
 export type WorkflowContextMode = "fresh" | "fork";
 export type WorkflowThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 export type WorkflowExecutionMode = "interactive" | "non_interactive";
-export type WorkflowExitStatus = "completed" | "skipped" | "cancelled" | "blocked";
-export type RunStatus = "pending" | "running" | "paused" | WorkflowExitStatus | "failed" | "killed";
+export type WorkflowExitStatus = "completed" | "skipped" | "cancelled" | "blocked" | "failed";
+export type RunStatus = "pending" | "running" | "paused" | WorkflowExitStatus | "killed";
 /**
  * Who performed a workflow lifecycle action. Mirrors the store-side union; the
  * authoring contract keeps its own copy so it stays independent of store types.
  */
 export type WorkflowActor = "user" | "agent";
 export type WorkflowDetailsMode = "named" | "inspection" | "control";
-export type WorkflowDetailsStatus = "accepted" | "running" | WorkflowExitStatus | "failed" | "killed" | "noop";
+export type WorkflowDetailsStatus = "accepted" | "running" | WorkflowExitStatus | "killed" | "noop";
 export type WorkflowAction = "list" | "get" | "inputs" | "run" | "status" | "interrupt" | "resume";
 type WorkflowExitOutputValues<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> = [keyof TOutputs] extends [
     never
@@ -38,6 +38,8 @@ type WorkflowExitOutputValues<TOutputs extends WorkflowOutputValues = WorkflowOu
 export interface WorkflowExitOptions<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> {
     readonly status?: WorkflowExitStatus;
     readonly reason?: string;
+    /** Failed exits are non-resumable by default; set this only when retry is intended. */
+    readonly resumable?: boolean;
     readonly outputs?: WorkflowExitOutputValues<TOutputs>;
 }
 export interface WorkflowModelFallbackFields {

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

@@ -31,8 +31,8 @@ export type WorkflowOutputMode = "inline" | "file-only";
 export type WorkflowContextMode = "fresh" | "fork";
 export type WorkflowThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 export type WorkflowExecutionMode = "interactive" | "non_interactive";
-export type WorkflowExitStatus = "completed" | "skipped" | "cancelled" | "blocked";
-export type RunStatus = "pending" | "running" | "paused" | WorkflowExitStatus | "failed" | "killed";
+export type WorkflowExitStatus = "completed" | "skipped" | "cancelled" | "blocked" | "failed";
+export type RunStatus = "pending" | "running" | "paused" | WorkflowExitStatus | "killed";
 
 /**
  * Who performed a workflow lifecycle action. Mirrors the store-side union; the
@@ -40,7 +40,7 @@ export type RunStatus = "pending" | "running" | "paused" | WorkflowExitStatus |
  */
 export type WorkflowActor = "user" | "agent";
 export type WorkflowDetailsMode = "named" | "inspection" | "control";
-export type WorkflowDetailsStatus = "accepted" | "running" | WorkflowExitStatus | "failed" | "killed" | "noop";
+export type WorkflowDetailsStatus = "accepted" | "running" | WorkflowExitStatus | "killed" | "noop";
 export type WorkflowAction = "list" | "get" | "inputs" | "run" | "status" | "interrupt" | "resume";
 
 type WorkflowExitOutputValues<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> = [keyof TOutputs] extends [
@@ -52,6 +52,8 @@ type WorkflowExitOutputValues<TOutputs extends WorkflowOutputValues = WorkflowOu
 export interface WorkflowExitOptions<TOutputs extends WorkflowOutputValues = WorkflowOutputValues> {
 	readonly status?: WorkflowExitStatus;
 	readonly reason?: string;
+	/** Failed exits are non-resumable by default; set this only when retry is intended. */
+	readonly resumable?: boolean;
 	readonly outputs?: WorkflowExitOutputValues<TOutputs>;
 }
 

package/dist/builtin/workflows/src/shared/graph-store-snapshot.ts

@@ -13,6 +13,7 @@ import type {
 import type { WorkflowOutputValues, WorkflowSerializableValue } from "./types.js";
 
 export const COMPACT_RESULT_FIELD_LIMIT = 1024;
+const COMPACT_EXIT_OUTPUT_LIMIT = COMPACT_RESULT_FIELD_LIMIT * 4;
 
 function compactResultField(value: WorkflowSerializableValue | undefined): string | undefined {
 	if (typeof value !== "string") return undefined;
@@ -22,7 +23,10 @@ function compactResultField(value: WorkflowSerializableValue | undefined): strin
 	return flattenTruncatedString(value.slice(0, COMPACT_RESULT_FIELD_LIMIT));
 }
 
-function compactRunResult(result: WorkflowOutputValues | undefined): WorkflowOutputValues | undefined {
+function compactRunResult(
+	result: WorkflowOutputValues | undefined,
+	preserveExitedOutputs = false,
+): WorkflowOutputValues | undefined {
 	if (result === undefined) return undefined;
 	const status = compactResultField(result.status);
 	const summary = compactResultField(result.summary);
@@ -34,9 +38,37 @@ function compactRunResult(result: WorkflowOutputValues | undefined): WorkflowOut
 		...(remainingWork !== undefined ? { remaining_work: remainingWork } : {}),
 		...(resultText !== undefined ? { result: resultText } : {}),
 	};
+	if (!preserveExitedOutputs) return Object.keys(compact).length === 0 ? undefined : compact;
+	return compactExitedOutputs(result, compact);
+}
+
+function compactExitedOutputs(
+	result: WorkflowOutputValues,
+	compact: WorkflowOutputValues,
+): WorkflowOutputValues | undefined {
+	try {
+		const serialized = JSON.stringify(result);
+		if (serialized !== undefined && serialized.length <= COMPACT_EXIT_OUTPUT_LIMIT) {
+			const parsed: unknown = JSON.parse(serialized);
+			if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+				return compactExitedObject(parsed as Record<string, WorkflowSerializableValue>);
+			}
+		}
+	} catch {
+		// Fall through to the bounded legacy fields below.
+	}
 	return Object.keys(compact).length === 0 ? undefined : compact;
 }
 
+function compactExitedObject(result: Record<string, WorkflowSerializableValue>): WorkflowOutputValues | undefined {
+	const compacted = { ...result };
+	for (const key of ["status", "summary", "remaining_work", "result"]) {
+		const value = compacted[key];
+		if (typeof value === "string") compacted[key] = compactResultField(value) ?? "";
+	}
+	return Object.keys(compacted).length === 0 ? undefined : compacted;
+}
+
 // Both cloners are called only from a `!== undefined` guard at their call sites,
 // so they take and return a concrete value; an internal undefined branch here
 // would be unreachable and would only weaken the type for every caller.
@@ -106,7 +138,7 @@ function compactToolNode(node: ToolNodeSnapshot): ToolNodeSnapshot {
 
 function compactRun(run: RunSnapshot): RunSnapshot {
 	const { inputs: _inputs, result: sourceResult, stages, toolNodes, pendingPrompt, ...metadata } = run;
-	const result = compactRunResult(sourceResult);
+	const result = compactRunResult(sourceResult, run.exited === true && run.status === "failed");
 	return {
 		...metadata,
 		inputs: {},

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

@@ -190,7 +190,13 @@ export function serializableObjectOrEmpty(value: unknown): WorkflowOutputValues
 }
 
 function isWorkflowChildReplayStatus(status: unknown): status is WorkflowExitStatus {
-	return status === "completed" || status === "skipped" || status === "cancelled" || status === "blocked";
+	return (
+		status === "completed" ||
+		status === "skipped" ||
+		status === "cancelled" ||
+		status === "blocked" ||
+		status === "failed"
+	);
 }
 
 function workflowChildMetadata(payload: Record<string, unknown>): Pick<StageSnapshot, "workflowChild"> {
@@ -235,9 +241,11 @@ function workflowChildMetadata(payload: Record<string, unknown>): Pick<StageSnap
 			status,
 			...(typeof exited === "boolean"
 				? { exited }
-				: status !== "completed" || typeof exitReason === "string"
-					? { exited: true }
-					: {}),
+				: status === "failed"
+					? {}
+					: status !== "completed" || typeof exitReason === "string"
+						? { exited: true }
+						: {}),
 			outputs: clonedOutputs,
 			...(typeof exitReason === "string" ? { exitReason } : {}),
 		},
@@ -388,8 +396,11 @@ export function restoreTerminalRuns(entries: readonly SessionEntry[], store: Sto
 		const resumable = end.resumable;
 		const failedToolNodeId = end.failedToolNodeId;
 		const failedToolNode = restoreFailedToolNode(end.failedToolNode);
+		// Failed is both an author-exit status and the engine's ordinary failure
+		// status, so an exit reason alone cannot establish author intent.
 		const restoredAuthorExit =
-			isWorkflowExitTerminalStatus(status) && (exited === true || typeof exitReason === "string");
+			isWorkflowExitTerminalStatus(status) &&
+			(exited === true || (status !== "failed" && typeof exitReason === "string"));
 		if (status === "completed" && !restoredAuthorExit && stages.some((stage) => stage.status !== "completed"))
 			continue;
 		store.recordRunStart({
@@ -456,7 +467,13 @@ export function restoreTerminalRuns(entries: readonly SessionEntry[], store: Sto
 }
 
 function isWorkflowExitTerminalStatus(status: RunStatus): status is WorkflowExitStatus {
-	return status === "completed" || status === "skipped" || status === "cancelled" || status === "blocked";
+	return (
+		status === "completed" ||
+		status === "skipped" ||
+		status === "cancelled" ||
+		status === "blocked" ||
+		status === "failed"
+	);
 }
 
 function restoreTerminalRunStatus(status: unknown): RunStatus | undefined {

package/dist/builtin/workflows/src/shared/stage-ui-broker.ts

@@ -1,6 +1,12 @@
 import { randomUUID } from "node:crypto";
 import type { Component, Focusable, TUI } from "@earendil-works/pi-tui";
-import type { PiCustomOverlayFactory, PiCustomOverlayOptions, PiKeybindings, PiTheme } from "../extension/wiring.js";
+import type {
+	PiCustomComponent,
+	PiCustomOverlayFactory,
+	PiCustomOverlayOptions,
+	PiKeybindings,
+	PiTheme,
+} from "../extension/wiring.js";
 import type { StageInputAnswer, StagePromptAdapter } from "./stage-prompt.js";
 import type { StagePromptAnswerSource, Store } from "./store.js";
 import { store as defaultStore } from "./store.js";
@@ -280,7 +286,7 @@ export class StageUiBroker {
 
 export interface MountedStageCustomUi {
 	readonly request: StageCustomUiRequest;
-	readonly component: Component & { dispose?(): void };
+	readonly component: PiCustomComponent & { invalidate(): void; dispose?(): void } & Partial<Focusable>;
 }
 
 export async function mountStageCustomUi(
@@ -302,10 +308,10 @@ export async function mountStageCustomUi(
 			onDone?.();
 		},
 	);
-	const component: Component & { dispose?(): void } & Partial<Focusable> = {
+	const component: PiCustomComponent & { invalidate(): void; dispose?(): void } & Partial<Focusable> = {
 		render: (width) => rawComponent.render(width),
 		...(rawComponent.handleInput !== undefined
-			? { handleInput: (data: string) => rawComponent.handleInput?.(data) }
+			? { handleInput: (data: string): boolean => rawComponent.handleInput?.(data) === true }
 			: {}),
 		invalidate: () => rawComponent.invalidate?.(),
 		...(rawComponent.dispose !== undefined ? { dispose: () => rawComponent.dispose?.() } : {}),

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

@@ -117,7 +117,7 @@ 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 | skipped | cancelled | blocked).
-	 * `result` is applied for intentional success/exit statuses (completed | skipped | cancelled | blocked)
+	 * `result` is applied for intentional success/exit statuses (completed | skipped | cancelled | blocked | failed)
 	 * and for workflows that intentionally return a failed status with structured outputs.
 	 * `error` is applied for status "failed" | "killed" | "blocked".
 	 */
@@ -265,7 +265,9 @@ export interface Store {
 	clear(): void;
 	snapshot(): StoreSnapshot;
 	/**
-	 * Return one immutable payload-free graph projection per store version.
+	 * Return one immutable payload-bounded graph projection per store version.
+	 * Authored failed-exit results may retain bounded JSON output values; all
+	 * other run payloads stay omitted or compacted to bounded diagnostic fields.
 	 * Graph-visible state may change only through a version-bumping store method;
 	 * direct mutation of values returned by `runs()` would leave this cache stale.
 	 */

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

@@ -5,7 +5,7 @@
 
 import type { WorkflowExitStatus, WorkflowInputValues, WorkflowOutputValues } from "./types.js";
 
-export type RunStatus = "pending" | "running" | "paused" | WorkflowExitStatus | "failed" | "killed";
+export type RunStatus = "pending" | "running" | "paused" | WorkflowExitStatus | "killed";
 export type StageStatus =
 	| "pending"
 	| "running"

package/dist/builtin/workflows/src/shared/workflow-artifact-env.ts

@@ -0,0 +1,21 @@
+/**
+ * Leaf module: durable workflow-artifact constants with no imports.
+ *
+ * These values are plain data, but their previous home — `workflow-artifacts.ts`
+ * — sits atop roughly fifty modules including `@bastani/atomic` itself. Any
+ * consumer that wanted only a constant paid to transform that whole graph.
+ *
+ * `test/setup-workflow-durability.ts` is such a consumer, and vitest runs it
+ * once per test file, so every unit file transformed ten thousand lines to read
+ * one string. Keeping these constants importable without dependencies is what
+ * lets that setup stay cheap; `workflow-artifacts.ts` re-exports them, so this
+ * split is invisible to every existing caller.
+ *
+ * Keep this module dependency-free.
+ */
+
+/** Maximum age of durable workflow run artifacts before the next workflow write prunes them. */
+export const WORKFLOW_ARTIFACT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** Overrides the durable workflow-artifact root, mirroring the agent-directory override convention. */
+export const ENV_WORKFLOW_ARTIFACT_DIR = "ATOMIC_WORKFLOW_ARTIFACT_DIR";

package/dist/builtin/workflows/src/shared/workflow-artifacts.ts

@@ -8,12 +8,9 @@ import { getDurableBackend } from "../durable/factory.js";
 import { type WorkflowRunResumeCandidate, workflowRunHasPausedState } from "../durable/resume-eligibility.js";
 import { store } from "./store.js";
 import type { RunSnapshot } from "./store-types.js";
+import { ENV_WORKFLOW_ARTIFACT_DIR, WORKFLOW_ARTIFACT_RETENTION_MS } from "./workflow-artifact-env.js";
 
-/** Maximum age of durable workflow run artifacts before the next workflow write prunes them. */
-export const WORKFLOW_ARTIFACT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
-
-/** Overrides the durable workflow-artifact root, mirroring the agent-directory override convention. */
-export const ENV_WORKFLOW_ARTIFACT_DIR = "ATOMIC_WORKFLOW_ARTIFACT_DIR";
+export { ENV_WORKFLOW_ARTIFACT_DIR, WORKFLOW_ARTIFACT_RETENTION_MS };
 
 export type WorkflowArtifactRunState = "protected" | "terminal" | "orphan";
 export type WorkflowArtifactRunStateResolver = (runId: string) => WorkflowArtifactRunState | undefined;

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

@@ -273,11 +273,45 @@ function renderInputsSegment(
 	};
 }
 
+/**
+ * Anything that would break a value out of its single card row.
+ *
+ * Card rows are spliced into a bordered box by `renderRoundedBox`, which pads
+ * each row to the interior width. A value carrying a literal newline emits a
+ * second physical line that no border ever wraps, destroying the box from that
+ * row down. `truncateToWidth` cannot save us: it measures *visible width*, and
+ * a control character has none, so a `\n` survives truncation intact.
+ *
+ * This is reachable from ordinary use — any multi-line workflow input (a
+ * `prompt`, an `acceptance_criteria` block) contains newlines by nature.
+ *
+ * Scoped to `\p{Cc}` (C0/C1 controls, so `\n`, `\r`, `\t`, and a stray ESC that
+ * would otherwise inject styling) plus the two separators `JSON.stringify` does
+ * *not* escape, which some terminals still break lines on. It deliberately does
+ * NOT cover all of `\p{Cf}`: that class includes U+200D ZERO WIDTH JOINER, and
+ * stripping it splits emoji sequences such as a family glyph into their
+ * components. A format character that occupies no cell cannot break a row, so
+ * removing it only corrupts the value the user asked to see.
+ */
+const ROW_BREAKING_RE = /[\p{Cc}\u2028\u2029]+/gu;
+
+/**
+ * Replace runs of row-breaking characters with a single space.
+ *
+ * Only the replaced runs collapse. Pre-existing spacing is left alone and the
+ * result is not trimmed, because a value's own leading, trailing, or repeated
+ * spaces are content: the card renders inside quotes, so `"  alpha   beta  "`
+ * should still read as what was passed rather than as `"alpha beta"`.
+ */
+function toSingleLine(value: string): string {
+	return value.replace(ROW_BREAKING_RE, " ");
+}
+
 function renderInputValue(value: unknown, budget: number): string {
 	if (typeof value === "string") {
 		// Reserve 2 cells for the surrounding quotes; truncate the interior.
 		const interior = Math.max(0, budget - 2);
-		const trimmed = truncateToWidth(value, interior, ELLIPSIS);
+		const trimmed = truncateToWidth(toSingleLine(value), interior, ELLIPSIS);
 		return `"${trimmed}"`;
 	}
 	if (typeof value === "number" || typeof value === "boolean") {
@@ -285,8 +319,9 @@ function renderInputValue(value: unknown, budget: number): string {
 	}
 	if (value === null) return "null";
 	// Objects / arrays — show a compact JSON projection within budget.
+	// JSON.stringify escapes \n as literal backslash-n, but not U+2028/U+2029.
 	const json = JSON.stringify(value);
-	return truncateToWidth(json ?? "", budget, ELLIPSIS);
+	return truncateToWidth(toSingleLine(json ?? ""), budget, ELLIPSIS);
 }
 
 /**

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

@@ -17,20 +17,6 @@ export const COMPACT_HINT_KEYS: Array<{ key: string; label: string }> = [
  */
 export const MODE_PILL_LABEL = "GRAPH";
 
-/**
- * Fixed line count emitted by `_renderOverlay`. pi-tui paints the
- * overlay in the same buffer as the chat, so a *variable* line count
- * causes the chat to scroll every time the focused-stage section grows
- * or shrinks — that's exactly the duplicate-rows bug we hit when
- * navigating with j/k. Padding to a constant height keeps the overlay
- * a stable rectangle that pi-tui can diff cell-by-cell.
- *
- * Mirrors the doom-overlay reference extension, which always emits the
- * same number of lines per frame regardless of game state.
- */
-export const OVERLAY_LINE_COUNT = 32;
-export const OVERLAY_VERTICAL_MARGIN_ROWS = 1;
-
 /**
  * Animation tick period. Overlay re-renders fire on this cadence so
  * duration counters tick from active elapsed time (freezing while paused)
@@ -50,4 +36,3 @@ export const ANIMATION_TICK_MS = 100;
  */
 export const PULSE_PERIOD_MS = 2000;
 export const GRAPH_SCROLL_STEP_COLS = 4;
-export const GRAPH_SCROLL_STEP_ROWS = 4;

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

@@ -1,3 +1,4 @@
+import type { RunSnapshot } from "../shared/store-types.js";
 import { hexBg, hexToAnsi, RESET } from "./color-utils.js";
 import { GraphCanvas } from "./graph-canvas.js";
 import { PULSE_PERIOD_MS } from "./graph-view-constants.js";
@@ -11,46 +12,51 @@ interface Placement {
 	line: string;
 }
 
-/** Graph body rendering and vertical/horizontal viewport management. */
+/** Graph body rendering and horizontal canvas management. */
 export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
-	protected _renderGraph(width: number): string[] {
-		const run = this._getCurrentRun();
+	protected _renderGraph(
+		width: number,
+		viewportTop: number,
+		viewportRows: number,
+		renderRun?: RunSnapshot | null,
+	): string[] {
+		const safeRows = Math.max(0, Math.floor(viewportRows));
+		const run = renderRun !== undefined ? renderRun : this._getCurrentRun();
 		if (!run || this.cachedLayout.length === 0) {
 			this.lastGraphViewport = null;
 			this.graphNodeHitRects = [];
-			this.lastGraphTotalRows = 1;
-			const dim = hexToAnsi(this.graphTheme.dim);
-			return [this._centerCanvasContent(`${dim}waiting for stage events…${RESET}`, width)];
+			this.lastGraphTopPad = 0;
+			this.lastGraphVisibleRows = safeRows;
+			const lines = Array.from({ length: safeRows }, () => "");
+			if (safeRows > 0) {
+				const dim = hexToAnsi(this.graphTheme.dim);
+				lines[Math.floor((safeRows - 1) / 2)] = this._centerCanvasContent(
+					`${dim}waiting for stage events…${RESET}`,
+					width,
+				);
+			}
+			return lines;
 		}
 
 		const graphInner = Math.max(1, width - 4);
 		const { canvasWidth, totalRows, bands, edges } = this.cachedRenderGeometry;
-		this.lastGraphTotalRows = totalRows;
 		const leftMargin = Math.max(2, canvasWidth <= graphInner ? Math.floor((graphInner - canvasWidth) / 2) : 2);
 		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);
-		}
-
-		const bodyRows = this._overlayBodyRows(this._overlayPanelLineCount());
-		if (totalRows > bodyRows) {
-			this._clampGraphScroll(totalRows, bodyRows);
-			if (this.pendingEnsureFocusedVisible) this._scrollFocusedIntoView(width, bodyRows, totalRows);
-			this._clampGraphScroll(totalRows, bodyRows);
-		} else {
-			this.graphScrollOffset = 0;
-		}
 
-		const viewportTop = this.graphScrollOffset;
-		const viewportBottom = Math.min(totalRows, viewportTop + bodyRows);
+		const safeTop = Math.max(0, Math.min(totalRows, Math.floor(viewportTop)));
+		const graphRows = Math.max(0, Math.min(safeRows, totalRows - safeTop));
+		const viewportBottom = safeTop + graphRows;
+		this._clampGraphHorizontalScroll(fullCanvasWidth, viewportWidth);
+		const topPad = safeTop === 0 && totalRows <= safeRows ? Math.min(3, Math.floor((safeRows - totalRows) / 2)) : 0;
+		this.lastGraphTopPad = topPad;
+		this.lastGraphVisibleRows = graphRows;
 		const viewportLeft = this.graphScrollColOffset;
 		const viewportRight = viewportLeft + viewportWidth;
 		const pulsePhase = (Date.now() % PULSE_PERIOD_MS) / PULSE_PERIOD_MS;
 		const edgeCanvas = new GraphCanvas({
-			top: viewportTop,
+			top: safeTop,
 			bottom: viewportBottom,
 			left: viewportLeft,
 			right: viewportRight,
@@ -58,7 +64,7 @@ export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
 		const edgeColor = this.graphTheme.borderDim;
 		for (const edge of edges) {
 			if (
-				edge.bottom <= viewportTop ||
+				edge.bottom <= safeTop ||
 				edge.top >= viewportBottom ||
 				edge.right <= viewportLeft ||
 				edge.left >= viewportRight
@@ -69,7 +75,7 @@ export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
 		}
 		const edgeLines = edgeCanvas.toLines();
 		const placements = new Map<number, Placement[]>();
-		for (let bandIndex = this._firstVisibleLayoutBand(viewportTop); bandIndex < bands.length; bandIndex++) {
+		for (let bandIndex = this._firstVisibleLayoutBand(safeTop); bandIndex < bands.length; bandIndex++) {
 			const band = bands[bandIndex]!;
 			if (band.top >= viewportBottom) break;
 			for (const ni of band.nodeIndices) {
@@ -88,8 +94,8 @@ export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
 				const visibleRight = Math.min(node.x + NODE_W, viewportRight);
 				for (let li = 0; li < cardLines.length; li++) {
 					const globalRow = node.y + li;
-					if (globalRow < viewportTop || globalRow >= viewportBottom) continue;
-					const localRow = globalRow - viewportTop;
+					if (globalRow < safeTop || globalRow >= viewportBottom) continue;
+					const localRow = globalRow - safeTop;
 					let bucket = placements.get(localRow);
 					if (!bucket) {
 						bucket = [];
@@ -106,10 +112,10 @@ export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
 
 		const bg = hexBg(this.graphTheme.bg);
 		const leftPad = `${bg}${" ".repeat(leftMargin)}${RESET}`;
-		const composed: string[] = [];
-		for (let localRow = 0; localRow < viewportBottom - viewportTop; localRow++) {
+		const composed = Array.from({ length: safeRows }, () => "");
+		for (let localRow = 0; localRow < graphRows; localRow++) {
 			const line = this._composeRow(edgeLines[localRow] ?? "", placements.get(localRow) ?? [], edgeColor);
-			composed.push(`${leftPad}${this._padCanvas(line, viewportWidth)}`);
+			composed[topPad + localRow] = `${leftPad}${this._padCanvas(line, viewportWidth)}`;
 		}
 		return composed;
 	}
@@ -126,8 +132,8 @@ export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
 		const viewportLeft = viewport.leftMargin;
 		const viewportRight = viewport.leftMargin + viewport.viewportWidth;
 		const rects: typeof this.graphNodeHitRects = [];
-		const viewportTop = this.graphScrollOffset;
-		const viewportBottom = viewportTop + visibleRowCount;
+		const viewportTop = this._graphScrollTop();
+		const viewportBottom = Math.min(this.cachedRenderGeometry.totalRows, viewportTop + visibleRowCount);
 		const { bands } = this.cachedRenderGeometry;
 		for (let bandIndex = this._firstVisibleLayoutBand(viewportTop); bandIndex < bands.length; bandIndex++) {
 			const band = bands[bandIndex]!;
@@ -148,19 +154,4 @@ export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
 		}
 		this.graphNodeHitRects = rects;
 	}
-
-	protected _visibleGraphLines(
-		graphLines: string[],
-		_frameWidth: number,
-		bodyRows: number,
-	): { lines: string[]; topPad: number } {
-		this.pendingEnsureFocusedVisible = false;
-		return {
-			lines: graphLines,
-			topPad:
-				this.lastGraphTotalRows <= bodyRows
-					? Math.min(3, Math.max(0, Math.floor((bodyRows - this.lastGraphTotalRows) / 2)))
-					: 0,
-		};
-	}
 }