@gajae-code/coding-agent 0.15.6 → 0.16.1

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":
@@ -266,8 +291,8 @@ function invoke(
 			return surface.setQueueMode("steering", input.mode);
 		case "queue.follow_up_mode.set":
 			return surface.setQueueMode("follow_up", input.mode);
-		case "queue.interrupt_mode.set":
-			return surface.setQueueMode("interrupt", input.mode);
+		case "queue.tool_interrupt_policy.set":
+			return surface.setQueueMode("tool_interrupt", input.mode);
 		case "compaction.run":
 			return surface.runCompaction();
 		case "compaction.auto.set":
@@ -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();
 }

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

@@ -6,6 +6,8 @@ export {
 	type ControlResponse,
 	controlRequestFromFrame,
 	dispatchControl,
+	type TerminalAbortIdentity,
 	TypedControlError,
+	terminalAbortIdentity,
 } from "./dispatch";
 export type { AbortScope, ControlInput, ControlSurface, ControlValue } from "./operations";

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

@@ -11,6 +11,8 @@ export type AbortScope = "turn" | "owned";
 export interface TerminalAbortInput {
 	mode: "terminal";
 	scope?: AbortScope;
+	/** Broker-authorized local override; public SDK callers cannot grant this authority. */
+	operator?: boolean;
 }
 export type ControlInput = Record<string, unknown>;
 

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

@@ -1,13 +1,19 @@
+import { findOperation } from "../../protocol/operation-registry";
+
 /**
- * Private field carried only on the Broker's endpoint close request.
+ * Private fields carried only on Broker-authorized endpoint controls.
  *
- * 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.
+ * Their values are lifecycle effect markers bound to the serving process. They
+ * are never published in endpoint discovery or lifecycle service results;
+ * callers that do not hold the Broker's indexed lifecycle record cannot satisfy
+ * either gate.
  */
 export const BROKER_RUNTIME_CLOSE_CAPABILITY_FIELD = "__gjcBrokerCloseCapability";
+/** Private field carried only on the Broker-authorized terminal-abort request. */
+export const BROKER_RUNTIME_ABORT_CAPABILITY_FIELD = "__gjcBrokerAbortCapability";
 const EXPECTED_BROKER_RUNTIME_CLOSE_CAPABILITY = process.env.GJC_LIFECYCLE_REQUEST_ID;
+const EXPECTED_BROKER_RUNTIME_ABORT_CAPABILITY = process.env.GJC_LIFECYCLE_REQUEST_ID;
+let brokerRuntimeAbortCapabilityOverrideForTest: string | undefined;
 
 function record(value: unknown): Record<string, unknown> | undefined {
 	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
@@ -18,13 +24,188 @@ export function brokerRuntimeCloseCapability(input: unknown): string | undefined
 	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;
+export function brokerRuntimeAbortCapability(input: unknown): string | undefined {
+	const value = record(input)?.[BROKER_RUNTIME_ABORT_CAPABILITY_FIELD];
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/** Remove private Broker capabilities before a request is exposed to diagnostics. */
+export function redactBrokerRuntimeCapabilities(frame: Record<string, unknown>): Record<string, unknown> {
+	if (frame.type !== "control_request") 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 };
+	if (!input) return frame;
+	let redacted = false;
+	const publicInput: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(input)) {
+		if (key === BROKER_RUNTIME_CLOSE_CAPABILITY_FIELD || key === BROKER_RUNTIME_ABORT_CAPABILITY_FIELD) {
+			redacted = true;
+			continue;
+		}
+		publicInput[key] = value;
+	}
+	return redacted ? { ...frame, input: publicInput } : frame;
+}
+
+/**
+ * Frame-level keys an observer may see. `SdkFrame` is an open
+ * `Record<string, unknown>` and `#observeRequest` runs BEFORE dispatch
+ * validation, so an adversarial or malformed frame can carry content under any
+ * top-level key. Only structural routing values survive. `idempotencyKey`,
+ * `id`, and other correlation values are caller-chosen and are deliberately
+ * absent; so are `cursor` (a signed pagination token that can carry
+ * session/revision data) and `expectedRevision` (no diagnostic consumer reads
+ * it). Even allowlisted routing names are checked against their protocol
+ * values below: a field-name allowlist alone is fail-open for scalar secrets.
+ */
+const OBSERVABLE_FRAME_FIELDS = new Set(["type", "operation", "query"]);
+
+/**
+ * Frame keys whose value must match an exact expected type to survive.
+ * `confirm` is a structural destructive-op gate, so only the boolean form is
+ * routing information; a caller-authored string under that name is content.
+ */
+const OBSERVABLE_TYPED_FRAME_FIELDS: Readonly<Record<string, "boolean">> = { confirm: "boolean" };
+
+const OBSERVABLE_FRAME_LITERAL_FIELDS: Readonly<Record<string, ReadonlySet<string>>> = {
+	type: new Set(["control_request", "query_request"]),
+};
+
+const OBSERVER_MARKER_MAX_COUNT = 4096;
+
+/**
+ * Input fields an observer may see. This is an ALLOWLIST on purpose: a
+ * denylist is fail-open, so every unlisted or newly added field would leak by
+ * default. Only structural routing/correlation values are preserved; all other
+ * values are caller content and are replaced with a shape marker.
+ */
+const OBSERVABLE_INPUT_FIELDS = new Set(["mode", "scope", "kind", "level", "on", "confirm"]);
+
+/**
+ * Input fields that carry a finite protocol value. Correlation identifiers,
+ * names, and operation arguments remain redacted even when they look like
+ * ordinary identifiers: callers are free to put arbitrary content in them.
+ */
+const OBSERVABLE_INPUT_LITERAL_FIELDS: Readonly<Record<string, ReadonlySet<string>>> = {
+	mode: new Set([
+		"turn",
+		"terminal",
+		"owned",
+		"allow",
+		"always-allow",
+		"deny",
+		"always-deny",
+		"prompt",
+		"all",
+		"one-at-a-time",
+		"immediate",
+		"wait",
+	]),
+	scope: new Set(["turn", "owned"]),
+	kind: new Set(["prompt", "skill"]),
+	level: new Set(["inherit", "off", "minimal", "low", "medium", "high", "xhigh", "max"]),
+};
+
+const OBSERVABLE_INPUT_TYPED_FIELDS: Readonly<Record<string, "boolean">> = {
+	on: "boolean",
+	confirm: "boolean",
+};
+
+/** Replaces caller content with a shape-preserving marker for observers. */
+function redactedContentMarker(value: unknown): string {
+	if (typeof value === "string") {
+		const count = Math.min(value.length, OBSERVER_MARKER_MAX_COUNT);
+		return `[redacted ${count}${value.length > count ? "+" : ""} chars]`;
+	}
+	if (Array.isArray(value)) {
+		const count = Math.min(value.length, OBSERVER_MARKER_MAX_COUNT);
+		return `[redacted ${count}${value.length > count ? "+" : ""} items]`;
+	}
+	if (value !== null && typeof value === "object") {
+		const fields = Object.keys(value).length;
+		const count = Math.min(fields, OBSERVER_MARKER_MAX_COUNT);
+		return `[redacted ${count}${fields > count ? "+" : ""} fields]`;
+	}
+	return "[redacted]";
+}
+
+function setObservedField(target: Record<string, unknown>, key: string, value: unknown): void {
+	Object.defineProperty(target, key, { configurable: true, enumerable: true, writable: true, value });
+}
+
+function observableFrameValue(key: string, value: unknown): unknown {
+	const requiredType = OBSERVABLE_TYPED_FRAME_FIELDS[key];
+	if (requiredType !== undefined) return typeof value === requiredType ? value : redactedContentMarker(value);
+	if (key === "operation" || key === "query") {
+		const known =
+			findOperation("control", String(value)) ??
+			findOperation("global", String(value)) ??
+			findOperation("query", String(value)) ??
+			findOperation("reverse", String(value));
+		return typeof value === "string" && value.length <= 128 && known !== undefined
+			? value
+			: redactedContentMarker(value);
+	}
+	const allowed = OBSERVABLE_FRAME_LITERAL_FIELDS[key];
+	return allowed?.has(typeof value === "string" ? value : "") ? value : redactedContentMarker(value);
+}
+
+/**
+ * Strips caller content from a request frame before it reaches a diagnostic
+ * observer. Known protocol operation names and finite enum values survive so
+ * instrumentation stays useful; caller-chosen ids and all other values are
+ * redacted, including nested objects, so a field this module has never heard
+ * of cannot leak.
+ */
+export function redactObservedRequestContent(frame: Record<string, unknown>): Record<string, unknown> {
+	const observed: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(frame)) {
+		if (value === undefined) continue;
+		if (key === "input") {
+			const input = record(value);
+			// A non-record payload is content, not "nothing to redact". Returning
+			// early here would hand a string or array `input` through verbatim.
+			setObservedField(
+				observed,
+				key,
+				input === undefined ? redactedContentMarker(value) : redactObservedInput(input),
+			);
+			continue;
+		}
+		// Structural routing scalars survive; every other top-level key, including
+		// one this module has never heard of, is redacted.
+		setObservedField(
+			observed,
+			key,
+			OBSERVABLE_FRAME_FIELDS.has(key) || Object.hasOwn(OBSERVABLE_TYPED_FRAME_FIELDS, key)
+				? observableFrameValue(key, value)
+				: redactedContentMarker(value),
+		);
+	}
+	return observed;
+}
+
+/** Redacts one input payload, preserving only structural scalar routing fields. */
+function redactObservedInput(input: Record<string, unknown>): Record<string, unknown> {
+	const redacted: Record<string, unknown> = {};
+	for (const [field, value] of Object.entries(input)) {
+		if (value === undefined) continue;
+		const requiredType = OBSERVABLE_INPUT_TYPED_FIELDS[field];
+		if (requiredType !== undefined) {
+			setObservedField(redacted, field, typeof value === requiredType ? value : redactedContentMarker(value));
+			continue;
+		}
+		const allowed = OBSERVABLE_INPUT_LITERAL_FIELDS[field];
+		// A finite protocol value is safe; every caller-chosen scalar, including
+		// an allowlisted field with a forged string, is content and is redacted.
+		setObservedField(
+			redacted,
+			field,
+			OBSERVABLE_INPUT_FIELDS.has(field) && allowed?.has(typeof value === "string" ? value : "")
+				? value
+				: redactedContentMarker(value),
+		);
+	}
+	return redacted;
 }
 
 /**
@@ -38,3 +219,14 @@ export function hasBrokerRuntimeCloseCapability(input: unknown): boolean {
 	const actual = brokerRuntimeCloseCapability(input);
 	return typeof expected === "string" && expected.length > 0 && actual === expected;
 }
+
+/** Test-only override for the abort gate; production authority remains process-local. */
+export function setBrokerRuntimeAbortCapabilityForTest(capability: string | undefined): void {
+	brokerRuntimeAbortCapabilityOverrideForTest = capability;
+}
+
+export function hasBrokerRuntimeAbortCapability(input: unknown): boolean {
+	const expected = brokerRuntimeAbortCapabilityOverrideForTest ?? EXPECTED_BROKER_RUNTIME_ABORT_CAPABILITY;
+	const actual = brokerRuntimeAbortCapability(input);
+	return typeof expected === "string" && expected.length > 0 && actual === expected;
+}

package/src/sdk/host/events.ts

@@ -2,6 +2,7 @@ import type { SdkFrame } from "./types";
 
 export interface EventFrame extends SdkFrame {
 	type: "event";
+	revision?: number;
 	generation: number;
 	seq: number;
 }

package/src/sdk/host/host.ts

@@ -1,6 +1,6 @@
 import { logger } from "@gajae-code/utils";
 import { AUTOROUTING_INACTIVE_WARNING } from "../../config/autorouting-contract";
-import { redactBrokerRuntimeCloseCapability } from "./control/runtime-gate";
+import { redactBrokerRuntimeCapabilities, redactObservedRequestContent } from "./control/runtime-gate";
 import { type EventFrame, SessionEventStream } from "./events";
 import { isAutoroutingInactive } from "./internal-autorouting-state";
 import { type ProviderLease, ReverseLeaseError, ReverseLeaseRuntime } from "./reverse-leases";
@@ -88,6 +88,12 @@ export interface SessionSdkHostOptions extends HostEndpointAdapters {
 	 * that fails is never read as authorization.
 	 */
 	activationGate?: SessionActivationGate;
+	/** Private one-shot master-capability verification; never durable or public SDK surface. */
+	masterCapabilityVerify?: (frame: { nonce: unknown; attestationEpoch: unknown; capability: unknown }) => {
+		ok: boolean;
+		nonce: string;
+		attestationEpoch: string;
+	};
 }
 
 /** Shared by the replay filter and transport live broadcasts: a connection
@@ -348,6 +354,8 @@ export class SessionSdkHost {
 			if (this.events.generation !== generation) return "generation_changed";
 			if (this.#readyGeneration === generation) return "already";
 		}
+		if (!this.#started || this.#stopping) return "not_prepared";
+		if (this.events.generation !== generation) return "generation_changed";
 		this.#publishReadiness();
 		return "activated";
 	}
@@ -416,6 +424,21 @@ export class SessionSdkHost {
 				return;
 			}
 			switch (frame.type) {
+				case "master_capability_verify": {
+					const result = this.#options.masterCapabilityVerify?.({
+						nonce: frame.nonce,
+						attestationEpoch: frame.attestationEpoch,
+						capability: frame.capability,
+					}) ?? { ok: false, nonce: "", attestationEpoch: "" };
+					await this.#send(connectionId, {
+						type: "master_capability_verify_result",
+						id: typeof frame.id === "string" ? frame.id : "",
+						ok: result.ok,
+						nonce: result.nonce,
+						attestationEpoch: result.attestationEpoch,
+					});
+					break;
+				}
 				case "control_request": {
 					this.#observeRequest("control", connectionId, frame);
 					// Deferred readiness withholds `session_ready`, but the control
@@ -616,7 +639,11 @@ export class SessionSdkHost {
 	}
 	#observeRequest(kind: "control" | "query", connectionId: string, frame: SdkFrame): void {
 		try {
-			this.#options.onRequest?.(kind, connectionId, redactBrokerRuntimeCloseCapability(frame));
+			this.#options.onRequest?.(
+				kind,
+				connectionId,
+				redactObservedRequestContent(redactBrokerRuntimeCapabilities(frame)),
+			);
 		} catch {
 			// Diagnostic observers must not change request handling.
 		}

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

@@ -18,6 +18,7 @@ export interface CursorEnvelope {
 	issuedAt?: number;
 	/** TTL metadata minted by `CursorRegistry.grant`: wall-clock ms when the cursor expires. */
 	expiresAt?: number;
+	purpose?: "checkpoint";
 	position: unknown;
 	direction: string;
 	pageShape: unknown;
@@ -68,6 +69,7 @@ export interface CursorQueryContext {
 	resourceId?: string;
 	direction: string;
 	pageShape: unknown;
+	purpose?: "checkpoint";
 }
 
 export class CursorError extends Error {
@@ -170,26 +172,68 @@ export class CursorRegistry {
 		cursor: string,
 		connectionId: string,
 		expected: CursorQueryContext,
-		resourceKind: string,
+		_resourceKind: string,
 		resourceId: string,
 	): Promise<{ cursor: string; envelope: CursorEnvelope }> {
 		const envelope = verifyCursor(cursor, this.sessionToken);
-		if (!envelope) throw new CursorError("invalid_cursor", false);
-		if (envelope.expiresAt === undefined || envelope.expiresAt <= this.now()) throw new CursorError("cursor_expired");
+		if (!envelope) {
+			this.release(cursor);
+			throw new CursorError("invalid_cursor", true);
+		}
+		const source = this.#active.get(cursor);
+		if (!source || envelope.expiresAt === undefined) {
+			this.release(cursor);
+			throw new CursorError("invalid_cursor", true);
+		}
+		const validatedAt = this.now();
+		if (source.expiresAt <= validatedAt || envelope.expiresAt <= validatedAt) {
+			this.release(cursor);
+			throw new CursorError("cursor_expired");
+		}
 		if (
 			envelope.sessionId !== expected.sessionId ||
 			(expected.resource !== undefined && envelope.resource !== expected.resource) ||
 			envelope.direction !== expected.direction ||
-			canonicalJson(envelope.pageShape) !== canonicalJson(expected.pageShape)
+			canonicalJson(envelope.pageShape) !== canonicalJson(expected.pageShape) ||
+			envelope.purpose !== expected.purpose ||
+			_resourceKind !== envelope.resource ||
+			source.resourceId !== resourceId
 		)
 			throw new CursorError("invalid_input", false, "cursor does not match query");
+		// Preserve the already-validated source while removing expired target
+		// grants before capacity accounting. The shared timestamp prevents the
+		// source from changing classification at a TTL boundary mid-exchange.
+		this.sweep(cursor, validatedAt);
+		const targetConnectionCount = [...this.#active.values()].filter(
+			item => item.connectionId === connectionId,
+		).length;
+		if (
+			this.#active.size > MAX_CURSORS_PER_SESSION ||
+			targetConnectionCount - (source.connectionId === connectionId ? 1 : 0) >= MAX_CURSORS_PER_CONNECTION
+		)
+			throw new CursorError("snapshot_capacity_exceeded", false);
 		const exchanged: CursorEnvelope = {
 			...envelope,
 			nonce: randomUUID(),
 			issuedAt: undefined,
 			expiresAt: undefined,
 		};
-		const exchangedCursor = await this.grant(connectionId, exchanged, resourceKind, resourceId);
+		const issuedAt = this.now();
+		exchanged.issuedAt = issuedAt;
+		exchanged.expiresAt = issuedAt + CURSOR_TTL_MS;
+		const exchangedCursor = signCursor(exchanged, this.sessionToken);
+		try {
+			this.revisions.transferPin(cursor, exchangedCursor);
+		} catch (error) {
+			if (error instanceof RevisionStoreError) throw new CursorError(error.code, false, error.message);
+			throw error;
+		}
+		this.#active.delete(cursor);
+		this.#active.set(exchangedCursor, {
+			connectionId,
+			resourceId,
+			expiresAt: exchanged.expiresAt,
+		});
 		return { cursor: exchangedCursor, envelope: exchanged };
 	}
 
@@ -227,8 +271,9 @@ export class CursorRegistry {
 	close(): void {
 		for (const cursor of this.#active.keys()) this.release(cursor);
 	}
-	sweep(): void {
-		for (const [cursor, active] of this.#active) if (active.expiresAt <= this.now()) this.release(cursor);
+	sweep(exceptCursor?: string, at = this.now()): void {
+		for (const [cursor, active] of this.#active)
+			if (cursor !== exceptCursor && active.expiresAt <= at) this.release(cursor);
 		this.revisions.sweep();
 	}
 	get size(): number {