@sayknow-cli/coding-agent 0.5.1 → 0.5.6

package/src/cli/config-cli.ts

@@ -88,6 +88,10 @@ function redactConfigValue(path: string, value: unknown, showSecrets?: boolean):
 	}
 	return REDACTED_SECRET_VALUE;
 }
+function reportConfigPersistenceFailure(): never {
+	console.error(chalk.red("Failed to persist configuration."));
+	process.exit(1);
+}
 
 /** Find setting definition by path */
 function findSettingDef(path: string): CliSettingDef | undefined {
@@ -223,25 +227,25 @@ function parseAndSetValue(path: SettingPath, rawValue: string): void {
 			const lower = trimmed.toLowerCase();
 			if (["true", "1", "yes", "on"].includes(lower)) parsedValue = true;
 			else if (["false", "0", "no", "off"].includes(lower)) parsedValue = false;
-			else throw new Error(`Invalid boolean value: ${rawValue}. Use true/false, yes/no, on/off, or 1/0`);
+			else throw new Error("Invalid boolean value. Use true/false, yes/no, on/off, or 1/0");
 			break;
 		}
 		case "number": {
 			parsedValue = Number(trimmed);
-			if (!Number.isFinite(parsedValue)) throw new Error(`Invalid number: ${rawValue}`);
+			if (!Number.isFinite(parsedValue)) throw new Error("Invalid number");
 			const validate =
 				"validate" in SETTINGS_SCHEMA[path]
 					? (SETTINGS_SCHEMA[path].validate as ((value: number) => boolean) | undefined)
 					: undefined;
 			if (validate?.(parsedValue as number) === false) {
-				throw new Error(`Invalid number for ${path}: ${rawValue}`);
+				throw new Error(`Invalid number for ${path}`);
 			}
 			break;
 		}
 		case "enum": {
 			const valid = getEnumValues(path);
 			if (valid && !valid.includes(trimmed)) {
-				throw new Error(`Invalid value: ${rawValue}. Valid values: ${valid.join(", ")}`);
+				throw new Error(`Invalid value. Valid values: ${valid.join(", ")}`);
 			}
 			parsedValue = trimmed;
 			break;
@@ -251,10 +255,10 @@ function parseAndSetValue(path: SettingPath, rawValue: string): void {
 			try {
 				parsed = JSON.parse(trimmed);
 			} catch {
-				throw new Error(`Invalid array JSON: ${rawValue}`);
+				throw new Error("Invalid array JSON");
 			}
 			if (!Array.isArray(parsed)) {
-				throw new Error(`Invalid array JSON: ${rawValue}`);
+				throw new Error("Invalid array JSON");
 			}
 			parsedValue = parsed;
 			break;
@@ -264,10 +268,10 @@ function parseAndSetValue(path: SettingPath, rawValue: string): void {
 			try {
 				parsed = JSON.parse(trimmed);
 			} catch {
-				throw new Error(`Invalid record JSON: ${rawValue}`);
+				throw new Error("Invalid record JSON");
 			}
 			if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-				throw new Error(`Invalid record JSON: ${rawValue}`);
+				throw new Error("Invalid record JSON");
 			}
 			parsedValue = parsed;
 			break;
@@ -408,6 +412,11 @@ async function handleSet(
 		console.error(chalk.red(String(err)));
 		process.exit(1);
 	}
+	try {
+		await settings.flushOrThrow();
+	} catch {
+		reportConfigPersistenceFailure();
+	}
 
 	const newValue = settings.get(def.path);
 	const displayValue = redactConfigValue(def.path, newValue, flags.showSecrets);
@@ -438,6 +447,12 @@ async function handleReset(key: string | undefined, flags: { json?: boolean }):
 	if (defaultValue === undefined) settings.unset(path);
 	else settings.set(path, defaultValue as SettingValue<typeof path>);
 
+	try {
+		await settings.flushOrThrow();
+	} catch {
+		reportConfigPersistenceFailure();
+	}
+
 	if (flags.json) {
 		console.log(JSON.stringify({ key: def.path, value: defaultValue }));
 	} else {

package/src/cli/update-cli.ts

@@ -4,6 +4,7 @@
  * Handles `skc update` to check for and install updates.
  * Uses bun if available, otherwise downloads binary from GitHub releases.
  */
+import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { pipeline } from "node:stream/promises";
@@ -17,6 +18,8 @@ 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 BINARY_MANIFEST_ASSET = "sayknow-release-binaries-v1.json";
+const BINARY_SHA256_ASSET = "sayknow-release-binaries.sha256";
 
 interface ReleaseInfo {
 	tag: string;
@@ -272,11 +275,21 @@ function getBinaryName(platform: NodeJS.Platform = process.platform, arch: strin
 	}
 
 	if (os === "windows") {
+		if (archName !== "x64") {
+			throw new Error(formatUnsupportedTargetMessage(`Unsupported architecture for Windows: ${arch}`));
+		}
 		return `${APP_NAME}-${os}-${archName}.exe`;
 	}
 	return `${APP_NAME}-${os}-${archName}`;
 }
 
+export function getBinaryNameForTest(
+	platform: NodeJS.Platform = process.platform,
+	arch: string = process.arch,
+): string {
+	return getBinaryName(platform, arch);
+}
+
 /**
  * Resolve the path that `skc` maps to in the user's PATH.
  */
@@ -367,10 +380,89 @@ function buildReleaseBinaryUrl(
 	arch: string = process.arch,
 ): string {
 	const binaryName = getBinaryName(platform, arch);
-	const tag = `v${version}`;
+	const tag = `sayknow-v${version}`;
 	return `https://github.com/${RELEASE_REPO}/releases/download/${tag}/${binaryName}`;
 }
 
+function buildReleaseAssetUrl(version: string, assetName: string): string {
+	return `https://github.com/${RELEASE_REPO}/releases/download/sayknow-v${version}/${assetName}`;
+}
+
+function parseExpectedDigestFromSums(text: string, assetName: string): string | undefined {
+	const matches: string[] = [];
+	for (const line of text.split(/\r?\n/)) {
+		const match = line.trim().match(/^([a-fA-F0-9]{64}) {2}[ *]?([^/\\]+)$/);
+		if (match?.[2] === assetName) matches.push(match[1]!.toLowerCase());
+	}
+	if (matches.length > 1) throw new Error(`Release checksum file lists ${assetName} more than once`);
+	return matches[0];
+}
+
+function expectedDigestFromManifest(value: unknown, version: string, assetName: string): string {
+	if (!value || typeof value !== "object") throw new Error("Release binary manifest is not an object");
+	const manifest = value as Record<string, unknown>;
+	if (
+		manifest.schema !== "sayknow-release-binaries-v1" ||
+		manifest.schema_version !== 1 ||
+		manifest.release_version !== version ||
+		manifest.tag !== `sayknow-v${version}` ||
+		!Array.isArray(manifest.binaries)
+	) {
+		throw new Error("Release binary manifest metadata does not match the requested release");
+	}
+	const matches = manifest.binaries.filter(
+		entry => entry && typeof entry === "object" && (entry as Record<string, unknown>).name === assetName,
+	) as Array<Record<string, unknown>>;
+	if (matches.length !== 1 || typeof matches[0]?.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(matches[0].sha256)) {
+		throw new Error(`Release binary manifest does not contain one valid SHA-256 for ${assetName}`);
+	}
+	return matches[0].sha256;
+}
+
+export async function fetchExpectedBinaryDigest(
+	version: string,
+	assetName: string,
+	fetchImpl: (url: string) => Promise<Response> = fetch,
+): Promise<string> {
+	const sumsResponse = await fetchImpl(buildReleaseAssetUrl(version, BINARY_SHA256_ASSET));
+	if (sumsResponse.ok) {
+		const digest = parseExpectedDigestFromSums(await sumsResponse.text(), assetName);
+		if (!digest) throw new Error(`Release checksum file does not list ${assetName}`);
+		return digest;
+	}
+	if (sumsResponse.status !== 404) {
+		throw new Error(`Release checksum file could not be fetched: HTTP ${sumsResponse.status}`);
+	}
+
+	const manifestResponse = await fetchImpl(buildReleaseAssetUrl(version, BINARY_MANIFEST_ASSET));
+	if (!manifestResponse.ok) {
+		if (manifestResponse.status === 404) {
+			throw new Error(`Release ${version} has no Sayknow binary integrity manifest`);
+		}
+		throw new Error(`Release binary manifest could not be fetched: HTTP ${manifestResponse.status}`);
+	}
+	return expectedDigestFromManifest(await manifestResponse.json(), version, assetName);
+}
+
+async function sha256File(filePath: string): Promise<string> {
+	const hash = createHash("sha256");
+	for await (const chunk of fs.createReadStream(filePath)) hash.update(chunk);
+	return hash.digest("hex");
+}
+
+export async function verifyReleaseBinaryIntegrity(
+	filePath: string,
+	version: string,
+	assetName: string,
+	fetchImpl: (url: string) => Promise<Response> = fetch,
+): Promise<void> {
+	const expected = await fetchExpectedBinaryDigest(version, assetName, fetchImpl);
+	const actual = await sha256File(filePath);
+	if (actual !== expected) {
+		throw new Error(`SHA-256 mismatch for ${assetName}: expected ${expected}, got ${actual}`);
+	}
+}
+
 function formatBinaryDownloadFailureMessage(
 	binaryName: string,
 	url: string,
@@ -439,42 +531,186 @@ function formatBackupCleanupWarning(backupPath: string, err: unknown): string {
 
 async function cleanupVerifiedBackup(backupPath: string): Promise<string | undefined> {
 	try {
-		await unlinkIfExists(backupPath);
+		await unlinkDurably(backupPath);
 		return undefined;
 	} catch (err) {
 		return formatBackupCleanupWarning(backupPath, err);
 	}
 }
 
+async function pathExists(filePath: string): Promise<boolean> {
+	try {
+		await fs.promises.lstat(filePath);
+		return true;
+	} catch (err) {
+		if (isEnoent(err)) return false;
+		throw err;
+	}
+}
+
+async function syncParentDirectory(filePath: string): Promise<void> {
+	// Node cannot portably fsync directory handles on Windows. NTFS journals the
+	// rename operations used below; POSIX platforms require an explicit parent sync.
+	if (process.platform === "win32") return;
+	const handle = await fs.promises.open(path.dirname(filePath), "r");
+	try {
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
+
+async function unlinkDurably(filePath: string): Promise<void> {
+	await unlinkIfExists(filePath);
+	await syncParentDirectory(filePath);
+}
+
+async function renameDurably(sourcePath: string, targetPath: string): Promise<void> {
+	await fs.promises.rename(sourcePath, targetPath);
+	await syncParentDirectory(targetPath);
+	if (path.dirname(sourcePath) !== path.dirname(targetPath)) await syncParentDirectory(sourcePath);
+}
+
+export async function withBinaryUpdateLock<T>(targetPath: string, operation: () => Promise<T>): Promise<T> {
+	const lockPath = path.join(path.dirname(targetPath), ".skc-install.lock");
+	try {
+		await fs.promises.mkdir(lockPath);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "EEXIST") {
+			throw new Error(`Another SKC installer or update is already running (lock: ${lockPath}).`);
+		}
+		throw err;
+	}
+	try {
+		await fs.promises.writeFile(
+			path.join(lockPath, "owner.json"),
+			JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }),
+			{ flag: "wx" },
+		);
+		return await operation();
+	} finally {
+		await fs.promises.rm(lockPath, { recursive: true, force: true });
+	}
+}
+
+type BinaryReplacementPhase = "replacing" | "committed";
+
+interface BinaryReplacementState {
+	phase: BinaryReplacementPhase;
+	hadTarget: boolean;
+}
+
+function binaryReplacementStatePath(backupPath: string): string {
+	return `${backupPath}.state.json`;
+}
+
+async function readBinaryReplacementState(statePath: string): Promise<BinaryReplacementState | undefined> {
+	try {
+		const value = JSON.parse(await fs.promises.readFile(statePath, "utf8")) as Partial<BinaryReplacementState>;
+		if ((value.phase === "replacing" || value.phase === "committed") && typeof value.hadTarget === "boolean") {
+			return value as BinaryReplacementState;
+		}
+		return { phase: "replacing", hadTarget: true };
+	} catch (err) {
+		if (isEnoent(err)) return undefined;
+		return { phase: "replacing", hadTarget: true };
+	}
+}
+
+async function writeBinaryReplacementState(statePath: string, state: BinaryReplacementState): Promise<void> {
+	const handle = await fs.promises.open(statePath, "w", 0o600);
+	try {
+		await handle.writeFile(JSON.stringify(state));
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+	await syncParentDirectory(statePath);
+}
+
+async function recoverInterruptedBinaryReplacement(targetPath: string, backupPath: string): Promise<void> {
+	const statePath = binaryReplacementStatePath(backupPath);
+	const state = await readBinaryReplacementState(statePath);
+	if (!(await pathExists(backupPath))) {
+		if (state?.phase === "replacing" && state.hadTarget === false) {
+			await unlinkDurably(targetPath);
+		}
+		await unlinkDurably(statePath);
+		return;
+	}
+	if (state?.phase === "committed" && (await pathExists(targetPath))) {
+		await unlinkDurably(backupPath);
+		await unlinkDurably(statePath);
+		return;
+	}
+	await unlinkDurably(targetPath);
+	await renameDurably(backupPath, targetPath);
+	await unlinkDurably(statePath);
+}
+
+async function cleanupCommittedReplacementState(statePath: string): Promise<string | undefined> {
+	try {
+		await unlinkDurably(statePath);
+		return undefined;
+	} catch (err) {
+		return `Installed update, but could not remove transaction state file ${statePath}: ${err}. The verified binary remains installed.`;
+	}
+}
+
 /**
  * Atomically replace the installed binary and roll back if version verification fails.
  */
 export async function replaceBinaryForUpdate(options: BinaryReplacementOptions): Promise<InstalledVersionVerification> {
+	const statePath = binaryReplacementStatePath(options.backupPath);
+	await recoverInterruptedBinaryReplacement(options.targetPath, options.backupPath);
+	await unlinkDurably(options.backupPath);
+	const hadTarget = await pathExists(options.targetPath);
 	let backupReady = false;
+	let publishedNew = false;
+	let verification: InstalledVersionVerification;
 	try {
-		await unlinkIfExists(options.backupPath);
-		await fs.promises.rename(options.targetPath, options.backupPath);
-		backupReady = true;
+		await writeBinaryReplacementState(statePath, {
+			phase: "replacing",
+			hadTarget,
+		});
+		try {
+			await fs.promises.rename(options.targetPath, options.backupPath);
+			backupReady = true;
+			await syncParentDirectory(options.backupPath);
+		} catch (err) {
+			if (!isEnoent(err)) throw err;
+		}
 		await fs.promises.rename(options.tempPath, options.targetPath);
+		publishedNew = true;
+		await syncParentDirectory(options.targetPath);
 
-		const verification = await options.verifyInstalledVersion(options.expectedVersion);
+		verification = await options.verifyInstalledVersion(options.expectedVersion);
 		if (!verification.ok) {
 			throw new Error(
 				`${formatVerificationFailure(verification, options.expectedVersion)}; restored previous ${APP_NAME} binary`,
 			);
 		}
 
+		await writeBinaryReplacementState(statePath, {
+			phase: "committed",
+			hadTarget,
+		});
 		backupReady = false;
-		const cleanupWarning = await cleanupVerifiedBackup(options.backupPath);
-		return cleanupWarning ? { ...verification, cleanupWarning } : verification;
 	} catch (err) {
 		if (backupReady) {
-			await unlinkIfExists(options.targetPath);
-			await fs.promises.rename(options.backupPath, options.targetPath);
+			await unlinkDurably(options.targetPath);
+			await renameDurably(options.backupPath, options.targetPath);
+		} else if (publishedNew) {
+			await unlinkDurably(options.targetPath);
 		}
-		await unlinkIfExists(options.tempPath);
+		await unlinkDurably(options.tempPath);
+		await unlinkDurably(statePath);
 		throw err;
 	}
+
+	let cleanupWarning = await cleanupVerifiedBackup(options.backupPath);
+	if (!cleanupWarning) cleanupWarning = await cleanupCommittedReplacementState(statePath);
+	return cleanupWarning ? { ...verification, cleanupWarning } : verification;
 }
 
 function formatPackageManagerInstallFailure(
@@ -594,17 +830,20 @@ async function downloadBinaryTo(url: string, tempPath: string, binaryName: strin
 /** Injectable steps of the binary update flow (seams for testing ordering). */
 export interface BinaryUpdateFlow {
 	download(url: string, tempPath: string): Promise<void>;
+	verifyIntegrity(filePath: 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>;
+	/** Stable suffix for focused tests; production uses a process-unique staging path. */
+	transactionId?: string;
 	/** Called once fsync has succeeded, right before replacement begins. */
 	beforeReplace?(): void;
 }
 
 /**
- * Orchestrate download → fsync → replace → verify with a strict ordering
+ * Orchestrate download → integrity verification → fsync → replace → version/smoke verification.
  * contract: the downloaded temp binary MUST be flushed to stable storage
  * before it is published (renamed into place) or exec'd for verification.
  *
@@ -618,11 +857,13 @@ export async function runBinaryUpdateFlow(
 	expectedVersion: string,
 	flow: BinaryUpdateFlow,
 ): Promise<InstalledVersionVerification> {
-	const tempPath = `${targetPath}.new`;
+	const transactionId = flow.transactionId ?? `${process.pid}.${randomUUID()}`;
+	const tempPath = `${targetPath}.new.${transactionId}`;
 	const backupPath = `${targetPath}.bak`;
 
 	await flow.download(url, tempPath);
 	try {
+		await flow.verifyIntegrity(tempPath);
 		await flow.fsync(tempPath);
 	} catch (err) {
 		if (flow.removeTemp) await flow.removeTemp(tempPath);
@@ -647,14 +888,17 @@ async function updateViaBinaryAt(targetPath: string, expectedVersion: string): P
 	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...")),
-	});
+	const verification = await withBinaryUpdateLock(targetPath, () =>
+		runBinaryUpdateFlow(targetPath, url, expectedVersion, {
+			download: (downloadUrl, tempPath) => downloadBinaryTo(downloadUrl, tempPath, binaryName),
+			verifyIntegrity: tempPath => verifyReleaseBinaryIntegrity(tempPath, expectedVersion, 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));

package/src/commands/session.ts

@@ -1,4 +1,13 @@
 import { Args, Command, Flags } from "@sayknow-cli/utils/cli";
+import { readBootGeneration } from "../skc-runtime/boot-generation";
+import {
+	decodeRestoreReference,
+	encodeRestoreReference,
+	evaluateRestoreCandidates,
+	listRestorePointers,
+	type RestoreCandidateVerdict,
+} from "../skc-runtime/session-restore";
+import { buildRestoreCandidateDeps, restoreSession } from "../skc-runtime/session-restore-runtime";
 import {
 	attachSkcTmuxSession,
 	createSkcTmuxSession,
@@ -45,12 +54,13 @@ function sessionJson(session: SessionJsonDto): SessionJsonDto {
 }
 
 export default class Session extends Command {
-	static description = "List, inspect, attach, and remove tagged SKC-managed tmux sessions";
+	static description =
+		"List, inspect, attach, and remove tagged SKC-managed tmux sessions. `restore` is a manual, opt-in recovery step that only ever restores sessions this machine can prove died in a REBOOT: nothing starts automatically at login, a session that is still live is never duplicated, and running tools or background work are not recovered — only the tmux session, its directory, and its conversation.";
 	static strict = false;
 
 	static args = {
 		action: Args.string({
-			description: "list (default), status, create, attach, or remove",
+			description: "list (default), status, create, attach, remove, or restore",
 			required: false,
 		}),
 		session: Args.string({
@@ -67,6 +77,15 @@ export default class Session extends Command {
 		"state-file": Flags.string({
 			description: "Expected @skc-session-state-file tag for force-close (defense-in-depth match)",
 		}),
+		"dry-run": Flags.boolean({
+			description:
+				"restore: list candidates and their verdicts. Changes nothing at all (no tmux command, no lock, no database, no pointer write). This is the default when no --reference is given.",
+			default: false,
+		}),
+		reference: Flags.string({
+			description:
+				"restore: restore exactly one candidate by the opaque reference shown in --dry-run output. Refused unless that candidate is still reboot-eligible at this moment.",
+		}),
 	};
 
 	static examples = [
@@ -76,6 +95,8 @@ export default class Session extends Command {
 		"skc session attach <session>",
 		"skc session remove <session>",
 		"skc session force-close <session> --session-id <id>",
+		"skc session restore --dry-run   # list what a reboot left behind",
+		"skc session restore --reference <ref>   # restore exactly that one",
 	];
 
 	async run(): Promise<void> {
@@ -105,6 +126,71 @@ export default class Session extends Command {
 				return;
 			}
 
+			if (action === "restore") {
+				// Manual, reboot-proven, opt-in. Nothing here starts automatically at
+				// login, and a session is only ever restored when this host can prove
+				// the machine rebooted since that session was recorded.
+				const reference = flags.reference;
+				const decoded = reference ? decodeRestoreReference(reference) : null;
+				if (reference && !decoded) throw new Error("invalid_restore_reference");
+				const pointers = listRestorePointers().filter(
+					pointer =>
+						!decoded ||
+						(pointer.coordinator_session_id === decoded.coordinatorSessionId &&
+							pointer.state_file === decoded.stateFile),
+				);
+				if (reference && pointers.length === 0) throw new Error("restore_reference_not_found");
+				const verdicts = evaluateRestoreCandidates(pointers, buildRestoreCandidateDeps(readBootGeneration()));
+				const describe = (verdict: RestoreCandidateVerdict) => ({
+					reference: encodeRestoreReference(verdict.pointer.coordinator_session_id, verdict.pointer.state_file),
+					sessionId: verdict.pointer.skc_session_id,
+					cwd: verdict.pointer.cwd,
+					branch: verdict.pointer.branch,
+					eligible: verdict.eligible,
+					...(verdict.eligible ? {} : { reason: verdict.reason }),
+				});
+				// Dry run is the default reporting surface and performs zero mutation:
+				// no pointer write, no lock, no SQLite, no tmux command.
+				if (flags["dry-run"] || !reference) {
+					const rows = verdicts.map(describe);
+					if (json) {
+						writeJson({ ok: true, dryRun: true, candidates: rows });
+						return;
+					}
+					writeText(
+						rows.length === 0
+							? ["no restore candidates"]
+							: rows.map(row =>
+									[
+										row.eligible ? "restorable" : `skipped(${row.reason})`,
+										row.sessionId,
+										row.cwd,
+										row.reference,
+									].join("\t"),
+								),
+					);
+					return;
+				}
+				const verdict = verdicts[0];
+				if (!verdict) throw new Error("restore_reference_not_found");
+				if (!verdict.eligible) throw new Error(`restore_ineligible_${verdict.reason}`);
+				const outcome = restoreSession(verdict.pointer);
+				if (!outcome.ok) throw new Error(outcome.detail);
+				if (json) {
+					writeJson({
+						ok: true,
+						restored: {
+							sessionId: outcome.pointer.skc_session_id,
+							cwd: outcome.pointer.cwd,
+							tmuxSession: outcome.tmuxSession,
+						},
+					});
+					return;
+				}
+				writeText([`restored: ${outcome.tmuxSession} (${outcome.pointer.skc_session_id})`]);
+				return;
+			}
+
 			if (action === "create") {
 				const session = createSkcTmuxSession();
 				if (json) {