@iowarp/clio-coder 0.3.7 → 0.3.9

package/src/interactive/render-trace.ts

@@ -1,6 +1,6 @@
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { appendFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 import type { TuiRenderObserver, TuiRenderPhase } from "../engine/tui.js";
 
 /** The trace format is append-only JSONL so partial sessions remain readable. */
@@ -106,6 +106,106 @@ export type RenderTraceRecord =
 	  }
 	| { type: "trace_drop"; version: typeof RENDER_TRACE_VERSION; at: number; records: number };
 
+/** One byte-level delivery from the stdin reader to the application listener. */
+export type RenderTraceInputIngressRecord = Extract<RenderTraceRecord, { type: "input_ingress" }>;
+
+/**
+ * How many `input_ingress` records and how many committed frame records the
+ * always-on ring keeps, each. 256 keystrokes and 256 committed frames cover the
+ * last stretch of interaction an operator would still be describing when they
+ * kill a wedged pane, and cost about 200 KB of process memory in the worst case
+ * (a frame record carries its terminal-write commits).
+ */
+export const INPUT_WEDGE_RING_CAPACITY = 256;
+
+/** Subdirectory of the state directory that holds SIGTERM wedge dumps. */
+export const INPUT_WEDGE_DUMP_DIRNAME = "input-wedge";
+
+/** Dumps kept in that directory; older ones are removed as new ones land. */
+export const INPUT_WEDGE_DUMP_RETAINED = 5;
+
+/**
+ * Which half of the input pipeline was still moving when the dump was taken.
+ *
+ * `input-not-committed` is the consumer's failure: bytes reached the
+ * application listener and no frame that carries them ever reached stdout.
+ * `no-input-recorded` is the reader's: nothing was delivered at all, so an
+ * operator who was typing was typing into a reader that had stopped.
+ * `input-committed` says neither half of this pipeline was stuck.
+ */
+export type InputWedgeClassification = "no-input-recorded" | "input-not-committed" | "input-committed";
+
+export interface InputWedgeSnapshot {
+	version: typeof RENDER_TRACE_VERSION;
+	capacity: number;
+	pid: number;
+	/** Wall clock at trace open, so a record's relative `at` maps onto real time. */
+	openedAtEpochMs: number;
+	atEpochMs: number;
+	/** Milliseconds since trace open, the same clock every record's `at` uses. */
+	at: number;
+	classification: InputWedgeClassification;
+	msSinceLastInputIngress: number | null;
+	msSinceLastCommittedFrame: number | null;
+	inputIngress: RenderTraceInputIngressRecord[];
+	frames: RenderTraceFrameRecord[];
+}
+
+/** Bounded FIFO that overwrites its oldest entry rather than growing. */
+function createRing<T>(capacity: number): { push(value: T): void; toArray(): T[] } {
+	const slots: T[] = [];
+	let next = 0;
+	return {
+		push(value): void {
+			if (slots.length < capacity) slots.push(value);
+			else slots[next] = value;
+			next = (next + 1) % capacity;
+		},
+		toArray(): T[] {
+			if (slots.length < capacity) return [...slots];
+			return [...slots.slice(next), ...slots.slice(0, next)];
+		},
+	};
+}
+
+/**
+ * Read the two rings the way the ticket asks the wedge to be read: the newest
+ * input the operator should have seen, against the newest frame that reached
+ * stdout carrying it.
+ */
+function classifyInputWedge(
+	inputIngress: ReadonlyArray<RenderTraceInputIngressRecord>,
+	frames: ReadonlyArray<RenderTraceFrameRecord>,
+): InputWedgeClassification {
+	const newest = [...inputIngress].reverse().find((record) => record.visualExpected) ?? inputIngress.at(-1);
+	if (newest === undefined) return "no-input-recorded";
+	return frames.some((frame) => frame.inputHighWater >= newest.inputSeq) ? "input-committed" : "input-not-committed";
+}
+
+/**
+ * Write one snapshot under `<stateDir>/input-wedge/`, newest-first by name, and
+ * drop everything past the retention bound. Synchronous on purpose: the caller
+ * is a signal handler on a process that is about to end.
+ */
+export function writeInputWedgeDump(stateDir: string, snapshot: InputWedgeSnapshot): string {
+	const directory = join(stateDir, INPUT_WEDGE_DUMP_DIRNAME);
+	mkdirSync(directory, { recursive: true });
+	const stamp = new Date(snapshot.atEpochMs).toISOString().replace(/[:.]/gu, "-");
+	const path = join(directory, `${stamp}-${snapshot.pid}.json`);
+	writeFileSync(path, `${JSON.stringify(snapshot, null, 2)}\n`, "utf8");
+	try {
+		const existing = readdirSync(directory)
+			.filter((name) => name.endsWith(".json"))
+			.sort();
+		for (const name of existing.slice(0, Math.max(0, existing.length - INPUT_WEDGE_DUMP_RETAINED))) {
+			rmSync(join(directory, name), { force: true });
+		}
+	} catch {
+		// Retention is housekeeping; a dump that landed is worth more than a tidy directory.
+	}
+	return path;
+}
+
 interface TraceWriter {
 	enqueue(record: RenderTraceRecord): void;
 	close(): Promise<void>;
@@ -236,6 +336,8 @@ export interface RenderTrace extends TuiRenderObserver {
 	recordTerminalDrain(writeId: number): void;
 	currentFrameId(): number | null;
 	onFirstFrameCommit(listener: (frameId: number) => void): void;
+	/** The always-on ring as it stands, classified. Allocates; call it once, on the way out. */
+	snapshotInputWedge(): InputWedgeSnapshot;
 	close(): Promise<void>;
 }
 
@@ -255,17 +357,32 @@ export function renderTracePath(env: NodeJS.ProcessEnv = process.env): string |
 	return raw && raw.length > 0 ? raw : null;
 }
 
+/**
+ * One tracer, two sinks. The JSONL file is the armed sink: it exists only when
+ * `CLIO_CODER_RENDER_TRACE` named a path, and it keeps every record. The
+ * bounded in-memory ring is the always-on sink: it keeps the last
+ * {@link INPUT_WEDGE_RING_CAPACITY} `input_ingress` records and the same number
+ * of committed frames, so the SIGTERM that recovers a wedged pane can still say
+ * which half of the input pipeline stopped (#224). A null `path` is the
+ * ring-only mode, and there the recorders that only ever fed the file keep
+ * their counters and skip building a record nothing would read.
+ */
 export function createRenderTrace(
-	path: string,
+	path: string | null,
 	now: () => number = () => performance.now(),
 	writerOptions: AsyncTraceWriterOptions = {},
 ): RenderTrace {
 	// Initialization happens before the terminal/TUI starts, never in a frame.
-	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, "", "utf8");
+	if (path !== null) {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, "", "utf8");
+	}
 	const openedAt = now();
+	const openedAtEpochMs = Date.now();
 	const at = (): number => rounded(now() - openedAt);
-	const writer = createAsyncTraceWriter(path, { ...writerOptions, recordTime: at });
+	const writer = path === null ? null : createAsyncTraceWriter(path, { ...writerOptions, recordTime: at });
+	const inputRing = createRing<RenderTraceInputIngressRecord>(INPUT_WEDGE_RING_CAPACITY);
+	const frameRing = createRing<RenderTraceFrameRecord>(INPUT_WEDGE_RING_CAPACITY);
 	let frameSeq = 0;
 	let writeSeq = 0;
 	let eventSeq = 0;
@@ -282,7 +399,7 @@ export function createRenderTrace(
 	const ranges = new Map<string, { codeUnits: number; graphemes: number }>();
 	const pendingDrains = new Map<number, { frameId: number | null; at: number }>();
 
-	writer.enqueue({ type: "trace_start", version: RENDER_TRACE_VERSION, at: 0 });
+	writer?.enqueue({ type: "trace_start", version: RENDER_TRACE_VERSION, at: 0 });
 
 	const trace: RenderTrace = {
 		recordPanelRender(metrics): void {
@@ -294,12 +411,15 @@ export function createRenderTrace(
 		},
 		recordVisibleEvent(fields): number {
 			eventSeq += 1;
+			// The ring keeps no provider deltas, so ring-only mode does not pay for
+			// grapheme segmentation on every token of every stream.
+			if (writer === null) return eventSeq;
 			const key = `${generation}:${fields.kind}:${fields.contentIndex}`;
 			const previous = ranges.get(key) ?? { codeUnits: 0, graphemes: 0 };
 			const graphemes = graphemeCount(fields.delta);
 			const next = { codeUnits: previous.codeUnits + fields.delta.length, graphemes: previous.graphemes + graphemes };
 			ranges.set(key, next);
-			writer.enqueue({
+			writer?.enqueue({
 				type: "event_ingress",
 				version: RENDER_TRACE_VERSION,
 				eventSeq,
@@ -317,7 +437,7 @@ export function createRenderTrace(
 		},
 		recordQueue(sequence, action): void {
 			queueDepth = Math.max(0, queueDepth + (action === "admit" ? 1 : -1));
-			writer.enqueue({
+			writer?.enqueue({
 				type: "queue",
 				version: RENDER_TRACE_VERSION,
 				eventSeq: sequence,
@@ -328,7 +448,7 @@ export function createRenderTrace(
 		},
 		recordPanelApplied(sequence): void {
 			panelHighWater = Math.max(panelHighWater, sequence);
-			writer.enqueue({
+			writer?.enqueue({
 				type: "panel",
 				version: RENDER_TRACE_VERSION,
 				eventSeq: sequence,
@@ -339,7 +459,7 @@ export function createRenderTrace(
 		recordInputIngress(action, bytes, visualExpected = action !== "no-visual-change"): number {
 			inputSeq += 1;
 			if (visualExpected) inputHighWater = inputSeq;
-			writer.enqueue({
+			const record: RenderTraceInputIngressRecord = {
 				type: "input_ingress",
 				version: RENDER_TRACE_VERSION,
 				inputSeq,
@@ -347,7 +467,9 @@ export function createRenderTrace(
 				at: at(),
 				bytes,
 				visualExpected,
-			});
+			};
+			inputRing.push(record);
+			writer?.enqueue(record);
 			return inputSeq;
 		},
 		beginFrame(fields): FrameState {
@@ -403,8 +525,11 @@ export function createRenderTrace(
 				},
 				commits: frame.commits,
 			};
-			writer.enqueue(record);
+			writer?.enqueue(record);
 			if (frame.commits.length > 0) {
+				// Only a frame that reached stdout answers the question the ring exists
+				// for, which is whether the consumer half is still painting.
+				frameRing.push(record);
 				lastCommitAt = frame.commits.at(-1)?.at ?? endAt;
 				if (!firstCommitDelivered) {
 					firstCommitDelivered = true;
@@ -439,6 +564,7 @@ export function createRenderTrace(
 				backpressured: !fields.returned,
 			};
 			currentFrame?.commits.push(commit);
+			if (writer === null) return writeSeq;
 			writer.enqueue({ type: "terminal_write", version: RENDER_TRACE_VERSION, frameId, ...commit });
 			if (!fields.returned) pendingDrains.set(writeSeq, { frameId, at: commit.at });
 			return writeSeq;
@@ -448,7 +574,7 @@ export function createRenderTrace(
 			if (!pending) return;
 			pendingDrains.delete(writeId);
 			const drainAt = at();
-			writer.enqueue({
+			writer?.enqueue({
 				type: "terminal_drain",
 				version: RENDER_TRACE_VERSION,
 				writeId,
@@ -461,7 +587,28 @@ export function createRenderTrace(
 		onFirstFrameCommit(listener): void {
 			firstCommitListener = listener;
 		},
-		close: () => writer.close(),
+		snapshotInputWedge(): InputWedgeSnapshot {
+			const inputIngress = inputRing.toArray();
+			const frames = frameRing.toArray();
+			const nowAt = at();
+			const lastIngressAt = inputIngress.at(-1)?.at;
+			const lastFrame = frames.at(-1);
+			const lastFrameCommitAt = lastFrame?.commits.at(-1)?.at ?? lastFrame?.endAt;
+			return {
+				version: RENDER_TRACE_VERSION,
+				capacity: INPUT_WEDGE_RING_CAPACITY,
+				pid: process.pid,
+				openedAtEpochMs,
+				atEpochMs: Date.now(),
+				at: nowAt,
+				classification: classifyInputWedge(inputIngress, frames),
+				msSinceLastInputIngress: lastIngressAt === undefined ? null : rounded(nowAt - lastIngressAt),
+				msSinceLastCommittedFrame: lastFrameCommitAt === undefined ? null : rounded(nowAt - lastFrameCommitAt),
+				inputIngress,
+				frames,
+			};
+		},
+		close: () => writer?.close() ?? Promise.resolve(),
 	};
 	return trace;
 }

package/src/interactive/renderers/tool-execution.ts

@@ -18,6 +18,7 @@ import { formatSize } from "../../engine/truncate.js";
 import { visibleWidth, wrapTextWithAnsi } from "../../engine/tui.js";
 import { classifyResourceRead, toolPresentationPolicy } from "../../tools/presentation.js";
 import { toolResultPresentationPolicy, toolResultPresentationText } from "../../tools/result-disposition.js";
+import { mutationFactsLine } from "../mutation-preview.js";
 import type { ApprovalRequestView } from "../permission-overlay.js";
 import { clioTheme, formatCompactMs, GLYPH } from "../theme/index.js";
 import { renderDiffLines } from "./diff.js";
@@ -490,6 +491,9 @@ export function renderToolAwaitingApproval(
 		["action", view.actionClass],
 		["axis", axis],
 		...(view.target !== undefined && view.target.length > 0 ? [["target", view.target]] : []),
+		// Size and digest, never the mutation text: this row is the transcript,
+		// which is written, replayed, and shared (issue #254).
+		...(view.mutation !== undefined ? [["mutation", mutationFactsLine(view.mutation)]] : []),
 	] as const;
 	for (const [label, value] of facts) {
 		lines.push(...indentAndWrap(`${dim(`${label} ·`)} ${value}`, width, false));

package/src/interactive/side-question.ts

@@ -13,7 +13,13 @@
  * machine without adding an engine seam of its own. Tools are never sent.
  */
 
+import {
+	isResponseSchemaRejection,
+	type ResponseSchemaDialect,
+	responseSchemaDialectFor,
+} from "../core/response-schema.js";
 import { stream } from "../engine/ai.js";
+import { patchResponseSchemaPayloadForDialect } from "../engine/provider-payload.js";
 import type { AgentMessage, EngineModel, Usage } from "../engine/types.js";
 
 /**
@@ -67,6 +73,18 @@ export interface OutOfTurnRoundInput extends Omit<SideQuestionInput, "question">
 	systemPrompt: string;
 	/** The one message appended to the read-only copy of the history. */
 	userText: string;
+	/**
+	 * Bind the answer to a JSON schema on the wire, where the runtime takes one.
+	 *
+	 * A round that asked for a schema in prose and bound nothing is what made
+	 * `/handoff` refuse on local targets: the model answered with prose around
+	 * the object, or with no object at all, and the parser had nothing to work
+	 * with (issue #223). Absent, or on a runtime with no dialect, the request
+	 * goes out exactly as before and the prompt-level instruction carries it.
+	 */
+	responseSchema?: { name: string; schema: Record<string, unknown> };
+	/** Resolved runtime id, which is what decides the wire dialect. */
+	runtimeId?: string;
 }
 
 export interface SideQuestionResult {
@@ -80,7 +98,12 @@ function positive(value: unknown): number {
 	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
 }
 
-function sideQuestionUsage(raw: unknown): SideQuestionUsage | null {
+/**
+ * Normalize one provider usage object into the shape `/cost` and the
+ * out-of-turn usage store take. Shared with the session pre-warm, which is
+ * another call billed beside the session rather than inside it.
+ */
+export function sideQuestionUsage(raw: unknown): SideQuestionUsage | null {
 	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
 	const usage = raw as Partial<Usage> & { reasoning?: number };
 	const input = positive(usage.input);
@@ -128,11 +151,45 @@ export async function runSideQuestion(input: SideQuestionInput): Promise<SideQue
 	return runOutOfTurnRound({ ...rest, systemPrompt: SIDE_QUESTION_SYSTEM_PROMPT, userText: question });
 }
 
+interface SchemaBinding {
+	dialect: ResponseSchemaDialect;
+	name: string;
+	schema: Record<string, unknown>;
+}
+
+/** The schema binding for this round, or null when nothing can be bound on the wire. */
+function schemaBindingFor(input: OutOfTurnRoundInput): SchemaBinding | null {
+	if (input.responseSchema === undefined || input.runtimeId === undefined) return null;
+	const dialect = responseSchemaDialectFor(input.runtimeId);
+	return dialect === null ? null : { dialect, ...input.responseSchema };
+}
+
 /** The shared round. See {@link OutOfTurnRoundInput}. */
 export async function runOutOfTurnRound(input: OutOfTurnRoundInput): Promise<SideQuestionResult> {
+	const binding = schemaBindingFor(input);
+	if (binding === null) return runRound(input, null);
+	try {
+		return await runRound(input, binding);
+	} catch (error) {
+		// Native enforcement is an optimization here, never a precondition. A
+		// server that refuses the constrained request answers with the same 400
+		// the worker seam already recognizes, and the round is worth more
+		// unconstrained than not at all. Anything else is a real failure and
+		// rejects, so a broken target still costs exactly one round.
+		if (input.signal?.aborted === true) throw error;
+		if (!isResponseSchemaRejection(error instanceof Error ? error.message : String(error))) throw error;
+		return runRound(input, null);
+	}
+}
+
+async function runRound(input: OutOfTurnRoundInput, binding: SchemaBinding | null): Promise<SideQuestionResult> {
 	const options: Record<string, unknown> = { maxTokens: input.maxTokens ?? SIDE_QUESTION_MAX_TOKENS };
 	if (input.apiKey !== undefined) options.apiKey = input.apiKey;
 	if (input.signal !== undefined) options.signal = input.signal;
+	if (binding !== null) {
+		options.onPayload = (payload: unknown): unknown | undefined =>
+			patchResponseSchemaPayloadForDialect(payload, binding.dialect, binding.schema, binding.name);
+	}
 
 	const context = {
 		systemPrompt: input.systemPrompt,

package/src/interactive/slash-commands.ts

@@ -6,9 +6,9 @@ import type { AgentSpec } from "../domains/agents/spec.js";
 import type { ContextInitOptions } from "../domains/context/init-options.js";
 import type { DispatchContract, DispatchRequest } from "../domains/dispatch/contract.js";
 import { type AgentRoleFactsResolver, requestExecutionRole } from "../domains/dispatch/execution-role.js";
-import type { ReceiptIntegrityResult } from "../domains/dispatch/receipt-integrity.js";
 import type { RunReceipt } from "../domains/dispatch/types.js";
 import type { JobThinkingLevel } from "../domains/dispatch/validation.js";
+import type { ReceiptIntegrityOutcome } from "../domains/evidence/trust-status.js";
 import type { InstalledExtension } from "../domains/extensions/index.js";
 import type { InteropAgentId, InteropProposal, InteropReport } from "../domains/interop/index.js";
 import type { ProvidersContract, ResolvedModelRef } from "../domains/providers/index.js";
@@ -665,7 +665,7 @@ export interface SlashCommandContext {
 	 * and emit a single status line. Kept on the context so the registry does
 	 * not import the overlay module.
 	 */
-	verifyReceipt: (runId: string) => ReceiptIntegrityResult;
+	verifyReceipt: (runId: string) => ReceiptIntegrityOutcome;
 	/**
 	 * Handles the "unknown" case: append the text to the chat panel as a user
 	 * turn, submit to the chat loop, and schedule a re-render. Handlers for
@@ -1507,6 +1507,11 @@ export const BUILTIN_SLASH_COMMANDS: ReadonlyArray<BuiltinSlashCommand> = [
 			const result = ctx.verifyReceipt(command.runId);
 			if (result.ok) {
 				ctx.notice("success", `verify ok ${command.runId}`);
+			} else if (result.retired !== undefined) {
+				// A retired seal is the expected state of a run from the previous
+				// release, so it is a warning that names the versions, never the
+				// failure a tampered receipt gets.
+				ctx.notice("warn", `verify retired ${command.runId} ${result.reason}`);
 			} else {
 				ctx.notice("error", `verify fail ${command.runId} ${result.reason}`);
 			}

package/src/interactive/status/controller.ts

@@ -178,6 +178,17 @@ export function createStatusController(deps: StatusControllerDeps): StatusContro
 		notify(prev, status, force);
 	};
 
+	// The window between the editor and the stream. `preparing` and `idle`
+	// bracket it; `compacting` inside it is already carried by the compaction
+	// bus overlay, which now lands because `preparing` is an active phase.
+	if (deps.chat.onTurnPreparation) {
+		unsubscribes.push(
+			deps.chat.onTurnPreparation((phase) => {
+				apply({ type: phase === "idle" ? "submit_settled" : "submit_accepted" }, true);
+			}),
+		);
+	}
+
 	unsubscribes.push(
 		deps.chat.onEvent((event: ChatLoopEvent) => {
 			if (event.type === "agent_status") return;

package/src/interactive/status/state-machine.ts

@@ -53,6 +53,21 @@ export interface DispatchProgressStatusEvent {
 	type: "dispatch_progress";
 }
 
+/**
+ * A prompt has left the editor and Clio is preparing the turn: capability
+ * probe, pre-submit compaction, prompt compile, overflow preflight. None of
+ * that produces an engine event, so without this the footer kept reporting the
+ * previous turn as done for the whole window (issue #251).
+ */
+export interface SubmitAcceptedStatusEvent {
+	type: "submit_accepted";
+}
+
+/** The prepared turn was admitted, refused, or failed. Either way the window is over. */
+export interface SubmitSettledStatusEvent {
+	type: "submit_settled";
+}
+
 export type StatusInputEvent =
 	| ChatLoopEvent
 	| WatchdogTickEvent
@@ -60,7 +75,9 @@ export type StatusInputEvent =
 	| OverlayPopEvent
 	| RunAbortedStatusEvent
 	| ForceCancelledStatusEvent
-	| DispatchProgressStatusEvent;
+	| DispatchProgressStatusEvent
+	| SubmitAcceptedStatusEvent
+	| SubmitSettledStatusEvent;
 
 const OVERLAY_PHASES = new Set<StatusPhase>(["tool_blocked", "retrying", "compacting", "dispatching", "stuck"]);
 const CORE_ACTIVE_PHASES = new Set<StatusPhase>(["preparing", "waiting_model", "thinking", "writing", "tool_running"]);
@@ -292,8 +309,43 @@ function retryOverlay(status: {
 
 export function reduceStatus(prev: AgentStatus, event: StatusInputEvent, ctx: ReduceContext): AgentStatus {
 	switch (event.type) {
-		case "agent_start":
+		// A consumed prompt occupies `preparing` before any engine event exists,
+		// and the previous turn's summary rides along untouched: a refused
+		// admission puts the footer back on the last turn that actually ran,
+		// which is still the truth about what happened.
+		case "submit_accepted":
 			if (isActive(prev.phase)) return prev;
+			return {
+				...prev,
+				phase: "preparing",
+				since: ctx.now,
+				lastMeaningfulAt: ctx.now,
+				localRuntime: ctx.localRuntime,
+				preparingSubmission: true,
+				watchdogTier: 0,
+				resumePhase: undefined,
+				activePhases: undefined,
+				overlayStack: [],
+				tool: undefined,
+				toolStartedAt: undefined,
+				retry: undefined,
+				dispatch: undefined,
+			};
+		case "submit_settled":
+			if (prev.preparingSubmission !== true) return prev;
+			return {
+				...prev,
+				phase: prev.summary ? "ended" : "idle",
+				since: ctx.now,
+				preparingSubmission: undefined,
+				resumePhase: undefined,
+				activePhases: undefined,
+				overlayStack: [],
+			};
+		case "agent_start":
+			// A window this opened is the same turn arriving, not a duplicate
+			// start, so the run resets through it rather than being ignored.
+			if (isActive(prev.phase) && prev.preparingSubmission !== true) return prev;
 			return {
 				...INITIAL_STATUS,
 				phase: "preparing",

package/src/interactive/status/types.ts

@@ -106,6 +106,13 @@ export interface AgentStatus {
 	toolStartedAt?: number | undefined;
 	retry?: RetryOverlay | undefined;
 	dispatch?: DispatchOverlay | undefined;
+	/**
+	 * Set while the `preparing` phase belongs to a consumed prompt that has not
+	 * yet been admitted, rather than to a run the engine has started. It is what
+	 * lets `agent_start` take over a window this opened instead of treating an
+	 * already-active phase as a duplicate start (issue #251).
+	 */
+	preparingSubmission?: boolean | undefined;
 	summary?: TurnSummary | undefined;
 	/** Usage settled so far in the active run. Reset by `agent_start`. */
 	runTally?: RunTally | undefined;

package/src/interactive/terminal-lease.ts

@@ -190,6 +190,8 @@ export function createProcessTerminalLease(options: CreateProcessTerminalLeaseOp
 		getThinkingLabel: () => editorChrome.getThinkingLabel(),
 		isStreaming: () => editorChrome.isStreaming?.() ?? false,
 		isAwaitingApproval: () => editorChrome.isAwaitingApproval?.() ?? false,
+		getPermissionInspection: () => editorChrome.getPermissionInspection?.() ?? "none",
+		getTurnPreparation: () => editorChrome.getTurnPreparation?.() ?? "idle",
 		willEnterSteer: (text) => editorChrome.willEnterSteer?.(text) ?? false,
 		getSubmitKeyLabel: () => editorChrome.getSubmitKeyLabel?.() ?? "Enter",
 		getNewlineKeyLabel: () => editorChrome.getNewlineKeyLabel?.() ?? "Shift+Enter",