@sayknow-cli/coding-agent 0.3.7 → 0.3.9

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 { SkcSessionContext } from "../skc-runtime/session-layout";
+import { resolveSkcSessionForRead, SessionResolutionError } from "../skc-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 = "skc";
+
+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 SKC 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 SKC 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: SkcSessionContext;
+	try {
+		session = await resolveSkcSessionForRead(process.cwd(), {
+			flagValue: fixtureId,
+			envSessionId: process.env.SKC_SESSION_ID,
+		});
+	} catch (error) {
+		if (error instanceof SessionResolutionError) return { kind: "unknown" };
+		throw error;
+	}
+	// resolveSkcSessionForRead 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}).`,
+		'SKC 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 SKC_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.SKC_SKIP_NOFILE_CHECK === "1" || env.SKC_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

@@ -4,7 +4,7 @@
  * Handles `skc notify` setup/status and the hidden daemon entrypoint.
  */
 import { createInterface } from "node:readline/promises";
-import { APP_NAME } from "@sayknow-cli/utils";
+import { APP_NAME } from "@sayknow-cli/utils/dirs";
 import chalk from "chalk";
 import type { Settings } from "../config/settings";
 import { getNotificationConfig, maskToken } from "../notifications/config";
@@ -58,6 +58,11 @@ interface TelegramUser {
 	allows_users_to_create_topics?: boolean;
 }
 
+interface TelegramChat {
+	id?: number | string;
+	type?: string;
+}
+
 type ThreadedModeState = "enabled" | "disabled" | "unknown";
 type ThreadedModeFinalLabel = "verified" | "unverified" | "unknown";
 
@@ -148,6 +153,7 @@ async function runSetup(deps: NotifyCommandDeps): Promise<void> {
 	let chatId: string;
 	if (deps.setupChatId?.trim()) {
 		chatId = deps.setupChatId.trim();
+		await verifyPrivateChatId(fetchImpl, apiBase, token, chatId);
 		process.stdout.write(`Using provided chat id ${chatId} (non-interactive).\n`);
 	} else {
 		const stale = await getUpdates(fetchImpl, apiBase, token, { timeout: 0, allowed_updates: ["message"] });
@@ -170,31 +176,91 @@ async function runSetup(deps: NotifyCommandDeps): Promise<void> {
 	);
 }
 
-async function promptForToken(): Promise<string> {
-	if (!process.stdin.isTTY) {
+type TokenPromptInput = NodeJS.ReadStream & {
+	isRaw?: boolean;
+	setRawMode?: (mode: boolean) => unknown;
+};
+
+type TokenPromptOutput = Pick<NodeJS.WriteStream, "write">;
+
+export async function promptForToken(
+	input: TokenPromptInput = process.stdin,
+	output: TokenPromptOutput = process.stdout,
+): Promise<string> {
+	if (!input.isTTY) {
 		throw new Error("notify setup requires an interactive TTY unless setupToken is injected.");
 	}
-	const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
-	try {
-		return (await rl.question("Telegram BotFather token: ")).trim();
-	} finally {
-		rl.close();
+	if (typeof input.setRawMode !== "function") {
+		throw new Error("notify setup requires a TTY with raw input support unless setupToken is injected.");
 	}
+
+	output.write("Telegram BotFather token: ");
+	const wasRaw = input.isRaw === true;
+	input.setRawMode(true);
+
+	return await new Promise<string>((resolve, reject) => {
+		let value = "";
+		let settled = false;
+
+		const cleanup = () => {
+			input.off("data", onData);
+			input.off("error", onError);
+			input.setRawMode?.(wasRaw);
+			output.write("\n");
+		};
+
+		const finish = (callback: () => void) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			callback();
+		};
+
+		const accept = () => finish(() => resolve(value.trim()));
+		const cancel = () => finish(() => reject(new Error("Telegram bot token prompt cancelled.")));
+		const onError = (error: Error) => finish(() => reject(error));
+		const onData = (chunk: Buffer | string) => {
+			for (const char of String(chunk)) {
+				if (char === "\r" || char === "\n") {
+					accept();
+					return;
+				}
+				if (char === "\u0003") {
+					cancel();
+					return;
+				}
+				if (char === "\u0004") {
+					if (value) accept();
+					else cancel();
+					return;
+				}
+				if (char === "\u007f" || char === "\b") {
+					value = value.slice(0, -1);
+					continue;
+				}
+				if (char >= " ") value += char;
+			}
+		};
+
+		input.on("data", onData);
+		input.once("error", onError);
+		input.resume();
+	});
 }
 
 const THREADED_ENABLED_SUCCESS =
-	"Telegram Threaded Mode capability verified for this bot. SKC 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. SKC 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 SKC 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 SKC 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. SKC 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. SKC needs Telegram private-chat topics so each session can use its own thread.\n" +
-	"SKC 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";
+	"SKC 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: ";
@@ -204,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";
 
@@ -223,6 +289,24 @@ async function getMe(fetchImpl: typeof fetch, apiBase: string, token: string): P
 	return user;
 }
 
+async function verifyPrivateChatId(
+	fetchImpl: typeof fetch,
+	apiBase: string,
+	token: string,
+	chatId: string,
+): Promise<void> {
+	const chat = (await callTelegram<unknown>(fetchImpl, apiBase, token, "getChat", { chat_id: chatId })) as
+		| TelegramChat
+		| undefined;
+	if (!chat || typeof chat !== "object") {
+		throw new Error("Telegram getChat returned invalid Telegram response: missing valid Chat result.");
+	}
+	if (chat.type !== "private") {
+		const type = typeof chat.type === "string" && chat.type ? chat.type : "unknown";
+		throw new Error(`Provided chat id ${chatId} is a ${type} chat; pairing requires a private Telegram chat.`);
+	}
+}
+
 function threadedModeState(user: TelegramUser): ThreadedModeState {
 	if (user.has_topics_enabled === true) return "enabled";
 	if (user.has_topics_enabled === false) return "disabled";
@@ -416,8 +500,10 @@ ${chalk.bold("Examples:")}
 
 ${chalk.bold("Threaded Mode:")}
   SKC 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,
-  SKC 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, SKC 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/telegram-cli.ts

@@ -4,10 +4,10 @@
  */
 
 import { logger } from "@sayknow-cli/utils";
-import { resolveSkcRuntimeSpawnInfo } from "../daemon/runtime";
 import { isSettingsInitialized, Settings, settings } from "../config/settings";
 import type { TelegramSettings } from "../config/settings-schema";
 import { telegramSettingsToEnv, validateTelegramSettings } from "../config/telegram-env-bridge";
+import { resolveSkcRuntimeSpawnInfo } from "../daemon/runtime";
 
 export type TelegramAction = "start" | "status" | "env" | "__gateway";
 

package/src/cli/update-cli.ts

@@ -14,9 +14,10 @@ import { installDefaultSkcDefinitions } from "../defaults/skc-defaults";
 import { theme } from "../modes/theme/theme";
 
 const RELEASE_REPO = "jaybeyond/Sayknow_CLI";
-const PACKAGE = "@sayknow-cli/coding-agent";
-const NPM_WRAPPER_PACKAGE = "sayknow-cli";
-const NPM_MANAGED_PACKAGES = [NPM_WRAPPER_PACKAGE, PACKAGE] as const;
+const RELEASE_TAG_PREFIX = "sayknow-v";
+const PACKAGE = "sayknow-cli";
+const SCOPED_CLI_PACKAGE = "@sayknow-cli/coding-agent";
+const NPM_MANAGED_PACKAGES = [PACKAGE, SCOPED_CLI_PACKAGE] as const;
 
 interface ReleaseInfo {
 	tag: string;
@@ -136,35 +137,79 @@ function defaultPackageExists(_packageName: string, packageRoot: string): boolea
 	return fs.existsSync(path.join(packageRoot, "package.json"));
 }
 
-function npmPackageRootForBinPath(binPath: string, packageName: string, platform: PathPlatform): string {
+function npmPackageRootForWindowsShim(binPath: string, packageName: string, platform: PathPlatform): string {
 	const pathApi = pathApiForPlatform(platform);
 	const segments = packageName.split("/");
 	return pathApi.join(pathApi.dirname(binPath), "node_modules", ...segments);
 }
 
+function packageRootFromNodeModulesPath(
+	binPath: string,
+	packageName: string,
+	platform: PathPlatform,
+): string | undefined {
+	const pathApi = pathApiForPlatform(platform);
+	const packageSegments = packageName.split("/");
+	const parts = pathApi.normalize(binPath).split(pathApi.sep).filter(Boolean);
+	for (let index = 0; index < parts.length; index++) {
+		if (parts[index] !== "node_modules") continue;
+		const packageStart = index + 1;
+		const matched = packageSegments.every((segment, offset) => parts[packageStart + offset] === segment);
+		if (!matched) continue;
+		const prefix = binPath.startsWith(pathApi.sep) ? pathApi.sep : "";
+		return pathApi.join(prefix, ...parts.slice(0, packageStart + packageSegments.length));
+	}
+	return undefined;
+}
+
+function npmPackageRootsForPosixShim(binPath: string, packageName: string): string[] {
+	const pathApi = path.posix;
+	const binDir = pathApi.dirname(binPath);
+	const packageSegments = packageName.split("/");
+	return [
+		pathApi.join(pathApi.dirname(binDir), "lib", "node_modules", ...packageSegments),
+		pathApi.join(binDir, "node_modules", ...packageSegments),
+	];
+}
+
 function resolveNpmManagedTarget(
 	ompPath: string,
 	platform: PathPlatform = process.platform,
 	packageExists: PackageExists = defaultPackageExists,
 ): PackageManagerTarget | undefined {
-	if (platform !== "win32") return undefined;
 	const pathApi = pathApiForPlatform(platform);
-	const extension = pathApi.extname(ompPath).toLowerCase();
-	if (extension !== ".cmd" && extension !== ".ps1") return undefined;
-	const basename = pathApi.basename(ompPath, extension).toLowerCase();
-	if (basename !== APP_NAME.toLowerCase()) return undefined;
+	const basename = pathApi.basename(ompPath, pathApi.extname(ompPath)).toLowerCase();
+	const resolvedPath = tryRealpath(ompPath);
+	const candidatePaths = resolvedPath ? [resolvedPath, ompPath] : [ompPath];
+
+	if (platform === "win32") {
+		const extension = pathApi.extname(ompPath).toLowerCase();
+		if (extension !== ".cmd" && extension !== ".ps1") return undefined;
+		if (basename !== APP_NAME.toLowerCase()) return undefined;
+		for (const packageName of NPM_MANAGED_PACKAGES) {
+			const packageRoot = npmPackageRootForWindowsShim(ompPath, packageName, platform);
+			if (packageExists(packageName, packageRoot)) return { manager: "npm", packageName };
+		}
+		return undefined;
+	}
 
+	if (basename !== APP_NAME.toLowerCase()) return undefined;
 	for (const packageName of NPM_MANAGED_PACKAGES) {
-		const packageRoot = npmPackageRootForBinPath(ompPath, packageName, platform);
-		if (packageExists(packageName, packageRoot)) return { manager: "npm", packageName };
+		for (const candidatePath of candidatePaths) {
+			const packageRoot = packageRootFromNodeModulesPath(candidatePath, packageName, platform);
+			if (packageRoot && packageExists(packageName, packageRoot)) return { manager: "npm", packageName };
+		}
+		for (const packageRoot of npmPackageRootsForPosixShim(ompPath, packageName)) {
+			if (packageExists(packageName, packageRoot)) return { manager: "npm", packageName };
+		}
 	}
 	return undefined;
 }
 
 function resolveUpdateMethod(ompPath: string, bunBinDir: string | undefined): "bun" | "npm" | "binary" {
+	if (bunBinDir && isPathInDirectory(ompPath, bunBinDir)) return "bun";
 	if (resolveNpmManagedTarget(ompPath)) return "npm";
-	if (!bunBinDir) return "binary";
-	return isPathInDirectory(ompPath, bunBinDir) ? "bun" : "binary";
+	return "binary";
 }
 
 export function resolveUpdateMethodForTest(ompPath: string, bunBinDir: string | undefined): "bun" | "npm" | "binary" {
@@ -183,16 +228,10 @@ async function resolveUpdateTarget(): Promise<UpdateTarget> {
 	const ompPath = resolveSkcPath();
 
 	if (ompPath) {
+		if (bunBinDir && isPathInDirectory(ompPath, bunBinDir)) return { method: "bun" };
 		const npmTarget = resolveNpmManagedTarget(ompPath);
 		if (npmTarget) return { method: "npm", packageName: npmTarget.packageName };
-		const method = resolveUpdateMethod(ompPath, bunBinDir);
-		if (method === "bun") return { method };
-		if (method === "npm") {
-			throw new Error(
-				formatUnsupportedTargetMessage(`Could not resolve npm package root for ${APP_NAME} shim ${ompPath}`),
-			);
-		}
-		return { method, path: ompPath };
+		return { method: "binary", path: ompPath };
 	}
 
 	if (bunBinDir) return { method: "bun" };
@@ -212,7 +251,7 @@ async function getLatestRelease(): Promise<ReleaseInfo> {
 
 	const data = (await response.json()) as { version: string };
 	const version = data.version;
-	const tag = `v${version}`;
+	const tag = `${RELEASE_TAG_PREFIX}${version}`;
 
 	return {
 		tag,
@@ -350,7 +389,7 @@ function formatBinaryInstallInstruction(platform: NodeJS.Platform = process.plat
 function formatManualUpdateInstructions(platform: NodeJS.Platform = process.platform): string {
 	return [
 		`If ${APP_NAME} was installed with Bun, run: bun install -g ${PACKAGE}@latest`,
-		`If ${APP_NAME} was installed with npm, pnpm, or another package manager, update it with that same manager.`,
+		`If ${APP_NAME} was installed with npm, pnpm, or another package manager, run: npm install -g ${PACKAGE}@latest`,
 		formatBinaryInstallInstruction(platform),
 	].join("\n");
 }
@@ -365,7 +404,7 @@ function buildReleaseBinaryUrl(
 	arch: string = process.arch,
 ): string {
 	const binaryName = getBinaryName(platform, arch);
-	const tag = `v${version}`;
+	const tag = `${RELEASE_TAG_PREFIX}${version}`;
 	return `https://github.com/${RELEASE_REPO}/releases/download/${tag}/${binaryName}`;
 }
 
@@ -552,31 +591,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 `skc --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;
+}
+
+/**
+ * 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;
+	}
 
-	console.log(chalk.dim("Installing update..."));
-	const verification = await replaceBinaryForUpdate({
+	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();