@gajae-code/coding-agent 0.18.11 → 0.19.0

package/src/commands/harness.ts

@@ -47,7 +47,11 @@ import {
 } from "../harness-control-plane/lifecycle-reconciliation";
 import { type ResolvedOwner, RuntimeOwner, resolveOwner, resolveOwnerLive } from "../harness-control-plane/owner";
 import { preserveDirtyWorktree } from "../harness-control-plane/preserve";
-import { RECEIPT_SPOOL_DIR_ENV } from "../harness-control-plane/receipt-spool";
+import {
+	RECEIPT_SPOOL_DIR_ENV,
+	resolveReceiptSpoolDir,
+	trustedReceiptSpoolDir,
+} from "../harness-control-plane/receipt-spool";
 import { buildReceipt, requiresVanishBeforeAction, type VanishEvidence } from "../harness-control-plane/receipts";
 import { createSdkSessionTransport, spawnNormalHarnessSession } from "../harness-control-plane/sdk-transport";
 import { classifyLeaseStatus, readLease } from "../harness-control-plane/session-lease";
@@ -1004,8 +1008,9 @@ export default class Harness extends Command {
 			`${GJC_TMUX_OWNER_STATE_DIR_ENV}=${shellQuote(ownerStateDir)}`,
 			`${GJC_TMUX_OWNER_SERVER_KEY_ENV}=${shellQuote(socketKey)}`,
 		];
-		if (process.env[RECEIPT_SPOOL_DIR_ENV])
-			envAssignments.push(`${RECEIPT_SPOOL_DIR_ENV}=${shellQuote(process.env[RECEIPT_SPOOL_DIR_ENV])}`);
+		const trustedSpoolDir = resolveReceiptSpoolDir();
+		if (trustedSpoolDir) envAssignments.push(`${RECEIPT_SPOOL_DIR_ENV}=${shellQuote(trustedSpoolDir)}`);
+		else envAssignments.unshift(`-u ${RECEIPT_SPOOL_DIR_ENV}`);
 		if (process.env.GJC_HARNESS_TEST_NODE_MODULES)
 			envAssignments.push(`GJC_HARNESS_TEST_NODE_MODULES=${shellQuote(process.env.GJC_HARNESS_TEST_NODE_MODULES)}`);
 		if (process.env.GJC_SDK_DISABLE)
@@ -1203,19 +1208,20 @@ export default class Harness extends Command {
 		}
 		const fallbackReason = tmux.reason;
 		const cmd = this.#buildOwnerCommand(sessionId);
+		const trustedSpoolDir = resolveReceiptSpoolDir();
+		const childEnv: NodeJS.ProcessEnv = {
+			...process.env,
+			GJC_HARNESS_STATE_ROOT: root,
+			...(process.env.GJC_HARNESS_TEST_NODE_MODULES
+				? { GJC_HARNESS_TEST_NODE_MODULES: process.env.GJC_HARNESS_TEST_NODE_MODULES }
+				: {}),
+			...(process.env.GJC_SDK_DISABLE ? { GJC_SDK_DISABLE: process.env.GJC_SDK_DISABLE } : {}),
+		};
+		if (trustedSpoolDir) childEnv[RECEIPT_SPOOL_DIR_ENV] = trustedSpoolDir;
+		else delete childEnv[RECEIPT_SPOOL_DIR_ENV];
 		const child = Bun.spawn(cmd, {
 			cwd,
-			env: {
-				...process.env,
-				GJC_HARNESS_STATE_ROOT: root,
-				...(process.env[RECEIPT_SPOOL_DIR_ENV]
-					? { [RECEIPT_SPOOL_DIR_ENV]: process.env[RECEIPT_SPOOL_DIR_ENV] }
-					: {}),
-				...(process.env.GJC_HARNESS_TEST_NODE_MODULES
-					? { GJC_HARNESS_TEST_NODE_MODULES: process.env.GJC_HARNESS_TEST_NODE_MODULES }
-					: {}),
-				...(process.env.GJC_SDK_DISABLE ? { GJC_SDK_DISABLE: process.env.GJC_SDK_DISABLE } : {}),
-			},
+			env: childEnv,
 			stdout: "ignore",
 			stderr: "ignore",
 			stdin: "ignore",
@@ -1374,7 +1380,11 @@ export default class Harness extends Command {
 		if (!owner.live || !owner.socketPath) return false;
 		const priorSpoolDir = input[RECEIPT_SPOOL_DIR_ENV];
 		try {
-			if (process.env[RECEIPT_SPOOL_DIR_ENV]) input[RECEIPT_SPOOL_DIR_ENV] = process.env[RECEIPT_SPOOL_DIR_ENV];
+			const fromEnv = resolveReceiptSpoolDir();
+			const fromInput = trustedReceiptSpoolDir(typeof priorSpoolDir === "string" ? priorSpoolDir : undefined);
+			const trustedSpoolDir = fromEnv ?? fromInput;
+			if (trustedSpoolDir) input[RECEIPT_SPOOL_DIR_ENV] = trustedSpoolDir;
+			else delete input[RECEIPT_SPOOL_DIR_ENV];
 			const res = (await callEndpoint(owner.socketPath, { verb, input })) as { ok?: boolean };
 			writeJson(res);
 			if (res?.ok === false) process.exitCode = 1;

package/src/commands/migrate.ts

@@ -1,11 +1,11 @@
 /**
- * Import MCP servers and skills from other coding agents into GJC.
+ * Import MCP servers, skills, slash commands, and instructions from other coding agents into GJC.
  */
 import { Command, Flags } from "@gajae-code/utils/cli";
 import { type MigrateCommandArgs, runMigrateCommand } from "../cli/migrate-cli";
 
 export default class Migrate extends Command {
-	static description = "Import MCP servers and skills from Claude Code, Codex, or OpenCode";
+	static description = "Import MCP servers, skills, slash commands, and instructions from other coding agents";
 
 	static examples = [
 		"gjc migrate --from claude-code",
@@ -25,7 +25,7 @@ export default class Migrate extends Command {
 			default: false,
 		}),
 		force: Flags.boolean({
-			description: "Overwrite existing skills/MCP servers instead of skipping them",
+			description: "Overwrite existing skills, commands, MCP servers, or instruction files instead of skipping them",
 			default: false,
 		}),
 		"dry-run": Flags.boolean({ description: "Preview the migration without writing anything", default: false }),

package/src/commands/sdk.ts

@@ -12,12 +12,15 @@ import {
 } from "@gajae-code/natives";
 import { getAgentDir, logger, postmortem } from "@gajae-code/utils";
 import { CliParseError, Command } from "@gajae-code/utils/cli";
+import { startupProjectEnvSnapshot } from "@gajae-code/utils/env";
+import { type ProjectEnvSnapshot, projectEnvSnapshot } from "@gajae-code/utils/env-file";
 import type { Args as ParsedArgs } from "../cli/args";
 import { isSafeSdkInternalAgentDir, scanPublicCommand } from "../cli/public-command-entry";
 import { PublicCommandFailure } from "../cli/public-command-errors";
-import { FileLockAcquireError } from "../config/file-lock";
+import { FileLockAcquireError, isFileLockAcquireTimeout } from "../config/file-lock";
 import { parseModelString } from "../config/model-resolver";
 import { Settings } from "../config/settings";
+import { trustedCoordinatorEnv } from "../gjc-runtime/sidecar-bootstrap-env";
 import { usePostmortemSignalExitAuthority } from "../lsp/client";
 import { applyStartupModelProfiles, createSessionManager } from "../main";
 import { initializeExtensions } from "../modes/runtime-init";
@@ -29,15 +32,21 @@ import {
 	type BrokerStartupExitWriteStatus,
 	writeBrokerStartupExitRecordBounded,
 } from "../sdk/broker/broker-exit";
-import { readBrokerDiscovery } from "../sdk/broker/discovery";
+import {
+	type BrokerRestartIntentWithIdentity,
+	readBrokerDiscovery,
+	readBrokerRestartIntent,
+} from "../sdk/broker/discovery";
 import { type EndpointFileRead, readEndpointFile } from "../sdk/broker/endpoint-authority";
 import {
 	BROKER_DISCOVERY_BUDGET,
 	emitBrokerStartupTestSignal,
+	reapBrokerTrampolineChild,
 	reconcileBrokerGenerationForStartup,
 	SDK_BROKER_AUTOSTART_ENV,
 	withBrokerStartupLock,
 } from "../sdk/broker/ensure";
+import { waitForBrokerHandoffAcknowledgement, waitForBrokerHandoffDecision } from "../sdk/broker/hop";
 import {
 	LifecycleFailurePublicationCleanupError,
 	LifecycleReadinessCleanupError,
@@ -88,11 +97,17 @@ export async function lifecycleArgs(
 	if (targetScope.kind !== "resolved") throw new Error(`Lifecycle session scope is invalid: ${targetScope.message}`);
 	const forkSessionDir =
 		request.operation === "session.fork" ? SessionManager.getDefaultSessionDir(cwd, agentDir) : undefined;
+	// Bun has already copied the project dotenv into process.env. A matching or
+	// dynamic declaration must not select an in-memory session. The exact "1"
+	// check stays; an operator value the project does not declare is still honored.
+	const inMemorySession =
+		process.env.GJC_SDK_TEST_IN_MEMORY_SESSION === "1" &&
+		trustedCoordinatorEnv("GJC_SDK_TEST_IN_MEMORY_SESSION", process.env, projectEnvSnapshot(cwd)) === "1";
 	return {
 		messages: [],
 		fileArgs: [],
 		unknownFlags: new Map(),
-		...(process.env.GJC_SDK_TEST_IN_MEMORY_SESSION === "1" ? { noSession: true } : {}),
+		...(inMemorySession ? { noSession: true } : {}),
 		...(request.operation === "session.resume" ? { resume: request.sessionPath } : {}),
 		...(request.modelPreset ? { mpreset: request.modelPreset } : {}),
 		// Explicit model pin (#4707): coordinator-resolved `provider/model`
@@ -547,6 +562,65 @@ export function startMemoryBackendAfterReadiness(start: () => Promise<void>): vo
 	});
 }
 
+const SDK_CWD_EQUALITY_TEST_SEAMS = [
+	"GJC_SDK_TEST_HANG_MODEL_PROFILE",
+	"GJC_SDK_TEST_FAIL_AFTER_REGISTRATION",
+	"GJC_SDK_TEST_EXIT_AFTER_READY",
+	"GJC_SDK_TEST_REJECT_AFTER_READY",
+] as const;
+
+type SdkCwdEqualityTestSeam = (typeof SDK_CWD_EQUALITY_TEST_SEAMS)[number];
+
+function isSdkCwdEqualityTestSeam(name: string): name is SdkCwdEqualityTestSeam {
+	return (SDK_CWD_EQUALITY_TEST_SEAMS as readonly string[]).includes(name);
+}
+
+function sdkCwdEqualitySnapshots(cwd: string): ProjectEnvSnapshot[] {
+	// The startup snapshot keeps a declaration Bun loaded before a later chdir.
+	return [projectEnvSnapshot(cwd), startupProjectEnvSnapshot()];
+}
+
+/**
+ * Cwd-equality test seams accept only an operator value. A project dotenv line,
+ * including one Bun expands from `$PWD`, never arms the seam.
+ */
+export function sdkCwdEqualityTestSeamActive(
+	name: string,
+	cwd: string,
+	env: NodeJS.ProcessEnv = process.env,
+	snapshots: readonly ProjectEnvSnapshot[] = sdkCwdEqualitySnapshots(cwd),
+): boolean {
+	if (!isSdkCwdEqualityTestSeam(name) || env[name] !== cwd) return false;
+	// Provenance only. trustedCoordinatorEnv trims, so a second compare to cwd
+	// would drop a trusted path that still matches exactly, including trailing space.
+	return snapshots.every(snapshot => trustedCoordinatorEnv(name, env, snapshot) !== undefined);
+}
+
+/** Copy `env` without project-dotenv values for the four cwd-equality seams. */
+export function omitUntrustedSdkCwdEqualitySeams(
+	env: NodeJS.ProcessEnv,
+	snapshots: readonly ProjectEnvSnapshot[],
+): NodeJS.ProcessEnv {
+	const denied: string[] = [];
+	for (const name of SDK_CWD_EQUALITY_TEST_SEAMS) {
+		const raw = env[name];
+		if (typeof raw !== "string" || raw.length === 0) continue;
+		if (snapshots.some(snapshot => trustedCoordinatorEnv(name, env, snapshot) === undefined)) denied.push(name);
+	}
+	if (denied.length === 0) return env;
+	const next: NodeJS.ProcessEnv = { ...env };
+	for (const name of denied) delete next[name];
+	return next;
+}
+
+function dropUntrustedSdkCwdEqualitySeams(env: NodeJS.ProcessEnv, snapshots: readonly ProjectEnvSnapshot[]): void {
+	const next = omitUntrustedSdkCwdEqualitySeams(env, snapshots);
+	if (next === env) return;
+	for (const name of SDK_CWD_EQUALITY_TEST_SEAMS) {
+		if (next[name] === undefined) delete env[name];
+	}
+}
+
 /** Runs the same persisted AgentSession bootstrap used by the production CLI. */
 export async function runSessionHost(
 	timing: {
@@ -578,6 +652,11 @@ export async function runSessionHost(
 	const agentDir = process.env.GJC_AGENT_DIR;
 	if (!agentDir) throw new Error("GJC_AGENT_DIR is required for sdk session-host-internal.");
 	const cwd = timing.cwd ?? process.cwd();
+	const cwdSeamSnapshots = sdkCwdEqualitySnapshots(cwd);
+	// Drop rejected copies before startup work can spawn a child that inherits them.
+	dropUntrustedSdkCwdEqualitySeams(process.env, cwdSeamSnapshots);
+	const cwdEqualitySeam = (name: SdkCwdEqualityTestSeam): boolean =>
+		sdkCwdEqualityTestSeamActive(name, cwd, process.env, cwdSeamSnapshots);
 	if ((await fs.realpath(request.cwd)) !== (await fs.realpath(cwd)))
 		throw new Error(`Lifecycle worktree mismatch: expected ${request.cwd}, got ${cwd}.`);
 	if (
@@ -1409,7 +1488,7 @@ export async function runSessionHost(
 	try {
 		const startupThinkingLevel = request.modelId ? parseModelString(request.modelId)?.thinkingLevel : undefined;
 		await beforeCutoff(() =>
-			process.env.GJC_SDK_TEST_HANG_MODEL_PROFILE === cwd
+			cwdEqualitySeam("GJC_SDK_TEST_HANG_MODEL_PROFILE")
 				? new Promise<void>(() => {})
 				: applyModelProfiles({
 						session,
@@ -1436,7 +1515,7 @@ export async function runSessionHost(
 		const startup = await beforeCutoff<SdkStartupResult>(() => capability.promise);
 		if (startup.status !== "started") throw startup.failure;
 		throwIfStartupInterrupted();
-		if (process.env.GJC_SDK_TEST_FAIL_AFTER_REGISTRATION === cwd)
+		if (cwdEqualitySeam("GJC_SDK_TEST_FAIL_AFTER_REGISTRATION"))
 			throw new Error("Lifecycle test failure after SDK host registration.");
 
 		await beforeCutoff(() => session.sessionManager.ensureOnDisk());
@@ -1505,11 +1584,11 @@ export async function runSessionHost(
 	// Readiness is published; the session is live. Memory startup issues one LLM
 	// request per queued rollout, so it must run outside the readiness window and
 	// its failure must never take the session down.
-	if (process.env.GJC_SDK_TEST_EXIT_AFTER_READY === cwd) {
+	if (cwdEqualitySeam("GJC_SDK_TEST_EXIT_AFTER_READY")) {
 		process.stderr.write("GJC_SDK_TEST_EXIT_AFTER_READY\n");
 		process.exit(7);
 	}
-	if (process.env.GJC_SDK_TEST_REJECT_AFTER_READY === cwd) {
+	if (cwdEqualitySeam("GJC_SDK_TEST_REJECT_AFTER_READY")) {
 		// Simulates the post-readiness liveness watcher rejecting. With the
 		// post-ready startup receipt removed, this unhandled rejection kills the
 		// host without writing any startup receipt; the broker must classify the
@@ -1713,6 +1792,34 @@ export default class Sdk extends Command {
 	}
 }
 
+/** Captures and removes one-shot restart credentials before the broker forks descendants. */
+export function consumeBrokerRestartEnvironment(environment: NodeJS.ProcessEnv): {
+	requestIdEnv: string | undefined;
+	restartDeadlineAt: number | undefined;
+} {
+	const restartRequestEnv = environment.GJC_BROKER_RESTART_REQUEST;
+	const restartDeadlineEnv = environment.GJC_BROKER_RESTART_DEADLINE;
+	delete environment.GJC_BROKER_RESTART_REQUEST;
+	delete environment.GJC_BROKER_RESTART_DEADLINE;
+	const requestIdEnv =
+		typeof restartRequestEnv === "string" && /^[A-Za-z0-9_-]{1,256}$/.test(restartRequestEnv)
+			? restartRequestEnv
+			: undefined;
+	let restartDeadlineAt: number | undefined;
+	if (restartDeadlineEnv !== undefined) {
+		const parsedDeadlineAt = Number(restartDeadlineEnv);
+		if (
+			requestIdEnv === undefined ||
+			!/^[0-9]{1,16}$/.test(restartDeadlineEnv) ||
+			!Number.isSafeInteger(parsedDeadlineAt) ||
+			parsedDeadlineAt <= Date.now()
+		)
+			throw new Error("Invalid SDK broker restart deadline; refusing successor startup.");
+		restartDeadlineAt = parsedDeadlineAt;
+	}
+	return { requestIdEnv, restartDeadlineAt };
+}
+
 /**
  * Runs one parsed SDK internal entry point. `publicBrokerRun` is set only by
  * the stable `gjc sdk broker run` contract, which must report a lost ownership
@@ -1722,13 +1829,17 @@ export default class Sdk extends Command {
 async function runSdkInternal(internal: SdkInternalArgv, publicBrokerRun = false): Promise<void> {
 	if (internal.action === "broker-trampoline-internal") {
 		if (process.platform === "win32") throw new CliParseError("Broker trampoline is unavailable on Windows.");
+		const retainChildUntilPublication = process.env.GJC_BROKER_TRAMPOLINE_RETAIN_UNTIL_PUBLICATION === "1";
 		const command = resolveSdkInternalSpawnCommand("broker-internal");
+		const brokerEnvironment = { ...command.env };
+		delete brokerEnvironment.GJC_BROKER_TRAMPOLINE_RETAIN_UNTIL_PUBLICATION;
+		dropUntrustedSdkCwdEqualitySeams(brokerEnvironment, sdkCwdEqualitySnapshots(process.cwd()));
 		let child: ChildProcess;
 		try {
 			child = spawn(command.file, [...command.args, "--agent-dir", internal.agentDir], {
 				detached: true,
 				stdio: ["ignore", "ignore", "inherit"],
-				env: command.env,
+				env: brokerEnvironment,
 				...(command.kind === "bun-source" ? { cwd: command.cwd } : {}),
 			});
 		} catch (error) {
@@ -1741,11 +1852,7 @@ async function runSdkInternal(internal: SdkInternalArgv, publicBrokerRun = false
 		if (child.pid === undefined) throw new Error("Broker trampoline could not start broker.");
 		const incarnation = processIncarnation(child.pid);
 		if (!incarnation) {
-			try {
-				child.kill("SIGKILL");
-			} catch {
-				// The child may already have exited; either way identity was not established.
-			}
+			await reapBrokerTrampolineChild(child, child.pid);
 			throw new Error("Broker trampoline could not observe broker identity.");
 		}
 		if (spawnError) throw new Error("Broker trampoline could not start broker.", { cause: spawnError });
@@ -1757,13 +1864,19 @@ async function runSdkInternal(internal: SdkInternalArgv, publicBrokerRun = false
 		try {
 			await stdoutWrite.promise;
 		} catch (error) {
-			try {
-				child.kill("SIGKILL");
-			} catch {
-				// The child may already have exited; reporting failure remains authoritative.
-			}
+			await reapBrokerTrampolineChild(child, child.pid, incarnation);
 			throw error;
 		}
+		if (retainChildUntilPublication) {
+			const decision = await waitForBrokerHandoffDecision(process.stdin);
+			if (decision === "abort") {
+				await reapBrokerTrampolineChild(child, child.pid, incarnation);
+				return;
+			}
+		} else if (!(await waitForBrokerHandoffAcknowledgement(process.stdin))) {
+			await reapBrokerTrampolineChild(child, child.pid, incarnation);
+			throw new Error("Broker trampoline handoff was not acknowledged; its direct child was reaped.");
+		}
 		child.unref();
 		return;
 	}
@@ -1846,7 +1959,13 @@ async function runSdkInternal(internal: SdkInternalArgv, publicBrokerRun = false
 		if (startupExitLogged) return;
 		startupExitLogged = true;
 		const level = record.exitCode === 1 ? "error" : "warn";
-		if (record.exitCode === 1) logger.error("sdk broker: startup watchdog forcing exit", record);
+		if (record.exitCode === 1)
+			logger.error(
+				record.reason === "startup-deadline"
+					? "sdk broker: startup watchdog forcing exit"
+					: "sdk broker: startup refused",
+				record,
+			);
 		else logger.warn("sdk broker: startup interrupted", record);
 		process.stderr.write(`${JSON.stringify({ level, message, ...record })}\n`);
 	};
@@ -1866,9 +1985,11 @@ async function runSdkInternal(internal: SdkInternalArgv, publicBrokerRun = false
 		const message =
 			reason === "startup-lock-blocked" && blockingLockPath
 				? `SDK broker startup blocked by retained removal transition ${blockingLockPath}.`
-				: reason === "startup-deadline"
-					? `SDK broker startup exceeded its ${timeoutMs}ms fence deadline.`
-					: `SDK broker startup interrupted by ${signal} before readiness.`;
+				: reason === "startup-lock-unavailable"
+					? `SDK broker startup could not acquire ${blockingLockPath ?? "a required lock"}.`
+					: reason === "startup-deadline"
+						? `SDK broker startup exceeded its ${timeoutMs}ms fence deadline.`
+						: `SDK broker startup interrupted by ${signal} before readiness.`;
 		writeStartupExitLog(exitRecord, message);
 		startupExitTask = (async () => {
 			const exitRecordWrite = await beginStartupExitRecordWrite(exitRecord);
@@ -1922,33 +2043,124 @@ async function runSdkInternal(internal: SdkInternalArgv, publicBrokerRun = false
 		await exitDuringStartup("startup-signal", startupSignalExitCode(signal), signal);
 		return true;
 	};
+	let startupFenceAcquired = false;
 	try {
+		const { requestIdEnv, restartDeadlineAt } = consumeBrokerRestartEnvironment(process.env);
+		const MAX_SESSION_INDEX_TIMEOUT_RETRIES = 2;
+		let sessionIndexTimeoutRetries = 0;
+		let activeStartupDeadlineAt = 0;
 		const startupOperation = async (deadline: number): Promise<Broker | undefined> => {
+			for (;;) {
+				activeStartupDeadlineAt = deadline;
+				try {
+					return await singleStartupAttempt(deadline);
+				} catch (error) {
+					if (
+						!isFileLockAcquireTimeout(error) ||
+						!startupFenceAcquired ||
+						path.resolve(error.filePath) !==
+							path.resolve(path.join(agentDir, "sdk", "sessions", "index.jsonl")) ||
+						sessionIndexTimeoutRetries >= MAX_SESSION_INDEX_TIMEOUT_RETRIES
+					)
+						throw error;
+					sessionIndexTimeoutRetries++;
+					const backoffMs = 100 * 2 ** (sessionIndexTimeoutRetries - 1);
+					if (Date.now() + backoffMs >= activeStartupDeadlineAt) throw error;
+					const failedBroker = broker;
+					if (failedBroker) {
+						try {
+							await failedBroker.stop({ kind: "startup-failure" });
+						} catch (cleanupError) {
+							throw new AggregateError(
+								[error, cleanupError],
+								"Session-index startup retry could not clean up the failed broker candidate.",
+							);
+						}
+						if (broker === failedBroker) broker = undefined;
+						if (runningBroker === failedBroker) runningBroker = undefined;
+					}
+					candidateStartTask = undefined;
+					logger.debug("sdk broker: session-index lock timeout, retrying startup", {
+						reason: "session-index-timeout-retry",
+						attempt: sessionIndexTimeoutRetries,
+						backoffMs,
+					});
+					await Bun.sleep(backoffMs);
+				}
+			}
+		};
+		const singleStartupAttempt = async (deadline: number): Promise<Broker | undefined> => {
 			const remainingMs = Math.max(1, deadline - Date.now());
 			const testWatchdogMs = Number(process.env.GJC_SDK_TEST_BROKER_STARTUP_WATCHDOG_MS ?? 0);
-			const watchdogMs =
+			const ordinaryWatchdogMs =
 				Number.isSafeInteger(testWatchdogMs) && testWatchdogMs > 0 && testWatchdogMs <= remainingMs
 					? testWatchdogMs
 					: remainingMs;
-			const startupCheckpointDeadline = performance.now() + watchdogMs - 1_000;
-			const startupWatchdog = setTimeout(() => {
-				startupAbortController.abort();
-				void exitDuringStartup("startup-deadline", 1, null, watchdogMs).then(async started => {
-					if (!started) {
-						// A prior startup signal owns the exit cause; its postmortem callback
-						// returns after bounded cleanup and preserves the signal status.
-						return;
-					}
-					await waitForStartupAbortCleanup();
-					process.exit(1);
-				});
-			}, watchdogMs);
+			let restartRequestId: string | undefined;
+			let startupDeadlineAt = deadline;
+			let effectiveWatchdogMs = ordinaryWatchdogMs;
+			let startupCheckpointDeadline = performance.now() + Math.max(1, effectiveWatchdogMs - 1_000);
+			const armStartupWatchdog = (): NodeJS.Timeout =>
+				setTimeout(() => {
+					startupAbortController.abort();
+					void exitDuringStartup("startup-deadline", 1, null, effectiveWatchdogMs).then(async started => {
+						if (!started) {
+							// A prior startup signal owns the exit cause; its postmortem callback
+							// returns after bounded cleanup and preserves the signal status.
+							return;
+						}
+						await waitForStartupAbortCleanup();
+						process.exit(1);
+					});
+				}, effectiveWatchdogMs);
+			let startupWatchdog = armStartupWatchdog();
 			try {
+				let restartIntent: BrokerRestartIntentWithIdentity | null;
+				try {
+					restartIntent = await readBrokerRestartIntent(agentDir);
+				} catch (error) {
+					throw new Error("Could not validate SDK broker restart intent; refusing untagged startup.", {
+						cause: error,
+					});
+				}
+				// A committed request survives the prior owner's exit. Ordinary or
+				// mismatched starts must not publish ahead of its exact successor.
+				if (
+					restartIntent?.phase === "committed" &&
+					restartIntent.expiresAt > Date.now() &&
+					restartIntent.requestId !== requestIdEnv
+				)
+					throw new Error("A committed SDK broker restart is active; startup requires its exact request ID.");
+				if (
+					restartDeadlineAt !== undefined &&
+					(restartIntent?.phase !== "committed" ||
+						restartIntent.requestId !== requestIdEnv ||
+						restartIntent.expiresAt !== restartDeadlineAt)
+				)
+					throw new Error("Could not validate SDK broker restart deadline; refusing successor startup.");
+				if (requestIdEnv !== undefined && restartIntent?.requestId === requestIdEnv) {
+					if (restartIntent.phase !== "committed")
+						throw new Error("SDK broker restart intent is not committed; refusing successor startup.");
+					const remainingSuccessorMs = restartIntent.expiresAt - Date.now();
+					if (remainingSuccessorMs <= 0)
+						throw new Error("SDK broker restart intent expired; refusing untagged startup.");
+					restartRequestId = requestIdEnv;
+					startupDeadlineAt = restartDeadlineAt ?? restartIntent.expiresAt;
+					activeStartupDeadlineAt = startupDeadlineAt;
+					effectiveWatchdogMs =
+						Number.isSafeInteger(testWatchdogMs) && testWatchdogMs > 0 && testWatchdogMs <= remainingSuccessorMs
+							? testWatchdogMs
+							: remainingSuccessorMs;
+					clearTimeout(startupWatchdog);
+					startupCheckpointDeadline = performance.now() + Math.max(1, effectiveWatchdogMs - 1_000);
+					startupWatchdog = armStartupWatchdog();
+				}
+				if (startupAbortController.signal.aborted) return undefined;
 				// `gjc sdk broker run` never retires another owner, even one this generation cannot
 				// reuse: any live incumbent is a refusal. Autostart repairs unusable generations.
 				const existing = publicBrokerRun
 					? ((await readBrokerDiscovery(agentDir)) ?? undefined)
-					: await reconcileBrokerGenerationForStartup({ agentDir }, deadline);
+					: await reconcileBrokerGenerationForStartup({ agentDir }, startupDeadlineAt);
 				if (startupAbortController.signal.aborted) return undefined;
 				if (existing) {
 					logger.info("sdk broker: startup reused an existing owner", {
@@ -1985,11 +2197,9 @@ async function runSdkInternal(internal: SdkInternalArgv, publicBrokerRun = false
 				// launcher-supplied environment variable; it is validated here and handed
 				// to Broker as a typed setting, never read a second time inside broker.ts
 				// from process.env directly.
-				const restartRequestEnv = process.env.GJC_BROKER_RESTART_REQUEST;
-				const restartRequestId =
-					typeof restartRequestEnv === "string" && /^[A-Za-z0-9_-]{1,256}$/.test(restartRequestEnv)
-						? restartRequestEnv
-						: undefined;
+				// Restart authorization is revalidated before constructing the broker; the
+				// watchdog was already armed before any intent-file I/O.
+				const effectiveCheckpointDeadline = startupCheckpointDeadline;
 				const testPostPublicationDelayMs = Number(process.env.GJC_SDK_TEST_BROKER_POST_PUBLICATION_DELAY_MS ?? 0);
 				const startupPostPublicationDelayMs =
 					Number.isSafeInteger(testPostPublicationDelayMs) &&
@@ -2027,14 +2237,19 @@ async function runSdkInternal(internal: SdkInternalArgv, publicBrokerRun = false
 								}
 							}
 						: undefined;
+				const brokerSettings = await Settings.loadForScope({ cwd: process.cwd(), agentDir });
 				const candidate = new Broker({
 					agentDir,
 					startupAbortSignal: startupAbortController.signal,
-					startupCheckpointDeadline,
+					startupCheckpointDeadline: effectiveCheckpointDeadline,
 					onStartupReady: () => clearTimeout(startupWatchdog),
-					masterOrphanGraceMs: (await Settings.loadForScope({ cwd: process.cwd(), agentDir })).get(
-						"sdk.masterOrphanGraceMs",
-					),
+					masterOrphanGraceMs: brokerSettings.get("sdk.masterOrphanGraceMs"),
+					abandonedGraceMs: brokerSettings.get("sdk.brokerAbandonedGraceMs"),
+					// Only the detached autostart entry retires itself when nobody is left to
+					// use it. A supervised `gjc sdk broker run` service is owned by its
+					// operator's process manager, which reads an owned-root completion as a
+					// clean exit and would not restart it.
+					reapWhenAbandoned: !publicBrokerRun,
 					resolveDirectoryMigration: async cwd => {
 						const settings = await Settings.loadForScope({ cwd, agentDir });
 						try {
@@ -2066,7 +2281,11 @@ async function runSdkInternal(internal: SdkInternalArgv, publicBrokerRun = false
 			}
 		};
 		broker = await withBrokerStartupLock(agentDir, startupOperation, {
-			onAcquired: () => void emitBrokerStartupTestSignal("fence-acquired"),
+			...(restartDeadlineAt === undefined ? {} : { deadlineAt: restartDeadlineAt }),
+			onAcquired: () => {
+				startupFenceAcquired = true;
+				void emitBrokerStartupTestSignal("fence-acquired");
+			},
 			onContended: () => void emitBrokerStartupTestSignal("fence-contended"),
 		});
 	} catch (error) {
@@ -2074,9 +2293,14 @@ async function runSdkInternal(internal: SdkInternalArgv, publicBrokerRun = false
 			await finishPendingStartupSignal();
 			return;
 		}
-		// A retained removal transition is an explicit acquire failure, not only
-		// an exhausted ordinary contention timeout.
-		if (error instanceof FileLockAcquireError && error.orphanPath) {
+		// Only a retained transition on the outer startup fence gets its own
+		// blocked reason. Nested resource-lock failures are retryable unavailability.
+		if (
+			error instanceof FileLockAcquireError &&
+			!startupFenceAcquired &&
+			error.code === "orphan_transition" &&
+			error.orphanPath
+		) {
 			await exitDuringStartup(
 				"startup-lock-blocked",
 				1,
@@ -2084,6 +2308,9 @@ async function runSdkInternal(internal: SdkInternalArgv, publicBrokerRun = false
 				BROKER_DISCOVERY_BUDGET.startupLockWaitMs,
 				error.orphanPath,
 			);
+		} else if (error instanceof FileLockAcquireError) {
+			// Nested lock failures or non-orphan-transition errors
+			await exitDuringStartup("startup-lock-unavailable", 1, null, undefined, error.orphanPath ?? error.lockPath);
 		}
 		if (broker) {
 			try {

package/src/commands/ultragoal.ts

@@ -8,6 +8,7 @@ import {
 	writeCurrentSessionGoalModeState,
 	writePendingGoalModeRequest,
 } from "../gjc-runtime/goal-mode-request";
+import { trustedCoordinatorEnv } from "../gjc-runtime/sidecar-bootstrap-env";
 import { isUltragoalHelpInvocation, runNativeUltragoalCommand } from "../gjc-runtime/ultragoal-runtime";
 
 export default class Ultragoal extends Command {
@@ -44,16 +45,23 @@ export default class Ultragoal extends Command {
 		const { objective, goalsPath, provenance } = await readUltragoalGjcObjective(cwd);
 
 		await writeCurrentSessionGoalModeState({
-			sessionFile: process.env[GJC_SESSION_FILE_ENV],
+			// Bun has already copied the project dotenv into the environment. A
+			// value that matches that snapshot must not select the transcript.
+			sessionFile: trustedCoordinatorEnv(GJC_SESSION_FILE_ENV),
 			objective,
 			provenance,
 		});
-		await writePendingGoalModeRequest({
-			cwd,
-			objective,
-			goalsPath,
-			provenance,
-			sessionId: process.env[GJC_SESSION_ID_ENV],
-		});
+		// A matching or dynamic project declaration must not select the session.
+		// Skip the write in that case: the helper falls back to the same env value.
+		const sessionId = trustedCoordinatorEnv(GJC_SESSION_ID_ENV);
+		if (sessionId !== undefined || !process.env[GJC_SESSION_ID_ENV]?.trim()) {
+			await writePendingGoalModeRequest({
+				cwd,
+				objective,
+				goalsPath,
+				provenance,
+				sessionId,
+			});
+		}
 	}
 }