handmux 0.23.0 → 0.25.0

package/dist/src/cli/tunnelClients.js

@@ -0,0 +1,72 @@
+// Resolve the natapp / cpolar client binaries, mirroring cloudflared.js. The two providers differ in one
+// hard way: cpolar publishes stable per-OS/arch zips, so we can AUTO-DOWNLOAD it (PATH → ~/.handmux/bin →
+// fetch+unzip); natapp gates its downloads behind a login, so there's no stable URL to fetch — we resolve an
+// already-installed binary and otherwise throw a clear "download it yourself into ~/.handmux/bin" message.
+// Pure mappers (assetForCpolar) are unit-tested offline; `which`/`fetchImpl` are injectable.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { pocketHome } from './state.js';
+import { onPath, drain, defaultProgress } from './cloudflared.js';
+import { t } from './i18n/index.js';
+// cpolar release asset for this OS/arch. Linux/macOS ship a bare binary inside a .zip; Windows ships a
+// `-setup.zip` INSTALLER (not a bare binary), so we don't auto-extract it — Windows users install manually.
+const CPOLAR_VERSION = '3.3.12';
+export function assetForCpolar(platform = process.platform, arch = process.arch) {
+    const a = { x64: 'amd64', arm64: 'arm64', arm: 'arm', ia32: '386' }[arch] || arch;
+    const base = `https://www.cpolar.com/static/downloads/releases/${CPOLAR_VERSION}`;
+    if (platform === 'win32')
+        return { bin: 'cpolar.exe', url: null }; // installer-only → manual
+    const file = `cpolar-stable-${platform === 'darwin' ? 'darwin' : 'linux'}-${a}.zip`;
+    return { bin: 'cpolar', file, url: `${base}/${file}` };
+}
+// PATH → ~/.handmux/bin/cpolar → download+unzip. Any download/extract failure surfaces the friendly manual
+// hint (t('client.cpolarManual')) so the worst case is "install it yourself", never a silent dead child.
+export async function resolveCpolar(home, { which = onPath, fetchImpl, log = console, progress } = {}) {
+    const found = which('cpolar');
+    if (found)
+        return found;
+    const dir = path.join(pocketHome(home), 'bin');
+    const asset = assetForCpolar();
+    const dest = path.join(dir, asset.bin);
+    if (fs.existsSync(dest))
+        return dest;
+    if (!asset.url)
+        throw new Error(t('client.cpolarManual')); // windows / unknown platform
+    const doFetch = fetchImpl || globalThis.fetch;
+    if (!doFetch)
+        throw new Error(t('client.cpolarManual'));
+    fs.mkdirSync(dir, { recursive: true });
+    log.log?.(t('client.downloading', { name: 'cpolar', file: asset.file }));
+    let res;
+    try {
+        res = await doFetch(asset.url, { redirect: 'follow' });
+    }
+    catch {
+        throw new Error(t('client.cpolarManual'));
+    }
+    if (!res.ok)
+        throw new Error(t('client.cpolarManual'));
+    const buf = await drain(res, progress || defaultProgress(process.stdout, 'cpolar'));
+    const tmp = path.join(dir, asset.file);
+    fs.writeFileSync(tmp, buf);
+    const r = spawnSync('unzip', ['-o', tmp, '-d', dir], { encoding: 'utf8' });
+    try {
+        fs.unlinkSync(tmp);
+    }
+    catch { /* best-effort cleanup */ }
+    if (r.status !== 0 || !fs.existsSync(dest))
+        throw new Error(t('client.cpolarManual'));
+    fs.chmodSync(dest, 0o755);
+    return dest;
+}
+// natapp: PATH → ~/.handmux/bin/natapp, else a clear manual-download hint (no auto-download — login-gated).
+export function resolveNatapp(home, { which = onPath } = {}) {
+    const found = which('natapp');
+    if (found)
+        return found;
+    const dest = path.join(pocketHome(home), 'bin', process.platform === 'win32' ? 'natapp.exe' : 'natapp');
+    if (fs.existsSync(dest))
+        return dest;
+    throw new Error(t('client.natappManual', { dir: path.join(pocketHome(home), 'bin') }));
+}

package/{src → dist/src}/cli/updateCheck.js

@@ -7,127 +7,156 @@
 //   2. The version query goes through the user's own npm (`npm view handmux version`), so it honours a
 //      configured China mirror / private registry instead of hard-coding registry.npmjs.org. Any failure
 //      (offline, blocked, npm missing) is swallowed — the notifier is best-effort, never an error.
-import fs from 'node:fs';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { pocketHome } from './state.js';
 import { t } from './i18n/index.js';
-
+import { PrivateStateStore } from '../privateStateStore.js';
 export const PKG_NAME = 'handmux';
 export const CHECK_INTERVAL_MS = 60 * 60 * 1000; // refresh the cached "latest" at most once an hour
-
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 // A Homebrew-installed handmux lives under the Cellar (…/Cellar/handmux/<ver>/…, symlinked from the brew
 // prefix's bin), or under a linuxbrew prefix. For such installs `handmux update` must NOT `npm i -g` over
 // itself — that plants a second, conflicting copy that brew can't see or upgrade — and the "how to upgrade"
 // hint must point at `brew upgrade` instead. Detect the source from the (real, symlink-resolved) entry path.
-export function isBrewInstall(selfPath = '') { return /\/(Cellar|homebrew)\//.test(selfPath); }
-
+export function isBrewInstall(selfPath = '') { return /\/(Cellar|homebrew)\//.test(String(selfPath)); }
 export function updateCachePath(home) { return path.join(pocketHome(home), 'update-check.json'); }
-
+function parseHighlights(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.flatMap((item) => {
+        if (!isRecord(item)
+            || typeof item.version !== 'string'
+            || typeof item.date !== 'string'
+            || typeof item.zh !== 'string'
+            || typeof item.en !== 'string')
+            return [];
+        return [{ version: item.version, date: item.date, zh: item.zh, en: item.en }];
+    });
+}
 export function readCache(home) {
-  try { return JSON.parse(fs.readFileSync(updateCachePath(home), 'utf8')); } catch { return null; }
+    const value = new PrivateStateStore(updateCachePath(home)).read();
+    if (!isRecord(value))
+        return null;
+    const cache = {};
+    if (typeof value.checkedAt === 'number' && Number.isFinite(value.checkedAt))
+        cache.checkedAt = value.checkedAt;
+    if (typeof value.latest === 'string' && parts(value.latest))
+        cache.latest = value.latest;
+    else if (value.latest === null)
+        cache.latest = null;
+    if (Array.isArray(value.whatsNew))
+        cache.whatsNew = parseHighlights(value.whatsNew);
+    else if (value.whatsNew === null)
+        cache.whatsNew = null;
+    return cache;
 }
-
 export function writeCache(home, obj) {
-  try {
-    fs.mkdirSync(pocketHome(home), { recursive: true });
-    fs.writeFileSync(updateCachePath(home), JSON.stringify(obj));
-  } catch { /* best effort — a missing cache just means we re-check next time */ }
+    try {
+        new PrivateStateStore(updateCachePath(home)).write(obj);
+    }
+    catch { /* best effort — a missing cache just means we re-check next time */ }
 }
-
 // "1.2.3" → [1,2,3]; a prerelease/build tail (`-rc.1`, `+meta`) is ignored. null if unparseable.
 function parts(v) {
-  const m = String(v || '').trim().match(/^v?(\d+)\.(\d+)\.(\d+)/);
-  return m ? [+m[1], +m[2], +m[3]] : null;
+    const m = String(v || '').trim().match(/^v?(\d+)\.(\d+)\.(\d+)/);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
 }
-
 // -1 / 0 / 1 by numeric major.minor.patch. Unparseable inputs compare equal (→ no false "upgrade").
 export function compareVersions(a, b) {
-  const pa = parts(a), pb = parts(b);
-  if (!pa || !pb) return 0;
-  for (let i = 0; i < 3; i++) if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
-  return 0;
+    const pa = parts(a), pb = parts(b);
+    if (!pa || !pb)
+        return 0;
+    for (let i = 0; i < 3; i++) {
+        const left = pa[i] ?? 0;
+        const right = pb[i] ?? 0;
+        if (left !== right)
+            return left < right ? -1 : 1;
+    }
+    return 0;
 }
-
 export function isNewer(latest, current) { return compareVersions(latest, current) > 0; }
-
 export function shouldRefresh(cache, now = Date.now(), interval = CHECK_INTERVAL_MS) {
-  return !cache || typeof cache.checkedAt !== 'number' || (now - cache.checkedAt) > interval;
+    return !isRecord(cache) || typeof cache.checkedAt !== 'number' || (now - cache.checkedAt) > interval;
 }
-
 // ONE npm call fetches both the latest version AND its concise `whatsNew` highlights (the published
 // package.json field release.sh mirrors from the changelog), so the phone can show "what's new" BEFORE
 // upgrading — sourced through the user's own npm, so it stays China-mirror-friendly. `@latest` + `--json`
 // makes npm return an object keyed by field: {"version":"0.9.1","whatsNew":[{version,date,zh,en},…]}.
 export const VIEW_ARGS = ['view', `${PKG_NAME}@latest`, 'version', 'whatsNew', '--json'];
-
 // Parse that JSON into { latest, whatsNew }. `latest` is null unless it's a real version; `whatsNew` is
 // null unless it's an array (old published versions predate the field). Never throws.
 export function parseView(stdout) {
-  try {
-    const o = JSON.parse(String(stdout));
-    const v = String(o.version || '').trim();
-    return { latest: parts(v) ? v : null, whatsNew: Array.isArray(o.whatsNew) ? o.whatsNew : null };
-  } catch { return { latest: null, whatsNew: null }; }
+    try {
+        const value = JSON.parse(String(stdout));
+        if (!isRecord(value))
+            return { latest: null, whatsNew: null };
+        const version = typeof value.version === 'string' ? value.version.trim() : '';
+        return { latest: parts(version) ? version : null, whatsNew: parseHighlights(value.whatsNew) };
+    }
+    catch {
+        return { latest: null, whatsNew: null };
+    }
 }
-
 // Query the latest version + highlights via the user's own npm (honours their registry/mirror). Hard
 // timeout; any non-zero exit, empty/garbled output, or thrown error → { latest:null, whatsNew:null }.
 export function fetchLatest({ timeoutMs = 4000, run = spawnSync } = {}) {
-  try {
-    const r = run('npm', VIEW_ARGS, { timeout: timeoutMs, encoding: 'utf8' });
-    if (!r || r.status !== 0 || !r.stdout) return { latest: null, whatsNew: null };
-    return parseView(r.stdout);
-  } catch { return { latest: null, whatsNew: null }; }
+    try {
+        const r = run('npm', VIEW_ARGS, { timeout: timeoutMs, encoding: 'utf8' });
+        if (!r || r.status !== 0 || !r.stdout)
+            return { latest: null, whatsNew: null };
+        return parseView(r.stdout);
+    }
+    catch {
+        return { latest: null, whatsNew: null };
+    }
 }
-
 // Merge a fetch result over the prior cache: on a failed field keep the previously-known value, so a flaky
 // network never blanks out a good `latest`/`whatsNew`. Always stamps `checkedAt`.
 function mergedCache(home, now, { latest, whatsNew }) {
-  const prev = readCache(home);
-  return { checkedAt: now, latest: latest ?? prev?.latest ?? null, whatsNew: whatsNew ?? prev?.whatsNew ?? null };
+    const prev = readCache(home);
+    return { checkedAt: now, latest: latest ?? prev?.latest ?? null, whatsNew: whatsNew ?? prev?.whatsNew ?? null };
 }
-
 // Non-blocking refresh for the long-running server: query npm asynchronously (never stalls the event loop
 // the way the CLI's spawnSync path would) and persist the same cache the CLI reads. The /api/version route
 // calls this when the cache is stale, so the phone opening the app keeps `latest`/`whatsNew` current without
 // the user re-running the CLI. Best-effort: npm missing/offline/blocked leaves the prior values.
-export function refreshLatestAsync(home, { now = Date.now(), spawnFn = spawn, timeoutMs = 4000 } = {}) {
-  try {
-    const child = spawnFn('npm', VIEW_ARGS, { timeout: timeoutMs });
-    let out = '';
-    child.stdout?.on('data', (d) => { out += d; });
-    child.on('close', (code) => {
-      writeCache(home, mergedCache(home, now, code === 0 ? parseView(out) : { latest: null, whatsNew: null }));
-    });
-    child.on('error', () => { /* npm missing/offline — leave the cache untouched */ });
-  } catch { /* best effort */ }
+export function refreshLatestAsync(home, { now = Date.now(), spawnFn = spawn, timeoutMs = 4000, } = {}) {
+    try {
+        const child = spawnFn('npm', VIEW_ARGS, { timeout: timeoutMs });
+        let out = '';
+        child.stdout?.on('data', (data) => { out += String(data); });
+        child.on('close', (code) => {
+            writeCache(home, mergedCache(home, now, code === 0 ? parseView(out) : { latest: null, whatsNew: null }));
+        });
+        child.on('error', () => { });
+    }
+    catch { /* best effort */ }
 }
-
 // The hidden `__update-check` worker (runs detached, prints nothing): refresh the cache. On a failed fetch
 // keep the previously-known values but still stamp checkedAt, so a flaky network doesn't re-spawn every run.
 export function runUpdateCheck(home, { now = Date.now(), ...opts } = {}) {
-  writeCache(home, mergedCache(home, now, fetchLatest(opts)));
+    writeCache(home, mergedCache(home, now, fetchLatest(opts)));
 }
-
 // Fire-and-forget notifier for a foreground command. Prints an upgrade line straight from the cache (no
 // network on this path), then — if the cache is stale — kicks off a detached refresh so the NEXT run is
 // current. Returns true if a notice was printed (handy for tests). `selfPath` is the CLI entry so the
 // background worker re-invokes this same binary.
-export function notifyUpdate(home, { version, selfPath, now = Date.now(), log = console.log, spawnFn = spawn } = {}) {
-  const cache = readCache(home);
-  let shown = false;
-  if (cache && cache.latest && isNewer(cache.latest, version)) {
-    log('');
-    log(t('update.available', { current: version, latest: cache.latest }));
-    log(t(isBrewInstall(selfPath) ? 'update.howBrew' : 'update.how'));
-    shown = true;
-  }
-  if (selfPath && shouldRefresh(cache, now)) {
-    try {
-      const child = spawnFn(process.execPath, [selfPath, '__update-check'], { detached: true, stdio: 'ignore' });
-      child.unref?.();
-    } catch { /* best effort */ }
-  }
-  return shown;
+export function notifyUpdate(home, { version, selfPath, now = Date.now(), log = console.log, spawnFn = spawn, } = {}) {
+    const cache = readCache(home);
+    let shown = false;
+    if (cache && cache.latest && isNewer(cache.latest, version)) {
+        log('');
+        log(t('update.available', { current: version, latest: cache.latest }));
+        log(t(isBrewInstall(selfPath) ? 'update.howBrew' : 'update.how'));
+        shown = true;
+    }
+    if (selfPath && shouldRefresh(cache, now)) {
+        try {
+            const child = spawnFn(process.execPath, [selfPath, '__update-check'], { detached: true, stdio: 'ignore' });
+            child.unref?.();
+        }
+        catch { /* best effort */ }
+    }
+    return shown;
 }

package/{src → dist/src}/cli/urlHost.js

@@ -2,11 +2,15 @@
 // host up front, so instead of scraping a random URL we gate readiness on the tunnel process echoing that
 // exact host in its own log — and cpolar derives its -subdomain/-hostname flag from the same host. Pure.
 export function hostOf(url) {
-  try { return new URL(String(url)).host; } catch { return null; }
+    try {
+        return new URL(String(url)).host;
+    }
+    catch {
+        return null;
+    }
 }
-
 // Has the process output mentioned this URL's host yet? (i.e. the named tunnel is up on its known domain.)
 export function hostIn(text, url) {
-  const h = hostOf(url);
-  return !!h && String(text || '').includes(h);
+    const h = hostOf(url);
+    return !!h && String(text || '').includes(h);
 }

package/dist/src/cli/workspaceCmd.js

@@ -0,0 +1,347 @@
+import { homedir } from 'node:os';
+import { runTmux as defaultRunTmux } from '../tmux/commands.js';
+import { createWorkspaceStore } from '../workspace/store.js';
+import { createWorkspaceTmux } from '../workspace/tmuxAdapter.js';
+import { createWorkspaceLock } from '../workspace/lock.js';
+import { createWorkspaceBackground } from '../workspace/checkpointer.js';
+import { createEnvironmentProvider } from '../workspace/environment.js';
+import { createWorkspaceRuntime } from '../workspace/runtime.js';
+import { claudeStatePath } from './state.js';
+import { ask, select, CANCELLED } from './prompt.js';
+import { t } from './i18n/index.js';
+const RESTORE_FLAGS = new Set(['list', 'dryRun', 'checkpoint', 'session', 'lang', 'config']);
+const SAFE_CHECKPOINT_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const INVALID_TOPOLOGY_REASONS = new Set([
+    'invalid-session', 'invalid-session-id', 'invalid-session-name', 'invalid-active-window-id',
+    'invalid-window-links', 'missing-window-links', 'invalid-window-link', 'invalid-window-link-index',
+    'duplicate-window-link', 'duplicate-window-link-index', 'dangling-window-link', 'dangling-active-window',
+    'missing-window-panes', 'invalid-pane', 'duplicate-pane', 'dangling-active-pane',
+]);
+const recordOf = (value) => value && typeof value === 'object' && !Array.isArray(value)
+    ? value : null;
+const arrayOfRecords = (value) => Array.isArray(value) ? value.flatMap((item) => {
+    const record = recordOf(item);
+    return record ? [record] : [];
+}) : [];
+const strings = (value) => Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+function line(stream, value = '') {
+    if (typeof stream === 'function')
+        stream(value);
+    else
+        stream.write(`${value}\n`);
+}
+function countAgents(checkpoint) {
+    return arrayOfRecords(checkpoint.windows)
+        .flatMap((window) => arrayOfRecords(window.panes))
+        .filter((pane) => Boolean(pane.agent)).length;
+}
+function checkpointCounts(checkpoint) {
+    const windows = arrayOfRecords(checkpoint.windows);
+    return {
+        sessions: Array.isArray(checkpoint.sessions) ? checkpoint.sessions.length : 0,
+        windows: windows.length,
+        panes: windows.reduce((sum, window) => sum + (Array.isArray(window.panes) ? window.panes.length : 0), 0),
+        agents: countAgents(checkpoint),
+    };
+}
+function unsupportedReason(reason) {
+    if (reason === 'linked-windows-unsupported')
+        return t('restore.reason.linkedWindows');
+    if (typeof reason === 'string' && INVALID_TOPOLOGY_REASONS.has(reason))
+        return t('restore.reason.invalidTopology');
+    return t('restore.reason.unknown', { reason: reason || 'unknown' });
+}
+function posixQuote(value) {
+    return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+function restoreCommand(checkpoint, sessions = []) {
+    const selectedSessions = Array.isArray(sessions) ? sessions : [sessions];
+    return selectedSessions.reduce((command, session) => `${command} --session ${posixQuote(session)}`, `handmux restore --checkpoint ${posixQuote(checkpoint)}`);
+}
+function manualSessionCommand(session) {
+    return `tmux new-session -s ${posixQuote(session)}`;
+}
+function writeManualRecovery(stream, session) {
+    line(stream, t('restore.manualRecovery', { command: manualSessionCommand(session) }));
+}
+function normalizeFlags(flags) {
+    const unknown = Object.keys(flags).find((key) => !RESTORE_FLAGS.has(key));
+    if (unknown)
+        return { error: t('restore.badFlag', { flag: `--${unknown}` }) };
+    if (flags.list !== undefined && typeof flags.list !== 'boolean')
+        return { error: t('restore.flagBoolean', { flag: '--list' }) };
+    if (flags.dryRun !== undefined && typeof flags.dryRun !== 'boolean')
+        return { error: t('restore.flagBoolean', { flag: '--dry-run' }) };
+    if (flags.checkpoint !== undefined && (typeof flags.checkpoint !== 'string' || !flags.checkpoint.trim())) {
+        return { error: t('restore.checkpointValue') };
+    }
+    if (typeof flags.checkpoint === 'string'
+        && (!SAFE_CHECKPOINT_ID.test(flags.checkpoint.trim()) || flags.checkpoint.trim() === '.' || flags.checkpoint.trim() === '..')) {
+        return { error: t('restore.checkpointId') };
+    }
+    const rawSessions = flags.session === undefined ? [] : (Array.isArray(flags.session) ? flags.session : [flags.session]);
+    if (rawSessions.some((name) => typeof name !== 'string' || !name.trim()))
+        return { error: t('restore.sessionValue') };
+    if (flags.list && (flags.dryRun || flags.checkpoint !== undefined || flags.session !== undefined)) {
+        return { error: t('restore.listExclusive') };
+    }
+    const checkpoint = typeof flags.checkpoint === 'string' ? flags.checkpoint.trim() : undefined;
+    return {
+        list: flags.list === true,
+        dryRun: flags.dryRun === true,
+        ...(checkpoint ? { checkpoint } : {}),
+        sessions: rawSessions.map((name) => name.trim()),
+    };
+}
+function checkpointRows(value) {
+    if (!Array.isArray(value))
+        throw new Error('invalid checkpoint list');
+    return value.map((candidate) => {
+        const row = recordOf(candidate);
+        if (row?.status === 'ok' && typeof row.id === 'string' && row.id && recordOf(row.value)) {
+            return candidate;
+        }
+        if (typeof row?.status === 'string' && typeof row.id === 'string' && row.id
+            && typeof row.error === 'string') {
+            return candidate;
+        }
+        return {
+            status: typeof row?.status === 'string' ? row.status : 'invalid',
+            id: typeof row?.id === 'string' && row.id ? row.id : '?',
+            error: typeof row?.error === 'string' ? row.error : 'invalid checkpoint record',
+        };
+    });
+}
+function validRows(rows) {
+    return rows.filter((row) => 'value' in row);
+}
+function writeCheckpointRow(stdout, row) {
+    if (!('value' in row)) {
+        line(stdout, t('restore.listUnavailable', { id: row.id || '?', error: row.error || row.status || 'unknown' }));
+        return;
+    }
+    const counts = checkpointCounts(row.value);
+    line(stdout, t('restore.listRow', {
+        id: row.id,
+        time: row.value.archivedAt || row.value.capturedAt || '?',
+        ...counts,
+    }));
+}
+async function defaultSelectCheckpoint(rows) {
+    const selected = await ask(select({
+        message: t('restore.selectCheckpoint'),
+        options: rows.map((row) => {
+            const counts = checkpointCounts(row.value);
+            return {
+                value: row.id,
+                label: row.id,
+                hint: t('restore.selectHint', { time: row.value.archivedAt || row.value.capturedAt || '?', ...counts }),
+            };
+        }),
+        initialValue: rows[0]?.id,
+    }));
+    if (typeof selected !== 'string')
+        throw new Error('invalid checkpoint selection');
+    return selected;
+}
+function writePlan(stdout, planInput, dryRun, continuationCommand) {
+    const plan = recordOf(planInput);
+    if (!plan || typeof plan.checkpointId !== 'string')
+        throw new Error('invalid restore plan');
+    const summary = recordOf(plan.summary);
+    const preExisting = recordOf(plan.preExistingRuntimeIds);
+    const planSessions = arrayOfRecords(plan.sessions);
+    line(stdout, t('restore.planCheckpoint', {
+        id: plan.checkpointId,
+        time: plan.capturedAt || plan.archivedAt || '?',
+        sessions: summary?.sessions ?? 0,
+        windows: summary?.windows ?? 0,
+        panes: summary?.panes ?? 0,
+    }));
+    line(stdout, t('restore.planCurrent', {
+        sessions: Array.isArray(preExisting?.sessions) ? preExisting.sessions.length : 0,
+    }));
+    line(stdout);
+    for (const item of planSessions) {
+        if (item.action === 'create')
+            line(stdout, t('restore.planCreate', { session: item.sourceName }));
+        else if (item.action === 'create-renamed')
+            line(stdout, t('restore.planRenamed', { session: item.sourceName, target: item.targetName }));
+        else if (item.action === 'already-present')
+            line(stdout, t('restore.planAlready', { session: item.sourceName }));
+        else {
+            const session = item.sourceName || item.logicalId || '?';
+            line(stdout, t('restore.planUnavailable', { session, reason: unsupportedReason(item.reason) }));
+            writeManualRecovery(stdout, session);
+        }
+    }
+    for (const warning of strings(plan.warnings))
+        line(stdout, t('restore.warning', { warning }));
+    line(stdout);
+    line(stdout, t('restore.nonDestructive'));
+    if (dryRun && !planSessions.some((item) => item.action === 'unsupported')) {
+        line(stdout, t('restore.dryRunHint', { command: continuationCommand }));
+    }
+    const unsupported = recordOf(plan.planSummary)?.unsupported;
+    return typeof unsupported === 'number' && Number.isFinite(unsupported) ? unsupported : 0;
+}
+function writeResult(stdout, stderr, checkpointId, resultInput) {
+    const result = recordOf(resultInput);
+    if (!result || typeof result.status !== 'string' || !Array.isArray(result.results)) {
+        throw new Error('invalid restore result');
+    }
+    const resultRows = arrayOfRecords(result.results);
+    for (const item of resultRows) {
+        const session = item.sourceName || item.logicalId || '?';
+        if (item.status === 'restored') {
+            line(stdout, item.targetName && item.targetName !== session
+                ? t('restore.resultRenamed', { session, target: item.targetName })
+                : t('restore.resultRestored', { session }));
+            for (const warning of strings(item.warnings))
+                line(stdout, t('restore.sessionWarning', { session, warning }));
+        }
+        else if (item.status === 'already-present') {
+            line(stdout, t('restore.resultAlready', { session }));
+        }
+        else {
+            const stage = item.stage || 'restore';
+            line(stderr, t('restore.sessionFailed', {
+                checkpoint: checkpointId,
+                session,
+                stage,
+                error: stage === 'plan' ? unsupportedReason(item.error) : (item.error || 'unknown error'),
+            }));
+            if (stage === 'plan')
+                writeManualRecovery(stderr, session);
+            else
+                line(stderr, t('restore.retrySession', { command: restoreCommand(checkpointId, session) }));
+        }
+    }
+    if (result.status !== 'succeeded' && result.error && !resultRows.some((item) => item.status === 'failed')) {
+        line(stderr, t('restore.operationFailed', { checkpoint: checkpointId, stage: 'restore', error: result.error }));
+        line(stderr, t('restore.retry', { command: restoreCommand(checkpointId) }));
+    }
+    for (const warning of strings(result.warnings))
+        line(stdout, t('restore.warning', { warning }));
+    line(stdout);
+    line(stdout, t('restore.resultSummary', {
+        restored: result.restored ?? 0,
+        already: result.alreadyPresent ?? 0,
+        failed: result.failed ?? 0,
+    }));
+    line(stdout, t('restore.nonDestructivePast'));
+    return result.status;
+}
+export function createStandaloneWorkspaceRuntime(options = {}) {
+    const home = options.home ?? homedir();
+    const runTmux = options.runTmux ?? defaultRunTmux;
+    const stateFile = options.stateFile ?? claudeStatePath(home);
+    const readOnly = options.readOnly ?? false;
+    const createStore = (options.createStore ?? createWorkspaceStore);
+    const createTmux = (options.createTmux ?? createWorkspaceTmux);
+    const createLock = (options.createLock ?? createWorkspaceLock);
+    const createCheckpointer = (options.createCheckpointer ?? createWorkspaceBackground);
+    const createRuntime = (options.createRuntime ?? createWorkspaceRuntime);
+    const store = createStore({ home });
+    const tmux = createTmux({ run: runTmux, readOnly });
+    const lock = createLock({ dir: store.paths.lockDir });
+    const observe = options.observeEnvironment || createEnvironmentProvider({
+        tmuxServerIdProvider: async () => {
+            const observeTmux = recordOf(tmux)?.observeEnvironment;
+            if (typeof observeTmux !== 'function')
+                throw new Error('tmux environment observer unavailable');
+            const observedInput = await observeTmux.call(tmux);
+            const observed = recordOf(observedInput);
+            if (!observed)
+                throw new Error('tmux environment unavailable');
+            if (observed.status === 'unknown')
+                throw new Error('tmux environment unavailable');
+            return observed.tmuxServerId ?? null;
+        },
+    });
+    const checkpointer = createCheckpointer({ store, tmux, observeEnvironment: observe, lock, stateFile });
+    return createRuntime({ store, tmux, lock, checkpointer, home });
+}
+export async function runWorkspaceCommand({ flags = {}, positionals = [], unknownShortFlags = [], home = homedir(), runtime, inputIsTTY = Boolean(process.stdin.isTTY), outputIsTTY = Boolean(process.stdout.isTTY), selectCheckpoint = defaultSelectCheckpoint, stdout = process.stdout, stderr = process.stderr, createRuntime = createStandaloneWorkspaceRuntime, } = {}) {
+    if (positionals.length > 0 || unknownShortFlags.length > 0) {
+        const error = positionals.length > 0
+            ? t('restore.unexpectedArgument', { value: positionals[0] })
+            : t('restore.unknownShortFlag', { flag: unknownShortFlags[0] });
+        line(stderr, error);
+        line(stderr, t('restore.usage'));
+        return 2;
+    }
+    const parsed = normalizeFlags(flags);
+    if ('error' in parsed) {
+        line(stderr, parsed.error);
+        line(stderr, t('restore.usage'));
+        return 2;
+    }
+    const workspace = runtime || createRuntime({ home, readOnly: parsed.dryRun });
+    let resolvedCheckpoint = parsed.checkpoint || 'latest';
+    try {
+        if (parsed.list) {
+            const rows = checkpointRows(await workspace.listCheckpoints());
+            if (rows.length === 0)
+                line(stdout, t('restore.listEmpty'));
+            else
+                rows.forEach((row) => writeCheckpointRow(stdout, row));
+            return 0;
+        }
+        let checkpointId;
+        let historical = false;
+        if (parsed.checkpoint && parsed.checkpoint !== 'latest') {
+            checkpointId = parsed.checkpoint;
+            historical = true;
+        }
+        else {
+            const rows = validRows(checkpointRows(await workspace.listCheckpoints()));
+            if (rows.length === 0) {
+                line(stderr, t('restore.noCheckpoint'));
+                return 1;
+            }
+            const firstRow = rows[0];
+            if (!firstRow)
+                return 1;
+            if (parsed.checkpoint === 'latest') {
+                checkpointId = firstRow.id;
+                historical = true;
+            }
+            else if (rows.length === 1) {
+                checkpointId = firstRow.id;
+            }
+            else if (inputIsTTY && outputIsTTY) {
+                checkpointId = await selectCheckpoint(rows);
+                historical = true;
+            }
+            else {
+                checkpointId = firstRow.id;
+            }
+        }
+        if (typeof checkpointId !== 'string' || !checkpointId) {
+            line(stderr, t('restore.selectionCancelled', { command: 'handmux restore' }));
+            return 1;
+        }
+        resolvedCheckpoint = checkpointId;
+        const request = { checkpointId, sessions: parsed.sessions, historical: historical || parsed.dryRun };
+        if (parsed.dryRun) {
+            const restorePlan = await workspace.getRestorePlan(request);
+            const unsupported = writePlan(stdout, restorePlan, true, restoreCommand(checkpointId, parsed.sessions));
+            return unsupported > 0 ? 1 : 0;
+        }
+        const result = await workspace.restoreNow(request);
+        return writeResult(stdout, stderr, checkpointId, result) === 'succeeded' ? 0 : 1;
+    }
+    catch (error) {
+        if (error === CANCELLED) {
+            line(stderr, t('restore.selectionCancelled', { command: 'handmux restore' }));
+            return 1;
+        }
+        line(stderr, t('restore.error', {
+            checkpoint: resolvedCheckpoint,
+            error: error instanceof Error ? error.message : String(error),
+        }));
+        line(stderr, t('restore.retry', { command: restoreCommand(resolvedCheckpoint) }));
+        return 1;
+    }
+}