@sayknow-cli/coding-agent 0.3.5 → 0.3.7

package/src/cli/telegram-cli.ts

@@ -0,0 +1,156 @@
+/**
+ * `skc telegram` command handlers — start/status/env for the Telegram Remote
+ * integration, driven entirely by the `telegram.*` settings group.
+ */
+
+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";
+
+export type TelegramAction = "start" | "status" | "env" | "__gateway";
+
+export interface TelegramCommandArgs {
+	action: TelegramAction;
+	flags: {
+		json?: boolean;
+	};
+}
+
+export const TELEGRAM_ACTIONS: readonly TelegramAction[] = ["start", "status", "env", "__gateway"];
+
+/** Read the full telegram settings group from the settings singleton. */
+function readTelegramSettings(): TelegramSettings {
+	return {
+		enabled: settings.get("telegram.enabled"),
+		botToken: settings.get("telegram.botToken"),
+		allowedUserIds: settings.get("telegram.allowedUserIds"),
+		allowedChatIds: settings.get("telegram.allowedChatIds"),
+		backend: settings.get("telegram.backend"),
+		enableStop: settings.get("telegram.enableStop"),
+		enableRich: settings.get("telegram.enableRich"),
+		enablePush: settings.get("telegram.enablePush"),
+		registerCommands: settings.get("telegram.registerCommands"),
+		presets: settings.get("telegram.presets"),
+		rpcSocket: settings.get("telegram.rpcSocket"),
+		stateDir: settings.get("telegram.stateDir"),
+		pollTimeoutSec: settings.get("telegram.pollTimeoutSec"),
+		apiBase: settings.get("telegram.apiBase"),
+		coordinatorCommand: settings.get("telegram.coordinatorCommand") ?? "skc",
+		coordinatorArgs: settings.get("telegram.coordinatorArgs") ?? "mcp-serve,coordinator",
+		enableEditMessageText: settings.get("telegram.enableEditMessageText"),
+		richCallbackTtlMs: settings.get("telegram.richCallbackTtlMs"),
+		richCallbackMaxTokens: settings.get("telegram.richCallbackMaxTokens"),
+		defaultTaskMaxLen: settings.get("telegram.defaultTaskMaxLen"),
+		livenessMs: settings.get("telegram.livenessMs"),
+		followTtlMs: settings.get("telegram.followTtlMs"),
+		subscriptionsMax: settings.get("telegram.subscriptionsMax"),
+		longPollMs: settings.get("telegram.longPollMs"),
+		digestThreshold: settings.get("telegram.digestThreshold"),
+		allowAttachSocketArg: settings.get("telegram.allowAttachSocketArg"),
+	};
+}
+
+/** Resolve the gateway spawn command by re-invoking skc's own hidden
+ *  `telegram __gateway` subcommand: a compiled binary self-spawns the bundled
+ *  gateway entrypoint, and a source run re-executes cli.ts under bun. */
+function resolveGatewayCommand(): { cmd: string; args: string[] } {
+	const rt = resolveSkcRuntimeSpawnInfo();
+	return { cmd: rt.execPath, args: [...rt.argsPrefix, "telegram", "__gateway"] };
+}
+
+async function runStart(): Promise<void> {
+	const config = readTelegramSettings();
+
+	if (!config.enabled) {
+		process.stderr.write(
+			"Telegram Remote is disabled. Enable it in Settings → Integrations, or set telegram.enabled.\n",
+		);
+		process.exit(1);
+	}
+
+	const errors = validateTelegramSettings(config);
+	if (errors.length > 0) {
+		process.stderr.write("Telegram configuration is incomplete:\n");
+		for (const err of errors) process.stderr.write(`  • ${err}\n`);
+		process.exit(1);
+	}
+
+	const env = telegramSettingsToEnv(config);
+	const { cmd, args } = resolveGatewayCommand();
+
+	logger.info("telegram-remote starting", { cmd });
+
+	const proc = Bun.spawn([cmd, ...args], {
+		env: { ...process.env, ...env },
+		stdio: ["inherit", "inherit", "inherit"],
+	});
+
+	// Forward termination signals to the child.
+	const forward = (sig: NodeJS.Signals): void => void proc.kill(sig);
+	process.on("SIGINT", forward);
+	process.on("SIGTERM", forward);
+
+	const code = await proc.exited;
+	process.off("SIGINT", forward);
+	process.off("SIGTERM", forward);
+	process.exit(code);
+}
+
+async function runStatus(flags: TelegramCommandArgs["flags"]): Promise<void> {
+	const config = readTelegramSettings();
+	const errors = config.enabled ? validateTelegramSettings(config) : [];
+
+	if (flags.json) {
+		process.stdout.write(`${JSON.stringify({ enabled: config.enabled, valid: errors.length === 0, errors })}\n`);
+		return;
+	}
+
+	process.stdout.write(`Telegram Remote: ${config.enabled ? "enabled" : "disabled"}\n`);
+	process.stdout.write(`Backend: ${config.backend}\n`);
+
+	if (config.botToken) process.stdout.write(`Bot Token: ✓ set\n`);
+	else process.stdout.write(`Bot Token: ✗ missing\n`);
+
+	if (config.allowedUserIds || config.allowedChatIds) {
+		process.stdout.write(`Allowlist: ✓ configured\n`);
+	} else {
+		process.stdout.write(`Allowlist: ✗ missing\n`);
+	}
+
+	if (errors.length > 0) {
+		process.stdout.write("\nConfiguration issues:\n");
+		for (const err of errors) process.stdout.write(`  • ${err}\n`);
+	}
+}
+
+async function runEnv(): Promise<void> {
+	const config = readTelegramSettings();
+	const env = telegramSettingsToEnv(config);
+	for (const [key, value] of Object.entries(env)) {
+		process.stdout.write(`${key}=${value}\n`);
+	}
+}
+
+export async function runTelegramCommand(cmd: TelegramCommandArgs): Promise<void> {
+	if (!isSettingsInitialized()) await Settings.init();
+	switch (cmd.action) {
+		case "start":
+			await runStart();
+			return;
+		case "status":
+			await runStatus(cmd.flags);
+			return;
+		case "env":
+			await runEnv();
+			return;
+		case "__gateway": {
+			// Hidden entrypoint: run the Telegram Remote gateway in-process. Reached
+			// only via the self-spawn from runStart()/autostart, never by users.
+			const { loadConfigFromEnv, runService } = await import("../../../telegram-remote/src/index");
+			await runService(loadConfigFromEnv(process.env));
+			return;
+		}
+	}
+}

package/src/cli/update-cli.ts

@@ -10,10 +10,13 @@ import { pipeline } from "node:stream/promises";
 import { $which, APP_NAME, isEnoent, VERSION } from "@sayknow-cli/utils";
 import { $ } from "bun";
 import chalk from "chalk";
+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;
 
 interface ReleaseInfo {
 	tag: string;
@@ -27,6 +30,23 @@ export interface InstalledVersionVerification {
 	path?: string;
 	smokeTestFailed?: boolean;
 	smokeTestOutput?: string;
+	cleanupWarning?: string;
+}
+
+export interface PackageManagerUpdateResult {
+	exitCode: number | null;
+	text: () => string;
+}
+
+export type PackageManagerUpdateRunner = (expectedVersion: string) => Promise<PackageManagerUpdateResult>;
+
+export interface PackageManagerUpdateOptions {
+	managerName: string;
+	expectedVersion: string;
+	runInstall: PackageManagerUpdateRunner;
+	verifyInstalledRuntime: (expectedVersion: string) => Promise<InstalledVersionVerification>;
+	printVerificationResult?: (expectedVersion: string) => Promise<void>;
+	printRecoveredVerification?: (expectedVersion: string) => void;
 }
 
 /** Paths and verifier used while replacing a downloaded binary update. */
@@ -102,23 +122,76 @@ function isPathInDirectory(filePath: string, directoryPath: string): boolean {
 	return isPathInDirectoryLexical(resolvedFile, dirReal);
 }
 
-type UpdateTarget = { method: "bun" } | { method: "binary"; path: string };
+type PackageManagerTarget = { manager: "npm"; packageName: string };
+type UpdateTarget = { method: "bun" } | { method: "npm"; packageName: string } | { method: "binary"; path: string };
+
+type PathPlatform = NodeJS.Platform;
+type PackageExists = (packageName: string, packageRoot: string) => boolean;
+
+function pathApiForPlatform(platform: PathPlatform): typeof path.posix | typeof path.win32 {
+	return platform === "win32" ? path.win32 : path.posix;
+}
+
+function defaultPackageExists(_packageName: string, packageRoot: string): boolean {
+	return fs.existsSync(path.join(packageRoot, "package.json"));
+}
+
+function npmPackageRootForBinPath(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 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;
+
+	for (const packageName of NPM_MANAGED_PACKAGES) {
+		const packageRoot = npmPackageRootForBinPath(ompPath, packageName, platform);
+		if (packageExists(packageName, packageRoot)) return { manager: "npm", packageName };
+	}
+	return undefined;
+}
 
-function resolveUpdateMethod(ompPath: string, bunBinDir: string | undefined): "bun" | "binary" {
+function resolveUpdateMethod(ompPath: string, bunBinDir: string | undefined): "bun" | "npm" | "binary" {
+	if (resolveNpmManagedTarget(ompPath)) return "npm";
 	if (!bunBinDir) return "binary";
 	return isPathInDirectory(ompPath, bunBinDir) ? "bun" : "binary";
 }
 
-export function resolveUpdateMethodForTest(ompPath: string, bunBinDir: string | undefined): "bun" | "binary" {
+export function resolveUpdateMethodForTest(ompPath: string, bunBinDir: string | undefined): "bun" | "npm" | "binary" {
 	return resolveUpdateMethod(ompPath, bunBinDir);
 }
+
+export function resolveNpmManagedTargetForTest(
+	ompPath: string,
+	platform: PathPlatform,
+	packageExists: PackageExists,
+): PackageManagerTarget | undefined {
+	return resolveNpmManagedTarget(ompPath, platform, packageExists);
+}
 async function resolveUpdateTarget(): Promise<UpdateTarget> {
 	const bunBinDir = await getBunGlobalBinDir();
 	const ompPath = resolveSkcPath();
 
 	if (ompPath) {
+		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 };
 	}
 
@@ -262,6 +335,11 @@ function printVerifiedVersion(expectedVersion: string): void {
 	console.log(chalk.green(`\n${theme.status.success} Updated to ${expectedVersion}`));
 }
 
+function printSuccessfulVerification(expectedVersion: string): void {
+	printVerifiedVersion(expectedVersion);
+	printRestartGuidance();
+}
+
 function formatBinaryInstallInstruction(platform: NodeJS.Platform = process.platform): string {
 	if (platform === "win32") {
 		return `For a supported binary install, reinstall with PowerShell: irm https://raw.githubusercontent.com/${RELEASE_REPO}/main/scripts/install.ps1 | iex`;
@@ -351,8 +429,7 @@ export function formatVerificationFailureForTest(
 async function printVerification(expectedVersion: string): Promise<void> {
 	const result = await verifyInstalledRuntime(expectedVersion);
 	if (result.ok) {
-		printVerifiedVersion(expectedVersion);
-		printRestartGuidance();
+		printSuccessfulVerification(expectedVersion);
 		return;
 	}
 	console.log(chalk.yellow(`\nWarning: ${formatVerificationFailure(result, expectedVersion)}`));
@@ -367,6 +444,19 @@ async function unlinkIfExists(filePath: string): Promise<void> {
 	}
 }
 
+function formatBackupCleanupWarning(backupPath: string, err: unknown): string {
+	return `Installed update, but could not remove backup file ${backupPath}: ${err}. You can delete it manually after closing shells or antivirus processes that may still hold it.`;
+}
+
+async function cleanupVerifiedBackup(backupPath: string): Promise<string | undefined> {
+	try {
+		await unlinkIfExists(backupPath);
+		return undefined;
+	} catch (err) {
+		return formatBackupCleanupWarning(backupPath, err);
+	}
+}
+
 /**
  * Atomically replace the installed binary and roll back if version verification fails.
  */
@@ -386,8 +476,8 @@ export async function replaceBinaryForUpdate(options: BinaryReplacementOptions):
 		}
 
 		backupReady = false;
-		await unlinkIfExists(options.backupPath);
-		return verification;
+		const cleanupWarning = await cleanupVerifiedBackup(options.backupPath);
+		return cleanupWarning ? { ...verification, cleanupWarning } : verification;
 	} catch (err) {
 		if (backupReady) {
 			await unlinkIfExists(options.targetPath);
@@ -398,17 +488,67 @@ export async function replaceBinaryForUpdate(options: BinaryReplacementOptions):
 	}
 }
 
+function formatPackageManagerInstallFailure(
+	managerName: string,
+	result: PackageManagerUpdateResult,
+	verification: InstalledVersionVerification,
+	expectedVersion: string,
+): string {
+	const output = normalizeVerificationOutput(result.text());
+	const outputSuffix = output ? `: ${output}` : "";
+	return `${managerName} install failed with exit code ${result.exitCode ?? "unknown"}${outputSuffix}. ${formatVerificationFailure(verification, expectedVersion)}`;
+}
+
+export async function runPackageManagerUpdateForTest(
+	options: PackageManagerUpdateOptions,
+): Promise<InstalledVersionVerification> {
+	return updateViaPackageManager(options);
+}
+
+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) {
+		console.warn(
+			chalk.yellow(
+				`${options.managerName} exited with ${result.exitCode ?? "unknown"}, but ${APP_NAME} now verifies as ${options.expectedVersion}. Treating the update as installed.`,
+			),
+		);
+		(options.printRecoveredVerification ?? printSuccessfulVerification)(options.expectedVersion);
+		return verification;
+	}
+
+	throw new Error(
+		formatPackageManagerInstallFailure(options.managerName, result, verification, options.expectedVersion),
+	);
+}
+
 /**
  * Update via bun package manager.
  */
 async function updateViaBun(expectedVersion: string): Promise<void> {
 	console.log(chalk.dim("Updating via bun..."));
-	const result = await $`bun install -g ${PACKAGE}@${expectedVersion}`.nothrow();
-	if (result.exitCode !== 0) {
-		throw new Error(`bun install failed with exit code ${result.exitCode}`);
-	}
+	await updateViaPackageManager({
+		managerName: "bun",
+		expectedVersion,
+		runInstall: async version => await $`bun install -g ${PACKAGE}@${version}`.nothrow(),
+		verifyInstalledRuntime,
+	});
+}
 
-	await printVerification(expectedVersion);
+async function updateViaNpm(packageName: string, expectedVersion: string): Promise<void> {
+	console.log(chalk.dim(`Updating npm-managed install via npm (${packageName})...`));
+	await updateViaPackageManager({
+		managerName: "npm",
+		expectedVersion,
+		runInstall: async version => await $`npm install -g ${packageName}@${version}`.nothrow(),
+		verifyInstalledRuntime,
+	});
 }
 
 /**
@@ -430,7 +570,7 @@ async function updateViaBinaryAt(targetPath: string, expectedVersion: string): P
 	await pipeline(response.body, fileStream);
 
 	console.log(chalk.dim("Installing update..."));
-	await replaceBinaryForUpdate({
+	const verification = await replaceBinaryForUpdate({
 		targetPath,
 		tempPath,
 		backupPath,
@@ -438,6 +578,7 @@ async function updateViaBinaryAt(targetPath: string, expectedVersion: string): P
 		verifyInstalledVersion: verifyInstalledRuntime,
 	});
 	printVerifiedVersion(expectedVersion);
+	if (verification.cleanupWarning) console.warn(chalk.yellow(verification.cleanupWarning));
 	printRestartGuidance();
 }
 
@@ -479,6 +620,8 @@ export async function runUpdateCommand(opts: { force: boolean; check: boolean })
 		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);
 		}
@@ -486,6 +629,29 @@ export async function runUpdateCommand(opts: { force: boolean; check: boolean })
 		console.error(chalk.red(`Update failed: ${err}`));
 		process.exit(1);
 	}
+
+	await refreshInstalledDefaultSkills();
+}
+
+/**
+ * Refresh opted-in on-disk default workflow skill copies after a successful
+ * update. The four default skills ship embedded in the binary, so most users
+ * need nothing here. But users who ran `skc setup defaults` have on-disk copies
+ * under the agent dir that shadow the embedded defaults; those would otherwise
+ * go stale after an update. Only rewrite files that already exist and differ —
+ * never materialize new copies for users who never opted in.
+ */
+async function refreshInstalledDefaultSkills(): Promise<void> {
+	try {
+		const result = await installDefaultSkcDefinitions({ refreshOnly: true });
+		if (result.written > 0) {
+			console.log(
+				chalk.dim(`Refreshed ${result.written} local default workflow skill file(s) at ${result.targetRoot}`),
+			);
+		}
+	} catch (err) {
+		console.error(chalk.yellow(`Warning: failed to refresh local default workflow skills: ${err}`));
+	}
 }
 
 /**

package/src/cli/web-search-cli.ts

@@ -9,13 +9,14 @@ import chalk from "chalk";
 import { Settings } from "../config/settings";
 import { initTheme, theme } from "../modes/theme/theme";
 import {
+	getConfiguredSearchProviderPreference,
 	isConfigurableSearchProviderId,
 	isSearchProviderPreference,
 	runSearchQuery,
 	type SearchQueryParams,
 } from "../web/search/index";
 import { SEARCH_PROVIDER_ORDER, setPreferredSearchProvider, setSearchFallbackProviders } from "../web/search/provider";
-import { setSearchHardTimeoutMs } from "../web/search/providers/utils";
+import { applyConfiguredSearchTimeout } from "../web/search/providers/utils";
 import { renderSearchResult } from "../web/search/render";
 import type { SearchProviderId } from "../web/search/types";
 
@@ -170,8 +171,8 @@ export async function runSearchCommand(cmd: SearchCommandArgs): Promise<void> {
 
 	await initTheme();
 	const settings = await Settings.init();
-	const configuredProvider = settings.get("providers.webSearch");
-	if (typeof configuredProvider === "string" && isSearchProviderPreference(configuredProvider)) {
+	const configuredProvider = getConfiguredSearchProviderPreference(settings);
+	if (isSearchProviderPreference(configuredProvider)) {
 		setPreferredSearchProvider(configuredProvider);
 	}
 	const configuredFallback = settings.get("web_search.fallback");
@@ -180,10 +181,7 @@ export async function runSearchCommand(cmd: SearchCommandArgs): Promise<void> {
 			configuredFallback.filter(value => typeof value === "string" && isConfigurableSearchProviderId(value)),
 		);
 	}
-	const configuredTimeout = settings.get("web_search.timeout");
-	if (typeof configuredTimeout === "number" && Number.isFinite(configuredTimeout) && configuredTimeout > 0) {
-		setSearchHardTimeoutMs(configuredTimeout * 1000);
-	}
+	applyConfiguredSearchTimeout(settings);
 
 	const params: SearchQueryParams = {
 		query: cmd.query,

package/src/cli.ts

@@ -38,6 +38,7 @@ export const commands: CommandEntry[] = [
 	{ name: "notify", load: () => import("./commands/notify").then(m => m.default) },
 	{ name: "daemon", load: () => import("./commands/daemon").then(m => m.default) },
 	{ name: "web-search", aliases: ["q"], load: () => import("./commands/web-search").then(m => m.default) },
+	{ name: "local-provider", load: () => import("./commands/local-provider").then(m => m.default) },
 	{ name: "mcp-serve", load: () => import("./commands/mcp-serve").then(m => m.default) },
 	{ name: "mcp", load: () => import("./commands/mcp").then(m => m.default) },
 	{
@@ -51,6 +52,7 @@ export const commands: CommandEntry[] = [
 	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
 	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
 	{ name: "launch", load: () => import("./commands/launch").then(m => m.default) },
+	{ name: "telegram", load: () => import("./commands/telegram").then(m => m.default) },
 ];
 
 async function showHelp(config: CliConfig): Promise<void> {
@@ -79,6 +81,19 @@ async function installRuntimeGlobals(): Promise<void> {
 	delete process.env.MallocStackLoggingNoCompact;
 }
 
+function isNotifyDaemonInternalFastPath(argv: string[]): boolean {
+	return argv[0] === "notify" && argv[1] === "daemon-internal";
+}
+
+async function runNotifyDaemonInternalFastPath(argv: string[]): Promise<void> {
+	const { parseNotifyArgs, runNotifyCommand } = await import("./cli/notify-cli");
+	const cmd = parseNotifyArgs(argv);
+	if (cmd?.action !== "daemon-internal") {
+		throw new Error("invalid notify daemon-internal fast path");
+	}
+	await runNotifyCommand(cmd);
+}
+
 function hasRootFastFlag(argv: string[], flags: readonly string[]): boolean {
 	for (const arg of argv) {
 		if (isSubcommand(arg)) return false;
@@ -126,7 +141,7 @@ class RootHelpCommand extends Command {
 		resume: Flags.string({ char: "r", description: "Resume a session (by ID prefix, path, or picker if omitted)" }),
 		"session-dir": Flags.string({ description: "Directory for session storage and lookup" }),
 		"no-session": Flags.boolean({ description: "Don't save session (ephemeral)" }),
-		models: Flags.string({ description: "Comma-separated model patterns for Ctrl+P cycling" }),
+		models: Flags.string({ description: "Comma-separated model patterns for Alt+N cycling" }),
 		"no-tools": Flags.boolean({ description: "Disable all built-in tools" }),
 		"no-lsp": Flags.boolean({ description: "Disable LSP tools, formatting, and diagnostics" }),
 		"no-pty": Flags.boolean({ description: "Disable PTY-based interactive bash execution" }),
@@ -208,6 +223,10 @@ async function runSmokeTest(): Promise<void> {
 
 /** Run the CLI with the given argv (no `process.argv` prefix). */
 export async function runCli(argv: string[]): Promise<void> {
+	if (isNotifyDaemonInternalFastPath(argv)) {
+		await runNotifyDaemonInternalFastPath(argv);
+		return;
+	}
 	if (argv[0] === "--smoke-test") {
 		await runSmokeTest();
 		return;

package/src/commands/launch.ts

@@ -2,6 +2,8 @@
  * Root command for the coding agent CLI.
  */
 
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
 import { THINKING_EFFORTS } from "@sayknow-cli/ai";
 import { APP_NAME, setProjectDir } from "@sayknow-cli/utils";
 import { Args, Command, Flags } from "@sayknow-cli/utils/cli";
@@ -10,6 +12,43 @@ import { runRootCommand } from "../main";
 import { prepareAcpTerminalAuthArgs } from "../modes/acp/terminal-auth";
 import { launchDefaultTmuxIfNeeded } from "../skc-runtime/launch-tmux";
 import { prepareLaunchWorktree } from "../skc-runtime/launch-worktree";
+import {
+	SKC_COORDINATOR_SESSION_ID_ENV,
+	SKC_COORDINATOR_SESSION_STATE_FILE_ENV,
+} from "../skc-runtime/session-state-sidecar";
+
+async function persistCoordinatorLaunchFailure(error: unknown, cwd: string): Promise<void> {
+	const stateFile = process.env[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]?.trim();
+	if (!stateFile) return;
+	const message = error instanceof Error ? error.message : String(error);
+	const code = message.split(":", 1)[0] || "launch_failed";
+	const now = new Date().toISOString();
+	const payload = {
+		schema_version: 1,
+		session_id: process.env[SKC_COORDINATOR_SESSION_ID_ENV]?.trim() || null,
+		state: "errored",
+		ready_for_input: false,
+		updated_at: now,
+		current_turn_id: null,
+		last_turn_id: null,
+		live: false,
+		reason: code,
+		source: "agent_session_event",
+		event: "launch_error",
+		cwd,
+		session_file: null,
+		final_response: {
+			text: message,
+			format: "markdown",
+			source: "launch_error",
+			artifact_path: null,
+			truncated: false,
+		},
+		error: { code, message, recoverable: true },
+	};
+	await fs.mkdir(path.dirname(stateFile), { recursive: true });
+	await Bun.write(stateFile, `${JSON.stringify(payload, null, 2)}\n`);
+}
 
 export default class Index extends Command {
 	static description = "Sayknow-CLI — an AI coding assistant";
@@ -80,7 +119,7 @@ export default class Index extends Command {
 			description: "Don't save session (ephemeral)",
 		}),
 		models: Flags.string({
-			description: "Comma-separated model patterns for Ctrl+P cycling",
+			description: "Comma-separated model patterns for Alt+N cycling",
 		}),
 		"no-tools": Flags.boolean({
 			description: "Disable all built-in tools",
@@ -157,7 +196,13 @@ export default class Index extends Command {
 			return;
 		}
 
-		const launch = prepareLaunchWorktree(process.cwd(), args);
+		let launch: ReturnType<typeof prepareLaunchWorktree>;
+		try {
+			launch = prepareLaunchWorktree(process.cwd(), args);
+		} catch (error) {
+			await persistCoordinatorLaunchFailure(error, process.cwd());
+			throw error;
+		}
 		if (launch.worktree.enabled) {
 			process.chdir(launch.cwd);
 			setProjectDir(launch.cwd);

package/src/commands/local-provider.ts

@@ -0,0 +1,62 @@
+/**
+ * Test configured local OpenAI-compatible providers.
+ */
+import { Args, Command, Flags } from "@sayknow-cli/utils/cli";
+import {
+	runLocalProviderDiscoverCommand,
+	runLocalProviderSmokeCommand,
+	runLocalProviderStatusCommand,
+} from "../cli/local-provider-smoke";
+
+export const LOCAL_PROVIDER_ACTIONS = ["status", "diagnose", "discover", "models", "smoke"] as const;
+export const LOCAL_PROVIDER_DEFAULT_ACTION = "status";
+
+export default class LocalProvider extends Command {
+	static description = "Diagnose configured local OpenAI-compatible providers";
+
+	static args = {
+		action: Args.string({ description: "Action", required: false, options: LOCAL_PROVIDER_ACTIONS }),
+	};
+
+	static flags = {
+		model: Flags.string({ description: "Model id to use for smoke (otherwise uses the first /models id)" }),
+		"models-path": Flags.string({ description: "Override models config path" }),
+		"timeout-ms": Flags.integer({ description: "Request timeout in milliseconds" }),
+		smoke: Flags.boolean({ description: "Run optional streaming chat smoke during status/diagnose" }),
+		json: Flags.boolean({ description: "Output JSON" }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(LocalProvider);
+		const action = args.action ?? LOCAL_PROVIDER_DEFAULT_ACTION;
+		if (action === "status" || action === "diagnose") {
+			await runLocalProviderStatusCommand({
+				model: flags.model,
+				modelsPath: flags["models-path"],
+				timeoutMs: flags["timeout-ms"],
+				smoke: flags.smoke,
+				json: flags.json,
+			});
+			return;
+		}
+		if (action === "discover" || action === "models") {
+			await runLocalProviderDiscoverCommand({
+				modelsPath: flags["models-path"],
+				timeoutMs: flags["timeout-ms"],
+				json: flags.json,
+			});
+			return;
+		}
+		if (action === "smoke") {
+			await runLocalProviderSmokeCommand({
+				model: flags.model,
+				modelsPath: flags["models-path"],
+				timeoutMs: flags["timeout-ms"],
+				json: flags.json,
+			});
+			return;
+		}
+		process.stderr.write(`Unsupported local-provider action: ${action}\n`);
+		process.exitCode = 1;
+	}
+}