@gajae-code/coding-agent 0.15.6 → 0.16.0

package/src/sdk/cli/session-cli.ts

@@ -2,17 +2,27 @@ import { randomBytes } from "node:crypto";
 import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { replaceTabs, truncateToWidth } from "@gajae-code/tui";
 import { getAgentDir } from "@gajae-code/utils";
 import { repo as resolveGitRepository } from "../../utils/git";
 import { ensureBroker } from "../broker/ensure";
+import { resolveSessionLocator } from "../broker/session-index";
+import {
+	resolveScopeRequest,
+	type ScopeNameV1,
+	type ScopeRequestV1,
+	type SdkSearchResultV1,
+	type SdkSearchRowV1,
+} from "../broker/session-scope";
 import { lifecycleRequestTimeoutMs } from "../broker/startup-budget";
-import { SdkClientError } from "../client";
+import { readSdkBrokerDiscovery, SdkClient, SdkClientError } from "../client";
 import { createBrokerSessionLifecycleService } from "../lifecycle/broker-client";
 import type {
 	SessionLifecycleMutationRequest,
 	SessionLifecycleOperation,
 	SessionLifecycleSavedSession,
 	SessionLifecycleSavedSessionIdentity,
+	SessionLifecycleService,
 	SessionReconcileUncertainTarget,
 } from "../lifecycle/service";
 import { PROMPT_CLIENT_REF_MAX_LENGTH } from "../prompt-status";
@@ -24,6 +34,7 @@ import {
 import { adapterDispositionError, findOperation, type OperationKind } from "../protocol/operation-registry";
 import { type SessionAttachment, SessionRouter, SessionRouterError, type SessionRouterFrame } from "../router";
 import { SessionListTraversalError, sessionListPageFromResponse, traverseSessionList } from "../session-list";
+import { SESSION_REQUEST_TIMEOUT_MS } from "../session-reconnect";
 import {
 	type SdkCheckpointRecordV1,
 	type SdkRetentionGapV1,
@@ -39,6 +50,7 @@ import {
 
 export type SdkSessionCliAction =
 	| "list"
+	| "search"
 	| "inspect"
 	| "send"
 	| "status"
@@ -64,7 +76,6 @@ export interface SdkSessionCliArgs {
 	jsonInputFile?: string;
 	jsonInputStdin?: boolean;
 	idempotencyKey?: string;
-	scope?: string;
 	confirm?: boolean;
 	cursor?: string;
 	wait?: boolean;
@@ -73,6 +84,10 @@ export interface SdkSessionCliArgs {
 	untilIdle?: boolean;
 	allEvents?: boolean;
 	repo?: string;
+	scope?: string;
+	limit?: number;
+	json?: boolean;
+
 	agentDir?: string;
 }
 
@@ -95,6 +110,9 @@ const TAIL_OFFLINE_MAX_SCAN_BYTES = 4 * 1024 * 1024;
 const TAIL_OFFLINE_MAX_SCANNED_LINES = 4_096;
 const TAIL_OFFLINE_MAX_LINE_BYTES = 256 * 1024;
 const transcriptDecoder = new TextDecoder("utf-8", { fatal: true });
+const SEARCH_PROBE_TIMEOUT_MS = 2_000;
+const SEARCH_PROBE_MAX_ROWS = 100;
+const SEARCH_TEXT_WIDTH = 80;
 
 const TERMINAL_TURN_KINDS = new Set(["turn_end", "agent_end"]);
 const START_TURN_KINDS = new Set(["turn_start", "agent_start"]);
@@ -214,6 +232,10 @@ function isEndpointOperation(operation: string): boolean {
 	return operation === "session.get_endpoint";
 }
 
+function isRawSpawnOperation(kind: OperationKind, operation: string): boolean {
+	return kind === "global" && operation === "session.spawn";
+}
+
 function isLifecycleOperation(operation: string): operation is LifecycleMutationOperation {
 	return (
 		operation === "session.create" ||
@@ -257,9 +279,11 @@ async function withRouter<T>(
 	agentDir: string,
 	action: (router: SessionRouter) => Promise<T>,
 	onFrame?: (attachment: SessionAttachment, frame: SessionRouterFrame) => void,
+	sessionIds?: readonly string[],
 ): Promise<T> {
 	const router = new SessionRouter({
 		agentDir,
+		...(sessionIds === undefined ? {} : { sessionIds }),
 		...(onFrame === undefined ? {} : { deps: { onFrame } }),
 	});
 	let result!: T;
@@ -367,6 +391,145 @@ async function sessionRows(agentDir: string): Promise<SessionRows> {
 	});
 }
 
+function searchScopeRequest(scope: ScopeNameV1, locator: { cwd: string; worktreeRoot: string | null }): ScopeRequestV1 {
+	return { version: 1, requested: scope, requestAnchor: { cwd: locator.cwd, worktreeRoot: locator.worktreeRoot } };
+}
+
+function searchProbe(row: SdkSearchRowV1, router: SessionRouter): Promise<SdkSearchRowV1> {
+	if (!row.live) return Promise.resolve({ ...row, probe: "stale" });
+	return (async () => {
+		try {
+			const attachment = router.attachment(row.id);
+			if (!attachment) return { ...row, probe: "unreachable" };
+			const response = await router.request(
+				row.id,
+				{ type: "query_request", query: "session.checkpoint", input: {} },
+				attachment.generation,
+				attachment,
+				{ timeoutMs: SEARCH_PROBE_TIMEOUT_MS },
+			);
+			return { ...row, probe: response.ok === true ? "reachable" : "unreachable" };
+		} catch {
+			return { ...row, probe: "unreachable" };
+		}
+	})();
+}
+
+export function mergeProbedSearchRows(
+	rows: readonly SdkSearchRowV1[],
+	probedRows: readonly SdkSearchRowV1[],
+): readonly SdkSearchRowV1[] {
+	return [...probedRows, ...rows.slice(probedRows.length)];
+}
+
+async function probeSearchRows(agentDir: string, result: SdkSearchResultV1): Promise<SdkSearchResultV1> {
+	if (result.status === "unavailable" || result.status === "not-in-git-worktree" || result.rows.length === 0)
+		return result;
+	const rows = result.rows.slice(0, SEARCH_PROBE_MAX_ROWS);
+	try {
+		const probes = await withRouter(
+			agentDir,
+			async router => await Promise.all(rows.map(row => searchProbe(row, router))),
+			undefined,
+			rows.map(row => row.id),
+		);
+		return { ...result, rows: mergeProbedSearchRows(result.rows, probes) };
+	} catch {
+		return {
+			...result,
+			rows: mergeProbedSearchRows(
+				result.rows,
+				rows.map(row => ({ ...row, probe: row.live ? "unreachable" : "stale" })),
+			),
+		};
+	}
+}
+
+/** Resolves, lists, and probes only the exact rows selected by the Broker-scoped search. */
+export async function runSdkSearch(
+	args: Pick<SdkSessionCliArgs, "agentDir" | "repo" | "scope" | "limit" | "cursor">,
+	createService: (agentDir: string) => SessionLifecycleService = createBrokerSessionLifecycleService,
+	probe: (agentDir: string, result: SdkSearchResultV1) => Promise<SdkSearchResultV1> = probeSearchRows,
+): Promise<{ result: SdkSearchResultV1; exitCode: 0 | 1 }> {
+	const agentDir = args.agentDir ?? getAgentDir();
+	const locator = await resolveSessionLocator(args.repo ?? process.cwd(), agentDir);
+	const scope: ScopeNameV1 =
+		args.scope === undefined || args.scope === "repo" || args.scope === "pwd" || args.scope === "global"
+			? ((args.scope ?? "repo") as ScopeNameV1)
+			: (() => {
+					throw new SdkSessionCliError(
+						"usage",
+						`Invalid search scope "${args.scope}". Expected repo, pwd, or global.`,
+						2,
+					);
+				})();
+	const request = searchScopeRequest(scope, locator);
+	const resolved = await resolveScopeRequest(request);
+	const outcome = await createService(agentDir).scopedList(request, args.limit, args.cursor);
+	if (outcome.ok) {
+		if ("rows" in outcome.result) {
+			if (outcome.result.status === "not-in-git-worktree") return { result: outcome.result, exitCode: 0 };
+			if (outcome.result.status === "unavailable") return { result: outcome.result, exitCode: 1 };
+			return { result: await probe(agentDir, outcome.result), exitCode: 0 };
+		}
+		return {
+			result: {
+				version: 1,
+				scope: resolved,
+				status: "unavailable",
+				observedAt: new Date().toISOString(),
+				rows: [],
+				warnings: [],
+				error: { code: "malformed_response", message: "broker search returned an unscoped result" },
+			},
+			exitCode: 1,
+		};
+	}
+	if (!outcome.ok && outcome.result?.status === "unavailable") return { result: outcome.result, exitCode: 1 };
+	return {
+		result: {
+			version: 1,
+			scope: resolved,
+			status: "unavailable",
+			observedAt: new Date().toISOString(),
+			rows: [],
+			warnings: [],
+			error: { code: outcome.error.code, message: outcome.error.message },
+		},
+		exitCode: 1,
+	};
+}
+
+function searchScopeLabel(result: SdkSearchResultV1): string {
+	const resolved = result.scope.resolved;
+	if (resolved === null) return "not-in-git-worktree";
+	if (resolved.kind === "repo") return resolved.worktreeRoot;
+	if (resolved.kind === "pwd") return resolved.cwd;
+	return resolved.visibility;
+}
+
+function safeSearchText(value: string): string {
+	return truncateToWidth(replaceTabs(value).replaceAll(/[\r\n]/g, " "), SEARCH_TEXT_WIDTH);
+}
+
+/** Renders a credential-free scope/status preamble and bounded search table. */
+export function renderSdkSearchTable(result: SdkSearchResultV1): string {
+	const lines = [
+		`Scope requested: ${result.scope.requested}`,
+		`Scope resolved: ${safeSearchText(searchScopeLabel(result))}`,
+		`Status: ${result.status}`,
+		`Observed at: ${result.observedAt}`,
+		...(result.cursor === undefined ? [] : [`Continuation cursor: ${safeSearchText(result.cursor)}`]),
+	];
+	if (result.rows.length === 0) return lines.join("\n");
+	lines.push("ID  PROBE        LIVE  CWD");
+	for (const row of result.rows)
+		lines.push(
+			`${safeSearchText(row.id).padEnd(20)}  ${(row.probe ?? "-").padEnd(11)}  ${String(row.live).padEnd(4)}  ${safeSearchText(row.locator.cwd)}`,
+		);
+	return lines.join("\n");
+}
+
 const SESSION_LIST_SCOPES: readonly SdkSessionListScope[] = ["repo", "cwd", "worktree", "all"];
 /** Row workspaces whose locator cannot be canonicalized still get one deterministic identity. */
 const WORKSPACE_IDENTITY_CACHE_LIMIT = 4096;
@@ -487,7 +650,7 @@ export async function filterSessionRowsByScope(
 	const warnings: string[] = [];
 	const sessions: SdkSessionRowV1[] = [];
 	for (const row of rows) {
-		const identity = await workspaceIdentity(row.locator.repo);
+		const identity = await workspaceIdentity(row.locator.cwd);
 		let keep: boolean;
 		if (scope === "cwd") keep = identity.canonicalPath === selection.selection.canonicalPath;
 		else if (scope === "worktree")
@@ -496,7 +659,7 @@ export async function filterSessionRowsByScope(
 		if (keep) sessions.push(row);
 		else if (identity.repoRoot === null && identity.commonDir === null)
 			warnings.push(
-				`Session ${row.sessionId} workspace "${row.locator.repo}" is outside Git; excluded by scope ${scope}.`,
+				`Session ${row.sessionId} workspace "${row.locator.cwd}" is outside Git; excluded by scope ${scope}.`,
 			);
 	}
 	return { sessions, warnings };
@@ -563,7 +726,7 @@ async function requestControl(
 	const attachment = attachmentFor(router, sessionId);
 	const response = await router.request(
 		sessionId,
-		{ type: "control_request", operation, input, confirm: args.confirm === true },
+		controlRequestFrame(operation, input, args),
 		attachment.generation,
 		attachment,
 		args.timeoutMs === undefined ? undefined : { timeoutMs: args.timeoutMs },
@@ -572,6 +735,81 @@ async function requestControl(
 	return response;
 }
 
+/** Builds the public CLI control envelope without leaking envelope fields into operation input. */
+export function controlRequestFrame(
+	operation: string,
+	input: JsonRecord,
+	args: Pick<SdkSessionCliArgs, "confirm" | "idempotencyKey">,
+): JsonRecord {
+	return {
+		type: "control_request",
+		operation,
+		input,
+		confirm: args.confirm === true,
+		...(args.idempotencyKey ? { idempotencyKey: args.idempotencyKey } : {}),
+	};
+}
+
+const BROKER_OPERATOR_ABORT_FIELDS = new Set(["mode", "scope", "operator"]);
+
+export function operatorAbortBrokerRequest(
+	sessionId: string,
+	operation: string,
+	input: JsonRecord,
+	args: Pick<SdkSessionCliArgs, "confirm" | "idempotencyKey">,
+): JsonRecord | undefined {
+	if (!Object.hasOwn(input, "operator")) return undefined;
+	if (operation !== "turn.abort")
+		throw new SdkSessionCliError("invalid_input", "operator is only available for terminal turn.abort.", 2);
+	if (input.operator !== true)
+		throw new SdkSessionCliError("invalid_input", "turn.abort operator must be true when provided.", 2);
+	if (input.mode !== "terminal")
+		throw new SdkSessionCliError("invalid_input", 'operator turn.abort requires mode:"terminal".', 2);
+	for (const key of Object.keys(input))
+		if (!BROKER_OPERATOR_ABORT_FIELDS.has(key))
+			throw new SdkSessionCliError(`invalid_input`, `Unknown turn.abort terminal field: ${key}`, 2);
+	if (input.scope !== undefined && input.scope !== "turn" && input.scope !== "owned")
+		throw new SdkSessionCliError("invalid_input", 'operator turn.abort scope must be "turn" or "owned".', 2);
+	if (args.confirm !== true)
+		throw new SdkSessionCliError("invalid_input", "operator terminal abort requires --confirm.", 2);
+	if (!args.idempotencyKey)
+		throw new SdkSessionCliError("invalid_input", "operator terminal abort requires --idempotency-key.", 2);
+	return { sessionId, operation: "turn.abort", input, confirm: true };
+}
+
+async function requestBrokerOperatorAbort(
+	agentDir: string,
+	request: JsonRecord,
+	args: SdkSessionCliArgs,
+): Promise<JsonRecord> {
+	const idempotencyKey = args.idempotencyKey;
+	if (!idempotencyKey)
+		throw new SdkSessionCliError("invalid_input", "operator terminal abort requires --idempotency-key.", 2);
+	const discovery = await readSdkBrokerDiscovery(agentDir);
+	if (!discovery) throw new SdkSessionCliError("session_unavailable", "SDK broker discovery is unavailable.", 1);
+	const timeoutMs = args.timeoutMs ?? SESSION_REQUEST_TIMEOUT_MS;
+	const client = await SdkClient.connect(discovery.url, discovery.token, {
+		timeoutMs,
+		reconnectAttempts: 0,
+	});
+	try {
+		const response = await client.global("session.control", request, {
+			idempotencyKey,
+			timeoutMs,
+		});
+		const result = object(response);
+		if (!result) throw new SdkClientError("protocol_error", "SDK broker returned a malformed control response.");
+		throwResponseFailure(result);
+		return result;
+	} finally {
+		await client.close().catch(error => {
+			process.stderr.write(
+				`SDK broker control cleanup failed: ${error instanceof Error ? error.message : String(error)}\n`,
+			);
+		});
+	}
+}
+
 async function requestQuery(
 	router: SessionRouter,
 	sessionId: string,
@@ -1121,6 +1359,12 @@ async function offlineTailReplay(
 	});
 	if (!outcome.ok)
 		throw new SdkSessionCliError(outcome.error.code, outcome.error.message, 1, { certainty: outcome.certainty });
+	if ("rows" in outcome.result)
+		throw new SdkSessionCliError(
+			"malformed_response",
+			"broker returned a scoped result for retained transcript replay",
+			1,
+		);
 	const savedSession = outcome.result.savedSession;
 	if (!savedSession)
 		throw new SdkSessionCliError(
@@ -1413,6 +1657,8 @@ async function runRawControl(
 	const invalid = validateAdapterControl(operation, input);
 	if (invalid) throw new SdkSessionCliError(invalid.code, invalid.message, 2);
 	await ensureBroker({ agentDir });
+	const operatorRequest = operatorAbortBrokerRequest(sessionId, operation, input, args);
+	if (operatorRequest) return await requestBrokerOperatorAbort(agentDir, operatorRequest, args);
 	return await withRouter(agentDir, async router => await requestControl(router, sessionId, operation, input, args));
 }
 
@@ -1506,6 +1752,7 @@ export async function runSdkSessionCli(
 		const action = args.action;
 		if (
 			action !== "list" &&
+			action !== "search" &&
 			action !== "inspect" &&
 			action !== "send" &&
 			action !== "status" &&
@@ -1526,6 +1773,12 @@ export async function runSdkSessionCli(
 			writeOutput(stripSecretFields(await runList(agentDir, args)));
 			return;
 		}
+		if (action === "search") {
+			const search = await runSdkSearch(args);
+			writeOutput(args.json === true ? search.result : renderSdkSearchTable(search.result));
+			if (search.exitCode !== 0) setExitCode(search.exitCode);
+			return;
+		}
 		if (action === "inspect") {
 			writeOutput(stripSecretFields(await runInspect(agentDir, requireValue(args.sessionId, "<sessionId>"))));
 			return;
@@ -1577,6 +1830,12 @@ export async function runSdkSessionCli(
 		const kind = rawKind(requireValue(action, "<verb>"), args);
 		if (!kind) throw new SdkSessionCliError("usage", "raw requires one of: control, query, global.", 2);
 		const operation = kind === "query" ? requireValue(args.query, "--query") : requireValue(args.operation, "--op");
+		if (isRawSpawnOperation(kind, operation))
+			throw new SdkSessionCliError(
+				"adapter_operation_prohibited",
+				"session.spawn is unavailable through the SDK session CLI.",
+				1,
+			);
 		const dispositionError = cliOperationError(kind, operation);
 		if (dispositionError) throw new SdkSessionCliError(dispositionError.code, dispositionError.message, 1);
 		if (isEndpointOperation(operation))

package/src/sdk/client/client.ts

@@ -116,13 +116,13 @@ export interface SdkDispatchContext {
 	readonly generation: number;
 }
 
-/** Request identity retained after an uncertain send for lifecycle reconciliation. */
-
+/** Request identity retained after an uncertain send. */
 export interface SdkSentRecord {
 	readonly id: string;
 	readonly operation?: string;
 	readonly idempotencyKey?: string;
-	readonly fingerprint: string;
+	/** Present for lifecycle lookups; `session.spawn` replays through its idempotency key. */
+	readonly fingerprint?: string;
 }
 
 export type SdkFrameHandler = (frame: SdkFrame) => void;
@@ -473,8 +473,10 @@ export class SdkClient {
 		const sentOperation = typeof serializedFrame.operation === "string" ? serializedFrame.operation : undefined;
 		const sentIdempotencyKey =
 			typeof serializedFrame.idempotencyKey === "string" ? serializedFrame.idempotencyKey : undefined;
-		const sentFingerprint =
-			typeof serializedFrame.operation === "string"
+		const isSpawn = sentOperation === "session.spawn";
+		const sentFingerprint = isSpawn
+			? undefined
+			: typeof serializedFrame.operation === "string"
 				? lifecycleFingerprint(serializedFrame.operation, serializedFrame.input ?? {})
 				: inputFingerprint(serializedFrame.input ?? {});
 		const deferred = Promise.withResolvers<unknown>();
@@ -571,11 +573,15 @@ export class SdkClient {
 		// nothing reached the transport, so the request stays retryable and
 		// non-uncertain with no record retained.
 		pending.sent = true;
+		// A spawn claim replays only through its caller-provided idempotency key;
+		// it deliberately has no lifecycle fingerprint. Retain the common sent
+		// record anyway so an uncertain transport result tells the caller which
+		// key can join that durable claim.
 		this.#rememberSentRecord({
 			id,
-			operation: sentOperation,
-			idempotencyKey: sentIdempotencyKey,
-			fingerprint: sentFingerprint,
+			...(sentOperation === undefined ? {} : { operation: sentOperation }),
+			...(sentIdempotencyKey === undefined ? {} : { idempotencyKey: sentIdempotencyKey }),
+			...(sentFingerprint === undefined ? {} : { fingerprint: sentFingerprint }),
 		});
 		try {
 			incarnation.socket.send(serializedRequest);

package/src/sdk/host/control/dispatch.ts

@@ -6,7 +6,12 @@ import {
 import { validateRequiredPromptText } from "../../protocol/adapter-validation";
 import { OPERATIONS, type Operation } from "../../protocol/operation-registry";
 import type { ControlInput, ControlSurface, ControlValue } from "./operations";
-import { brokerRuntimeCloseCapability, hasBrokerRuntimeCloseCapability } from "./runtime-gate";
+import {
+	BROKER_RUNTIME_ABORT_CAPABILITY_FIELD,
+	brokerRuntimeCloseCapability,
+	hasBrokerRuntimeAbortCapability,
+	hasBrokerRuntimeCloseCapability,
+} from "./runtime-gate";
 
 export interface ControlRequest {
 	id: string;
@@ -149,29 +154,35 @@ function inputHash(input: unknown): string {
 		.update(JSON.stringify(canonicalize(input)))
 		.digest("hex");
 }
-/**
- * Normalize a WELL-FORMED terminal abort input for the idempotency hash:
- * omitted scope defaults to "turn", so `{mode:"terminal"}` and
- * `{mode:"terminal", scope:"turn"}` share one idempotency key (the durable
- * terminal-scope replay hashes the same normalized payload). Malformed
- * inputs (unknown fields, invalid mode/scope) are left raw so they are
- * rejected downstream and never collide with a valid input's key.
- */
-function normalizeTerminalAbortInputForHash(input: unknown): unknown {
-	if (typeof input !== "object" || input === null) return input;
-	const record = input as Record<string, unknown>;
-	if (record.mode !== "terminal") return input;
-	for (const key of Object.keys(record)) if (!TERMINAL_ABORT_FIELDS.has(key)) return input;
-	const scope = record.scope;
-	if (scope !== undefined && scope !== "turn" && scope !== "owned") return input;
-	return { mode: "terminal", scope: scope === undefined ? "turn" : scope };
+
+export interface TerminalAbortIdentity {
+	input: { mode: "terminal"; scope: "turn" | "owned"; operator?: true };
+	inputHash: string;
+}
+
+/** One strict, capability-free identity shared by dispatch, durable admission, and delivery observation. */
+export function terminalAbortIdentity(input: unknown, operatorAuthorized: boolean): TerminalAbortIdentity | undefined {
+	if (!isInput(input) || input.mode !== "terminal") return undefined;
+	for (const key of Object.keys(input)) if (!TERMINAL_ABORT_FIELDS.has(key)) return undefined;
+	let scope: "turn" | "owned";
+	if (input.scope === undefined || input.scope === "turn") scope = "turn";
+	else if (input.scope === "owned") scope = "owned";
+	else return undefined;
+	if (input.operator !== undefined && input.operator !== true) return undefined;
+	if (input.operator === true && !operatorAuthorized) return undefined;
+	const normalized = {
+		mode: "terminal" as const,
+		scope,
+		...(input.operator === true ? { operator: true as const } : {}),
+	};
+	return { input: normalized, inputHash: inputHash(normalized) };
 }
 
 function text(input: ControlInput, key = "text"): string {
 	return input[key] as string;
 }
 
-const TERMINAL_ABORT_FIELDS = new Set(["mode", "scope"]);
+const TERMINAL_ABORT_FIELDS = new Set(["mode", "scope", "operator"]);
 
 function invalidInput(message: string): never {
 	throw new TypedControlError("invalid_input", message);
@@ -184,15 +195,23 @@ function invalidInput(message: string): never {
  * input is dropped and the ordinary argument-less `surface.abort()` runs.
  *
  * Terminal mode (`mode:"terminal"`) is validated strictly and side-effect-free
- * before any surface call: only `mode`/`scope` fields are accepted, `scope`
- * must be `"turn"` or `"owned"` (default `"turn"`), and a nonempty idempotency
- * key of at most 128 UTF-8 bytes is required on the request envelope. Terminal
- * semantics (see the approved plan): stop the root worker's current turn and
- * block only its own continuation routes; left-running owned work keeps
- * running and its completions are delivered normally so the root worker can
- * resume with a fresh attempt — owned delivery is NOT suppressed.
+ * before any surface call: only `mode`/`scope`/`operator` fields are accepted,
+ * `scope` must be `"turn"` or `"owned"` (default `"turn"`), and a nonempty
+ * idempotency key of at most 128 UTF-8 bytes is required on the request envelope.
+ * A cross-connection local operator must arrive through the Broker route with a
+ * private lifecycle capability, set `operator:true`, and confirm the destructive
+ * control request explicitly. Terminal semantics (see the approved plan) always
+ * stop the root worker's current turn. `scope:"turn"` leaves owned work running
+ * so its completion can resume the root worker; `scope:"owned"` additionally
+ * requires exact causal proof and stops that owned work. Operator authority
+ * changes only connection ownership, never those settlement proofs.
  */
-function invokeAbort(surface: ControlSurface, input: ControlInput, idempotencyKey: string | undefined): ControlValue {
+function invokeAbort(
+	surface: ControlSurface,
+	input: ControlInput,
+	confirm: boolean | undefined,
+	idempotencyKey: string | undefined,
+): ControlValue {
 	const mode = input.mode === undefined ? "turn" : input.mode;
 	if (mode === "turn") return surface.abort();
 	if (mode !== "terminal") invalidInput('turn.abort mode must be "turn" or "terminal".');
@@ -200,12 +219,18 @@ function invokeAbort(surface: ControlSurface, input: ControlInput, idempotencyKe
 		if (!TERMINAL_ABORT_FIELDS.has(key)) invalidInput(`Unknown turn.abort terminal field: ${key}`);
 	const scope = input.scope === undefined ? "turn" : input.scope;
 	if (scope !== "turn" && scope !== "owned") invalidInput('turn.abort terminal scope must be "turn" or "owned".');
+	if (input.operator !== undefined && input.operator !== true)
+		invalidInput("turn.abort terminal operator must be true when provided.");
+	if (input.operator === true && confirm !== true) invalidInput("operator terminal abort requires confirm:true.");
 	if (typeof idempotencyKey !== "string" || idempotencyKey.length === 0)
 		invalidInput("terminal abort requires a nonempty idempotency key.");
 	if (new TextEncoder().encode(idempotencyKey).length > 128)
 		invalidInput("terminal abort idempotency key must be at most 128 UTF-8 bytes.");
 	if (!surface.abortTerminal) invalidInput("terminal abort is not supported by this surface.");
-	return surface.abortTerminal({ mode: "terminal", scope }, idempotencyKey);
+	return surface.abortTerminal(
+		{ mode: "terminal", scope, ...(input.operator === true ? { operator: true } : {}) },
+		idempotencyKey,
+	);
 }
 function invoke(
 	surface: ControlSurface,
@@ -222,7 +247,7 @@ function invoke(
 		case "turn.follow_up":
 			return surface.followUp(text(input));
 		case "turn.abort":
-			return invokeAbort(surface, input, idempotencyKey);
+			return invokeAbort(surface, input, confirm, idempotencyKey);
 		case "turn.abort_and_prompt":
 			return surface.abortAndPrompt(text(input));
 		case "ask.answer":
@@ -404,11 +429,7 @@ function idempotent(
 	const now = Date.now();
 	for (const [key, entry] of requests) if (entry.expiresAt <= now) requests.delete(key);
 	const key = `${row.sdkId}\u0000${request.idempotencyKey}`;
-	// Terminal abort normalizes the omitted scope BEFORE hashing so the
-	// defaulted and explicit shapes share one idempotency key (and reach the
-	// durable terminal-scope replay on eviction); malformed inputs stay raw.
-	const hashInput = row.sdkId === "turn.abort" ? normalizeTerminalAbortInputForHash(request.input) : request.input;
-	const hash = inputHash(hashInput);
+	const hash = inputHash(request.input);
 	const existing = requests.get(key);
 	if (existing) {
 		requests.delete(key);
@@ -445,6 +466,10 @@ export function dispatchControl(
 			failure(request.id, "unknown_operation", `Unknown control operation: ${request.operation}.`),
 		);
 	const brokerCloseAuthorized = row.sdkId === "session.close" && hasBrokerRuntimeCloseCapability(request.input);
+	const brokerAbortInput = row.sdkId === "turn.abort" && isInput(request.input) ? request.input : undefined;
+	const brokerAbortFieldPresent =
+		brokerAbortInput !== undefined && Object.hasOwn(brokerAbortInput, BROKER_RUNTIME_ABORT_CAPABILITY_FIELD);
+	const brokerAbortAuthorized = row.sdkId === "turn.abort" && hasBrokerRuntimeAbortCapability(request.input);
 	if (BROKER_LIFECYCLE_CONTROL_OPERATIONS.has(row.sdkId) && !brokerCloseAuthorized)
 		return Promise.resolve(
 			failure(
@@ -453,6 +478,20 @@ export function dispatchControl(
 				`${request.operation} is available only through the Broker lifecycle service.`,
 			),
 		);
+	if (!isInput(request.input))
+		return Promise.resolve(failure(request.id, "invalid_input", "Control input must be an object."));
+	if (
+		row.sdkId === "turn.abort" &&
+		((brokerAbortFieldPresent && !brokerAbortAuthorized) ||
+			(request.input.operator === true && !brokerAbortAuthorized))
+	)
+		return Promise.resolve(
+			failure(
+				request.id,
+				"operation_prohibited",
+				"Operator terminal aborts are available only through the Broker control route.",
+			),
+		);
 	if (
 		!brokerCloseAuthorized &&
 		surface.installedOperations instanceof Set &&
@@ -461,20 +500,42 @@ export function dispatchControl(
 		return Promise.resolve(
 			failure(request.id, "operation_not_session_owned", `${request.operation} is not installed for this session.`),
 		);
-	if (!isInput(request.input))
-		return Promise.resolve(failure(request.id, "invalid_input", "Control input must be an object."));
-	const promptError = validateRequiredPromptText(row.sdkId, request.input);
+	let dispatchRequest: ControlRequest = request;
+	if (row.sdkId === "turn.abort" && request.input.mode === "terminal") {
+		const publicInput = brokerAbortInput
+			? (() => {
+					const { [BROKER_RUNTIME_ABORT_CAPABILITY_FIELD]: _capability, ...input } = brokerAbortInput;
+					return input;
+				})()
+			: request.input;
+		const identity = terminalAbortIdentity(publicInput, brokerAbortAuthorized);
+		if (!identity)
+			return Promise.resolve(failure(request.id, "invalid_input", "Terminal turn.abort input is malformed."));
+		if (identity.input.operator === true && request.confirm !== true)
+			return Promise.resolve(failure(request.id, "invalid_input", "operator terminal abort requires confirm:true."));
+		if (typeof request.idempotencyKey !== "string" || request.idempotencyKey.length === 0)
+			return Promise.resolve(
+				failure(request.id, "invalid_input", "terminal abort requires a nonempty idempotency key."),
+			);
+		if (new TextEncoder().encode(request.idempotencyKey).length > 128)
+			return Promise.resolve(
+				failure(request.id, "invalid_input", "terminal abort idempotency key must be at most 128 UTF-8 bytes."),
+			);
+		dispatchRequest = { ...request, input: identity.input };
+	}
+	const promptError = validateRequiredPromptText(row.sdkId, dispatchRequest.input as ControlInput);
 	if (promptError) return Promise.resolve(failure(request.id, promptError.code, promptError.message));
 	if ((row.sdkId === "context.clear" || row.sdkId === "session.delete") && request.confirm !== true)
 		return Promise.resolve(
 			failure(request.id, "invalid_input", "confirm: true is required for this destructive operation."),
 		);
-	const work = () => execute(surface, row, request);
+	const work = () => execute(surface, row, dispatchRequest);
 	if (row.sdkId === "turn.abort_and_prompt") {
 		const cancellable = surface as PreflightCancellableSurface;
 		if (Object.hasOwn(cancellable, "cancelPendingPreflights")) cancellable.cancelPendingPreflights?.();
 		return serialize(surface, work);
 	}
-	if (row.idempotency === "idempotent" && request.idempotencyKey) return idempotent(surface, row, request, work);
+	if (row.idempotency === "idempotent" && dispatchRequest.idempotencyKey)
+		return idempotent(surface, row, dispatchRequest, work);
 	return row.idempotency === "ordered" && row.sdkId !== "retry.now" ? serialize(surface, work) : work();
 }