handmux 0.22.1 → 0.24.0

package/src/workspace/restore.js

@@ -1,279 +0,0 @@
-import fsp from 'node:fs/promises';
-import os from 'node:os';
-import { AGENTS } from '../agents/index.js';
-
-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 ['sessions', 'windows', 'panes']) {
-    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 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,
-}) {
-  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 = windows.get(seedLink.windowId);
-      const seedPane = sortedPanes(seedWindow)[0];
-      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 fallbackWindow = windows.get(links[0]?.windowId);
-      const cwd = await usableCwd(sortedPanes(fallbackWindow)[0].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);
-      if (sharedRuntime || disposition?.action === 'reuse') {
-        const windowId = sharedRuntime || disposition.runtimeId;
-        await tmux.linkWindow(windowId, temp.sessionId, link.index, { existing: !sharedRuntime });
-        if (!sharedRuntime) mapRuntime(mapping, 'windows', window.runtimeId, window.id, windowId);
-        continue;
-      }
-
-      const firstPane = sortedPanes(window)[0];
-      const cwd = await usableCwd(firstPane.cwd, { access, home, warnings });
-      const created = await tmux.createWindow(temp.sessionId, {
-        name: window.name,
-        index: link.index,
-        cwd,
-        windowLogicalId: window.id,
-        paneLogicalId: firstPane.id,
-      });
-      localWindows.set(window.id, created.windowId);
-      localPanes.set(firstPane.id, created.paneId);
-      mapRuntime(mapping, 'windows', window.runtimeId, window.id, created.windowId);
-      mapRuntime(mapping, 'panes', firstPane.runtimeId, firstPane.id, created.paneId);
-    }
-
-    for (const [logicalId, runtimeId] of localWindows) {
-      const window = windows.get(logicalId);
-      const panes = sortedPanes(window);
-      const seedPaneId = localPanes.get(panes[0].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 driver = agents.find((candidate) => candidate.id === pane.agent.id);
-      if (!driver) {
-        warnings.push(`agent ${pane.agent.id || '(missing)'} is unsupported; shell was restored`);
-        continue;
-      }
-      if (!driver.sessions.isId(pane.agent.sessionId)) {
-        warnings.push(`agent ${driver.id} session id is invalid; shell was restored`);
-        continue;
-      }
-      try {
-        await access(pane.agent.transcriptPath);
-      } catch {
-        warnings.push(`agent ${driver.id} context is unavailable; shell was restored`);
-        continue;
-      }
-      const [cmd, ...args] = driver.sessions.resumeArgs(pane.agent.sessionId);
-      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;
-    failure.stage ||= error?.stage || 'topology';
-    throw failure;
-  }
-}
-
-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 {
-    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', error: item.reason };
-      } else {
-        try {
-          result = await restoreOneSession({ item, checkpoint, tmux, agents, access, home, dispositions, restoredWindows });
-        } catch (error) {
-          result = {
-            logicalId: item.logicalId,
-            sourceName: item.sourceName,
-            status: 'failed',
-            stage: error.stage || 'topology',
-            error: message(error),
-          };
-        }
-      }
-      results.push(result);
-      await notify(onProgress, results, result, plan.sessions.length);
-    }
-    return summarizeRestore(results, checkpoint);
-  } finally {
-    tmux.revokeCreatedTargets?.();
-  }
-}

package/src/workspace/runtime.js

@@ -1,314 +0,0 @@
-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';
-
-function unwrapCheckpoint(result) {
-  if (result?.status !== 'ok' || !result.value) {
-    throw new Error(result?.error || `checkpoint is ${result?.status || 'unavailable'}`);
-  }
-  return { checkpoint: result.value, warnings: [result.warning, ...(result.warnings || [])].filter(Boolean) };
-}
-
-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.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(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;
-  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sorted(value[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;
-
-  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,
-            onProgress,
-            access,
-            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: ${error?.message || String(error)}`;
-    }
-    if (restoreError) throw restoreError;
-    if (reconcileWarning) {
-      result = {
-        ...result,
-        warnings: [...(result.warnings || []), reconcileWarning],
-      };
-    }
-    return result;
-  }
-
-  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) {
-      startPromise = startOnce().catch((error) => {
-        startPromise = null;
-        throw error;
-      });
-    }
-    return startPromise;
-  }
-
-  return {
-    start,
-    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 }),
-  };
-}