@ngockhoale/ukit 3.4.27 → 3.4.28

package/src/core/diffPlan.js

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import { isSymlinkTo } from './fileOps.js';
 import { GATEWAY_RESILIENCE_ENV_DEFAULTS } from './gatewayResilienceEnv.js';
 import { isOmpConfigTarget, mergeOmpConfig } from './ompConfigMerge.js';
+import { mergeRuntimeConfigText } from './runtimeConfigMerge.js';
 
 const GATEWAY_RESILIENCE_KEYS = new Set(Object.keys(GATEWAY_RESILIENCE_ENV_DEFAULTS));
 
@@ -45,130 +46,121 @@ async function checkLinkStatus(targetPath, linkTarget) {
   }
 }
 
-// Settings.json uses a strategy where only the gateway-resilience env keys (managed by
-// applyGatewayResilienceEnv post-apply) are ignored during the diff. Every other top-level
-// key — including the rest of the env block — is still compared byte-for-byte against the
-// template, so a template-side change to e.g. CLAUDE_CODE_AUTO_COMPACT_WINDOW still triggers
-// a real reinstall. Without this carve-out, the managed gateway keys written by the post-apply
-// step would cause a spurious "update" on every subsequent install.
-//
-// `permissions.defaultMode` is user-owned: the user picks their permission mode
-// (bypassPermissions / plan / acceptEdits / default) and UKit must never change it.
-// It is excluded from the drift comparison AND re-injected into the rendered content
-// before write (mergeSettingsJson), so an install/update can never flip the user's mode.
-// When the user has NOT set it, the template's shipped default applies on create/update.
-const USER_OWNED_PERMISSION_KEYS = new Set(['defaultMode']);
+// Settings.json ownership model (U1). `.claude/settings.json` is a shared file: UKit ships
+// a baseline and users customise it. Ownership per key:
+//   UKit-owned (template always wins):  `hooks` (the safety/enforcement wiring), the
+//                                       template's own `env` keys, and every `permissions.deny`
+//                                       entry the template ships.
+//   Additive (union, template first):   `permissions.allow|deny|ask|additionalDirectories` —
+//                                       user entries are kept; the template's entries are
+//                                       always present.
+//   User-owned (existing wins):         `permissions.defaultMode`, and every other key the
+//                                       user already has (model, effortLevel, statusLine,
+//                                       enabledPlugins, unknown/future keys, user env keys…).
+//   Template-filled:                    keys the user does not have take the template value.
+// Gateway-resilience env keys are post-apply managed (applyGatewayResilienceEnv) and are
+// ignored by the drift comparison.
+const UKIT_OWNED_TOP_LEVEL_KEYS = new Set(['hooks']);
+const PERMISSION_LIST_KEYS = new Set(['allow', 'deny', 'ask', 'additionalDirectories']);
+const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
 
 function parseSettingsJson(content) {
   if (typeof content !== 'string') return null;
   try {
     const parsed = JSON.parse(content);
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    return isPlainObject(parsed) ? parsed : null;
   } catch {
     return null;
   }
 }
 
-// Strip user-owned permission keys from a parsed permissions object for comparison.
-// Returns a new object; never mutates the input.
-function stripUserOwnedPermissionKeys(permissions) {
-  if (!permissions || typeof permissions !== 'object' || Array.isArray(permissions)) {
-    return permissions;
-  }
-  const stripped = { ...permissions };
-  for (const key of USER_OWNED_PERMISSION_KEYS) delete stripped[key];
-  return stripped;
-}
-
-// Merge rendered settings.json with the user's existing file: the rendered template
-// wins every key EXCEPT user-owned permission keys (currently permissions.defaultMode),
-// which keep the value the user set. Returns the merged JSON as a string, or the
-// rendered content unchanged when either side is unparseable.
-export function mergeSettingsJson(existingContent, renderedContent) {
-  const existing = parseSettingsJson(existingContent);
-  const rendered = parseSettingsJson(renderedContent);
-  if (!existing || !rendered) return renderedContent;
-  const merged = { ...rendered };
-  if (existing.permissions && typeof existing.permissions === 'object' && !Array.isArray(existing.permissions)) {
-    const mergedPermissions = { ...(rendered.permissions && typeof rendered.permissions === 'object' ? rendered.permissions : {}) };
-    for (const key of USER_OWNED_PERMISSION_KEYS) {
-      if (key in existing.permissions) mergedPermissions[key] = existing.permissions[key];
+function unionList(templateList, userList) {
+  const out = Array.isArray(templateList) ? [...templateList] : [];
+  if (!Array.isArray(userList)) return out;
+  const seen = new Set(out.map((item) => JSON.stringify(item)));
+  for (const item of userList) {
+    const key = JSON.stringify(item);
+    if (!seen.has(key)) {
+      seen.add(key);
+      out.push(item);
     }
-    merged.permissions = mergedPermissions;
   }
-  return `${JSON.stringify(merged, null, 2)}\n`;
+  return out;
 }
 
-function settingsJsonIgnoresGatewayEnvDiff(existingContent, renderedContent) {
-  if (typeof existingContent !== 'string' || typeof renderedContent !== 'string') {
-    return false;
-  }
-  let parsedExisting;
-  let parsedRendered;
-  try {
-    parsedExisting = JSON.parse(existingContent);
-    parsedRendered = JSON.parse(renderedContent);
-  } catch {
-    return false;
+function mergeSettingsObjects(existing, rendered) {
+  const merged = {};
+  for (const key of Object.keys(rendered)) {
+    if (BLOCKED_KEYS.has(key)) continue;
+    merged[key] = rendered[key];
   }
-  if (!parsedExisting || typeof parsedExisting !== 'object' || Array.isArray(parsedExisting)) {
-    return false;
-  }
-  if (!parsedRendered || typeof parsedRendered !== 'object' || Array.isArray(parsedRendered)) {
-    return false;
-  }
-
-  for (const key of Object.keys(parsedRendered)) {
-    if (key === 'env') continue;
-    if (!(key in parsedExisting)) return false;
-    const renderedValue = key === 'permissions'
-      ? stripUserOwnedPermissionKeys(parsedRendered[key])
-      : parsedRendered[key];
-    const existingValue = key === 'permissions'
-      ? stripUserOwnedPermissionKeys(parsedExisting[key])
-      : parsedExisting[key];
-    if (JSON.stringify(existingValue) !== JSON.stringify(renderedValue)) {
-      return false;
+  for (const [key, userValue] of Object.entries(existing)) {
+    if (BLOCKED_KEYS.has(key) || UKIT_OWNED_TOP_LEVEL_KEYS.has(key)) continue;
+    if (!(key in rendered)) {
+      merged[key] = userValue; // unknown/user key — preserved
+      continue;
+    }
+    const templateValue = rendered[key];
+    if (key === 'permissions' && isPlainObject(userValue) && isPlainObject(templateValue)) {
+      const permissions = { ...templateValue };
+      for (const [pKey, pValue] of Object.entries(userValue)) {
+        if (BLOCKED_KEYS.has(pKey)) continue;
+        if (PERMISSION_LIST_KEYS.has(pKey)) {
+          permissions[pKey] = unionList(templateValue[pKey], pValue);
+        } else {
+          permissions[pKey] = pValue; // defaultMode + unknown permission keys are user-owned
+        }
+      }
+      merged.permissions = permissions;
+    } else if (key === 'env' && isPlainObject(userValue) && isPlainObject(templateValue)) {
+      merged.env = { ...userValue, ...templateValue };
+    } else if (key === 'permissions' || key === 'env') {
+      // user value has the wrong shape (e.g. permissions: "x") — template shape wins
+      merged[key] = templateValue;
+    } else {
+      merged[key] = userValue; // user-owned scalar/section (model, effortLevel, …)
     }
   }
+  return merged;
+}
 
-  // Reverse direction: an existing top-level key that the template does NOT ship is also
-  // drift. Catches template key REMOVAL (e.g. a previous template shipped `permissions`
-  // and the new one dropped it) and user-side additions. The `merge_env_overwrite_with_backup`
-  // strategy is a narrowed overwrite — the only carve-out is the UKit-managed gateway env
-  // keys below — so every other byte mismatch must reinstall, in either direction.
-  for (const key of Object.keys(parsedExisting)) {
-    if (key === 'env') continue;
-    if (!(key in parsedRendered)) return false;
-  }
+// Merge rendered settings.json with the user's existing file per the ownership model above.
+// Returns the merged JSON as a string, or the rendered content unchanged when either side is
+// unparseable (the caller still takes a timestamped backup before writing).
+export function mergeSettingsJson(existingContent, renderedContent) {
+  const existing = parseSettingsJson(existingContent);
+  const rendered = parseSettingsJson(renderedContent);
+  if (!existing || !rendered) return renderedContent;
+  return `${JSON.stringify(mergeSettingsObjects(existing, rendered), null, 2)}\n`;
+}
 
-  const templateEnv = parsedRendered.env && typeof parsedRendered.env === 'object' && !Array.isArray(parsedRendered.env)
-    ? parsedRendered.env
-    : {};
-  const fileEnv = parsedExisting.env && typeof parsedExisting.env === 'object' && !Array.isArray(parsedExisting.env)
-    ? parsedExisting.env
-    : {};
+function withoutGatewayEnv(settings) {
+  if (!isPlainObject(settings.env)) return settings;
+  const env = { ...settings.env };
+  for (const key of GATEWAY_RESILIENCE_KEYS) delete env[key];
+  return { ...settings, env };
+}
 
-  // Only enforce template env keys that are NOT UKit-managed. UKit-managed keys
-  // (CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK, CLAUDE_STREAM_IDLE_TIMEOUT_MS) are owned by
-  // applyGatewayResilienceEnv — it adds them post-apply and preserves user overrides.
-  for (const key of Object.keys(templateEnv)) {
-    if (GATEWAY_RESILIENCE_KEYS.has(key)) continue;
-    if (JSON.stringify(fileEnv[key]) !== JSON.stringify(templateEnv[key])) {
-      return false;
-    }
-  }
+function settingsJsonIgnoresGatewayEnvDiff(existingContent, renderedContent) {
+  const existing = parseSettingsJson(existingContent);
+  const rendered = parseSettingsJson(renderedContent);
+  if (!existing || !rendered) return false;
+  const merged = mergeSettingsObjects(existing, rendered);
+  return JSON.stringify(canonicalize(withoutGatewayEnv(merged)))
+    === JSON.stringify(canonicalize(withoutGatewayEnv(existing)));
+}
 
-  // Reverse direction for env: an env key in the file that the template does NOT ship
-  // (and that is not UKit-managed) is also drift — a removed template env key, or a
-  // user-added env key, must reinstall. UKit-managed gateway keys remain carved out
-  // because applyGatewayResilienceEnv owns them post-apply.
-  for (const key of Object.keys(fileEnv)) {
-    if (GATEWAY_RESILIENCE_KEYS.has(key)) continue;
-    if (!(key in templateEnv)) return false;
+// Key-order-insensitive structure for comparison (arrays keep order).
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (isPlainObject(value)) {
+    return Object.fromEntries(Object.keys(value).sort().map((k) => [k, canonicalize(value[k])]));
   }
-
-  return true;
+  return value;
 }
 
 function resolveFileAction(entry, existingContent) {
@@ -205,6 +197,12 @@ function resolveFileAction(entry, existingContent) {
     const merged = mergeSettingsJson(existingContent, entry.renderedContent);
     action = settingsJsonIgnoresGatewayEnvDiff(existingContent, entry.renderedContent) ? 'unchanged' : 'update';
     return { ...entry, renderedContent: merged, exists, action, existingContent };
+  } else if (entry.id === 'runtime-config' && typeof existingContent === 'string' && typeof entry.renderedContent === 'string') {
+    // U2: .ukit/storage/config.json is user-owned state seeded from the template — merge
+    // by ownership instead of overwriting (see runtimeConfigMerge.js).
+    const merged = mergeRuntimeConfigText(existingContent, entry.renderedContent);
+    action = merged.changed ? 'update' : 'unchanged';
+    return { ...entry, renderedContent: merged.text, migrationReport: merged.report, exists, action, existingContent };
   } else if (existingContent === entry.renderedContent) {
     action = 'unchanged';
   } else if (entry.mergeStrategy === 'skip') {

package/src/core/observability/emit/sessionBoot.js

@@ -334,6 +334,15 @@ function outcomeCost(value) {
   };
 }
 
+// A3 (C100 O8): agent/model/provider linkage. Nullable and additive: a value the hook payload
+// or emitter did not supply stays null (UNKNOWN) — never a guess, never 0, never inferred from a model name.
+function linkageField(...candidates) {
+  for (const value of candidates) {
+    if (typeof value === 'string' && value.trim().length > 0) return value.trim().slice(0, 96);
+  }
+  return null;
+}
+
 /**
  * buildOutcomeObservedRecord({ outcome, projectRoot, payload, sessionId,
  * engine, env }) → semantic-record candidate for `outcome.observed`.
@@ -375,6 +384,11 @@ export function buildOutcomeObservedRecord({
     evidenceIds: outcomeStringList(safe.evidenceIds, 32),
     cost: outcomeCost(safe.cost),
     reviewActions: outcomeStringList(safe.reviewActions, 32),
+    agentId: linkageField(safe.agentId, payload?.agent_id),
+    parentAgentId: linkageField(safe.parentAgentId, payload?.parent_agent_id),
+    agentType: linkageField(safe.agentType, payload?.agent_type),
+    model: linkageField(safe.model, payload?.model),
+    provider: linkageField(safe.provider),
     enforcement: OUTCOME_ENFORCEMENTS.has(safe.enforcement)
       ? safe.enforcement
       : deriveEnforcement({ engine: engineName, env }),

package/src/core/runtimeConfigMerge.js

@@ -0,0 +1,125 @@
+import { buildDefaultRuntimeConfig, validateRuntimeConfig } from './runtimeConfig.js';
+
+// U2: ownership-based migration for `.ukit/storage/config.json`.
+//
+//   Template-owned (always the new release's value): `version`, `agent`, `_help`
+//     (documentation block) and every key listed in REMOVED_KEYS (dropped on migration).
+//   Security-reset (never carried over silently, reported instead): SECURITY_RESET_KEYS —
+//     an unsafe opt-in must be re-confirmed after an upgrade; the new default applies.
+//   User-owned (existing value wins): every other key the user already has — model routing
+//     (`modelRoles`, `router`, `subagents.*`), `autonomy`, `orchestration.permissionMode`,
+//     thresholds, arrays, and unknown keys (kept verbatim).
+//   Template-filled: keys the user does not have take the new default (so new features get
+//     their defaults, and a partial/old config is upgraded without losing user values).
+//
+// If the merged result fails validateRuntimeConfig, the merge refuses to guess: the existing
+// file is left untouched and the report says why. An unparseable (corrupt) existing file is
+// replaced by the rendered template (applyPlan takes a timestamped backup first).
+
+export const TEMPLATE_OWNED_KEYS = Object.freeze(['version', 'agent', '_help']);
+export const SECURITY_RESET_KEYS = Object.freeze(['orchestration.allowUnsafeEval']);
+export const REMOVED_KEYS = Object.freeze([]);
+
+const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+function getPath(obj, dotted) {
+  return dotted.split('.').reduce((acc, k) => (isPlainObject(acc) ? acc[k] : undefined), obj);
+}
+
+function deletePath(obj, dotted) {
+  const parts = dotted.split('.');
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    if (!isPlainObject(cur[parts[i]])) return;
+    cur = cur[parts[i]];
+  }
+  delete cur[parts[parts.length - 1]];
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (isPlainObject(value)) {
+    return Object.fromEntries(Object.keys(value).sort().map((k) => [k, canonicalize(value[k])]));
+  }
+  return value;
+}
+
+function mergeOwned(template, existing) {
+  const merged = {};
+  for (const key of Object.keys(template)) {
+    if (!BLOCKED_KEYS.has(key)) merged[key] = template[key];
+  }
+  for (const [key, userValue] of Object.entries(existing)) {
+    if (BLOCKED_KEYS.has(key)) continue;
+    if (!(key in template)) {
+      merged[key] = userValue;
+    } else if (isPlainObject(template[key]) && isPlainObject(userValue)) {
+      merged[key] = mergeOwned(template[key], userValue);
+    } else {
+      merged[key] = userValue;
+    }
+  }
+  return merged;
+}
+
+export function mergeRuntimeConfigText(existingText, renderedText) {
+  const report = { merged: false, fallback: null, resetSecurityKeys: [], removedKeys: [] };
+  let existing;
+  let rendered;
+  try {
+    rendered = JSON.parse(renderedText);
+  } catch {
+    report.fallback = 'rendered-template-unparseable';
+    return { text: renderedText, changed: renderedText !== existingText, report };
+  }
+  try {
+    existing = JSON.parse(existingText);
+  } catch {
+    report.fallback = 'existing-unparseable';
+    return { text: renderedText, changed: true, report };
+  }
+  if (!isPlainObject(existing) || !isPlainObject(rendered)) {
+    report.fallback = 'not-an-object';
+    return { text: renderedText, changed: true, report };
+  }
+
+  const merged = mergeOwned(rendered, existing);
+  for (const key of TEMPLATE_OWNED_KEYS) {
+    if (key in rendered) merged[key] = rendered[key];
+    else delete merged[key];
+  }
+  for (const dotted of REMOVED_KEYS) {
+    if (getPath(existing, dotted) !== undefined) report.removedKeys.push(dotted);
+    deletePath(merged, dotted);
+  }
+  for (const dotted of SECURITY_RESET_KEYS) {
+    const before = getPath(merged, dotted);
+    const fallback = getPath(rendered, dotted);
+    if (before !== fallback) {
+      report.resetSecurityKeys.push(dotted);
+      const parts = dotted.split('.');
+      let cur = merged;
+      for (let i = 0; i < parts.length - 1; i += 1) {
+        if (!isPlainObject(cur[parts[i]])) cur[parts[i]] = {};
+        cur = cur[parts[i]];
+      }
+      if (fallback === undefined) delete cur[parts[parts.length - 1]];
+      else cur[parts[parts.length - 1]] = fallback;
+    }
+  }
+
+  // The runtime loader validates the file layered over built-in defaults, so do the same.
+  const validation = validateRuntimeConfig(mergeOwned(buildDefaultRuntimeConfig(), merged));
+  if (!validation.valid) {
+    // Never discard the user's customisations on a guess: leave the file untouched and
+    // report why. `ukit doctor` surfaces the invalid value; the user's file stays intact.
+    report.fallback = `merged-config-invalid (file left untouched): ${validation.errors.slice(0, 3).join('; ')}`;
+    return { text: existingText, changed: false, report };
+  }
+
+  report.merged = true;
+  const changed = JSON.stringify(canonicalize(merged)) !== JSON.stringify(canonicalize(existing));
+  return { text: `${JSON.stringify(merged, null, 2)}\n`, changed, report };
+}

package/src/core/updateSafety.js

@@ -0,0 +1,174 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawnSync as defaultSpawnSync } from 'node:child_process';
+import { readInstallMetadata } from './metadata.js';
+import { writeFileAtomic } from './fileOps.js';
+
+// F5: safety net around `ukit update`.
+//
+//   preflight  -> before ANY change: npm answers, project metadata readable and project
+//                 writable. A failed preflight aborts with nothing modified.
+//   snapshot   -> copies every UKit-managed regular file (install.json ledger + the known
+//                 user-edited configs) plus a sha256 manifest, BEFORE `npm install -g`.
+//   restore    -> if the project refresh fails, puts the project back and VERIFIES hashes.
+//
+// Honest scope: the snapshot covers PROJECT files only. The global npm package is never
+// rolled back automatically — after a failed refresh the global CLI stays on the new
+// version while the project is back on the old files. The report says so and prints the
+// exact npm command to pin the previous version; it never claims a full rollback.
+
+const SNAPSHOT_REL_DIR = path.join('.claude', 'ukit', '.ukit', 'update-snapshots');
+const INSTALL_META_REL = path.join('.claude', 'ukit', '.ukit', 'install.json');
+const EXTRA_SNAPSHOT_PATHS = [
+  '.claude/settings.json',
+  '.ukit/storage/config.json',
+  '.omp/config.yml',
+  '.gitignore',
+  'CLAUDE.md',
+  'AGENTS.md',
+];
+export const SNAPSHOT_KEEP = 3;
+
+const toPosix = (p) => p.replace(/\\/g, '/');
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+
+function insideProject(projectRoot, rel) {
+  const abs = path.resolve(projectRoot, rel);
+  const relBack = path.relative(path.resolve(projectRoot), abs);
+  return relBack !== '' && !relBack.startsWith('..') && !path.isAbsolute(relBack) ? abs : null;
+}
+
+export async function preflightUpdate({ projectRoot, spawnSync = defaultSpawnSync, checkNpm = true } = {}) {
+  const problems = [];
+  if (checkNpm) {
+    const r = spawnSync('npm', ['--version'], { encoding: 'utf8', timeout: 15_000, killSignal: 'SIGKILL' });
+    if (r.error || r.status !== 0) problems.push(`npm is not runnable (${r.error?.message ?? `exit ${r.status}`})`);
+  }
+  try {
+    await readInstallMetadata(path.join(projectRoot, INSTALL_META_REL));
+  } catch (error) {
+    problems.push(`install metadata unreadable: ${error.message}`);
+  }
+  try {
+    await fs.access(projectRoot, fs.constants.W_OK);
+  } catch {
+    problems.push(`project directory is not writable: ${projectRoot}`);
+  }
+  return { ok: problems.length === 0, problems };
+}
+
+async function listManagedFiles(projectRoot) {
+  const rels = new Set(EXTRA_SNAPSHOT_PATHS.map(toPosix));
+  rels.add(toPosix(INSTALL_META_REL));
+  try {
+    const meta = await readInstallMetadata(path.join(projectRoot, INSTALL_META_REL));
+    for (const entry of Array.isArray(meta?.files) ? meta.files : []) {
+      const p = typeof entry === 'string' ? entry : entry?.p;
+      if (typeof p === 'string' && p.trim()) rels.add(toPosix(p.trim()));
+    }
+  } catch {
+    // preflight already reported unreadable metadata
+  }
+  return [...rels].filter((rel) => !rel.startsWith(`${toPosix(SNAPSHOT_REL_DIR)}/`));
+}
+
+export async function createUpdateSnapshot({ projectRoot, previousGlobalVersion = null, now = Date.now() }) {
+  const dir = path.join(projectRoot, SNAPSHOT_REL_DIR, String(now));
+  const filesDir = path.join(dir, 'files');
+  await fs.mkdir(filesDir, { recursive: true });
+  const files = [];
+  for (const rel of await listManagedFiles(projectRoot)) {
+    const abs = insideProject(projectRoot, rel);
+    if (!abs) continue;
+    let stat;
+    try {
+      stat = await fs.lstat(abs);
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        files.push({ rel, existed: false });
+        continue;
+      }
+      throw new Error(`snapshot failed: cannot stat ${rel}: ${error.message}`);
+    }
+    if (!stat.isFile()) continue; // links and directories are re-created by install
+    const content = await fs.readFile(abs);
+    const dest = path.join(filesDir, rel);
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    await fs.writeFile(dest, content);
+    files.push({ rel, existed: true, sha256: sha256(content), mode: stat.mode & 0o777 });
+  }
+  const manifest = { version: 1, createdAt: new Date(now).toISOString(), previousGlobalVersion, files };
+  await fs.writeFile(path.join(dir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+  await pruneSnapshots(path.join(projectRoot, SNAPSHOT_REL_DIR));
+  return { dir, manifest };
+}
+
+async function pruneSnapshots(root) {
+  try {
+    const names = (await fs.readdir(root)).filter((n) => /^\d+$/.test(n)).sort((a, b) => Number(b) - Number(a));
+    for (const name of names.slice(SNAPSHOT_KEEP)) await fs.rm(path.join(root, name), { recursive: true, force: true });
+  } catch {
+    // advisory
+  }
+}
+
+// Restore the project to the snapshot and verify every file by hash. Files the failed
+// install created (tracked in the NEW ledger but absent from the snapshot ledger) are removed.
+export async function restoreUpdateSnapshot({ projectRoot, snapshotDir }) {
+  const manifest = JSON.parse(await fs.readFile(path.join(snapshotDir, 'manifest.json'), 'utf8'));
+  const failures = [];
+  let restored = 0;
+
+  for (const file of manifest.files) {
+    const abs = insideProject(projectRoot, file.rel);
+    if (!abs) continue;
+    try {
+      if (file.existed) {
+        const content = await fs.readFile(path.join(snapshotDir, 'files', file.rel));
+        await writeFileAtomic(abs, content);
+        if (typeof file.mode === 'number') await fs.chmod(abs, file.mode).catch(() => {});
+        restored += 1;
+      } else {
+        await fs.rm(abs, { force: true }); // created by the failed refresh
+      }
+    } catch (error) {
+      failures.push(`${file.rel}: ${error.message}`);
+    }
+  }
+
+  // Files tracked by the failed install but unknown to the snapshot: created by it.
+  const known = new Set(manifest.files.map((f) => f.rel));
+  try {
+    const meta = await readInstallMetadata(path.join(projectRoot, INSTALL_META_REL));
+    for (const entry of Array.isArray(meta?.files) ? meta.files : []) {
+      const rel = toPosix(typeof entry === 'string' ? entry : entry?.p ?? '');
+      if (!rel || known.has(rel)) continue;
+      const abs = insideProject(projectRoot, rel);
+      if (!abs) continue;
+      const stat = await fs.lstat(abs).catch(() => null);
+      if (stat?.isFile()) await fs.rm(abs, { force: true });
+    }
+  } catch {
+    // ledger itself was restored above; nothing more to reconcile
+  }
+
+  const mismatches = [];
+  for (const file of manifest.files) {
+    const abs = insideProject(projectRoot, file.rel);
+    if (!abs) continue;
+    if (file.existed) {
+      const now = await fs.readFile(abs).catch(() => null);
+      if (!now || sha256(now) !== file.sha256) mismatches.push(file.rel);
+    } else if (await fs.lstat(abs).then(() => true, () => false)) {
+      mismatches.push(file.rel);
+    }
+  }
+  return {
+    ok: failures.length === 0 && mismatches.length === 0,
+    restored,
+    failures,
+    mismatches,
+    previousGlobalVersion: manifest.previousGlobalVersion ?? null,
+  };
+}