@gajae-code/coding-agent 0.15.6 → 0.16.0

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

@@ -37,8 +37,15 @@ import {
 	settleOwnedWork,
 } from "../../session/terminal-abort";
 import { parseThinkingLevel } from "../../thinking";
+import { readEndpointFile } from "../broker/endpoint-authority";
 import { ensureBroker } from "../broker/ensure";
-import { SessionIndex } from "../broker/session-index";
+import { processIncarnation } from "../broker/process-incarnation";
+import {
+	type MasterRoleAttestationV2,
+	resolveSessionLocator,
+	SessionIndex,
+	type SessionLocatorV2,
+} from "../broker/session-index";
 import {
 	parseSyntheticModelId,
 	resolveSyntheticModelSelection,
@@ -58,8 +65,12 @@ import {
 	resolveReconciliationSessionFile,
 } from "../reconciliation-extensions";
 import { sanitizeTurnResultContent, type TurnResultContent } from "../turn-result";
-import { type ControlSurface, controlRequestFromFrame, dispatchControl } from "./control";
-import { BROKER_RUNTIME_CLOSE_CAPABILITY_FIELD } from "./control/runtime-gate";
+import { type ControlSurface, controlRequestFromFrame, dispatchControl, terminalAbortIdentity } from "./control";
+import {
+	BROKER_RUNTIME_ABORT_CAPABILITY_FIELD,
+	BROKER_RUNTIME_CLOSE_CAPABILITY_FIELD,
+	hasBrokerRuntimeAbortCapability,
+} from "./control/runtime-gate";
 import { SessionSdkHost, type SessionSdkHostOptions } from "./host";
 import { clearAutoroutingInactive, isAutoroutingInactive, markAutoroutingInactive } from "./internal-autorouting-state";
 import { CursorRegistry, QueryHandlers, RevisionStore, type SessionSurface } from "./query";
@@ -103,6 +114,65 @@ const SDK_ONLY_TERMINAL_PUBLICATION_WAIT_MS = 1_000;
  *  after this bound are abandoned — their durable broker state is the recovery
  *  authority, and outcomes are inherently uncertain. */
 const GATE_RESOLUTION_QUIESCENCE_MS = 5_000;
+/** Master verification fields are ephemeral protocol values, not unbounded input. */
+const MASTER_AUTH_VALUE_MAX_LENGTH = 512;
+const MASTER_AUTH_VALUE_PATTERN = /^[A-Za-z0-9_-]+$/u;
+/** Keep replay protection finite even when an authenticated client floods nonces. */
+const MASTER_NONCE_REPLAY_MAX_ENTRIES = 1_024;
+/** Verification exchanges complete in seconds; retain replay evidence for a bounded window. */
+const MASTER_NONCE_REPLAY_TTL_MS = 5 * 60_000;
+
+export type MasterCapabilityReplayState = Map<string, number>;
+
+export function verifyMasterCapabilityFrame(input: {
+	frame: { nonce: unknown; attestationEpoch: unknown; capability: unknown };
+	expectedCapability: string | undefined;
+	expectedEpoch: string | undefined;
+	replay: MasterCapabilityReplayState;
+	now?: number;
+}): { ok: boolean; nonce: string; attestationEpoch: string } {
+	const now = input.now ?? Date.now();
+	for (const [consumedNonce, expiresAt] of input.replay) {
+		if (expiresAt <= now) input.replay.delete(consumedNonce);
+	}
+	const bounded = (value: unknown): value is string =>
+		typeof value === "string" &&
+		value.length > 0 &&
+		value.length <= MASTER_AUTH_VALUE_MAX_LENGTH &&
+		MASTER_AUTH_VALUE_PATTERN.test(value);
+	const nonce = bounded(input.frame.nonce) ? input.frame.nonce : "";
+	const epoch = bounded(input.frame.attestationEpoch) ? input.frame.attestationEpoch : "";
+	const capability = bounded(input.frame.capability) ? input.frame.capability : "";
+	const expectedCapability = bounded(input.expectedCapability) ? input.expectedCapability : "";
+	const expectedEpoch = bounded(input.expectedEpoch) ? input.expectedEpoch : "";
+	const authenticatedFields =
+		bounded(input.frame.nonce) &&
+		bounded(input.frame.attestationEpoch) &&
+		bounded(input.frame.capability) &&
+		bounded(input.expectedCapability) &&
+		bounded(input.expectedEpoch) &&
+		epoch === expectedEpoch;
+	const expectedBytes = Buffer.from(expectedCapability);
+	const capabilityBytes = Buffer.from(capability);
+	const capabilityMatches =
+		authenticatedFields &&
+		expectedBytes.length === capabilityBytes.length &&
+		crypto.timingSafeEqual(expectedBytes, capabilityBytes);
+	const reusable = capabilityMatches && !input.replay.has(nonce);
+	if (reusable) {
+		if (input.replay.size >= MASTER_NONCE_REPLAY_MAX_ENTRIES) {
+			const oldest = input.replay.keys().next().value;
+			if (typeof oldest === "string") input.replay.delete(oldest);
+		}
+		input.replay.set(nonce, now + MASTER_NONCE_REPLAY_TTL_MS);
+	}
+	return {
+		ok: reusable,
+		nonce,
+		attestationEpoch: authenticatedFields ? epoch : "",
+	};
+}
+
 /** Maximum time a replaced runtime may retain a lifecycle persistence task. */
 const LIFECYCLE_QUIESCENCE_MS = 1_000;
 
@@ -142,6 +212,8 @@ export interface SessionSdkRuntimeOptions
 	settings?: Settings;
 	/** Mutable shadow of patched config values merged into query readback. */
 	configOverrides?: Map<string, unknown>;
+	/** Stable master lineage identity retained across session switches/branches. */
+	masterOwnerSessionId?: string;
 }
 
 export interface SdkOnlyInvocationRecord extends InvocationCorrelation {
@@ -400,6 +472,8 @@ export interface CreateSdkSessionRuntimeOptions {
 	agentDir: string;
 	/** Lifecycle-owned sessions require broker publication before they become usable. */
 	brokerRegistrationRequired?: boolean;
+	/** Trusted broker-issued lifecycle marker bound to lifecycle host index events. */
+	lifecycleRequestId?: string;
 	createTransport(input: {
 		sessionId: string;
 		stateRoot: string;
@@ -411,6 +485,12 @@ export interface CreateSdkSessionRuntimeOptions {
 	onSdkRequest?: SessionSdkHostOptions["onRequest"];
 	/** Mutable shadow of patched config values merged into query readback. */
 	configOverrides?: Map<string, unknown>;
+	/** In-memory master capability for private broker verification only. */
+	masterCapability?: string;
+	/** Opaque direct-role epoch this effective host may adopt. */
+	masterAttestationEpoch?: string;
+	/** Stable master lineage identity retained across session switches/branches. */
+	masterOwnerSessionId?: string;
 	/** Private session-owned terminal-abort capabilities; never exposed on ExtensionContext. */
 	terminalAbortSeams?: SdkOnlyTerminalAbortSeams;
 	/** Callback when a frame is admitted to the runtime (test harness). */
@@ -1117,18 +1197,15 @@ function createQuerySurface(
 		kind: ctx.sessionMetadata?.kind ?? "main",
 	});
 	const lastAssistant = () => {
-		for (const entry of ctx.sessionManager.getBranch().toReversed()) {
-			if (entry.type !== "message" || entry.message.role !== "assistant") continue;
-			const content = entry.message.content;
-			if (typeof content === "string") return content;
-			if (Array.isArray(content))
-				return content
-					.filter(
-						(block): block is { type: "text"; text: string } =>
-							block.type === "text" && typeof block.text === "string",
-					)
-					.map(block => block.text)
-					.join("");
+		const transcript =
+			typeof (ctx as Partial<ExtensionContext>).getTranscript === "function" ? ctx.getTranscript() : [];
+		for (const entry of transcript.toReversed()) {
+			if (entry.role !== "assistant") continue;
+			const text =
+				typeof entry.body === "string"
+					? entry.body
+					: entry.content?.flatMap(block => (block.type === "text" ? [block.text] : [])).join("\n");
+			if (text !== undefined && text.trim().length > 0) return text;
 		}
 		return undefined;
 	};
@@ -2269,7 +2346,7 @@ function createControlSurface(
 		}
 	};
 	const terminalAbort = async (
-		input: { mode: "terminal"; scope?: "turn" | "owned" },
+		input: { mode: "terminal"; scope?: "turn" | "owned"; operator?: boolean },
 		idempotencyKey?: string,
 	): Promise<unknown> => {
 		const scope = input.scope === "owned" ? "owned" : "turn";
@@ -2300,10 +2377,12 @@ function createControlSurface(
 				typeof idempotencyKey === "string"
 					? crypto.createHash("sha256").update(idempotencyKey).digest("hex")
 					: undefined;
-			const inputHash = crypto
-				.createHash("sha256")
-				.update(JSON.stringify({ mode: "terminal", scope }))
-				.digest("hex");
+			const abortIdentity = terminalAbortIdentity(
+				{ mode: "terminal", scope, ...(input.operator === true ? { operator: true } : {}) },
+				input.operator === true,
+			);
+			if (!abortIdentity) throw new Error("Terminal abort identity is invalid after dispatch validation.");
+			const inputHash = abortIdentity.inputHash;
 			const stored = (record: SdkOnlyTerminalScopeRecord | SdkOnlyEvictedTerminalKeyEntry) => ({
 				responseState: record.responseState ?? "pending",
 				responsePayloadHash: record.responsePayloadHash ?? inputHash,
@@ -2676,6 +2755,16 @@ function createControlSurface(
 						pendingPreflights.delete(requesterBucketKey);
 				}
 			};
+			const returnNoActiveTurn = async () => {
+				const result = {
+					ok: true,
+					selection: scope,
+					turn: "no_active_turn",
+					terminal: "terminal_no_effect",
+				};
+				await finalizeNoEffectReservation(result);
+				return result;
+			};
 			if (!handle || epoch === undefined) {
 				if ((await writeNoEffect()) === "conflict") {
 					throw Object.assign(new Error("Idempotency key was reused with different input."), {
@@ -2691,6 +2780,10 @@ function createControlSurface(
 					if (replayed !== undefined) return replayed;
 				}
 				cancelRequesterPreflights();
+				// Operator authority overrides connection ownership only for a turn
+				// observed at admission. It must never adopt a successor that starts
+				// while the durable no-effect reservation is being written.
+				if (input.operator === true) return await returnNoActiveTurn();
 				// A prompt for this requester may have become ACTIVE while the
 				// reservation awaited the filesystem transaction: its submit()
 				// cleanup already removed the preflight callback, so cancelling here
@@ -2706,14 +2799,7 @@ function createControlSurface(
 					// No prompt won the race: finalize the reserved row so a later
 					// same-key retry replays this deterministic no_active_turn result
 					// (review thread P2).
-					const noActiveTurnResult = {
-						ok: true,
-						selection: scope,
-						turn: "no_active_turn",
-						terminal: "terminal_no_effect",
-					};
-					await finalizeNoEffectReservation(noActiveTurnResult);
-					return noActiveTurnResult;
+					return await returnNoActiveTurn();
 				}
 				handle = recheckedHandle;
 				epoch = recheckedEpoch;
@@ -2743,7 +2829,11 @@ function createControlSurface(
 			// cleared after a terminal lifecycle boundary) authorizes no client, and
 			// a stale prior owner authorizes only that old client — never a later
 			// turn it did not submit (review thread P1).
-			if (handle && (abortingConnectionId === undefined || !currentOwnerConnectionIds().has(abortingConnectionId))) {
+			if (
+				input.operator !== true &&
+				handle &&
+				(abortingConnectionId === undefined || !currentOwnerConnectionIds().has(abortingConnectionId))
+			) {
 				if ((await writeNoEffect()) === "conflict") {
 					throw Object.assign(new Error("Idempotency key was reused with different input."), {
 						code: "idempotency_conflict",
@@ -3412,6 +3502,107 @@ export function registerSdkOnlyNotificationCommand(api: ExtensionAPI): void {
 	});
 }
 
+export function masterAttestationForEffectiveHost(input: {
+	masterCapability: string | undefined;
+	attestationEpoch: string | undefined;
+	ownerSessionId?: string;
+	sessionId: string;
+	pid: number;
+	processIncarnation: string | undefined;
+	direct: MasterRoleAttestationV2 | undefined;
+}): MasterRoleAttestationV2 | undefined {
+	const direct = input.direct;
+	if (
+		input.masterCapability === undefined ||
+		input.attestationEpoch === undefined ||
+		direct === undefined ||
+		direct.ownerSessionId !== (input.ownerSessionId ?? input.sessionId) ||
+		direct.launchPid !== input.pid ||
+		direct.launchProcessIncarnation !== input.processIncarnation ||
+		direct.attestationEpoch !== input.attestationEpoch
+	)
+		return undefined;
+	return direct;
+}
+
+function masterDirectAttestation(input: {
+	masterCapability: string | undefined;
+	attestationEpoch: string | undefined;
+	ownerSessionId?: string;
+	sessionId: string;
+	pid: number;
+	processIncarnation: string | undefined;
+}): MasterRoleAttestationV2 | undefined {
+	if (
+		input.masterCapability === undefined ||
+		input.attestationEpoch === undefined ||
+		input.processIncarnation === undefined
+	)
+		return undefined;
+	return {
+		version: 2,
+		ownerSessionId: input.ownerSessionId ?? input.sessionId,
+		launchPid: input.pid,
+		launchProcessIncarnation: input.processIncarnation,
+		role: "master",
+		attestationEpoch: input.attestationEpoch,
+	};
+}
+
+function sameMasterAttestation(left: MasterRoleAttestationV2, right: MasterRoleAttestationV2): boolean {
+	return (
+		left.version === right.version &&
+		left.ownerSessionId === right.ownerSessionId &&
+		left.launchPid === right.launchPid &&
+		left.launchProcessIncarnation === right.launchProcessIncarnation &&
+		left.role === right.role &&
+		left.attestationEpoch === right.attestationEpoch
+	);
+}
+
+/**
+ * Establish direct master authority for the session currently hosted by this
+ * process. Session identity transitions retain the master capability and epoch
+ * but require a new direct attestation before their effective endpoint can
+ * adopt that authority.
+ */
+export async function reattestMasterSessionIdentity(input: {
+	index: SessionIndex;
+	locator: SessionLocatorV2;
+	masterCapability: string | undefined;
+	attestationEpoch: string | undefined;
+	ownerSessionId?: string;
+	sessionId: string;
+	pid: number;
+	processIncarnation: string | undefined;
+}): Promise<MasterRoleAttestationV2 | undefined> {
+	const masterRole = masterDirectAttestation(input);
+	if (!masterRole) return undefined;
+	const directExists = input.index.listSessionIdentities().some(row => {
+		const processIdentity = row.hostIncarnation ?? row.processIncarnation;
+		return (
+			row.sessionId === input.sessionId &&
+			row.endpointGeneration === 0 &&
+			row.pid === input.pid &&
+			processIdentity === input.processIncarnation &&
+			row.masterRole !== undefined &&
+			sameMasterAttestation(row.masterRole, masterRole)
+		);
+	});
+	if (!directExists) {
+		await input.index.append({
+			type: "host_registered",
+			sessionId: input.sessionId,
+			locator: input.locator,
+			endpointGeneration: 0,
+			pid: input.pid,
+			processIncarnation: input.processIncarnation,
+			masterRole,
+		});
+	}
+	return masterRole;
+}
+
 function quiescingFrame(frame: Record<string, unknown>): Record<string, unknown> | undefined {
 	const error = { code: "session_quiescing", message: "The session endpoint is being replaced." };
 	const id = typeof frame.id === "string" ? frame.id : "";
@@ -4172,6 +4363,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		await current.registerBroker();
 		current.runtime.emitEvent({ type: "turn_start", sessionId: ctx.sessionManager.getSessionId() });
 	});
+	const consumedMasterNonces = new Map<string, number>();
 	api.on("turn_end", (_event, ctx) =>
 		lifecycleStateForContext(ctx, "agent_end")?.runtime.emitEvent({
 			type: "turn_end",
@@ -4731,6 +4923,13 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		};
 		runtime = new SessionSdkSessionRuntime({
 			transport,
+			masterCapabilityVerify: frame =>
+				verifyMasterCapabilityFrame({
+					frame,
+					expectedCapability: options.masterCapability,
+					expectedEpoch: options.masterAttestationEpoch,
+					replay: consumedMasterNonces,
+				}),
 			onFrameAdmission: (_connectionId, frame) =>
 				inputGate.quiescing ? quiescingFrame(frame as Record<string, unknown>) : undefined,
 			control: async (connectionId, frame) => {
@@ -4776,21 +4975,13 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 					(request.input as { mode?: unknown }).mode !== "terminal"
 				)
 					return;
-				const input = request.input as Record<string, unknown>;
-				const mode = input.mode;
-				const rawScope = input.scope;
-				if (mode !== "terminal") return;
-				if (rawScope !== undefined && rawScope !== "turn" && rawScope !== "owned") return;
-				// A malformed retry (e.g. {mode:"terminal", scope:"turn", extra:true})
-				// rejected by dispatch must never hash as the valid turn input and
-				// advance the legitimate stored row (review thread P2).
-				for (const key of Object.keys(input)) if (key !== "mode" && key !== "scope") return;
-				const scopeInput = rawScope === "owned" ? "owned" : "turn";
+				const rawInput = request.input as Record<string, unknown>;
+				const operatorAuthorized = hasBrokerRuntimeAbortCapability(rawInput);
+				const { [BROKER_RUNTIME_ABORT_CAPABILITY_FIELD]: _capability, ...publicInput } = rawInput;
+				const abortIdentity = terminalAbortIdentity(publicInput, operatorAuthorized);
+				if (!abortIdentity) return;
 				const keyHash = crypto.createHash("sha256").update(String(request.idempotencyKey)).digest("hex");
-				const inputHash = crypto
-					.createHash("sha256")
-					.update(JSON.stringify({ mode: "terminal", scope: scopeInput }))
-					.digest("hex");
+				const inputHash = abortIdentity.inputHash;
 				// Hash the ACTUAL written response payload: the durable state may only
 				// advance when the written response corresponds to the row's payload.
 				// When more than 256 concurrent requests evict an in-flight abort from
@@ -4846,21 +5037,72 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		const disposeGate = ctx.workflowGate?.onGateEmitted?.(gate =>
 			runtime.emitEvent({ kind: "workflow_gate", payload: gate }),
 		);
+		let publishedEndpointUrl: string | undefined;
 		let brokerRegistered = false;
 		const registerBroker = async (): Promise<void> => {
 			if (brokerRegistered) return;
 			try {
+				if (options.brokerRegistrationRequired && !options.lifecycleRequestId)
+					throw new Error("Lifecycle broker registration requires a request identity.");
 				await ensureBroker({ agentDir: options.agentDir });
 				const index = await new SessionIndex(options.agentDir).open();
-				const locator = { repo: path.resolve(ctx.cwd), stateRoot };
+				const locator = await resolveSessionLocator(ctx.cwd, stateRoot);
+				const effectiveIncarnation = processIncarnation(process.pid);
+				const direct = await reattestMasterSessionIdentity({
+					index,
+					locator,
+					masterCapability: options.masterCapability,
+					attestationEpoch: options.masterAttestationEpoch,
+					ownerSessionId: options.masterOwnerSessionId,
+					sessionId,
+					pid: process.pid,
+					processIncarnation: effectiveIncarnation,
+				});
 				await runtime.registerWithBroker({
 					register: async input => {
-						const endpointMtimeMs = (await fs.stat(path.join(input.stateRoot, "sdk", `${input.sessionId}.json`)))
-							.mtimeMs;
-						await index.append({ type: "host_registered", ...input, locator, pid: process.pid, endpointMtimeMs });
+						if (publishedEndpointUrl === undefined)
+							throw new Error("SDK transport endpoint was not published before broker registration.");
+						const endpointPath = path.join(input.stateRoot, "sdk", `${input.sessionId}.json`);
+						const file = await readEndpointFile(endpointPath);
+						if (!file) throw new Error("SDK endpoint could not be read as a stable regular file.");
+						const endpoint = JSON.parse(file.source) as Record<string, unknown>;
+						if (
+							endpoint.sessionId !== input.sessionId ||
+							endpoint.pid !== process.pid ||
+							endpoint.url !== publishedEndpointUrl ||
+							endpoint.token !== transport.token
+						)
+							throw new Error("SDK endpoint did not match the published transport authority.");
+						const endpointMtimeMs = file.mtimeMs;
+						const endpointFileId = `${file.dev}:${file.ino}`;
+						const masterRole = masterAttestationForEffectiveHost({
+							masterCapability: options.masterCapability,
+							attestationEpoch: options.masterAttestationEpoch,
+							ownerSessionId: options.masterOwnerSessionId,
+							sessionId: input.sessionId,
+							pid: process.pid,
+							processIncarnation: effectiveIncarnation,
+							direct,
+						});
+						await index.append({
+							type: "host_registered",
+							...input,
+							locator,
+							pid: process.pid,
+							endpointMtimeMs,
+							endpointFileId,
+							...(options.lifecycleRequestId ? { lifecycleRequestId: options.lifecycleRequestId } : {}),
+							...(masterRole ? { masterRole } : {}),
+						});
 					},
 					unregister: async input => {
-						await index.append({ type: "host_unregistered", ...input, locator, pid: process.pid });
+						await index.append({
+							type: "host_unregistered",
+							...input,
+							locator,
+							pid: process.pid,
+							...(options.lifecycleRequestId ? { lifecycleRequestId: options.lifecycleRequestId } : {}),
+						});
 					},
 				});
 				brokerRegistered = true;
@@ -4899,7 +5141,7 @@ export function createSdkSessionRuntimeExtension(api: ExtensionAPI, options: Cre
 		lifecycleOwnerHolder.state = runtimeOwner;
 		active = runtimeOwner;
 		try {
-			await runtime.start();
+			publishedEndpointUrl = (await runtime.start()).url;
 			await registerBroker();
 		} catch (error) {
 			active = undefined;

package/src/sdk/lifecycle/broker-client.ts

@@ -51,3 +51,31 @@ export class AgentDirSessionLifecycleClient implements SessionLifecycleClient {
 export function createBrokerSessionLifecycleService(agentDir: string): SessionLifecycleService {
 	return new SessionLifecycleService(new AgentDirSessionLifecycleClient(agentDir));
 }
+
+/**
+ * Dedicated dispatch for the local master `session.spawn` surface. It shares
+ * the lifecycle client's credential boundary but bypasses the generic mutation
+ * outcome types: spawn responses are validated by the caller's allowlist.
+ */
+export async function dispatchSpawnGlobal(
+	agentDir: string,
+	input: Record<string, unknown>,
+	idempotencyKey: string,
+	timeoutMs: number,
+): Promise<unknown> {
+	await ensureBroker({ agentDir });
+	const discovery = await readSdkBrokerDiscovery(agentDir);
+	if (!discovery) throw new Error("SDK broker discovery is unavailable.");
+	const client = await SdkClient.connect(discovery.url, discovery.token, { timeoutMs });
+	try {
+		return await client.global("session.spawn", input, { idempotencyKey, timeoutMs });
+	} finally {
+		try {
+			await client.close();
+		} catch (error) {
+			logger.warn("SDK spawn client cleanup failed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
+}