@gajae-code/coding-agent 0.15.6 → 0.16.1

package/src/sdk/broker/lifecycle.ts

@@ -26,10 +26,13 @@ import {
 import { mergeModelProfiles } from "../../config/model-profiles";
 import { ModelsConfigFile } from "../../config/model-registry";
 import {
-	ensureLaunchWorktree,
-	ensureReusableNodeModules,
+	DependencyPreparationTimeoutError,
+	ensureLaunchWorktreeCancellable,
+	ensureReusableNodeModulesCancellable,
 	type GjcLaunchWorktreePlan,
 	planLaunchWorktree,
+	removeOwnedLaunchWorktree,
+	WorktreePreparationTimeoutError,
 } from "../../gjc-runtime/launch-worktree";
 import { probeLinuxProcPidSync } from "../../gjc-runtime/linux-proc";
 import {
@@ -66,6 +69,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,14 +85,23 @@ 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,
+	deriveLifecycleOuterDeadlines,
 	isValidReadinessTimeoutMs,
+	PREPARATION_TIMEOUT_INVALID_MESSAGE,
 	READINESS_TIMEOUT_INVALID_MESSAGE,
+	readPreparationTimeouts,
 	startupQueueWaitMs,
 } from "./startup-budget";
+import { worktreeOccupant } from "./worktree-occupancy";
 
 export {
 	type ProcessIncarnationCommandRunner,
@@ -194,6 +207,17 @@ const lifecycleCommandResolversForTest = new WeakMap<Broker, LifecycleCommandRes
 const lifecycleCleanupHooksForTest = new WeakMap<Broker, () => void>();
 const startupAdmittedInputs = new WeakSet<Input>();
 const startupLaunchInputs = new WeakMap<Input, SessionLaunch>();
+type EnsureLaunchWorktreeForTest = (
+	plan: GjcLaunchWorktreePlan,
+	opts: { signal: AbortSignal; deadlineAt: number },
+) => Promise<SessionLifecycleWorktreeReceipt & { createdBranch: boolean }>;
+type EnsureReusableNodeModulesForTest = (
+	sourceRoot: string,
+	worktreePath: string,
+	opts: { signal: AbortSignal; deadlineAt: number },
+) => Promise<"symlink" | "present" | "missing">;
+let ensureLaunchWorktreeForTest: EnsureLaunchWorktreeForTest | undefined;
+let ensureReusableNodeModulesForTest: EnsureReusableNodeModulesForTest | undefined;
 
 /** Test-only hook for simulating a crash immediately after one exact lifecycle detach. */
 export function setLifecycleCleanupHookForTest(broker: Broker, hook: (() => void) | undefined): void {
@@ -213,6 +237,20 @@ export function setLifecycleTimingForTest(broker: Broker, timing: LifecycleTimin
 	if (timing) lifecycleTimingsForTest.set(broker, timing);
 	else lifecycleTimingsForTest.delete(broker);
 }
+export function setEnsureLaunchWorktreeForTest(
+	_broker: Broker | undefined,
+	fn?: EnsureLaunchWorktreeForTest | undefined,
+): void {
+	ensureLaunchWorktreeForTest = typeof _broker === "function" ? (_broker as EnsureLaunchWorktreeForTest) : fn;
+}
+
+export function setEnsureReusableNodeModulesForTest(
+	_broker: Broker | undefined,
+	fn?: EnsureReusableNodeModulesForTest | undefined,
+): void {
+	ensureReusableNodeModulesForTest =
+		typeof _broker === "function" ? (_broker as EnsureReusableNodeModulesForTest) : fn;
+}
 
 let lifecycleHostPlatformForTest: NodeJS.Platform | undefined;
 
@@ -293,6 +331,7 @@ export interface SessionLifecycleWorktreeReceipt {
 	cwd: string;
 	created: boolean;
 	reused: boolean;
+	createdBranch: boolean;
 	branch?: string;
 }
 
@@ -612,7 +651,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();
@@ -727,16 +766,19 @@ function isLifecycleWorktreeTarget(value: unknown): value is SessionLifecycleWor
 
 function lifecycleWorktreeTarget(input: Input): SessionLifecycleWorktreeTarget | null | undefined {
 	const target = input.target as Record<string, unknown> | undefined;
-	const worktree = target?.worktree;
+	const worktree = target?.worktree ?? input.worktree;
 	if (worktree === undefined) return undefined;
 	return isLifecycleWorktreeTarget(worktree) ? worktree : null;
 }
 
 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 +797,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 +819,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 +968,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 +1007,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 +1040,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 +1109,7 @@ type ReadyAuthority = {
 	endpoint: Record<string, unknown>;
 	endpointSource: string;
 	endpointMtimeMs: number;
+	endpointFileId?: string;
 	endpointGeneration: number;
 };
 type ReadinessResult =
@@ -3351,7 +3488,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 +3804,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 +3987,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 +4002,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 +4034,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 +4046,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,8 +4173,31 @@ function worktreeIntent(plan: GjcLaunchWorktreePlan | undefined): LifecycleWorkt
 	};
 }
 
-function preparePlannedWorktree(plan: GjcLaunchWorktreePlan): SessionLifecycleWorktreeReceipt {
-	const prepared = ensureLaunchWorktree(plan);
+/** 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);
+}
+
+async function preparePlannedWorktree(
+	plan: GjcLaunchWorktreePlan,
+	opts: { signal: AbortSignal; deadlineAt: number; now: () => number },
+): Promise<SessionLifecycleWorktreeReceipt> {
+	const hooked = ensureLaunchWorktreeForTest;
+	if (hooked) {
+		const receipt = await hooked(plan, { signal: opts.signal, deadlineAt: opts.deadlineAt });
+		if (!receipt.enabled || path.resolve(receipt.cwd) !== path.resolve(plan.worktreePath))
+			throw new Error("Lifecycle worktree preparation did not preserve the durable worktree identity.");
+		return receipt;
+	}
+	const prepared = await ensureLaunchWorktreeCancellable(plan, {
+		signal: opts.signal,
+		deadlineAt: opts.deadlineAt,
+		now: opts.now,
+	});
 	if (!prepared.enabled || path.resolve(prepared.worktreePath) !== path.resolve(plan.worktreePath))
 		throw new Error("Lifecycle worktree preparation did not preserve the durable worktree identity.");
 	return {
@@ -4031,9 +4205,67 @@ function preparePlannedWorktree(plan: GjcLaunchWorktreePlan): SessionLifecycleWo
 		cwd: path.resolve(prepared.worktreePath),
 		created: prepared.created,
 		reused: prepared.reused,
+		createdBranch: prepared.createdBranch,
 		...(prepared.branchName ? { branch: prepared.branchName } : {}),
 	};
 }
+
+function mapPreparationFailure(error: unknown): BrokerResponse {
+	const message = sanitizeSdkStartupMessage(error);
+	if (
+		error instanceof WorktreePreparationTimeoutError ||
+		(error as { code?: string }).code === "worktree_preparation_timeout"
+	) {
+		return fail("worktree_preparation_timeout", message);
+	}
+	if (
+		error instanceof DependencyPreparationTimeoutError ||
+		(error as { code?: string }).code === "dependency_preparation_timeout"
+	) {
+		return fail("dependency_preparation_timeout", message);
+	}
+	return fail("spawn_failed", `Unable to prepare lifecycle worktree: ${message}`);
+}
+
+function abortWhenDue(
+	controller: AbortController,
+	deadlineAt: number,
+	now: () => number,
+): ReturnType<typeof setInterval> {
+	const tick = (): void => {
+		if (now() >= deadlineAt && !controller.signal.aborted) controller.abort();
+	};
+	tick();
+	return setInterval(tick, 10);
+}
+
+function durableWorktreeEffects(
+	receipt: SessionLifecycleWorktreeReceipt,
+	timings: { worktreePreparationMs?: number; dependencyPreparationMs?: number; spawnAuthorizedAtOffsetMs?: number },
+): LifecycleDurableEffectsReceipt {
+	const worktree = {
+		cwdDigest: createHash("sha256").update(receipt.cwd, "utf8").digest("hex"),
+		created: receipt.created,
+		reused: receipt.reused,
+		createdBranch: receipt.createdBranch,
+		...(receipt.branch ? { branchDigest: createHash("sha256").update(receipt.branch, "utf8").digest("hex") } : {}),
+	};
+	return {
+		worktree,
+		timings,
+		digest: createHash("sha256").update(canonicalJson({ worktree, timings })).digest("hex"),
+	};
+}
+
+function deadlineFieldsPresent(input: Input): boolean {
+	return [
+		input.receivedAt,
+		input.requestedReadinessTimeoutMs,
+		input.semanticReadyDeadlineAt,
+		input.terminationStartDeadlineAt,
+		input.lifecycleCleanupDeadlineAt,
+	].some(value => value !== undefined);
+}
 async function launchInput(
 	broker: Broker,
 	operation: "session.create" | "session.fork" | "session.resume",
@@ -4453,7 +4685,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 +4699,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 +4789,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 +4853,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 +4871,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 +4888,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 +4952,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 +4977,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 {
@@ -4792,8 +5027,16 @@ async function executeLifecycleResponse(
 			const queueWaitMs = startupQueueWaitMs(requestedReadinessTimeoutMs);
 			const launch = await launchInput(broker, operation, input);
 			if ("ok" in launch) return launch;
+			if (launch.worktreePlan && deadlineFieldsPresent(input)) {
+				return fail(
+					"invalid_input",
+					"Lifecycle worktree launches cannot carry a caller-supplied child deadline tuple.",
+				);
+			}
 			const admitted = await broker.runStartup(queueWaitMs, timing, async admittedAt => {
-				const admittedInput = { ...input, ...deriveLifecycleDeadlines(admittedAt, requestedReadinessTimeoutMs) };
+				const admittedInput = launch.worktreePlan
+					? { ...input, admittedAt, requestedReadinessTimeoutMs }
+					: { ...input, ...deriveLifecycleDeadlines(admittedAt, requestedReadinessTimeoutMs) };
 				startupAdmittedInputs.add(admittedInput);
 				startupLaunchInputs.set(admittedInput, launch);
 				try {
@@ -4813,27 +5056,73 @@ async function executeLifecycleResponse(
 			return fail("startup_admission_timeout", failure.message);
 		}
 
-		const deadlines = lifecycleDeadlines(input, input.receivedAt as number);
-
-		if ("ok" in deadlines) return deadlines;
-		const lifecycleDeadline = deadlines.lifecycleCleanupDeadlineAt;
-		const readinessDeadline = deadlines.semanticReadyDeadlineAt;
-		const terminationStartDeadline = deadlines.terminationStartDeadlineAt;
-
 		const launch = startupLaunchInputs.get(input) ?? (await launchInput(broker, operation, input));
 		if ("ok" in launch) return launch;
+		if (launch.worktreePlan && deadlineFieldsPresent(input) && input.admittedAt === undefined) {
+			return fail(
+				"invalid_input",
+				"Lifecycle worktree launches cannot carry a caller-supplied child deadline tuple.",
+			);
+		}
+
+		let childDeadlines: LifecycleDeadlines | undefined;
+		let lifecycleDeadline: number;
+		let readinessDeadline: number;
+		let terminationStartDeadline: number;
+		let outerCleanupDeadlineAt: number | undefined;
+		if (launch.worktreePlan) {
+			const prepTimeouts = readPreparationTimeouts(input);
+			if (!prepTimeouts.ok) return fail("invalid_input", PREPARATION_TIMEOUT_INVALID_MESSAGE);
+			const admittedAt =
+				typeof input.admittedAt === "number" && Number.isSafeInteger(input.admittedAt)
+					? input.admittedAt
+					: timing.now();
+			const requestedReadinessTimeoutMs =
+				typeof input.requestedReadinessTimeoutMs === "number" &&
+				isValidReadinessTimeoutMs(input.requestedReadinessTimeoutMs)
+					? input.requestedReadinessTimeoutMs
+					: readinessTimeout(input);
+			if (typeof requestedReadinessTimeoutMs !== "number") return requestedReadinessTimeoutMs;
+			const outer = deriveLifecycleOuterDeadlines({
+				admittedAt,
+				worktreePrepTimeoutMs: prepTimeouts.worktreePrepTimeoutMs,
+				dependencyPrepTimeoutMs: prepTimeouts.dependencyPrepTimeoutMs,
+				requestedReadinessTimeoutMs,
+			});
+			outerCleanupDeadlineAt = outer.lifecycleCleanupDeadlineAt;
+			lifecycleDeadline = outer.lifecycleCleanupDeadlineAt;
+			readinessDeadline = outer.lifecycleCleanupDeadlineAt;
+			terminationStartDeadline = outer.lifecycleCleanupDeadlineAt;
+		} else {
+			const deadlines = lifecycleDeadlines(input, input.receivedAt as number);
+			if ("ok" in deadlines) return deadlines;
+			childDeadlines = deadlines;
+			lifecycleDeadline = deadlines.lifecycleCleanupDeadlineAt;
+			readinessDeadline = deadlines.semanticReadyDeadlineAt;
+			terminationStartDeadline = deadlines.terminationStartDeadlineAt;
+		}
+
 		if (!hasProcessIncarnationAuthority())
 			return fail(
 				"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 = {
 			sessionId: launch.id,
 			stateRoot: launch.root,
 			childOwnershipEstablished: false,
-			lifecycleCleanupDeadlineAt: deadlines.lifecycleCleanupDeadlineAt,
+			lifecycleCleanupDeadlineAt:
+				outerCleanupDeadlineAt ?? (childDeadlines as LifecycleDeadlines).lifecycleCleanupDeadlineAt,
 			...(plannedWorktreeIntent ? { worktree: plannedWorktreeIntent } : {}),
 		};
 
@@ -4850,39 +5139,109 @@ async function executeLifecycleResponse(
 		let worktreeReceipt: SessionLifecycleWorktreeReceipt | undefined;
 		try {
 			if (launch.worktreePlan) {
-				worktreeReceipt = preparePlannedWorktree(launch.worktreePlan);
-				const worktree = {
-					cwdDigest: createHash("sha256").update(worktreeReceipt.cwd, "utf8").digest("hex"),
-					created: worktreeReceipt.created,
-					reused: worktreeReceipt.reused,
-					...(worktreeReceipt.branch
-						? { branchDigest: createHash("sha256").update(worktreeReceipt.branch, "utf8").digest("hex") }
-						: {}),
-				};
-				const durableEffects: LifecycleDurableEffectsReceipt = {
-					worktree,
-					digest: createHash("sha256").update(canonicalJson({ worktree })).digest("hex"),
-				};
-				await broker.ledger.transition(identity, "effect_started", { durableEffects });
-				ensureReusableNodeModules(launch.worktreePlan.repoRoot, launch.worktreePlan.worktreePath);
+				const prepTimeouts = readPreparationTimeouts(input);
+				if (!prepTimeouts.ok) return fail("invalid_input", PREPARATION_TIMEOUT_INVALID_MESSAGE);
+				const admittedAt =
+					typeof input.admittedAt === "number" && Number.isSafeInteger(input.admittedAt)
+						? input.admittedAt
+						: timing.now();
+				const requestedReadinessTimeoutMs =
+					typeof input.requestedReadinessTimeoutMs === "number" &&
+					isValidReadinessTimeoutMs(input.requestedReadinessTimeoutMs)
+						? input.requestedReadinessTimeoutMs
+						: readinessTimeout(input);
+				if (typeof requestedReadinessTimeoutMs !== "number") return requestedReadinessTimeoutMs;
+				const outer = deriveLifecycleOuterDeadlines({
+					admittedAt,
+					worktreePrepTimeoutMs: prepTimeouts.worktreePrepTimeoutMs,
+					dependencyPrepTimeoutMs: prepTimeouts.dependencyPrepTimeoutMs,
+					requestedReadinessTimeoutMs,
+				});
+				const controller = new AbortController();
+				const worktreeStartedAt = timing.now();
+				const worktreeWatch = abortWhenDue(controller, outer.worktreePreparationDeadlineAt, () => timing.now());
+				try {
+					worktreeReceipt = await preparePlannedWorktree(launch.worktreePlan, {
+						signal: controller.signal,
+						deadlineAt: outer.worktreePreparationDeadlineAt,
+						now: () => timing.now(),
+					});
+				} finally {
+					clearInterval(worktreeWatch);
+				}
+				const worktreeDoneAt = timing.now();
+				const worktreePreparationMs = Math.max(0, worktreeDoneAt - worktreeStartedAt);
+				await broker.ledger.transition(identity, "effect_started", {
+					durableEffects: durableWorktreeEffects(worktreeReceipt, { worktreePreparationMs }),
+				});
+				const remainingDepBudget = Math.min(
+					prepTimeouts.dependencyPrepTimeoutMs,
+					Math.max(0, outer.lifecycleCleanupDeadlineAt - worktreeDoneAt - requestedReadinessTimeoutMs),
+				);
+				const dependencyDeadlineAt = worktreeDoneAt + remainingDepBudget;
+				if (timing.now() >= dependencyDeadlineAt) throw new DependencyPreparationTimeoutError();
+				const depWatch = abortWhenDue(controller, dependencyDeadlineAt, () => timing.now());
+				const depHook = ensureReusableNodeModulesForTest;
+				const dependencyStartedAt = timing.now();
+				try {
+					if (depHook) {
+						await depHook(launch.worktreePlan.repoRoot, launch.worktreePlan.worktreePath, {
+							signal: controller.signal,
+							deadlineAt: dependencyDeadlineAt,
+						});
+					} else {
+						await ensureReusableNodeModulesCancellable(
+							launch.worktreePlan.repoRoot,
+							launch.worktreePlan.worktreePath,
+							{
+								signal: controller.signal,
+								deadlineAt: dependencyDeadlineAt,
+								now: () => timing.now(),
+							},
+						);
+					}
+				} finally {
+					clearInterval(depWatch);
+				}
+				const dependencyPreparationMs = Math.max(0, timing.now() - dependencyStartedAt);
+				await broker.ledger.transition(identity, "effect_started", {
+					durableEffects: durableWorktreeEffects(worktreeReceipt, {
+						worktreePreparationMs,
+						dependencyPreparationMs,
+						spawnAuthorizedAtOffsetMs: Math.max(0, timing.now() - admittedAt),
+					}),
+				});
+				const prepSucceededAt = timing.now();
+				childDeadlines = deriveLifecycleDeadlines(prepSucceededAt, requestedReadinessTimeoutMs);
+				readinessDeadline = childDeadlines.semanticReadyDeadlineAt;
+				terminationStartDeadline = childDeadlines.terminationStartDeadlineAt;
+				lifecycleDeadline = childDeadlines.lifecycleCleanupDeadlineAt;
 			}
 			await reapDeadLifecycleMarkers(launch.root);
 		} catch (error) {
-			return fail(
-				"spawn_failed",
-				`Unable to prepare lifecycle worktree: ${error instanceof Error ? error.message : String(error)}`,
-			);
+			if (launch.worktreePlan && worktreeReceipt?.created && !worktreeReceipt.reused) {
+				removeOwnedLaunchWorktree(launch.worktreePlan, worktreeReceipt);
+			}
+			return mapPreparationFailure(error);
 		}
-		if (timing.now() >= readinessDeadline)
+		if (!launch.worktreePlan && timing.now() >= readinessDeadline)
 			return fail(
 				"readiness_timeout",
 				"Lifecycle preparation exhausted the semantic readiness deadline before spawning.",
 			);
+		if (launch.worktreePlan && !childDeadlines)
+			return fail(
+				worktreeReceipt ? "dependency_preparation_timeout" : "worktree_preparation_timeout",
+				worktreeReceipt
+					? "Dependency preparation exceeded its deadline before the session host was spawned."
+					: "Worktree preparation exceeded its deadline before the session host was spawned.",
+			);
 		if (!hasProcessIncarnationAuthority())
 			return fail(
 				"incarnation_unavailable",
 				"OS process incarnation authority is unavailable; refusing to spawn a lifecycle session.",
 			);
+		const deadlines = childDeadlines as LifecycleDeadlines;
 
 		const coordinatorSidecarTarget =
 			typeof launch.coordinatorStateDir === "string" && typeof launch.coordinatorSidecarKeyId === "string"
@@ -4933,7 +5292,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 +5438,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 =