@gajae-code/coding-agent 0.18.7 → 0.18.9

package/src/gjc-runtime/deep-interview-stage.ts

@@ -14,6 +14,7 @@ import {
 } from "./deep-interview-state";
 import { sessionStateDir } from "./session-layout";
 import { resolveGjcSessionForWrite, SessionResolutionError, writeSessionActivityMarker } from "./session-resolution";
+import { migrateWorkflowState } from "./state-migrations";
 import { runNativeStateCommand } from "./state-runtime";
 import {
 	persistedStateRevision,
@@ -184,7 +185,12 @@ const RUNTIME_OWNED_ENVELOPE_KEYS = [
  * `invalid intent contract`, bricking the interview until a destructive
  * `clear --force`. The recorder is the only writer that can lock intent.
  */
-const RECORDER_OWNED_STATE_KEYS = ["intent_contract", "intent_review"] as const;
+const RUNTIME_OWNED_STATE_KEYS = [
+	"intent_contract",
+	"intent_review",
+	"execution_approval",
+	"execution_approval_receipt",
+] as const;
 
 /**
  * Remove sanitizer-owned keys from a staged payload and classify the
@@ -213,7 +219,7 @@ function sanitizeStagedPayload(payload: Record<string, unknown>): {
 	}
 	if (isPlainObject(next.state)) {
 		const state = { ...(next.state as Record<string, unknown>) };
-		for (const key of RECORDER_OWNED_STATE_KEYS) {
+		for (const key of RUNTIME_OWNED_STATE_KEYS) {
 			if (key in state) {
 				delete state[key];
 				ignoredKeys.push(`state.${key}`);
@@ -231,11 +237,11 @@ function sanitizeStagedPayload(payload: Record<string, unknown>): {
 }
 
 /**
- * Self-heal a poisoned merge base: a persisted `state.intent_contract` that
- * fails canonical validation can only come from a pre-guard poisoned write
- * (the recorder always persists valid manifests). Left in place it makes
- * every merge throw, bricking the interview. Drop it (and any equally
- * unverifiable intent_review) from the base and report the repair.
+ * Validate a persisted `state.intent_contract`: if it fails canonical validation
+ * and `intent_contract_required === true`, the contract is locked and must be valid.
+ * Fail closed with an integrity error to preserve the invalid contract for recovery/audit.
+ * When intent_contract_required is absent or false, healing may occur for backward
+ * compatibility with pre-guard poisoned writes, but only after explicit authorization.
  */
 function healPoisonedIntentContract(base: Record<string, unknown>): {
 	base: Record<string, unknown>;
@@ -247,7 +253,16 @@ function healPoisonedIntentContract(base: Record<string, unknown>): {
 	try {
 		assertDeepInterviewIntentManifest(state.intent_contract);
 		return { base, healed: false };
-	} catch {
+	} catch (error) {
+		// If intent_contract_required is set (locked contract), fail closed
+		if (state.intent_contract_required === true) {
+			throw new DeepInterviewStageError(
+				"DI_STAGE_STATE_CORRUPT",
+				`locked intent contract is malformed or tampered: ${error instanceof Error ? error.message : String(error)}`,
+				"preserve the state for recovery; contact support with the session state for audit",
+			);
+		}
+		// For unlocked contracts, continue with healing for backward compatibility
 		const healedState = { ...state };
 		delete healedState.intent_contract;
 		delete healedState.intent_review;
@@ -371,7 +386,7 @@ async function readCurrentState(cwd: string, sessionId: string): Promise<Current
 	if (read.kind === "absent")
 		return { value: {}, revision: 0, sha256: workflowEnvelopeContentSha256({}), exists: false };
 	return {
-		value: read.value,
+		value: migrateWorkflowState(read.value, "deep-interview").state,
 		revision: persistedStateRevision(read.value),
 		sha256: workflowEnvelopeContentSha256(read.value),
 		exists: true,
@@ -430,6 +445,11 @@ function computeMergedEnvelope(
 	draft: DeepInterviewStageDraft,
 	nowIso: string,
 ): Record<string, unknown> {
+	if (current.active === false)
+		throw new DeepInterviewStageError(
+			"DI_STAGE_MERGE_REJECTED",
+			"cannot stage after deep-interview handoff or completion",
+		);
 	// A poisoned (unverifiable) intent contract in the persisted base would make
 	// every merge throw forever; heal it instead of bricking the interview.
 	const { base: healedCurrent, healed } = healPoisonedIntentContract(current);
@@ -454,6 +474,39 @@ function computeMergedEnvelope(
 	// one-fact patch cannot erase confirmed/disputed history (#3387 finding 2).
 	const mergedState = isPlainObject(merged.state) ? (merged.state as Record<string, unknown>) : undefined;
 	const priorState = isPlainObject(current.state) ? (current.state as Record<string, unknown>) : undefined;
+	if (priorState?.crystal === undefined && mergedState?.crystal !== undefined)
+		throw new DeepInterviewStageError(
+			"DI_STAGE_MERGE_REJECTED",
+			"staged apply cannot introduce canonical Crystal state",
+		);
+	if (priorState?.crystal !== undefined) {
+		if (!mergedState || JSON.stringify(mergedState.crystal) !== JSON.stringify(priorState.crystal))
+			throw new DeepInterviewStageError(
+				"DI_STAGE_MERGE_REJECTED",
+				"canonical crystallized state cannot be replaced or deleted through staged apply",
+			);
+		if (mergedState.execution_approval !== priorState.execution_approval)
+			throw new DeepInterviewStageError(
+				"DI_STAGE_MERGE_REJECTED",
+				"crystallized execution approval is immutable through staged apply",
+			);
+		if (
+			JSON.stringify(mergedState.execution_approval_receipt) !==
+			JSON.stringify(priorState.execution_approval_receipt)
+		)
+			throw new DeepInterviewStageError(
+				"DI_STAGE_MERGE_REJECTED",
+				"crystallized execution approval provenance is immutable through staged apply",
+			);
+		for (const field of ["spec_path", "spec_sha256", "spec_slug", "spec_stage"] as const)
+			if (merged[field] !== current[field])
+				throw new DeepInterviewStageError(
+					"DI_STAGE_MERGE_REJECTED",
+					`crystallized ${field} is immutable through staged apply`,
+				);
+	}
+	if (mergedState?.crystal && isPlainObject(mergedState.crystal) && mergedState.crystal.lifecycle !== "ready")
+		merged.current_phase = "interviewing";
 	if (mergedState && priorState && Array.isArray(priorState.established_facts)) {
 		mergedState.established_facts = mergeEstablishedFacts(
 			priorState.established_facts,
@@ -461,6 +514,24 @@ function computeMergedEnvelope(
 		);
 	}
 	merged = deriveRuntimeAmbiguity(merged, current);
+	if (isPlainObject(priorState?.crystal) && priorState.crystal.lifecycle === "ready") {
+		for (const field of [
+			"rounds",
+			"established_facts",
+			"intent_review",
+			"current_ambiguity",
+			"topology",
+			"auto_answered_rounds",
+		] as const)
+			if (
+				JSON.stringify((merged.state as Record<string, unknown> | undefined)?.[field]) !==
+				JSON.stringify(priorState[field])
+			)
+				throw new DeepInterviewStageError(
+					"DI_STAGE_MERGE_REJECTED",
+					"ready Crystal evidence is immutable through staged apply",
+				);
+	}
 	try {
 		assertDeepInterviewEnvelopeInputLimits(merged);
 	} catch (error) {
@@ -851,6 +922,14 @@ async function handleWrite(args: readonly string[], cwd: string): Promise<Record
 				);
 			}
 			const current = await readCurrentState(cwd, sessionId);
+			const currentInner = isPlainObject(current.value.state) ? current.value.state : {};
+			if (reset && currentInner.crystal !== undefined) {
+				throw new DeepInterviewStageError(
+					"DI_STAGE_MERGE_REJECTED",
+					"reset cannot rewrite canonical Crystal state",
+					"clear the workflow explicitly or continue through the approval and handoff lifecycle",
+				);
+			}
 			const nowIso = new Date().toISOString();
 			const syntheticDraft: DeepInterviewStageDraft = {
 				version: DRAFT_VERSION,
@@ -862,17 +941,15 @@ async function handleWrite(args: readonly string[], cwd: string): Promise<Record
 				payload,
 				created_at: nowIso,
 			};
-			// --reset replaces: merge against an empty base but re-lock the intent
-			// contract from prior state through the merge's own immutability guard.
-			const base = reset
-				? (() => {
-						const priorState = isPlainObject(current.value.state)
-							? (current.value.state as Record<string, unknown>)
-							: {};
-						return priorState.intent_contract !== undefined
-							? { state: { intent_contract: priorState.intent_contract, intent_contract_required: true } }
-							: {};
-					})()
+			// Canonical Crystal resets are rejected above. Ordinary resets retain only
+			// locked intent, never legacy handoff/spec metadata or execution authority.
+			const base: Record<string, unknown> = reset
+				? {
+						state: {
+							intent_contract: currentInner.intent_contract,
+							intent_contract_required: currentInner.intent_contract_required,
+						},
+					}
 				: current.value;
 			const merged = computeMergedEnvelope(base as Record<string, unknown>, syntheticDraft, nowIso);
 			merged.last_applied_draft_id = syntheticDraft.draft_id;
@@ -930,7 +1007,7 @@ async function syncStageHud(cwd: string, sessionId: string, envelope: Record<str
 		await syncSkillActiveState({
 			cwd,
 			skill: "deep-interview",
-			active: phase !== "complete",
+			active: envelope.active !== false && phase !== "complete",
 			phase,
 			sessionId,
 			source: "gjc-deep-interview-native",

package/src/gjc-runtime/gc-runtime.ts

@@ -30,8 +30,22 @@ import {
 	listCanonicalBlobs,
 	removeCanonicalBlob,
 } from "../session/blob-store";
-import { probeSessionRetirement, retireSessionTranscript } from "../session/session-retirement";
-import { FileSessionStorage } from "../session/session-storage";
+import type { ManagedGcSessionRetirementReceipt } from "../session/internal/managed-gc-retirement-codec";
+import {
+	discoverManagedGcSessionRetirementReceipts,
+	type ManagedScope,
+	resolveManagedGcScopeForRead,
+} from "../session/internal/managed-session-scope";
+import { taskArtifactOwnerLocatorFromTranscriptBytes } from "../session/internal/task-artifact-owner-transcript";
+import {
+	probeSessionRetirement,
+	retireOrphanSessionTranscript,
+	retireSessionTranscript,
+	type SessionRetirementContinuation,
+	type SessionRetirementOutcome,
+} from "../session/session-retirement";
+import { FileSessionStorage, type SessionStorageSnapshot } from "../session/session-storage";
+import { parseFirstJsonlLine } from "../session/session-transcript-header";
 import {
 	collectEmptyDeleteReceipts,
 	type EmptyDeleteGcRecord,
@@ -757,6 +771,11 @@ export interface GcDiskRecord {
 	action: GcDiskAction;
 	reason: string;
 	error?: string;
+	/** Exact incomplete retirement phase surfaced by the owning session adapter. */
+	phase?: "artifacts" | "transcript";
+	task_artifact_owner_retired?: true;
+	task_artifact_owner_payload_retired?: true;
+	task_artifact_owner_namespace_retained?: true;
 	/** Set when `bytes` is a floor because a walk was capped or partially unreadable. */
 	partial?: true;
 	/** Set when this entry was a reclaim candidate that its surface withheld on incomplete evidence. */
@@ -1202,6 +1221,59 @@ async function discoverGcDiskTranscripts(sessionsRoot: string, errors: GcDiskErr
  * Classify (and optionally retire) session transcripts. Returns the transcripts
  * that survived, which is exactly the mark set for the blob sweep.
  */
+function sessionRetirementContinuation(
+	storage: FileSessionStorage,
+	sessionsRoot: string,
+	transcriptPath: string,
+	agentDir: string,
+): SessionRetirementContinuation | undefined {
+	let snapshot: SessionStorageSnapshot;
+	try {
+		snapshot = storage.readSnapshotSync(transcriptPath);
+	} catch {
+		return undefined;
+	}
+	const header = parseFirstJsonlLine(snapshot.bytes);
+	if (header?.type !== "session" || typeof header.id !== "string" || typeof header.cwd !== "string") return undefined;
+	try {
+		if (!taskArtifactOwnerLocatorFromTranscriptBytes(snapshot.bytes, header.id)) return undefined;
+	} catch {
+		return undefined;
+	}
+	const resolved = resolveManagedGcScopeForRead({ cwd: header.cwd, agentDir, sessionsRoot });
+	if (
+		resolved.kind !== "resolved" ||
+		path.resolve(resolved.scope.sessionsRoot) !== path.resolve(sessionsRoot) ||
+		path.resolve(resolved.scope.directoryPath) !== path.resolve(path.dirname(transcriptPath))
+	)
+		return undefined;
+	return { managedScope: resolved.scope };
+}
+
+function orphanRetirementRecord(
+	receipt: ManagedGcSessionRetirementReceipt,
+	now: number,
+	reason: string,
+	withheld = false,
+): GcDiskRecord {
+	const mtimeMs = Number(receipt.transcriptIdentity.mtimeNs / 1_000_000n);
+	const outcome = receipt.taskArtifactOwnerRetirementOutcome;
+	return {
+		surface: "sessions",
+		id: receipt.sessionId,
+		path: receipt.transcriptPath,
+		bytes: 0,
+		age_days: gcDiskAgeDays(now, mtimeMs),
+		action: "keep",
+		reason,
+		...(withheld ? { withheld: true as const } : {}),
+		...(receipt.state === "owner_retired" ? { task_artifact_owner_retired: true as const } : {}),
+		...(outcome?.kind === "payload_retired"
+			? { task_artifact_owner_payload_retired: true as const, task_artifact_owner_namespace_retained: true as const }
+			: {}),
+	};
+}
+
 async function runGcDiskSessions(input: {
 	surface: GcDiskSurfaceReport;
 	transcripts: GcDiskTranscript[];
@@ -1209,8 +1281,35 @@ async function runGcDiskSessions(input: {
 	policy: GcDiskPolicy;
 	now: number;
 	prune: boolean;
+	agentDir: string;
+	errors: GcDiskError[];
 }): Promise<GcDiskTranscript[]> {
-	const { surface, transcripts, references, policy, now, prune } = input;
+	const { surface, transcripts, references, policy, now, prune, agentDir, errors } = input;
+	const storage = new FileSessionStorage();
+	let orphanReceipts: readonly {
+		readonly scope: ManagedScope;
+		readonly receipt: ManagedGcSessionRetirementReceipt;
+	}[] = [];
+	let receiptDiscoveryError: string | undefined;
+	try {
+		const entries = await fsp.readdir(surface.root, { withFileTypes: true });
+		if (entries.some(entry => entry.name.startsWith("v2-"))) {
+			orphanReceipts = (
+				await discoverManagedGcSessionRetirementReceipts({
+					agentDir,
+					sessionsRoot: surface.root,
+				})
+			).filter(
+				item =>
+					!storage.existsSync(item.receipt.transcriptPath) &&
+					!transcripts.some(
+						transcript => path.resolve(transcript.path) === path.resolve(item.receipt.transcriptPath),
+					),
+			);
+		}
+	} catch (error) {
+		if (!isEnoent(error)) receiptDiscoveryError = gcDiskErrorText(error);
+	}
 	const maxAgeMs = policy.sessions_max_age_days * GC_DISK_DAY_MS;
 
 	// The newest transcript in each project directory is the `--continue` resume
@@ -1279,18 +1378,54 @@ async function runGcDiskSessions(input: {
 		}
 	}
 
-	const storage = new FileSessionStorage();
 	if (!prune) {
 		// Dry run must project the prune verdict, not just the policy verdict: the
 		// retention pass re-checks its own preconditions before it may call the
 		// delete authority, and a candidate that fails them is never removable.
 		for (const item of classified) {
 			if (item.record.action !== "would_reclaim") continue;
-			const probe = probeSessionRetirement(storage, surface.root, item.transcript.path);
-			if (probe.kind === "retirable") continue;
-			item.record.action = "keep";
-			item.record.reason = `retention_declined: ${probe.reason}`;
+			try {
+				const continuation = sessionRetirementContinuation(storage, surface.root, item.transcript.path, agentDir);
+				const probe = await probeSessionRetirement(storage, surface.root, item.transcript.path, continuation);
+				if (probe.kind === "retirable") {
+					if (probe.taskArtifactOwnerRetired) item.record.task_artifact_owner_retired = true;
+					if (probe.taskArtifactOwnerPayloadRetired) item.record.task_artifact_owner_payload_retired = true;
+					if (probe.taskArtifactOwnerNamespaceRetained) item.record.task_artifact_owner_namespace_retained = true;
+					continue;
+				}
+				if (probe.kind === "cleanup_pending") {
+					item.record.action = "reclaim_failed";
+					item.record.reason = `retention_incomplete: ${probe.reason}`;
+					item.record.error = probe.reason;
+					if (probe.phase) item.record.phase = probe.phase;
+					if (probe.taskArtifactOwnerRetired) item.record.task_artifact_owner_retired = true;
+					if (probe.taskArtifactOwnerPayloadRetired) item.record.task_artifact_owner_payload_retired = true;
+					if (probe.taskArtifactOwnerNamespaceRetained) item.record.task_artifact_owner_namespace_retained = true;
+					continue;
+				}
+				item.record.action = "keep";
+				item.record.reason = `retention_declined: ${probe.reason}`;
+				if (probe.reason.includes("task_artifact_owner_")) item.record.error = probe.reason;
+			} catch (error) {
+				const message = gcDiskErrorText(error);
+				item.record.action = "keep";
+				item.record.reason = `retention_declined: ${message}`;
+				item.record.error = message;
+				item.record.withheld = true;
+			}
+		}
+		for (const { receipt } of orphanReceipts) {
+			let reason = "transcript_missing_without_verified_retirement";
+			if (!references.complete) reason = `reference_scan_incomplete: ${references.notes.join(", ")}`;
+			else if (references.ids.has(receipt.sessionId)) reason = "referenced_by_live_surface";
+			surface.records.push(orphanRetirementRecord(receipt, now, reason, true));
 		}
+		if (receiptDiscoveryError)
+			errors.push({
+				surface: "sessions",
+				scope: surface.root,
+				message: `managed_gc_retirement_discovery_incomplete: ${receiptDiscoveryError}`,
+			});
 		return classified.filter(item => item.record.action !== "would_reclaim").map(item => item.transcript);
 	}
 
@@ -1304,9 +1439,21 @@ async function runGcDiskSessions(input: {
 			survivors.push(item.transcript);
 			continue;
 		}
-		const outcome = await retireSessionTranscript(storage, surface.root, item.transcript.path);
+		let outcome: SessionRetirementOutcome;
+		try {
+			const continuation = sessionRetirementContinuation(storage, surface.root, item.transcript.path, agentDir);
+			outcome = await retireSessionTranscript(storage, surface.root, item.transcript.path, continuation);
+		} catch (error) {
+			const message = gcDiskErrorText(error);
+			item.record.action = "reclaim_failed";
+			item.record.reason = `retention_failed: ${message}`;
+			item.record.error = message;
+			survivors.push(item.transcript);
+			continue;
+		}
 		if (outcome.kind === "retired") {
 			item.record.action = "reclaimed";
+			if (outcome.taskArtifactOwnerRetired) item.record.task_artifact_owner_retired = true;
 			continue;
 		}
 		if (outcome.kind === "cleanup_pending") {
@@ -1316,13 +1463,61 @@ async function runGcDiskSessions(input: {
 			item.record.action = "reclaim_failed";
 			item.record.reason = `retention_incomplete: ${outcome.reason}`;
 			item.record.error = outcome.reason;
+			if (outcome.phase) item.record.phase = outcome.phase;
+			if (outcome.taskArtifactOwnerRetired) item.record.task_artifact_owner_retired = true;
+			if (outcome.taskArtifactOwnerPayloadRetired) item.record.task_artifact_owner_payload_retired = true;
+			if (outcome.taskArtifactOwnerNamespaceRetained) item.record.task_artifact_owner_namespace_retained = true;
 			survivors.push(item.transcript);
 			continue;
 		}
 		item.record.action = "keep";
 		item.record.reason = `retention_declined: ${outcome.reason}`;
+		if (outcome.reason.includes("task_artifact_owner_")) item.record.error = outcome.reason;
 		survivors.push(item.transcript);
 	}
+	for (const { scope, receipt } of orphanReceipts) {
+		const record = orphanRetirementRecord(
+			receipt,
+			now,
+			!references.complete
+				? `reference_scan_incomplete: ${references.notes.join(", ")}`
+				: references.ids.has(receipt.sessionId)
+					? "referenced_by_live_surface"
+					: "transcript_missing_without_verified_retirement",
+			true,
+		);
+		if (!references.complete || references.ids.has(receipt.sessionId)) {
+			surface.records.push(record);
+			continue;
+		}
+		try {
+			const outcome = await retireOrphanSessionTranscript(storage, surface.root, { managedScope: scope }, receipt);
+			if (outcome.kind === "cleanup_pending") {
+				record.action = "reclaim_failed";
+				record.reason = `retention_incomplete: ${outcome.reason}`;
+				record.error = outcome.reason;
+				if (outcome.phase) record.phase = outcome.phase;
+				if (outcome.taskArtifactOwnerRetired) record.task_artifact_owner_retired = true;
+				if (outcome.taskArtifactOwnerPayloadRetired) record.task_artifact_owner_payload_retired = true;
+				if (outcome.taskArtifactOwnerNamespaceRetained) record.task_artifact_owner_namespace_retained = true;
+			} else {
+				record.reason = outcome.kind === "kept" ? outcome.reason : "transcript_missing_without_verified_retirement";
+				if (outcome.kind === "kept") record.error = outcome.reason;
+			}
+		} catch (error) {
+			const message = gcDiskErrorText(error);
+			record.action = "reclaim_failed";
+			record.reason = `retention_failed: ${message}`;
+			record.error = message;
+		}
+		surface.records.push(record);
+	}
+	if (receiptDiscoveryError)
+		errors.push({
+			surface: "sessions",
+			scope: surface.root,
+			message: `managed_gc_retirement_discovery_incomplete: ${receiptDiscoveryError}`,
+		});
 	return survivors;
 }
 
@@ -2204,6 +2399,8 @@ export async function collectGcDiskReport(input: {
 		policy,
 		now,
 		prune,
+		agentDir,
+		errors,
 	});
 	await runGcDiskBlobs({
 		surface: surfaces.blobs,

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.
  *
@@ -205,19 +208,40 @@ export function resolveWorktreeBucketForPath(
 	const template = expandHomePrefix(configured || DEFAULT_WORKTREE_BUCKET, home, pathApi);
 	return pathApi.resolve(
 		pathApi.dirname(repoRoot),
-		template.replaceAll(REPO_NAME_PLACEHOLDER, pathApi.basename(repoRoot)),
+		// Function replacer so a `$` in the repository directory name is kept verbatim.
+		template.replaceAll(REPO_NAME_PLACEHOLDER, () => pathApi.basename(repoRoot)),
 	);
 }
 
+/**
+ * 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 {
@@ -453,12 +477,51 @@ 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 };
-	if (next === "--") return { name: null, nextIndex: index };
-	if (next.startsWith("-")) return { name: null, nextIndex: index };
-	return { name: next.trim() || null, nextIndex: index + 1 };
+	if (next === "--" || next.startsWith("-")) return { name: null, nextIndex: index };
+	// A bare --worktree is the detached selector. Only consume the following
+	// positional token as a branch name when it is a valid ref; otherwise it is
+	// the launch prompt and must remain in the forwarded arguments.
+	const trimmed = next.trim();
+	if (!trimmed || /\s/.test(trimmed)) return { name: null, nextIndex: index };
+	const valid =
+		Bun.spawnSync(["git", "check-ref-format", "--branch", trimmed], {
+			stdout: "ignore",
+			stderr: "ignore",
+		}).exitCode === 0;
+	return valid ? { name: trimmed, nextIndex: index + 1 } : { name: null, nextIndex: index };
 }
 
 export function parseLaunchWorktreeMode(args: string[]): ParsedLaunchWorktreeMode {
@@ -771,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) {
@@ -867,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"