@ran-sh/dsh-crew 1.1.0 → 1.2.0-rc.4

package/src/extension-contract.mjs

@@ -2,7 +2,9 @@
 // describes only DSH Crew and deliberately never advertises itself as a top-
 // level Executor or control plane.
 
-export const EXTENSION_CONTRACT_SCHEMA_VERSION = 1;
+import { validateModelCallabilityV2 } from './model-callability-contract.mjs';
+
+export const EXTENSION_CONTRACT_SCHEMA_VERSION = 1;
 
 function row(matrix, id) {
   return Array.isArray(matrix?.rows) ? matrix.rows.find((entry) => entry?.id === id) : undefined;
@@ -34,40 +36,56 @@ function readinessFromRow(entry, { pass = 'READY', notRun = 'DEGRADED' } = {}) {
   return component('UNAVAILABLE', entry.reason_code ?? 'CHECK_FAILED');
 }
 
-export function buildExtensionContract({ config = {}, readinessMatrix = {}, readinessSnapshot = null, workspace = null, profiles = null, runtime = null } = {}) {
-  const matrix = readinessSnapshot?.readiness_matrix ?? readinessMatrix;
+function modelReadinessFromSnapshot(readinessSnapshot, matrix, runtime, expectedEnabledRoles, now = Date.now()) {
+  const callability = readinessSnapshot?.model_callability;
+  const providerHealthEvidence = row(matrix, 'provider_health');
+  const catalogEvidence = row(matrix, 'provider_catalog');
+  if (callability && typeof callability === 'object') {
+    const validation = validateModelCallabilityV2({
+      projection: callability,
+      runtime,
+      expectedEnabledRoles,
+      expectedSelections: { worker: readinessSnapshot?.worker?.selected ?? null, reviewer: readinessSnapshot?.reviewer?.selected ?? null },
+      now,
+    });
+    if (validation.ok && validation.state === 'CALLABLE') return component('READY', 'CURRENT_MODEL_CALLABLE', { captured_at: callability.captured_at, expires_at: callability.expires_at, runtime_id: callability.current_runtime_id });
+    if (validation.ok && validation.state === 'NOT_CALLABLE') return component('UNAVAILABLE', callability.roles.worker?.state === 'NOT_CALLABLE' ? callability.roles.worker.reason_code : callability.roles.reviewer.reason_code ?? 'CURRENT_MODEL_NOT_CALLABLE');
+    if (validation.ok && validation.state === 'STALE') return component('DEGRADED', 'MODEL_EVIDENCE_STALE');
+    return component('DEGRADED', validation.reason_code ?? 'MODEL_CALLABILITY_UNKNOWN');
+  }
+  if (providerHealthEvidence?.status === 'FAIL') return readinessFromRow(providerHealthEvidence);
+  if (catalogEvidence?.status === 'FAIL') return readinessFromRow(catalogEvidence);
+  if (providerHealthEvidence || catalogEvidence) return component('DEGRADED', 'MODEL_CALLABILITY_NOT_PROJECTED');
+  return component('UNAVAILABLE', 'MODEL_CALLABILITY_NOT_PROJECTED');
+}
+
+export function buildExtensionContract({ config = {}, readinessMatrix = {}, readinessSnapshot = null, workspace = null, profiles = null, runtime = null } = {}) {
+  const matrix = readinessSnapshot?.readiness_matrix ?? readinessMatrix;
   const workerEnabled = config.subagents_enabled !== false && config.worker_state !== 'disabled';
   const reviewerEnabled = config.subagents_enabled !== false && config.review_state !== 'disabled';
-  const realModelEvidence = ['worker_primary_callable', 'model_execution', 'worker_escalation_callable', 'deepseek_flash', 'deepseek_pro']
-    .map((id) => row(matrix, id))
-    .find((entry) => entry?.status === 'PASS');
-  const catalogEvidence = row(matrix, 'provider_catalog');
-  const lifecycleEvidence = row(matrix, 'provider_lifecycle_consistent');
-  const modelReadiness = catalogEvidence?.status === 'FAIL'
-    ? readinessFromRow(catalogEvidence)
-    : realModelEvidence
-      ? component('READY', realModelEvidence.reason_code ?? 'MODEL_EXECUTION_PASSED')
-      : catalogEvidence?.status === 'PASS' || catalogEvidence?.status === 'SKIP'
-        ? component('DEGRADED', 'MODEL_CATALOG_ONLY')
-        : component('UNAVAILABLE', catalogEvidence?.reason_code ?? 'NO_EVIDENCE');
-  const components = {
-    harness: readinessFromRow(row(matrix, 'hub_compatibility')),
-    provider_lifecycle: lifecycleEvidence
-      ? readinessFromRow(lifecycleEvidence, { notRun: 'DEGRADED' })
-      : component('DEGRADED', 'PROVIDER_LIFECYCLE_NOT_CHECKED'),
-    model: modelReadiness,
+  const reviewerHealthEvidence = row(matrix, 'reviewer_health');
+  const lifecycleEvidence = row(matrix, 'provider_lifecycle_consistent');
+  const modelReadiness = modelReadinessFromSnapshot(readinessSnapshot, matrix, runtime, { worker: workerEnabled, reviewer: reviewerEnabled });
+  const components = {
+    harness: readinessFromRow(row(matrix, 'hub_compatibility')),
+    provider_lifecycle: lifecycleEvidence
+      ? readinessFromRow(lifecycleEvidence, { notRun: 'DEGRADED' })
+      : component('DEGRADED', 'PROVIDER_LIFECYCLE_NOT_CHECKED'),
+    model: modelReadiness,
     workspace: workspaceComponent(workspace),
     reviewer: reviewerEnabled
-      ? readinessFromRow(row(matrix, 'reviewer_pipeline'))
-      : component('DEGRADED', 'REVIEWER_DISABLED'),
+      ? reviewerHealthEvidence?.status === 'FAIL'
+        ? readinessFromRow(reviewerHealthEvidence)
+        : readinessFromRow(row(matrix, 'reviewer_pipeline'))
+      : component('NOT_APPLICABLE', 'REVIEWER_DISABLED'),
   };
-  const states = Object.values(components).map((entry) => entry.status);
+  const states = Object.entries(components).filter(([key]) => key !== 'reviewer' || reviewerEnabled).map(([, entry]) => entry.status);
   const readiness = states.includes('UNAVAILABLE') ? 'UNAVAILABLE' : states.includes('DEGRADED') ? 'DEGRADED' : 'READY';
   return {
     schema_version: EXTENSION_CONTRACT_SCHEMA_VERSION,
     kind: 'dsh-crew-extension',
-    runtime: runtime ?? null,
-    ...(readinessSnapshot ? { readiness_snapshot: readinessSnapshot } : {}),
+    runtime: runtime ?? null,
+    ...(readinessSnapshot ? { readiness_snapshot: readinessSnapshot } : {}),
     capabilities: {
       'deepseek.worker': workerEnabled,
       'deepseek.reviewer': reviewerEnabled,

package/src/history/admission-gate.mjs

@@ -0,0 +1,51 @@
+/**
+ * Crew-profile-only runtime adapter. Fence the public agent creation entry,
+ * including creations still awaiting publication in the official agent list.
+ * Callers must persist their maintenance marker BEFORE asking idle().
+ * No original agent is cancelled or disposed by this adapter.
+ */
+const installed = new WeakSet();
+const guarded = Symbol.for('dsh-crew.history.admission');
+function method(object, name) {
+  for (let current = object; current; current = Object.getPrototypeOf(current)) {
+    const descriptor = Object.getOwnPropertyDescriptor(current, name);
+    if (descriptor) return descriptor.value;
+  }
+}
+
+export function installHistoryAdmissionGate(agents, isMaintenancePending) {
+  if (typeof agents?.create !== 'function' || typeof agents?.list !== 'function'
+    || typeof isMaintenancePending !== 'function') throw new Error('HISTORY_ADMISSION_UNAVAILABLE');
+  if (installed.has(agents)) throw new Error('HISTORY_ADMISSION_ALREADY_INSTALLED');
+  const entries = ['create', 'resume'].filter(name => typeof method(agents, name) === 'function')
+    .map(name => ({ name, original: method(agents, name), wrapper: null }));
+  if (!entries.some(entry => entry.name === 'create')) throw new Error('HISTORY_ADMISSION_UNAVAILABLE');
+  if (entries.some(entry => entry.original[guarded])) throw new Error('HISTORY_ADMISSION_ALREADY_INSTALLED');
+  let creating = 0;
+  for (const entry of entries) {
+    entry.wrapper = async function(...args) {
+      if (isMaintenancePending()) throw new Error('HISTORY_MAINTENANCE_PENDING');
+      creating += 1;
+      try { return await entry.original.apply(this, args); }
+      finally { creating -= 1; }
+    };
+    entry.wrapper[guarded] = true;
+    agents[entry.name] = entry.wrapper;
+  }
+  installed.add(agents);
+  return {
+    idle() {
+      // Cordis returns fresh traceable callable proxies; compare descriptors,
+      // not the per-access wrapper returned by agents.create/resume.
+      if (entries.some(entry => method(agents, entry.name) !== entry.wrapper)) return false;
+      try {
+        const live = agents.list();
+        return Array.isArray(live) && creating === 0 && live.length === 0;
+      } catch { return false; }
+    },
+    dispose() {
+      for (const entry of entries) if (method(agents, entry.name) === entry.wrapper) agents[entry.name] = entry.original;
+      installed.delete(agents);
+    },
+  };
+}

package/src/history/archive-store.mjs

@@ -0,0 +1,261 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+const WORKSPACE = 'harness/storages/workspace.json';
+const LIMIT = 512 * 1024 * 1024;
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object'
+  ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
+const equal = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+const validId = id => typeof id === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,255}$/.test(id);
+const fail = code => { throw new Error(`HISTORY_${code}`); };
+
+function pathInside(root, relativePath) {
+  if (typeof relativePath !== 'string' || isAbsolute(relativePath) || relativePath.includes('\\')
+    || relativePath.includes(':') || relativePath.split('/').some(p => !p || p === '.' || p === '..')) fail('INVALID_PATH');
+  let current = resolve(root);
+  if (!lstatSync(current).isDirectory() || lstatSync(current).isSymbolicLink()) fail('LINKED_ROOT');
+  const canonical = realpathSync(current);
+  if ((process.platform === 'win32' ? canonical.toLowerCase() !== current.toLowerCase() : canonical !== current)) fail('LINKED_ROOT');
+  for (const part of relativePath.split('/')) {
+    current = join(current, part);
+    try { if (lstatSync(current).isSymbolicLink()) fail('LINKED_PATH'); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return current;
+}
+
+function artifactPath(root, file) {
+  if (!validId(file?.sessionId) || typeof file.relativePath !== 'string'
+    || !/^harness\/sessions\/[^/]+\/[^/]+\/session\.jsonl(?:\.zstd)?$/.test(file.relativePath)
+    || file.relativePath.split('/')[3] !== file.sessionId) fail('INVALID_ARTIFACT');
+  return pathInside(root, file.relativePath);
+}
+
+function readBounded(file) {
+  const info = lstatSync(file);
+  if (!info.isFile() || info.isSymbolicLink() || info.size > LIMIT) fail('INVALID_FILE');
+  const bytes = readFileSync(file);
+  if (bytes.length > LIMIT || bytes.length !== info.size) fail('FILE_CHANGED');
+  return bytes;
+}
+
+function atomic(root, relativePath, bytes, exclusive = false) {
+  const file = pathInside(root, relativePath);
+  mkdirSync(dirname(file), { recursive: true });
+  pathInside(root, relativePath);
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  let fd;
+  try {
+    fd = openSync(temporary, 'wx', 0o600); writeFileSync(fd, bytes); fsyncSync(fd); closeSync(fd); fd = undefined;
+    if (exclusive) {
+      try { linkSync(temporary, file); }
+      catch (error) { if (error.code === 'EEXIST') fail('RESTORE_CONFLICT'); throw error; }
+    } else renameSync(temporary, file);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}
+
+function decodeStore(bytes) {
+  let store;
+  try { store = JSON.parse(bytes.toString('utf8')); } catch { fail('INVALID_STORAGE'); }
+  if (store?.unit?.name !== 'workspace' || store.unit.version !== 2 || store.global?.initialized !== true
+    || store.global.pendingMutation || !Array.isArray(store.global.workspaceIds) || !Array.isArray(store.global.archivedSessionIds)
+    || !store.tables?.workspaces || Array.isArray(store.tables.workspaces)) fail('UNSUPPORTED_STORAGE');
+  if (store.global.archivedSessionIds.some(id => !validId(id))
+    || new Set(store.global.archivedSessionIds).size !== store.global.archivedSessionIds.length) fail('INVALID_STORAGE');
+  const table = store.tables.workspaces;
+  if (Object.keys(table).length > 10000 || store.global.workspaceIds.length !== Object.keys(table).length
+    || new Set(store.global.workspaceIds).size !== store.global.workspaceIds.length
+    || store.global.workspaceIds.some(id => !validId(id) || !Object.hasOwn(table, id))) fail('INVALID_STORAGE');
+  for (const record of Object.values(table)) if (!record || !Array.isArray(record.sessionIds)
+    || record.sessionIds.some(id => !validId(id)) || typeof record.path !== 'string') fail('INVALID_STORAGE');
+  return store;
+}
+
+function batchPath(id) {
+  if (typeof id !== 'string' || !/^[a-f0-9-]{36}$/.test(id)) fail('INVALID_ARCHIVE_ID');
+  return `history/transactions/${id}`;
+}
+
+function saveManifest(root, manifest) {
+  atomic(root, `${batchPath(manifest.id)}/manifest.json`, JSON.stringify(manifest));
+}
+
+function loadManifest(root, id) {
+  let manifest;
+  try { manifest = JSON.parse(readBounded(pathInside(root, `${batchPath(id)}/manifest.json`))); }
+  catch { fail('INVALID_MANIFEST'); }
+  if (manifest.id !== id || manifest.schemaVersion !== 1 || !['archive', 'delete'].includes(manifest.operation)
+    || !Array.isArray(manifest.files) || manifest.files.length > 10000
+    || !['PREPARING', 'PREPARED', 'APPLYING', 'APPLIED', 'RESTORING', 'RESTORED', 'ROLLED_BACK', 'DELETING', 'DELETED'].includes(manifest.state)
+    || manifest.files.some(file => !file || !/^[a-f0-9]{64}$/.test(file.sha256) || !Number.isSafeInteger(file.size) || file.size < 0)
+    || new Set(manifest.files.map(file => file.sessionId)).size !== manifest.files.length
+    || new Set(manifest.files.map(file => file.relativePath)).size !== manifest.files.length
+    || manifest.files.reduce((total, file) => total + file.size, 0) > LIMIT) fail('INVALID_MANIFEST');
+  decodeStore(Buffer.from(JSON.stringify(manifest.before)));
+  decodeStore(Buffer.from(JSON.stringify(manifest.after)));
+  for (const file of manifest.files) artifactPath(root, file);
+  if (manifest.state === 'RESTORING') {
+    decodeStore(Buffer.from(JSON.stringify(manifest.restoreBefore ?? null)));
+    decodeStore(Buffer.from(JSON.stringify(manifest.restoreAfter ?? null)));
+  }
+  return manifest;
+}
+
+async function requireStopped(assertStopped) {
+  if (typeof assertStopped !== 'function' || await assertStopped() !== true) fail('BACKEND_NOT_STOPPED');
+}
+
+/** Internal offline primitive: caller must own the maintenance lease + update lock. */
+export async function archiveHistory({ crewRoot, request, assertStopped, archiveId = randomUUID() }) {
+  await requireStopped(assertStopped);
+  if (!request || !['archive', 'delete'].includes(request.operation) || !Array.isArray(request.artifacts)
+    || !Array.isArray(request.sessionIds) || !Array.isArray(request.workspaceIds)
+    || request.artifacts.length > 10000 || request.workspaceIds.length > 10000) fail('INVALID_REQUEST');
+  const selectedSessions = new Set(request.sessionIds);
+  const selectedWorkspaces = new Set(request.workspaceIds);
+  if ([...selectedSessions, ...selectedWorkspaces].some(id => !validId(id))
+    || selectedSessions.size !== request.sessionIds.length || selectedWorkspaces.size !== request.workspaceIds.length
+    || request.artifacts.length !== selectedSessions.size
+    || new Set(request.artifacts.map(f => f.sessionId)).size !== selectedSessions.size
+    || request.artifacts.some(f => !selectedSessions.has(f.sessionId))) fail('INVALID_SELECTION');
+  const beforeBytes = readBounded(pathInside(crewRoot, WORKSPACE));
+  if (hash(beforeBytes) !== request.workspaceHash) fail('PREVIEW_CHANGED');
+  const before = decodeStore(beforeBytes);
+  const after = structuredClone(before);
+  for (const id of selectedWorkspaces) {
+    const record = before.tables.workspaces[id];
+    if (!record || record.sessionIds.some(sid => !selectedSessions.has(sid))) fail('PREVIEW_CHANGED');
+    delete after.tables.workspaces[id];
+  }
+  after.global.workspaceIds = after.global.workspaceIds.filter(id => !selectedWorkspaces.has(id));
+  after.global.archivedSessionIds = after.global.archivedSessionIds.filter(id => !selectedSessions.has(id));
+  for (const record of Object.values(after.tables.workspaces)) record.sessionIds = record.sessionIds.filter(id => !selectedSessions.has(id));
+  let size = 0;
+  const files = request.artifacts.map(file => {
+    const bytes = readBounded(artifactPath(crewRoot, file));
+    size += bytes.length;
+    if (size > LIMIT) fail('ARCHIVE_TOO_LARGE');
+    if (hash(bytes) !== file.sha256) fail('PREVIEW_CHANGED');
+    return { sessionId: file.sessionId, relativePath: file.relativePath, sha256: file.sha256, size: bytes.length };
+  });
+  if (existsSync(pathInside(crewRoot, `${batchPath(archiveId)}/manifest.json`))) fail('ARCHIVE_EXISTS');
+  const manifest = { schemaVersion: 1, id: archiveId, operation: request.operation,
+    createdAt: new Date().toISOString(), state: 'PREPARING', files, before, after };
+  saveManifest(crewRoot, manifest);
+  try {
+    for (const [index, file] of files.entries()) {
+      atomic(crewRoot, `${batchPath(manifest.id)}/files/${index}.bin`, readBounded(artifactPath(crewRoot, file)));
+      if (hash(readBounded(pathInside(crewRoot, `${batchPath(manifest.id)}/files/${index}.bin`))) !== file.sha256) fail('BACKUP_CHANGED');
+    }
+    manifest.state = 'PREPARED'; saveManifest(crewRoot, manifest);
+    await requireStopped(assertStopped);
+    if (hash(readBounded(pathInside(crewRoot, WORKSPACE))) !== request.workspaceHash) fail('PREVIEW_CHANGED');
+    for (const file of files) if (hash(readBounded(artifactPath(crewRoot, file))) !== file.sha256) fail('PREVIEW_CHANGED');
+    manifest.state = 'APPLYING'; saveManifest(crewRoot, manifest);
+    for (const file of files) unlinkSync(artifactPath(crewRoot, file));
+    atomic(crewRoot, WORKSPACE, JSON.stringify(after));
+    manifest.state = 'APPLIED'; saveManifest(crewRoot, manifest);
+    return { id: manifest.id, state: manifest.state, operation: manifest.operation, counts: { sessions: files.length, workspaces: selectedWorkspaces.size } };
+  } catch (error) {
+    // The caller retains the stopped lease. Never restart after this exception
+    // without explicitly recovering the referenced durable transaction.
+    error.archiveId = manifest.id;
+    throw error;
+  }
+}
+
+// Shared internal IO for the controller; no paths are accepted from HTTP clients.
+export { pathInside as historyPath, readBounded as readHistoryBytes, atomic as writeHistoryBytes,
+  decodeStore as decodeWorkspaceStore, loadManifest as readHistoryManifest, hash as historyHash };
+
+export async function restoreHistory({ crewRoot, archiveId, assertStopped }) {
+  await requireStopped(assertStopped);
+  const manifest = loadManifest(crewRoot, archiveId);
+  if (manifest.operation !== 'archive' || manifest.state !== 'APPLIED') fail('ARCHIVE_NOT_RESTORABLE');
+  const currentBytes = readBounded(pathInside(crewRoot, WORKSPACE));
+  const current = decodeStore(currentBytes);
+  const next = structuredClone(current);
+  const restoredIds = [];
+  for (const [id, old] of Object.entries(manifest.before.tables.workspaces)) {
+    const after = manifest.after.tables.workspaces[id];
+    if (equal(old, after)) continue;
+    if (!equal(current.tables.workspaces[id], after)) fail('RESTORE_CONFLICT');
+    if (Object.entries(current.tables.workspaces).some(([other, record]) => other !== id && record.path === old.path)) fail('RESTORE_CONFLICT');
+    next.tables.workspaces[id] = old;
+    if (after === undefined) restoredIds.push(id);
+  }
+  next.global.workspaceIds = [...manifest.before.global.workspaceIds.filter(id => restoredIds.includes(id)), ...current.global.workspaceIds];
+  const selected = new Set(manifest.files.map(file => file.sessionId));
+  next.global.archivedSessionIds = [...new Set([...current.global.archivedSessionIds, ...manifest.before.global.archivedSessionIds.filter(id => selected.has(id))])];
+  for (const [index, file] of manifest.files.entries()) {
+    if (existsSync(artifactPath(crewRoot, file))) fail('RESTORE_CONFLICT');
+    if (hash(readBounded(pathInside(crewRoot, `${batchPath(archiveId)}/files/${index}.bin`))) !== file.sha256) fail('BACKUP_CHANGED');
+  }
+  manifest.restoreBefore = current; manifest.restoreAfter = next; manifest.state = 'RESTORING'; saveManifest(crewRoot, manifest);
+  await requireStopped(assertStopped);
+  if (hash(readBounded(pathInside(crewRoot, WORKSPACE))) !== hash(currentBytes)) fail('RESTORE_CONFLICT');
+  for (const [index, file] of manifest.files.entries()) {
+    artifactPath(crewRoot, file);
+    // A durable temporary file is published exclusively. A crash cannot leave
+    // a partially written target that recovery mistakes for someone else's data.
+    atomic(crewRoot, file.relativePath, readBounded(pathInside(crewRoot, `${batchPath(archiveId)}/files/${index}.bin`)), true);
+  }
+  atomic(crewRoot, WORKSPACE, JSON.stringify(next));
+  manifest.state = 'RESTORED'; saveManifest(crewRoot, manifest);
+  return { id: archiveId, state: manifest.state };
+}
+
+/** Roll back an interrupted offline operation. The caller retains its stop lease. */
+export async function recoverHistory({ crewRoot, archiveId, assertStopped }) {
+  await requireStopped(assertStopped);
+  const manifest = loadManifest(crewRoot, archiveId);
+  if (manifest.state === 'ROLLED_BACK') return { id: archiveId, state: manifest.state };
+  if (!['PREPARING', 'PREPARED', 'APPLYING', 'APPLIED', 'RESTORING'].includes(manifest.state)) fail('RECOVERY_UNAVAILABLE');
+  const restoring = manifest.state === 'RESTORING';
+  const desired = restoring ? manifest.restoreBefore : manifest.before;
+  const possible = restoring ? manifest.restoreAfter : manifest.after;
+  decodeStore(Buffer.from(JSON.stringify(desired)));
+  decodeStore(Buffer.from(JSON.stringify(possible)));
+  const currentBytes = readBounded(pathInside(crewRoot, WORKSPACE));
+  const current = decodeStore(currentBytes);
+  if (!equal(current, desired) && !equal(current, possible)) fail('RECOVERY_CONFLICT');
+  const touched = !['PREPARING', 'PREPARED'].includes(manifest.state);
+  for (const [index, file] of manifest.files.entries()) {
+    const target = artifactPath(crewRoot, file);
+    if (existsSync(target) && hash(readBounded(target)) !== file.sha256) fail('RECOVERY_CONFLICT');
+    if (!touched && !existsSync(target)) fail('RECOVERY_CONFLICT');
+    if (touched && hash(readBounded(pathInside(crewRoot, `${batchPath(archiveId)}/files/${index}.bin`))) !== file.sha256) fail('BACKUP_CHANGED');
+  }
+  await requireStopped(assertStopped);
+  if (hash(readBounded(pathInside(crewRoot, WORKSPACE))) !== hash(currentBytes)) fail('RECOVERY_CONFLICT');
+  for (const [index, file] of manifest.files.entries()) {
+    const target = artifactPath(crewRoot, file);
+    if (restoring) { if (existsSync(target)) unlinkSync(target); }
+    else if (!existsSync(target)) {
+      atomic(crewRoot, file.relativePath, readBounded(pathInside(crewRoot, `${batchPath(archiveId)}/files/${index}.bin`)), true);
+    }
+  }
+  atomic(crewRoot, WORKSPACE, JSON.stringify(desired));
+  manifest.state = restoring ? 'APPLIED' : 'ROLLED_BACK'; saveManifest(crewRoot, manifest);
+  return { id: archiveId, state: manifest.state };
+}
+
+/** The private rollback artifacts are purged only after the new runtime is verified. */
+export async function finalizeHistoryDeletion({ crewRoot, archiveId, assertRestarted }) {
+  if (typeof assertRestarted !== 'function' || await assertRestarted() !== true) fail('RESTART_NOT_VERIFIED');
+  const manifest = loadManifest(crewRoot, archiveId);
+  if (manifest.operation !== 'delete' || !['APPLIED', 'DELETING', 'DELETED'].includes(manifest.state)) fail('DELETE_UNAVAILABLE');
+  if (manifest.state === 'DELETED') return { id: archiveId, state: manifest.state };
+  manifest.state = 'DELETING'; saveManifest(crewRoot, manifest);
+  for (const [index] of manifest.files.entries()) {
+    const backup = pathInside(crewRoot, `${batchPath(archiveId)}/files/${index}.bin`);
+    if (existsSync(backup)) unlinkSync(backup);
+  }
+  manifest.state = 'DELETED'; saveManifest(crewRoot, manifest);
+  return { id: archiveId, state: manifest.state };
+}

package/src/history/cleanup-plan.mjs

@@ -0,0 +1,64 @@
+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. */
+export function planHistoryCleanup(snapshot, { operation = 'archive', scope = 'all', before } = {}) {
+  if (!['archive', 'delete'].includes(operation) || !['all', '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);
+  const selected = new Set(sessions.filter(row => scope === 'all' || (instant(row.createdAt) !== null && instant(row.createdAt) < cutoff)).map(row => row.id));
+  const workspaceIds = workspaces.filter(row => {
+    const children = ids(row.sessionIds);
+    return (scope === 'all' || (instant(row.createdAt) !== null && instant(row.createdAt) < cutoff))
+      && 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,
+  };
+  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

@@ -0,0 +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 });
+    }
+  } });
+}

package/src/history/operation.mjs

@@ -0,0 +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); }
+}

package/src/history/runner.mjs

@@ -0,0 +1,51 @@
+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';
+
+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 === '0.1.2-rc.1' && 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; });
+}