codex-copilot-dx 0.6.15 → 0.6.18

package/src/pm-studio-setup.mjs

@@ -12,7 +12,10 @@ import {
   PM_STUDIO_2_9_10_RECIPE,
   PM_STUDIO_RECIPES,
   createCompatiblePmStudioRecipe,
+  createCompatiblePmStudioRecipeFromFile,
+  inspectAsarFile,
   inspectElectronAsarIntegritySlots,
+  inspectElectronAsarIntegrityFile,
   inspectAsarBuffer,
   patchAsarBuffer,
   sha256Hex,
@@ -57,10 +60,10 @@ function runChecked(processRunner, command, args, label) {
   return result;
 }
 
-function hashRegularFile(filePath, expected) {
+function hashRegularFile(filePath, expected, readBuffer) {
   const hash = createHash("sha256");
   const file = fs.openSync(filePath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
-  const buffer = Buffer.allocUnsafe(1024 * 1024);
+  const buffer = readBuffer || Buffer.allocUnsafe(1024 * 1024);
   try {
     const before = fs.fstatSync(file, { bigint: true });
     if (before.dev !== BigInt(expected.dev)
@@ -136,6 +139,7 @@ function parseXattrHex(output, root, ignoredXattrs) {
 export function inspectBundleContent(appPath, {
   xattrOutput = "",
   ignoredXattrs = [],
+  readBuffer,
 } = {}) {
   const root = path.resolve(appPath);
   const rootStat = fs.lstatSync(root);
@@ -186,7 +190,7 @@ export function inspectBundleContent(appPath, {
         }
         regularFileCount += 1;
         regularBytes += stat.size;
-        records.push(["file", relative, mode, stat.size, hashRegularFile(fullPath, stat)]);
+        records.push(["file", relative, mode, stat.size, hashRegularFile(fullPath, stat, readBuffer)]);
       } else {
         throw setupError("PM_STUDIO_BUNDLE_ENTRY_INVALID", `PM Studio contains an unsupported entry: ${relative}`);
       }
@@ -208,12 +212,13 @@ export function inspectBundleContent(appPath, {
   };
 }
 
-function defaultInspectBundleContent({ appPath, recipe, processRunner }) {
+function defaultInspectBundleContent({ appPath, recipe, processRunner, readBuffer }) {
   const xattrs = runChecked(processRunner, "/usr/bin/xattr", ["-r", "-s", "-x", "-l", appPath],
     "Reading PM Studio extended attributes");
   return inspectBundleContent(appPath, {
     xattrOutput: xattrs.stdout,
     ignoredXattrs: recipe.sourceBundleContent?.ignoredXattrs || [],
+    readBuffer,
   });
 }
 
@@ -316,6 +321,55 @@ function defaultInspectExecutableIntegrity({ appPath, infoPlistPath, recipe, pro
   };
 }
 
+function statusInspectExecutableIntegrity({ appPath, infoPlistPath, recipe, processRunner, evidenceCache }) {
+  const executableName = plistRead(processRunner, infoPlistPath, "CFBundleExecutable");
+  if (!executableName || path.basename(executableName) !== executableName) {
+    throw setupError("PM_STUDIO_EXECUTABLE_INVALID", "PM Studio CFBundleExecutable is invalid");
+  }
+  const executablePath = path.join(appPath, "Contents", "MacOS", executableName);
+  const frameworkPath = path.join(appPath, recipe.electronFrameworkPath);
+  const executable = inspectElectronAsarIntegrityFile(executablePath, { cache: evidenceCache });
+  const framework = inspectElectronAsarIntegrityFile(frameworkPath, { cache: evidenceCache });
+  return {
+    executableName,
+    executablePath,
+    executableSha256: executable.sha256,
+    frameworkPath,
+    frameworkSha256: framework.sha256,
+    embeddedIntegrity: {
+      state: executable.integrity.slots.length === 0 && framework.integrity.slots.length === 0 ? "absent" : "present",
+      supported: executable.integrity.slots.length === 0 && framework.integrity.slots.length === 0,
+      executable: executable.integrity,
+      framework: framework.integrity,
+    },
+    matchesRecipeName: executableName === recipe.executable,
+  };
+}
+
+export function createPmStudioStatusOperationOverrides() {
+  const evidenceCache = new Map();
+  const bundleReadBuffer = Buffer.allocUnsafe(1024 * 1024);
+  return {
+    inspectExecutableIntegrity: (args) => statusInspectExecutableIntegrity({
+      ...args,
+      evidenceCache,
+    }),
+    inspectAsarFile: ({ asarPath, recipe }) => inspectAsarFile(asarPath, recipe, {
+      cache: evidenceCache,
+      releaseTargets: true,
+    }),
+    createCompatibleRecipeFromFile: ({ asarPath, options }) => createCompatiblePmStudioRecipeFromFile(
+      asarPath,
+      options,
+      { cache: evidenceCache, releaseTargets: true },
+    ),
+    inspectBundleContent: (args) => defaultInspectBundleContent({
+      ...args,
+      readBuffer: bundleReadBuffer,
+    }),
+  };
+}
+
 function defaultSignApp({ appPath, source, processRunner }) {
   const preserve = [];
   if (source?.codeSign?.displayValid === true) {
@@ -411,6 +465,17 @@ function defaultAssertPermissions({ appPath, backupRoot }) {
   }
 }
 
+function defaultAssertRestorePermissions({ appPath, backupAppPath }) {
+  try {
+    fs.accessSync(appPath, fs.constants.R_OK | fs.constants.X_OK);
+    fs.accessSync(path.dirname(appPath), fs.constants.W_OK | fs.constants.X_OK);
+    fs.accessSync(backupAppPath, fs.constants.R_OK | fs.constants.X_OK);
+  } catch {
+    throw setupError("PM_STUDIO_PERMISSION_DENIED",
+      "PM Studio or its verified backup is not accessible to the current user; restore will not use sudo");
+  }
+}
+
 export function createPmStudioSetupOperations(overrides = {}) {
   const processRunner = overrides.processRunner || defaultProcessRunner;
   return {
@@ -432,6 +497,7 @@ export function createPmStudioSetupOperations(overrides = {}) {
     availableBytes: defaultAvailableBytes,
     volumeId: defaultVolumeId,
     assertPermissions: defaultAssertPermissions,
+    assertRestorePermissions: defaultAssertRestorePermissions,
     readClaudeCredentials: ({ home }) => readAuthProfileCredentials(AUTH_PROFILE_CLAUDE, { home }),
     now: () => new Date(),
     uuid: () => randomUUID(),
@@ -470,7 +536,9 @@ export function inspectPmStudioApp({
   const paths = appPaths(appPath, recipe);
   const issues = [];
   const metadata = operations.readBundleMetadata({ ...paths, recipe, processRunner: operations.processRunner });
-  const asar = inspectAsarBuffer(fs.readFileSync(paths.asarPath), recipe);
+  const asar = operations.inspectAsarFile
+    ? operations.inspectAsarFile({ ...paths, recipe, processRunner: operations.processRunner })
+    : inspectAsarBuffer(fs.readFileSync(paths.asarPath), recipe);
   const plistIntegrity = operations.readAsarIntegrity({ ...paths, recipe, processRunner: operations.processRunner });
   const executableIntegrity = operations.inspectExecutableIntegrity({
     ...paths, recipe, processRunner: operations.processRunner,
@@ -679,11 +747,14 @@ function compatibleSourceStructure({ appPath, metadata, operations }) {
     throw setupError("PM_STUDIO_ASAR_INCOMPATIBLE",
       "PM Studio compatible-version discovery found an unsupported executable or embedded ASAR integrity policy");
   }
-  const compatibleRecipe = createCompatiblePmStudioRecipe(fs.readFileSync(paths.asarPath), {
+  const recipeOptions = {
     ...compatibleStaticOptions(metadata, executableIntegrity.executableName),
     sourceExecutableSha256: executableIntegrity.executableSha256,
     sourceElectronFrameworkSha256: executableIntegrity.frameworkSha256,
-  });
+  };
+  const compatibleRecipe = operations.createCompatibleRecipeFromFile
+    ? operations.createCompatibleRecipeFromFile({ asarPath: paths.asarPath, options: recipeOptions })
+    : createCompatiblePmStudioRecipe(fs.readFileSync(paths.asarPath), recipeOptions);
   const plistIntegrity = operations.readAsarIntegrity({
     ...paths,
     recipe: compatibleRecipe,
@@ -737,11 +808,14 @@ function compatibleRecipeFromManifest({ backupDir, manifest, metadata, operation
     recipe: PM_STUDIO_2_9_10_RECIPE,
     processRunner: operations.processRunner,
   });
-  const compatibleRecipe = createCompatiblePmStudioRecipe(fs.readFileSync(sourceAsarPath), {
+  const recipeOptions = {
     ...compatibleStaticOptions(metadata, executableIntegrity.executableName),
     sourceExecutableSha256: manifest?.source?.binaries?.main_executable_sha256,
     sourceElectronFrameworkSha256: manifest?.source?.binaries?.electron_framework_sha256,
-  });
+  };
+  const compatibleRecipe = operations.createCompatibleRecipeFromFile
+    ? operations.createCompatibleRecipeFromFile({ asarPath: sourceAsarPath, options: recipeOptions })
+    : createCompatiblePmStudioRecipe(fs.readFileSync(sourceAsarPath), recipeOptions);
   const recipe = Object.freeze({
     ...compatibleRecipe,
     sourceBundleContent: frozenBundleContent(manifest.source.bundle_content),
@@ -766,7 +840,8 @@ function compatibleRecipeFromManifest({ backupDir, manifest, metadata, operation
 
 function compatibleRecipeFromBackup({ appPath, backupRoot, metadata, operations }) {
   if (!fs.existsSync(backupRoot)) return null;
-  const installedAsar = fs.readFileSync(path.join(appPath, PM_STUDIO_2_9_10_RECIPE.asarPath));
+  const installedAsarPath = path.join(appPath, PM_STUDIO_2_9_10_RECIPE.asarPath);
+  const installedAsar = operations.inspectAsarFile ? null : fs.readFileSync(installedAsarPath);
   let candidates = [];
   const invalidCandidates = [];
   for (const entry of fs.readdirSync(backupRoot, { withFileTypes: true })) {
@@ -788,7 +863,9 @@ function compatibleRecipeFromBackup({ appPath, backupRoot, metadata, operations
       continue;
     }
     if (!recipe) continue;
-    const asarState = inspectAsarBuffer(installedAsar, recipe).state;
+    const asarState = operations.inspectAsarFile
+      ? operations.inspectAsarFile({ asarPath: installedAsarPath, recipe }).state
+      : inspectAsarBuffer(installedAsar, recipe).state;
     if (asarState === "drift") continue;
     candidates.push({ recipe, manifest, asarState });
   }
@@ -1188,6 +1265,74 @@ function assertSpace({ appPath, backupRoot, backupExists, operations }) {
   }
 }
 
+function assertRestoreSpace({ appPath, backupAppPath, operations }) {
+  const bundleBytes = operations.bundleSize(backupAppPath);
+  if (!Number.isFinite(bundleBytes) || bundleBytes <= 0) {
+    throw setupError("PM_STUDIO_SIZE_INVALID", "Could not determine verified PM Studio backup size");
+  }
+  if (operations.availableBytes(path.dirname(appPath)) < bundleBytes + MIN_FREE_MARGIN_BYTES) {
+    throw setupError("PM_STUDIO_SPACE_INSUFFICIENT", "Not enough free space for PM Studio restore staging");
+  }
+}
+
+function codeSignFingerprint(codeSign) {
+  return {
+    valid: codeSign?.valid === true,
+    verifyValid: codeSign?.verifyValid === true,
+    displayValid: codeSign?.displayValid === true,
+    entitlementsState: codeSign?.entitlementsState || "",
+    adHoc: codeSign?.adHoc === true,
+    identifier: codeSign?.identifier || "",
+    teamIdentifier: codeSign?.teamIdentifier || "",
+    flags: codeSign?.flags || "",
+    runtimeVersion: codeSign?.runtimeVersion || "",
+    cdHashFull: codeSign?.cdHashFull || "",
+    notarizationTicket: codeSign?.notarizationTicket || "",
+    entitlementsSha256: codeSign?.entitlementsSha256 || "",
+  };
+}
+
+function restoreStateFingerprint(inspection, bundleContent) {
+  return JSON.stringify({
+    state: inspection.state,
+    metadata: inspection.metadata,
+    asar: {
+      state: inspection.asar?.state,
+      asarSha256: inspection.asar?.asarSha256,
+      headerSha256: inspection.asar?.headerSha256,
+    },
+    plistIntegrity: inspection.plistIntegrity,
+    executableIntegrity: {
+      executableName: inspection.executableIntegrity?.executableName,
+      executableSha256: inspection.executableIntegrity?.executableSha256,
+      frameworkSha256: inspection.executableIntegrity?.frameworkSha256,
+      embeddedIntegrity: inspection.executableIntegrity?.embeddedIntegrity,
+      matchesRecipeName: inspection.executableIntegrity?.matchesRecipeName,
+    },
+    codeSign: codeSignFingerprint(inspection.codeSign),
+    bundleContent,
+  });
+}
+
+function inspectRestoreState({ appPath, recipe, operations }) {
+  const inspection = inspectPmStudioApp({ appPath, recipe, operations });
+  const bundleContent = inspection.bundleContent || operations.inspectBundleContent({
+    ...appPaths(appPath, recipe),
+    recipe,
+    processRunner: operations.processRunner,
+  });
+  return {
+    inspection,
+    fingerprint: restoreStateFingerprint(inspection, bundleContent),
+  };
+}
+
+function assertRestoreStateMatches(actual, expected, code, message) {
+  if (actual.fingerprint !== expected.fingerprint) {
+    throw setupError(code, message, actual.inspection.issues);
+  }
+}
+
 function replaceVerifiedStage({ appPath, stagePath, operations }) {
   try {
     operations.replaceApp({ appPath, stagePath, processRunner: operations.processRunner });
@@ -1376,9 +1521,8 @@ export async function runPmStudioSetup({
     emit(`[OK] Verified backup: ${backup.backupAppPath}${backup.reused ? " (reused)" : ""}`);
     emit(`[OK] Backup manifest: ${backup.manifestPath}`);
     emit("[INFO] The verified staging bundle was installed with Foundation's atomic item replacement.");
-    emit(`[INFO] Restore step 1/3: quit PM Studio and its updater.`);
-    emit(`[INFO] Restore step 2/3: confirm the installed Info.plist still reports version/build ${recipe.version}/${recipe.build}; never restore this backup over another version.`);
-    emit(`[INFO] Restore step 3/3: move ${appPath} aside, copy ${backup.backupAppPath} to that exact path, and verify its signature before launch.`);
+    emit(`[INFO] To restore, quit PM Studio and its updater, then run ${commandName} pms restore.`);
+    emit("[INFO] Restore uses exact source-content verification; the original source signature is inspected and reported but is not an admission gate.");
     emit(`[INFO] Start ${commandName} before using Claude in PM Studio; GPT remains on PM Studio's native GitHub Copilot path.`);
     return {
       status: migratingExistingPatch ? "migrated" : "patched",
@@ -1394,3 +1538,164 @@ export async function runPmStudioSetup({
   }
   });
 }
+
+export async function runPmStudioRestore({
+  commandName = "ccdx",
+  appPath = DEFAULT_PM_STUDIO_APP_PATH,
+  home = os.homedir(),
+  backupRoot = pmStudioBackupRoot(home),
+  recipes = PM_STUDIO_RECIPES,
+  operations: operationOverrides = {},
+  logger = (line) => console.log(line),
+} = {}) {
+  const operations = createPmStudioSetupOperations(operationOverrides);
+  return operations.withSetupLock({ appPath }, async () => {
+    const messages = [];
+    const emit = (message) => {
+      messages.push(message);
+      logger(message);
+    };
+
+    assertInstalledAppPath(appPath);
+    assertNoBlockingProcesses(operations, appPath);
+    const metadata = operations.readBundleMetadata({
+      appPath,
+      infoPlistPath: path.join(appPath, "Contents/Info.plist"),
+      processRunner: operations.processRunner,
+    });
+    const recipe = resolvePmStudioCompatibleRecipe({
+      appPath,
+      home,
+      backupRoot,
+      metadata,
+      recipes,
+      operations,
+    });
+    const source = inspectRestoreState({ appPath, recipe, operations });
+    if (source.inspection.state === "clean") {
+      emit(`[OK] PM Studio ${recipe.version} build ${recipe.build} is already the exact clean local bundle; no files were changed.`);
+      return {
+        status: "already_clean",
+        changed: false,
+        recipe: recipe.id,
+        inspection: source.inspection,
+        messages,
+      };
+    }
+    if (!["patched", "predecessor", "legacy"].includes(source.inspection.state)) {
+      throw setupError("PM_STUDIO_BUNDLE_DRIFT",
+        `PM Studio ${recipe.version} build ${recipe.build} does not match a recorded patch state; no files were changed`,
+        source.inspection.issues);
+    }
+
+    const manifestPath = pmStudioPatchManifestPath({ home, backupRoot, recipe });
+    const backupDir = path.dirname(manifestPath);
+    const backup = validateBackup({ backupDir, recipe, operations });
+    assertPatchedBinaryRecord({
+      inspection: source.inspection,
+      manifestPath: backup.manifestPath,
+      recipe,
+      recordState: source.inspection.state,
+    });
+    operations.assertRestorePermissions({
+      appPath,
+      backupAppPath: backup.backupAppPath,
+      processRunner: operations.processRunner,
+    });
+    assertRestoreSpace({ appPath, backupAppPath: backup.backupAppPath, operations });
+    const manifestSnapshot = fs.readFileSync(backup.manifestPath);
+    const backupSource = inspectRestoreState({ appPath: backup.backupAppPath, recipe, operations });
+    if (backupSource.inspection.state !== "clean") {
+      throw setupError("PM_STUDIO_BACKUP_INVALID", "Verified PM Studio backup is not an exact clean bundle",
+        backupSource.inspection.issues);
+    }
+
+    const stagePath = path.join(path.dirname(appPath),
+      `.${path.basename(appPath)}.ccdx-restore-stage-${operations.uuid()}`);
+    let preserveStage = false;
+    try {
+      operations.copyBundle({
+        source: backup.backupAppPath,
+        destination: stagePath,
+        processRunner: operations.processRunner,
+      });
+      if (!fs.readFileSync(backup.manifestPath).equals(manifestSnapshot)) {
+        throw setupError("PM_STUDIO_BACKUP_CHANGED",
+          "PM Studio backup manifest changed during restore; the verified staging bundle was not installed");
+      }
+      const currentBackup = validateBackup({ backupDir, recipe, operations });
+      const unchangedBackup = inspectRestoreState({
+        appPath: currentBackup.backupAppPath,
+        recipe,
+        operations,
+      });
+      assertRestoreStateMatches(unchangedBackup, backupSource, "PM_STUDIO_BACKUP_CHANGED",
+        "PM Studio backup changed during restore; the verified staging bundle was not installed");
+      const unchangedSource = inspectRestoreState({ appPath, recipe, operations });
+      assertRestoreStateMatches(unchangedSource, source, "PM_STUDIO_SOURCE_CHANGED",
+        "PM Studio changed during restore; the verified staging bundle was not installed");
+      assertPatchedBinaryRecord({
+        inspection: unchangedSource.inspection,
+        manifestPath: backup.manifestPath,
+        recipe,
+        recordState: source.inspection.state,
+      });
+
+      const staged = inspectRestoreState({ appPath: stagePath, recipe, operations });
+      if (staged.inspection.state !== "clean") {
+        throw setupError("PM_STUDIO_RESTORE_STAGE_INVALID",
+          "PM Studio restore staging copy is not an exact clean bundle", staged.inspection.issues);
+      }
+      assertRestoreStateMatches(staged, backupSource, "PM_STUDIO_RESTORE_STAGE_INVALID",
+        "PM Studio restore staging copy differs from the verified clean backup");
+      assertNoBlockingProcesses(operations, appPath);
+
+      const replacementError = replaceVerifiedStage({ appPath, stagePath, operations });
+      let installed;
+      try {
+        installed = inspectRestoreState({ appPath, recipe, operations });
+      } catch {
+        preserveStage = fs.existsSync(stagePath);
+        throw setupError("PM_STUDIO_RESTORE_STATE_UNKNOWN",
+          `PM Studio restore final state could not be verified. Do not launch it. ${recoveryMessage(backup)}${preserveStage ? ` Verified staging retained: ${stagePath}.` : ""}`);
+      }
+      if (installed.inspection.state !== "clean" || installed.fingerprint !== staged.fingerprint) {
+        const originalRetained = installed.fingerprint === source.fingerprint;
+        preserveStage = !originalRetained && fs.existsSync(stagePath);
+        const code = originalRetained
+          ? "PM_STUDIO_RESTORE_REPLACE_FAILED"
+          : "PM_STUDIO_RESTORE_INSTALL_VERIFY_FAILED";
+        const stateMessage = originalRetained
+          ? `The installed PM Studio remains the verified ${source.inspection.state} bundle`
+          : "The installed PM Studio does not match the verified clean backup; do not launch it";
+        throw setupError(code,
+          `${stateMessage}. ${recoveryMessage(backup)}${preserveStage ? ` Verified staging retained: ${stagePath}.` : ""}`,
+          installed.inspection.issues);
+      }
+      if (replacementError) {
+        emit("[WARN] Atomic replacement reported an error after the exact clean bundle became installed; the final bundle was independently verified.");
+      }
+      emit(`[OK] Restored PM Studio ${recipe.version} build ${recipe.build} from the exact verified clean backup.`);
+      emit(`[OK] Verified backup retained: ${backup.backupAppPath}`);
+      emit(`[OK] Backup manifest retained: ${backup.manifestPath}`);
+      emit("[INFO] The verified clean staging bundle was installed with Foundation's atomic item replacement.");
+      if (installed.inspection.codeSign?.valid === true) {
+        emit("[OK] The restored source bundle's original signature verifies successfully.");
+      } else {
+        emit("[WARN] The restored bundle exactly matches its recorded local source, whose original signature does not currently verify; reinstall PM Studio if a vendor-valid signature is required.");
+      }
+      emit(`[INFO] Run ${commandName} pms setup to apply the split-origin patch again.`);
+      return {
+        status: "restored",
+        changed: true,
+        recipe: recipe.id,
+        backup,
+        inspection: installed.inspection,
+        replacementMode: "foundation-atomic-replace",
+        messages,
+      };
+    } finally {
+      if (!preserveStage && fs.existsSync(stagePath)) operations.removePath({ target: stagePath });
+    }
+  });
+}

package/src/pm-studio-status.mjs

@@ -8,6 +8,7 @@ import {
 import { PM_STUDIO_RECIPES } from "./pm-studio-asar.mjs";
 import {
   assertPatchedBinaryRecord,
+  createPmStudioStatusOperationOverrides,
   createPmStudioSetupOperations,
   DEFAULT_PM_STUDIO_APP_PATH,
   inspectPmStudioApp,
@@ -147,7 +148,10 @@ export async function inspectPmStudioStatus({
   readAdapterStatusFn = readAdapterStatus,
   probePmStudioRelayFn = probePmStudioRelay,
 } = {}) {
-  const operations = createPmStudioSetupOperations(operationOverrides);
+  const operations = createPmStudioSetupOperations({
+    ...createPmStudioStatusOperationOverrides(),
+    ...operationOverrides,
+  });
   let app;
   if (!existsSync(appPath)) {
     app = { state: "not_installed", metadata: null, issues: [] };

package/src/response-history.mjs

@@ -71,6 +71,7 @@ function jsonByteLength(value, seen = new Set()) {
 const histories = new Map();
 const childrenById = new Map();
 const treeLru = new Map();
+const pinnedTrees = new Map();
 const evictedIds = new Set();
 let totalBytes = 0;
 const HISTORY_RUNTIME_CONFIG = loadRuntimeConfig();
@@ -88,6 +89,21 @@ function touchTree(rootId) {
   treeLru.set(rootId, true);
 }
 
+function pinTree(rootId) {
+  if (!rootId) return;
+  pinnedTrees.set(rootId, (pinnedTrees.get(rootId) || 0) + 1);
+}
+
+function unpinTree(rootId) {
+  const count = pinnedTrees.get(rootId) || 0;
+  if (count <= 1) pinnedTrees.delete(rootId);
+  else pinnedTrees.set(rootId, count - 1);
+}
+
+function treeIsPinned(rootId) {
+  return (pinnedTrees.get(rootId) || 0) > 0;
+}
+
 function linkChild(parentId, id) {
   if (!parentId) return;
   let children = childrenById.get(parentId);
@@ -148,18 +164,50 @@ function assignSubtreeRoot(id, rootId) {
   }
 }
 
-function enforceLimits() {
-  while (histories.size > maxEntries || totalBytes > maxBytes) {
-    const oldestRootId = treeLru.keys().next().value;
-    if (!oldestRootId) break;
-    removeSubtree(oldestRootId);
+function subtreeUsage(rootId) {
+  const pending = [rootId];
+  const seen = new Set();
+  let bytes = 0;
+  let entries = 0;
+  while (pending.length) {
+    const id = pending.pop();
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const entry = histories.get(id);
+    if (entry) {
+      entries += 1;
+      bytes += entry.bytes;
+    }
+    const children = childrenById.get(id);
+    if (children) pending.push(...children);
+  }
+  return { bytes, entries };
+}
+
+function makeRoomFor({ additionalBytes, additionalEntries, protectedRoots }) {
+  let projectedBytes = totalBytes + additionalBytes;
+  let projectedEntries = histories.size + additionalEntries;
+  if (projectedEntries <= maxEntries && projectedBytes <= maxBytes) return true;
+
+  const candidates = [];
+  for (const rootId of treeLru.keys()) {
+    if (protectedRoots.has(rootId) || treeIsPinned(rootId)) continue;
+    const usage = subtreeUsage(rootId);
+    candidates.push(rootId);
+    projectedBytes -= usage.bytes;
+    projectedEntries -= usage.entries;
+    if (projectedEntries <= maxEntries && projectedBytes <= maxBytes) break;
   }
+  if (projectedEntries > maxEntries || projectedBytes > maxBytes) return false;
+  for (const rootId of candidates) removeSubtree(rootId);
+  return true;
 }
 
 export function clearResponseHistoryForTests() {
   histories.clear();
   childrenById.clear();
   treeLru.clear();
+  pinnedTrees.clear();
   evictedIds.clear();
   totalBytes = 0;
   maxBytes = DEFAULT_MAX_BYTES;
@@ -202,6 +250,50 @@ export function responseHistoryMaterializedBytes(responseId) {
   return chain.reduce((bytes, entry) => bytes + entry.bytes, 0);
 }
 
+export function acquireResponseHistorySnapshot(responseId, { assertActive, signal } = {}) {
+  assertActive?.();
+  if (signal?.aborted) throw signal.reason || new DOMException("The operation was aborted", "AbortError");
+  const { chain, rootId } = responseHistoryChain(responseId);
+  const entries = chain.slice().reverse();
+  const bytes = chain.reduce((total, entry) => total + entry.bytes, 0);
+  pinTree(rootId);
+
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    signal?.removeEventListener("abort", release);
+    unpinTree(rootId);
+  };
+  signal?.addEventListener("abort", release, { once: true });
+
+  return Object.freeze({
+    responseId,
+    rootId,
+    bytes,
+    materialize({ assertActive: assertSnapshotActive, routeMetadata } = {}) {
+      assertSnapshotActive?.();
+      if (released) throw new Error("Response history snapshot has been released");
+      const items = [];
+      for (let index = 0; index < entries.length; index += 1) {
+        if ((index & 63) === 0) assertSnapshotActive?.();
+        const entry = entries[index];
+        routeMetadata?.push({
+          affinity: entry.routeAffinity || null,
+          hasOpaque: entry.hasOpaque === true,
+        });
+        items.push(...entry.inputItems, ...entry.outputItems);
+      }
+      assertSnapshotActive?.();
+      const materialized = cloneJson(items);
+      assertSnapshotActive?.();
+      touchTree(rootId);
+      return materialized;
+    },
+    release,
+  });
+}
+
 export function materializeResponseHistory(responseId, { assertActive, routeMetadata } = {}) {
   assertActive?.();
   const { chain, rootId } = responseHistoryChain(responseId);
@@ -231,7 +323,13 @@ export function rememberResponseHistoryNode({
   routeAffinity = null,
   takeOwnership = false,
 }) {
-  if (!id || !Array.isArray(inputItems)) return;
+  if (!id || !Array.isArray(inputItems)) return false;
+  const existing = histories.get(id);
+  const parentEntry = parentId ? histories.get(parentId) : null;
+  if (parentId && !parentEntry) {
+    if (!existing) rememberEvictedId(id);
+    return false;
+  }
   clearResponsesToolOutputPartsCache(inputItems);
   clearResponsesToolOutputPartsCache(outputItems);
   const historyValue = routeAffinity
@@ -239,13 +337,11 @@ export function rememberResponseHistoryNode({
     : [inputItems, outputItems];
   const bytes = jsonByteLength(historyValue);
   if (bytes > maxBytes) {
-    if (histories.has(id)) removeSubtree(id);
-    rememberEvictedId(id);
-    return;
+    if (!existing) rememberEvictedId(id);
+    else if (!treeIsPinned(existing.rootId)) removeSubtree(id);
+    return false;
   }
-  const existing = histories.get(id);
-  const parentEntry = parentId ? histories.get(parentId) : null;
-  const rootId = parentEntry?.rootId || (parentId ? existing?.rootId : id) || id;
+  const rootId = parentEntry?.rootId || id;
   const entry = {
     parentId: parentId || null,
     rootId,
@@ -256,6 +352,19 @@ export function rememberResponseHistoryNode({
     bytes,
   };
   const oldRootId = existing?.rootId;
+  const protectedRoots = new Set([rootId]);
+  if (oldRootId) protectedRoots.add(oldRootId);
+  if (!makeRoomFor({
+    additionalBytes: bytes - (existing?.bytes || 0),
+    additionalEntries: existing ? 0 : 1,
+    protectedRoots,
+  })) {
+    if (!existing) {
+      if (parentEntry && !treeIsPinned(rootId)) removeSubtree(rootId);
+      rememberEvictedId(id);
+    }
+    return false;
+  }
   if (existing) {
     totalBytes -= existing.bytes;
     unlinkChild(existing.parentId, id);
@@ -270,5 +379,5 @@ export function rememberResponseHistoryNode({
   totalBytes += entry.bytes;
   evictedIds.delete(id);
   touchTree(rootId);
-  enforceLimits();
+  return true;
 }