@gajae-code/coding-agent 0.8.2 → 0.9.1

package/src/cli/fixture-report.test.ts

@@ -0,0 +1,230 @@
+import { describe, expect, it } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { sessionRoot } from "../gjc-runtime/session-layout";
+import type { TaskTokenLog } from "../task/types";
+import { buildFixtureReport, type LiveRunReportShape, runFixtureReport } from "./fixture-report";
+
+function expectParseReportCompatible(report: LiveRunReportShape, fixtureId: string): void {
+	expect(report.schemaVersion).toBe(1);
+	expect(typeof report.binaryId).toBe("string");
+	expect(report.binaryId.length).toBeGreaterThan(0);
+	expect(report.fixtureId).toBe(fixtureId);
+	for (const value of Object.values(report.totals)) {
+		expect(typeof value).toBe("number");
+		expect(Number.isFinite(value)).toBe(true);
+	}
+	expect(report.receiptArtifactRatio).toBeNull();
+	expect(report.spawnDecisions).toBeNull();
+	expect(report.roi).toBeNull();
+}
+
+describe("fixture report", () => {
+	it("reports empty logs as a schema-v1 null-cache-hit report", () => {
+		const report = buildFixtureReport("empty-fixture", []);
+
+		expectParseReportCompatible(report, "empty-fixture");
+		expect(report.totals).toEqual({
+			turns: 0,
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: 0,
+			cacheWriteTokens: 0,
+			totalTokens: 0,
+		});
+		expect(report.cacheHitRate).toBeNull();
+	});
+
+	it("sums deterministic fixed-fixture raw token buckets without folding cache into input", () => {
+		const logs: TaskTokenLog[] = [
+			{
+				subagentId: "root",
+				agent: "main",
+				turn: 1,
+				at: "2026-01-01T00:00:00.000Z",
+				input: 100,
+				output: 20,
+				cacheRead: 40,
+				cacheWrite: 10,
+				totalTokens: 170,
+				model: "fixture-model",
+			},
+			{
+				subagentId: "1-executor",
+				agent: "executor",
+				turn: 1,
+				at: "2026-01-01T00:00:01.000Z",
+				input: 60,
+				output: 15,
+				cacheRead: 20,
+				cacheWrite: 5,
+				totalTokens: 100,
+				model: "fixture-model",
+			},
+		];
+		const report = buildFixtureReport("fixed-fixture", logs);
+		const inputTokens = logs.reduce((sum, log) => sum + log.input, 0);
+		const outputTokens = logs.reduce((sum, log) => sum + log.output, 0);
+		const cacheReadTokens = logs.reduce((sum, log) => sum + log.cacheRead, 0);
+		const cacheWriteTokens = logs.reduce((sum, log) => sum + log.cacheWrite, 0);
+		const totalTokens = inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens;
+
+		expectParseReportCompatible(report, "fixed-fixture");
+		expect(report.totals).toEqual({
+			turns: logs.length,
+			inputTokens,
+			outputTokens,
+			cacheReadTokens,
+			cacheWriteTokens,
+			totalTokens,
+		});
+		expect(report.cacheHitRate).toBe(cacheReadTokens / (inputTokens + cacheReadTokens));
+	});
+
+	it("emits only parseReport-compatible schema-v1 fields", () => {
+		const report = buildFixtureReport("shape-fixture", [
+			{
+				subagentId: "root",
+				turn: 1,
+				at: "2026-01-01T00:00:00.000Z",
+				input: 0,
+				output: 0,
+				cacheRead: 1,
+				cacheWrite: 0,
+				totalTokens: 1,
+			},
+		]);
+
+		expect(Object.keys(report).sort()).toEqual([
+			"binaryId",
+			"cacheHitRate",
+			"fixtureId",
+			"receiptArtifactRatio",
+			"roi",
+			"schemaVersion",
+			"spawnDecisions",
+			"totals",
+		]);
+		expect(Object.keys(report.totals).sort()).toEqual([
+			"cacheReadTokens",
+			"cacheWriteTokens",
+			"inputTokens",
+			"outputTokens",
+			"totalTokens",
+			"turns",
+		]);
+		expectParseReportCompatible(report, "shape-fixture");
+	});
+});
+
+async function captureRun(fixtureId: string): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+	const originalCwd = process.cwd();
+	const originalStdout = process.stdout.write.bind(process.stdout);
+	const originalStderr = process.stderr.write.bind(process.stderr);
+	let exitCode = 0;
+	let stdout = "";
+	let stderr = "";
+	process.stdout.write = ((chunk: string | Uint8Array): boolean => {
+		stdout += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf-8");
+		return true;
+	}) as typeof process.stdout.write;
+	process.stderr.write = ((chunk: string | Uint8Array): boolean => {
+		stderr += typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf-8");
+		return true;
+	}) as typeof process.stderr.write;
+	try {
+		exitCode = await runFixtureReport(fixtureId);
+		return { stdout, stderr, exitCode };
+	} finally {
+		process.stdout.write = originalStdout;
+		process.stderr.write = originalStderr;
+		process.chdir(originalCwd);
+	}
+}
+
+describe("runFixtureReport CLI degradation", () => {
+	it("exits non-zero without emitting JSON for an unknown fixture id", async () => {
+		await withTempCwd(async () => {
+			const { stdout, stderr, exitCode } = await captureRun("definitely-not-a-real-session-id");
+			expect(exitCode).toBe(1);
+			expect(stdout).toBe("");
+			expect(stderr).toContain("unknown fixture id");
+		});
+	});
+
+	it("reads only the requested session token-log directory", async () => {
+		await withTempCwd(async () => {
+			const firstSession = "fixture-session-a";
+			const secondSession = "fixture-session-b";
+			await writeTokenLog(firstSession, { input: 100, output: 10, cacheRead: 0, cacheWrite: 0, totalTokens: 110 });
+			await writeTokenLog(secondSession, { input: 900, output: 90, cacheRead: 0, cacheWrite: 0, totalTokens: 990 });
+
+			const { stdout, exitCode } = await captureRun(firstSession);
+			const report = JSON.parse(stdout) as LiveRunReportShape;
+
+			expect(exitCode).toBe(0);
+			expect(report.fixtureId).toBe(firstSession);
+			expect(report.totals.totalTokens).toBe(110);
+		});
+	});
+
+	it("emits deterministic PR9 default-candidate fixture reports", async () => {
+		await withTempCwd(async () => {
+			const { stdout, exitCode } = await captureRun("pr9.read-artifact-spill-threshold.after");
+			const report = JSON.parse(stdout) as LiveRunReportShape;
+
+			expect(exitCode).toBe(0);
+			expectParseReportCompatible(report, "pr9.read-artifact-spill-threshold.after");
+			expect(report.totals.totalTokens).toBe(20_100);
+		});
+	});
+
+	it("exits non-zero without emitting JSON for a corrupt token-log", async () => {
+		await withTempCwd(async () => {
+			const id = "corrupt-session";
+			const dir = join(sessionRoot(process.cwd(), id), "token-logs");
+			await mkdir(dir, { recursive: true });
+			await writeFile(join(dir, "token-log.jsonl"), "not json\n{}\n", "utf-8");
+			const { stdout, stderr, exitCode } = await captureRun(id);
+			expect(exitCode).toBe(1);
+			expect(stdout).toBe("");
+			expect(stderr).toContain("failed to build fixture report");
+		});
+	});
+});
+
+async function withTempCwd(fn: (cwd: string) => Promise<void>): Promise<void> {
+	const originalCwd = process.cwd();
+	const dir = await mkdtemp(join(tmpdir(), "gjc-fixture-report-"));
+	process.chdir(dir);
+	try {
+		await fn(dir);
+	} finally {
+		// Restore the real cwd BEFORE removing the temp dir, otherwise the process
+		// is left sitting in a deleted directory and later tests in the same
+		// process fail with ENOENT on relative-path/process.cwd() operations.
+		process.chdir(originalCwd);
+		await rm(dir, { recursive: true, force: true });
+	}
+}
+
+async function writeTokenLog(
+	sessionId: string,
+	metrics: { input: number; output: number; cacheRead: number; cacheWrite: number; totalTokens: number },
+): Promise<void> {
+	const dir = join(sessionRoot(process.cwd(), sessionId), "token-logs");
+	await mkdir(dir, { recursive: true });
+	await writeFile(
+		join(dir, "token-log.jsonl"),
+		`${JSON.stringify({
+			subagentId: "root",
+			agent: "main",
+			turn: 1,
+			at: "2026-01-01T00:00:00.000Z",
+			model: "fixture-model",
+			...metrics,
+		})}\n`,
+		"utf-8",
+	);
+}

package/src/cli/fixture-report.ts

@@ -0,0 +1,171 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { GjcSessionContext } from "../gjc-runtime/session-layout";
+import { resolveGjcSessionForRead, SessionResolutionError } from "../gjc-runtime/session-resolution";
+import { computeTaskTokenMetrics, readTaskTokenLogs } from "../task/token-log";
+import type { TaskTokenLog } from "../task/types";
+
+const LIVE_RUNNER_SCHEMA_VERSION = 1;
+const BINARY_ID = "gjc";
+
+function deterministicLog(
+	input: number,
+	output: number,
+	cacheRead: number,
+	cacheWrite: number,
+	totalTokens: number,
+): TaskTokenLog {
+	return {
+		subagentId: "root",
+		agent: "main",
+		turn: 1,
+		at: "2026-01-01T00:00:00.000Z",
+		input,
+		output,
+		cacheRead,
+		cacheWrite,
+		totalTokens,
+		model: "fixture-model",
+	};
+}
+
+export interface LiveRunReportShape {
+	schemaVersion: 1;
+	binaryId: string;
+	fixtureId: string;
+	totals: {
+		turns: number;
+		inputTokens: number;
+		outputTokens: number;
+		cacheReadTokens: number;
+		cacheWriteTokens: number;
+		totalTokens: number;
+	};
+	cacheHitRate: number | null;
+	receiptArtifactRatio: number | null;
+	spawnDecisions: number | null;
+	roi: number | null;
+}
+
+const DETERMINISTIC_FIXTURES: Record<string, readonly TaskTokenLog[]> = {
+	"fixed-fixture": [
+		{
+			subagentId: "root",
+			agent: "main",
+			turn: 1,
+			at: "2026-01-01T00:00:00.000Z",
+			input: 100,
+			output: 20,
+			cacheRead: 40,
+			cacheWrite: 10,
+			totalTokens: 170,
+			model: "fixture-model",
+		},
+		{
+			subagentId: "1-executor",
+			agent: "executor",
+			turn: 1,
+			at: "2026-01-01T00:00:01.000Z",
+			input: 60,
+			output: 15,
+			cacheRead: 20,
+			cacheWrite: 5,
+			totalTokens: 100,
+			model: "fixture-model",
+		},
+	],
+};
+const DEFAULT_REDUCTION_FIXTURE_LOGS: Record<string, readonly TaskTokenLog[]> = {
+	"pr9.task-recursion.before": [deterministicLog(2400, 420, 600, 200, 3620)],
+	"pr9.task-recursion.after": [deterministicLog(1800, 360, 450, 150, 2760)],
+	"pr9.output-caps.before": [deterministicLog(22_000, 3_200, 0, 0, 25_200)],
+	"pr9.output-caps.after": [deterministicLog(18_000, 2_400, 0, 0, 20_400)],
+	"pr9.max-inline-result-bytes.before": [deterministicLog(48_000, 2_000, 0, 0, 50_000)],
+	"pr9.max-inline-result-bytes.after": [deterministicLog(12_000, 1_600, 0, 0, 13_600)],
+	"pr9.read-artifact-spill-threshold.before": [deterministicLog(96_000, 2_500, 0, 0, 98_500)],
+	"pr9.read-artifact-spill-threshold.after": [deterministicLog(18_000, 2_100, 0, 0, 20_100)],
+	"pr9.maintenance-pruning.before": [deterministicLog(40_000, 2_000, 18_000, 6_000, 66_000)],
+	"pr9.maintenance-pruning.after": [deterministicLog(30_000, 1_800, 10_000, 3_000, 44_800)],
+	"pr9.append-only-provider-expansion.before": [deterministicLog(28_000, 1_700, 8_000, 2_500, 40_200)],
+	"pr9.append-only-provider-expansion.after": [deterministicLog(20_000, 1_700, 14_000, 2_500, 38_200)],
+	"pr9.rpc-compact-deltas.before": [deterministicLog(14_000, 1_200, 6_000, 1_500, 22_700)],
+	"pr9.rpc-compact-deltas.after": [deterministicLog(10_000, 900, 6_200, 1_500, 18_600)],
+};
+
+export function buildFixtureReport(fixtureId: string, logs: readonly TaskTokenLog[]): LiveRunReportShape {
+	const metrics = computeTaskTokenMetrics(logs);
+	return {
+		schemaVersion: LIVE_RUNNER_SCHEMA_VERSION,
+		binaryId: BINARY_ID,
+		fixtureId,
+		totals: {
+			turns: metrics.turns,
+			inputTokens: metrics.inputTokens,
+			outputTokens: metrics.outputTokens,
+			cacheReadTokens: metrics.cacheReadTokens,
+			cacheWriteTokens: metrics.cacheWriteTokens,
+			totalTokens: metrics.totalTokens,
+		},
+		cacheHitRate: logs.length === 0 ? null : metrics.cacheHitRate,
+		receiptArtifactRatio: null,
+		spawnDecisions: null,
+		roi: null,
+	};
+}
+
+export async function runFixtureReport(fixtureId: string): Promise<number> {
+	let resolved: ResolvedFixtureLogs;
+	try {
+		resolved = await resolveFixtureLogs(fixtureId);
+	} catch (error) {
+		// e.g. a corrupt token-log. Fail loudly rather than emitting an all-zero report.
+		process.stderr.write(
+			`failed to build fixture report for ${fixtureId}: ${error instanceof Error ? error.message : String(error)}\n`,
+		);
+		return 1;
+	}
+	if (resolved.kind === "unknown") {
+		// Neither a known deterministic fixture nor a resolvable GJC session. Emit a
+		// bounded error on stderr with a non-zero exit rather than a schema-valid
+		// all-zero report, which a before/after benchmark would misread as "0 tokens".
+		process.stderr.write(`unknown fixture id and no matching GJC session: ${fixtureId}\n`);
+		return 1;
+	}
+	process.stdout.write(JSON.stringify(buildFixtureReport(fixtureId, resolved.logs)));
+	return 0;
+}
+
+type ResolvedFixtureLogs =
+	| { readonly kind: "logs"; readonly logs: readonly TaskTokenLog[] }
+	| { readonly kind: "unknown" };
+
+async function resolveFixtureLogs(fixtureId: string): Promise<ResolvedFixtureLogs> {
+	const deterministic = DETERMINISTIC_FIXTURES[fixtureId] ?? DEFAULT_REDUCTION_FIXTURE_LOGS[fixtureId];
+	if (deterministic) return { kind: "logs", logs: deterministic };
+	let session: GjcSessionContext;
+	try {
+		session = await resolveGjcSessionForRead(process.cwd(), {
+			flagValue: fixtureId,
+			envSessionId: process.env.GJC_SESSION_ID,
+		});
+	} catch (error) {
+		if (error instanceof SessionResolutionError) return { kind: "unknown" };
+		throw error;
+	}
+	// resolveGjcSessionForRead accepts any explicit flagValue as a session id
+	// without checking the dir exists, so a typo would otherwise yield a
+	// schema-valid all-zero report. Require the session root to exist; a real
+	// session with no turns yet still reads as a legitimate empty log set.
+	if (!(await directoryExists(session.sessionRoot))) return { kind: "unknown" };
+	const logs = await readTaskTokenLogs(path.join(session.sessionRoot, "token-logs"));
+	return { kind: "logs", logs };
+}
+
+async function directoryExists(dir: string): Promise<boolean> {
+	try {
+		const stat = await fs.stat(dir);
+		return stat.isDirectory();
+	} catch {
+		return false;
+	}
+}

package/src/cli/nofile-limit.ts

@@ -0,0 +1,48 @@
+import { execFileSync } from "node:child_process";
+
+export const RECOMMENDED_MACOS_NOFILE_LIMIT = 4096;
+
+export function parseNoFileLimit(text: string): number | undefined {
+	const trimmed = text.trim();
+	if (!trimmed || trimmed === "unlimited") return undefined;
+	const value = Number(trimmed);
+	return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+export function buildMacOSNoFileLimitWarning(currentLimit: number): string {
+	return [
+		`Warning: macOS file descriptor limit is low (ulimit -n = ${currentLimit}).`,
+		'GJC and project dev servers can hit EMFILE / "too many open files" while scanning or watching repositories.',
+		"For this terminal session, run:",
+		`  ulimit -n ${RECOMMENDED_MACOS_NOFILE_LIMIT}`,
+		"If your shell refuses that value, raise the per-user launchd limit and restart the terminal:",
+		`  sudo launchctl limit maxfiles ${RECOMMENDED_MACOS_NOFILE_LIMIT} 65536`,
+		"Avoid using huge values such as 2147483646 on macOS; they are commonly rejected or clamped.",
+		"Set GJC_SKIP_NOFILE_CHECK=1 to silence this preflight warning.",
+	].join("\n");
+}
+
+export interface WarnIfMacOSNoFileLimitTooLowDeps {
+	platform?: NodeJS.Platform;
+	env?: NodeJS.ProcessEnv;
+	execFileSync?: typeof execFileSync;
+	writeStderr?: (text: string) => void;
+}
+
+export function warnIfMacOSNoFileLimitTooLow(deps: WarnIfMacOSNoFileLimitTooLowDeps = {}): void {
+	const platform = deps.platform ?? process.platform;
+	if (platform !== "darwin") return;
+	const env = deps.env ?? process.env;
+	if (env.GJC_SKIP_NOFILE_CHECK === "1" || env.GJC_SKIP_NOFILE_CHECK === "true") return;
+
+	const run = deps.execFileSync ?? execFileSync;
+	let currentLimit: number | undefined;
+	try {
+		currentLimit = parseNoFileLimit(run("/bin/sh", ["-lc", "ulimit -n"], { encoding: "utf8" }));
+	} catch {
+		return;
+	}
+	if (currentLimit === undefined || currentLimit >= RECOMMENDED_MACOS_NOFILE_LIMIT) return;
+	const write = deps.writeStderr ?? (text => process.stderr.write(text));
+	write(`${buildMacOSNoFileLimitWarning(currentLimit)}\n`);
+}

package/src/cli/notify-cli.ts

@@ -249,18 +249,18 @@ export async function promptForToken(
 }
 
 const THREADED_ENABLED_SUCCESS =
-	"Telegram Threaded Mode capability verified for this bot. GJC will request a private-chat topic per session; if Telegram ever refuses topic creation, notifications fall back to this flat chat with a one-time nudge.\n";
+	"Telegram Threaded Mode capability verified for this bot. GJC will request a private-chat topic per session; if Telegram ever refuses topic creation, notifications fall back to this flat chat with inline ask buttons only and a one-time Threaded Mode nudge.\n";
 
 const THREADED_MISSING_WARNING =
-	"Warning: Telegram getMe did not include has_topics_enabled, so GJC cannot verify private-chat Threaded Mode capability for this bot. Setup will continue; update Telegram/Bot API support or re-run setup if per-session topics fail.\n";
+	"Warning: Telegram getMe did not include has_topics_enabled, so GJC cannot verify private-chat Threaded Mode capability for this bot. Setup will continue; flat private-chat fallback supports outbound notifications and inline ask buttons only. Free-text replies and session commands require Threaded Mode/topic routing.\n";
 
 const THREADED_NONINTERACTIVE_WARNING =
-	"Warning: Telegram Threaded Mode capability is OFF for this bot. Setup will be saved because this run is non-interactive, but per-session Telegram delivery may fail closed until the bot owner enables Threaded Mode in @BotFather. GJC cannot enable it through the Bot API.\n";
+	"Warning: Telegram Threaded Mode capability is OFF for this bot. Setup will be saved because this run is non-interactive. Flat private-chat fallback supports outbound notifications and inline ask buttons only; free-text replies and session commands require enabling Threaded Mode in @BotFather > Bot Settings > Threads Settings.\n";
 
 const THREADED_DISABLED_GUIDANCE =
 	"Telegram Threaded Mode is OFF for this bot. GJC needs Telegram private-chat topics so each session can use its own thread.\n" +
-	"GJC cannot enable this through the Bot API. Open @BotFather, select this bot, enable Threaded Mode / forum topics for private chats, then return here.\n" +
-	"Telegram may require an additional Stars purchase fee for private-chat topics.\n";
+	"GJC cannot enable this through the Bot API. Open @BotFather > Bot Settings > Threads Settings for this bot, enable Threaded Mode / forum topics for private chats, then return here.\n" +
+	"Without Threaded Mode, flat private-chat fallback supports outbound notifications and inline ask buttons only; free-text replies and session commands require topic routing.\n";
 
 const THREADED_DISABLED_PROMPT =
 	"Press Enter after enabling Threaded Mode, or type skip to finish setup with a warning: ";
@@ -270,7 +270,7 @@ const THREADED_STILL_OFF = "Telegram still reports Threaded Mode OFF for this bo
 const THREADED_RETRY_PROMPT = "Press Enter to check again, or type skip to finish setup with a warning: ";
 
 const THREADED_SKIP_WARNING =
-	"Warning: continuing without verified Telegram Threaded Mode capability. Setup will be saved, but per-session Telegram delivery may fail closed until Threaded Mode is enabled in BotFather.\n";
+	"Warning: continuing without verified Telegram Threaded Mode capability. Setup will be saved. Flat private-chat fallback supports outbound notifications and inline ask buttons only; free-text replies and session commands require enabling Threaded Mode in BotFather.\n";
 
 const THREADED_INVALID_INPUT = "Type Enter to retry or skip to continue with a warning.\n";
 
@@ -500,8 +500,10 @@ ${chalk.bold("Examples:")}
 
 ${chalk.bold("Threaded Mode:")}
   GJC uses Telegram private-chat topics for per-session threads. Setup verifies the bot
-  capability via getMe.has_topics_enabled. If it is off, enable Threaded Mode in @BotFather;
-  bots cannot toggle it through the Bot API. If Telegram refuses topic creation at runtime,
-  GJC delivers flat to the paired private chat and nudges you to enable Threaded Mode.
+  capability via getMe.has_topics_enabled. Enable Threaded Mode in @BotFather > Bot Settings
+  > Threads Settings; bots cannot toggle it through the Bot API. If Telegram refuses topic
+  creation at runtime, GJC delivers flat to the paired private chat with outbound notifications
+  and inline ask buttons only, then nudges you to enable Threaded Mode for free-text replies
+  and session commands.
 `);
 }

package/src/cli/update-cli.ts

@@ -552,31 +552,107 @@ async function updateViaNpm(packageName: string, expectedVersion: string): Promi
 }
 
 /**
- * Download a release binary to a target path, replacing an existing file.
+ * Flush a freshly written file's data to stable storage.
+ *
+ * Critical on network filesystems (e.g. NFS home directories): `pipeline`
+ * resolving does not guarantee the downloaded bytes are durable on the
+ * server, so the post-install `gjc --version` check can exec a binary whose
+ * pages are not yet consistent. The child then faults, the version check
+ * fails, and the update is rolled back with "could not verify updated
+ * version" even though the download itself succeeded. Explicitly fsyncing
+ * before the rename/exec avoids the race.
  */
-async function updateViaBinaryAt(targetPath: string, expectedVersion: string): Promise<void> {
-	const binaryName = getBinaryName();
-	const url = buildReleaseBinaryUrl(expectedVersion);
+async function fsyncFile(filePath: string): Promise<void> {
+	const handle = await fs.promises.open(filePath, "r+");
+	try {
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
 
-	const tempPath = `${targetPath}.new`;
-	const backupPath = `${targetPath}.bak`;
-	console.log(chalk.dim(`Downloading ${binaryName}…`));
+export async function fsyncFileForTest(filePath: string): Promise<void> {
+	return fsyncFile(filePath);
+}
 
+/**
+ * Download a release binary to a temp path, throwing a friendly error when the
+ * release asset cannot be fetched.
+ */
+async function downloadBinaryTo(url: string, tempPath: string, binaryName: string): Promise<void> {
 	const response = await fetch(url, { redirect: "follow" });
 	if (!response.ok || !response.body) {
 		throw new Error(formatBinaryDownloadFailureMessage(binaryName, url, response.statusText || response.status));
 	}
 	const fileStream = fs.createWriteStream(tempPath, { mode: 0o755 });
 	await pipeline(response.body, fileStream);
+}
+
+/** Injectable steps of the binary update flow (seams for testing ordering). */
+export interface BinaryUpdateFlow {
+	download(url: string, tempPath: string): Promise<void>;
+	fsync(filePath: string): Promise<void>;
+	replace(options: BinaryReplacementOptions): Promise<InstalledVersionVerification>;
+	verifyInstalledVersion(expectedVersion: string): Promise<InstalledVersionVerification>;
+	/** Best-effort cleanup of the temp file when the flow aborts before replace. */
+	removeTemp?(filePath: string): Promise<void>;
+	/** Called once fsync has succeeded, right before replacement begins. */
+	beforeReplace?(): void;
+}
 
-	console.log(chalk.dim("Installing update..."));
-	const verification = await replaceBinaryForUpdate({
+/**
+ * Orchestrate download → fsync → replace → verify with a strict ordering
+ * contract: the downloaded temp binary MUST be flushed to stable storage
+ * before it is published (renamed into place) or exec'd for verification.
+ *
+ * If fsync fails the temp bytes are not durable, so we abort before
+ * replacement/verification and clean up the temp file rather than installing a
+ * possibly-truncated binary.
+ */
+export async function runBinaryUpdateFlow(
+	targetPath: string,
+	url: string,
+	expectedVersion: string,
+	flow: BinaryUpdateFlow,
+): Promise<InstalledVersionVerification> {
+	const tempPath = `${targetPath}.new`;
+	const backupPath = `${targetPath}.bak`;
+
+	await flow.download(url, tempPath);
+	try {
+		await flow.fsync(tempPath);
+	} catch (err) {
+		if (flow.removeTemp) await flow.removeTemp(tempPath);
+		throw err;
+	}
+
+	flow.beforeReplace?.();
+	return flow.replace({
 		targetPath,
 		tempPath,
 		backupPath,
 		expectedVersion,
+		verifyInstalledVersion: flow.verifyInstalledVersion,
+	});
+}
+
+/**
+ * Download a release binary to a target path, replacing an existing file.
+ */
+async function updateViaBinaryAt(targetPath: string, expectedVersion: string): Promise<void> {
+	const binaryName = getBinaryName();
+	const url = buildReleaseBinaryUrl(expectedVersion);
+	console.log(chalk.dim(`Downloading ${binaryName}…`));
+
+	const verification = await runBinaryUpdateFlow(targetPath, url, expectedVersion, {
+		download: (downloadUrl, tempPath) => downloadBinaryTo(downloadUrl, tempPath, binaryName),
+		fsync: fsyncFile,
+		replace: replaceBinaryForUpdate,
 		verifyInstalledVersion: verifyInstalledRuntime,
+		removeTemp: unlinkIfExists,
+		beforeReplace: () => console.log(chalk.dim("Installing update...")),
 	});
+
 	printVerifiedVersion(expectedVersion);
 	if (verification.cleanupWarning) console.warn(chalk.yellow(verification.cleanupWarning));
 	printRestartGuidance();

package/src/cli.ts

@@ -6,6 +6,7 @@
  */
 import { Args, type CliConfig, Command, type CommandEntry, Flags, run } from "@gajae-code/utils/cli";
 import { APP_NAME, formatBunRuntimeError, MIN_BUN_VERSION, VERSION } from "@gajae-code/utils/dirs";
+import { runFixtureReport } from "./cli/fixture-report";
 
 if (Bun.semver.order(Bun.version, MIN_BUN_VERSION) < 0) {
 	process.stderr.write(
@@ -76,6 +77,9 @@ async function installRuntimeGlobals(): Promise<void> {
 	// `HTTP2Unsupported`. See @gajae-code/ai/utils/h2-fetch for details.
 	installH2Fetch();
 
+	const { warnIfMacOSNoFileLimitTooLow } = await import("./cli/nofile-limit");
+	warnIfMacOSNoFileLimitTooLow();
+
 	// Strip macOS malloc-stack-logging env vars before any subprocess is spawned.
 	// Otherwise every child bun process (subagents, plugin installs, ptree spawns,
 	// etc.) prints a `MallocStackLogging: can't turn off …` warning to stderr.
@@ -96,6 +100,17 @@ async function runNotifyDaemonInternalFastPath(argv: string[]): Promise<void> {
 	await runNotifyCommand(cmd);
 }
 
+function rootFixtureArg(argv: string[]): { present: boolean; id: string | undefined } {
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		// Stop at the first subcommand token so a `--fixture` flag belonging to a
+		// subcommand never hijacks the root fast-path into fixture-report mode.
+		if (isSubcommand(arg)) return { present: false, id: undefined };
+		if (arg === "--fixture") return { present: true, id: argv[i + 1] };
+	}
+	return { present: false, id: undefined };
+}
+
 function hasRootFastFlag(argv: string[], flags: readonly string[]): boolean {
 	for (const arg of argv) {
 		if (isSubcommand(arg)) return false;
@@ -233,6 +248,17 @@ export async function runCli(argv: string[]): Promise<void> {
 		await runSmokeTest();
 		return;
 	}
+	const fixtureArg = rootFixtureArg(argv);
+	if (fixtureArg.present) {
+		const id = fixtureArg.id;
+		if (!id || id.startsWith("-")) {
+			process.stderr.write(`${APP_NAME} --fixture requires a fixture id\n`);
+			process.exitCode = 1;
+			return;
+		}
+		process.exitCode = await runFixtureReport(id);
+		return;
+	}
 	if (hasRootHelpFlag(argv)) {
 		const { renderRootHelp } = await import("@gajae-code/utils/cli");
 		const { getExtraHelpText } = await import("./cli/fast-help");

package/src/commands/contribution-prep.ts

@@ -1,5 +1,4 @@
 import { Command, Flags } from "@gajae-code/utils/cli";
-import { prepareContributionPrep } from "../session/contribution-prep";
 
 function writeText(lines: string[]): void {
 	process.stdout.write(`${lines.join("\n")}\n`);
@@ -19,6 +18,7 @@ export default class ContributionPrep extends Command {
 
 	async run(): Promise<void> {
 		const { flags } = await this.parse(ContributionPrep);
+		const { prepareContributionPrep } = await import("../session/contribution-prep");
 		const cwd = process.cwd();
 		const result = await prepareContributionPrep(
 			{