@ran-sh/dsh-crew 1.9.0 → 1.10.0

package/src/history/cleanup-plan.mjs

@@ -1,89 +1,89 @@
-import { createHash } from 'node:crypto';
-
-const MAX_RECORDS = 10_000;
-
-function instant(value) {
-  if (typeof value === 'number') return Number.isFinite(value) && value >= 0 ? value : null;
-  if (typeof value !== 'string') return null;
-  const match = /^(\d{4})-(\d{2})-(\d{2})T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/.exec(value);
-  if (!match) return null;
-  const [, y, m, d] = match.map(Number);
-  const calendar = new Date(0);
-  calendar.setUTCFullYear(y, m - 1, d);
-  if (calendar.getUTCFullYear() !== y || calendar.getUTCMonth() !== m - 1 || calendar.getUTCDate() !== d) return null;
-  const ms = Date.parse(value);
-  return Number.isFinite(ms) ? ms : null;
-}
-
-function ids(values) {
-  if (!Array.isArray(values) || values.length > MAX_RECORDS) throw new Error('HISTORY_INVALID_IDENTITIES');
-  if (values.some(id => typeof id !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,255}$/.test(id))) throw new Error('HISTORY_INVALID_IDENTITY');
-  if (new Set(values).size !== values.length) throw new Error('HISTORY_DUPLICATE_IDENTITY');
-  return [...values].sort();
-}
-
-function records(values) {
-  if (!Array.isArray(values) || values.some(row => !row || typeof row !== 'object')) throw new Error('HISTORY_INVALID_RECORDS');
-  ids(values.map(row => row.id));
-  return [...values].sort((a, b) => a.id.localeCompare(b.id, 'en'));
-}
-
-/**
- * Pure preview only. No filesystem or project-path operations are performed.
- *
- * `scope` defaults to `crew`: a caller that forgets to narrow the range gets the
- * one range that cannot remove sessions the operator opened themselves. Widening
- * to `all` is always an explicit choice.
- */
-export function planHistoryCleanup(snapshot, { operation = 'archive', scope = 'crew', before } = {}) {
-  if (!['archive', 'delete'].includes(operation) || !['all', 'crew', 'worktree', 'before'].includes(scope)) throw new Error('HISTORY_INVALID_OPTIONS');
-  const cutoff = scope === 'before' ? instant(before) : null;
-  if (scope === 'before' && (typeof before !== 'string' || cutoff === null)) throw new Error('HISTORY_INVALID_CUTOFF');
-  const workspaces = records(snapshot.workspaces);
-  const sessions = records(snapshot.sessions);
-  const active = ids(snapshot.activeSessionIds);
-  // `crew` and `worktree` narrow by provenance, never by project path: a session
-  // is Crew's own only when Crew recorded creating it, and worktree scope adds
-  // the isolated-workspace marker the hub stamps at dispatch.
-  const origin = new Set(Array.isArray(snapshot.crewSessionIds) ? snapshot.crewSessionIds : []);
-  const admitted = (row) => {
-    if (scope === 'crew') return origin.has(row.id);
-    if (scope === 'worktree') return origin.has(row.id) && row.worktree === true;
-    return true;
-  };
-  const withinTime = (row) => cutoff === null
-    || (instant(row.createdAt) !== null && instant(row.createdAt) < cutoff);
-  const selected = new Set(sessions.filter(row => admitted(row) && withinTime(row)).map(row => row.id));
-  // A workspace carries no provenance of its own: it follows its sessions, and
-  // only when every one of them is selected. Checking `admitted(row)` here would
-  // test a workspace id against a session ledger and always fail. A provenance
-  // scope additionally requires at least one selected child — an empty workspace
-  // holds no Crew work, so it is not Crew's to remove; `all` keeps its historical
-  // behaviour of following an empty workspace.
-  const requiresOwnedChild = scope === 'crew' || scope === 'worktree';
-  const workspaceIds = workspaces.filter(row => {
-    const children = ids(row.sessionIds);
-    return withinTime(row) && (!requiresOwnedChild || children.length > 0)
-      && children.every(id => selected.has(id));
-  }).map(row => row.id).sort();
-  const sessionIds = [...selected].sort();
-  const signature = {
-    operation, scope, cutoff,
-    workspaces: workspaces.map(row => ({ id: row.id, createdAt: row.createdAt, updatedAt: row.updatedAt, sessionIds: ids(row.sessionIds) })),
-    sessions: sessions.map(row => ({ id: row.id, createdAt: row.createdAt, revision: row.revision })),
-    active,
-    crewSessionIds: [...origin].sort(),
-  };
-  return {
-    schemaVersion: 1, operation, scope,
-    before: cutoff === null ? null : new Date(cutoff).toISOString(),
-    timeBasis: 'createdAt', workspaceIds, sessionIds,
-    counts: { workspaces: workspaceIds.length, sessions: sessionIds.length },
-    protectedCounts: { workspaces: workspaces.length - workspaceIds.length, sessions: sessions.length - sessionIds.length },
-    executable: active.length === 0 && (workspaceIds.length > 0 || sessionIds.length > 0),
-    blockedReason: active.length > 0 ? 'ACTIVE_SESSIONS' : workspaceIds.length + sessionIds.length === 0 ? 'EMPTY_SELECTION' : null,
-    activeSessionCount: active.length,
-    projectFilesAffected: false,
-    revision: createHash('sha256').update(JSON.stringify(signature)).digest('hex'),
-  };
-}
+import { createHash } from 'node:crypto';
+
+const MAX_RECORDS = 10_000;
+
+function instant(value) {
+  if (typeof value === 'number') return Number.isFinite(value) && value >= 0 ? value : null;
+  if (typeof value !== 'string') return null;
+  const match = /^(\d{4})-(\d{2})-(\d{2})T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:\d{2})$/.exec(value);
+  if (!match) return null;
+  const [, y, m, d] = match.map(Number);
+  const calendar = new Date(0);
+  calendar.setUTCFullYear(y, m - 1, d);
+  if (calendar.getUTCFullYear() !== y || calendar.getUTCMonth() !== m - 1 || calendar.getUTCDate() !== d) return null;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+function ids(values) {
+  if (!Array.isArray(values) || values.length > MAX_RECORDS) throw new Error('HISTORY_INVALID_IDENTITIES');
+  if (values.some(id => typeof id !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,255}$/.test(id))) throw new Error('HISTORY_INVALID_IDENTITY');
+  if (new Set(values).size !== values.length) throw new Error('HISTORY_DUPLICATE_IDENTITY');
+  return [...values].sort();
+}
+
+function records(values) {
+  if (!Array.isArray(values) || values.some(row => !row || typeof row !== 'object')) throw new Error('HISTORY_INVALID_RECORDS');
+  ids(values.map(row => row.id));
+  return [...values].sort((a, b) => a.id.localeCompare(b.id, 'en'));
+}
+
+/**
+ * Pure preview only. No filesystem or project-path operations are performed.
+ *
+ * `scope` defaults to `crew`: a caller that forgets to narrow the range gets the
+ * one range that cannot remove sessions the operator opened themselves. Widening
+ * to `all` is always an explicit choice.
+ */
+export function planHistoryCleanup(snapshot, { operation = 'archive', scope = 'crew', before } = {}) {
+  if (!['archive', 'delete'].includes(operation) || !['all', 'crew', 'worktree', 'before'].includes(scope)) throw new Error('HISTORY_INVALID_OPTIONS');
+  const cutoff = scope === 'before' ? instant(before) : null;
+  if (scope === 'before' && (typeof before !== 'string' || cutoff === null)) throw new Error('HISTORY_INVALID_CUTOFF');
+  const workspaces = records(snapshot.workspaces);
+  const sessions = records(snapshot.sessions);
+  const active = ids(snapshot.activeSessionIds);
+  // `crew` and `worktree` narrow by provenance, never by project path: a session
+  // is Crew's own only when Crew recorded creating it, and worktree scope adds
+  // the isolated-workspace marker the hub stamps at dispatch.
+  const origin = new Set(Array.isArray(snapshot.crewSessionIds) ? snapshot.crewSessionIds : []);
+  const admitted = (row) => {
+    if (scope === 'crew') return origin.has(row.id);
+    if (scope === 'worktree') return origin.has(row.id) && row.worktree === true;
+    return true;
+  };
+  const withinTime = (row) => cutoff === null
+    || (instant(row.createdAt) !== null && instant(row.createdAt) < cutoff);
+  const selected = new Set(sessions.filter(row => admitted(row) && withinTime(row)).map(row => row.id));
+  // A workspace carries no provenance of its own: it follows its sessions, and
+  // only when every one of them is selected. Checking `admitted(row)` here would
+  // test a workspace id against a session ledger and always fail. A provenance
+  // scope additionally requires at least one selected child — an empty workspace
+  // holds no Crew work, so it is not Crew's to remove; `all` keeps its historical
+  // behaviour of following an empty workspace.
+  const requiresOwnedChild = scope === 'crew' || scope === 'worktree';
+  const workspaceIds = workspaces.filter(row => {
+    const children = ids(row.sessionIds);
+    return withinTime(row) && (!requiresOwnedChild || children.length > 0)
+      && children.every(id => selected.has(id));
+  }).map(row => row.id).sort();
+  const sessionIds = [...selected].sort();
+  const signature = {
+    operation, scope, cutoff,
+    workspaces: workspaces.map(row => ({ id: row.id, createdAt: row.createdAt, updatedAt: row.updatedAt, sessionIds: ids(row.sessionIds) })),
+    sessions: sessions.map(row => ({ id: row.id, createdAt: row.createdAt, revision: row.revision })),
+    active,
+    crewSessionIds: [...origin].sort(),
+  };
+  return {
+    schemaVersion: 1, operation, scope,
+    before: cutoff === null ? null : new Date(cutoff).toISOString(),
+    timeBasis: 'createdAt', workspaceIds, sessionIds,
+    counts: { workspaces: workspaceIds.length, sessions: sessionIds.length },
+    protectedCounts: { workspaces: workspaces.length - workspaceIds.length, sessions: sessions.length - sessionIds.length },
+    executable: active.length === 0 && (workspaceIds.length > 0 || sessionIds.length > 0),
+    blockedReason: active.length > 0 ? 'ACTIVE_SESSIONS' : workspaceIds.length + sessionIds.length === 0 ? 'EMPTY_SELECTION' : null,
+    activeSessionCount: active.length,
+    projectFilesAffected: false,
+    revision: createHash('sha256').update(JSON.stringify(signature)).digest('hex'),
+  };
+}

package/src/history/http.mjs

@@ -1,32 +1,32 @@
-import { localRequestCore, originAuthorityMatches } from '../local-request-guard.mjs';
-import { safeHistoryError } from './service.mjs';
-
-export function registerHistoryHttp(webServer, service) {
-  return webServer.register({ kind: 'prefix', path: '/_dsh/dsh-crew/history', async handler(req, res) {
-    const send = (status, body) => { res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' }); res.end(JSON.stringify(body)); };
-    if (!localRequestCore(req) || (req.headers.origin !== undefined && !originAuthorityMatches(req.headers.origin, req.headers.host))) return send(403, { ok: false, code: 'HISTORY_LOCAL_ORIGIN_REQUIRED' });
-    const action = new URL(req.url, 'http://127.0.0.1').pathname.split('/').pop();
-    try {
-      if (req.method === 'GET') {
-        if (action === 'status') return send(200, { ok: true, status: service.status() });
-        if (action === 'archives') return send(200, { ok: true, archives: service.archives() });
-        return send(405, { ok: false, code: 'HISTORY_METHOD_NOT_ALLOWED' });
-      }
-      if (req.method !== 'POST') return send(405, { ok: false, code: 'HISTORY_METHOD_NOT_ALLOWED' });
-      let bytes = 0; const chunks = [];
-      for await (const chunk of req) { bytes += chunk.length; if (bytes > 4096) return send(413, { ok: false, code: 'HISTORY_BODY_TOO_LARGE' }); chunks.push(Buffer.from(chunk)); }
-      let body;
-      try { body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'); } catch { return send(400, { ok: false, code: 'HISTORY_INVALID_JSON' }); }
-      if (!body || typeof body !== 'object' || Array.isArray(body)) return send(400, { ok: false, code: 'HISTORY_INVALID_JSON' });
-      if (action === 'preview') return send(200, { ok: true, preview: await service.preview(body) });
-      if (action === 'execute') return send(202, { ok: true, status: await service.execute(body) });
-      if (action === 'restore') return send(202, { ok: true, status: await service.restore(body) });
-      if (action === 'recover') return send(202, { ok: true, status: await service.recover(body) });
-      if (action === 'fenced-check') return send(200, { ok: await service.fencedCheck() });
-      return send(404, { ok: false, code: 'HISTORY_NOT_FOUND' });
-    } catch (error) {
-      const code = safeHistoryError(error);
-      return send(/INVALID|CONFIRMATION/.test(code) ? 400 : /UNSUPPORTED|UNAVAILABLE/.test(code) ? 503 : 409, { ok: false, code });
-    }
-  } });
-}
+import { localRequestCore, originAuthorityMatches } from '../local-request-guard.mjs';
+import { safeHistoryError } from './service.mjs';
+
+export function registerHistoryHttp(webServer, service) {
+  return webServer.register({ kind: 'prefix', path: '/_dsh/dsh-crew/history', async handler(req, res) {
+    const send = (status, body) => { res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' }); res.end(JSON.stringify(body)); };
+    if (!localRequestCore(req) || (req.headers.origin !== undefined && !originAuthorityMatches(req.headers.origin, req.headers.host))) return send(403, { ok: false, code: 'HISTORY_LOCAL_ORIGIN_REQUIRED' });
+    const action = new URL(req.url, 'http://127.0.0.1').pathname.split('/').pop();
+    try {
+      if (req.method === 'GET') {
+        if (action === 'status') return send(200, { ok: true, status: service.status() });
+        if (action === 'archives') return send(200, { ok: true, archives: service.archives() });
+        return send(405, { ok: false, code: 'HISTORY_METHOD_NOT_ALLOWED' });
+      }
+      if (req.method !== 'POST') return send(405, { ok: false, code: 'HISTORY_METHOD_NOT_ALLOWED' });
+      let bytes = 0; const chunks = [];
+      for await (const chunk of req) { bytes += chunk.length; if (bytes > 4096) return send(413, { ok: false, code: 'HISTORY_BODY_TOO_LARGE' }); chunks.push(Buffer.from(chunk)); }
+      let body;
+      try { body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'); } catch { return send(400, { ok: false, code: 'HISTORY_INVALID_JSON' }); }
+      if (!body || typeof body !== 'object' || Array.isArray(body)) return send(400, { ok: false, code: 'HISTORY_INVALID_JSON' });
+      if (action === 'preview') return send(200, { ok: true, preview: await service.preview(body) });
+      if (action === 'execute') return send(202, { ok: true, status: await service.execute(body) });
+      if (action === 'restore') return send(202, { ok: true, status: await service.restore(body) });
+      if (action === 'recover') return send(202, { ok: true, status: await service.recover(body) });
+      if (action === 'fenced-check') return send(200, { ok: await service.fencedCheck() });
+      return send(404, { ok: false, code: 'HISTORY_NOT_FOUND' });
+    } catch (error) {
+      const code = safeHistoryError(error);
+      return send(/INVALID|CONFIRMATION/.test(code) ? 400 : /UNSUPPORTED|UNAVAILABLE/.test(code) ? 503 : 409, { ok: false, code });
+    }
+  } });
+}

package/src/history/operation.mjs

@@ -1,86 +1,86 @@
-import { existsSync } from 'node:fs';
-import { archiveHistory, restoreHistory, recoverHistory, finalizeHistoryDeletion, readHistoryManifest,
-  historyPath, readHistoryBytes, historyHash, decodeWorkspaceStore } from './archive-store.mjs';
-import { readHistoryState, writeHistoryState, TERMINAL_HISTORY_PHASES } from './state.mjs';
-import { safeHistoryError } from './service.mjs';
-
-function verifyDisk(root, manifest) {
-  const restored = manifest.state === 'RESTORED';
-  const rolledBack = manifest.state === 'ROLLED_BACK';
-  if (!['APPLIED', 'RESTORED', 'ROLLED_BACK', 'DELETING', 'DELETED'].includes(manifest.state)) throw Error('HISTORY_DISK_NOT_VERIFIED');
-  const expected = restored ? manifest.restoreAfter : rolledBack ? manifest.before : manifest.after;
-  const current = decodeWorkspaceStore(readHistoryBytes(historyPath(root, 'harness/storages/workspace.json')));
-  if (JSON.stringify(current) !== JSON.stringify(expected)) throw Error('HISTORY_DISK_NOT_VERIFIED');
-  for (const file of manifest.files) {
-    const path = historyPath(root, file.relativePath);
-    if (restored || rolledBack) {
-      if (!existsSync(path) || historyHash(readHistoryBytes(path)) !== file.sha256) throw Error('HISTORY_DISK_NOT_VERIFIED');
-    } else if (existsSync(path)) throw Error('HISTORY_DISK_NOT_VERIFIED');
-  }
-}
-
-/** Detached executor core; injected boundaries make the real transaction testable. */
-export async function runHistoryOperation({ crewRoot, id, acquire, release, supervisor, checkFence,
-  assertStopped, verifyRunning, recover = false }) {
-  let state = readHistoryState(crewRoot);
-  if (!state || state.id !== id) throw Error('HISTORY_OPERATION_CHANGED');
-  if (TERMINAL_HISTORY_PHASES.includes(state.phase)) return state;
-  if (!recover && state.phase !== 'QUEUED') throw Error('HISTORY_RECOVERY_REQUIRED');
-  const lock = await acquire();
-  if (!lock?.ok) throw Error('HISTORY_UPDATE_BUSY');
-  const originalPhase = state.phase === 'RECOVERY_REQUIRED' ? state.resumePhase : state.phase;
-  const save = phase => { state = { ...state, phase, code: undefined }; writeHistoryState(crewRoot, state); };
-  let result;
-  let ownsState = false;
-  try {
-    const currentState = readHistoryState(crewRoot);
-    if (currentState?.id !== state.id || currentState.phase !== state.phase) throw Error('HISTORY_OPERATION_CHANGED');
-    ownsState = true;
-    if (recover && originalPhase === 'QUEUED') {
-      state.code = 'HISTORY_CANCELLED_BEFORE_STOP';
-      state.phase = 'FAILED'; writeHistoryState(crewRoot, state);
-      return state;
-    }
-    // A process may have died after a successful restart but before finalization.
-    const alreadyStarted = recover && ['STARTING', 'VERIFYING'].includes(originalPhase) && await verifyRunning(state);
-    if (!alreadyStarted) {
-      if (!recover || await assertStopped(state) !== true) await checkFence(state);
-      save('STOPPING');
-      const stopped = await supervisor.stopOwnedBackend({ lease: state.lease, runtimeId: state.runtimeId });
-      if (!stopped?.ok || await assertStopped(state) !== true) throw Error('HISTORY_STOP_NOT_VERIFIED');
-      const archiveId = state.operation === 'restore' ? state.archiveId : state.id;
-      const manifestFile = historyPath(crewRoot, `history/transactions/${archiveId}/manifest.json`);
-      save('APPLYING');
-      const m = existsSync(manifestFile) ? readHistoryManifest(crewRoot, archiveId) : null;
-      if (recover && m && ['PREPARING', 'PREPARED', 'APPLYING', 'RESTORING'].includes(m.state)) {
-        result = await recoverHistory({ crewRoot, archiveId, assertStopped: () => assertStopped(state) });
-        state.rolledBack = true;
-      } else if (recover && m && ((state.operation !== 'restore' && ['APPLIED', 'DELETING', 'DELETED', 'ROLLED_BACK'].includes(m.state)) || m.state === 'RESTORED')) {
-        result = { id: archiveId, state: m.state };
-        state.rolledBack = m.state === 'ROLLED_BACK';
-      } else if (state.operation === 'restore') {
-        result = await restoreHistory({ crewRoot, archiveId, assertStopped: () => assertStopped(state) });
-      } else {
-        result = await archiveHistory({ crewRoot, archiveId, request: state.request, assertStopped: () => assertStopped(state) });
-      }
-      state.archiveId = result.id;
-      const manifest = readHistoryManifest(crewRoot, result.id);
-      // Recovery of a half-restored archive leaves the original archived state.
-      verifyDisk(crewRoot, manifest);
-      save('STARTING');
-      const started = await supervisor.startOwnedBackend({ lease: state.lease, runtimeId: state.runtimeId });
-      if (!started?.ok) throw Error('HISTORY_RESTART_NOT_VERIFIED');
-    }
-    save('VERIFYING');
-    if (await verifyRunning(state) !== true) throw Error('HISTORY_RESTART_NOT_VERIFIED');
-    if (state.operation === 'delete' && !state.rolledBack) {
-      await finalizeHistoryDeletion({ crewRoot, archiveId: state.archiveId ?? state.id, assertRestarted: () => verifyRunning(state) });
-    }
-    save(state.rolledBack ? 'ROLLED_BACK' : 'DONE');
-    return state;
-  } catch (error) {
-    state = { ...state, phase: 'RECOVERY_REQUIRED', resumePhase: state.phase, code: safeHistoryError(error) };
-    if (ownsState) writeHistoryState(crewRoot, state);
-    throw error;
-  } finally { await release(lock); }
-}
+import { existsSync } from 'node:fs';
+import { archiveHistory, restoreHistory, recoverHistory, finalizeHistoryDeletion, readHistoryManifest,
+  historyPath, readHistoryBytes, historyHash, decodeWorkspaceStore } from './archive-store.mjs';
+import { readHistoryState, writeHistoryState, TERMINAL_HISTORY_PHASES } from './state.mjs';
+import { safeHistoryError } from './service.mjs';
+
+function verifyDisk(root, manifest) {
+  const restored = manifest.state === 'RESTORED';
+  const rolledBack = manifest.state === 'ROLLED_BACK';
+  if (!['APPLIED', 'RESTORED', 'ROLLED_BACK', 'DELETING', 'DELETED'].includes(manifest.state)) throw Error('HISTORY_DISK_NOT_VERIFIED');
+  const expected = restored ? manifest.restoreAfter : rolledBack ? manifest.before : manifest.after;
+  const current = decodeWorkspaceStore(readHistoryBytes(historyPath(root, 'harness/storages/workspace.json')));
+  if (JSON.stringify(current) !== JSON.stringify(expected)) throw Error('HISTORY_DISK_NOT_VERIFIED');
+  for (const file of manifest.files) {
+    const path = historyPath(root, file.relativePath);
+    if (restored || rolledBack) {
+      if (!existsSync(path) || historyHash(readHistoryBytes(path)) !== file.sha256) throw Error('HISTORY_DISK_NOT_VERIFIED');
+    } else if (existsSync(path)) throw Error('HISTORY_DISK_NOT_VERIFIED');
+  }
+}
+
+/** Detached executor core; injected boundaries make the real transaction testable. */
+export async function runHistoryOperation({ crewRoot, id, acquire, release, supervisor, checkFence,
+  assertStopped, verifyRunning, recover = false }) {
+  let state = readHistoryState(crewRoot);
+  if (!state || state.id !== id) throw Error('HISTORY_OPERATION_CHANGED');
+  if (TERMINAL_HISTORY_PHASES.includes(state.phase)) return state;
+  if (!recover && state.phase !== 'QUEUED') throw Error('HISTORY_RECOVERY_REQUIRED');
+  const lock = await acquire();
+  if (!lock?.ok) throw Error('HISTORY_UPDATE_BUSY');
+  const originalPhase = state.phase === 'RECOVERY_REQUIRED' ? state.resumePhase : state.phase;
+  const save = phase => { state = { ...state, phase, code: undefined }; writeHistoryState(crewRoot, state); };
+  let result;
+  let ownsState = false;
+  try {
+    const currentState = readHistoryState(crewRoot);
+    if (currentState?.id !== state.id || currentState.phase !== state.phase) throw Error('HISTORY_OPERATION_CHANGED');
+    ownsState = true;
+    if (recover && originalPhase === 'QUEUED') {
+      state.code = 'HISTORY_CANCELLED_BEFORE_STOP';
+      state.phase = 'FAILED'; writeHistoryState(crewRoot, state);
+      return state;
+    }
+    // A process may have died after a successful restart but before finalization.
+    const alreadyStarted = recover && ['STARTING', 'VERIFYING'].includes(originalPhase) && await verifyRunning(state);
+    if (!alreadyStarted) {
+      if (!recover || await assertStopped(state) !== true) await checkFence(state);
+      save('STOPPING');
+      const stopped = await supervisor.stopOwnedBackend({ lease: state.lease, runtimeId: state.runtimeId });
+      if (!stopped?.ok || await assertStopped(state) !== true) throw Error('HISTORY_STOP_NOT_VERIFIED');
+      const archiveId = state.operation === 'restore' ? state.archiveId : state.id;
+      const manifestFile = historyPath(crewRoot, `history/transactions/${archiveId}/manifest.json`);
+      save('APPLYING');
+      const m = existsSync(manifestFile) ? readHistoryManifest(crewRoot, archiveId) : null;
+      if (recover && m && ['PREPARING', 'PREPARED', 'APPLYING', 'RESTORING'].includes(m.state)) {
+        result = await recoverHistory({ crewRoot, archiveId, assertStopped: () => assertStopped(state) });
+        state.rolledBack = true;
+      } else if (recover && m && ((state.operation !== 'restore' && ['APPLIED', 'DELETING', 'DELETED', 'ROLLED_BACK'].includes(m.state)) || m.state === 'RESTORED')) {
+        result = { id: archiveId, state: m.state };
+        state.rolledBack = m.state === 'ROLLED_BACK';
+      } else if (state.operation === 'restore') {
+        result = await restoreHistory({ crewRoot, archiveId, assertStopped: () => assertStopped(state) });
+      } else {
+        result = await archiveHistory({ crewRoot, archiveId, request: state.request, assertStopped: () => assertStopped(state) });
+      }
+      state.archiveId = result.id;
+      const manifest = readHistoryManifest(crewRoot, result.id);
+      // Recovery of a half-restored archive leaves the original archived state.
+      verifyDisk(crewRoot, manifest);
+      save('STARTING');
+      const started = await supervisor.startOwnedBackend({ lease: state.lease, runtimeId: state.runtimeId });
+      if (!started?.ok) throw Error('HISTORY_RESTART_NOT_VERIFIED');
+    }
+    save('VERIFYING');
+    if (await verifyRunning(state) !== true) throw Error('HISTORY_RESTART_NOT_VERIFIED');
+    if (state.operation === 'delete' && !state.rolledBack) {
+      await finalizeHistoryDeletion({ crewRoot, archiveId: state.archiveId ?? state.id, assertRestarted: () => verifyRunning(state) });
+    }
+    save(state.rolledBack ? 'ROLLED_BACK' : 'DONE');
+    return state;
+  } catch (error) {
+    state = { ...state, phase: 'RECOVERY_REQUIRED', resumePhase: state.phase, code: safeHistoryError(error) };
+    if (ownsState) writeHistoryState(crewRoot, state);
+    throw error;
+  } finally { await release(lock); }
+}

package/src/history/runner-detach.mjs

@@ -1,34 +1,34 @@
-// Detach the history maintenance runner from the hub's process tree.
-//
-// The runner must outlive the hub it is maintaining: its transaction stops 3210,
-// rewrites the session store while nothing holds it, then starts 3210 again. The
-// supervisor stops a service by killing that service's whole tracked process
-// tree, and the tree is walked through `ParentProcessId`. A runner spawned
-// directly by the hub is therefore inside the tree and is killed by the very stop
-// it requested, leaving the transaction stranded in STOPPING with a stale update
-// lock and no operator-side way to finish it.
-//
-// This launcher is the intermediate: it starts the runner, confirms the process
-// exists, and exits immediately. The runner's parent is then a process that no
-// longer exists, so the supervisor's tree walk cannot reach it and it survives.
-//
-// Usage: node runner-detach.mjs <runnerPath> [...runnerArgs]
-import { spawn } from 'node:child_process';
-
-const [runnerPath, ...runnerArgs] = process.argv.slice(2);
-if (!runnerPath) {
-  process.stderr.write('runner-detach: missing runner path\n');
-  process.exit(2);
-}
-
-const child = spawn(process.execPath, [runnerPath, ...runnerArgs], {
-  detached: true,
-  windowsHide: true,
-  stdio: 'ignore',
-  env: { ...process.env },
-});
-child.once('error', () => process.exit(1));
-child.once('spawn', () => {
-  child.unref();
-  process.exit(0);
-});
+// Detach the history maintenance runner from the hub's process tree.
+//
+// The runner must outlive the hub it is maintaining: its transaction stops 3210,
+// rewrites the session store while nothing holds it, then starts 3210 again. The
+// supervisor stops a service by killing that service's whole tracked process
+// tree, and the tree is walked through `ParentProcessId`. A runner spawned
+// directly by the hub is therefore inside the tree and is killed by the very stop
+// it requested, leaving the transaction stranded in STOPPING with a stale update
+// lock and no operator-side way to finish it.
+//
+// This launcher is the intermediate: it starts the runner, confirms the process
+// exists, and exits immediately. The runner's parent is then a process that no
+// longer exists, so the supervisor's tree walk cannot reach it and it survives.
+//
+// Usage: node runner-detach.mjs <runnerPath> [...runnerArgs]
+import { spawn } from 'node:child_process';
+
+const [runnerPath, ...runnerArgs] = process.argv.slice(2);
+if (!runnerPath) {
+  process.stderr.write('runner-detach: missing runner path\n');
+  process.exit(2);
+}
+
+const child = spawn(process.execPath, [runnerPath, ...runnerArgs], {
+  detached: true,
+  windowsHide: true,
+  stdio: 'ignore',
+  env: { ...process.env },
+});
+child.once('error', () => process.exit(1));
+child.once('spawn', () => {
+  child.unref();
+  process.exit(0);
+});

package/src/history/runner.mjs

@@ -1,52 +1,52 @@
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { createConnection } from 'node:net';
-import { acquireUpdateLock, releaseUpdateLock, createCrewSupervisor } from '../install/npx-lifecycle.mjs';
-import { readMaintenanceSession } from '../supervisor/restart-request.mjs';
-import { runHistoryOperation } from './operation.mjs';
-import { readHistoryState } from './state.mjs';
-import { TARGET_DSH_VERSION } from '../dsh-cohort.mjs';
-
-async function portFree() {
-  return new Promise(resolve => {
-    const socket = createConnection({ host: '127.0.0.1', port: 3210 });
-    socket.setTimeout(2000);
-    socket.once('connect', () => { socket.destroy(); resolve(false); });
-    socket.once('timeout', () => { socket.destroy(); resolve(false); });
-    socket.once('error', error => { socket.destroy(); resolve(error.code === 'ECONNREFUSED'); });
-  });
-}
-
-export async function runProductionHistory({ id, recover = false } = {}) {
-  if (process.platform !== 'win32') throw Error('HISTORY_PLATFORM_UNSUPPORTED');
-  const home = homedir(); const crewRoot = join(home, '.config', 'dsh-crew');
-  const state = readHistoryState(crewRoot);
-  id ??= state?.id;
-  if (!state || id !== state.id) throw Error('HISTORY_OPERATION_CHANGED');
-  return runHistoryOperation({ crewRoot, id, recover,
-    acquire: () => acquireUpdateLock({ home }), release: lock => releaseUpdateLock({ home, nonce: lock.nonce }),
-    supervisor: createCrewSupervisor({ home }),
-    checkFence: async () => {
-      const response = await fetch('http://127.0.0.1:3210/_dsh/dsh-crew/history/fenced-check', { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}', signal: AbortSignal.timeout(30000) });
-      if (!response.ok || (await response.json()).ok !== true) throw Error('HISTORY_FENCE_NOT_IDLE');
-    },
-    assertStopped: async s => {
-      const lease = readMaintenanceSession(crewRoot);
-      return lease.ok && lease.state === 'present' && lease.session.lease === s.lease && lease.session.runtime_id === s.runtimeId && await portFree();
-    },
-    verifyRunning: async s => {
-      try {
-        const response = await fetch('http://127.0.0.1:3210/_dsh/dsh-crew/runtime', { signal: AbortSignal.timeout(3000) });
-        const runtime = await response.json();
-        return response.ok && runtime.ok === true && runtime.service === 'dsh-crew-hub' && runtime.profile === 'dsh-crew'
-          && runtime.execution_plane === 'hub-3210' && runtime.listen_port === 3210 && runtime.protocol_version === 1
-          && runtime.dsh_version === TARGET_DSH_VERSION && typeof runtime.runtime_id === 'string' && runtime.runtime_id !== s.runtimeId;
-      } catch { return false; }
-    },
-  });
-}
-
-if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
-  runProductionHistory({ id: process.argv[2], recover: process.argv.includes('--recover') }).catch(() => { process.exitCode = 1; });
-}
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createConnection } from 'node:net';
+import { acquireUpdateLock, releaseUpdateLock, createCrewSupervisor } from '../install/npx-lifecycle.mjs';
+import { readMaintenanceSession } from '../supervisor/restart-request.mjs';
+import { runHistoryOperation } from './operation.mjs';
+import { readHistoryState } from './state.mjs';
+import { TARGET_DSH_VERSION } from '../dsh-cohort.mjs';
+
+async function portFree() {
+  return new Promise(resolve => {
+    const socket = createConnection({ host: '127.0.0.1', port: 3210 });
+    socket.setTimeout(2000);
+    socket.once('connect', () => { socket.destroy(); resolve(false); });
+    socket.once('timeout', () => { socket.destroy(); resolve(false); });
+    socket.once('error', error => { socket.destroy(); resolve(error.code === 'ECONNREFUSED'); });
+  });
+}
+
+export async function runProductionHistory({ id, recover = false } = {}) {
+  if (process.platform !== 'win32') throw Error('HISTORY_PLATFORM_UNSUPPORTED');
+  const home = homedir(); const crewRoot = join(home, '.config', 'dsh-crew');
+  const state = readHistoryState(crewRoot);
+  id ??= state?.id;
+  if (!state || id !== state.id) throw Error('HISTORY_OPERATION_CHANGED');
+  return runHistoryOperation({ crewRoot, id, recover,
+    acquire: () => acquireUpdateLock({ home }), release: lock => releaseUpdateLock({ home, nonce: lock.nonce }),
+    supervisor: createCrewSupervisor({ home }),
+    checkFence: async () => {
+      const response = await fetch('http://127.0.0.1:3210/_dsh/dsh-crew/history/fenced-check', { method: 'POST', headers: { 'content-type': 'application/json' }, body: '{}', signal: AbortSignal.timeout(30000) });
+      if (!response.ok || (await response.json()).ok !== true) throw Error('HISTORY_FENCE_NOT_IDLE');
+    },
+    assertStopped: async s => {
+      const lease = readMaintenanceSession(crewRoot);
+      return lease.ok && lease.state === 'present' && lease.session.lease === s.lease && lease.session.runtime_id === s.runtimeId && await portFree();
+    },
+    verifyRunning: async s => {
+      try {
+        const response = await fetch('http://127.0.0.1:3210/_dsh/dsh-crew/runtime', { signal: AbortSignal.timeout(3000) });
+        const runtime = await response.json();
+        return response.ok && runtime.ok === true && runtime.service === 'dsh-crew-hub' && runtime.profile === 'dsh-crew'
+          && runtime.execution_plane === 'hub-3210' && runtime.listen_port === 3210 && runtime.protocol_version === 1
+          && runtime.dsh_version === TARGET_DSH_VERSION && typeof runtime.runtime_id === 'string' && runtime.runtime_id !== s.runtimeId;
+      } catch { return false; }
+    },
+  });
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  runProductionHistory({ id: process.argv[2], recover: process.argv.includes('--recover') }).catch(() => { process.exitCode = 1; });
+}