@gajae-code/coding-agent 0.16.0 → 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 {
@@ -91,8 +94,11 @@ import {
 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";
@@ -201,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 {
@@ -220,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;
 
@@ -300,6 +331,7 @@ export interface SessionLifecycleWorktreeReceipt {
 	cwd: string;
 	created: boolean;
 	reused: boolean;
+	createdBranch: boolean;
 	branch?: string;
 }
 
@@ -734,7 +766,7 @@ 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;
 }
@@ -4150,8 +4182,22 @@ export function worktreeOccupantForTest(
 	return worktreeOccupant(sessions, worktreePath, observe);
 }
 
-function preparePlannedWorktree(plan: GjcLaunchWorktreePlan): SessionLifecycleWorktreeReceipt {
-	const prepared = ensureLaunchWorktree(plan);
+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 {
@@ -4159,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",
@@ -4923,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 {
@@ -4944,15 +5056,52 @@ 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",
@@ -4972,7 +5121,8 @@ async function executeLifecycleResponse(
 			sessionId: launch.id,
 			stateRoot: launch.root,
 			childOwnershipEstablished: false,
-			lifecycleCleanupDeadlineAt: deadlines.lifecycleCleanupDeadlineAt,
+			lifecycleCleanupDeadlineAt:
+				outerCleanupDeadlineAt ?? (childDeadlines as LifecycleDeadlines).lifecycleCleanupDeadlineAt,
 			...(plannedWorktreeIntent ? { worktree: plannedWorktreeIntent } : {}),
 		};
 
@@ -4989,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"

package/src/sdk/broker/spawn-substrate.ts

@@ -90,6 +90,30 @@ function launchFailureMessage(selected: "tmux" | "psmux" | "headless", error: un
 	return `${selected} substrate launch failed${bounded ? `: ${bounded}` : ""}`;
 }
 
+function cleanupFailureMessage(selected: "tmux" | "psmux", error: unknown): string {
+	const detail = error instanceof Error ? error.message : String(error);
+	const bounded = detail
+		.replace(/[\u0000-\u001f\u007f]/g, " ")
+		.trim()
+		.slice(0, MAX_SUBSTRATE_DIAGNOSTIC_LENGTH);
+	return `${selected} substrate cleanup failed${bounded ? `: ${bounded}` : ""}`;
+}
+
+function cleanupUncertaintyMessage(selected: "tmux" | "psmux"): string {
+	return `${selected} substrate cleanup could not be verified`;
+}
+
+function cleanupWasVerifiedAfterManagedLaunchFailure(error: unknown): boolean {
+	if (error instanceof AggregateError) return false;
+	const detail = error instanceof Error ? error.message : String(error);
+	// The owner-isolation layer reports a failed tmux allocation before a
+	// managed session exists. That is the only managed launch failure that is
+	// safe to replace with the exact headless substrate. Every other thrown
+	// error may follow a partial create/proof path and therefore needs explicit
+	// cleanup evidence instead of optimistic fallback.
+	return detail.includes("planned_spawn_failed") && !detail.includes("cleanup_uncertain");
+}
+
 function hasOnlyKeys(value: Record<string, unknown>, keys: Set<string>): boolean {
 	return Object.keys(value).every(key => keys.has(key));
 }
@@ -440,6 +464,16 @@ export function createSpawnSubstrateProvider(
 					managed = launchManaged(spec, launchEnv, platform);
 				} catch (error) {
 					const failure = launchFailureMessage(selected, error);
+					if (!cleanupWasVerifiedAfterManagedLaunchFailure(error))
+						return {
+							ok: false,
+							code: "substrate_proof_failed",
+							message: `${failure}; ${
+								error instanceof AggregateError
+									? cleanupFailureMessage(selected, error)
+									: cleanupUncertaintyMessage(selected)
+							}`,
+						};
 					try {
 						const fallback = await launchHeadlessSubstrate(spec, launchEnv);
 						if (fallback.ok) return fallback;
@@ -458,12 +492,21 @@ export function createSpawnSubstrateProvider(
 				}
 				const incarnation = readIncarnation(managed.pid);
 				if (!incarnation || verifyManaged(managed, launchEnv) !== "verified") {
+					let cleanupVerified = false;
+					let cleanupError: unknown;
 					try {
 						await closeManaged(managed, launchEnv);
-					} catch {
-						// The managed close primitive is already exact-proof fenced. Retain its result only in authority state.
+						cleanupVerified = true;
+					} catch (error) {
+						cleanupError = error;
 					}
 					const failure = launchFailureMessage(selected, new Error("exact substrate proof failed"));
+					if (!cleanupVerified)
+						return {
+							ok: false,
+							code: "substrate_proof_failed",
+							message: `${failure}; ${cleanupFailureMessage(selected, cleanupError)}`,
+						};
 					const fallback = await launchHeadlessSubstrate(spec, launchEnv);
 					if (fallback.ok) return fallback;
 					return {

package/src/sdk/broker/startup-budget.ts

@@ -3,6 +3,14 @@ export const DEFAULT_READINESS_TIMEOUT_MS = 10_000;
 export const MIN_READINESS_TIMEOUT_MS = 4_000;
 export const MAX_READINESS_TIMEOUT_MS = 60_000;
 
+/** Bounded git worktree add/reuse window; independent of child semantic readiness. */
+export const DEFAULT_WORKTREE_PREPARATION_TIMEOUT_MS = 30_000;
+export const MIN_PREPARATION_TIMEOUT_MS = 1_000;
+export const MAX_PREPARATION_TIMEOUT_MS = 120_000;
+
+/** Bounded workspace install window; independent of child semantic readiness. */
+export const DEFAULT_DEPENDENCY_PREPARATION_TIMEOUT_MS = 30_000;
+
 export function isValidReadinessTimeoutMs(value: unknown): value is number {
 	return (
 		typeof value === "number" &&
@@ -12,7 +20,17 @@ export function isValidReadinessTimeoutMs(value: unknown): value is number {
 	);
 }
 
+export function isValidPreparationTimeoutMs(value: unknown): value is number {
+	return (
+		typeof value === "number" &&
+		Number.isSafeInteger(value) &&
+		value >= MIN_PREPARATION_TIMEOUT_MS &&
+		value <= MAX_PREPARATION_TIMEOUT_MS
+	);
+}
+
 export const READINESS_TIMEOUT_INVALID_MESSAGE = `readinessTimeoutMs must be an integer between ${MIN_READINESS_TIMEOUT_MS} and ${MAX_READINESS_TIMEOUT_MS}.`;
+export const PREPARATION_TIMEOUT_INVALID_MESSAGE = `worktreePreparationTimeoutMs and dependencyPreparationTimeoutMs must be integers between ${MIN_PREPARATION_TIMEOUT_MS} and ${MAX_PREPARATION_TIMEOUT_MS}.`;
 /**
  * Sleep until the duration elapses or the caller cancels the wait. Queue admission
  * uses this so a granted or refused waiter does not retain its cutoff timer for the
@@ -77,6 +95,10 @@ export function lifecycleStartupBudgetMs(requestedReadinessTimeoutMs: number): n
  * rather than left unextended: the broker queues it for exactly as long as one that
  * asked, so the common path would otherwise fail client-side while the broker runs
  * the startup to a durably persisted terminal result.
+ *
+ * Worktree launches add independent preparation budgets so git add / install cannot
+ * cut the caller while the broker still owns the request. One-arg
+ * {@link lifecycleStartupBudgetMs} stays queue+readiness for no-worktree callers.
  */
 export function lifecycleRequestTimeoutMs(operation: string, input: Record<string, unknown>): number | undefined {
 	const deadlineFields = [
@@ -97,7 +119,127 @@ export function lifecycleRequestTimeoutMs(operation: string, input: Record<strin
 		if (requested !== undefined && !isValidReadinessTimeoutMs(requested)) return undefined;
 		supplied = requested as number | undefined;
 	}
-	if (isStartupLifecycleOperation(operation))
-		return lifecycleStartupBudgetMs(supplied ?? DEFAULT_READINESS_TIMEOUT_MS) + CALLER_DEADLINE_SLACK_MS;
+	if (isStartupLifecycleOperation(operation)) {
+		const readiness = supplied ?? DEFAULT_READINESS_TIMEOUT_MS;
+		const preparation = preparationBudgetMs(input);
+		if (preparation === undefined) return undefined;
+		return lifecycleStartupBudgetMs(readiness) + preparation + CALLER_DEADLINE_SLACK_MS;
+	}
 	return supplied === undefined ? undefined : supplied + CALLER_DEADLINE_SLACK_MS;
 }
+
+function recordEnabled(value: unknown): boolean {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		!Array.isArray(value) &&
+		(value as Record<string, unknown>).enabled === true
+	);
+}
+
+function worktreeNamePresent(value: unknown): boolean {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const name = (value as Record<string, unknown>).name;
+	return typeof name === "string" && name.length > 0;
+}
+
+/**
+ * True when this request will run named or detached worktree preparation.
+ * Coordinator nests the selector at `target.worktree`; Direct/lifecycle service
+ * put `worktree` on the mutation target itself; broker serialization also
+ * accepts `{ worktree: { name } }` without `enabled`.
+ */
+export function lifecycleRequestHasWorktree(input: Record<string, unknown>): boolean {
+	const nested = input.target;
+	if (typeof nested === "object" && nested !== null && !Array.isArray(nested)) {
+		const nestedWorktree = (nested as Record<string, unknown>).worktree;
+		if (recordEnabled(nestedWorktree) || worktreeNamePresent(nestedWorktree)) return true;
+	}
+	const worktree = input.worktree;
+	if (worktree === true) return true;
+	return recordEnabled(worktree) || worktreeNamePresent(worktree);
+}
+
+function readPreparationTimeout(
+	input: Record<string, unknown>,
+	key: "worktreePreparationTimeoutMs" | "dependencyPreparationTimeoutMs",
+): number | undefined | "invalid" {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	return isValidPreparationTimeoutMs(value) ? value : "invalid";
+}
+
+/**
+ * Sum of worktree and dependency preparation budgets, or 0 when the request
+ * has no worktree. Returns `undefined` when an explicit prep field is present
+ * but invalid so callers fail closed instead of silently dropping prep time.
+ */
+export function preparationBudgetMs(input: Record<string, unknown>): number | undefined {
+	const worktreeTimeout = readPreparationTimeout(input, "worktreePreparationTimeoutMs");
+	const dependencyTimeout = readPreparationTimeout(input, "dependencyPreparationTimeoutMs");
+	if (worktreeTimeout === "invalid" || dependencyTimeout === "invalid") return undefined;
+	if (!lifecycleRequestHasWorktree(input)) return 0;
+	return (
+		(worktreeTimeout ?? DEFAULT_WORKTREE_PREPARATION_TIMEOUT_MS) +
+		(dependencyTimeout ?? DEFAULT_DEPENDENCY_PREPARATION_TIMEOUT_MS)
+	);
+}
+
+export interface LifecycleOuterDeadlines {
+	admittedAt: number;
+	worktreePrepTimeoutMs: number;
+	dependencyPrepTimeoutMs: number;
+	requestedReadinessTimeoutMs: number;
+	worktreePreparationDeadlineAt: number;
+	lifecycleCleanupDeadlineAt: number;
+}
+
+/**
+ * Whole-request outer deadlines for a worktree launch. Child semantic readiness
+ * is still derived later at prepSucceededAt. Dependency start is sequential:
+ * callers clip remaining dep budget against `lifecycleCleanupDeadlineAt`
+ * after worktreeDoneAt.
+ */
+export function deriveLifecycleOuterDeadlines(input: {
+	admittedAt: number;
+	worktreePrepTimeoutMs: number;
+	dependencyPrepTimeoutMs: number;
+	requestedReadinessTimeoutMs: number;
+}): LifecycleOuterDeadlines {
+	const { admittedAt, worktreePrepTimeoutMs, dependencyPrepTimeoutMs, requestedReadinessTimeoutMs } = input;
+	if (
+		!Number.isSafeInteger(admittedAt) ||
+		!isValidPreparationTimeoutMs(worktreePrepTimeoutMs) ||
+		!isValidPreparationTimeoutMs(dependencyPrepTimeoutMs) ||
+		!isValidReadinessTimeoutMs(requestedReadinessTimeoutMs)
+	) {
+		throw new Error("Lifecycle outer timing values must be safe integers in the approved ranges.");
+	}
+	const worktreePreparationDeadlineAt = admittedAt + worktreePrepTimeoutMs;
+	const lifecycleCleanupDeadlineAt =
+		admittedAt + worktreePrepTimeoutMs + dependencyPrepTimeoutMs + requestedReadinessTimeoutMs;
+	if (!Number.isSafeInteger(worktreePreparationDeadlineAt) || !Number.isSafeInteger(lifecycleCleanupDeadlineAt)) {
+		throw new Error("Lifecycle outer timing values overflow the safe integer range.");
+	}
+	return {
+		admittedAt,
+		worktreePrepTimeoutMs,
+		dependencyPrepTimeoutMs,
+		requestedReadinessTimeoutMs,
+		worktreePreparationDeadlineAt,
+		lifecycleCleanupDeadlineAt,
+	};
+}
+
+export function readPreparationTimeouts(
+	input: Record<string, unknown>,
+): { ok: true; worktreePrepTimeoutMs: number; dependencyPrepTimeoutMs: number } | { ok: false } {
+	const worktreeTimeout = readPreparationTimeout(input, "worktreePreparationTimeoutMs");
+	const dependencyTimeout = readPreparationTimeout(input, "dependencyPreparationTimeoutMs");
+	if (worktreeTimeout === "invalid" || dependencyTimeout === "invalid") return { ok: false };
+	return {
+		ok: true,
+		worktreePrepTimeoutMs: worktreeTimeout ?? DEFAULT_WORKTREE_PREPARATION_TIMEOUT_MS,
+		dependencyPrepTimeoutMs: dependencyTimeout ?? DEFAULT_DEPENDENCY_PREPARATION_TIMEOUT_MS,
+	};
+}

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

@@ -8,6 +8,16 @@ export const SDK_STATE_VERSION = 1;
 export const SESSION_INDEX_SNAPSHOT_VERSION = 4;
 export const SESSION_INDEX_EVENT_VERSION = SESSION_INDEX_SNAPSHOT_VERSION;
 
+/**
+ * Thrown when a persisted SDK state file carries a version this build does not
+ * support. `assertSupportedStateVersion` fences only generic SDK state (broker
+ * discovery, lifecycle-ledger rows, guide cache meta) whose current format is
+ * exactly `SDK_STATE_VERSION`. Session-index files carry their own versions
+ * (see `assertSupportedSessionIndexEventVersion` and
+ * `assertSupportedSnapshotVersion`) and MUST NOT be validated with the generic
+ * guard — a supported v4 index row would crash with "maximum supported version
+ * is 1" (#5181).
+ */
 export class UnsupportedStateVersionError extends Error {
 	readonly code = "unsupported_state_version";
 
@@ -23,6 +33,13 @@ export class UnsupportedStateVersionError extends Error {
 	}
 }
 
+/**
+ * Generic SDK-state fence: rejects any version above `SDK_STATE_VERSION`.
+ * ONLY for generic state whose current format is exactly `SDK_STATE_VERSION`
+ * (broker discovery `broker.json`, lifecycle-ledger rows, guide cache meta).
+ * Never validate session-index rows or snapshots with this guard — they have
+ * dedicated version fences and currently accept v4 (#5181).
+ */
 export function assertSupportedStateVersion(file: string, value: unknown): void {
 	if (!value || typeof value !== "object") return;
 	const record = value as { version?: unknown; stateVersion?: unknown };

package/src/sdk/bus/chat-daemon-control.ts

@@ -135,8 +135,8 @@ export type ChatDaemonAction = "stop" | "reload";
  * pre-upgrade owner cannot retain the queue race fixed by #5120.
  */
 export const CHAT_DAEMON_GENERATIONS: Readonly<Record<ChatDaemonKind, number>> = {
-	discord: 72,
-	slack: 75,
+	discord: 73,
+	slack: 77,
 };
 
 export function chatDaemonGeneration(kind: ChatDaemonKind): number {