@gajae-code/coding-agent 0.10.2 → 0.11.1

package/src/sdk/broker/process-incarnation.ts

@@ -0,0 +1,159 @@
+import { dlopen, ptr } from "bun:ffi";
+import * as fs from "node:fs";
+import { Process } from "@gajae-code/natives";
+
+const DARWIN_PROC_PIDTBSDINFO = 3;
+const DARWIN_PROC_BSDINFO_SIZE = 136;
+const DARWIN_PROC_BSDINFO_START_SECONDS_OFFSET = 120;
+const DARWIN_PROC_BSDINFO_START_MICROSECONDS_OFFSET = 128;
+const POWERSHELL_PROCESS_INCARNATION_COMMAND = "powershell.exe";
+const WIN32_PROCESS_INCARNATION_OUTPUT = /^(\d+)\t(0|[1-9]\d*)(?:\r?\n)?$/;
+const MAX_WINDOWS_FILETIME_TICKS = 18_446_744_073_709_551_615n;
+
+const darwinProcLibrary =
+	process.platform === "darwin"
+		? (() => {
+				try {
+					return dlopen("/usr/lib/libproc.dylib", {
+						proc_pidinfo: {
+							args: ["i32", "i32", "u64", "ptr", "i32"],
+							returns: "i32",
+						},
+					});
+				} catch {
+					return undefined;
+				}
+			})()
+		: undefined;
+
+type ProcessIncarnationCommandResult = { exitCode: number | null; stdout: string } | undefined;
+
+export type ProcessIncarnationCommandRunner = (
+	command: string,
+	args: readonly string[],
+) => ProcessIncarnationCommandResult;
+
+export interface ProcessIncarnationOptions {
+	platform?: typeof process.platform;
+	runCommand?: ProcessIncarnationCommandRunner;
+}
+
+function runProcessIncarnationCommand(command: string, args: readonly string[]): ProcessIncarnationCommandResult {
+	try {
+		const result = Bun.spawnSync([command, ...args], { stdin: "ignore", stdout: "pipe", stderr: "ignore" });
+		return { exitCode: result.exitCode, stdout: Buffer.from(result.stdout).toString("utf8") };
+	} catch {
+		return undefined;
+	}
+}
+
+function windowsProcessIncarnationCommand(pid: number): { command: string; args: string[] } {
+	return {
+		command: POWERSHELL_PROCESS_INCARNATION_COMMAND,
+		args: [
+			"-NoLogo",
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			[
+				"$ErrorActionPreference = 'Stop'",
+				"$OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)",
+				`$process = Get-Process -Id ${pid} -ErrorAction Stop`,
+				"$filetime = [UInt64]($process.StartTime.ToUniversalTime().ToFileTimeUtc())",
+				'[Console]::Out.WriteLine(("{0}`t{1}" -f $process.Id, $filetime))',
+			].join("; "),
+		],
+	};
+}
+
+function isWindowsFiletimeTicks(value: string): boolean {
+	if (!/^(?:0|[1-9]\d*)$/.test(value)) return false;
+	try {
+		return BigInt(value) <= MAX_WINDOWS_FILETIME_TICKS;
+	} catch {
+		return false;
+	}
+}
+
+function parseWin32ProcessIncarnation(pid: number, output: string): string | undefined {
+	const match = WIN32_PROCESS_INCARNATION_OUTPUT.exec(output);
+	if (!match || match[1] !== String(pid) || !isWindowsFiletimeTicks(match[2])) return undefined;
+	return `windows:${match[2]}`;
+}
+
+/** Parse the microsecond-resolution start timestamp returned by Darwin proc_pidinfo. */
+export function parseDarwinProcessIncarnation(info: Uint8Array): string | undefined {
+	if (info.byteLength < DARWIN_PROC_BSDINFO_SIZE) return undefined;
+	try {
+		const view = new DataView(info.buffer, info.byteOffset, info.byteLength);
+		const seconds = view.getBigUint64(DARWIN_PROC_BSDINFO_START_SECONDS_OFFSET, true);
+		const microseconds = view.getBigUint64(DARWIN_PROC_BSDINFO_START_MICROSECONDS_OFFSET, true);
+		if (seconds === 0n || microseconds >= 1_000_000n) return undefined;
+		return `darwin:${seconds}:${microseconds}`;
+	} catch {
+		return undefined;
+	}
+}
+
+function isProcessIncarnation(value: unknown): value is string {
+	return (
+		typeof value === "string" &&
+		(/^(?:linux:\d+|darwin:[1-9]\d*:\d+)$/.test(value) ||
+			(value.startsWith("windows:") && isWindowsFiletimeTicks(value.slice("windows:".length))))
+	);
+}
+
+/** A PID is reusable; bind it to the strongest OS-provided process start incarnation available. */
+export function processIncarnation(pid: number, options: ProcessIncarnationOptions = {}): string | undefined {
+	if (!Number.isSafeInteger(pid) || pid <= 0) return undefined;
+	const platform = options.platform ?? process.platform;
+	if (platform === process.platform && options.runCommand === undefined) {
+		try {
+			const nativeProcess = Process.fromPid(pid) as { incarnation?: unknown } | null;
+			if (isProcessIncarnation(nativeProcess?.incarnation)) return nativeProcess.incarnation;
+		} catch {
+			// Fall through to the platform-specific reader.
+		}
+	}
+	if (platform === "linux") {
+		try {
+			const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf8");
+			const close = stat.lastIndexOf(")");
+			const startTicks = stat
+				.slice(close + 2)
+				.trim()
+				.split(/\s+/)[19];
+			return startTicks ? `linux:${startTicks}` : undefined;
+		} catch {
+			return undefined;
+		}
+	}
+	if (platform === "darwin") {
+		const info = new Uint8Array(DARWIN_PROC_BSDINFO_SIZE);
+		try {
+			const bytesRead = darwinProcLibrary?.symbols.proc_pidinfo(
+				pid,
+				DARWIN_PROC_PIDTBSDINFO,
+				0,
+				ptr(info),
+				info.byteLength,
+			);
+			return bytesRead === DARWIN_PROC_BSDINFO_SIZE ? parseDarwinProcessIncarnation(info) : undefined;
+		} catch {
+			return undefined;
+		}
+	}
+	if (platform === "win32") {
+		const command = windowsProcessIncarnationCommand(pid);
+		let result: ProcessIncarnationCommandResult;
+		try {
+			result = (options.runCommand ?? runProcessIncarnationCommand)(command.command, command.args);
+		} catch {
+			return undefined;
+		}
+		return result?.exitCode === 0 && typeof result.stdout === "string"
+			? parseWin32ProcessIncarnation(pid, result.stdout)
+			: undefined;
+	}
+	return undefined;
+}

package/src/sdk/broker/runtime.ts

@@ -0,0 +1,164 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import internalSourceMarker from "./internal-source-marker-2178.txt" with { type: "file" };
+
+export type SdkInternalAction = "broker-internal" | "session-host-internal";
+
+export type SdkInternalSpawnCommand =
+	| {
+			kind: "bun-source";
+			file: string;
+			args: string[];
+			env: NodeJS.ProcessEnv;
+			cwd: string;
+	  }
+	| {
+			kind: "compiled";
+			file: string;
+			args: string[];
+			env: NodeJS.ProcessEnv;
+			cwd?: undefined;
+	  };
+
+type EmbeddedFile = Blob | { name: string };
+
+/** Test-only injectable inputs for hostile evidence and platform grammar coverage. */
+export interface SdkInternalRuntimeDescriptorTestOptions {
+	execPath?: string;
+	environment?: NodeJS.ProcessEnv;
+	embeddedFiles?: readonly EmbeddedFile[];
+	markerPath?: string;
+	brokerDirectory?: string;
+	cliPath?: string;
+	configPath?: string;
+	bunAvailable?: boolean;
+}
+
+const COMPILED_MARKER_NAME = /^internal-source-marker-2178-[A-Za-z0-9]+\.txt$/;
+const POSIX_MARKER_VFS_PATH = /^\/\$bunfs\/root\/internal-source-marker-2178-[A-Za-z0-9]+\.txt$/;
+const WINDOWS_MARKER_VFS_PATH = /^[A-Za-z]:\/~BUN\/(?:root\/)?internal-source-marker-2178-[A-Za-z0-9]+\.txt$/;
+
+function isCompiledMarkerPath(markerPath: string): boolean {
+	const normalized = markerPath.replaceAll("\\", "/");
+	return POSIX_MARKER_VFS_PATH.test(normalized) || WINDOWS_MARKER_VFS_PATH.test(normalized);
+}
+function embeddedFileName(file: EmbeddedFile): string | undefined {
+	return "name" in file && typeof file.name === "string" ? file.name : undefined;
+}
+
+function containedPath(parent: string, candidate: string): boolean {
+	const relative = path.relative(parent, candidate);
+	return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+function regularReadablePath(file: string, label: string): string {
+	let canonical: string;
+	try {
+		canonical = fs.realpathSync(file);
+		const stat = fs.statSync(canonical);
+		fs.accessSync(canonical, fs.constants.R_OK);
+		if (!stat.isFile()) throw new Error("not a regular file");
+	} catch {
+		throw new Error(`SDK internal launch refused: ${label} is not a readable regular file.`);
+	}
+	return canonical;
+}
+
+function internalEnvironment(environment: NodeJS.ProcessEnv, source: boolean): NodeJS.ProcessEnv {
+	const isolated = { ...environment };
+	delete isolated.BUN_OPTIONS;
+	if (source) {
+		delete isolated.PI_COMPILED;
+		delete isolated.GJC_COMPILED;
+	}
+	return isolated;
+}
+function expectedPackageName(packageDirectory: string): void {
+	try {
+		const manifest = JSON.parse(fs.readFileSync(path.join(packageDirectory, "package.json"), "utf8")) as {
+			name?: unknown;
+		};
+		if (manifest.name !== "@gajae-code/coding-agent") throw new Error("unexpected package name");
+	} catch {
+		throw new Error("SDK internal launch refused: product package identity is invalid.");
+	}
+}
+
+function sourceDescriptor(
+	action: SdkInternalAction,
+	options: SdkInternalRuntimeDescriptorTestOptions,
+	markerPath: string,
+): SdkInternalSpawnCommand {
+	if (options.bunAvailable === false || typeof Bun === "undefined")
+		throw new Error("SDK internal launch refused: Bun source runtime is unavailable.");
+	const brokerDirectory = path.resolve(options.brokerDirectory ?? import.meta.dir);
+	const packageDirectory = path.resolve(brokerDirectory, "../../..");
+	const sourceDirectory = path.resolve(brokerDirectory, "../..");
+	const runtime = regularReadablePath(path.resolve(options.execPath ?? process.execPath), "runtime executable");
+	const cli = regularReadablePath(
+		path.resolve(options.cliPath ?? path.join(sourceDirectory, "cli.ts")),
+		"CLI entrypoint",
+	);
+	const config = regularReadablePath(
+		path.resolve(options.configPath ?? path.join(brokerDirectory, "internal-source.bunfig.toml")),
+		"isolated Bun configuration",
+	);
+	const marker = regularReadablePath(path.resolve(markerPath), "source marker");
+	const canonicalBrokerDirectory = fs.realpathSync(brokerDirectory);
+	const canonicalPackageDirectory = fs.realpathSync(packageDirectory);
+	const canonicalSourceDirectory = fs.realpathSync(sourceDirectory);
+	expectedPackageName(canonicalPackageDirectory);
+	if (
+		!containedPath(canonicalPackageDirectory, canonicalBrokerDirectory) ||
+		!containedPath(canonicalPackageDirectory, canonicalSourceDirectory) ||
+		!containedPath(canonicalSourceDirectory, cli) ||
+		!containedPath(canonicalBrokerDirectory, config) ||
+		!containedPath(canonicalBrokerDirectory, marker)
+	)
+		throw new Error("SDK internal launch refused: product runtime assets escape their trusted directories.");
+	return {
+		kind: "bun-source",
+		file: runtime,
+		args: ["--no-env-file", `--config=${config}`, cli, "sdk", action],
+		env: internalEnvironment(options.environment ?? process.env, true),
+		cwd: canonicalBrokerDirectory,
+	};
+}
+
+function resolveSdkInternalSpawnCommandWithEvidence(
+	action: SdkInternalAction,
+	options: SdkInternalRuntimeDescriptorTestOptions,
+): SdkInternalSpawnCommand {
+	const markerPath = options.markerPath ?? internalSourceMarker;
+	const embeddedFiles = options.embeddedFiles ?? (typeof Bun === "undefined" ? undefined : Bun.embeddedFiles);
+	if (!embeddedFiles) throw new Error("SDK internal launch refused: Bun runtime evidence is unavailable.");
+	const markerName = path.basename(markerPath.replaceAll("\\", "/"));
+	const markerEntries = embeddedFiles.filter(file => embeddedFileName(file) === markerName);
+	const compiledMarkerPath = isCompiledMarkerPath(markerPath);
+	const exactCompiledArtifact = COMPILED_MARKER_NAME.test(markerName) && markerEntries.length === 1;
+	const isSourceMarker = path.isAbsolute(markerPath) && !compiledMarkerPath;
+	if (embeddedFiles.length === 0 && isSourceMarker) return sourceDescriptor(action, options, markerPath);
+	if (exactCompiledArtifact && compiledMarkerPath) {
+		const executable = regularReadablePath(path.resolve(options.execPath ?? process.execPath), "compiled executable");
+		return {
+			kind: "compiled",
+			file: executable,
+			args: ["sdk", action],
+			env: internalEnvironment(options.environment ?? process.env, false),
+		};
+	}
+	throw new Error("SDK internal launch refused: compiled-runtime marker evidence is inconsistent.");
+}
+
+/** Resolve the production descriptor from the statically imported marker and current Bun runtime evidence. */
+export function resolveSdkInternalSpawnCommand(action: SdkInternalAction): SdkInternalSpawnCommand {
+	return resolveSdkInternalSpawnCommandWithEvidence(action, {});
+}
+
+/** Test hook: injects runtime evidence without weakening the production marker authority. */
+export function resolveSdkInternalSpawnCommandForTest(
+	action: SdkInternalAction,
+	options: SdkInternalRuntimeDescriptorTestOptions,
+): SdkInternalSpawnCommand {
+	return resolveSdkInternalSpawnCommandWithEvidence(action, options);
+}

package/src/sdk/broker/session-index.ts

@@ -0,0 +1,318 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { withFileLock } from "../../config/file-lock";
+import { assertSupportedStateVersion, SDK_STATE_VERSION, UnsupportedStateVersionError } from "./state-version";
+
+export type SessionIndexEventType =
+	| "host_registered"
+	| "host_heartbeat"
+	| "host_unregistered"
+	| "lifecycle_started"
+	| "lifecycle_terminal"
+	| "session_closed"
+	| "record_reconciled";
+export interface SessionIndexEvent {
+	version: typeof SDK_STATE_VERSION;
+	indexSeq: number;
+	type: SessionIndexEventType;
+	sessionId: string;
+	locator: { repo: string; stateRoot: string };
+	endpointGeneration: number;
+	pid: number;
+	endpointMtimeMs?: number;
+	lifecycleRequestId?: string;
+	terminalUncertain?: boolean;
+	ts: number;
+	checksum: string;
+}
+export interface IndexedSession {
+	sessionId: string;
+	locator: { repo: string; stateRoot: string };
+	endpointGeneration: number;
+	pid: number;
+	endpointMtimeMs?: number;
+	live: boolean;
+	indexSeq: number;
+	lifecycleRequestId?: string;
+	terminalUncertain?: boolean;
+}
+export interface SessionList {
+	indexSeq: number;
+	sessions: IndexedSession[];
+	warnings: string[];
+}
+const canonical = (event: Omit<SessionIndexEvent, "checksum">) => JSON.stringify(event);
+export const sessionIndexChecksum = (event: Omit<SessionIndexEvent, "checksum">) =>
+	createHash("sha256").update(canonical(event)).digest("hex");
+const dirFor = (agentDir: string) => path.join(agentDir, "sdk", "sessions");
+const logFor = (agentDir: string) => path.join(dirFor(agentDir), "index.jsonl");
+const snapshotFor = (agentDir: string) => path.join(dirFor(agentDir), "index.snapshot.json");
+async function appendSync(file: string, value: string): Promise<void> {
+	const h = await fs.open(file, "a", 0o600);
+	try {
+		await h.write(`${value}\n`);
+		await h.sync();
+	} finally {
+		await h.close();
+	}
+}
+function alive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (e) {
+		return (e as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+export class SessionIndex {
+	#agentDir: string;
+	#events: SessionIndexEvent[] = [];
+	#warnings: string[] = [];
+	#logOffset = 0;
+	constructor(agentDir: string) {
+		this.#agentDir = agentDir;
+	}
+	async open(): Promise<this> {
+		await this.assertSupportedStateVersions();
+		await fs.mkdir(dirFor(this.#agentDir), { recursive: true, mode: 0o700 });
+		await fs.chmod(dirFor(this.#agentDir), 0o700);
+		await this.replay();
+		return this;
+	}
+	async replay(): Promise<void> {
+		this.#events = [];
+		this.#warnings = [];
+		this.#logOffset = 0;
+		let snapshotSeq = 0;
+		try {
+			const snapshot = JSON.parse(await fs.readFile(snapshotFor(this.#agentDir), "utf8")) as {
+				version?: number;
+				events?: SessionIndexEvent[];
+				indexSeq?: number;
+			};
+			assertSupportedStateVersion(snapshotFor(this.#agentDir), snapshot);
+			const snapshotIndexSeq = snapshot.indexSeq;
+			if (
+				typeof snapshotIndexSeq !== "number" ||
+				!Number.isSafeInteger(snapshotIndexSeq) ||
+				snapshotIndexSeq < 0 ||
+				!Array.isArray(snapshot.events) ||
+				snapshot.events.some(event => {
+					const { checksum, ...unsigned } = event;
+					return event.indexSeq > snapshotIndexSeq || checksum !== sessionIndexChecksum(unsigned);
+				})
+			)
+				throw new Error("invalid snapshot");
+			this.#events = snapshot.events;
+			snapshotSeq = snapshotIndexSeq;
+		} catch (e) {
+			if (e instanceof UnsupportedStateVersionError) throw e;
+			if ((e as NodeJS.ErrnoException).code !== "ENOENT") this.#warnings.push("Invalid session index snapshot");
+		}
+		await this.#tail(snapshotSeq);
+	}
+	async #tail(snapshotSeq = this.indexSeq): Promise<void> {
+		let data: Buffer;
+		try {
+			const handle = await fs.open(logFor(this.#agentDir), "r");
+			try {
+				const stat = await handle.stat();
+				if (stat.size < this.#logOffset) {
+					this.#warnings.push("Session index log was truncated");
+					return;
+				}
+				data = Buffer.alloc(stat.size - this.#logOffset);
+				if (data.length) await handle.read(data, 0, data.length, this.#logOffset);
+			} finally {
+				await handle.close();
+			}
+		} catch (e) {
+			if ((e as NodeJS.ErrnoException).code === "ENOENT") return;
+			throw e;
+		}
+		const lastNewline = data.lastIndexOf(0x0a);
+		if (lastNewline < 0) return;
+		const consumed = data.subarray(0, lastNewline + 1);
+		this.#logOffset += consumed.length;
+		for (const line of consumed.toString("utf8").split("\n")) {
+			if (!line) continue;
+			let event: SessionIndexEvent;
+			try {
+				event = JSON.parse(line) as SessionIndexEvent;
+				assertSupportedStateVersion(logFor(this.#agentDir), event);
+			} catch (error) {
+				if (error instanceof UnsupportedStateVersionError) throw error;
+				this.#warnings.push("Corrupt session index entry; replay truncated");
+				return;
+			}
+			if (event.indexSeq <= snapshotSeq) continue;
+			const { checksum, ...unsigned } = event;
+			if (checksum !== sessionIndexChecksum(unsigned) || event.indexSeq !== this.indexSeq + 1) {
+				this.#warnings.push("Corrupt session index entry; replay truncated");
+				return;
+			}
+			this.#events.push(event);
+		}
+	}
+	async refresh(): Promise<void> {
+		await this.#tail();
+	}
+	get indexSeq(): number {
+		return this.#events.at(-1)?.indexSeq ?? 0;
+	}
+	async append(
+		input: Omit<SessionIndexEvent, "version" | "indexSeq" | "checksum" | "ts"> &
+			Partial<Pick<SessionIndexEvent, "ts">>,
+	): Promise<SessionIndexEvent> {
+		await fs.mkdir(dirFor(this.#agentDir), { recursive: true, mode: 0o700 });
+		return withFileLock(logFor(this.#agentDir), async () => {
+			await this.refresh();
+			const unsigned: Omit<SessionIndexEvent, "checksum"> = {
+				...input,
+				version: SDK_STATE_VERSION,
+				indexSeq: this.indexSeq + 1,
+				ts: input.ts ?? Date.now(),
+			};
+			const event: SessionIndexEvent = { ...unsigned, checksum: sessionIndexChecksum(unsigned) };
+			await appendSync(logFor(this.#agentDir), JSON.stringify(event));
+			await this.refresh();
+			return event;
+		});
+	}
+	async snapshot(): Promise<void> {
+		const file = snapshotFor(this.#agentDir);
+		const tmp = `${file}.${process.pid}.tmp`;
+		await fs.writeFile(
+			tmp,
+			JSON.stringify({ version: SDK_STATE_VERSION, indexSeq: this.indexSeq, events: this.#events }),
+			{ mode: 0o600 },
+		);
+		const h = await fs.open(tmp, "r");
+		try {
+			await h.sync();
+		} finally {
+			await h.close();
+		}
+		await fs.rename(tmp, file);
+	}
+	async assertSupportedStateVersions(): Promise<void> {
+		const files = [snapshotFor(this.#agentDir), logFor(this.#agentDir)];
+		for (const file of files) {
+			let source: string;
+			try {
+				source = await fs.readFile(file, "utf8");
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+				throw error;
+			}
+			if (file.endsWith(".json")) {
+				assertSupportedStateVersion(file, JSON.parse(source));
+				continue;
+			}
+			for (const line of source.split("\n")) {
+				if (!line) continue;
+				try {
+					assertSupportedStateVersion(file, JSON.parse(line));
+				} catch (error) {
+					if (error instanceof UnsupportedStateVersionError) throw error;
+				}
+			}
+		}
+	}
+
+	listSessions(): SessionList {
+		const latest = new Map<string, SessionIndexEvent>();
+		for (const event of this.#events) {
+			const previous = latest.get(event.sessionId);
+			latest.set(
+				event.sessionId,
+				event.type === "host_heartbeat" && previous
+					? {
+							...event,
+							locator: previous.locator,
+							endpointMtimeMs: previous.endpointMtimeMs,
+							lifecycleRequestId: previous.lifecycleRequestId,
+						}
+					: event,
+			);
+		}
+		const sessions = [...latest.values()]
+			.filter(event => !["host_unregistered", "session_closed"].includes(event.type))
+			.map(event => ({
+				sessionId: event.sessionId,
+				locator: event.locator,
+				endpointGeneration: event.endpointGeneration,
+				pid: event.pid,
+				endpointMtimeMs: event.endpointMtimeMs,
+				lifecycleRequestId: event.lifecycleRequestId,
+				terminalUncertain: event.type === "lifecycle_terminal" || event.terminalUncertain === true,
+				indexSeq: event.indexSeq,
+				live: alive(event.pid),
+			}));
+		return { indexSeq: this.indexSeq, sessions, warnings: this.#warnings };
+	}
+
+	hostUnregisteredAfter(
+		registration: Pick<
+			IndexedSession,
+			"sessionId" | "endpointGeneration" | "pid" | "indexSeq" | "lifecycleRequestId"
+		>,
+	): { indexSeq: number; lifecycleRequestId?: string } | undefined {
+		const lifecycleRequestId = registration.lifecycleRequestId;
+		const event = this.#events.findLast(
+			item =>
+				item.type === "host_unregistered" &&
+				item.indexSeq > registration.indexSeq &&
+				item.sessionId === registration.sessionId &&
+				item.endpointGeneration === registration.endpointGeneration &&
+				item.pid === registration.pid &&
+				(lifecycleRequestId === undefined || item.lifecycleRequestId === lifecycleRequestId),
+		);
+		return event
+			? {
+					indexSeq: event.indexSeq,
+					...(lifecycleRequestId ? { lifecycleRequestId } : {}),
+				}
+			: undefined;
+	}
+
+	findHostRegistration(
+		sessionId: string,
+		endpointGeneration: number,
+		pid: number,
+		lifecycleRequestId?: string,
+	): IndexedSession | undefined {
+		const event = this.#events.findLast(
+			item =>
+				item.type === "host_registered" &&
+				item.sessionId === sessionId &&
+				item.endpointGeneration === endpointGeneration &&
+				item.pid === pid &&
+				(lifecycleRequestId === undefined || item.lifecycleRequestId === lifecycleRequestId),
+		);
+		return event
+			? {
+					sessionId: event.sessionId,
+					locator: event.locator,
+					endpointGeneration: event.endpointGeneration,
+					pid: event.pid,
+					endpointMtimeMs: event.endpointMtimeMs,
+					lifecycleRequestId: event.lifecycleRequestId,
+					terminalUncertain: false,
+					indexSeq: event.indexSeq,
+					live: alive(event.pid),
+				}
+			: undefined;
+	}
+
+	hasHostRegistrationForLifecycle(sessionId: string, pid: number, lifecycleRequestId: string): boolean {
+		return this.#events.some(
+			event =>
+				event.type === "host_registered" &&
+				event.sessionId === sessionId &&
+				event.pid === pid &&
+				event.lifecycleRequestId === lifecycleRequestId,
+		);
+	}
+}

package/src/sdk/broker/state-version.ts

@@ -0,0 +1,23 @@
+export const SDK_STATE_VERSION = 1;
+
+export class UnsupportedStateVersionError extends Error {
+	readonly code = "unsupported_state_version";
+
+	constructor(
+		readonly file: string,
+		readonly version: number,
+	) {
+		super(`Unsupported SDK state version ${version} in ${file}; maximum supported version is ${SDK_STATE_VERSION}.`);
+		this.name = "UnsupportedStateVersionError";
+	}
+}
+
+export function assertSupportedStateVersion(file: string, value: unknown): void {
+	if (!value || typeof value !== "object") return;
+	const record = value as { version?: unknown; stateVersion?: unknown };
+	for (const version of [record.version, record.stateVersion]) {
+		if (typeof version === "number" && Number.isFinite(version) && version > SDK_STATE_VERSION) {
+			throw new UnsupportedStateVersionError(file, version);
+		}
+	}
+}