@gajae-code/coding-agent 0.15.6 → 0.16.1

package/src/sdk/broker/master-capability.ts

@@ -0,0 +1,232 @@
+import { randomBytes } from "node:crypto";
+import * as path from "node:path";
+import { readEndpointFile } from "./endpoint-authority";
+import {
+	type IndexedSession,
+	isSessionAuthorityEligible,
+	type MasterRoleAttestationV2,
+	type SessionIndex,
+} from "./session-index";
+import type { MasterCapabilityVerifier } from "./spawn-authority";
+
+const MASTER_CAPABILITY_VERIFY_TIMEOUT_MS = 2_000;
+
+export type SessionEndpoint = {
+	url: string;
+	token: string;
+};
+
+function processIdentity(record: Pick<IndexedSession, "hostIncarnation" | "processIncarnation">): string | undefined {
+	return record.hostIncarnation ?? record.processIncarnation;
+}
+
+function matchesAttestation(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
+	);
+}
+
+function isEffectiveMasterHost(
+	record: IndexedSession,
+	ownerSessionId: string,
+	attestationEpoch: string,
+): record is IndexedSession & { masterRole: MasterRoleAttestationV2 } {
+	const attestation = record.masterRole;
+	return (
+		record.endpointGeneration > 0 &&
+		record.live &&
+		!record.terminal &&
+		!record.terminalUncertain &&
+		isSessionAuthorityEligible(record) &&
+		attestation !== undefined &&
+		attestation.version === 2 &&
+		attestation.role === "master" &&
+		attestation.ownerSessionId === ownerSessionId &&
+		attestation.attestationEpoch === attestationEpoch &&
+		attestation.launchPid === record.pid &&
+		attestation.launchProcessIncarnation === processIdentity(record)
+	);
+}
+
+function sameAttachment(left: IndexedSession, right: IndexedSession): boolean {
+	return (
+		left.sessionId === right.sessionId &&
+		left.endpointGeneration === right.endpointGeneration &&
+		left.pid === right.pid &&
+		left.endpointMtimeMs === right.endpointMtimeMs &&
+		left.endpointFileId === right.endpointFileId &&
+		left.hostIncarnation === right.hostIncarnation &&
+		left.processIncarnation === right.processIncarnation &&
+		left.indexSeq === right.indexSeq &&
+		left.masterRole !== undefined &&
+		right.masterRole !== undefined &&
+		matchesAttestation(left.masterRole, right.masterRole)
+	);
+}
+
+function endpointFileId(stat: { dev: bigint; ino: bigint }): string {
+	return `${stat.dev}:${stat.ino}`;
+}
+
+function adoptedDirectAttestation(
+	rows: readonly IndexedSession[],
+	effective: IndexedSession & { masterRole: MasterRoleAttestationV2 },
+): boolean {
+	return rows.some(row => {
+		const direct = row.masterRole;
+		return (
+			row.sessionId === effective.sessionId &&
+			row.endpointGeneration === 0 &&
+			row.pid === effective.masterRole.launchPid &&
+			processIdentity(row) === effective.masterRole.launchProcessIncarnation &&
+			direct !== undefined &&
+			matchesAttestation(direct, effective.masterRole)
+		);
+	});
+}
+
+/** Reads and validates a registered host's authenticated endpoint record. */
+export async function readEndpoint(record: IndexedSession): Promise<SessionEndpoint | undefined> {
+	if (record.endpointMtimeMs === undefined || record.endpointFileId === undefined) return undefined;
+	try {
+		const endpointPath = path.join(record.locator.stateRoot, "sdk", `${record.sessionId}.json`);
+		const file = await readEndpointFile(endpointPath);
+		if (!file) return undefined;
+		const endpoint = JSON.parse(file.source) as Record<string, unknown>;
+		if (
+			endpoint.sessionId !== record.sessionId ||
+			endpoint.pid !== record.pid ||
+			typeof endpoint.url !== "string" ||
+			typeof endpoint.token !== "string" ||
+			endpoint.url.length === 0 ||
+			endpoint.token.length === 0 ||
+			endpointFileId(file) !== record.endpointFileId ||
+			Math.abs(file.mtimeMs - record.endpointMtimeMs) > 0.001
+		)
+			return undefined;
+		const url = new URL(endpoint.url);
+		if (url.protocol !== "ws:" && url.protocol !== "wss:") return undefined;
+		return { url: endpoint.url, token: endpoint.token };
+	} catch {
+		return undefined;
+	}
+}
+
+async function verifyOverAttachment(input: {
+	endpoint: SessionEndpoint;
+	nonce: string;
+	attestationEpoch: string;
+	capability: string;
+}): Promise<boolean> {
+	const settled = Promise.withResolvers<boolean>();
+	let complete = false;
+	const settle = (allowed: boolean): void => {
+		if (complete) return;
+		complete = true;
+		settled.resolve(allowed);
+	};
+	let socket: WebSocket | undefined;
+	try {
+		const url = new URL(input.endpoint.url);
+		url.searchParams.set("token", input.endpoint.token);
+		socket = new WebSocket(url);
+		const onClose = (): void => {
+			settle(false);
+		};
+		const onError = (): void => {
+			settle(false);
+		};
+		const onMessage = (event: MessageEvent): void => {
+			let frame: Record<string, unknown>;
+			try {
+				const parsed = JSON.parse(String(event.data));
+				if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return;
+				frame = parsed as Record<string, unknown>;
+			} catch {
+				return;
+			}
+			if (frame.type === "hello") {
+				try {
+					socket?.send(JSON.stringify({ type: "hello", protocolVersion: 3, capabilities: [] }));
+					socket?.send(
+						JSON.stringify({
+							type: "master_capability_verify",
+							id: input.nonce,
+							nonce: input.nonce,
+							attestationEpoch: input.attestationEpoch,
+							capability: input.capability,
+						}),
+					);
+				} catch {
+					settle(false);
+				}
+				return;
+			}
+			if (frame.type !== "master_capability_verify_result") return;
+			settle(
+				frame.id === input.nonce &&
+					frame.ok === true &&
+					frame.nonce === input.nonce &&
+					frame.attestationEpoch === input.attestationEpoch,
+			);
+		};
+		socket.addEventListener("error", onError);
+		socket.addEventListener("close", onClose);
+		socket.addEventListener("message", onMessage);
+		return await Promise.race([settled.promise, Bun.sleep(MASTER_CAPABILITY_VERIFY_TIMEOUT_MS).then(() => false)]);
+	} catch {
+		return false;
+	} finally {
+		try {
+			socket?.close();
+		} catch {
+			// Closing an already failed attachment is best effort.
+		}
+	}
+}
+
+/** Creates the ephemeral effective-host verifier used by broker spawn admission. */
+export function createMasterCapabilityVerifier(index: SessionIndex): MasterCapabilityVerifier {
+	return {
+		async verifyMasterCapability(
+			ownerSessionId: string,
+			rawCapability: string,
+			attestationEpoch: string,
+		): Promise<{ allowed: boolean }> {
+			try {
+				await index.refresh();
+				const rows = index.listSessionIdentities();
+				const effective = rows.filter(row => isEffectiveMasterHost(row, ownerSessionId, attestationEpoch));
+				if (effective.length !== 1) return { allowed: false };
+				const attachment = effective[0]!;
+				if (!adoptedDirectAttestation(rows, attachment)) return { allowed: false };
+				const endpoint = await readEndpoint(attachment);
+				if (!endpoint) return { allowed: false };
+				await index.refresh();
+				const current = index.listSessionIdentities().find(row => sameAttachment(attachment, row));
+				if (!current || !isEffectiveMasterHost(current, ownerSessionId, attestationEpoch))
+					return { allowed: false };
+				const nonce = randomBytes(32).toString("base64url");
+				const allowed = await verifyOverAttachment({
+					endpoint,
+					nonce,
+					attestationEpoch,
+					capability: rawCapability,
+				});
+				await index.refresh();
+				const after = index.listSessionIdentities().find(row => sameAttachment(attachment, row));
+				return {
+					allowed:
+						allowed && after !== undefined && isEffectiveMasterHost(after, ownerSessionId, attestationEpoch),
+				};
+			} catch {
+				return { allowed: false };
+			}
+		},
+	};
+}

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

@@ -1,14 +1,16 @@
-import { createHash, randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import path from "node:path";
 import { logger, resolveEquivalentPath } from "@gajae-code/utils";
 import { nativeProcessBindings } from "@gajae-code/utils/native-process";
 import { withFileLock } from "../../config/file-lock";
+import { repo } from "../../utils/git";
 import { processIncarnation } from "./process-incarnation";
 import {
+	assertSupportedSessionIndexEventVersion,
 	assertSupportedSnapshotVersion,
-	assertSupportedStateVersion,
 	SDK_STATE_VERSION,
+	SESSION_INDEX_EVENT_VERSION,
 	SESSION_INDEX_SNAPSHOT_VERSION,
 	UnsupportedStateVersionError,
 } from "./state-version";
@@ -53,12 +55,79 @@ export interface SessionIndexProcessObservation {
 	readonly incarnation: string;
 	readonly isRunning: () => boolean;
 }
+/**
+ * Canonical location facts for one SDK session.
+ *
+ * `cwd` is always a realpath-canonicalized directory. `worktreeRoot` is the
+ * canonical Git worktree root when `cwd` is in a worktree, otherwise `null`.
+ * `stateRoot` retains its host-provided authority spelling and is never derived
+ * from either canonical path.
+ */
+export type SessionLocatorV2 = {
+	cwd: string;
+	worktreeRoot: string | null;
+	stateRoot: string;
+};
+
+/** Durable master-role facts. `attestationEpoch` is opaque random broker state. */
+export type MasterRoleAttestationV2 = {
+	version: 2;
+	ownerSessionId: string;
+	launchPid: number;
+	launchProcessIncarnation: string;
+	role: "master";
+	attestationEpoch: string;
+};
+
+export function newMasterAttestationEpoch(): string {
+	return randomBytes(32).toString("base64url");
+}
+
+/** Canonicalize a cwd without making an unavailable path a launch failure. */
+export async function canonicalSessionCwd(cwd: string): Promise<string> {
+	try {
+		return await fs.realpath(cwd);
+	} catch {
+		return path.resolve(cwd);
+	}
+}
+
+/** Resolve the canonical worktree root; non-Git and probe failures are `null`. */
+export async function sessionWorktreeRoot(cwd: string): Promise<string | null> {
+	try {
+		const repository = await repo.resolve(cwd);
+		return repository ? await canonicalSessionCwd(repository.repoRoot) : null;
+	} catch {
+		return null;
+	}
+}
+
+/** Build the only permitted locator shape for a newly registered session. */
+export async function resolveSessionLocator(cwd: string, stateRoot: string): Promise<SessionLocatorV2> {
+	const canonicalCwd = await canonicalSessionCwd(cwd);
+	return { cwd: canonicalCwd, worktreeRoot: await sessionWorktreeRoot(canonicalCwd), stateRoot };
+}
+
+function sessionLocatorV2(locator: unknown): locator is SessionLocatorV2 {
+	if (typeof locator !== "object" || locator === null || Array.isArray(locator)) return false;
+	const keys = Object.keys(locator);
+	if (keys.length !== 3 || !keys.every(key => key === "cwd" || key === "worktreeRoot" || key === "stateRoot"))
+		return false;
+	return (
+		typeof (locator as { cwd?: unknown }).cwd === "string" &&
+		(locator as { cwd: string }).cwd.length > 0 &&
+		(typeof (locator as { worktreeRoot?: unknown }).worktreeRoot === "string" ||
+			(locator as { worktreeRoot?: unknown }).worktreeRoot === null) &&
+		typeof (locator as { stateRoot?: unknown }).stateRoot === "string" &&
+		(locator as { stateRoot: string }).stateRoot.length > 0
+	);
+}
 export interface SessionIndexEvent {
-	version: typeof SDK_STATE_VERSION;
+	version: typeof SDK_STATE_VERSION | typeof SESSION_INDEX_EVENT_VERSION;
 	indexSeq: number;
 	type: SessionIndexEventType;
 	sessionId: string;
-	locator: { repo: string; stateRoot: string };
+	locator: SessionLocatorV2;
 	endpointGeneration: number;
 	pid: number;
 	/**
@@ -69,23 +138,28 @@ export interface SessionIndexEvent {
 	 */
 	processIncarnation?: string;
 	endpointMtimeMs?: number;
+	/** Immutable endpoint file identity captured by the broker at registration. */
+	endpointFileId?: string;
 	lifecycleRequestId?: string;
 	terminalUncertain?: boolean;
 	/** OS process incarnation (C1); absent on legacy v1/v2 events. */
 	hostIncarnation?: string;
 	/** Present on host_heartbeat checkpoints (C2). */
 	activity?: SessionActivity;
+	masterRole?: MasterRoleAttestationV2;
 	ts: number;
 	checksum: string;
 }
 export interface IndexedSession {
 	sessionId: string;
-	locator: { repo: string; stateRoot: string };
+	locator: SessionLocatorV2;
 	endpointGeneration: number;
 	pid: number;
 	/** OS start incarnation of `pid` as published by its own host at registration. */
 	processIncarnation?: string;
 	endpointMtimeMs?: number;
+	/** Immutable endpoint file identity captured by the broker at registration. */
+	endpointFileId?: string;
 	live: boolean;
 	indexSeq: number;
 	lifecycleRequestId?: string;
@@ -95,6 +169,7 @@ export interface IndexedSession {
 	activity?: SessionActivity;
 	/** Wall-clock timestamp of the latest admitted heartbeat, when one exists. */
 	lastHeartbeatAt?: number;
+	masterRole?: MasterRoleAttestationV2;
 	/** True when more than one unresolved authority-fencing state-root identity claims this session id. */
 	ambiguous: boolean;
 	/** True when the identity's latest event is terminal (DR-1 retains stopped rows for inspection/offline tail). */
@@ -164,7 +239,10 @@ interface SessionIndexScan {
 }
 
 /** Admission-fence rejection codes recorded in the durable index audit (C5/C4). */
-export type SessionIndexAuditCode = "rejected_superseded_incarnation" | "rejected_after_tombstone";
+export type SessionIndexAuditCode =
+	| "rejected_superseded_incarnation"
+	| "rejected_after_tombstone"
+	| "rejected_legacy_locator";
 export interface SessionIndexAuditRecord {
 	version: typeof SDK_STATE_VERSION;
 	code: SessionIndexAuditCode;
@@ -268,6 +346,14 @@ const tupleKey = (event: SessionIndexEvent) =>
 const effectiveIncarnation = (event: SessionIndexEvent) => event.hostIncarnation ?? event.processIncarnation;
 const identityKey = (event: SessionIndexEvent) => `${tupleKey(event)}\u0000${effectiveIncarnation(event) ?? ""}`;
 
+function hasSessionLocatorV2(event: SessionIndexEvent): boolean {
+	return sessionLocatorV2(event.locator);
+}
+
+function legacyLocatorDiagnostic(event: SessionIndexEvent): string {
+	return `Session ${event.sessionId} has a legacy locator row and must re-register.`;
+}
+
 interface ResolvedRetentionPolicy {
 	clock: () => number;
 	maxAgeMs: number;
@@ -305,7 +391,17 @@ interface Admission {
  */
 function admitEvents(events: SessionIndexEvent[]): Admission {
 	const authoritative = new Map<string, { incarnation: string | undefined; indexSeq: number }>();
+	const rejected: RejectedEvent[] = [];
 	for (const event of events) {
+		if (!hasSessionLocatorV2(event)) {
+			rejected.push({
+				code: "rejected_legacy_locator",
+				event,
+				supersededByIncarnation: undefined,
+				supersededByIndexSeq: event.indexSeq,
+			});
+			continue;
+		}
 		if (event.type !== "host_registered") continue;
 		const key = tupleKey(event);
 		const current = authoritative.get(key);
@@ -314,8 +410,8 @@ function admitEvents(events: SessionIndexEvent[]): Admission {
 		}
 	}
 	const admitted: SessionIndexEvent[] = [];
-	const rejected: RejectedEvent[] = [];
 	for (const event of events) {
+		if (!hasSessionLocatorV2(event)) continue;
 		const authority = authoritative.get(tupleKey(event));
 		if (
 			authority !== undefined &&
@@ -378,7 +474,7 @@ function auditRecords(events: SessionIndexEvent[], ts: number): SessionIndexAudi
 		indexSeq: rejection.event.indexSeq,
 		sessionId: rejection.event.sessionId,
 		endpointGeneration: rejection.event.endpointGeneration,
-		stateRoot: rejection.event.locator.stateRoot,
+		stateRoot: hasSessionLocatorV2(rejection.event) ? rejection.event.locator.stateRoot : "unknown",
 		...(rejection.event.hostIncarnation !== undefined ? { hostIncarnation: rejection.event.hostIncarnation } : {}),
 		...(rejection.supersededByIncarnation !== undefined
 			? { supersededByIncarnation: rejection.supersededByIncarnation }
@@ -499,10 +595,12 @@ function projectIdentity(
 		pid: latest.pid,
 		processIncarnation: latest.processIncarnation,
 		endpointMtimeMs: latest.endpointMtimeMs,
+		endpointFileId: latest.endpointFileId,
 		lifecycleRequestId: latest.lifecycleRequestId,
 		terminalUncertain,
 		indexSeq: latest.indexSeq,
 		hostIncarnation: latest.hostIncarnation,
+		masterRole: latest.masterRole,
 		identityProvenance: recordedIncarnation === undefined ? "legacy" : "composite",
 		activity: heartbeat?.activity,
 		lastHeartbeatAt: heartbeat?.ts,
@@ -1140,6 +1238,9 @@ export class SessionIndex {
 		if (scan.diagnosis.status === "unsupported") throw scan.unsupportedError!;
 		this.#events = [...scan.snapshotEvents, ...scan.validLogEvents];
 		this.#warnings = [];
+		for (const event of this.#events) {
+			if (!hasSessionLocatorV2(event)) this.#warn(legacyLocatorDiagnostic(event));
+		}
 		this.#logOffset = scan.logContents?.length ?? 0;
 		this.#corruptSuffix = scan.diagnosis.status === "corrupt";
 		if (scan.diagnosis.reason === "invalid snapshot") this.#warnings.push("Invalid session index snapshot");
@@ -1195,7 +1296,7 @@ export class SessionIndex {
 			if (Array.isArray(snapshot.events)) {
 				try {
 					for (const event of snapshot.events) {
-						assertSupportedStateVersion(snapshotFor(this.#agentDir), event);
+						assertSupportedSessionIndexEventVersion(snapshotFor(this.#agentDir), event);
 						supportedEvents.push(event as SessionIndexEvent);
 					}
 				} catch (error) {
@@ -1234,7 +1335,7 @@ export class SessionIndex {
 				if (!line) continue;
 				try {
 					const event = JSON.parse(line) as SessionIndexEvent;
-					assertSupportedStateVersion(logFor(this.#agentDir), event);
+					assertSupportedSessionIndexEventVersion(logFor(this.#agentDir), event);
 					const { checksum, ...unsigned } = event;
 					if (checksum !== sessionIndexChecksum(unsigned)) {
 						corrupt = true;
@@ -1401,7 +1502,7 @@ export class SessionIndex {
 			let event: SessionIndexEvent;
 			try {
 				event = JSON.parse(line) as SessionIndexEvent;
-				assertSupportedStateVersion(logFor(this.#agentDir), event);
+				assertSupportedSessionIndexEventVersion(logFor(this.#agentDir), event);
 			} catch (error) {
 				if (error instanceof UnsupportedStateVersionError) throw error;
 				corrupt = true;
@@ -1485,7 +1586,7 @@ export class SessionIndex {
 				}
 				const unsigned: Omit<SessionIndexEvent, "checksum"> = {
 					...input,
-					version: SDK_STATE_VERSION,
+					version: SESSION_INDEX_EVENT_VERSION,
 					indexSeq: this.indexSeq + 1,
 					ts: input.ts ?? Date.now(),
 				};
@@ -1535,7 +1636,7 @@ export class SessionIndex {
 						session.processIncarnation === expected.processIncarnation &&
 						(session.hostIncarnation ?? session.processIncarnation) ===
 							(expected.hostIncarnation ?? expected.processIncarnation) &&
-						resolveEquivalentPath(session.locator.repo) === resolveEquivalentPath(expected.locator.repo) &&
+						resolveEquivalentPath(session.locator.cwd) === resolveEquivalentPath(expected.locator.cwd) &&
 						path.resolve(session.locator.stateRoot) === path.resolve(expected.locator.stateRoot),
 				);
 				let currentRoot: IndexedSession | undefined;
@@ -1543,7 +1644,7 @@ export class SessionIndex {
 					if (
 						session.sessionId !== expected.sessionId ||
 						session.terminal ||
-						resolveEquivalentPath(session.locator.repo) !== resolveEquivalentPath(expected.locator.repo) ||
+						resolveEquivalentPath(session.locator.cwd) !== resolveEquivalentPath(expected.locator.cwd) ||
 						path.resolve(session.locator.stateRoot) !== path.resolve(expected.locator.stateRoot)
 					)
 						continue;
@@ -1564,7 +1665,7 @@ export class SessionIndex {
 				)
 					return false;
 				const unsigned: Omit<SessionIndexEvent, "checksum"> = {
-					version: SDK_STATE_VERSION,
+					version: SESSION_INDEX_EVENT_VERSION,
 					indexSeq: this.indexSeq + 1,
 					ts: Date.now(),
 					type: "host_unregistered",
@@ -2100,7 +2201,7 @@ export class SessionIndex {
 					const current = probed.get(`${row.sessionId}\u0000${row.endpointGeneration}\u0000${row.pid}`);
 					if (current === undefined || current !== recordedIncarnation) continue;
 					const unsigned: Omit<SessionIndexEvent, "checksum"> = {
-						version: SDK_STATE_VERSION,
+						version: SESSION_INDEX_EVENT_VERSION,
 						indexSeq: this.indexSeq + events.length + 1,
 						type: "host_heartbeat",
 						sessionId: row.sessionId,
@@ -2109,6 +2210,7 @@ export class SessionIndex {
 						pid: row.pid,
 						...(row.processIncarnation === undefined ? {} : { processIncarnation: row.processIncarnation }),
 						...(row.hostIncarnation === undefined ? {} : { hostIncarnation: row.hostIncarnation }),
+						...(row.masterRole === undefined ? {} : { masterRole: row.masterRole }),
 						activity: { state: "active", at: now },
 						ts: now,
 					};
@@ -2145,7 +2247,7 @@ export class SessionIndex {
 				item.sessionId === registration.sessionId &&
 				item.endpointGeneration === registration.endpointGeneration &&
 				item.pid === registration.pid &&
-				resolveEquivalentPath(item.locator.repo) === resolveEquivalentPath(registration.locator.repo) &&
+				resolveEquivalentPath(item.locator.cwd) === resolveEquivalentPath(registration.locator.cwd) &&
 				path.resolve(item.locator.stateRoot) === path.resolve(registration.locator.stateRoot) &&
 				(lifecycleRequestId === undefined || item.lifecycleRequestId === lifecycleRequestId) &&
 				(incarnation === undefined || (item.hostIncarnation ?? item.processIncarnation) === incarnation),
@@ -2180,10 +2282,12 @@ export class SessionIndex {
 					pid: event.pid,
 					processIncarnation: event.processIncarnation,
 					endpointMtimeMs: event.endpointMtimeMs,
+					endpointFileId: event.endpointFileId,
 					lifecycleRequestId: event.lifecycleRequestId,
 					terminalUncertain: false,
 					indexSeq: event.indexSeq,
 					hostIncarnation: event.hostIncarnation,
+					masterRole: event.masterRole,
 					identityProvenance: event.hostIncarnation === undefined ? "legacy" : "composite",
 					ambiguous: false,
 					live: alive(event.pid),