@gajae-code/coding-agent 0.15.6 → 0.16.0

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

@@ -232,6 +232,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;

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.ts

@@ -66,6 +66,7 @@ import {
 	sanitizeSdkStartupMessage,
 } from "../startup-capability";
 import type { Broker, BrokerCleanupEvidence, BrokerCleanupIdentity, BrokerResponse } from "./broker";
+import { matchesIndexedEndpointFile, readEndpointFile } from "./endpoint-authority";
 import { decodeLifecycleUtf8, parseLifecycleJson } from "./lifecycle-codec";
 import type {
 	LifecycleCleanupProof,
@@ -81,7 +82,12 @@ import {
 	processIncarnation,
 } from "./process-incarnation";
 import { resolveSdkInternalSpawnCommand, type SdkInternalSpawnCommand } from "./runtime";
-import { type IndexedSession, isSessionAuthorityEligible } from "./session-index";
+import {
+	type IndexedSession,
+	isSessionAuthorityEligible,
+	resolveSessionLocator,
+	type SessionLocatorV2,
+} from "./session-index";
 import {
 	cancellableSleep,
 	DEFAULT_READINESS_TIMEOUT_MS,
@@ -89,6 +95,7 @@ import {
 	READINESS_TIMEOUT_INVALID_MESSAGE,
 	startupQueueWaitMs,
 } from "./startup-budget";
+import { worktreeOccupant } from "./worktree-occupancy";
 
 export {
 	type ProcessIncarnationCommandRunner,
@@ -612,7 +619,7 @@ function text(value: unknown): string | undefined {
 	return typeof value === "string" && value ? value : undefined;
 }
 
-function validateBrokerModelPresetSync(agentDir: string, requestedProfile: string): string | BrokerResponse {
+export function validateBrokerModelPresetSync(agentDir: string, requestedProfile: string): string | BrokerResponse {
 	const modelsConfigFile = ModelsConfigFile.relocate(path.join(agentDir, "models.yml"));
 	modelsConfigFile.invalidate();
 	const loaded = modelsConfigFile.tryLoad();
@@ -733,10 +740,13 @@ function lifecycleWorktreeTarget(input: Input): SessionLifecycleWorktreeTarget |
 }
 
 type LiveResumeRecord = {
-	locator: { repo: string; stateRoot: string };
+	sessionId: string;
+	locator: SessionLocatorV2;
 	endpointGeneration: number;
 	pid: number;
 	endpointMtimeMs?: number;
+	processIncarnation?: string;
+	hostIncarnation?: string;
 	live: boolean;
 	ambiguous: boolean;
 };
@@ -755,7 +765,7 @@ type ResumeScope = {
 };
 function sameResumeLocator(record: LiveResumeRecord, cwd: string, root: string): boolean {
 	return (
-		resolveEquivalentPath(record.locator.repo) === resolveEquivalentPath(cwd) &&
+		resolveEquivalentPath(record.locator.cwd) === resolveEquivalentPath(cwd) &&
 		resolveEquivalentPath(record.locator.stateRoot) === resolveEquivalentPath(root)
 	);
 }
@@ -777,10 +787,24 @@ function sameLiveResumeRecord(expected: LiveResumeRecord, current: LiveResumeRec
 		current.endpointGeneration === expected.endpointGeneration &&
 		current.pid === expected.pid &&
 		current.endpointMtimeMs === expected.endpointMtimeMs &&
-		sameResumeLocator(current, expected.locator.repo, expected.locator.stateRoot)
+		(current.hostIncarnation ?? current.processIncarnation) ===
+			(expected.hostIncarnation ?? expected.processIncarnation) &&
+		sameResumeLocator(current, expected.locator.cwd, expected.locator.stateRoot)
 	);
 }
 
+function liveResumeAuthority(
+	sessions: readonly LiveResumeRecord[],
+	sessionId: string,
+): { kind: "none" } | { kind: "ambiguous" } | { kind: "live"; record: LiveResumeRecord } {
+	const indexedCandidates = sessions.filter(session => session.sessionId === sessionId);
+	if (indexedCandidates.some(session => !isSessionAuthorityEligible(session))) return { kind: "ambiguous" };
+	const liveCandidates = indexedCandidates.filter(session => session.live);
+	if (liveCandidates.length > 1) return { kind: "ambiguous" };
+	const record = liveCandidates[0];
+	return record ? { kind: "live", record } : { kind: "none" };
+}
+
 type ValidatedTranscript = {
 	path: string;
 	id: string;
@@ -912,18 +936,36 @@ async function validateLiveResumeScope(
 		sessionIdentity: session.identity,
 	};
 }
-async function reconcileReadyScope(broker: Broker, id: string, scope: string | undefined): Promise<void> {
+async function reconcileReadyScope(
+	broker: Broker,
+	id: string,
+	scope: string | undefined,
+	root: string,
+	expected: EffectMarker,
+): Promise<void> {
 	if (!scope) return;
 	await broker.index.refresh();
-	const record = broker.index.listSessions().sessions.find(session => session.sessionId === id);
-	if (!record || record.locator.repo === scope) return;
-	// The host records its physical cwd, which Darwin canonicalizes from /var to
-	// /private/var. Preserve the lifecycle caller's lexical cwd for ACP's scoped
-	// listing while retaining the host-provided state root for endpoint binding.
+	const record = broker.index
+		.listSessions()
+		.sessions.find(
+			session =>
+				session.sessionId === id &&
+				resolveEquivalentPath(session.locator.stateRoot) === resolveEquivalentPath(root) &&
+				session.pid === expected.pid &&
+				(session.hostIncarnation ?? session.processIncarnation) === expected.incarnation &&
+				session.lifecycleRequestId === expected.effectMarker,
+		);
+	if (!record) return;
+	const cwd = canonicalExistingPath(scope);
+	if (record.locator.cwd === cwd) return;
+	// Locator cwd is canonical everywhere. Reconcile only a pre-existing host row
+	// whose canonical registration race observed a different path; it never retains
+	// a caller's lexical spelling for ACP or any other scope consumer.
+	const locator = await resolveSessionLocator(scope, record.locator.stateRoot);
 	await broker.index.append({
 		type: "record_reconciled",
 		sessionId: id,
-		locator: { ...record.locator, repo: scope },
+		locator,
 		endpointGeneration: record.endpointGeneration,
 		pid: record.pid,
 		// Reconciliation only re-scopes the locator, so every identity fact the host
@@ -933,6 +975,8 @@ async function reconcileReadyScope(broker: Broker, id: string, scope: string | u
 		...(record.hostIncarnation === undefined ? {} : { hostIncarnation: record.hostIncarnation }),
 		...(record.lifecycleRequestId === undefined ? {} : { lifecycleRequestId: record.lifecycleRequestId }),
 		endpointMtimeMs: record.endpointMtimeMs,
+		...(record.endpointFileId === undefined ? {} : { endpointFileId: record.endpointFileId }),
+		...(record.masterRole === undefined ? {} : { masterRole: record.masterRole }),
 	});
 }
 
@@ -964,6 +1008,66 @@ function command(broker: Broker): LifecycleCommand {
 	return lifecycleCommandResolversForTest.get(broker)?.() ?? resolveSdkInternalSpawnCommand("session-host-internal");
 }
 
+/**
+ * Reuses the ordinary lifecycle host bootstrap without performing its direct
+ * process spawn. Broker-owned substrate providers receive this exact argv and
+ * split inherited/child-specific environment contract as their only launch
+ * authority for session.spawn.
+ */
+export type SpawnChildHostLaunch = {
+	childId: string;
+	cwd: string;
+	stateRoot: string;
+	argv: readonly string[];
+	inheritedEnv: Readonly<Record<string, string>>;
+	env: Readonly<Record<string, string>>;
+	effectMarker: string;
+};
+
+export function prepareSpawnChildHostLaunch(
+	broker: Broker,
+	input: { cwd: string; modelId?: string; modelPreset?: string; childId?: string; receivedAt?: number },
+): SpawnChildHostLaunch {
+	const cwd = path.resolve(input.cwd);
+	const childId = input.childId ?? randomUUID();
+	const stateRoot = defaultStateRoot(cwd);
+	const effectMarker = randomUUID();
+	const deadlines = deriveLifecycleDeadlines(input.receivedAt ?? Date.now(), DEFAULT_READINESS_TIMEOUT_MS);
+	const request: SessionLifecycleLaunchRequest = {
+		operation: "session.create",
+		sessionId: childId,
+		cwd,
+		stateRoot,
+		effectMarker,
+		...deadlines,
+		...(input.modelId === undefined ? {} : { modelId: input.modelId }),
+		...(input.modelPreset === undefined ? {} : { modelPreset: input.modelPreset }),
+	};
+	const cmd = command(broker);
+	const inherited = "kind" in cmd ? cmd.env : process.env;
+	const inheritedEnv = Object.fromEntries(
+		Object.entries(inherited).filter(
+			(entry): entry is [string, string] => entry[0] !== "GJC_MASTER_CAPABILITY" && typeof entry[1] === "string",
+		),
+	);
+	return {
+		childId,
+		cwd,
+		stateRoot,
+		argv: [cmd.file, ...cmd.args],
+		inheritedEnv,
+		env: {
+			GJC_AGENT_DIR: broker.settings.agentDir,
+			GJC_CODING_AGENT_DIR: broker.settings.agentDir,
+			GJC_SESSION_ID: childId,
+			GJC_STATE_ROOT: stateRoot,
+			GJC_LIFECYCLE_REQUEST_ID: effectMarker,
+			GJC_SDK_LIFECYCLE_REQUEST: JSON.stringify(request),
+		},
+		effectMarker,
+	};
+}
+
 const lifecycleMarkerPath = (root: string, id: string) => path.join(root, "sdk", `${id}.lifecycle.json`);
 const lifecycleReadyPath = (root: string, id: string) => path.join(root, "sdk", `${id}.lifecycle.ready.json`);
 const lifecycleFailurePath = (root: string, id: string, effectMarker: string) =>
@@ -973,6 +1077,7 @@ type ReadyAuthority = {
 	endpoint: Record<string, unknown>;
 	endpointSource: string;
 	endpointMtimeMs: number;
+	endpointFileId?: string;
 	endpointGeneration: number;
 };
 type ReadinessResult =
@@ -3351,7 +3456,7 @@ async function recordTerminalUncertain(
 		await broker.index.append({
 			type: "lifecycle_terminal",
 			sessionId: id,
-			locator: { repo: "unknown", stateRoot: root },
+			locator: { cwd: "unknown", worktreeRoot: null, stateRoot: root },
 			endpointGeneration: 0,
 			pid,
 			terminalUncertain: true,
@@ -3667,7 +3772,10 @@ async function removeExactDeadSessionEndpoint(
 				: finalEndpointPath;
 	let handle: fs.FileHandle | undefined;
 	try {
-		handle = await fs.open(endpointSource, fsSync.constants.O_RDONLY | fsSync.constants.O_NOFOLLOW);
+		handle = await fs.open(
+			endpointSource,
+			fsSync.constants.O_RDONLY | (fsSync.constants.O_NOFOLLOW ?? 0) | (fsSync.constants.O_NONBLOCK ?? 0),
+		);
 		const metadata = await handle.stat({ bigint: true });
 		if (!metadata.isFile() || metadata.nlink !== 1n || metadata.size > 4096n) return false;
 		const bytes = Buffer.alloc(Number(metadata.size) + 1);
@@ -3847,10 +3955,9 @@ async function currentReadyAuthority(
 	if (!(await hasOwnedReadinessEvidence(broker, root, id, expected))) return undefined;
 	const endpointPath = path.join(root, "sdk", `${id}.json`);
 	try {
-		const [endpointSource, endpointMetadata] = await Promise.all([
-			fs.readFile(endpointPath, "utf8"),
-			fs.stat(endpointPath),
-		]);
+		const endpointFile = await readEndpointFile(endpointPath);
+		if (!endpointFile) return undefined;
+		const endpointSource = endpointFile.source;
 		const endpoint = JSON.parse(endpointSource) as {
 			sessionId?: unknown;
 			url?: unknown;
@@ -3863,14 +3970,24 @@ async function currentReadyAuthority(
 		// native-dead child; do not refuse a native-alive ready host for a stale live bit.
 		await broker.heartbeatSessions();
 		await broker.index.refresh();
-		const record = broker.index.listSessions().sessions.find(session => session.sessionId === id);
+		const record = broker.index
+			.listSessions()
+			.sessions.find(
+				session =>
+					session.sessionId === id &&
+					session.pid === expected.pid &&
+					resolveEquivalentPath(session.locator.stateRoot) === resolveEquivalentPath(root) &&
+					(session.hostIncarnation ?? session.processIncarnation) === expected.incarnation &&
+					session.lifecycleRequestId === expected.effectMarker,
+			);
 		if (
 			!record ||
 			record.terminal ||
 			record.terminalUncertain ||
 			record.pid !== expected.pid ||
 			resolveEquivalentPath(record.locator.stateRoot) !== resolveEquivalentPath(root) ||
-			record.endpointMtimeMs !== endpointMetadata.mtimeMs ||
+			(record.hostIncarnation ?? record.processIncarnation) !== expected.incarnation ||
+			!matchesIndexedEndpointFile(endpointFile, record) ||
 			endpoint.pid !== expected.pid ||
 			endpoint.sessionId !== id ||
 			typeof endpoint.url !== "string" ||
@@ -3885,7 +4002,8 @@ async function currentReadyAuthority(
 		return {
 			endpoint: endpoint as Record<string, unknown>,
 			endpointSource,
-			endpointMtimeMs: endpointMetadata.mtimeMs,
+			endpointMtimeMs: endpointFile.mtimeMs,
+			...(record.endpointFileId === undefined ? {} : { endpointFileId: record.endpointFileId }),
 			endpointGeneration: record.endpointGeneration,
 		};
 	} catch {
@@ -3896,7 +4014,8 @@ async function currentReadyAuthority(
 function sameReadyAuthority(left: ReadyAuthority, right: ReadyAuthority): boolean {
 	return (
 		left.endpointSource === right.endpointSource &&
-		left.endpointMtimeMs === right.endpointMtimeMs &&
+		Math.abs(left.endpointMtimeMs - right.endpointMtimeMs) <= 0.001 &&
+		left.endpointFileId === right.endpointFileId &&
 		left.endpointGeneration === right.endpointGeneration
 	);
 }
@@ -4022,6 +4141,15 @@ function worktreeIntent(plan: GjcLaunchWorktreePlan | undefined): LifecycleWorkt
 	};
 }
 
+/** Test seam for the worktree occupancy boundary. */
+export function worktreeOccupantForTest(
+	sessions: IndexedSession[],
+	worktreePath: string,
+	observe: (pid: number, expectedIncarnation: string | undefined) => ProcessObservation = observeProcess,
+): string | null {
+	return worktreeOccupant(sessions, worktreePath, observe);
+}
+
 function preparePlannedWorktree(plan: GjcLaunchWorktreePlan): SessionLifecycleWorktreeReceipt {
 	const prepared = ensureLaunchWorktree(plan);
 	if (!prepared.enabled || path.resolve(prepared.worktreePath) !== path.resolve(plan.worktreePath))
@@ -4453,7 +4581,7 @@ async function validateDeletePath(
 	broker: Broker,
 	input: Input,
 	id: string,
-	record: { locator: { repo: string; stateRoot: string } } | undefined,
+	record: { locator: SessionLocatorV2 } | undefined,
 	cleanup?: CleanupEvidence,
 ): Promise<ValidatedDelete | BrokerResponse> {
 	const sessionPath = text(input.sessionPath);
@@ -4467,7 +4595,7 @@ async function validateDeletePath(
 	const canonicalRequestedRoot = canonicalExistingPath(requestedRoot);
 	if (
 		record &&
-		(canonicalExistingPath(record.locator.repo) !== cwd ||
+		(canonicalExistingPath(record.locator.cwd) !== cwd ||
 			canonicalExistingPath(record.locator.stateRoot) !== canonicalRequestedRoot)
 	)
 		return fail("invalid_input", "session.delete locator does not match the indexed session.");
@@ -4557,7 +4685,7 @@ async function validateDeletePath(
 }
 type CloseAuthority = { endpointGeneration: number; endpointIncarnation: string };
 type CloseRecord = {
-	locator: { repo: string; stateRoot: string };
+	locator: SessionLocatorV2;
 	endpointGeneration: number;
 	pid: number;
 	endpointMtimeMs?: number;
@@ -4621,7 +4749,7 @@ function sameCloseStoredProcessIdentity(expected: CloseRecord, current: CloseRec
 		typeof expected.lifecycleRequestId === "string" &&
 		expected.lifecycleRequestId.length > 0 &&
 		current.lifecycleRequestId === expected.lifecycleRequestId &&
-		path.resolve(current.locator.repo) === path.resolve(expected.locator.repo) &&
+		path.resolve(current.locator.cwd) === path.resolve(expected.locator.cwd) &&
 		path.resolve(current.locator.stateRoot) === path.resolve(expected.locator.stateRoot)
 	);
 }
@@ -4639,7 +4767,7 @@ function sameCloseEndpointIdentity(expected: CloseRecord, current: CloseRecord):
 		current.endpointMtimeMs !== undefined &&
 		expected.endpointMtimeMs !== undefined &&
 		current.lifecycleRequestId === expected.lifecycleRequestId &&
-		path.resolve(current.locator.repo) === path.resolve(expected.locator.repo) &&
+		path.resolve(current.locator.cwd) === path.resolve(expected.locator.cwd) &&
 		path.resolve(current.locator.stateRoot) === path.resolve(expected.locator.stateRoot)
 	);
 }
@@ -4656,7 +4784,7 @@ function sameCloseGeneration(expected: CloseRecord, current: CloseRecord & { liv
 		current.endpointMtimeMs === expected.endpointMtimeMs &&
 		current.lifecycleRequestId === expected.lifecycleRequestId &&
 		current.processIncarnation === expected.processIncarnation &&
-		path.resolve(current.locator.repo) === path.resolve(expected.locator.repo) &&
+		path.resolve(current.locator.cwd) === path.resolve(expected.locator.cwd) &&
 		path.resolve(current.locator.stateRoot) === path.resolve(expected.locator.stateRoot)
 	);
 }
@@ -4720,13 +4848,15 @@ async function executeLifecycleResponse(
 	if (operation === "session.create" || operation === "session.fork" || operation === "session.resume") {
 		await broker.index.refresh();
 		await broker.heartbeatSessions();
+		await broker.index.refresh();
 		if (operation === "session.resume") {
 			const requestedSessionId = sessionId(input);
-			const existing = requestedSessionId
-				? broker.index.listSessions().sessions.find(session => session.sessionId === requestedSessionId)
-				: undefined;
-			if (existing && !isSessionAuthorityEligible(existing))
+			const authority = requestedSessionId
+				? liveResumeAuthority(broker.index.listSessions().sessions, requestedSessionId)
+				: { kind: "none" as const };
+			if (authority.kind === "ambiguous")
 				return fail("endpoint_stale", "Session authority is ambiguous and cannot be resumed safely.");
+			const existing = authority.kind === "live" ? authority.record : undefined;
 			if (existing?.live) {
 				const initialScope = await validateLiveResumeScope(broker, input, requestedSessionId!, existing);
 				if ("ok" in initialScope) return initialScope;
@@ -4743,16 +4873,17 @@ async function executeLifecycleResponse(
 						"live_session",
 						"Session is already live but its incarnation-bound endpoint is unavailable.",
 					);
-				await broker.index.refresh();
-				const current = broker.index
-					.listSessions()
-					.sessions.find(session => session.sessionId === requestedSessionId);
-				if (!current || !sameLiveResumeRecord(existing, current))
-					return fail("endpoint_stale", "Live session changed while its resume authority was being verified.");
-				const finalScope = await validateLiveResumeScope(broker, input, requestedSessionId!, current);
+				const finalScope = await validateLiveResumeScope(broker, input, requestedSessionId!, existing);
 				if ("ok" in finalScope) return finalScope;
 				if (!sameResumeSessionIdentity(initialScope, finalScope))
 					return fail("endpoint_stale", "Saved session changed while its resume authority was being verified.");
+				await broker.index.refresh();
+				const finalAuthority = liveResumeAuthority(broker.index.listSessions().sessions, requestedSessionId!);
+				if (finalAuthority.kind === "ambiguous")
+					return fail("endpoint_stale", "Session authority became ambiguous while it was being verified.");
+				const current = finalAuthority.kind === "live" ? finalAuthority.record : undefined;
+				if (!current || !sameLiveResumeRecord(existing, current))
+					return fail("endpoint_stale", "Live session changed while its resume authority was being verified.");
 				if (current.endpointMtimeMs === undefined)
 					return fail("endpoint_stale", "Live session endpoint authority is incomplete.");
 				return {
@@ -4827,6 +4958,14 @@ async function executeLifecycleResponse(
 				"incarnation_unavailable",
 				"OS process incarnation authority is unavailable; refusing to spawn a lifecycle session.",
 			);
+		if (launch.worktreePlan) {
+			const occupant = worktreeOccupant(broker.index.listSessions().sessions, launch.worktreePlan.worktreePath);
+			if (occupant && occupant !== launch.id)
+				return fail(
+					"worktree_in_use",
+					`The requested worktree is already held by session ${occupant}. Choose another worktree name or stop that session.`,
+				);
+		}
 		const effectMarker = randomUUID();
 		const plannedWorktreeIntent = worktreeIntent(launch.worktreePlan);
 		const effectIntent: LifecycleEffectIntentWithDeadline = {
@@ -4933,7 +5072,13 @@ async function executeLifecycleResponse(
 					// by the OS rather than captured (#4712 review).
 					stdio: "ignore",
 					env: {
-						...("kind" in cmd ? cmd.env : process.env),
+						// Master capability is process-local to direct Bash children and must
+						// never cross a broker lifecycle launch boundary.
+						...Object.fromEntries(
+							Object.entries("kind" in cmd ? cmd.env : process.env).filter(
+								([key]) => key !== "GJC_MASTER_CAPABILITY",
+							),
+						),
 						GJC_AGENT_DIR: broker.settings.agentDir,
 						GJC_CODING_AGENT_DIR: broker.settings.agentDir,
 						GJC_SESSION_ID: launch.id,
@@ -5073,7 +5218,7 @@ async function executeLifecycleResponse(
 									`Session ${launch.id} did not register an endpoint before the readiness timeout.`,
 								);
 		}
-		await reconcileReadyScope(broker, launch.id, launch.cwd);
+		await reconcileReadyScope(broker, launch.id, launch.cwd, launch.root, spawnedAuthority);
 		const verified = await currentReadyAuthority(broker, launch.id, launch.root, spawnedAuthority);
 		if (!verified || !sameReadyAuthority(readiness.authority, verified)) {
 			const exited =