@gajae-code/coding-agent 0.14.2 → 0.15.0

package/src/sdk/client/client.ts

@@ -74,9 +74,47 @@ export interface SdkRequestOptions {
 	timeoutMs?: number;
 	idempotencyKey?: string;
 	confirm?: boolean;
+	/**
+	 * Synchronous pre-send observer for one request. Called after the
+	 * connection is live and validated, immediately before the frame is written
+	 * to the socket. Throwing aborts the dispatch: nothing is written, no sent
+	 * record is retained, and the request rejects with the thrown error, so the
+	 * caller may safely retry (pre-send semantics).
+	 */
+	beforeDispatch?: SdkBeforeDispatchHandler;
+	/**
+	 * Synchronous dispatch-boundary observer for one request. Called immediately
+	 * after the frame was handed to the socket — never before — and before any
+	 * other client work. From this point a transport close before the response
+	 * settles the request as `uncertain_after_send`; observer exceptions cannot
+	 * alter that settlement.
+	 */
+	onDispatch?: SdkDispatchHandler;
 }
-
 export type SdkFrame = Record<string, unknown>;
+/**
+ * Synchronous by contract. Returning a thenable (e.g. an `async` function) is a
+ * contract violation: pre-send the dispatch aborts retryably and the eventual
+ * rejection is sunk, never escaping to the process unhandled-rejection channel.
+ */
+export type SdkBeforeDispatchHandler = (request: SdkDispatchContext) => void;
+/**
+ * Synchronous by contract. A returned thenable's rejection is sunk; it can
+ * neither displace request settlement nor escape to the process
+ * unhandled-rejection channel.
+ */
+export type SdkDispatchHandler = (request: SdkDispatchContext) => void;
+
+/**
+ * Facts about one request at its dispatch boundary. `frame.id` is the exact
+ * correlated identity a response frame must carry to settle this request.
+ */
+export interface SdkDispatchContext {
+	readonly frame: SdkFrame;
+	/** Transport generation this request was written to. */
+	readonly connectionId: string | undefined;
+	readonly generation: number;
+}
 
 /** Request identity retained after an uncertain send for lifecycle reconciliation. */
 
@@ -158,6 +196,52 @@ function parseFrame(value: unknown): Frame {
 	}
 	throw new SdkClientError("protocol_error", "SDK server sent a malformed frame.");
 }
+/**
+ * Recursively freezes the parsed request frame handed to dispatch-boundary
+ * observers. The frame a consumer sees in `beforeDispatch`/`onDispatch` must be
+ * the exact immutable bytes-derived identity that went on the wire, so a
+ * mutating callback can never desynchronize the advertised identity or the
+ * reconciliation fingerprint from the request that was actually sent.
+ */
+function deepFreeze<T>(value: T): T {
+	if (value && typeof value === "object") {
+		for (const nested of Object.values(value as Record<string, unknown>)) deepFreeze(nested);
+		Object.freeze(value);
+	}
+	return value;
+}
+
+type Thenable = { then?: unknown };
+
+/**
+ * Observers are synchronous by contract, but TypeScript happily accepts an
+ * `async` function where `() => void` is expected. A rejected promise returned
+ * by an observer would otherwise reach the process-level unhandled-rejection
+ * channel — terminating `--unhandled-rejections=strict` consumers — and a
+ * rejected `beforeDispatch` would silently not abort the dispatch. Observers
+ * that return a thenable are treated as a contract violation: detected
+ * explicitly, sunk here, and (pre-send) failed before the wire.
+ */
+function isThenable(value: unknown): value is Thenable {
+	return (
+		(typeof value === "object" || typeof value === "function") &&
+		value !== null &&
+		typeof (value as Thenable).then === "function"
+	);
+}
+
+function sinkThenable(value: unknown): void {
+	const thenable = value as { then: (onFulfilled: unknown, onRejected: (error: unknown) => void) => unknown };
+	try {
+		thenable.then(undefined, () => {
+			// Observer rejections never displace settlement; swallow them here
+			// so they cannot escape to the process unhandled-rejection channel.
+		});
+	} catch {
+		// A throwing then-accessor already surfaced synchronously to the caller
+		// of the observer; nothing further to sink.
+	}
+}
 
 function lifecycleFingerprint(operation: string, input: unknown): string {
 	return createHash("sha256").update(JSON.stringify({ operation, input })).digest("hex");
@@ -255,9 +339,9 @@ export class SdkClient {
 		}
 	}
 
-	request(frame: SdkFrame, timeout?: number | { timeoutMs?: number; idempotencyKey?: string }): Promise<SdkFrame> {
-		const options = typeof timeout === "number" ? { timeoutMs: timeout } : (timeout ?? {});
-		return this.#request(frame, options) as Promise<SdkFrame>;
+	request(frame: SdkFrame, options?: number | SdkRequestOptions): Promise<SdkFrame> {
+		const resolved = typeof options === "number" ? { timeoutMs: options } : (options ?? {});
+		return this.#request(frame, resolved) as Promise<SdkFrame>;
 	}
 
 	close(): Promise<void> {
@@ -370,7 +454,18 @@ export class SdkClient {
 			...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
 		};
 		const serializedRequest = JSON.stringify(requestFrame);
-		const serializedFrame = JSON.parse(serializedRequest) as Frame;
+		const serializedFrame: Frame = deepFreeze(JSON.parse(serializedRequest) as Frame);
+		// Snapshot reconciliation identity from the exact serialized bytes BEFORE any
+		// observer runs. Callers own `options`, so rereading `options.idempotencyKey`
+		// or recomputing the fingerprint after a callback would let a mutating or
+		// getter-swapping observer diverge the retained record from the wire request.
+		const sentOperation = typeof serializedFrame.operation === "string" ? serializedFrame.operation : undefined;
+		const sentIdempotencyKey =
+			typeof serializedFrame.idempotencyKey === "string" ? serializedFrame.idempotencyKey : undefined;
+		const sentFingerprint =
+			typeof serializedFrame.operation === "string"
+				? lifecycleFingerprint(serializedFrame.operation, serializedFrame.input ?? {})
+				: inputFingerprint(serializedFrame.input ?? {});
 		const deferred = Promise.withResolvers<unknown>();
 		const pending: Pending = {
 			incarnation,
@@ -397,26 +492,113 @@ export class SdkClient {
 			this.#settlePending(id, pending, new SdkClientError("unavailable", "SDK WebSocket is not connected"));
 			return await deferred.promise;
 		}
+		if (options.beforeDispatch) {
+			try {
+				const observerResult = options.beforeDispatch({
+					frame: serializedFrame,
+					connectionId: this.connectionId,
+					generation: incarnation.generation,
+				});
+				if (isThenable(observerResult)) {
+					// An async observer cannot honor the synchronous pre-send
+					// contract: its abort decision is unavailable before the
+					// write. Sink the eventual rejection so it never escapes,
+					// and abort the dispatch pre-send (retryable, nothing on
+					// the wire).
+					sinkThenable(observerResult);
+					this.#settlePending(
+						id,
+						pending,
+						new SdkClientError(
+							"invalid_input",
+							"beforeDispatch must be synchronous; an async observer cannot gate the dispatch boundary.",
+						),
+						false,
+					);
+					return await deferred.promise;
+				}
+			} catch (error) {
+				// Pre-send abort: the wire never saw this request, so retirement
+				// must not retain a sent record or classify it as uncertain. The
+				// caller's own rejection comes back unchanged so it stays
+				// retryable and distinguishable from transport failure.
+				this.#settlePending(
+					id,
+					pending,
+					error instanceof Error ? error : new SdkClientError("invalid_input", String(error), error),
+					false,
+				);
+				return await deferred.promise;
+			}
+		}
+		// `beforeDispatch` is arbitrary synchronous caller code: it may have closed
+		// the client, retired this incarnation, settled this pending entry, or run
+		// the deadline past its end. Nothing about the pre-call validation still
+		// holds, so revalidate all of it before the wire write and bookkeeping.
+		if (this.#closed || this.#pending.get(id) !== pending || !this.#isActive(incarnation)) {
+			if (this.#pending.get(id) === pending)
+				this.#settlePending(
+					id,
+					pending,
+					new SdkClientError("connection_closed", "SDK client closed during dispatch"),
+				);
+			return await deferred.promise;
+		}
+		if (this.#deadline !== undefined && Date.now() >= this.#deadline) {
+			this.#settlePending(id, pending, this.#deadlineError());
+			return await deferred.promise;
+		}
+		if (incarnation.socket.readyState !== WebSocket.OPEN) {
+			this.#settlePending(id, pending, new SdkClientError("unavailable", "SDK WebSocket is not connected"));
+			return await deferred.promise;
+		}
+		// Handoff bookkeeping is reentrancy-safe: `sent` flips BEFORE the wire
+		// write so a send that synchronously triggers a close event or response
+		// retires this request as already-sent (uncertain_after_send on close,
+		// never pre-send), and the sent record is retained up-front for the same
+		// reason. Only a synchronous send THROW rolls the pre-write state back:
+		// nothing reached the transport, so the request stays retryable and
+		// non-uncertain with no record retained.
+		pending.sent = true;
+		this.#rememberSentRecord({
+			id,
+			operation: sentOperation,
+			idempotencyKey: sentIdempotencyKey,
+			fingerprint: sentFingerprint,
+		});
 		try {
 			incarnation.socket.send(serializedRequest);
-			pending.sent = true;
-			this.#rememberSentRecord({
-				id,
-				operation: typeof serializedFrame.operation === "string" ? serializedFrame.operation : undefined,
-				idempotencyKey: options.idempotencyKey,
-				fingerprint:
-					typeof serializedFrame.operation === "string"
-						? lifecycleFingerprint(serializedFrame.operation, serializedFrame.input ?? {})
-						: inputFingerprint(serializedFrame.input ?? {}),
-			});
 		} catch (error) {
-			this.#settlePending(
-				id,
-				pending,
-				error instanceof SdkClientError
-					? error
-					: new SdkClientError("unavailable", "SDK WebSocket send failed", error),
-			);
+			if (this.#pending.get(id) === pending) {
+				// Nothing was accepted by the transport (the write threw before
+				// handoff), so this stays a retryable pre-send failure — unless a
+				// reentrant event already settled the request during the throw,
+				// in which case that settlement stands and must not be displaced.
+				pending.sent = false;
+				this.#sentRecords.delete(id);
+				this.#settlePending(
+					id,
+					pending,
+					error instanceof SdkClientError
+						? error
+						: new SdkClientError("unavailable", "SDK WebSocket send failed", error),
+				);
+			}
+			return await deferred.promise;
+		}
+		// Reconciliation identity was retained above the send so reentrant
+		// close/response handling finds it; nothing further to record here.
+		try {
+			const observerResult = options.onDispatch?.({
+				frame: serializedFrame,
+				connectionId: this.connectionId,
+				generation: incarnation.generation,
+			});
+			if (isThenable(observerResult)) sinkThenable(observerResult);
+		} catch {
+			// The frame was already handed to the socket. An observer failure can
+			// neither un-send it nor displace settlement, so the request stays
+			// pending for its response, deadline, or transport-close retirement.
 		}
 		return await deferred.promise;
 	}

package/src/sdk/host/host.ts

@@ -1,6 +1,8 @@
 import { logger } from "@gajae-code/utils";
+import { AUTOROUTING_INACTIVE_WARNING } from "../../config/autorouting-contract";
 import { redactBrokerRuntimeCloseCapability } from "./control/runtime-gate";
 import { type EventFrame, SessionEventStream } from "./events";
+import { isAutoroutingInactive } from "./internal-autorouting-state";
 import { type ProviderLease, ReverseLeaseError, ReverseLeaseRuntime } from "./reverse-leases";
 import type { BrokerIndexWriter, HostEndpointAdapters, SdkFrame } from "./types";
 
@@ -77,6 +79,7 @@ export interface SessionSdkHostOptions extends HostEndpointAdapters {
 	connectionCapabilities?: (connectionId: string) => ReadonlySet<string> | undefined;
 	/** Readiness publication mode; defaults to the stock immediate contract. */
 	readiness?: SessionReadinessMode;
+
 	/**
 	 * Authorization for a deferred activation. It is consulted on every attempt
 	 * that would publish readiness and never on an idempotent replay, and a gate
@@ -247,9 +250,22 @@ export class SessionSdkHost {
 		return this.events.emit(frame);
 	}
 
+	emitAutoroutingInactiveNotice(): EventFrame {
+		return this.emitEvent({
+			kind: "notice",
+			payload: {
+				type: "notice",
+				level: "warning",
+				message: AUTOROUTING_INACTIVE_WARNING,
+				source: "autorouting",
+			},
+		});
+	}
+
 	async start(): Promise<"started" | "already"> {
 		if (this.#started) return "already";
 		this.events.restart();
+		if (isAutoroutingInactive(this)) this.emitAutoroutingInactiveNotice();
 		if (this.#options.readiness !== "deferred") this.#publishReadiness();
 		else
 			this.emitEvent({

package/src/sdk/host/internal-autorouting-state.ts

@@ -0,0 +1,13 @@
+const inactiveAutoroutingState = new WeakMap<object, boolean>();
+
+export function markAutoroutingInactive(target: object): void {
+	inactiveAutoroutingState.set(target, true);
+}
+
+export function clearAutoroutingInactive(target: object): void {
+	inactiveAutoroutingState.delete(target);
+}
+
+export function isAutoroutingInactive(target: unknown): boolean {
+	return typeof target === "object" && target !== null && inactiveAutoroutingState.get(target) === true;
+}

package/src/sdk/host/model-pin.ts

@@ -0,0 +1,101 @@
+import * as path from "node:path";
+import type { AuthStorage } from "@gajae-code/ai/core";
+import { ModelRegistry } from "../../config/model-registry";
+import {
+	formatModelSelectorValue,
+	formatModelString,
+	type ResolveCliModelResult,
+	resolveCliModel,
+} from "../../config/model-resolver";
+import { Settings } from "../../config/settings";
+import { discoverAuthStorage } from "../session";
+
+const MAX_ECHOED_MODEL_LENGTH = 256;
+
+export interface SdkHostModelResolveContext {
+	cwd?: string;
+}
+
+/** Registry loader owned by the SDK host, not by machine-facing adapters. */
+export type SdkHostModelRegistryLoader = (
+	context?: SdkHostModelResolveContext,
+) => ModelRegistry | Promise<ModelRegistry>;
+
+/**
+ * Builds an offline model resolver for a single SDK host process.
+ *
+ * The registry is reused, but refreshed for every validation so additions and
+ * removals made while the broker is alive are observed without network I/O.
+ */
+export function createSdkHostModelRegistryLoader(
+	discoverStorage: () => Promise<AuthStorage>,
+	modelsPath?: string,
+	loadSettings?: (context?: SdkHostModelResolveContext) => Promise<Pick<Settings, "get" | "getGlobal">>,
+): SdkHostModelRegistryLoader {
+	const cachedRegistries = new Map<string, Promise<ModelRegistry>>();
+	return async (context?: SdkHostModelResolveContext) => {
+		const scopeKey = context?.cwd ?? "";
+		let cachedRegistry = cachedRegistries.get(scopeKey);
+		if (cachedRegistry === undefined) {
+			const initializing = Promise.all([discoverStorage(), loadSettings?.(context)]).then(
+				([storage, registrySettings]) => new ModelRegistry(storage, modelsPath, registrySettings),
+			);
+			cachedRegistries.set(scopeKey, initializing);
+			cachedRegistry = initializing;
+			try {
+				await initializing;
+			} catch (error) {
+				if (cachedRegistries.get(scopeKey) === initializing) cachedRegistries.delete(scopeKey);
+				throw error;
+			}
+		}
+		const registry = await cachedRegistry;
+		if (loadSettings) registry.setScopedSettings(await loadSettings(context));
+		await registry.refresh("offline");
+		return registry;
+	};
+}
+
+export type SdkHostModelResolution =
+	| { ok: true; model: string | null }
+	| { ok: false; reason: "unknown_model"; model: string; error: string };
+
+export type SdkHostModelResolver = (
+	raw: unknown,
+	context?: SdkHostModelResolveContext,
+) => Promise<SdkHostModelResolution>;
+
+/** Resolve the explicit model pin at the SDK host boundary. */
+export async function resolveSdkHostModel(
+	raw: unknown,
+	loadRegistry: SdkHostModelRegistryLoader,
+	context?: SdkHostModelResolveContext,
+): Promise<SdkHostModelResolution> {
+	if (raw === undefined || raw === null) return { ok: true, model: null };
+	const requested = typeof raw === "string" ? raw : "";
+	const echoed = requested.trim().slice(0, MAX_ECHOED_MODEL_LENGTH);
+	const registry = await loadRegistry(context);
+	const resolved: ResolveCliModelResult = resolveCliModel({ cliModel: requested, modelRegistry: registry });
+	if (!resolved.model)
+		return {
+			ok: false,
+			reason: "unknown_model",
+			model: echoed,
+			error: resolved.error ?? "No models available. Check your installation or add models to models.json.",
+		};
+	return {
+		ok: true,
+		model: formatModelSelectorValue(formatModelString(resolved.model), resolved.thinkingLevel),
+	};
+}
+
+/** Default resolver used by the SDK broker host. */
+export function createDefaultSdkHostModelResolver(agentDir: string): SdkHostModelResolver {
+	const loadRegistry = createSdkHostModelRegistryLoader(
+		() => discoverAuthStorage(agentDir),
+		path.join(agentDir, "models.yml"),
+		context => Settings.loadReadonly({ agentDir, cwd: context?.cwd }),
+	);
+	return (raw: unknown, context?: SdkHostModelResolveContext): Promise<SdkHostModelResolution> =>
+		resolveSdkHostModel(raw, loadRegistry, context);
+}

package/src/sdk/host/reverse-leases.ts

@@ -281,8 +281,9 @@ export class ReverseLeaseRuntime {
 			throw new ReverseLeaseError("not_lease_owner");
 		this.#takeOutstanding(id);
 		if (error) {
-			const rejection = new Error(error.message);
+			const rejection = new Error(error.message) as Error & { code: string };
 			rejection.name = error.code;
+			rejection.code = error.code;
 			request.reject(rejection);
 		} else request.resolve(result);
 	}

package/src/sdk/host/session-runtime.test.ts

@@ -13,9 +13,11 @@ import {
 } from "../../session/terminal-abort";
 import { Broker } from "../broker/broker";
 import { createReconciliationStore } from "../bus/reconciliation-store";
+import { CursorRegistry, QueryHandlers, RevisionStore } from "./query";
 import {
 	createInvocationReconciliation,
 	createSdkSessionRuntimeExtension,
+	createSdkSurfaceFactory,
 	SessionSdkSessionRuntime,
 	type SessionSdkTransport,
 } from "./session-runtime";
@@ -76,7 +78,15 @@ function admissionBarrier(target: number) {
 	};
 }
 
-function extensionContext(sessionId: string, cwd: string): ExtensionContext {
+function extensionContext(
+	sessionId: string,
+	cwd: string,
+	options: {
+		goalState?: unknown;
+		branch?: unknown[];
+		liveState?: { isStreaming: boolean; steeringQueueDepth: number; followupQueueDepth: number };
+	} = {},
+): ExtensionContext {
 	return {
 		cwd,
 		workflowGate: undefined,
@@ -85,10 +95,133 @@ function extensionContext(sessionId: string, cwd: string): ExtensionContext {
 			getSessionId: () => sessionId,
 			getSessionFile: () => path.join(cwd, `${sessionId}.json`),
 			getSessionName: () => undefined,
+			getBranch: () => options.branch ?? [],
 		},
+		getGoalState: () => options.goalState,
 	} as unknown as ExtensionContext;
 }
 
+function goalModeEntry(sessionId: string, tokensUsed: number): Record<string, unknown> {
+	return {
+		type: "mode_change",
+		id: `goal-${sessionId}`,
+		parentId: null,
+		timestamp: new Date(1_000).toISOString(),
+		mode: "goal",
+		data: {
+			goal: {
+				id: `goal-${sessionId}`,
+				objective: "Preserve the active SDK goal",
+				status: "active",
+				tokensUsed,
+				timeUsedSeconds: 2,
+				createdAt: 1_000,
+				updatedAt: 2_000,
+			},
+		},
+	};
+}
+
+async function queryGoalState(
+	ctx: ExtensionContext,
+	sessionId: string,
+	liveState?: { isStreaming: boolean; steeringQueueDepth: number; followupQueueDepth: number },
+): Promise<unknown> {
+	const surface = createSdkSurfaceFactory({
+		ctx,
+		id: sessionId,
+		api: {} as ExtensionAPI,
+		getLiveState: () => liveState ?? { isStreaming: false, steeringQueueDepth: 0, followupQueueDepth: 0 },
+	}).query;
+	const store = new RevisionStore(sessionId);
+	const cursors = new CursorRegistry("goal-test-token", store);
+	const response = await new QueryHandlers(surface, sessionId, store, cursors).dispatch({
+		query: "goal.list/get",
+		connectionId: "goal-test-connection",
+	});
+	if (!response.ok) throw new Error(`goal query failed: ${JSON.stringify(response)}`);
+	return response.page?.items[0];
+}
+
+describe("SDK goal snapshot lifecycle", () => {
+	test("recovers an active nonzero-activity goal from the durable session projection", async () => {
+		const cwd = await mkdtemp(path.join(os.tmpdir(), "gjc-sdk-goal-recovery-"));
+		try {
+			const sessionId = "runtime-recreated";
+			const branch = [goalModeEntry(sessionId, 17)];
+			const liveGoal = {
+				enabled: true,
+				mode: "active",
+				goal: { ...(branch[0] as { data: { goal: Record<string, unknown> } }).data.goal },
+			};
+			const live = await queryGoalState(
+				extensionContext(sessionId, cwd, { goalState: liveGoal, branch }),
+				sessionId,
+				{ isStreaming: true, steeringQueueDepth: 1, followupQueueDepth: 0 },
+			);
+			const recreated = await queryGoalState(extensionContext(sessionId, cwd, { branch }), sessionId);
+
+			expect(live).toMatchObject({ enabled: true, goal: { status: "active", tokensUsed: 17 } });
+			expect(recreated).toEqual(live);
+		} finally {
+			await rm(cwd, { recursive: true, force: true });
+		}
+	});
+
+	test("keeps fresh session/worktree projections isolated while an active turn has activity", async () => {
+		const root = await mkdtemp(path.join(os.tmpdir(), "gjc-sdk-goal-isolation-"));
+		try {
+			const first = await queryGoalState(
+				extensionContext("fresh-session-a", path.join(root, "a"), {
+					branch: [goalModeEntry("fresh-session-a", 11)],
+				}),
+				"fresh-session-a",
+			);
+			const second = await queryGoalState(
+				extensionContext("fresh-session-b", path.join(root, "b"), {
+					branch: [goalModeEntry("fresh-session-b", 23)],
+				}),
+				"fresh-session-b",
+			);
+
+			expect(first).toMatchObject({ goal: { id: "goal-fresh-session-a", tokensUsed: 11 } });
+			expect(second).toMatchObject({ goal: { id: "goal-fresh-session-b", tokensUsed: 23 } });
+			expect(first).not.toEqual(second);
+		} finally {
+			await rm(root, { recursive: true, force: true });
+		}
+	});
+
+	test("returns an explicit no-active-goal diagnostic for the zero-activity control", async () => {
+		const cwd = await mkdtemp(path.join(os.tmpdir(), "gjc-sdk-goal-empty-"));
+		try {
+			const result = await queryGoalState(extensionContext("zero-activity", cwd), "zero-activity");
+			expect(result).toMatchObject({ enabled: false, goal: null, reason: "no_active_goal" });
+		} finally {
+			await rm(cwd, { recursive: true, force: true });
+		}
+	});
+
+	test("returns a recoverable diagnostic when durable active-goal state is malformed", async () => {
+		const cwd = await mkdtemp(path.join(os.tmpdir(), "gjc-sdk-goal-corrupt-"));
+		try {
+			const result = await queryGoalState(
+				extensionContext("corrupt-goal", cwd, {
+					branch: [{ ...goalModeEntry("corrupt-goal", 19), data: { goal: { status: "active" } } }],
+				}),
+				"corrupt-goal",
+			);
+			expect(result).toMatchObject({
+				reason: "goal_state_unavailable",
+				recoverable: true,
+				goal: null,
+			});
+		} finally {
+			await rm(cwd, { recursive: true, force: true });
+		}
+	});
+});
+
 test("preserves an agent failure code in host prompt reconciliation", async () => {
 	const reconciliation = createInvocationReconciliation();
 	const correlation = { commandId: "failed-command", turnId: "failed-turn" };
@@ -2534,6 +2667,96 @@ describe("post-acceptance invocation terminalization", () => {
 			await rm(cwd, { recursive: true, force: true });
 		}
 	});
+	test("immediate prompt after abort ack is not terminalized by the aborted turn's delayed agent_end", async () => {
+		const cwd = await mkdtemp(path.join(os.tmpdir(), "gjc-abort-immediate-prompt-"));
+		try {
+			const firstInflight = Promise.withResolvers<void>();
+			const successorStarted = Promise.withResolvers<void>();
+			let prompts = 0;
+			const harness = await invocationHarness("abort-immediate-prompt", cwd, {
+				sendUserMessage: async (_content, options) => {
+					prompts += 1;
+					await options?.onPreflightAcceptCommit?.();
+					if (prompts === 1) {
+						await firstInflight.promise;
+						return;
+					}
+					successorStarted.resolve();
+					await Promise.withResolvers<void>().promise;
+				},
+			});
+			const first = await harness.control("turn.prompt", { text: "first" });
+			expect(first.ok).toBe(true);
+			const firstIds = { commandId: first.result?.commandId, turnId: first.result?.turnId };
+			await harness.emit("agent_start");
+			expect(await harness.control("turn.abort", {})).toMatchObject({ ok: true });
+			firstInflight.reject(Object.assign(new Error("turn aborted"), { code: "aborted" }));
+			const second = await harness.control("turn.prompt", { text: "successor" });
+			expect(second.ok).toBe(true);
+			const secondIds = { commandId: second.result?.commandId, turnId: second.result?.turnId };
+			expect(secondIds.commandId).not.toBe(firstIds.commandId);
+			expect(secondIds.turnId).not.toBe(firstIds.turnId);
+			await harness.emit("agent_start");
+			await successorStarted.promise;
+			await harness.emit("agent_end");
+			expect(await harness.query("turn.prompt_status", secondIds)).toMatchObject({
+				result: { status: expect.stringMatching(/accepted|in_flight/) },
+			});
+			expect(await settledStatus(harness, "turn.prompt_status", firstIds)).toMatchObject({
+				status: "failed",
+				error: { code: "aborted" },
+			});
+			await harness.emit("agent_end");
+			expect(await settledStatus(harness, "turn.prompt_status", secondIds)).toMatchObject({
+				status: "terminal_ok",
+			});
+			expect(prompts).toBe(2);
+			await harness.stop();
+		} finally {
+			await Bun.sleep(50);
+			await rm(cwd, { recursive: true, force: true });
+		}
+	});
+
+	test("abort_and_prompt starts exactly one successor and is not duplicated by delayed abort teardown", async () => {
+		const cwd = await mkdtemp(path.join(os.tmpdir(), "gjc-abort-and-prompt-once-"));
+		try {
+			const firstInflight = Promise.withResolvers<void>();
+			const abortReleased = Promise.withResolvers<void>();
+			let prompts = 0;
+			const harness = await invocationHarness("abort-and-prompt-once", cwd, {
+				sendUserMessage: async (_content, options) => {
+					prompts += 1;
+					await options?.onPreflightAcceptCommit?.();
+					if (prompts === 1) {
+						await firstInflight.promise;
+						return;
+					}
+				},
+				abort: () => abortReleased.promise,
+			});
+			const first = await harness.control("turn.prompt", { text: "first" });
+			expect(first.ok).toBe(true);
+			await harness.emit("agent_start");
+			const replacement = harness.control("turn.abort_and_prompt", { text: "replacement" });
+			firstInflight.reject(Object.assign(new Error("turn aborted"), { code: "aborted" }));
+			await harness.emit("agent_end");
+			abortReleased.resolve();
+			const accepted = await replacement;
+			expect(accepted.ok).toBe(true);
+			const successorIds = { commandId: accepted.result?.commandId, turnId: accepted.result?.turnId };
+			await harness.emit("agent_start");
+			await harness.emit("agent_end");
+			expect(await settledStatus(harness, "turn.prompt_status", successorIds)).toMatchObject({
+				status: "terminal_ok",
+			});
+			expect(prompts).toBe(2);
+			await harness.stop();
+		} finally {
+			await Bun.sleep(50);
+			await rm(cwd, { recursive: true, force: true });
+		}
+	});
 
 	test("a failed skill invocation still reports a terminal failed status", async () => {
 		const cwd = await mkdtemp(path.join(os.tmpdir(), "gjc-terminalize-skill-"));