@gajae-code/coding-agent 0.13.2 → 0.14.0

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

@@ -3,9 +3,9 @@ import {
 	DEFAULT_MODEL_SELECTION_RECOVERY_MESSAGE,
 	parseDefaultModelSelectionRecovery,
 } from "../../../session/default-model-selection";
-import { isElevationAllowlisted } from "../../elevation/allowlist";
 import { OPERATIONS, type Operation } from "../../protocol/operation-registry";
 import type { ControlInput, ControlSurface, ControlValue } from "./operations";
+import { brokerRuntimeCloseCapability, hasBrokerRuntimeCloseCapability } from "./runtime-gate";
 
 export interface ControlRequest {
 	id: string;
@@ -14,8 +14,6 @@ export interface ControlRequest {
 	expectedRevision?: string;
 	idempotencyKey?: string;
 	confirm?: boolean;
-	/** Top-level elevation claim selector, preserved from the control frame. */
-	elevationRequestId?: string;
 }
 
 export type ControlErrorCode = string;
@@ -69,8 +67,21 @@ const SHARED_ERROR_CODES = new Set([
 	"cursor_expired",
 	"event_gap",
 	"unavailable",
+	"operation_prohibited",
 	"internal",
 ]);
+
+/** Lifecycle mutations must enter through the Broker-backed lifecycle service. */
+const BROKER_LIFECYCLE_CONTROL_OPERATIONS = new Set([
+	"session.new",
+	"session.fork",
+	"session.resume",
+	"session.switch",
+	"session.branch",
+	"session.handoff",
+	"session.close",
+	"session.delete",
+]);
 const IDEMPOTENCY_TTL_MS = 15 * 60 * 1_000;
 const MAX_IDEMPOTENCY_ENTRIES = 256;
 
@@ -108,11 +119,7 @@ function failure(
 function isInput(value: unknown): value is ControlInput {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/**
- * Build the typed control request from a wire frame. Every runtime transport
- * mapper uses this helper so the top-level elevation claim selector cannot
- * drift between callsites.
- */
+
 export function controlRequestFromFrame(frame: Record<string, unknown>): ControlRequest {
 	return {
 		id: typeof frame.id === "string" ? frame.id : "",
@@ -121,7 +128,6 @@ export function controlRequestFromFrame(frame: Record<string, unknown>): Control
 		expectedRevision: typeof frame.expectedRevision === "string" ? frame.expectedRevision : undefined,
 		idempotencyKey: typeof frame.idempotencyKey === "string" ? frame.idempotencyKey : undefined,
 		confirm: frame.confirm === true,
-		elevationRequestId: typeof frame.elevationRequestId === "string" ? frame.elevationRequestId : undefined,
 	};
 }
 
@@ -142,47 +148,95 @@ 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 };
+}
 
 function text(input: ControlInput, key = "text"): string {
 	return input[key] as string;
 }
 
+const TERMINAL_ABORT_FIELDS = new Set(["mode", "scope"]);
+
+function invalidInput(message: string): never {
+	throw new TypedControlError("invalid_input", message);
+}
+
+/**
+ * C04 `turn.abort` dispatch.
+ *
+ * Legacy behavior (omitted mode or `mode:"turn"`) is preserved verbatim: the
+ * 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.
+ */
+function invokeAbort(surface: ControlSurface, input: ControlInput, 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".');
+	for (const key of Object.keys(input))
+		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 (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);
+}
 function invoke(
 	surface: ControlSurface,
 	operation: string,
 	input: ControlInput,
 	confirm: boolean | undefined,
 	idempotencyKey: string | undefined,
-	elevationRequestId: string | undefined,
 ): Promise<ControlValue> | ControlValue {
 	switch (operation) {
 		case "turn.prompt":
 			return surface.prompt(text(input), input.images, input.clientRef as string | undefined);
 		case "turn.steer":
-			return surface.steer(text(input));
+			return surface.steer(text(input), typeof input.clientRef === "string" ? input.clientRef : undefined);
 		case "turn.follow_up":
 			return surface.followUp(text(input));
 		case "turn.abort":
-			return surface.abort();
+			return invokeAbort(surface, input, idempotencyKey);
 		case "turn.abort_and_prompt":
 			return surface.abortAndPrompt(text(input));
 		case "ask.answer":
 			return surface.answerAsk(text(input, "id"), input.answer);
 		case "workflow.gate_answer":
+			if (idempotencyKey === undefined)
+				return surface.answerGate(text(input, "id"), input.response, input.expectedSessionId as string | undefined);
 			return surface.answerGate(
 				text(input, "id"),
 				input.response,
 				input.expectedSessionId as string | undefined,
 				idempotencyKey,
-				elevationRequestId,
 			);
 		case "workflow.plan_approve":
-			return surface.approvePlan(
-				text(input, "id"),
-				input.choice,
-				input.expectedSessionId as string | undefined,
-				elevationRequestId,
-			);
+			return surface.approvePlan(text(input, "id"), input.choice, input.expectedSessionId as string | undefined);
 		case "skill.invoke":
 			return surface.invokeSkill(
 				text(input, "name"),
@@ -225,22 +279,10 @@ function invoke(
 			return surface.executeBash(text(input, "cmd"));
 		case "bash.abort":
 			return surface.abortBash();
-		case "session.new":
-			return surface.newSession();
-		case "session.fork":
-			return surface.forkSession();
-		case "session.resume":
-			return surface.resumeSession(text(input, "id"));
 		case "session.close":
-			return surface.closeSession();
-		case "session.switch":
-			return surface.switchSession(text(input, "id"));
-		case "session.branch":
-			return surface.branchSession(text(input, "entryId"));
+			return surface.closeSession(brokerRuntimeCloseCapability(input));
 		case "session.rename":
 			return surface.renameSession(text(input, "name"));
-		case "session.handoff":
-			return surface.handoffSession(input.target);
 		case "session.export_html":
 			return surface.exportHtml();
 		case "config.patch":
@@ -270,8 +312,6 @@ function invoke(
 			return surface.setExtensionEnabled(text(input, "id"), input.on as boolean);
 		case "context.clear":
 			return surface.clearContext(confirm === true);
-		case "session.delete":
-			return surface.deleteSession(text(input, "id"), confirm === true);
 		case "session.cwd.move":
 			return surface.moveCwd(text(input, "path"));
 		case "retry.last":
@@ -329,7 +369,6 @@ async function execute(surface: ControlSurface, row: Operation, request: Control
 				request.input as ControlInput,
 				request.confirm,
 				request.idempotencyKey,
-				request.elevationRequestId,
 			),
 		};
 	} catch (error) {
@@ -364,7 +403,11 @@ 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}`;
-	const hash = inputHash(request.input);
+	// 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 existing = requests.get(key);
 	if (existing) {
 		requests.delete(key);
@@ -400,33 +443,25 @@ export function dispatchControl(
 		return Promise.resolve(
 			failure(request.id, "unknown_operation", `Unknown control operation: ${request.operation}.`),
 		);
-	if (surface.installedOperations instanceof Set && !surface.installedOperations.has(row.sdkId))
+	const brokerCloseAuthorized = row.sdkId === "session.close" && hasBrokerRuntimeCloseCapability(request.input);
+	if (BROKER_LIFECYCLE_CONTROL_OPERATIONS.has(row.sdkId) && !brokerCloseAuthorized)
+		return Promise.resolve(
+			failure(
+				request.id,
+				"operation_prohibited",
+				`${request.operation} is available only through the Broker lifecycle service.`,
+			),
+		);
+	if (
+		!brokerCloseAuthorized &&
+		surface.installedOperations instanceof Set &&
+		!surface.installedOperations.has(row.sdkId)
+	)
 		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 elevationEnabled =
-		process.env.GJC_SDK_ELEVATION_ENABLED === "1" || process.env.GJC_SDK_ELEVATION_ENABLED === "true";
-	const elevationAllowlisted = isElevationAllowlisted("control", row.sdkId);
-	const elevationRequired = elevationEnabled && elevationAllowlisted;
-	if (elevationRequired && request.elevationRequestId === undefined)
-		return Promise.resolve(failure(request.id, "elevation_required", `${row.sdkId} requires an elevation grant.`));
-	if (request.elevationRequestId !== undefined) {
-		const claim = request.elevationRequestId.trim();
-		if (!claim || claim.length > 128)
-			return Promise.resolve(
-				failure(request.id, "invalid_input", "elevationRequestId must be a non-empty bounded string."),
-			);
-		if (!elevationAllowlisted)
-			return Promise.resolve(
-				failure(request.id, "invalid_input", "Only allowlisted elevation operations may carry elevationRequestId."),
-			);
-		if (!surface.authorizeElevationClaim?.(row.sdkId, request.input, claim))
-			return Promise.resolve(
-				failure(request.id, "elevation_required", "The elevation claim is not broker-authorized for this control."),
-			);
-	}
 	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."),

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

@@ -8,4 +8,4 @@ export {
 	dispatchControl,
 	TypedControlError,
 } from "./dispatch";
-export type { ControlInput, ControlSurface, ControlValue } from "./operations";
+export type { AbortScope, ControlInput, ControlSurface, ControlValue } from "./operations";

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

@@ -1,4 +1,17 @@
 export type ControlValue = unknown;
+export type AbortMode = "turn" | "terminal";
+export type AbortScope = "turn" | "owned";
+
+/**
+ * Terminal-mode C04 `turn.abort` input. `scope` selects whether exact causal
+ * owned work (background Bash/task jobs, detached subagents) is also stopped
+ * (`"owned"`) or left running so its completion can resume the root worker
+ * (`"turn"`, the default).
+ */
+export interface TerminalAbortInput {
+	mode: "terminal";
+	scope?: AbortScope;
+}
 export type ControlInput = Record<string, unknown>;
 
 /**
@@ -6,11 +19,12 @@ export type ControlInput = Record<string, unknown>;
  * AgentSession and its controllers without exposing those concrete types here.
  */
 export interface ControlSurface {
-	authorizeElevationClaim?(sdkId: string, input: ControlInput, capability: string): boolean;
 	prompt(text: string, images?: ControlValue, clientRef?: string): Promise<ControlValue> | ControlValue;
-	steer(text: string): Promise<ControlValue> | ControlValue;
+	steer(text: string, clientRef?: string): Promise<ControlValue> | ControlValue;
 	followUp(text: string): Promise<ControlValue> | ControlValue;
 	abort(): Promise<ControlValue> | ControlValue;
+	/** Terminal abort: stop the current root turn (and optionally exact owned work). */
+	abortTerminal?(input: TerminalAbortInput, idempotencyKey?: string): Promise<ControlValue> | ControlValue;
 	abortAndPrompt(text: string): Promise<ControlValue> | ControlValue;
 	answerAsk(id: string, answer: ControlValue): Promise<ControlValue> | ControlValue;
 	answerGate(
@@ -18,14 +32,8 @@ export interface ControlSurface {
 		response: ControlValue,
 		expectedSessionId?: string,
 		idempotencyKey?: string,
-		elevationRequestId?: string,
-	): Promise<ControlValue> | ControlValue;
-	approvePlan(
-		id: string,
-		choice: ControlValue,
-		expectedSessionId?: string,
-		elevationRequestId?: string,
 	): Promise<ControlValue> | ControlValue;
+	approvePlan(id: string, choice: ControlValue, expectedSessionId?: string): Promise<ControlValue> | ControlValue;
 	invokeSkill(name: string, args: ControlValue, clientRef?: string): Promise<ControlValue> | ControlValue;
 	setPlanMode(on: boolean): Promise<ControlValue> | ControlValue;
 	operateGoal(op: string, objective?: string): Promise<ControlValue> | ControlValue;
@@ -46,7 +54,7 @@ export interface ControlSurface {
 	newSession(): Promise<ControlValue> | ControlValue;
 	forkSession(): Promise<ControlValue> | ControlValue;
 	resumeSession(id: string): Promise<ControlValue> | ControlValue;
-	closeSession(): Promise<ControlValue> | ControlValue;
+	closeSession(capability?: string): Promise<ControlValue> | ControlValue;
 	switchSession(id: string): Promise<ControlValue> | ControlValue;
 	branchSession(entryId: string): Promise<ControlValue> | ControlValue;
 	renameSession(name: string): Promise<ControlValue> | ControlValue;

package/src/sdk/host/control/runtime-gate.ts

@@ -0,0 +1,40 @@
+/**
+ * Private field carried only on the Broker's endpoint close request.
+ *
+ * The value is the lifecycle effect marker bound to the serving process. It is
+ * never published in endpoint discovery or lifecycle service results; callers
+ * that do not hold the Broker's indexed lifecycle record cannot satisfy this
+ * gate.
+ */
+export const BROKER_RUNTIME_CLOSE_CAPABILITY_FIELD = "__gjcBrokerCloseCapability";
+const EXPECTED_BROKER_RUNTIME_CLOSE_CAPABILITY = process.env.GJC_LIFECYCLE_REQUEST_ID;
+
+function record(value: unknown): Record<string, unknown> | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+
+export function brokerRuntimeCloseCapability(input: unknown): string | undefined {
+	const value = record(input)?.[BROKER_RUNTIME_CLOSE_CAPABILITY_FIELD];
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/** Remove the private close capability before a request is exposed to diagnostics. */
+export function redactBrokerRuntimeCloseCapability(frame: Record<string, unknown>): Record<string, unknown> {
+	if (frame.type !== "control_request" || frame.operation !== "session.close") return frame;
+	const input = record(frame.input);
+	if (!input || !Object.hasOwn(input, BROKER_RUNTIME_CLOSE_CAPABILITY_FIELD)) return frame;
+	const { [BROKER_RUNTIME_CLOSE_CAPABILITY_FIELD]: _capability, ...publicInput } = input;
+	return { ...frame, input: publicInput };
+}
+
+/**
+ * Runtime-local authority check for the Broker-only graceful close executor.
+ *
+ * A lifecycle child receives GJC_LIFECYCLE_REQUEST_ID from the Broker launch
+ * environment. Generic SDK requests never receive that private marker.
+ */
+export function hasBrokerRuntimeCloseCapability(input: unknown): boolean {
+	const expected = EXPECTED_BROKER_RUNTIME_CLOSE_CAPABILITY;
+	const actual = brokerRuntimeCloseCapability(input);
+	return typeof expected === "string" && expected.length > 0 && actual === expected;
+}

package/src/sdk/host/host.ts

@@ -1,3 +1,5 @@
+import { logger } from "@gajae-code/utils";
+import { redactBrokerRuntimeCloseCapability } from "./control/runtime-gate";
 import { type EventFrame, SessionEventStream } from "./events";
 import { type ProviderLease, ReverseLeaseError, ReverseLeaseRuntime } from "./reverse-leases";
 import type { BrokerIndexWriter, HostEndpointAdapters, SdkFrame } from "./types";
@@ -43,6 +45,8 @@ export type SessionActivationGate = (input: { sessionId: string; generation: num
 export interface SessionSdkHostOptions extends HostEndpointAdapters {
 	control?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
 	query?: (connectionId: string, frame: SdkFrame) => unknown | Promise<unknown>;
+	/** Test/lifecycle seam invoked synchronously before fire-and-forget dispatch. */
+	onFrameAdmitted?: (connectionId: string, frame: SdkFrame) => void;
 	/** Best-effort diagnostic observation of accepted control/query frames. */
 	onRequest?: SdkRequestObserver;
 	/** Runs before a control response is sent; identity transitions use sendTerminal. */
@@ -50,10 +54,22 @@ export interface SessionSdkHostOptions extends HostEndpointAdapters {
 		connectionId: string,
 		request: SdkFrame,
 		response: SdkFrame,
-		sendTerminal: () => Promise<void>,
+		sendTerminal: () => Promise<unknown>,
 	) => void | Promise<void>;
 	/** Runs only after a successful control response has been sent to the client. */
 	afterControlResponse?: (connectionId: string, request: SdkFrame, response: SdkFrame) => void | Promise<void>;
+	/**
+	 * Classifies the awaited control-response write exactly once: `written`
+	 * (sent), `rejected` (the write threw), or `dropped` (the send adapter
+	 * deliberately skipped delivery). `afterControlResponse` runs only
+	 * on `written`. Used to persist monotonic response-state transitions.
+	 */
+	onControlResponseDelivery?: (
+		connectionId: string,
+		request: SdkFrame,
+		response: SdkFrame,
+		outcome: "written" | "rejected" | "dropped",
+	) => void | Promise<void>;
 	installProviderDefinitions?: (capability: string, definitions: unknown) => void;
 	onProviderDefinitionsRemoved?: (capability: string) => void;
 	onReverseCancel?: (requestId: string, reason: "provider_disconnected" | "lease_released") => void;
@@ -69,8 +85,11 @@ export interface SessionSdkHostOptions extends HostEndpointAdapters {
 	activationGate?: SessionActivationGate;
 }
 
-const TOOL_ACTIVITY_CAPABILITY = "tool_activity_v2";
-const CAP_GATED_FRAME_KINDS = new Set(["tool_activity", "reasoning_summary"]);
+/** Shared by the replay filter and transport live broadcasts: a connection
+ *  must see the same capability-gated event kinds on both legs, or live and
+ *  replay delivery diverge for the same subscriber. */
+export const TOOL_ACTIVITY_CAPABILITY = "tool_activity_v2";
+export const CAP_GATED_FRAME_KINDS: ReadonlySet<string> = new Set(["tool_activity", "reasoning_summary"]);
 const EMPTY_CAPABILITIES: ReadonlySet<string> = new Set();
 
 /** Safe, identifier-free explanations for every refused activation status. */
@@ -239,6 +258,7 @@ export class SessionSdkHost {
 				generation: this.events.generation,
 			});
 		const disposer = this.#options.onFrame((connectionId, frame) => {
+			this.#options.onFrameAdmitted?.(connectionId, frame);
 			void this.#onFrame(connectionId, frame);
 		});
 		this.#unsubscribe = typeof disposer === "function" ? disposer : undefined;
@@ -353,8 +373,8 @@ export class SessionSdkHost {
 			});
 	}
 
-	async #send(connectionId: string, frame: SdkFrame): Promise<void> {
-		await this.#options.sendFrame(connectionId, frame);
+	async #send(connectionId: string, frame: SdkFrame): Promise<"written" | "dropped"> {
+		return await this.#options.sendFrame(connectionId, frame);
 	}
 
 	/**
@@ -395,14 +415,45 @@ export class SessionSdkHost {
 					if (result !== undefined) {
 						const response = { type: "control_response", ...(result as SdkFrame) };
 						let terminalSent = false;
-						const sendTerminal = async (): Promise<void> => {
-							if (terminalSent) return;
+						let sendOutcome: "written" | "rejected" | "dropped" = "dropped";
+						const sendTerminal = async (): Promise<"written" | "rejected" | "dropped"> => {
+							// Repeat calls (early hook send + fallback) return the FIRST,
+							// actual outcome — never a false dropped for an already
+							// written response (early-identity-rotation pattern).
+							if (terminalSent) return sendOutcome;
 							terminalSent = true;
-							await this.#send(connectionId, response);
+							try {
+								const outcome = await this.#send(connectionId, response);
+								sendOutcome = outcome === "written" ? "written" : "dropped";
+							} catch {
+								sendOutcome = "rejected";
+							}
+							return sendOutcome;
 						};
-						await this.#options.beforeControlResponse?.(connectionId, frame, response, sendTerminal);
-						await sendTerminal();
-						await this.#options.afterControlResponse?.(connectionId, frame, response);
+						try {
+							await this.#options.beforeControlResponse?.(connectionId, frame, response, sendTerminal);
+							// Fallback: if the before hook did not send early (identity
+							// rotation), the response is always sent here.
+							if (!terminalSent) sendOutcome = await sendTerminal();
+						} finally {
+							// Classify exactly once, immediately after the send attempt and
+							// BEFORE the optional post-write hook, so a rejected/dropped
+							// write (or an afterControlResponse throw) never mislabels it.
+							try {
+								await this.#options.onControlResponseDelivery?.(connectionId, frame, response, sendOutcome);
+							} catch (error) {
+								// Contain observer persistence failures: the response was already
+								// sent (or classified) and its delivery state recorded; rethrowing
+								// would escape into the outer #onFrame catch and send a SECOND
+								// control_response for the same request id (review thread P2).
+								logger.warn("sdk control delivery observer failed", {
+									error: error instanceof Error ? error.message : String(error),
+								});
+							}
+						}
+						if (sendOutcome === "written") {
+							await this.#options.afterControlResponse?.(connectionId, frame, response);
+						}
 					}
 					break;
 				}
@@ -542,7 +593,7 @@ export class SessionSdkHost {
 	}
 	#observeRequest(kind: "control" | "query", connectionId: string, frame: SdkFrame): void {
 		try {
-			this.#options.onRequest?.(kind, connectionId, frame);
+			this.#options.onRequest?.(kind, connectionId, redactBrokerRuntimeCloseCapability(frame));
 		} catch {
 			// Diagnostic observers must not change request handling.
 		}

package/src/sdk/host/query/handlers.ts

@@ -1,7 +1,10 @@
 import { randomUUID } from "node:crypto";
 import { PROMPT_CLIENT_REF_MAX_LENGTH } from "../../prompt-status.js";
+import { TURN_RESULT_PROMPT_ALIAS, TURN_RESULT_SKILL_ALIAS } from "../../protocol/operation-registry.js";
+
 import type { ActiveProviderDescriptor } from "../../providers.js";
 import { ActiveProviderResolutionError } from "../../providers.js";
+
 import {
 	assertCursorSelector,
 	type CursorEnvelope,
@@ -61,6 +64,7 @@ export interface SessionSurface {
 		commandId?: string;
 		turnId?: string;
 	}): unknown | Promise<unknown>;
+	getSteerStatus?(selector: { commandId?: string; turnId?: string; clientRef?: string }): unknown | Promise<unknown>;
 	/** Q27 effective model-profile catalog from the live session registry. */
 	getModelProfiles?(): unknown[] | Promise<unknown[]>;
 	/**
@@ -175,9 +179,11 @@ const names = [
 	"runtime.jobs.list",
 	"turn.result",
 	"models.profiles.list",
-	"skill.invoke_status",
+	// Q28 was folded into Q26; retain the vacant slot so Q29/Q30 remain stable.
+	undefined,
 	"providers.list/active",
 	"session.checkpoint",
+	"turn.steer_status",
 ];
 
 export class QueryHandlers {
@@ -199,8 +205,9 @@ export class QueryHandlers {
 					);
 				return await this.#turnResult(request);
 			}
-			if (request.query === "turn.prompt_status") return await this.#promptTurnResult(request);
-			if (request.query === "skill.invoke_status") return await this.#skillTurnResult(request);
+			if (request.query === TURN_RESULT_PROMPT_ALIAS) return await this.#promptTurnResult(request);
+
+			if (request.query === TURN_RESULT_SKILL_ALIAS) return await this.#skillTurnResult(request);
 
 			const query = request.query.startsWith("Q")
 				? request.query
@@ -217,7 +224,7 @@ export class QueryHandlers {
 					);
 				return await this.#turnResult(request);
 			}
-			if (query === "Q28") return await this.#skillTurnResult(request);
+
 			if (
 				this.surface.installedQueries instanceof Set &&
 				!this.surface.installedQueries.has(names[Number(query.slice(1)) - 1] ?? "")
@@ -252,6 +259,7 @@ export class QueryHandlers {
 			if (query === "Q23") return await this.#resourceBody(request);
 			if (query === "Q24") return await this.#artifact(request);
 			if (query === "Q30") return await this.#checkpoint(request);
+			if (query === "Q31") return await this.#steerStatus(request);
 			if (query === "Q27" && request.input && Object.keys(request.input).length > 0)
 				return this.#error(request, "invalid_request", false, "models.profiles.list does not accept input fields.");
 			if (query === "Q27" && typeof this.surface.getModelProfiles !== "function")
@@ -581,7 +589,8 @@ export class QueryHandlers {
 		// unreachable: the bounded content cap is well under both RESPONSE_CEILING_BYTES
 		// and TARGET_PAGE_BYTES, so no revision is ever created. Reject cursors
 		// upfront instead of advertising a continuation path that can never fire.
-		if (request.cursor) return this.#error(request, "invalid_cursor", false, "turn.result does not support cursors.");
+		if (request.cursor !== undefined)
+			return this.#error(request, "invalid_request", false, "turn.result does not support cursors.");
 		if (typeof this.surface.getTurnResult !== "function") return this.#error(request, "unavailable");
 		const result = await this.surface.getTurnResult({
 			kind,
@@ -637,12 +646,12 @@ export class QueryHandlers {
 		return await this.#turnResult({ ...request, input: { ...input, kind: "prompt" } });
 	}
 	async #skillTurnResult(request: QueryRequest): Promise<QueryResponse> {
-		if (this.surface.installedQueries instanceof Set && !this.surface.installedQueries.has("skill.invoke_status"))
+		if (this.surface.installedQueries instanceof Set && !this.surface.installedQueries.has("turn.result"))
 			return this.#error(
 				request,
 				"operation_not_session_owned",
 				false,
-				"skill.invoke_status is not installed for this session.",
+				"turn.result is not installed for this session.",
 			);
 		const input = request.input ?? {};
 		if (input.kind !== undefined && input.kind !== "skill")
@@ -779,6 +788,56 @@ export class QueryHandlers {
 		return { id: request.id, ok: true, page };
 	}
 
+	async #steerStatus(request: QueryRequest): Promise<QueryResponse> {
+		if (request.cursor)
+			return this.#error(request, "invalid_request", false, "turn.steer_status does not support cursors.");
+		const input = request.input ?? {};
+		for (const key of Object.keys(input))
+			if (key !== "commandId" && key !== "turnId" && key !== "clientRef")
+				return this.#error(
+					request,
+					"invalid_request",
+					false,
+					`turn.steer_status does not accept selector field "${key}".`,
+				);
+		const commandId = typeof input.commandId === "string" && input.commandId ? input.commandId : undefined;
+		const turnId = typeof input.turnId === "string" && input.turnId ? input.turnId : undefined;
+		const rawClientRef = typeof input.clientRef === "string" ? input.clientRef : undefined;
+		const clientRef = rawClientRef?.trim() || undefined;
+		if (rawClientRef !== undefined && (!clientRef || clientRef.length > PROMPT_CLIENT_REF_MAX_LENGTH))
+			return this.#error(
+				request,
+				"invalid_request",
+				false,
+				"clientRef must be a non-empty string of at most 128 characters.",
+			);
+		if ((commandId === undefined) !== (turnId === undefined))
+			return this.#error(request, "invalid_request", false, "commandId and turnId must be provided together.");
+		if (commandId !== undefined && clientRef !== undefined)
+			return this.#error(
+				request,
+				"invalid_request",
+				false,
+				"Provide exactly one selector: a commandId/turnId pair or a clientRef.",
+			);
+		if (commandId === undefined && clientRef === undefined)
+			return this.#error(
+				request,
+				"invalid_request",
+				false,
+				"turn.steer_status requires a commandId/turnId pair or a clientRef.",
+			);
+		if (typeof this.surface.getSteerStatus !== "function")
+			return this.#error(request, "unavailable", false, "turn.steer_status is unavailable for this session.");
+		return {
+			id: request.id,
+			ok: true,
+			result: await this.surface.getSteerStatus(
+				clientRef !== undefined ? { clientRef } : { commandId: commandId!, turnId: turnId! },
+			),
+		};
+	}
+
 	#error(request: QueryRequest, code: string, restartQuery = false, message = code, details?: unknown): QueryResponse {
 		return {
 			id: request.id,

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

@@ -57,7 +57,7 @@ interface Outstanding {
 export interface ReverseLeaseOptions {
 	now?: () => number;
 	leaseTtlMs?: number;
-	sendFrame: (connectionId: string, frame: SdkFrame) => void | Promise<void>;
+	sendFrame: (connectionId: string, frame: SdkFrame) => unknown;
 	installDefinitions?: (capability: string, definitions: unknown) => void;
 	onCancel?: (requestId: string, reason: "provider_disconnected" | "lease_released") => void;
 	onDefinitionsRemoved?: (capability: string) => void;
@@ -245,7 +245,7 @@ export class ReverseLeaseRuntime {
 					return;
 				}
 			}
-			let delivery: void | Promise<void>;
+			let delivery: unknown;
 			try {
 				delivery = this.#sendFrame(lease.connectionId, {
 					type: "reverse_request",