@gajae-code/coding-agent 0.18.8 → 0.18.9

package/src/eval/py/kernel.ts

@@ -77,6 +77,26 @@ interface KernelStartOptions extends KernelLifecycleOptions {
 	env?: Record<string, string | undefined>;
 	runtimeOptions?: PythonRuntimeOptions;
 	settings?: Settings;
+	/** @internal Synchronously registers the actual spawned kernel before startup callbacks run. */
+	onKernelCreated?: (kernel: PythonKernel) => void;
+	/** @internal Routes partial-start cleanup through the executor's retained ownership. */
+	onStartupFailure?: (kernel: PythonKernel) => Promise<void>;
+}
+
+export type PythonKernelStartupCleanupFailure =
+	| { kind: "unconfirmed"; result: KernelShutdownResult }
+	| { kind: "rejected"; error: unknown };
+
+/** Startup failed after a real runner was created and physical cleanup failed. */
+export class PythonKernelStartError extends Error {
+	constructor(
+		readonly kernel: PythonKernel,
+		readonly startupError: unknown,
+		readonly cleanupFailure: PythonKernelStartupCleanupFailure,
+	) {
+		super("Python kernel startup failed and runner cleanup was not confirmed", { cause: startupError });
+		this.name = "PythonKernelStartError";
+	}
 }
 
 interface KernelShutdownOptions {
@@ -108,6 +128,13 @@ function throwIfAborted(signal: AbortSignal | undefined, fallbackReason: string)
 	throw createAbortError("AbortError", typeof reason === "string" ? reason : fallbackReason);
 }
 
+function throwIfLifecycleEnded(lifecycle: KernelLifecycleOptions, message: string): void {
+	throwIfAborted(lifecycle.signal, message);
+	if (lifecycle.deadlineMs !== undefined && lifecycle.deadlineMs <= Date.now()) {
+		throw createAbortError("TimeoutError", `${message} timed out`);
+	}
+}
+
 async function waitForLifecycle<T>(
 	value: Promise<T>,
 	lifecycle: PythonRuntimeLifecycleOptions | undefined,
@@ -244,6 +271,7 @@ export class PythonKernel {
 	#alive = true;
 	#disposed = false;
 	#shutdownConfirmed = false;
+	#shutdownPromise: Promise<KernelShutdownResult> | null = null;
 	#exitedPromise: Promise<number> | null = null;
 	#exitCode: number | null = null;
 	#stderrTail = "";
@@ -255,6 +283,7 @@ export class PythonKernel {
 	}
 
 	static async start(options: KernelStartOptions): Promise<PythonKernel> {
+		throwIfLifecycleEnded(options, "Python kernel startup");
 		const availability = await logger.time(
 			"PythonKernel.start:availabilityCheck",
 			checkPythonKernelAvailability,
@@ -263,17 +292,20 @@ export class PythonKernel {
 			{ signal: options.signal, deadlineMs: options.deadlineMs },
 			options.settings,
 		);
+		throwIfLifecycleEnded(options, "Python kernel startup");
 		if (!availability.ok) {
 			throw new Error(availability.reason ?? "Python kernel unavailable");
 		}
 
 		const settings = options.settings ?? (await Settings.init());
+		throwIfLifecycleEnded(options, "Python kernel startup");
 		const { env: shellEnv } = settings.getShellConfig();
 		const baseEnv = filterEnv(shellEnv);
 		const runtime = await ensurePythonRuntime(options.cwd, baseEnv, options.runtimeOptions, {
 			signal: options.signal,
 			deadlineMs: options.deadlineMs,
 		});
+		throwIfLifecycleEnded(options, "Python kernel startup");
 		const spawnEnv: Record<string, string> = {};
 		for (const [key, value] of Object.entries(runtime.env)) {
 			if (typeof value === "string") spawnEnv[key] = value;
@@ -286,6 +318,7 @@ export class PythonKernel {
 		spawnEnv.PYTHONIOENCODING = "utf-8";
 
 		const scriptPath = await ensureRunnerScript();
+		throwIfLifecycleEnded(options, "Python kernel startup");
 		const kernel = new PythonKernel(Snowflake.next());
 
 		const proc = Bun.spawn([runtime.pythonPath, "-u", scriptPath], {
@@ -302,25 +335,40 @@ export class PythonKernel {
 		kernel.#proc = proc;
 		kernel.#stdin = proc.stdin;
 		kernel.#exitedPromise = proc.exited;
-		void kernel.#exitedPromise.then(code => {
-			kernel.#exitCode = code;
-			kernel.#alive = false;
-			kernel.#abortPendingExecutions(`Python kernel exited with code ${code}`, { kernelKilled: true });
-		});
 
-		kernel.#startReader(proc.stdout as ReadableStream<Uint8Array>);
-		kernel.#startStderrDrain(proc.stderr as ReadableStream<Uint8Array>);
+		try {
+			options.onKernelCreated?.(kernel);
+			void kernel.#exitedPromise.then(code => {
+				kernel.#exitCode = code;
+				kernel.#alive = false;
+				kernel.#abortPendingExecutions(`Python kernel exited with code ${code}`, { kernelKilled: true });
+			});
 
-		const startup = { signal: options.signal, deadlineMs: options.deadlineMs };
-		const startupBudget = Math.min(getRemainingTimeMs(startup.deadlineMs) ?? STARTUP_TIMEOUT_MS, STARTUP_TIMEOUT_MS);
+			kernel.#startReader(proc.stdout as ReadableStream<Uint8Array>);
+			kernel.#startStderrDrain(proc.stderr as ReadableStream<Uint8Array>);
 
-		try {
+			const startup = { signal: options.signal, deadlineMs: options.deadlineMs };
+			const startupBudget = Math.min(
+				getRemainingTimeMs(startup.deadlineMs) ?? STARTUP_TIMEOUT_MS,
+				STARTUP_TIMEOUT_MS,
+			);
 			const initScript = buildInitScript(options.cwd, options.env);
 			await kernel.#executeWithBudget(initScript, startup.signal, startupBudget, "Python kernel init");
 			await kernel.#executeWithBudget(PYTHON_PRELUDE, startup.signal, startupBudget, "Python kernel prelude");
 			return kernel;
 		} catch (err) {
-			await kernel.shutdown({ timeoutMs: SHUTDOWN_GRACE_MS }).catch(() => {});
+			let cleanupFailure: PythonKernelStartupCleanupFailure | undefined;
+			try {
+				if (options.onStartupFailure) {
+					await options.onStartupFailure(kernel);
+				} else {
+					const result = await kernel.shutdown({ timeoutMs: SHUTDOWN_GRACE_MS });
+					if (!result.confirmed) cleanupFailure = { kind: "unconfirmed", result };
+				}
+			} catch (cleanupError) {
+				cleanupFailure = { kind: "rejected", error: cleanupError };
+			}
+			if (cleanupFailure) throw new PythonKernelStartError(kernel, err, cleanupFailure);
 			throw err;
 		}
 	}
@@ -475,9 +523,27 @@ export class PythonKernel {
 		}
 	}
 
-	async shutdown(options?: KernelShutdownOptions): Promise<KernelShutdownResult> {
-		if (this.#shutdownConfirmed) return { confirmed: true };
+	shutdown(options?: KernelShutdownOptions): Promise<KernelShutdownResult> {
+		if (this.#shutdownConfirmed) return Promise.resolve({ confirmed: true });
+		if (this.#shutdownPromise) return this.#shutdownPromise;
+
+		const { promise, resolve, reject } = Promise.withResolvers<KernelShutdownResult>();
+		this.#shutdownPromise = promise;
+		void promise.then(
+			() => {
+				if (this.#shutdownPromise === promise) this.#shutdownPromise = null;
+			},
+			() => {
+				if (this.#shutdownPromise === promise) this.#shutdownPromise = null;
+			},
+		);
+		void Promise.resolve()
+			.then(() => this.#shutdown(options))
+			.then(resolve, reject);
+		return promise;
+	}
 
+	async #shutdown(options?: KernelShutdownOptions): Promise<KernelShutdownResult> {
 		this.#alive = false;
 		this.#abortPendingExecutions("Python kernel shutdown", { kernelKilled: true });
 

package/src/eval/py/tool-bridge.ts

@@ -72,6 +72,10 @@ async function startServer(): Promise<BridgeServer> {
 			if (!sessionId || !name) {
 				return Response.json({ ok: false, error: "Missing session/name" }, { status: 400 });
 			}
+			const live = registrations.get(capability);
+			if (live !== registration || registration.signal?.aborted) {
+				return new Response("Forbidden", { status: 403 });
+			}
 			if (sessionId !== registration.sessionId) {
 				return new Response("Forbidden", { status: 403 });
 			}

package/src/export/html/html-export-destination.ts

@@ -0,0 +1,16 @@
+import * as fs from "node:fs";
+
+const HTML_EXPORT_DESTINATION_OPEN_FLAGS =
+	fs.constants.O_WRONLY | fs.constants.O_CREAT | (process.platform === "win32" ? 0 : (fs.constants.O_NOFOLLOW ?? 0));
+
+/** Owner-only HTML export. A replaced file is locked down on the opened descriptor. */
+export function openHtmlExportDestination(outputPath: string): number {
+	const fd = fs.openSync(outputPath, HTML_EXPORT_DESTINATION_OPEN_FLAGS, 0o600);
+	try {
+		fs.fchmodSync(fd, 0o600);
+		return fd;
+	} catch (error) {
+		fs.closeSync(fd);
+		throw error;
+	}
+}

package/src/export/html/index.ts

@@ -7,6 +7,7 @@ import { getResolvedThemeColors, getThemeExportColors } from "../../modes/theme/
 import { SessionManager } from "../../session/session-manager";
 // Pre-generated template (created by scripts/generate-template.ts at publish time)
 import { cssColorOrFallback } from "./css-color";
+import { openHtmlExportDestination } from "./html-export-destination";
 import { TEMPLATE } from "./template.generated";
 
 export interface ExportOptions {
@@ -169,11 +170,6 @@ const HTML_EXPORT_SOURCE_OPEN_FLAGS =
 	syncFs.constants.O_NONBLOCK |
 	(process.platform === "win32" ? 0 : (syncFs.constants.O_NOFOLLOW ?? 0));
 
-const HTML_EXPORT_DESTINATION_OPEN_FLAGS =
-	syncFs.constants.O_WRONLY |
-	syncFs.constants.O_CREAT |
-	(process.platform === "win32" ? 0 : (syncFs.constants.O_NOFOLLOW ?? 0));
-
 function sameFileIdentity(left: syncFs.BigIntStats, right: syncFs.BigIntStats): boolean {
 	return left.dev === right.dev && left.ino === right.ino;
 }
@@ -193,7 +189,7 @@ async function openHtmlExportDescriptors(
 			}
 			await assertExportDoesNotAliasSource(sourcePath, outputPath);
 		}
-		destination = syncFs.openSync(outputPath, HTML_EXPORT_DESTINATION_OPEN_FLAGS, 0o666);
+		destination = openHtmlExportDestination(outputPath);
 		if (source !== undefined) {
 			const sourceIdentity = syncFs.fstatSync(source, { bigint: true });
 			const destinationIdentity = syncFs.fstatSync(destination, { bigint: true });

package/src/extensibility/extensions/function-hooks-internal.ts

@@ -4,6 +4,30 @@ import { type FunctionHookRegistration, validateFunctionHookTarget } from "./fun
 
 export type TaggedFunctionHookHandler = (...args: unknown[]) => Promise<unknown>;
 
+// Host SDK lifecycle observers publish the accepted run's bookkeeping. They do
+// not execute user work and must not consume provider-attempt replay authority.
+const sdkLifecycleObservers = new WeakSet<(...args: never[]) => unknown>();
+const providerRequestHandlers = new WeakMap<(...args: never[]) => unknown, string>();
+
+/** Host-owned provider adapters must not consume replay authority for other providers. */
+export function tagProviderRequestHandler<T extends (...args: never[]) => unknown>(provider: string, handler: T): T {
+	providerRequestHandlers.set(handler, provider);
+	return handler;
+}
+
+export function getProviderRequestHandlerProvider(handler: (...args: never[]) => unknown): string | undefined {
+	return providerRequestHandlers.get(handler);
+}
+
+export function tagSdkLifecycleObserver<T extends (...args: never[]) => unknown>(handler: T): T {
+	sdkLifecycleObservers.add(handler);
+	return handler;
+}
+
+export function isSdkLifecycleObserver(handler: (...args: never[]) => unknown): boolean {
+	return sdkLifecycleObservers.has(handler);
+}
+
 const registrations = new WeakMap<TaggedFunctionHookHandler, FunctionHookRegistration>();
 const registrationOrders = new WeakMap<(...args: never[]) => unknown, number>();
 
@@ -21,6 +45,9 @@ export function wrapExtensionHandlerRegistration<T extends (...args: never[]) =>
 ): T {
 	const registered = ((...args: never[]) => handler(...args)) as T;
 	registrationOrders.set(registered, registrationOrder);
+	if (sdkLifecycleObservers.has(handler)) sdkLifecycleObservers.add(registered);
+	const provider = providerRequestHandlers.get(handler);
+	if (provider !== undefined) providerRequestHandlers.set(registered, provider);
 	return registered;
 }
 

package/src/extensibility/extensions/runner.ts

@@ -51,6 +51,8 @@ import {
 import {
 	getExtensionHandlerRegistrationOrder,
 	getFunctionHookRegistration,
+	getProviderRequestHandlerProvider,
+	isSdkLifecycleObserver,
 	readConstrainedFunctionHookFile,
 } from "./function-hooks-internal";
 import type {
@@ -918,6 +920,13 @@ export class ExtensionRunner {
 		const wildcard = this.#handlersByEvent.get("*") ?? [];
 		const matches: IndexedHandler[] = [];
 		for (const indexed of [...exact, ...wildcard]) {
+			const provider = getProviderRequestHandlerProvider(indexed.handler);
+			if (
+				event.type === "before_provider_request" &&
+				provider !== undefined &&
+				this.createContext().model?.provider !== provider
+			)
+				continue;
 			const registration = getFunctionHookRegistration(indexed.handler);
 			if (!registration) {
 				if (includeLegacyToolHandlers && indexed.registrationOrder >= 0 && exact.includes(indexed))
@@ -1076,7 +1085,8 @@ export class ExtensionRunner {
 		if (handlers.length === 0) return { action: "continue", event };
 		const includesLegacy = handlers.some(indexed => getFunctionHookRegistration(indexed.handler) === undefined);
 		if (includesLegacy) this.#requireScopeOrFailClosed(options.scope, event.type);
-		this.#markAttemptExecuted(options.scope);
+		if (handlers.some(indexed => event.type !== "agent_start" || !isSdkLifecycleObserver(indexed.handler)))
+			this.#markAttemptExecuted(options.scope);
 		const functionHookDepth = this.#functionHookDepth.getStore() ?? 0;
 		if (functionHookDepth >= 16) {
 			const reason = "Function hook re-entry depth exceeded";

package/src/extensibility/gjc-plugins/mcp-policy.ts

@@ -6,7 +6,7 @@ import { GjcPluginLoadError, type GjcPluginMcpManifestEntry } from "./types";
 /**
  * Shared MCP security policy applied at BOTH install validation and runtime
  * connect for third-party plugin-bundle MCP servers. Defaults are deny-first:
- * HTTPS only, no private/loopback/link-local/metadata endpoints, stdio confined
+ * HTTPS only, no private/loopback/link-local/CGNAT/metadata endpoints, stdio confined
  * to the plugin root.
  */
 
@@ -34,6 +34,7 @@ export function isDeniedIpv4(host: string): boolean {
 	if (a === 172 && b >= 16 && b <= 31) return true; // private 172.16.0.0/12
 	if (a === 192 && b === 168) return true; // private 192.168.0.0/16
 	if (a === 169 && b === 254) return true; // link-local 169.254.0.0/16 (incl 169.254.169.254 metadata)
+	if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT 100.64.0.0/10
 	if (a === 0) return true; // 0.0.0.0/8 unspecified/this-network
 	if (a >= 224) return true; // multicast/reserved 224.0.0.0/4 and 240.0.0.0/4
 	return false;

package/src/extensibility/gjc-plugins/runtime-adapters.ts

@@ -172,6 +172,8 @@ const initialNodeIdentities = initialProcessEnvironment.then(async environment =
 		const lexical = path.join(pathEntry, process.platform === "win32" ? "node.exe" : "node");
 		try {
 			const real = await fs.realpath(lexical);
+			// A temporary root is writable by other local users and by checkouts the user
+			// never vetted, so a `node` resolved there never becomes launch authority.
 			if (temporaryRoots.some(root => isWithin(root, real))) continue;
 			if (identities.has(real)) continue;
 			const stat = await fs.stat(real);
@@ -189,7 +191,11 @@ const initialNodeIdentities = initialProcessEnvironment.then(async environment =
 	return identities;
 });
 
-/** First-use digests of startup Node candidates, keyed by realpath; failures are cached as `undefined`. */
+/**
+ * First-use digests of startup Node candidates, keyed by realpath. Successful and
+ * in-flight digests stay memoized; a failed attempt is evicted so a transient error
+ * (e.g. EMFILE) can be retried against the same startup identity.
+ */
 const initialNodeHashes = new Map<string, Promise<string | undefined>>();
 
 /**
@@ -197,20 +203,26 @@ const initialNodeHashes = new Map<string, Promise<string | undefined>>();
  * was not a startup candidate or no longer is the startup file object.
  */
 export function getInitialNodeHash(realPath: string): Promise<string | undefined> {
-	let digest = initialNodeHashes.get(realPath);
-	if (!digest) {
-		digest = initialNodeIdentities.then(async identities => {
-			const identity = identities.get(realPath);
-			if (!identity) return undefined;
-			try {
-				return await hashStableFile(realPath, "Initial Node executable", MCP_LAUNCHER_MAX_BYTES, identity);
-			} catch {
-				return undefined;
-			}
-		});
-		initialNodeHashes.set(realPath, digest);
-	}
-	return digest;
+	const cached = initialNodeHashes.get(realPath);
+	if (cached) return cached;
+
+	const attempt = initialNodeIdentities.then(async identities => {
+		const identity = identities.get(realPath);
+		if (!identity) return undefined;
+		try {
+			return await hashStableFile(realPath, "Initial Node executable", MCP_LAUNCHER_MAX_BYTES, identity);
+		} catch {
+			// Do not memoize failed attempts to allow retries on transient errors
+			// (e.g., EMFILE on file open/read). Remove the pending entry so the next
+			// call can retry the operation with the same startup identity.
+			initialNodeHashes.delete(realPath);
+			return undefined;
+		}
+	});
+	// Memoize the in-flight attempt so only one concurrent operation runs, but
+	// the entry may be deleted if the operation fails (to allow retry).
+	initialNodeHashes.set(realPath, attempt);
+	return attempt;
 }
 
 async function snapshotExistingFile(filePath: string): Promise<FileSnapshot | null> {

package/src/extensibility/skill-management.ts

@@ -56,6 +56,7 @@ export type SkillDisabledReason = "protected" | "scope-trust" | "ignored" | "inc
 export interface ManagedSkillRecord {
 	name: string;
 	description: string;
+	importedFrom?: string;
 	path: string;
 	scope: SkillScope;
 	/** Canonical source label, e.g. "project .gjc/skills" or "user ~/.gjc/agent/skills". */
@@ -392,9 +393,11 @@ export async function listNativeSkillsForManagement(options: {
 
 			if (!seenNames.has(skill.name)) {
 				seenNames.add(skill.name);
+				const importedFrom = skill.frontmatter?.xGjcImportedFrom ?? skill.frontmatter?.["x-gjc-imported-from"];
 				records.push({
 					name: skill.name,
 					description: typeof skill.frontmatter?.description === "string" ? skill.frontmatter.description : "",
+					...(typeof importedFrom === "string" ? { importedFrom } : {}),
 					path: skill.discoveryPath ?? skill.path,
 					scope,
 					source,

package/src/gjc-runtime/launch-worktree.ts

@@ -2,6 +2,7 @@ import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { canonicalEnvKey, projectEnvSnapshot } from "@gajae-code/utils/env-file";
 import { shortenPath } from "../tools/render-utils";
 
 export type GjcLaunchWorktreeMode =
@@ -175,6 +176,8 @@ function sanitizePathToken(value: string): string {
  * beside the first.
  */
 const WORKTREE_BUCKET_ENV = "GJC_WORKTREE_DIR";
+/** Captured when this module loads, before a later `chdir` or dotenv delete. */
+const startupWorktreeBucketSnapshot = projectEnvSnapshot();
 /**
  * Expands to the repository directory name.
  *
@@ -210,15 +213,35 @@ export function resolveWorktreeBucketForPath(
 	);
 }
 
+/**
+ * Operator override only. Bun has already copied the project dotenv into the
+ * environment, so a value that matches `projectEnvSnapshot` — a static hit or
+ * a dynamic declaration — must not select the bucket. An operator value the
+ * project does not declare is kept.
+ */
+function trustedWorktreeBucketEnv(env: NodeJS.ProcessEnv): string | undefined {
+	const raw = env[WORKTREE_BUCKET_ENV];
+	if (!raw) return undefined;
+	const snapshot = startupWorktreeBucketSnapshot;
+	const key = canonicalEnvKey(WORKTREE_BUCKET_ENV);
+	const declared = snapshot.values[key];
+	const trimmed = raw.trim();
+	if (declared !== undefined && (snapshot.dynamic.has(key) || declared === raw || declared === trimmed)) {
+		return undefined;
+	}
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
 /**
  * Directory that holds this repository's launch worktrees.
  *
  * A relative override resolves against the repository's parent directory. The default
  * `{repo}/.worktrees` template places managed worktrees inside the repository, while
  * `{repo}.worktrees` adopts an existing sibling bucket. An absolute override is used verbatim.
+ * A project dotenv value is ignored; an operator value the project does not declare is kept.
  */
 function resolveWorktreeBucket(repoRoot: string): string {
-	return resolveWorktreeBucketForPath(repoRoot, process.env[WORKTREE_BUCKET_ENV], os.homedir(), path);
+	return resolveWorktreeBucketForPath(repoRoot, trustedWorktreeBucketEnv(process.env), os.homedir(), path);
 }
 
 function ensureRepositoryBucketIgnored(repoRoot: string, bucketPath: string): void {
@@ -454,6 +477,36 @@ function isWorktreeDirty(worktreePath: string): boolean {
 	return runGit(worktreePath, ["status", "--porcelain"]).length > 0;
 }
 
+/** Porcelain status is clean when the only unique state is commits on this detached HEAD. */
+function isCommitAncestor(cwd: string, ancestor: string, descendant: string): boolean {
+	const result = Bun.spawnSync(["git", "merge-base", "--is-ancestor", ancestor, descendant], {
+		cwd,
+		stdout: "ignore",
+		stderr: "pipe",
+	});
+	if (result.exitCode === 0) return true;
+	if (result.exitCode === 1) return false;
+	const stderr = sanitizeWorktreeDiagnostic(result.stderr.toString().trim());
+	throw new Error(stderr || "git merge-base --is-ancestor failed");
+}
+
+function formatWorktreeDiverged(worktreePath: string, existingHead: string, baseRef: string): string {
+	return [
+		`worktree_diverged:${worktreePath}`,
+		`GJC refused to move detached launch worktree ${existingHead} onto ${baseRef} because that commit is not an ancestor of the source HEAD.`,
+		`Path: ${worktreePath}`,
+		"Checking out the source HEAD would drop that commit from this worktree. Safe remediation: create a branch at HEAD so the commit stays reachable (git branch <name>), then retarget or remove the worktree yourself if a later launch should reuse this path. GJC did not change HEAD.",
+	].join("\n");
+}
+
+function reuseDetachedLaunchHead(plan: GjcLaunchWorktreePlan, existingHead: string, dirty: boolean): void {
+	if (dirty) throw new Error(`worktree_dirty:${plan.worktreePath}`);
+	if (!isCommitAncestor(plan.worktreePath, existingHead, plan.baseRef)) {
+		throw new Error(formatWorktreeDiverged(plan.worktreePath, existingHead, plan.baseRef));
+	}
+	runGit(plan.worktreePath, ["checkout", "--detach", plan.baseRef]);
+}
+
 function resolveOptionalWorktreeName(args: string[], index: number): { name: string | null; nextIndex: number } {
 	const next = args[index + 1];
 	if (!next) return { name: null, nextIndex: index };
@@ -781,8 +834,7 @@ function ensureLaunchWorktreeSync(
 				throw new Error(formatWorktreeTargetMismatch(plan, existingAtPath));
 			}
 			if (existingAtPath.head !== plan.baseRef) {
-				if (dirty) throw new Error(`worktree_dirty:${plan.worktreePath}`);
-				runGit(plan.worktreePath, ["checkout", "--detach", plan.baseRef]);
+				reuseDetachedLaunchHead(plan, existingAtPath.head, dirty);
 				dirty = false;
 			}
 		} else if (existingAtPath.branchRef !== expectedBranchRef) {
@@ -877,8 +929,7 @@ export async function ensureLaunchWorktreeCancellable(
 				throw new Error(formatWorktreeTargetMismatch(plan, existingAtPath));
 			}
 			if (existingAtPath.head !== plan.baseRef) {
-				if (dirty) throw new Error(`worktree_dirty:${plan.worktreePath}`);
-				runGit(plan.worktreePath, ["checkout", "--detach", plan.baseRef]);
+				reuseDetachedLaunchHead(plan, existingAtPath.head, dirty);
 				dirty = false;
 			}
 		} else if (existingAtPath.branchRef !== expectedBranchRef) {

package/src/gjc-runtime/psmux-detect.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
+import { canonicalEnvKey, projectEnvSnapshot } from "@gajae-code/utils/env-file";
 
 /**
  * Windows psmux detection and tmux-binary resolution.
@@ -305,17 +306,40 @@ export interface ResolvedTmuxBinary {
 	viaExplicitOverride: boolean;
 }
 
+const GJC_TMUX_COMMAND_ENV = "GJC_TMUX_COMMAND";
+/** Captured when this module loads, before a later `chdir` or dotenv delete. */
+const startupTmuxCommandSnapshot = projectEnvSnapshot();
+
+/**
+ * Operator override only. Bun has already copied the project dotenv into the
+ * environment, so a value that matches `projectEnvSnapshot` — a static hit or
+ * a dynamic declaration — must not select the binary. An operator value the
+ * project does not declare is kept.
+ */
+function trustedTmuxCommand(env: NodeJS.ProcessEnv): string | undefined {
+	const raw = env[GJC_TMUX_COMMAND_ENV];
+	if (!raw) return undefined;
+	const snapshot = startupTmuxCommandSnapshot;
+	const key = canonicalEnvKey(GJC_TMUX_COMMAND_ENV);
+	const declared = snapshot.values[key];
+	const trimmed = raw.trim();
+	if (declared !== undefined && (snapshot.dynamic.has(key) || declared === raw || declared === trimmed)) {
+		return undefined;
+	}
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
 /**
- * Resolve the tmux command GJC should invoke. Honors the existing
- * GJC_TMUX_COMMAND override; on Windows when no
- * override is set, psmux (installed as psmux, pmux, or tmux) is picked
+ * Resolve the tmux command GJC should invoke. Honors an operator
+ * GJC_TMUX_COMMAND override; a project dotenv value is ignored. On Windows
+ * when no override is set, psmux (installed as psmux, pmux, or tmux) is picked
  * automatically so the default gjc --tmux flow lands on a real multiplexer.
  */
 export function resolveGjcTmuxBinary(options: ResolveGjcTmuxBinaryOptions = {}): ResolvedTmuxBinary {
 	const env = options.env ?? process.env;
 	const platform = options.platform ?? process.platform;
 	const runner = options.runner ?? readSpawnRunner();
-	const explicit = env.GJC_TMUX_COMMAND?.trim();
+	const explicit = trustedTmuxCommand(env);
 	if (explicit) {
 		const isPsmux =
 			platform === "win32"

package/src/gjc-runtime/session-state-sidecar.ts

@@ -22,6 +22,7 @@ import { reduceTerminalReceiptState } from "../sdk/receipt-state";
 import { TOOL_CATALOG } from "../tools/tool-catalog.generated";
 import { sessionRoot, sessionRuntimeDir, sessionRuntimeStatePath } from "./session-layout";
 import { SessionStateLockUnavailableError, withSessionStateFileLock } from "./session-state-lock";
+import { trustedCoordinatorEnv } from "./sidecar-bootstrap-env";
 import {
 	isValidOwnerIntent,
 	lifecyclePaths,
@@ -52,9 +53,9 @@ export const GJC_COORDINATOR_SIDECAR_SIGNATURE_REQUIRED_ENV = "GJC_COORDINATOR_S
  * children. The process environment is deliberately scrubbed synchronously even when the
  * key is malformed, so a rejected launch cannot leak it to descendants.
  */
-const coordinatorSidecarSigningBootstrapUrl = process.env[GJC_COORDINATOR_SIDECAR_BOOTSTRAP_URL_ENV]?.trim();
+const coordinatorSidecarSigningBootstrapUrl = trustedCoordinatorEnv(GJC_COORDINATOR_SIDECAR_BOOTSTRAP_URL_ENV);
 const coordinatorSidecarSigningKeyBootstrap = await (async (): Promise<string | undefined> => {
-	if (!coordinatorSidecarSigningBootstrapUrl) return process.env[GJC_COORDINATOR_SIDECAR_SIGNING_KEY_ENV];
+	if (!coordinatorSidecarSigningBootstrapUrl) return trustedCoordinatorEnv(GJC_COORDINATOR_SIDECAR_SIGNING_KEY_ENV);
 	try {
 		const response = await fetch(coordinatorSidecarSigningBootstrapUrl);
 		if (!response.ok) return undefined;

package/src/gjc-runtime/sidecar-bootstrap-env.ts

@@ -0,0 +1,19 @@
+import { canonicalEnvKey, type ProjectEnvSnapshot, projectEnvSnapshot } from "@gajae-code/utils/env-file";
+
+/**
+ * Operator environment only. A value that matches the project dotenv snapshot
+ * was loaded by Bun from the repository and must not become signing material.
+ */
+export function trustedCoordinatorEnv(
+	name: string,
+	env: NodeJS.ProcessEnv = process.env,
+	snapshot: ProjectEnvSnapshot = projectEnvSnapshot(),
+): string | undefined {
+	const raw = env[name];
+	if (!raw) return undefined;
+	const key = canonicalEnvKey(name);
+	const declared = snapshot.values[key];
+	if (declared !== undefined && (snapshot.dynamic.has(key) || declared === raw)) return undefined;
+	const trimmed = raw.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}

package/src/gjc-runtime/state-writer.ts

@@ -310,19 +310,33 @@ export function stampWorkflowEnvelopeChecksum<T>(value: T, filePath: string, com
 	return envelope as T;
 }
 
-export async function detectWorkflowEnvelopeIntegrityMismatch(
-	filePath: string,
-): Promise<WorkflowEnvelopeIntegrityMismatch | undefined> {
-	const current = await readJsonIfPresent(filePath);
-	if (!current || typeof current !== "object" || Array.isArray(current)) return undefined;
-	const receipt = (current as Record<string, unknown>).receipt;
+export type WorkflowEnvelopeChecksumStatus = "absent" | "match" | "mismatch";
+
+/** Compare a parsed envelope to its writer-stamped `content_sha256`, when one is present. */
+export function workflowEnvelopeChecksumStatus(value: unknown): WorkflowEnvelopeChecksumStatus {
+	const checksum = workflowEnvelopeChecksumPair(value);
+	if (!checksum) return "absent";
+	return checksum.actual === checksum.expected ? "match" : "mismatch";
+}
+
+function workflowEnvelopeChecksumPair(value: unknown): { expected: string; actual: string } | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const receipt = (value as Record<string, unknown>).receipt;
 	if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) return undefined;
 	const checksum = (receipt as Record<string, unknown>).content_sha256;
 	if (!checksum || typeof checksum !== "object" || Array.isArray(checksum)) return undefined;
 	const expected = (checksum as Record<string, unknown>).value;
 	if (typeof expected !== "string" || !expected) return undefined;
-	const actual = workflowEnvelopeContentSha256(current);
-	return actual === expected ? undefined : { path: filePath, expected, actual };
+	return { expected, actual: workflowEnvelopeContentSha256(value) };
+}
+
+export async function detectWorkflowEnvelopeIntegrityMismatch(
+	filePath: string,
+): Promise<WorkflowEnvelopeIntegrityMismatch | undefined> {
+	const current = await readJsonIfPresent(filePath);
+	const checksum = workflowEnvelopeChecksumPair(current);
+	if (!checksum || checksum.actual === checksum.expected) return undefined;
+	return { path: filePath, expected: checksum.expected, actual: checksum.actual };
 }
 
 function safeString(value: unknown): string {