@gajae-code/coding-agent 0.18.12 → 0.19.0

package/src/gjc-runtime/tmux-sessions.ts

@@ -4,6 +4,8 @@ import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { Process } from "@gajae-code/natives";
+import { startupProjectEnvSnapshot } from "@gajae-code/utils/env";
+import { canonicalEnvKey, type ProjectEnvSnapshot, projectEnvSnapshot } from "@gajae-code/utils/env-file";
 import { nativeProcessBindings } from "@gajae-code/utils/native-process";
 import { managedSecurityFailureClassification } from "../session/internal/managed-session-storage";
 import { readLinuxProcStartTime, readLinuxProcStartTimeSync } from "./linux-proc";
@@ -23,6 +25,7 @@ import {
 	GJC_TMUX_OWNER_SERVER_KEY_ENV,
 	GJC_TMUX_OWNER_STATE_DIR_ENV,
 } from "./session-state-sidecar";
+import { trustedCoordinatorEnv } from "./sidecar-bootstrap-env";
 import {
 	assertGjcTmuxMutationAuthoritySync,
 	bindGjcTmuxProviderAuthority,
@@ -247,6 +250,81 @@ export function __setMutationServerProofForTests(
 	mutationServerProofTestDependency = dependency;
 }
 
+const TMUX_LAUNCH_IDENTITY_ENV_NAMES = [
+	"GJC_SESSION_ID",
+	GJC_COORDINATOR_SESSION_ID_ENV,
+	GJC_COORDINATOR_SESSION_STATE_FILE_ENV,
+	"GJC_TMUX_SESSION",
+] as const;
+
+/**
+ * Drop project-dotenv copies of the tmux session name, coordinator id, and
+ * state-file path. A pin is kept only when every snapshot accepts it, so a
+ * declaration Bun loaded before `chdir` is refused even if the launch cwd no
+ * longer contains that file. Acceptance uses the shared helper, but the
+ * original string stays: callers trim at use, and a later check must see the
+ * same value that was accepted.
+ */
+export function trustedTmuxLaunchIdentityEnv(
+	env: NodeJS.ProcessEnv,
+	snapshots: readonly ProjectEnvSnapshot[],
+): NodeJS.ProcessEnv {
+	const denied: string[] = [];
+	for (const name of TMUX_LAUNCH_IDENTITY_ENV_NAMES) {
+		if (!env[name]) continue;
+		for (const snapshot of snapshots) {
+			if (trustedCoordinatorEnv(name, env, snapshot) === undefined) {
+				denied.push(name);
+				break;
+			}
+		}
+	}
+	if (denied.length === 0) return env;
+	const next: NodeJS.ProcessEnv = { ...env };
+	for (const name of denied) delete next[name];
+	return next;
+}
+
+export function tmuxLaunchIdentityEnv(env: NodeJS.ProcessEnv, cwd: string): NodeJS.ProcessEnv {
+	return trustedTmuxLaunchIdentityEnv(env, [projectEnvSnapshot(cwd), startupProjectEnvSnapshot()]);
+}
+
+/**
+ * Session id the launched child must see. A trusted pin is passed through.
+ * A rejected project pin is replaced by the same fallback the launch plan uses
+ * for the session root, which also stops Bun from reloading that dotenv value
+ * (`GJC_TMUX_LAUNCHED=1` skips the planner filter). An omitted id stays omitted.
+ */
+export function resolvedChildGjcSessionId(input: {
+	trusted: string | undefined;
+	inherited: string | undefined;
+	projectDeclared: boolean;
+	fallback: string;
+}): string | undefined {
+	const trusted = input.trusted?.trim();
+	if (trusted) return trusted;
+	if (!input.inherited?.trim() && !input.projectDeclared) return undefined;
+	const fallback = input.fallback.trim();
+	return fallback.length > 0 ? fallback : undefined;
+}
+
+export function childGjcSessionIdAssignment(
+	env: NodeJS.ProcessEnv,
+	identityEnv: NodeJS.ProcessEnv,
+	cwd: string,
+	fallbackSessionId: string,
+): Record<string, string> {
+	const snapshot = projectEnvSnapshot(cwd);
+	const key = canonicalEnvKey("GJC_SESSION_ID");
+	const value = resolvedChildGjcSessionId({
+		trusted: identityEnv.GJC_SESSION_ID,
+		inherited: env.GJC_SESSION_ID,
+		projectDeclared: snapshot.values[key] !== undefined || snapshot.dynamic.has(key),
+		fallback: fallbackSessionId,
+	});
+	return value === undefined ? {} : { GJC_SESSION_ID: value };
+}
+
 function psmuxAuthorityFromEnv(env: NodeJS.ProcessEnv): ProviderAuthority | null {
 	const stateDir = env[GJC_TMUX_OWNER_STATE_DIR_ENV]?.trim();
 	const sessionId = env[GJC_COORDINATOR_SESSION_ID_ENV]?.trim();
@@ -515,11 +593,14 @@ function canonicalProviderStateDirs(cwd: string): string[] {
 }
 
 function psmuxAuthorityEnvironments(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv[] {
-	const explicitAuthority = psmuxAuthorityFromEnv(env);
+	const identityEnv = tmuxLaunchIdentityEnv(env, process.cwd());
+	const explicitAuthority = psmuxAuthorityFromEnv(identityEnv);
 	if (explicitAuthority) return [environmentForProviderAuthority(env, explicitAuthority)];
 	const explicitStateDir =
-		env[GJC_TMUX_OWNER_STATE_DIR_ENV]?.trim() ??
-		(env[GJC_COORDINATOR_SESSION_STATE_FILE_ENV] ? path.dirname(env[GJC_COORDINATOR_SESSION_STATE_FILE_ENV]) : "");
+		identityEnv[GJC_TMUX_OWNER_STATE_DIR_ENV]?.trim() ??
+		(identityEnv[GJC_COORDINATOR_SESSION_STATE_FILE_ENV]
+			? path.dirname(identityEnv[GJC_COORDINATOR_SESSION_STATE_FILE_ENV])
+			: "");
 	const ambient = resolveGjcTmuxBinary({ env });
 	if (gjcTmuxAuthorityPlatform() === "win32") {
 		const ambientAvailable = path.isAbsolute(ambient.command)
@@ -669,17 +750,15 @@ export function createGjcTmuxSession(
 	if (launch && !validManagedLaunchSpec(launch, platform)) throw new Error("gjc_tmux_managed_launch_spec_invalid");
 	const provider = resolveGjcTmuxProviderContext({ env, platform });
 	const tmuxCommand = provider.command;
-	const launchEnvironment = launch ? { ...env, GJC_TMUX_SESSION: launch.childSessionId } : env;
-	const sessionName = buildGjcTmuxSessionName(launchEnvironment);
 	const cwd = launch?.cwd ?? process.cwd();
-	const sessionId = launch?.childSessionId ?? (env[GJC_COORDINATOR_SESSION_ID_ENV]?.trim() || sessionName);
+	const identityEnv = tmuxLaunchIdentityEnv(env, cwd);
+	const launchEnvironment = launch ? { ...identityEnv, GJC_TMUX_SESSION: launch.childSessionId } : identityEnv;
+	const sessionName = buildGjcTmuxSessionName(launchEnvironment);
+	const sessionId = launch?.childSessionId ?? (identityEnv[GJC_COORDINATOR_SESSION_ID_ENV]?.trim() || sessionName);
+	const filteredGjcSessionId = identityEnv.GJC_SESSION_ID?.trim() || sessionId;
 	const stateFile =
-		(!launch ? env[GJC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim() : undefined) ||
-		tmuxRuntimeSessionPath(
-			cwd,
-			launch?.childSessionId ?? (env.GJC_SESSION_ID?.trim() || sessionId),
-			buildGjcTmuxSessionSlug(sessionName),
-		);
+		(!launch ? identityEnv[GJC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim() : undefined) ||
+		tmuxRuntimeSessionPath(cwd, launch?.childSessionId ?? filteredGjcSessionId, buildGjcTmuxSessionSlug(sessionName));
 	const stateDir = (platform === "win32" ? path.win32 : path).dirname(stateFile);
 	const generation = crypto.randomUUID();
 	const authority = bindGjcTmuxProviderAuthority(provider, { stateDir, sessionId, generation });
@@ -690,6 +769,7 @@ export function createGjcTmuxSession(
 		[GJC_TMUX_OWNER_SERVER_KEY_ENV]: tmuxCommand,
 		[GJC_COORDINATOR_SESSION_ID_ENV]: sessionId,
 		[GJC_COORDINATOR_SESSION_STATE_FILE_ENV]: stateFile,
+		...childGjcSessionIdAssignment(env, identityEnv, cwd, filteredGjcSessionId),
 		...(launch
 			? {
 					[MANAGED_OWNER_RUN_ID_ENV]: crypto.randomUUID(),
@@ -699,7 +779,7 @@ export function createGjcTmuxSession(
 			: {}),
 	};
 	const childEnvironment: Record<string, string> = { ...(launch?.env ?? {}), ...managedEnvironment };
-	const executionEnv = { ...env, ...managedEnvironment };
+	const executionEnv = { ...identityEnv, ...managedEnvironment };
 	const shellQuote = (value: string): string => `'${value.replace(/'/g, `'\\''`)}'`;
 	const command =
 		platform === "win32"

package/src/gjc-runtime/ultragoal-change-set.ts

@@ -128,15 +128,30 @@ async function hashAddedFiles(cwd: string, paths: readonly UltragoalChangeSetPat
 
 export async function spawnText(
 	command: string[],
-	options: { cwd: string; timeoutMs?: number },
+	options: { cwd: string; timeoutMs?: number; stdin?: string },
 ): Promise<{ ok: boolean; stdout: string; stderr: string }> {
 	try {
-		const proc = Bun.spawn(command, { cwd: options.cwd, stdout: "pipe", stderr: "pipe" });
+		const proc = Bun.spawn(command, { cwd: options.cwd, stdin: "pipe", stdout: "pipe", stderr: "pipe" });
 		const timeout = setTimeout(() => proc.kill(), options.timeoutMs ?? 5000);
+		// Drain both pipes while the stdin write runs: a child that never reads
+		// stdin blocks the write, and a child that fills stdout before draining
+		// stdin blocks the read.
+		const stdinWrite = (async () => {
+			const stdin = proc.stdin;
+			if (!stdin || options.stdin === undefined) return;
+			try {
+				stdin.write(options.stdin);
+				await stdin.end();
+			} catch {
+				// The child closed stdin or the timer killed it; the exit code
+				// already reports the failure.
+			}
+		})();
 		const [stdoutBytes, stderrBytes, exitCode] = await Promise.all([
 			new Response(proc.stdout).arrayBuffer(),
 			new Response(proc.stderr).arrayBuffer(),
 			proc.exited,
+			stdinWrite,
 		]);
 		clearTimeout(timeout);
 		let stdout: string;
@@ -152,6 +167,37 @@ export async function spawnText(
 	}
 }
 
+/**
+ * Derive the empty tree object ID for the given repository, which depends on the
+ * repository's object format (SHA-1 vs SHA-256). A repository with no commits has
+ * no refs and no merge base, so the empty tree is the only authoritative baseline:
+ * every tracked, staged, and untracked file is an addition on top of it.
+ *
+ * @param cwd The repository root directory
+ * @returns The empty tree object ID (format-specific), or the SHA-1 ID if derivation fails
+ */
+async function getEmptyTreeId(cwd: string): Promise<string> {
+	// Compute the empty tree object ID by hashing an empty tree.
+	// This respects the repository's object format (SHA-1 or SHA-256).
+	const result = await spawnText(["git", "hash-object", "-t", "tree", "--stdin"], {
+		cwd,
+		timeoutMs: 3000,
+		stdin: "", // Empty input for empty tree
+	});
+	if (result.ok && result.stdout.trim()) {
+		return result.stdout.trim();
+	}
+	// Fallback to SHA-1 empty tree ID if derivation fails
+	// (e.g., git command not available, permission denied, etc.)
+	return "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+}
+
+/**
+ * The canonical empty tree object for SHA-1 repositories. Use getEmptyTreeId()
+ * to derive the format-specific ID for a given repository.
+ */
+export const GIT_EMPTY_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+
 export async function resolveGitBase(cwd: string, branch?: string): Promise<string> {
 	if (branch) {
 		const exists = await spawnText(["git", "rev-parse", "--verify", branch], { cwd, timeoutMs: 3000 });
@@ -163,11 +209,31 @@ export async function resolveGitBase(cwd: string, branch?: string): Promise<stri
 		// and mis-attributes other people's changes to this story (e.g. falsely
 		// tripping change-scoped gates). Among existing candidates, pick the one
 		// whose merge-base with HEAD is closest to HEAD (fewest commits ahead).
-		const candidates = ["origin/dev", "dev", "origin/main", "origin/master", "main", "master"];
+		const candidates = [
+			"origin/dev",
+			"dev",
+			"origin/develop",
+			"develop",
+			"origin/main",
+			"origin/master",
+			"main",
+			"master",
+		];
+		const currentBranch = await spawnText(["git", "symbolic-ref", "--quiet", "HEAD"], { cwd, timeoutMs: 3000 });
+		const currentRef = currentBranch.ok ? currentBranch.stdout.trim() : undefined;
 		let best: { ref: string; ahead: number } | undefined;
+
 		for (const candidate of candidates) {
-			const exists = await spawnText(["git", "rev-parse", "--verify", candidate], { cwd, timeoutMs: 3000 });
+			const exists = await spawnText(["git", "rev-parse", "--symbolic-full-name", "--verify", candidate], {
+				cwd,
+				timeoutMs: 3000,
+			});
 			if (!exists.ok) continue;
+			// Exclude only the checked-out local ref, not distinct refs at the same
+			// commit or remote-tracking refs with the same branch name. Comparing
+			// the checked-out ref to HEAD hides committed work as a complete empty
+			// capture; without an independent baseline, resolution must fail closed.
+			if (currentRef && exists.stdout.trim() === currentRef) continue;
 			const mergeBase = await spawnText(["git", "merge-base", "HEAD", candidate], { cwd, timeoutMs: 3000 });
 			if (!mergeBase.ok || !mergeBase.stdout.trim()) continue;
 			const count = await spawnText(["git", "rev-list", "--count", `${mergeBase.stdout.trim()}..HEAD`], {
@@ -285,16 +351,26 @@ export async function computeCheckpointChangeSet(cwd: string): Promise<Ultragoal
 	}
 	const captureWitness = await repositoryStateWitness(cwd);
 	await repositoryStateWitnessTestHook?.("after-initial", cwd);
-	const baseRef = await resolveGitBase(cwd);
+	// A freshly initialized repository has no commits, so `HEAD`, every branch
+	// candidate, and any merge base are unresolvable. The empty tree is the only
+	// authoritative baseline there; refusing outright would strand a run whose
+	// implementation is entirely untracked. Everything on disk then counts as an
+	// addition, which is hashed like any other added file and never committed.
+	const headPresent = await spawnText(["git", "rev-parse", "--verify", "HEAD"], { cwd, timeoutMs: 3000 });
+	const unborn = !headPresent.ok;
+	const baseRef = unborn ? await getEmptyTreeId(cwd) : await resolveGitBase(cwd);
 	const base = baseRef;
-	const mergeBase = await spawnText(["git", "merge-base", "HEAD", baseRef], { cwd, timeoutMs: 3000 });
+	const mergeBase = unborn
+		? { ok: false, stdout: "", stderr: "repository has no commits" }
+		: await spawnText(["git", "merge-base", "HEAD", baseRef], { cwd, timeoutMs: 3000 });
+	const diffRange = unborn ? baseRef : `${base}...HEAD`;
 	const [committed, unstaged, staged, untracked, stat, committedDiff, unstagedDiff, stagedDiff] = await Promise.all([
-		spawnText(["git", "diff", "--name-status", "-z", `${base}...HEAD`], { cwd, timeoutMs: 5000 }),
+		spawnText(["git", "diff", "--name-status", "-z", unborn ? baseRef : diffRange], { cwd, timeoutMs: 5000 }),
 		spawnText(["git", "diff", "--name-status", "-z"], { cwd, timeoutMs: 5000 }),
 		spawnText(["git", "diff", "--cached", "--name-status", "-z"], { cwd, timeoutMs: 5000 }),
 		spawnText(["git", "ls-files", "--others", "--exclude-standard", "-z"], { cwd, timeoutMs: 5000 }),
-		spawnText(["git", "diff", "--stat", `${base}...HEAD`], { cwd, timeoutMs: 5000 }),
-		spawnText(["git", "diff", `${base}...HEAD`], { cwd, timeoutMs: 5000 }),
+		spawnText(["git", "diff", "--stat", diffRange], { cwd, timeoutMs: 5000 }),
+		spawnText(["git", "diff", diffRange], { cwd, timeoutMs: 5000 }),
 		spawnText(["git", "diff"], { cwd, timeoutMs: 5000 }),
 		spawnText(["git", "diff", "--cached"], { cwd, timeoutMs: 5000 }),
 	]);
@@ -382,7 +458,10 @@ async function repositoryStateWitness(cwd: string): Promise<string | undefined>
 		spawnText(["git", "ls-files", "-z"], { cwd, timeoutMs: 5000 }),
 		spawnText(["git", "ls-files", "--others", "--exclude-standard", "-z"], { cwd, timeoutMs: 5000 }),
 	]);
-	if (!head.ok || !status.ok || !tracked.ok || !untracked.ok) return undefined;
+	// An unborn repository has no HEAD yet; the remaining reads still describe its
+	// full state, so witness it as an empty head rather than failing the capture.
+	if (!status.ok || !tracked.ok || !untracked.ok) return undefined;
+	const headToken = head.ok ? head.stdout.trim() : "unborn";
 	const paths = [
 		...new Set([
 			...parseGitUntrackedPaths(tracked.stdout).map(row => row.path),
@@ -417,7 +496,7 @@ async function repositoryStateWitness(cwd: string): Promise<string | undefined>
 	} catch {
 		return undefined;
 	}
-	return `${head.stdout.trim()}\u0000${status.stdout}\u0000sha256:${content.digest("hex")}`;
+	return `${headToken}\u0000${status.stdout}\u0000sha256:${content.digest("hex")}`;
 }
 
 export function parseUnifiedDiffPaths(diff: string): UltragoalChangeSetPath[] {

package/src/gjc-runtime/ultragoal-guard.ts

@@ -25,6 +25,7 @@ import {
 	type UltragoalPlan,
 	type UltragoalReceiptKind,
 } from "./ultragoal-runtime";
+import { readUltragoalSuccessionFence } from "./ultragoal-succession";
 
 export type UltragoalGuardState =
 	| "inactive"
@@ -823,7 +824,14 @@ async function consumeUltragoalNudge(input: {
 	if (!sessionId) return { nudged: false };
 	const plan = await readUltragoalPlan(input.cwd, sessionId);
 	if (!plan) return { nudged: false };
-	const target = selectUltragoalNudgeTarget(plan, { currentGoalObjective: input.currentGoal?.objective });
+	const fence = await readUltragoalSuccessionFence(input.cwd, sessionId);
+	// A goal handed off to a successor run is not this run's resolvable work. Skip
+	// fenced goals while selecting, so a retained source-owned goal can still receive
+	// the nudge (and keep aggregate drop guarded) without spending budget on the handoff.
+	const target = selectUltragoalNudgeTarget(plan, {
+		currentGoalObjective: input.currentGoal?.objective,
+		excludedGoalIds: fence?.selectedGoalIds,
+	});
 	if (!target) return { nudged: false };
 	const { budget } = await resolveUltragoalNudgeBudget(input.cwd, input.agentDir);
 	const outcome = await recordUltragoalNudgeIfBudgetRemaining({

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

@@ -82,6 +82,7 @@ import {
 import {
 	assertUltragoalAdoptionPublished,
 	assertUltragoalGoalNotFenced,
+	readUltragoalSuccessionFence,
 	runUltragoalSuccessionCommand,
 } from "./ultragoal-succession";
 import {
@@ -472,22 +473,27 @@ export async function resolveUltragoalNudgeBudget(
  */
 export function selectUltragoalNudgeTarget(
 	plan: UltragoalPlan,
-	options: { currentGoalObjective?: string; retryFailed?: boolean } = {},
+	options: { currentGoalObjective?: string; retryFailed?: boolean; excludedGoalIds?: readonly string[] } = {},
 ): UltragoalNudgeTarget | null {
 	const objective = options.currentGoalObjective?.trim();
+	const isExcluded = (goalId: string): boolean => options.excludedGoalIds?.includes(goalId) ?? false;
 	if (objective) {
 		const matched = plan.goals.find(
-			goal => goal.objective.trim() === objective && SCHEDULABLE_STATUSES.has(goal.status),
+			goal => goal.objective.trim() === objective && SCHEDULABLE_STATUSES.has(goal.status) && !isExcluded(goal.id),
 		);
 		if (matched) return { goalId: matched.id, targetKind: "story" };
 	}
-	const next = chooseNextGoal(plan, options.retryFailed === true);
+	const schedulableGoals = options.excludedGoalIds?.length
+		? plan.goals.filter(goal => !isExcluded(goal.id))
+		: plan.goals;
+	const next = selectNextSchedulableGoal(schedulableGoals, options.retryFailed === true);
 	if (next) return { goalId: next.id, targetKind: "story" };
 	const completion = getUltragoalRunCompletionState(plan, { retryFailed: options.retryFailed });
 	if (completion.needsFinalAggregateReceipt) {
 		const required = requiredUltragoalGoals(plan);
 		const finalGoal = required.at(-1);
-		if (finalGoal) return { goalId: finalGoal.id, targetKind: "final_aggregate_receipt" };
+		if (finalGoal && !isExcluded(finalGoal.id))
+			return { goalId: finalGoal.id, targetKind: "final_aggregate_receipt" };
 	}
 	return null;
 }
@@ -1125,7 +1131,11 @@ export async function getUltragoalStatus(
 	else if (counts.active > 0) status = "active";
 	else if (counts.failed > 0) status = "failed";
 	else if (counts.blocked > 0 || counts.review_blocked > 0) status = "blocked";
-	const nudgeTarget = selectUltragoalNudgeTarget(plan, { currentGoalObjective: currentGoal?.objective });
+	const fence = await readUltragoalSuccessionFence(cwd, resolvedSessionId);
+	const nudgeTarget = selectUltragoalNudgeTarget(plan, {
+		currentGoalObjective: currentGoal?.objective,
+		excludedGoalIds: fence?.selectedGoalIds,
+	});
 	let nudgeFields: Partial<UltragoalStatusSummary> = {};
 	if (nudgeTarget) {
 		const { budget } = await resolveUltragoalNudgeBudget(cwd, agentDir);

package/src/harness-control-plane/finalize.ts

@@ -14,6 +14,7 @@ import { randomBytes } from "node:crypto";
 import { readdirSync, readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { type LinuxProcPidProbeResult, probeLinuxProcPidSync } from "../gjc-runtime/linux-proc";
+import { checkTmuxSelfInjection } from "../tools/tmux-self-injection-guard";
 import {
 	buildReceipt,
 	type CompletionEvidence,
@@ -558,6 +559,16 @@ export function defaultFinalizeChecks(
 	return {
 		async runValidation(spec, signal) {
 			if (signal?.aborted) throw new ValidationObservationUncertainError(spec.command, workspace, signal.reason);
+			// Same preflight as BashTool: refuse before spawn so a plan command cannot type into this pane.
+			const injection = await checkTmuxSelfInjection(spec.command, {
+				env: process.env,
+				cwd: workspace,
+				executionEnv: process.env,
+			});
+			if (signal?.aborted) throw new ValidationObservationUncertainError(spec.command, workspace, signal.reason);
+			if (injection.block) {
+				return { exactCommand: spec.command, cwd: workspace, exitStatus: 1, pass: false };
+			}
 			let proc: Bun.Subprocess<"ignore", "pipe", "pipe">;
 			try {
 				proc = Bun.spawn(["bash", "-lc", spec.command], {

package/src/harness-control-plane/receipt-spool.ts

@@ -1,6 +1,8 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { constants as fsConstants } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { canonicalEnvKey, loadedProjectEnvSnapshot } from "@gajae-code/utils/dirs";
 import { withFileLock } from "../config/file-lock";
 import type { ReceiptEnvelope } from "./receipts";
 
@@ -21,6 +23,42 @@ export interface ReceiptSpoolAppendResult {
 const receiptSpoolDirStorage = new AsyncLocalStorage<string | undefined>();
 const spoolQueues = new Map<string, Promise<void>>();
 const noop = (): void => undefined;
+const NOFOLLOW = fsConstants.O_NOFOLLOW ?? 0;
+
+/** True only when an exception's `code` is `ENOENT`. Other codes propagate. */
+export function isEnoent(error: unknown): boolean {
+	return (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+/**
+ * Bun copies the cwd dotenv into `process.env` before module init. The startup
+ * project snapshot is the declaration set trusted directory overrides use: a
+ * path that resolves like that declaration, or a dynamic declaration, is not a
+ * spool directory. A shell or `--receipt-spool-dir` value that resolves
+ * somewhere else is kept.
+ */
+function projectDeclaredReceiptSpoolDir(raw: string): boolean {
+	const snapshot = loadedProjectEnvSnapshot();
+	const key = canonicalEnvKey(RECEIPT_SPOOL_DIR_ENV);
+	const projectValue = snapshot.values[key];
+	if (projectValue === undefined) return false;
+	if (snapshot.dynamic.has(key)) return true;
+	const declared = projectValue.trim();
+	const candidate = raw.trim();
+	if (!declared || !candidate) return declared === candidate;
+	return path.resolve(declared) === path.resolve(candidate);
+}
+
+function adoptReceiptSpoolDir(raw: string | undefined): string | undefined {
+	if (raw === undefined || projectDeclaredReceiptSpoolDir(raw)) return undefined;
+	const trimmed = raw.trim();
+	return trimmed ? path.resolve(trimmed) : undefined;
+}
+
+/** A spool directory the startup project snapshot does not declare. */
+export function trustedReceiptSpoolDir(raw: string | undefined): string | undefined {
+	return adoptReceiptSpoolDir(raw);
+}
 
 interface ReceiptSpoolCursorCache {
 	mtimeMs: number;
@@ -44,10 +82,15 @@ export function resetReceiptSpoolCursorCacheForTesting(): void {
 
 async function spoolStat(spoolFile: string): Promise<{ mtimeMs: number; size: number } | undefined> {
 	try {
-		const stats = await fs.stat(spoolFile);
-		return { mtimeMs: stats.mtimeMs, size: stats.size };
+		const handle = await fs.open(spoolFile, fsConstants.O_RDONLY | NOFOLLOW);
+		try {
+			const stats = await handle.stat();
+			return { mtimeMs: stats.mtimeMs, size: stats.size };
+		} finally {
+			await handle.close();
+		}
 	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		if (isEnoent(error)) return undefined;
 		throw error;
 	}
 }
@@ -64,15 +107,17 @@ async function cacheHighestCursor(spoolFile: string, highest: bigint): Promise<v
 export async function withReceiptSpoolDir<T>(spoolDir: string, fn: () => Promise<T>): Promise<T> {
 	const trimmed = spoolDir.trim();
 	if (!trimmed) throw new Error("receipt_spool_dir_empty");
-	const resolved = path.resolve(trimmed);
+	const resolved = adoptReceiptSpoolDir(trimmed);
+	// Owner input repeats process.env. A project-declared directory must not
+	// become the active spool via that copy.
+	if (!resolved) return fn();
 	return receiptSpoolDirStorage.run(resolved, fn);
 }
 
 export function resolveReceiptSpoolDir(env: NodeJS.ProcessEnv = process.env): string | undefined {
 	const active = receiptSpoolDirStorage.getStore();
 	if (active !== undefined) return active;
-	const raw = env[RECEIPT_SPOOL_DIR_ENV]?.trim();
-	return raw ? path.resolve(raw) : undefined;
+	return adoptReceiptSpoolDir(env[RECEIPT_SPOOL_DIR_ENV]);
 }
 
 export function receiptSpoolPath(spoolDir: string): string {
@@ -95,30 +140,56 @@ export function formatReceiptSpoolCursor(cursor: bigint): string {
 
 export async function readHighestReceiptSpoolCursor(spoolDir: string): Promise<bigint> {
 	const spoolFile = receiptSpoolPath(spoolDir);
-	const revision = await spoolStat(spoolFile);
-	if (!revision) {
-		cursorCache.delete(spoolFile);
-		return 0n;
+	let handle: fs.FileHandle;
+	try {
+		handle = await fs.open(spoolFile, fsConstants.O_RDONLY | NOFOLLOW);
+	} catch (error) {
+		if (isEnoent(error)) {
+			cursorCache.delete(spoolFile);
+			return 0n;
+		}
+		throw error;
 	}
-	const cached = cursorCache.get(spoolFile);
-	if (cached && sameSpoolRevision(cached, revision)) return cached.highest;
-
-	fullScanCount++;
-	const raw = await fs.readFile(spoolFile, "utf8");
-	let highest = 0n;
-	for (const line of raw.split("\n")) {
-		const trimmed = line.trim();
-		if (!trimmed) continue;
-		try {
-			const parsed = JSON.parse(trimmed) as { cursor?: unknown };
-			const cursor = parseCursor(parsed.cursor);
-			if (cursor !== undefined && cursor > highest) highest = cursor;
-		} catch {
-			// A crash may leave a torn tail; a full scan ignores it and re-establishes the cache.
+	try {
+		const stats = await handle.stat();
+		const revision = { mtimeMs: stats.mtimeMs, size: stats.size };
+		const cached = cursorCache.get(spoolFile);
+		if (cached && sameSpoolRevision(cached, revision)) return cached.highest;
+
+		fullScanCount++;
+		const raw = await handle.readFile({ encoding: "utf8" });
+		let highest = 0n;
+		for (const line of raw.split("\n")) {
+			const trimmed = line.trim();
+			if (!trimmed) continue;
+			try {
+				const parsed = JSON.parse(trimmed) as { cursor?: unknown };
+				const cursor = parseCursor(parsed.cursor);
+				if (cursor !== undefined && cursor > highest) highest = cursor;
+			} catch {
+				// A crash may leave a torn tail; a full scan ignores it and re-establishes the cache.
+			}
 		}
+		cursorCache.set(spoolFile, { ...revision, highest });
+		return highest;
+	} finally {
+		await handle.close();
+	}
+}
+
+async function tightenSpoolDir(dir: string): Promise<void> {
+	if (process.platform === "win32") return;
+	let handle: fs.FileHandle;
+	try {
+		handle = await fs.open(dir, fsConstants.O_RDONLY | (fsConstants.O_DIRECTORY ?? 0) | NOFOLLOW);
+	} catch {
+		return;
+	}
+	try {
+		await handle.chmod(0o700);
+	} finally {
+		await handle.close();
 	}
-	cursorCache.set(spoolFile, { ...revision, highest });
-	return highest;
 }
 
 async function enqueueSpoolAppend<T>(spoolFile: string, task: () => Promise<T>): Promise<T> {
@@ -142,13 +213,19 @@ export async function appendReceiptToSpool(
 	const spoolFile = receiptSpoolPath(resolvedDir);
 	return enqueueSpoolAppend(spoolFile, async () => {
 		await fs.mkdir(resolvedDir, { recursive: true, mode: 0o700 });
+		await tightenSpoolDir(resolvedDir);
 		return withFileLock(
 			spoolFile,
 			async () => {
 				const cursor = formatReceiptSpoolCursor((await readHighestReceiptSpoolCursor(resolvedDir)) + 1n);
 				const record: ReceiptSpoolRecord = { cursor, envelope };
-				const handle = await fs.open(spoolFile, "a", 0o600);
+				const handle = await fs.open(
+					spoolFile,
+					fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_APPEND | NOFOLLOW,
+					0o600,
+				);
 				try {
+					if (process.platform !== "win32") await handle.chmod(0o600);
 					await handle.writeFile(`${JSON.stringify(record)}\n`, "utf8");
 					await handle.sync();
 				} finally {