handmux 0.23.0 → 0.25.0

package/dist/src/workspace/restore.js

@@ -0,0 +1,363 @@
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import { AGENTS } from '../agents/index.js';
+const KINDS = ['sessions', 'windows', 'panes'];
+const errorStage = (error) => (error && typeof error === 'object' && 'stage' in error && typeof error.stage === 'string'
+    ? error.stage : undefined);
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function windowMap(checkpoint) {
+    return new Map(checkpoint.windows.map((window) => [window.id, window]));
+}
+function sessionMap(checkpoint) {
+    return new Map(checkpoint.sessions.map((session) => [session.id, session]));
+}
+function emptyMapping() {
+    return {
+        names: {},
+        runtime: { sessions: {}, windows: {}, panes: {} },
+        logical: { sessions: {}, windows: {}, panes: {} },
+    };
+}
+function mergeMapping(target, source) {
+    Object.assign(target.names, source.names);
+    for (const kind of KINDS) {
+        Object.assign(target.runtime[kind], source.runtime[kind]);
+        Object.assign(target.logical[kind], source.logical[kind]);
+    }
+    return target;
+}
+function mapRuntime(mapping, kind, source, logical, actual) {
+    if (typeof source === 'string' && source)
+        mapping.runtime[kind][source] = actual;
+    if (typeof logical === 'string' && logical)
+        mapping.logical[kind][logical] = actual;
+}
+async function usableCwd(cwd, { access, home, warnings, }) {
+    if (typeof cwd === 'string' && cwd) {
+        try {
+            await access(cwd);
+            return cwd;
+        }
+        catch { /* fall through */ }
+    }
+    warnings.push(`cwd ${typeof cwd === 'string' && cwd ? cwd : '(missing)'} is unavailable; restored in ${home}`);
+    return home;
+}
+function sortedPanes(window) {
+    return [...window.panes].sort((a, b) => a.index - b.index);
+}
+function requiredWindow(windows, id) {
+    const window = windows.get(id);
+    if (!window)
+        throw new Error(`checkpoint window ${id} is missing`);
+    return window;
+}
+function firstPane(window) {
+    const pane = sortedPanes(window)[0];
+    if (!pane)
+        throw new Error(`checkpoint window ${window.id} has no panes`);
+    return pane;
+}
+function dispositionMap(plan) {
+    return new Map((plan.windows || []).map((window) => [window.logicalId, window]));
+}
+async function notify(onProgress, results, result, total) {
+    if (typeof onProgress !== 'function')
+        return;
+    await onProgress({ completed: results.length, total, result });
+}
+async function restoreOneSession({ item, checkpoint, tmux, agents, access, home, dispositions, restoredWindows, agentReadiness, }) {
+    const sessions = sessionMap(checkpoint);
+    const windows = windowMap(checkpoint);
+    const source = sessions.get(item.logicalId);
+    if (!source)
+        throw Object.assign(new Error('checkpoint session is missing'), { stage: 'plan' });
+    const warnings = [];
+    const mapping = emptyMapping();
+    const localWindows = new Map();
+    const localPanes = new Map();
+    const links = [...item.windowLinks].sort((a, b) => a.index - b.index);
+    const seedLink = links.find((link) => {
+        if (restoredWindows.has(link.windowId))
+            return false;
+        return dispositions.get(link.windowId)?.action !== 'reuse';
+    });
+    let temp = null;
+    let topologyComplete = false;
+    try {
+        if (seedLink) {
+            const seedWindow = requiredWindow(windows, seedLink.windowId);
+            const seedPane = firstPane(seedWindow);
+            const cwd = await usableCwd(seedPane.cwd, { access, home, warnings });
+            temp = await tmux.createTemporarySession({
+                cwd,
+                sessionLogicalId: item.logicalId,
+                windowLogicalId: seedWindow.id,
+                paneLogicalId: seedPane.id,
+                windowName: seedWindow.name,
+                windowIndex: seedLink.index,
+            });
+            localWindows.set(seedWindow.id, temp.windowId);
+            localPanes.set(seedPane.id, temp.paneId);
+            mapRuntime(mapping, 'windows', seedWindow.runtimeId, seedWindow.id, temp.windowId);
+            mapRuntime(mapping, 'panes', seedPane.runtimeId, seedPane.id, temp.paneId);
+        }
+        else {
+            const fallbackId = links[0]?.windowId;
+            if (!fallbackId)
+                throw new Error('checkpoint session has no windows');
+            const fallbackWindow = requiredWindow(windows, fallbackId);
+            const cwd = await usableCwd(firstPane(fallbackWindow).cwd, { access, home, warnings });
+            temp = await tmux.createTemporarySession({ cwd, sessionLogicalId: item.logicalId });
+        }
+        mapRuntime(mapping, 'sessions', source.runtimeId, source.id, temp.sessionId);
+        for (const link of links) {
+            const window = windows.get(link.windowId);
+            if (!window)
+                throw new Error(`checkpoint window ${link.windowId} is missing`);
+            if (localWindows.has(window.id))
+                continue;
+            const sharedRuntime = restoredWindows.get(window.id);
+            const disposition = dispositions.get(window.id);
+            const dispositionRuntime = disposition?.action === 'reuse' ? disposition.runtimeId : undefined;
+            if (sharedRuntime || dispositionRuntime) {
+                const windowId = sharedRuntime || dispositionRuntime;
+                if (!windowId)
+                    throw new Error(`reused window ${window.id} has no runtime id`);
+                await tmux.linkWindow(windowId, temp.sessionId, link.index, { existing: !sharedRuntime });
+                if (!sharedRuntime)
+                    mapRuntime(mapping, 'windows', window.runtimeId, window.id, windowId);
+                continue;
+            }
+            const initialPane = firstPane(window);
+            const cwd = await usableCwd(initialPane.cwd, { access, home, warnings });
+            const created = await tmux.createWindow(temp.sessionId, {
+                name: window.name,
+                index: link.index,
+                cwd,
+                windowLogicalId: window.id,
+                paneLogicalId: initialPane.id,
+            });
+            localWindows.set(window.id, created.windowId);
+            localPanes.set(initialPane.id, created.paneId);
+            mapRuntime(mapping, 'windows', window.runtimeId, window.id, created.windowId);
+            mapRuntime(mapping, 'panes', initialPane.runtimeId, initialPane.id, created.paneId);
+        }
+        for (const [logicalId, runtimeId] of localWindows) {
+            const window = requiredWindow(windows, logicalId);
+            const panes = sortedPanes(window);
+            const firstPane = panes[0];
+            if (!firstPane)
+                throw new Error(`window ${logicalId} has no panes`);
+            const seedPaneId = localPanes.get(firstPane.id);
+            for (const pane of panes.slice(1)) {
+                const cwd = await usableCwd(pane.cwd, { access, home, warnings });
+                const paneId = await tmux.splitPane(seedPaneId, { cwd, paneLogicalId: pane.id });
+                localPanes.set(pane.id, paneId);
+                mapRuntime(mapping, 'panes', pane.runtimeId, pane.id, paneId);
+            }
+            try {
+                await tmux.applyLayout(runtimeId, window.layout);
+            }
+            catch (error) {
+                warnings.push(`layout for ${window.name} was unavailable; kept the default layout (${message(error)})`);
+            }
+            const activePane = localPanes.get(window.activePaneId);
+            if (activePane)
+                await tmux.selectPane(activePane);
+        }
+        const activeLink = links.find((link) => link.windowId === item.activeWindowId);
+        if (activeLink) {
+            if (typeof tmux.selectWindowInSession === 'function')
+                await tmux.selectWindowInSession(temp.sessionId, activeLink.index);
+            else {
+                const activeWindow = localWindows.get(activeLink.windowId) || restoredWindows.get(activeLink.windowId);
+                if (activeWindow)
+                    await tmux.selectWindow(activeWindow);
+            }
+        }
+        if (!seedLink && temp.windowId)
+            await tmux.killCreatedWindow(temp.windowId);
+        await tmux.renameCreatedSession(temp.sessionId, item.targetName);
+        topologyComplete = true;
+        mapping.names[item.sourceName] = item.targetName;
+        for (const [logicalId, runtimeId] of localWindows)
+            restoredWindows.set(logicalId, runtimeId);
+        for (const [logicalId, paneId] of localPanes) {
+            const pane = [...windows.values()].flatMap((window) => window.panes).find((candidate) => candidate.id === logicalId);
+            if (!pane?.agent)
+                continue;
+            const binding = pane.agent;
+            const agentId = typeof binding.id === 'string' ? binding.id : '';
+            const sessionId = typeof binding.sessionId === 'string' ? binding.sessionId : '';
+            const transcriptPath = typeof binding.transcriptPath === 'string' ? binding.transcriptPath : '';
+            const driver = agents.find((candidate) => candidate.id === agentId);
+            if (!driver) {
+                warnings.push(`agent ${agentId || '(missing)'} is unsupported; shell was restored`);
+                continue;
+            }
+            if (!driver.sessions.isId(sessionId)) {
+                warnings.push(`agent ${driver.id} session id is invalid; shell was restored`);
+                continue;
+            }
+            try {
+                await access(transcriptPath);
+            }
+            catch {
+                warnings.push(`agent ${driver.id} context is unavailable; shell was restored`);
+                continue;
+            }
+            const [cmd, ...args] = driver.sessions.resumeArgs(sessionId);
+            if (!cmd) {
+                warnings.push(`agent ${driver.id} resume command is unavailable; shell was restored`);
+                continue;
+            }
+            const executable = agentReadiness.get(cmd);
+            if (executable) {
+                let readiness;
+                try {
+                    readiness = await executable;
+                }
+                catch (error) {
+                    readiness = { status: 'failed', error: message(error) };
+                }
+                if (readiness.status !== 'ready') {
+                    warnings.push(`agent ${driver.id} executable is unavailable; shell was restored (${readiness.error})`);
+                    continue;
+                }
+            }
+            try {
+                await tmux.startAgent(paneId, cmd, args);
+            }
+            catch (error) {
+                warnings.push(`agent ${driver.id} resume failed; shell was restored (${message(error)})`);
+            }
+        }
+        return {
+            logicalId: item.logicalId,
+            sourceName: item.sourceName,
+            targetName: item.targetName,
+            status: 'restored',
+            warnings,
+            mapping,
+        };
+    }
+    catch (error) {
+        let cleanupError;
+        if (temp && !topologyComplete) {
+            try {
+                await tmux.killCreatedSession(temp.sessionId);
+            }
+            catch (failure) {
+                cleanupError = failure;
+            }
+        }
+        const failure = cleanupError
+            ? new Error(`${message(error)}; cleanup failed: ${message(cleanupError)}`)
+            : error instanceof Error ? error : new Error(message(error));
+        failure.stage ||= errorStage(error) || 'topology';
+        throw failure;
+    }
+}
+function requiredAgentCommands(plan, checkpoint, agents) {
+    const sessions = sessionMap(checkpoint);
+    const windows = windowMap(checkpoint);
+    const dispositions = dispositionMap(plan);
+    const commands = new Set();
+    for (const item of plan.sessions) {
+        if (item.action === 'already-present' || item.action === 'unsupported')
+            continue;
+        if (typeof item.logicalId !== 'string')
+            continue;
+        const session = sessions.get(item.logicalId);
+        if (!session)
+            continue;
+        for (const link of session.windowLinks) {
+            if (dispositions.get(link.windowId)?.action === 'reuse')
+                continue;
+            for (const pane of windows.get(link.windowId)?.panes || []) {
+                const binding = pane.agent;
+                if (!binding)
+                    continue;
+                const agentId = typeof binding.id === 'string' ? binding.id : '';
+                const sessionId = typeof binding.sessionId === 'string' ? binding.sessionId : '';
+                const driver = agents.find((candidate) => candidate.id === agentId);
+                if (!driver || !driver.sessions.isId(sessionId))
+                    continue;
+                const [command] = driver.sessions.resumeArgs(sessionId);
+                if (command)
+                    commands.add(command);
+            }
+        }
+    }
+    return [...commands];
+}
+function restoredTopologySummary(checkpoint, results) {
+    const restoredSessions = new Set(results
+        .filter((result) => result.status === 'restored')
+        .map((result) => result.logicalId));
+    const windowIds = new Set((checkpoint?.sessions || [])
+        .filter((session) => restoredSessions.has(session.id))
+        .flatMap((session) => (session.windowLinks || []).map((link) => link.windowId)));
+    const paneIds = new Set((checkpoint?.windows || [])
+        .filter((window) => windowIds.has(window.id))
+        .flatMap((window) => (window.panes || []).map((pane) => pane.id)));
+    return { sessions: restoredSessions.size, windows: windowIds.size, panes: paneIds.size };
+}
+export function summarizeRestore(results, checkpoint = null) {
+    const mapping = emptyMapping();
+    for (const result of results)
+        if (result.mapping)
+            mergeMapping(mapping, result.mapping);
+    const restored = results.filter((result) => result.status === 'restored').length;
+    const alreadyPresent = results.filter((result) => result.status === 'already-present').length;
+    const failed = results.filter((result) => result.status === 'failed').length;
+    const status = failed === 0 ? 'succeeded' : restored + alreadyPresent > 0 ? 'partial' : 'failed';
+    return { status, restored, alreadyPresent, failed, results, mapping, summary: restoredTopologySummary(checkpoint, results) };
+}
+export async function executeRestore({ plan, checkpoint, tmux, agents = AGENTS, onProgress, access = fsp.access, home = os.homedir(), }) {
+    const results = [];
+    const dispositions = dispositionMap(plan);
+    const restoredWindows = new Map();
+    try {
+        const commands = requiredAgentCommands(plan, checkpoint, agents);
+        const agentReadiness = tmux.waitForAgents?.(commands) ?? new Map();
+        for (const item of plan.sessions) {
+            let result;
+            if (item.action === 'already-present') {
+                result = { logicalId: item.logicalId, sourceName: item.sourceName, status: 'already-present' };
+            }
+            else if (item.action === 'unsupported') {
+                result = {
+                    logicalId: item.logicalId, sourceName: item.sourceName, status: 'failed', stage: 'plan',
+                    ...(item.reason ? { error: item.reason } : {}),
+                };
+            }
+            else {
+                try {
+                    result = await restoreOneSession({
+                        item: item,
+                        checkpoint, tmux, agents, access, home, dispositions, restoredWindows, agentReadiness,
+                    });
+                }
+                catch (error) {
+                    result = {
+                        logicalId: item.logicalId,
+                        sourceName: item.sourceName,
+                        status: 'failed',
+                        stage: errorStage(error) || 'topology',
+                        error: message(error),
+                    };
+                }
+            }
+            results.push(result);
+            await notify(onProgress, results, result, plan.sessions.length);
+        }
+        return summarizeRestore(results, checkpoint);
+    }
+    finally {
+        tmux.revokeCreatedTargets?.();
+    }
+}

package/dist/src/workspace/runtime.js

@@ -0,0 +1,318 @@
+import crypto from 'node:crypto';
+import { buildRestorePlan } from './planner.js';
+import { executeRestore } from './restore.js';
+import { createOperationManager, normalizeRestoreRequest, } from './operations.js';
+import { buildRecoveryMapping, } from './mapping.js';
+const recordOf = (value) => (value && typeof value === 'object' && !Array.isArray(value)
+    ? value : null);
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+function unwrapCheckpoint(result) {
+    const record = recordOf(result);
+    if (record?.status !== 'ok' || !record.value) {
+        const detail = typeof record?.error === 'string' ? record.error : `checkpoint is ${String(record?.status || 'unavailable')}`;
+        throw new Error(detail);
+    }
+    const warnings = [record.warning, ...(Array.isArray(record.warnings) ? record.warnings : [])]
+        .filter((warning) => typeof warning === 'string' && Boolean(warning));
+    return { checkpoint: record.value, warnings };
+}
+async function readCheckpoint(store, checkpointId) {
+    return unwrapCheckpoint(checkpointId === 'latest'
+        ? await store.readLatestCheckpoint()
+        : await store.readCheckpoint(checkpointId));
+}
+async function readRecovery(store, checkpointId, historical) {
+    const result = await store.readRecovery(checkpointId);
+    if (result.status === 'ok')
+        return result.value;
+    if (historical && result.status === 'missing')
+        return null;
+    throw new Error(result.status === 'corrupt' ? result.error : `recovery state is ${result.status}`);
+}
+async function captureLive(tmux) {
+    const live = await tmux.captureTopology({ readOnly: true });
+    if (live.status === 'ok')
+        return live;
+    if (live.status === 'empty')
+        return { ...live, sessions: [], windows: [] };
+    throw new Error(typeof live.error === 'string' ? live.error : 'current tmux topology is unavailable');
+}
+function blankMapping() {
+    return {
+        names: {},
+        runtime: { sessions: {}, windows: {}, panes: {} },
+        logical: { sessions: {}, windows: {}, panes: {} },
+    };
+}
+function mapRuntime(mapping, kind, source, logical, runtime) {
+    if (typeof source === 'string' && source)
+        mapping.runtime[kind][source] = runtime;
+    if (typeof logical === 'string' && logical)
+        mapping.logical[kind][logical] = runtime;
+}
+function mappingForAlreadyPresent(checkpoint, live, results) {
+    const mapping = blankMapping();
+    const resolved = new Set(results.filter((row) => row.status === 'already-present').map((row) => row.logicalId));
+    const liveSessions = new Map(live.sessions.map((session) => [session.id, session]));
+    const liveWindows = new Map(live.windows.map((window) => [window.id, window]));
+    const sourceWindows = new Map(checkpoint.windows.map((window) => [window.id, window]));
+    for (const source of checkpoint.sessions) {
+        if (!resolved.has(source.id))
+            continue;
+        const actual = liveSessions.get(source.id);
+        if (!actual)
+            continue;
+        mapping.names[source.name] = actual.name;
+        mapRuntime(mapping, 'sessions', source.runtimeId, source.id, actual.runtimeId);
+        for (const link of source.windowLinks) {
+            const sourceWindow = sourceWindows.get(link.windowId);
+            const actualWindow = liveWindows.get(link.windowId);
+            if (!sourceWindow || !actualWindow)
+                continue;
+            mapRuntime(mapping, 'windows', sourceWindow.runtimeId, sourceWindow.id, actualWindow.runtimeId);
+            const actualPanes = new Map(actualWindow.panes.map((pane) => [pane.id, pane]));
+            for (const sourcePane of sourceWindow.panes) {
+                const actualPane = actualPanes.get(sourcePane.id);
+                if (actualPane)
+                    mapRuntime(mapping, 'panes', sourcePane.runtimeId, sourcePane.id, actualPane.runtimeId);
+            }
+        }
+    }
+    return mapping;
+}
+function sorted(value) {
+    if (Array.isArray(value))
+        return value.map(sorted);
+    if (!value || typeof value !== 'object')
+        return value;
+    const record = value;
+    return Object.fromEntries(Object.keys(record).sort().map((key) => [key, sorted(record[key])]));
+}
+function restoreGuard(live) {
+    const topology = {
+        status: live.status,
+        tmuxVersion: live.tmuxVersion || null,
+        active: live.active || null,
+        sessions: live.sessions || [],
+        windows: live.windows || [],
+    };
+    return {
+        topologyFingerprint: crypto.createHash('sha256').update(JSON.stringify(sorted(topology))).digest('hex'),
+        identities: {
+            sessions: (live.sessions || []).map(({ id, runtimeId, name }) => [id, runtimeId, name]).sort(),
+            windows: (live.windows || []).map(({ id, runtimeId, name }) => [id, runtimeId, name]).sort(),
+            panes: (live.windows || []).flatMap((window) => (window.panes || []).map(({ id, runtimeId }) => [id, runtimeId])).sort(),
+        },
+    };
+}
+function sameRestoreGuard(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+export function createWorkspaceRuntime({ store, tmux, lock, checkpointer, now = Date.now, randomUUID = crypto.randomUUID, planner = buildRestorePlan, executor = executeRestore, agents, access, home, restoreGuardAttempts = 3, }) {
+    const operations = createOperationManager({
+        store,
+        now,
+        randomUUID,
+        tryAcquireOperationLock: (owner) => lock.tryAcquire(owner),
+    });
+    let startPromise = null;
+    let startupHealth = { status: 'starting', detail: 'workspace-starting' };
+    async function resolveOperationRequest(requestInput = {}) {
+        const request = normalizeRestoreRequest(requestInput);
+        if (request.checkpointId !== 'latest')
+            return request;
+        const { checkpoint } = unwrapCheckpoint(await store.readLatestCheckpoint());
+        return { ...request, checkpointId: checkpoint.id };
+    }
+    async function planRestore(requestInput = {}) {
+        const request = normalizeRestoreRequest(requestInput);
+        const { checkpoint, warnings } = await readCheckpoint(store, request.checkpointId);
+        const recovery = await readRecovery(store, checkpoint.id, request.historical);
+        const live = await captureLive(tmux);
+        const plan = planner(checkpoint, live, {
+            sessionNames: request.sessions,
+            recovery,
+            historical: request.historical,
+            warnings,
+        });
+        return { request, checkpoint, recovery, live, plan };
+    }
+    async function guardedPlanRestore(requestInput = {}) {
+        const request = normalizeRestoreRequest(requestInput);
+        const { checkpoint, warnings } = await readCheckpoint(store, request.checkpointId);
+        const recovery = await readRecovery(store, checkpoint.id, request.historical);
+        let live = await captureLive(tmux);
+        for (let attempt = 0; attempt < restoreGuardAttempts; attempt += 1) {
+            const plan = planner(checkpoint, live, {
+                sessionNames: request.sessions,
+                recovery,
+                historical: request.historical,
+                warnings,
+            });
+            const before = restoreGuard(live);
+            const verified = await captureLive(tmux);
+            if (sameRestoreGuard(before, restoreGuard(verified))) {
+                return { request, checkpoint, recovery, live: verified, plan };
+            }
+            live = verified;
+        }
+        throw new Error(`tmux topology changed during restore planning ${restoreGuardAttempts} times; retry restore`);
+    }
+    async function getRestorePlan(request = {}) {
+        await start();
+        const state = await planRestore(request);
+        const serverNow = new Date(now()).toISOString();
+        const promptEligible = Boolean(!state.request.historical
+            && state.recovery
+            && state.recovery.resolvedAt === null
+            && state.recovery.pendingSessionIds.length > 0
+            && Date.parse(state.recovery.expiresAt) > now());
+        return Object.freeze({ ...state.plan, mapping: state.recovery?.mapping || null, serverNow, promptEligible });
+    }
+    async function getProtectionStatus() {
+        let live;
+        try {
+            live = await store.readLive();
+        }
+        catch {
+            return { status: 'degraded', lastSuccessfulCaptureAt: null, errorCode: 'live-unavailable' };
+        }
+        if (live.status === 'ok') {
+            return { status: 'protected', lastSuccessfulCaptureAt: live.value.capturedAt || null, errorCode: null };
+        }
+        if (live.status === 'empty') {
+            return { status: 'unprotected', lastSuccessfulCaptureAt: null, errorCode: null };
+        }
+        return {
+            status: 'degraded',
+            lastSuccessfulCaptureAt: null,
+            errorCode: live.status === 'corrupt' ? 'live-corrupt' : 'live-unavailable',
+        };
+    }
+    async function performRestore(operationId, request, onProgress, onRunning, onTerminal) {
+        let result;
+        let restoreError;
+        try {
+            result = await lock.withLock({ operationId }, async () => {
+                try {
+                    await onRunning();
+                    // The preview may be stale by now. Capture and plan again while holding the writer lock so a name
+                    // created after preview receives the next non-destructive `-restored` suffix.
+                    const state = await guardedPlanRestore(request);
+                    const restored = await executor({
+                        plan: state.plan,
+                        checkpoint: state.checkpoint,
+                        tmux,
+                        ...(agents ? { agents } : {}),
+                        onProgress,
+                        ...(access ? { access } : {}),
+                        ...(home ? { home } : {}),
+                    });
+                    const resolvedIds = restored.results
+                        .filter((row) => row.status === 'restored' || row.status === 'already-present')
+                        .map((row) => row.logicalId);
+                    const mapping = buildRecoveryMapping(state.checkpoint.id, state.recovery?.mapping, [
+                        restored.mapping,
+                        mappingForAlreadyPresent(state.checkpoint, state.live, restored.results),
+                    ], now);
+                    if (mapping && typeof store.mergeRecoveryMapping === 'function') {
+                        await store.mergeRecoveryMapping(state.checkpoint.id, mapping);
+                    }
+                    // Persist migration data before resolving pending ids. If the second write fails, retry planning
+                    // still sees the session and will recognize it as already-present instead of losing its mapping.
+                    if (resolvedIds.length > 0)
+                        await store.resolveSessions(state.checkpoint.id, resolvedIds);
+                    const lockedResult = { ...restored, mapping };
+                    await onTerminal(lockedResult);
+                    return lockedResult;
+                }
+                catch (error) {
+                    await onTerminal(error);
+                    throw error;
+                }
+            });
+        }
+        catch (error) {
+            restoreError = error;
+        }
+        let reconcileWarning;
+        try {
+            const reconciled = await checkpointer.reconcile('restore-complete');
+            if (!['written', 'unchanged'].includes(reconciled?.status)) {
+                reconcileWarning = `live reconcile ${reconciled?.status || 'unknown'}; workspace protection may be degraded`;
+            }
+        }
+        catch (error) {
+            reconcileWarning = `live reconcile failed: ${errorMessage(error)}`;
+        }
+        if (restoreError)
+            throw restoreError;
+        const completed = result;
+        if (!completed)
+            throw new Error('restore completed without a result');
+        if (reconcileWarning) {
+            result = {
+                ...completed,
+                warnings: [...(completed.warnings || []), reconcileWarning],
+            };
+        }
+        return result ?? completed;
+    }
+    async function startOnce() {
+        let interrupted;
+        let sweepError;
+        try {
+            interrupted = await operations.interruptOrphans();
+        }
+        catch (error) {
+            sweepError = error;
+        }
+        let started;
+        let startError;
+        try {
+            started = await checkpointer.start?.();
+        }
+        catch (error) {
+            startError = error;
+        }
+        if (sweepError && startError) {
+            const sweepMessage = sweepError instanceof Error ? sweepError.message : String(sweepError);
+            const startMessage = startError instanceof Error ? startError.message : String(startError);
+            throw new AggregateError([sweepError, startError], `${sweepMessage}; workspace protection start failed: ${startMessage}`);
+        }
+        if (sweepError)
+            throw sweepError;
+        if (startError)
+            throw startError;
+        return [interrupted, started];
+    }
+    function start() {
+        if (!startPromise) {
+            startupHealth = { status: 'starting', detail: 'workspace-starting' };
+            startPromise = startOnce().then((result) => {
+                startupHealth = { status: 'ready', detail: null };
+                return result;
+            }).catch((error) => {
+                startupHealth = { status: 'degraded', detail: 'workspace-start-failed' };
+                startPromise = null;
+                throw error;
+            });
+        }
+        return startPromise;
+    }
+    return {
+        start,
+        health: () => (startupHealth.status === 'ready'
+            ? (checkpointer.health?.() || startupHealth)
+            : startupHealth),
+        stop: () => checkpointer.stop(),
+        requestReconcile: () => checkpointer.requestReconcile(),
+        confirmEmpty: () => checkpointer.confirmEmpty(),
+        listCheckpoints: () => store.listCheckpoints(),
+        getProtectionStatus,
+        getRestorePlan,
+        startRestore: async (request = {}) => operations.start(await resolveOperationRequest(request), ({ operationId, request: normalized, onProgress, onRunning, onTerminal }) => (performRestore(operationId, normalized, onProgress, onRunning, onTerminal)), { deferRunning: true }),
+        getOperation: (id) => operations.get(id),
+        restoreNow: async (request = {}) => operations.run(await resolveOperationRequest(request), ({ operationId, request: normalized, onProgress, onRunning, onTerminal }) => (performRestore(operationId, normalized, onProgress, onRunning, onTerminal)), { deferRunning: true }),
+    };
+}