@sayknow-cli/coding-agent 0.3.12 → 0.3.15

package/src/cli/malloc-env-guard.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "bun:test";
+import {
+	buildMallocReexecArgv,
+	formatMallocEnvNotice,
+	hasMacOSMallocEnv,
+	MACOS_MALLOC_ENV_VARS,
+	MALLOC_ENV_REEXEC_GUARD,
+	shouldReexecForMacOSMallocEnv,
+} from "./malloc-env-guard";
+
+describe("hasMacOSMallocEnv", () => {
+	it("detects MallocStackLogging", () => {
+		expect(hasMacOSMallocEnv({ MallocStackLogging: "0" })).toBe(true);
+	});
+
+	it("detects MallocStackLoggingNoCompact", () => {
+		expect(hasMacOSMallocEnv({ MallocStackLoggingNoCompact: "1" })).toBe(true);
+	});
+
+	it("is false when neither var is present", () => {
+		expect(hasMacOSMallocEnv({ PATH: "/usr/bin", HOME: "/home/x" })).toBe(false);
+	});
+
+	it("is false for an empty environment", () => {
+		expect(hasMacOSMallocEnv({})).toBe(false);
+	});
+});
+
+describe("shouldReexecForMacOSMallocEnv", () => {
+	it("is true on darwin with a malloc var and no loop guard", () => {
+		expect(shouldReexecForMacOSMallocEnv({ MallocStackLogging: "0" }, "darwin")).toBe(true);
+	});
+
+	it("is false off darwin even when a malloc var is present", () => {
+		expect(shouldReexecForMacOSMallocEnv({ MallocStackLogging: "0" }, "linux")).toBe(false);
+		expect(shouldReexecForMacOSMallocEnv({ MallocStackLogging: "0" }, "win32")).toBe(false);
+	});
+
+	it("is false when the loop guard is already set (already re-exec'd)", () => {
+		expect(shouldReexecForMacOSMallocEnv({ MallocStackLogging: "0", [MALLOC_ENV_REEXEC_GUARD]: "1" }, "darwin")).toBe(
+			false,
+		);
+	});
+
+	it("is false on darwin when no malloc var is present", () => {
+		expect(shouldReexecForMacOSMallocEnv({ PATH: "/usr/bin" }, "darwin")).toBe(false);
+	});
+});
+
+describe("buildMallocReexecArgv", () => {
+	it("drops the embedded virtual entry for a POSIX compiled binary", () => {
+		expect(buildMallocReexecArgv(["/exe", "/$bunfs/root/cli", "run", "--flag"], "/exe")).toEqual([
+			"/exe",
+			"run",
+			"--flag",
+		]);
+	});
+
+	it("drops the embedded virtual entry for a Windows compiled binary", () => {
+		expect(buildMallocReexecArgv(["C:/exe.exe", "B:\\~BUN\\root\\cli", "run"], "C:/exe.exe")).toEqual([
+			"C:/exe.exe",
+			"run",
+		]);
+	});
+
+	it("drops the percent-encoded embedded virtual entry", () => {
+		expect(buildMallocReexecArgv(["/exe", "B:\\%7EBUN\\root\\cli", "run"], "/exe")).toEqual(["/exe", "run"]);
+	});
+
+	it("keeps the on-disk script for a source/dev-link run", () => {
+		expect(
+			buildMallocReexecArgv(["/usr/bin/bun", "/repo/packages/coding-agent/src/cli.ts", "run", "-x"], "/usr/bin/bun"),
+		).toEqual(["/usr/bin/bun", "/repo/packages/coding-agent/src/cli.ts", "run", "-x"]);
+	});
+
+	it("handles a source run with no user args", () => {
+		expect(buildMallocReexecArgv(["/usr/bin/bun", "/repo/cli.ts"], "/usr/bin/bun")).toEqual([
+			"/usr/bin/bun",
+			"/repo/cli.ts",
+		]);
+	});
+});
+
+describe("formatMallocEnvNotice", () => {
+	it("names both env vars and the permanent launchctl fix", () => {
+		const notice = formatMallocEnvNotice();
+		for (const name of MACOS_MALLOC_ENV_VARS) {
+			expect(notice).toContain(name);
+		}
+		expect(notice).toContain("launchctl unsetenv MallocStackLogging");
+		expect(notice).toContain("launchctl unsetenv MallocStackLoggingNoCompact");
+		expect(notice.endsWith("\n")).toBe(true);
+	});
+});
+
+describe("module constants", () => {
+	it("exposes exactly the two macOS malloc env vars", () => {
+		expect([...MACOS_MALLOC_ENV_VARS]).toEqual(["MallocStackLogging", "MallocStackLoggingNoCompact"]);
+	});
+
+	it("uses a namespaced loop-guard variable", () => {
+		expect(MALLOC_ENV_REEXEC_GUARD).toBe("SKC_MALLOC_ENV_REEXEC");
+	});
+});

package/src/cli/malloc-env-guard.ts

@@ -0,0 +1,149 @@
+/**
+ * macOS malloc-stack-logging launch boundary.
+ *
+ * On macOS, an inherited `MallocStackLogging` / `MallocStackLoggingNoCompact`
+ * environment variable (from an Xcode scheme's malloc diagnostics, Instruments,
+ * `launchctl setenv`, or a debug-attached shell) makes libmalloc print
+ *
+ *   MallocStackLogging: can't turn off malloc stack logging because it was not enabled.
+ *
+ * to the stderr of every TTY-attached process. Bun snapshots the spawn-default
+ * environment at process startup — before any JS runs — so neither
+ * `delete process.env.X` nor a real libc `unsetenv()` cleans the environment
+ * that children inherit by default (verified on Bun 1.3.14). Inside the TUI,
+ * every PTY-spawned child then repeats the warning straight into the rendered
+ * frame and corrupts the display.
+ *
+ * The only way to hand children a clean startup snapshot is to start the primary
+ * process with a clean environment. This module re-execs the exact invocation
+ * once (darwin-only) with a `filterProcessEnv`-scrubbed environment and a
+ * `SKC_MALLOC_ENV_REEXEC` loop guard, before any fast path or subprocess spawn.
+ * The re-exec'd process — and therefore every downstream lane: `Bun.spawn`
+ * defaults, `node:child_process`, the native PTY, the tmux owner, plugin
+ * installs, and subagents — starts from a clean snapshot.
+ *
+ * The initial contaminated process's own libmalloc line is emitted by libc
+ * before any JS runs and cannot be suppressed from inside the process; it
+ * appears at most once per launch. A one-time actionable notice is written to
+ * interactive stderr (outside the rendered frame) pointing at the permanent
+ * `launchctl unsetenv` fix.
+ */
+
+import { filterProcessEnv } from "@sayknow-cli/utils/env";
+import type { Subprocess } from "bun";
+
+/** Env vars that make macOS libmalloc write to a TTY when inherited. */
+export const MACOS_MALLOC_ENV_VARS = ["MallocStackLogging", "MallocStackLoggingNoCompact"] as const;
+
+/** Loop guard set on the scrubbed re-exec so it never re-execs itself again. */
+export const MALLOC_ENV_REEXEC_GUARD = "SKC_MALLOC_ENV_REEXEC";
+
+/** True when at least one macOS malloc-stack-logging var is present in `env`. */
+export function hasMacOSMallocEnv(env: Record<string, string | undefined>): boolean {
+	return MACOS_MALLOC_ENV_VARS.some(name => env[name] !== undefined);
+}
+
+/**
+ * True iff we must re-exec to escape a contaminated macOS startup snapshot:
+ * darwin, not already inside the scrubbed re-exec, and at least one malloc var
+ * present. Off darwin or on the re-exec'd child this is always false, so the
+ * common launch path pays only two cheap lookups.
+ */
+export function shouldReexecForMacOSMallocEnv(
+	env: Record<string, string | undefined>,
+	platform: NodeJS.Platform,
+): boolean {
+	return platform === "darwin" && env[MALLOC_ENV_REEXEC_GUARD] === undefined && hasMacOSMallocEnv(env);
+}
+
+/**
+ * Reconstruct the argv that re-runs the exact same program image.
+ *
+ * - Compiled single-file executable: argv[1] is the embedded virtual entry
+ *   (`/$bunfs/…` on POSIX, `B:\~BUN\…` on Windows), which must be dropped — the
+ *   executable re-embeds its own entry. Re-run `[exe, ...userArgs]`.
+ * - Source / dev-link run: argv[1] is the on-disk script that must be passed
+ *   back to the interpreter. Re-run `[interpreter, script, ...userArgs]`.
+ */
+export function buildMallocReexecArgv(argv: readonly string[], execPath: string): string[] {
+	const entry = argv[1];
+	const isCompiledEntry =
+		typeof entry === "string" && (entry.includes("/$bunfs/") || entry.includes("~BUN") || entry.includes("%7EBUN"));
+	if (isCompiledEntry) {
+		return [execPath, ...argv.slice(2)];
+	}
+	return [execPath, ...argv.slice(1)];
+}
+
+/** One-time, human-actionable notice pointing at the permanent environment fix. */
+export function formatMallocEnvNotice(): string {
+	return (
+		"sayknow-cli: detected macOS malloc-stack-logging environment variables " +
+		"(MallocStackLogging / MallocStackLoggingNoCompact); relaunching once with a " +
+		"scrubbed environment so they do not flood the terminal.\n" +
+		"  Remove them permanently with:\n" +
+		"    unset MallocStackLogging MallocStackLoggingNoCompact\n" +
+		"    launchctl unsetenv MallocStackLogging\n" +
+		"    launchctl unsetenv MallocStackLoggingNoCompact\n"
+	);
+}
+
+/**
+ * Re-exec the current process once with a scrubbed environment and propagate the
+ * child's exit code. Callers MUST gate this behind `shouldReexecForMacOSMallocEnv`.
+ *
+ * Returns the child exit code, or `null` if the re-exec could not be spawned (in
+ * which case the caller falls back to running in the current, contaminated
+ * process — degraded but functional; the native PTY boundary and
+ * `filterProcessEnv` still keep managed children clean).
+ */
+export async function reexecWithScrubbedMallocEnv(): Promise<number | null> {
+	const cleanEnv = filterProcessEnv(process.env);
+	cleanEnv[MALLOC_ENV_REEXEC_GUARD] = "1";
+	const childArgv = buildMallocReexecArgv(process.argv, process.execPath);
+
+	// Surface the diagnostic exactly once, before the TUI enters its alternate
+	// screen, and only on an interactive terminal (piped/CI stderr is not a TTY,
+	// so libmalloc stays silent there and the notice would just be noise).
+	if (process.stderr.isTTY) {
+		process.stderr.write(formatMallocEnvNotice());
+	}
+
+	let child: Subprocess;
+	try {
+		child = Bun.spawn(childArgv, {
+			env: cleanEnv,
+			stdin: "inherit",
+			stdout: "inherit",
+			stderr: "inherit",
+		});
+	} catch {
+		return null;
+	}
+
+	// Keep the wrapper alive on SIGINT/SIGTERM so it reaps the child and
+	// propagates its exit code instead of dying first, and forward the signal so
+	// the scrubbed child terminates too. Interactive Ctrl-C is delivered to the
+	// whole foreground process group (and the TUI's raw mode turns it into a 0x03
+	// byte, not a signal, anyway), so re-forwarding is a harmless no-op once the
+	// child is already handling or exiting. Targeted delivery — `kill -INT <pid>`
+	// or a supervisor's `child.kill("SIGINT")` — reaches only the wrapper, so
+	// without forwarding the launch would be uncancellable outside a terminal.
+	const forwardSignal = (signal: NodeJS.Signals) => () => {
+		try {
+			child.kill(signal);
+		} catch {
+			// Child already gone; nothing to forward.
+		}
+	};
+	const onSigint = forwardSignal("SIGINT");
+	const onSigterm = forwardSignal("SIGTERM");
+	process.on("SIGINT", onSigint);
+	process.on("SIGTERM", onSigterm);
+	try {
+		return await child.exited;
+	} finally {
+		process.off("SIGINT", onSigint);
+		process.off("SIGTERM", onSigterm);
+	}
+}

package/src/cli/notify-cli.ts

@@ -7,9 +7,19 @@ import { createInterface } from "node:readline/promises";
 import { APP_NAME } from "@sayknow-cli/utils/dirs";
 import chalk from "chalk";
 import type { Settings } from "../config/settings";
-import { getNotificationConfig, maskToken } from "../notifications/config";
-
-export type NotifyAction = "setup" | "status" | "daemon-internal";
+import { maskToken } from "../notifications/config";
+import {
+	buildNotificationStatusReport,
+	checkNotificationHealth,
+	formatNotificationHealthReport,
+	formatNotificationRecoveryReport,
+	formatNotificationStatusReport,
+	formatNotificationTestResult,
+	recoverNotifications,
+	sendNotificationTest,
+} from "../notifications/notification-service";
+
+export type NotifyAction = "setup" | "status" | "health" | "test" | "recovery" | "daemon-internal";
 
 export interface NotifyCommandArgs {
 	action: NotifyAction;
@@ -18,6 +28,8 @@ export interface NotifyCommandArgs {
 	token?: string;
 	chatId?: string;
 	redact?: boolean;
+	probe?: boolean;
+	message?: string;
 }
 
 export interface NotifyCommandDeps {
@@ -93,6 +105,19 @@ export function parseNotifyArgs(args: string[]): NotifyCommandArgs | undefined {
 			redact: rest.includes("--redact"),
 		};
 	}
+	if (action === "health" || action === "test" || action === "recovery") {
+		const rest = args.slice(2);
+		const flag = (name: string): string | undefined => {
+			const i = rest.indexOf(name);
+			return i >= 0 ? rest[i + 1] : undefined;
+		};
+		return {
+			action,
+			rawArgs: rest,
+			probe: rest.includes("--probe"),
+			message: flag("--message"),
+		};
+	}
 	if (action === "daemon-internal") {
 		return {
 			action,
@@ -117,6 +142,15 @@ export async function runNotifyCommand(cmd: NotifyCommandArgs, deps: NotifyComma
 		case "status":
 			await runStatus(deps);
 			return;
+		case "health":
+			await runHealth(deps, cmd);
+			return;
+		case "test":
+			await runTest(deps, cmd);
+			return;
+		case "recovery":
+			await runRecovery(deps);
+			return;
 		case "daemon-internal": {
 			const m = await import("../notifications/telegram-daemon-cli");
 			if (cmd.smoke) {
@@ -411,20 +445,42 @@ async function verifyThreadedMode(
 
 async function runStatus(deps: NotifyCommandDeps): Promise<void> {
 	const settings = await getSettings(deps);
-	const cfg = getNotificationConfig(settings);
+	const report = buildNotificationStatusReport(settings);
 	process.stdout.write(
-		`${chalk.bold("Notifications")}\n` +
-			`  enabled: ${cfg.enabled}\n` +
-			`  telegram.botToken: ${maskToken(cfg.botToken)}\n` +
-			`  telegram.chatId: ${cfg.chatId ?? "(unset)"}\n` +
-			`  discord.botToken: ${maskToken(cfg.discord.botToken)}\n` +
-			`  discord.channelId: ${cfg.discord.channelId ?? "(unset)"}\n` +
-			`  slack.botToken: ${maskToken(cfg.slack.botToken)}\n` +
-			`  slack.channelId: ${cfg.slack.channelId ?? "(unset)"}\n` +
-			`  redact: ${cfg.redact}\n`,
+		`${chalk.bold("Notifications")}\n${formatNotificationStatusReport(report).split("\n").slice(1).join("\n")}\n`,
 	);
 }
 
+async function runHealth(deps: NotifyCommandDeps, cmd: NotifyCommandArgs): Promise<void> {
+	const settings = await getSettings(deps);
+	const report = await checkNotificationHealth({
+		settings,
+		probe: cmd.probe,
+		deps: { fetchImpl: deps.fetchImpl, apiBase: deps.apiBase },
+	});
+	process.stdout.write(`${formatNotificationHealthReport(report)}\n`);
+	if (report.overall === "error" && deps.setExitCode) deps.setExitCode(1);
+	else if (report.overall === "error") process.exitCode = 1;
+}
+
+async function runTest(deps: NotifyCommandDeps, cmd: NotifyCommandArgs): Promise<void> {
+	const settings = await getSettings(deps);
+	const result = await sendNotificationTest({
+		settings,
+		text: cmd.message,
+		deps: { fetchImpl: deps.fetchImpl, apiBase: deps.apiBase },
+	});
+	process.stdout.write(`${formatNotificationTestResult(result)}\n`);
+	if (!result.ok && deps.setExitCode) deps.setExitCode(1);
+	else if (!result.ok) process.exitCode = 1;
+}
+
+async function runRecovery(deps: NotifyCommandDeps): Promise<void> {
+	const settings = await getSettings(deps);
+	const report = await recoverNotifications({ settings });
+	process.stdout.write(`${formatNotificationRecoveryReport(report)}\n`);
+}
+
 async function waitForPrivateChat(
 	fetchImpl: typeof fetch,
 	apiBase: string,
@@ -514,15 +570,23 @@ ${chalk.bold("Usage:")}
   ${APP_NAME} notify setup
   ${APP_NAME} notify setup --token <botToken> --chat-id <chatId> [--redact]
   ${APP_NAME} notify status
+  ${APP_NAME} notify health [--probe]
+  ${APP_NAME} notify test [--message <text>]
+  ${APP_NAME} notify recovery
 
 ${chalk.bold("Subcommands:")}
   setup     Pair a Telegram bot token with a private chat and verify Threaded Mode capability
   status    Show notification configuration without secrets
+  health    Report config, daemon-ownership and endpoint health (--probe adds a Telegram reachability check)
+  test      Send a one-off test notification through the configured Telegram adapter
+  recovery  Clear dead-owner daemon locks and stale per-session endpoint files (never touches a live owner)
 
 ${chalk.bold("Examples:")}
   ${APP_NAME} notify setup
-  ${APP_NAME} notify setup --token <botToken> --chat-id <chatId> [--redact]
   ${APP_NAME} notify status
+  ${APP_NAME} notify health --probe
+  ${APP_NAME} notify test --message "hello from skc"
+  ${APP_NAME} notify recovery
 
 ${chalk.bold("Threaded Mode:")}
   SKC uses Telegram private-chat topics for per-session threads. Setup verifies the bot

package/src/cli/session-picker.ts

@@ -1,49 +1,32 @@
 import { ProcessTerminal, TUI } from "@sayknow-cli/tui";
-import { SessionSelectorComponent } from "../modes/components/session-selector";
-import type { SessionInfo } from "../session/session-manager";
+import { type SessionSelectionResult, SessionSelectorComponent } from "../modes/components/session-selector";
+import { type SessionInfo, SessionManager } from "../session/session-manager";
 import { FileSessionStorage } from "../session/session-storage";
 
-/** Show TUI session selector and return selected session path or null if cancelled */
-export async function selectSession(sessions: SessionInfo[]): Promise<string | null> {
-	const { promise, resolve } = Promise.withResolvers<string | null>();
+/** Show the read-only TUI session picker and return the user's consent intent. */
+export async function selectSession(sessions: SessionInfo[]): Promise<SessionSelectionResult> {
+	const { promise, resolve } = Promise.withResolvers<SessionSelectionResult>();
 	const ui = new TUI(new ProcessTerminal());
-	let resolved = false;
 	const storage = new FileSessionStorage();
-
-	const showSelector = () => {
-		const selector = new SessionSelectorComponent(
-			sessions,
-			(path: string) => {
-				if (!resolved) {
-					resolved = true;
-					ui.stop();
-					resolve(path);
-				}
-			},
-			() => {
-				if (!resolved) {
-					resolved = true;
-					ui.stop();
-					resolve(null);
-				}
-			},
-			() => {
-				if (!resolved) {
-					resolved = true;
-					ui.stop();
-					process.exit(0);
-				}
-			},
-			async (session: SessionInfo) => {
-				// Delete handler - SessionList will show confirmation internally
-				await storage.deleteSessionWithArtifacts(session.path);
-				return true;
-			},
-		);
-		return selector;
+	let settled = false;
+	const settle = (selection: SessionSelectionResult): void => {
+		if (settled) return;
+		settled = true;
+		ui.stop();
+		resolve(selection);
 	};
-
-	const selector = showSelector();
+	const selector = new SessionSelectorComponent(
+		sessions,
+		() => {},
+		() => settle({ kind: "cancelled" }),
+		() => settle({ kind: "cancelled" }),
+		async session => {
+			await storage.deleteSessionWithArtifacts(session.path);
+			return true;
+		},
+		SessionManager.inspectSessionTailReadOnly,
+		settle,
+	);
 	selector.setOnRequestRender(() => ui.requestRender());
 	ui.addChild(selector);
 	ui.setFocus(selector);

package/src/cli/update-cli.ts

@@ -45,7 +45,6 @@ export interface PackageManagerUpdateOptions {
 	expectedVersion: string;
 	runInstall: PackageManagerUpdateRunner;
 	verifyInstalledRuntime: (expectedVersion: string) => Promise<InstalledVersionVerification>;
-	printVerificationResult?: (expectedVersion: string) => Promise<void>;
 	printRecoveredVerification?: (expectedVersion: string) => void;
 }
 
@@ -122,8 +121,11 @@ function isPathInDirectory(filePath: string, directoryPath: string): boolean {
 	return isPathInDirectoryLexical(resolvedFile, dirReal);
 }
 
-type PackageManagerTarget = { manager: "npm"; packageName: string };
-type UpdateTarget = { method: "bun" } | { method: "npm"; packageName: string } | { method: "binary"; path: string };
+export type PackageManagerTarget = { manager: "npm"; packageName: string };
+export type UpdateTarget =
+	| { method: "bun" }
+	| { method: "npm"; packageName: string }
+	| { method: "binary"; path: string };
 
 type PathPlatform = NodeJS.Platform;
 type PackageExists = (packageName: string, packageRoot: string) => boolean;
@@ -423,19 +425,6 @@ export function formatVerificationFailureForTest(
 	return formatVerificationFailure(result, expectedVersion);
 }
 
-/**
- * Print post-update verification result.
- */
-async function printVerification(expectedVersion: string): Promise<void> {
-	const result = await verifyInstalledRuntime(expectedVersion);
-	if (result.ok) {
-		printSuccessfulVerification(expectedVersion);
-		return;
-	}
-	console.log(chalk.yellow(`\nWarning: ${formatVerificationFailure(result, expectedVersion)}`));
-	console.log(chalk.yellow(formatManualUpdateInstructions()));
-}
-
 async function unlinkIfExists(filePath: string): Promise<void> {
 	try {
 		await fs.promises.unlink(filePath);
@@ -499,6 +488,14 @@ function formatPackageManagerInstallFailure(
 	return `${managerName} install failed with exit code ${result.exitCode ?? "unknown"}${outputSuffix}. ${formatVerificationFailure(verification, expectedVersion)}`;
 }
 
+function formatPackageManagerVerificationFailure(
+	managerName: string,
+	verification: InstalledVersionVerification,
+	expectedVersion: string,
+): string {
+	return `${managerName} install exited successfully, but the selected ${APP_NAME} runtime failed verification: ${formatVerificationFailure(verification, expectedVersion)}`;
+}
+
 export async function runPackageManagerUpdateForTest(
 	options: PackageManagerUpdateOptions,
 ): Promise<InstalledVersionVerification> {
@@ -508,8 +505,14 @@ export async function runPackageManagerUpdateForTest(
 async function updateViaPackageManager(options: PackageManagerUpdateOptions): Promise<InstalledVersionVerification> {
 	const result = await options.runInstall(options.expectedVersion);
 	if (result.exitCode === 0) {
-		await (options.printVerificationResult ?? printVerification)(options.expectedVersion);
-		return await options.verifyInstalledRuntime(options.expectedVersion);
+		const verification = await options.verifyInstalledRuntime(options.expectedVersion);
+		if (!verification.ok) {
+			throw new Error(
+				formatPackageManagerVerificationFailure(options.managerName, verification, options.expectedVersion),
+			);
+		}
+		printSuccessfulVerification(options.expectedVersion);
+		return verification;
 	}
 
 	const verification = await options.verifyInstalledRuntime(options.expectedVersion);
@@ -661,16 +664,42 @@ async function updateViaBinaryAt(targetPath: string, expectedVersion: string): P
 /**
  * Run the update command.
  */
-export async function runUpdateCommand(opts: { force: boolean; check: boolean }): Promise<void> {
+export interface UpdateCommandDependencies {
+	getLatestRelease?: () => Promise<ReleaseInfo>;
+	resolveUpdateTarget?: () => Promise<UpdateTarget>;
+	performUpdate?: (target: UpdateTarget, expectedVersion: string) => Promise<void>;
+	refreshInstalledDefaultSkills?: () => Promise<void>;
+	exit?: (code: number) => never;
+}
+
+async function performUpdate(target: UpdateTarget, expectedVersion: string): Promise<void> {
+	if (target.method === "bun") {
+		await updateViaBun(expectedVersion);
+	} else if (target.method === "npm") {
+		await updateViaNpm(target.packageName, expectedVersion);
+	} else {
+		await updateViaBinaryAt(target.path, expectedVersion);
+	}
+}
+
+export async function runUpdateCommand(
+	opts: { force: boolean; check: boolean },
+	deps: UpdateCommandDependencies = {},
+): Promise<void> {
+	const lookupRelease = deps.getLatestRelease ?? getLatestRelease;
+	const resolveTarget = deps.resolveUpdateTarget ?? resolveUpdateTarget;
+	const update = deps.performUpdate ?? performUpdate;
+	const refreshDefaults = deps.refreshInstalledDefaultSkills ?? refreshInstalledDefaultSkills;
+	const exit = deps.exit ?? process.exit;
+
 	console.log(chalk.dim(`Current version: ${VERSION}`));
 
-	// Check for updates
 	let release: ReleaseInfo;
 	try {
-		release = await getLatestRelease();
+		release = await lookupRelease();
 	} catch (err) {
 		console.error(chalk.red(`Failed to check for updates: ${err}`));
-		process.exit(1);
+		return exit(1);
 	}
 
 	const comparison = compareVersions(release.version, VERSION);
@@ -686,27 +715,17 @@ export async function runUpdateCommand(opts: { force: boolean; check: boolean })
 		console.log(chalk.yellow(`Forcing reinstall of ${release.version}`));
 	}
 
-	if (opts.check) {
-		// Just check, don't install
-		return;
-	}
+	if (opts.check) return;
 
-	// Choose update method based on the prioritized skc binary in PATH
 	try {
-		const target = await resolveUpdateTarget();
-		if (target.method === "bun") {
-			await updateViaBun(release.version);
-		} else if (target.method === "npm") {
-			await updateViaNpm(target.packageName, release.version);
-		} else {
-			await updateViaBinaryAt(target.path, release.version);
-		}
+		const target = await resolveTarget();
+		await update(target, release.version);
 	} catch (err) {
 		console.error(chalk.red(`Update failed: ${err}`));
-		process.exit(1);
+		return exit(1);
 	}
 
-	await refreshInstalledDefaultSkills();
+	await refreshDefaults();
 }
 
 /**