@gajae-code/coding-agent 0.15.6 → 0.16.1

package/src/sdk/broker/endpoint-authority.ts

@@ -0,0 +1,86 @@
+import * as fsSync from "node:fs";
+import * as fs from "node:fs/promises";
+
+const MAX_ENDPOINT_BYTES = 4_096n;
+
+export type EndpointFileRead = {
+	source: string;
+	dev: bigint;
+	ino: bigint;
+	nlink: bigint;
+	size: bigint;
+	mtimeNs: bigint;
+	mtimeMs: number;
+};
+
+export type EndpointAuthorityFilesystem = Pick<typeof fs, "open">;
+
+export type IndexedEndpointAuthority = {
+	endpointMtimeMs?: number;
+	endpointFileId?: string;
+};
+
+function readFlags(): number {
+	return fsSync.constants.O_RDONLY | (fsSync.constants.O_NOFOLLOW ?? 0) | (fsSync.constants.O_NONBLOCK ?? 0);
+}
+
+/**
+ * Reads one endpoint from the descriptor opened for its pathname. The opened
+ * object must remain a small, singly-linked regular file with stable identity
+ * and metadata for the whole read; a pathname replacement cannot affect the
+ * bytes returned by this function.
+ */
+export async function readEndpointFile(
+	filePath: string,
+	filesystem: EndpointAuthorityFilesystem = fs,
+): Promise<EndpointFileRead | undefined> {
+	let handle: fs.FileHandle | undefined;
+	try {
+		handle = await filesystem.open(filePath, readFlags());
+		const before = await handle.stat({ bigint: true });
+		if (!before.isFile() || before.nlink !== 1n || before.size > MAX_ENDPOINT_BYTES) return undefined;
+		if (before.size > BigInt(Number.MAX_SAFE_INTEGER)) return undefined;
+		const bytes = Buffer.alloc(Number(before.size));
+		let offset = 0;
+		while (offset < bytes.length) {
+			const { bytesRead } = await handle.read(bytes, offset, bytes.length - offset, offset);
+			if (bytesRead <= 0) return undefined;
+			offset += bytesRead;
+		}
+		const after = await handle.stat({ bigint: true });
+		if (
+			before.dev !== after.dev ||
+			before.ino !== after.ino ||
+			before.nlink !== after.nlink ||
+			before.size !== after.size ||
+			before.mtimeNs !== after.mtimeNs
+		)
+			return undefined;
+		return {
+			source: bytes.toString("utf8"),
+			dev: before.dev,
+			ino: before.ino,
+			nlink: before.nlink,
+			size: before.size,
+			mtimeNs: before.mtimeNs,
+			mtimeMs: Number(before.mtimeNs) / 1_000_000,
+		};
+	} catch {
+		return undefined;
+	} finally {
+		await handle?.close().catch(() => undefined);
+	}
+}
+
+/** Match a descriptor-bound endpoint read to the index representation. */
+export function matchesIndexedEndpointFile(
+	file: Pick<EndpointFileRead, "dev" | "ino" | "mtimeMs">,
+	authority: IndexedEndpointAuthority,
+): boolean {
+	return (
+		authority.endpointMtimeMs !== undefined &&
+		Number.isFinite(authority.endpointMtimeMs) &&
+		Math.abs(file.mtimeMs - authority.endpointMtimeMs) <= 0.001 &&
+		(authority.endpointFileId === undefined || authority.endpointFileId === `${file.dev}:${file.ino}`)
+	);
+}

package/src/sdk/broker/ensure.ts

@@ -3,9 +3,21 @@ import { randomUUID } from "node:crypto";
 import type { FileHandle } from "node:fs/promises";
 import * as fs from "node:fs/promises";
 import path from "node:path";
+import packageJson from "../../../package.json" with { type: "json" };
+import { SdkClient } from "../client/client";
 import { type BrokerDiscovery, brokerProcessIncarnation, readBrokerDiscovery } from "./discovery";
 import { resolveSdkInternalSpawnCommand, type SdkInternalSpawnCommand } from "./runtime";
 import { BrokerStartupError, clearBrokerStartupFailureMarker, readBrokerStartupFailureMarker } from "./startup-failure";
+
+function resolveExpectedBrokerGeneration(): string {
+	const v = (packageJson as { version?: unknown }).version;
+	return typeof v === "string" && v.length > 0 ? v : "unknown";
+}
+
+function isBrokerGenerationCompatible(discovery: BrokerDiscovery | null): boolean {
+	if (!discovery) return false;
+	return discovery.packageGeneration === resolveExpectedBrokerGeneration();
+}
 export interface EnsureBrokerSettings {
 	agentDir: string;
 	heartbeatTtlMs?: number;
@@ -232,6 +244,11 @@ function registerBrokerOwner(
 function brokerSpawnEnvironment(command: SdkInternalSpawnCommand, override?: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
 	const environment = { ...(override ?? command.env) };
 	delete environment.BUN_OPTIONS;
+	// The master capability is a transient in-memory dispatch input. A broker
+	// cold-started from the master's own Bash environment would otherwise inherit
+	// it and pass it on to every substrate child it later launches, so it is
+	// stripped at the lifecycle boundary exactly as lifecycle children strip it.
+	delete environment.GJC_MASTER_CAPABILITY;
 	if (command.kind === "bun-source") {
 		delete environment.PI_COMPILED;
 		delete environment.GJC_COMPILED;
@@ -243,6 +260,47 @@ function fixtureLeaseUnavailable(): Error {
 	return new Error("fixture_broker_lease_unavailable");
 }
 
+const STALE_BROKER_SHUTDOWN_TIMEOUT_MS = 5_000;
+const STALE_BROKER_POLL_MS = 50;
+
+type BrokerOwnerIdentity = Pick<BrokerDiscovery, "ownerId" | "pid" | "incarnation">;
+
+function sameBrokerOwner(left: BrokerOwnerIdentity | null, right: BrokerOwnerIdentity): boolean {
+	return Boolean(
+		left && left.ownerId === right.ownerId && left.pid === right.pid && left.incarnation === right.incarnation,
+	);
+}
+
+async function retireStaleBrokerGeneration(stale: BrokerDiscovery, settings: EnsureBrokerSettings): Promise<void> {
+	let shutdownSucceeded = false;
+	try {
+		const current = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+		if (!current || !sameBrokerOwner(current, stale)) return;
+		const client = await SdkClient.connect(current.url, current.token, { timeoutMs: 2_000 });
+		try {
+			await client.global("broker.shutdown", {});
+			shutdownSucceeded = true;
+		} finally {
+			await client.close().catch(() => {});
+		}
+	} catch {}
+	if (!shutdownSucceeded) {
+		try {
+			if (brokerProcessIncarnation(stale.pid) === stale.incarnation) {
+				try {
+					process.kill(stale.pid, "SIGTERM");
+				} catch {}
+			}
+		} catch {}
+	}
+	// Wait for the stale identity to disappear (owner-fenced: pid+incarnation).
+	const deadline = Date.now() + STALE_BROKER_SHUTDOWN_TIMEOUT_MS;
+	while (Date.now() < deadline) {
+		const current = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+		if (!sameBrokerOwner(current, stale)) break;
+		await sleep(STALE_BROKER_POLL_MS);
+	}
+}
 function createFixtureLeaseFromChild(child: ChildProcess, terminate: () => Promise<void>): ExactFixtureBrokerLease {
 	let termination: Promise<void> | undefined;
 	const hasExited = (): boolean => child.exitCode !== null || child.signalCode !== null || child.pid === undefined;
@@ -295,11 +353,24 @@ async function ensureBrokerOnce(settings: EnsureBrokerSettings, initiator: Ensur
 		if (priorOwner.canReuse(existing)) return { kind: "prior-local-owner", discovery: existing!, owner: priorOwner };
 		await priorOwner.stop();
 		const discoveredAfterCleanup = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
-		if (discoveredAfterCleanup) return { kind: "external-discovery", discovery: discoveredAfterCleanup };
+		if (discoveredAfterCleanup && isBrokerGenerationCompatible(discoveredAfterCleanup))
+			return { kind: "external-discovery", discovery: discoveredAfterCleanup };
+		// A stale-generation discovery after cleanup must not be reused — fall through to replacement.
+		if (!discoveredAfterCleanup) {
+			// no discovery left after cleanup — fall through to spawn
+		} else {
+			await retireStaleBrokerGeneration(discoveredAfterCleanup, settings);
+			const afterRetire = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+			if (afterRetire && isBrokerGenerationCompatible(afterRetire))
+				return { kind: "external-discovery", discovery: afterRetire };
+		}
 	} else if (existing) {
-		return { kind: "external-discovery", discovery: existing };
+		if (isBrokerGenerationCompatible(existing)) return { kind: "external-discovery", discovery: existing };
+		await retireStaleBrokerGeneration(existing, settings);
+		const afterRetire = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+		if (afterRetire && isBrokerGenerationCompatible(afterRetire))
+			return { kind: "external-discovery", discovery: afterRetire };
 	}
-
 	const command = resolveSdkInternalSpawnCommand("broker-internal");
 	const spawnLog = await openBrokerSpawnLog(settings.agentDir);
 	// A stale marker must never be misattributed to this spawn; clear it first.
@@ -472,6 +543,13 @@ export function startFixtureBrokerCommandWithLeaseForTest(command: FixtureBroker
 export function brokerOwnerForTest(agentDir: string): BrokerOwner | undefined {
 	return owners.get(agentDir);
 }
+/** Test hook: verifies the complete broker owner identity used during stale retirement. */
+export function brokerOwnerIdentityMatchesForTest(
+	left: BrokerOwnerIdentity | null,
+	right: BrokerOwnerIdentity,
+): boolean {
+	return sameBrokerOwner(left, right);
+}
 /** Test hook: drives the detached-broker reap on a controllable child surface. */
 export function reapSpawnedBrokerForTest(child: ChildProcess, timing: ReapTiming = DEFAULT_REAP_TIMING): Promise<void> {
 	return reapSpawnedBroker(child, timing);

package/src/sdk/broker/index.ts

@@ -4,6 +4,9 @@ export * from "./ensure";
 export * from "./identity";
 export * from "./lifecycle";
 export * from "./lifecycle-ledger";
+export * from "./master-capability";
 export * from "./session-index";
+export * from "./spawn-authority";
+export * from "./spawn-substrate";
 export * from "./startup-budget";
 export * from "./transport";

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

@@ -55,6 +55,7 @@ export interface LifecycleDurableEffectsReceipt {
 		cwdDigest: string;
 		created: boolean;
 		reused: boolean;
+		createdBranch: boolean;
 		branchDigest?: string;
 	};
 	transcript?: {
@@ -62,6 +63,11 @@ export interface LifecycleDurableEffectsReceipt {
 		contentDigest: string;
 	};
 	startup?: LifecycleStartupFailureReceipt;
+	timings?: {
+		worktreePreparationMs?: number;
+		dependencyPreparationMs?: number;
+		spawnAuthorizedAtOffsetMs?: number;
+	};
 	digest?: string;
 }