@zaip-ai/cli 6.3.0 → 7.5.0

package/templates/.agents/skills/zaip-skill-worktree-recovery/scripts/durable-state-migration.mjs

@@ -0,0 +1,234 @@
+import { randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { link, lstat, open, readFile, realpath, unlink } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { revalidateDurableStatePlan } from "./durable-state-batches.mjs";
+import {
+  clearPrivatePermissionChecks,
+  digest,
+  directory,
+  hashFile,
+  physical,
+} from "./durable-state-files.mjs";
+import { selectedFamily, stateMapping } from "./durable-state-layout.mjs";
+import { privatePermissions } from "./durable-state-permissions.mjs";
+import { noActiveOwner, optional, planDurableState } from "./durable-state-plan.mjs";
+
+const transactionRoot = ".agents/private/state/storage-migrations";
+
+export function checkedPlan(plan) {
+  if (
+    !plan ||
+    Object.keys(plan).sort().join() !==
+      (plan.batch ? "batch,family,id,rows,schema_version" : "family,id,rows,schema_version") ||
+    plan.schema_version !== 1 ||
+    !Array.isArray(plan.rows) ||
+    plan.rows.length > 50000
+  )
+    throw new Error("Invalid state migration plan");
+  if (plan.batch) {
+    const batch = plan.batch;
+    if (
+      Object.keys(batch).sort().join() !== "batch_size,index,kind,previous_id" ||
+      batch.kind !== "explicit-sources" ||
+      !Number.isSafeInteger(batch.index) ||
+      batch.index < 0 ||
+      !Number.isSafeInteger(batch.batch_size) ||
+      batch.batch_size < 1 ||
+      batch.batch_size > 5000 ||
+      plan.rows.length < 1 ||
+      plan.rows.length > batch.batch_size ||
+      (batch.index === 0 ? batch.previous_id !== null : !/^[a-f0-9]{64}$/.test(batch.previous_id))
+    )
+      throw new Error("Invalid state migration batch selector");
+  }
+  const family = selectedFamily(plan.family);
+  const seen = new Set();
+  for (const row of plan.rows) {
+    if (
+      Object.keys(row).sort().join() !== "bytes,destination,privacy,sha256,source" ||
+      !(row.source === family.from || row.source.startsWith(`${family.from}/`)) ||
+      !/^[a-f0-9]{64}$/.test(row.sha256) ||
+      !Number.isSafeInteger(row.bytes) ||
+      row.bytes < 0 ||
+      seen.has(row.source.toLowerCase())
+    )
+      throw new Error("Invalid state migration row");
+    const mapping = stateMapping(row.source);
+    if (
+      mapping.from !== family.from ||
+      mapping.destination !== row.destination ||
+      mapping.privacy !== row.privacy
+    )
+      throw new Error("State migration mapping drift");
+    seen.add(row.source.toLowerCase());
+  }
+  const { id, ...body } = plan;
+  if (id !== digest(JSON.stringify(body))) throw new Error("State migration plan digest differs");
+  return plan;
+}
+
+export async function exclusiveJson(root, name, value) {
+  await directory(root, dirname(name).replaceAll("\\", "/"));
+  const text = `${JSON.stringify(value)}\n`;
+  const path = await physical(root, name, true);
+  const staging = `${path}.stage-${randomUUID()}`;
+  let handle;
+  try {
+    handle = await open(staging, "wx", 0o600);
+    await handle.writeFile(text);
+    await handle.sync();
+    await handle.close();
+    handle = undefined;
+    await link(staging, path);
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    if ((await readFile(await physical(root, name), "utf8")) !== text)
+      throw new Error("Migration receipt collision");
+  } finally {
+    await handle?.close();
+    await unlink(staging).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+  }
+}
+
+export async function withMigrationLock(root, operation) {
+  clearPrivatePermissionChecks(root);
+  await directory(root, ".agents/private/state");
+  const name = ".agents/private/state/storage-migration.lock";
+  const path = await physical(root, name, true);
+  const lock = await open(path, "wx", 0o600);
+  const identity = await lstat(path);
+  try {
+    await lock.writeFile(`${process.pid}\n`);
+    const result = await operation();
+    const current = await lstat(await physical(root, name));
+    if (identity.dev !== current.dev || identity.ino !== current.ino)
+      throw new Error("Migration lock ownership changed");
+    return result;
+  } finally {
+    await lock.close();
+    const current = await optional(path);
+    if (
+      current &&
+      !current.isSymbolicLink() &&
+      current.dev === identity.dev &&
+      current.ino === identity.ino
+    )
+      await unlink(path);
+    clearPrivatePermissionChecks(root);
+  }
+}
+
+async function assertCurrentPlan(root, plan) {
+  if (plan.batch) return revalidateDurableStatePlan(root, plan);
+  if ((await planDurableState(root, plan.family)).id !== plan.id)
+    throw new Error("State changed after dry-run; originals retained");
+}
+
+/** Copy first, retain every source byte until coordinated activation and finalize. */
+export async function applyDurableState(workspace, input, handoff) {
+  const root = await realpath(workspace);
+  const plan = checkedPlan(input);
+  return withMigrationLock(root, async () => {
+    await noActiveOwner(root, handoff);
+    await assertCurrentPlan(root, plan);
+    await exclusiveJson(root, `${transactionRoot}/${plan.id}.json`, plan);
+    const created = [];
+    for (const row of plan.rows) {
+      await directory(root, dirname(row.destination).replaceAll("\\", "/"));
+      const destination = await physical(root, row.destination, true);
+      try {
+        const handle = await open(destination, "wx", 0o600);
+        try {
+          // Stream bytes into an owned new file; Windows CopyFile can copy a broad source DACL.
+          for await (const chunk of createReadStream(await physical(root, row.source))) {
+            await handle.writeFile(chunk);
+          }
+          await handle.sync();
+        } finally {
+          await handle.close();
+        }
+        created.push(row.destination);
+      } catch (error) {
+        if (error.code !== "EEXIST") throw error;
+      }
+      if (
+        (await hashFile(root, row.source)).sha256 !== row.sha256 ||
+        (await hashFile(root, row.destination)).sha256 !== row.sha256
+      )
+        throw new Error("Migration copy parity failed; originals retained");
+    }
+    await privatePermissions(root, created, "protect");
+    await privatePermissions(
+      root,
+      plan.rows.map((row) => row.destination),
+    );
+    await noActiveOwner(root, handoff);
+    await assertCurrentPlan(root, plan);
+    return {
+      id: plan.id,
+      status: "copied_pending_activation",
+      files: plan.rows.length,
+      sources_retained: true,
+    };
+  });
+}
+
+async function activated() {
+  throw new Error(
+    "Use the native task storage-handoff generation coordinator; standalone finalization cannot prove coordinated activation",
+  );
+}
+
+export async function finalizeDurableState(workspace, id) {
+  if (!/^[a-f0-9]{64}$/.test(id)) throw new Error("Invalid migration transaction id");
+  const root = await realpath(workspace);
+  return withMigrationLock(root, async () => {
+    const path = `${transactionRoot}/${id}.json`;
+    const info = await lstat(await physical(root, path));
+    if (info.size > 32 * 1024 * 1024) throw new Error("Migration plan exceeds bound");
+    const plan = checkedPlan(JSON.parse(await readFile(resolve(root, path), "utf8")));
+    if (plan.id !== id) throw new Error("Migration transaction differs");
+    await noActiveOwner(root);
+    const hook_sha256 = await activated();
+    const sources = new Set(plan.rows.map((row) => row.source));
+    for (const row of plan.rows) {
+      if ((await hashFile(root, row.destination)).sha256 !== row.sha256)
+        throw new Error("Durable destination changed; retain legacy source");
+      if (await optional(resolve(root, row.source))) {
+        if ((await hashFile(root, row.source)).sha256 !== row.sha256)
+          throw new Error("Legacy state changed before activation");
+      }
+    }
+    const remaining = await planDurableState(root, plan.family);
+    if (remaining.rows.some((row) => !sources.has(row.source)))
+      throw new Error("New legacy state appeared before cutover");
+    await noActiveOwner(root);
+    const receipt = {
+      schema_version: 1,
+      id,
+      family: plan.family,
+      files: plan.rows.length,
+      bytes: plan.rows.reduce((n, row) => n + row.bytes, 0),
+      manifest_sha256: digest(JSON.stringify(plan)),
+      hook_sha256,
+    };
+    await exclusiveJson(root, `.agents/state/storage-migrations/${id}.json`, receipt);
+    for (const row of plan.rows) {
+      const source = await physical(root, row.source, true);
+      if (await optional(source)) {
+        if (
+          (await hashFile(root, row.source)).sha256 !== row.sha256 ||
+          (await hashFile(root, row.destination)).sha256 !== row.sha256
+        )
+          throw new Error("Cutover race detected");
+        await unlink(source);
+      }
+    }
+    return { ...receipt, status: "finalized", sources_retained: false };
+  });
+}
+
+export { planDurableState, revalidateDurableStatePlan };

package/templates/.agents/skills/zaip-skill-worktree-recovery/scripts/durable-state-observation-tail.mjs

@@ -0,0 +1,148 @@
+import assert from "node:assert/strict";
+import { lstat, readFile } from "node:fs/promises";
+import { durableStateSources } from "./durable-state-batches.mjs";
+import { digest, physical } from "./durable-state-files.mjs";
+import { loadStoragePlan } from "./durable-state-journal.mjs";
+import { checkedPlan, exclusiveJson } from "./durable-state-migration.mjs";
+import { durableStateRow, optional } from "./durable-state-plan.mjs";
+
+const observationPath = /^\.local\/hooks\/observations\/([a-f0-9]{64})\.json$/;
+const keys = new Set([
+  "schema_version",
+  "state",
+  "event_id",
+  "event_name",
+  "session_id",
+  "turn_id",
+  "agent_id",
+  "agent_path",
+  "parent_agent_id",
+  "tool_call_id",
+  "agent_type",
+  "model",
+  "reasoning_effort",
+  "status",
+  "transcript_path",
+  "governance",
+  "observed_at",
+  "run_id",
+  "last_error",
+]);
+
+/** An observation is copied as opaque evidence, never promoted to authorization. */
+export async function assertObservationTailSource(root, source) {
+  const match = observationPath.exec(source);
+  assert(match, "Unplanned legacy state is not a hook observation");
+  const path = await physical(root, source);
+  assert((await lstat(path)).size <= 16384, "Oversized hook observation");
+  const value = JSON.parse(await readFile(path, "utf8"));
+  assert(value && typeof value === "object" && !Array.isArray(value));
+  assert(
+    Object.keys(value).every((key) => keys.has(key)),
+    "Unknown observation fields",
+  );
+  assert(
+    value.schema_version === 1 &&
+      ["pending", "persisted"].includes(value.state) &&
+      ["PreToolUse", "SubagentStart", "SubagentStop", "Stop"].includes(value.event_name) &&
+      value.event_id === `HOBS-${match[1]}` &&
+      typeof value.governance === "boolean" &&
+      typeof value.session_id === "string" &&
+      value.session_id.length > 0 &&
+      value.session_id.length <= 200 &&
+      typeof value.turn_id === "string" &&
+      value.turn_id.length > 0 &&
+      value.turn_id.length <= 200 &&
+      typeof value.observed_at === "string" &&
+      Number.isFinite(Date.parse(value.observed_at)),
+    "Invalid hook observation tail",
+  );
+}
+
+/** Seal exactly once after the writer transition. Resume never expands this selection. */
+export async function sealObservationTail(
+  root,
+  generation,
+  handoff,
+  selection,
+  { required = false } = {},
+) {
+  const initial = selection.find((group) => group.family === "hooks");
+  assert(initial, "Missing hooks selection");
+  const name = `.agents/private/state/storage-cutover/observation-tails/${generation.id}.json`;
+  const path = await physical(root, name, true);
+  let body;
+  if (await optional(path)) {
+    assert((await lstat(path)).size <= 1024 * 1024, "Oversized observation tail manifest");
+    const { id, ...stored } = JSON.parse(await readFile(path, "utf8"));
+    assert.equal(id, digest(JSON.stringify(stored)), "Observation tail manifest changed");
+    body = stored;
+    assert.equal(body.schema_version, 1);
+    assert.equal(body.generation, generation.id);
+    assert.equal(body.task, handoff.task_id);
+    assert.equal(body.run, handoff.run_id);
+    assert.deepEqual(body.initial, initial.ids);
+    assert(Array.isArray(body.ids) && body.ids.length <= 1);
+  } else {
+    assert(!required, "Missing sealed observation tail after deletion started");
+    const known = new Set();
+    for (const id of initial.ids)
+      for (const row of (await loadStoragePlan(root, id)).rows) known.add(row.source);
+    const sources = [];
+    if (await optional(await physical(root, ".local/hooks/observations", true)))
+      for await (const source of durableStateSources(
+        root,
+        ".local/hooks/observations",
+        ".local/hooks",
+      )) {
+        if (known.has(source)) continue;
+        await assertObservationTailSource(root, source);
+        sources.push(source);
+        assert(sources.length <= 5000, "Observation tail exceeds bounded transition capacity");
+      }
+    const rows = [];
+    for (const source of sources.sort()) rows.push(await durableStateRow(root, source));
+    const ids = [];
+    if (rows.length) {
+      const planBody = {
+        schema_version: 1,
+        family: "hooks",
+        batch: {
+          kind: "explicit-sources",
+          index: initial.ids.length,
+          batch_size: 5000,
+          previous_id: initial.ids.at(-1) ?? null,
+        },
+        rows,
+      };
+      const plan = checkedPlan({ ...planBody, id: digest(JSON.stringify(planBody)) });
+      await exclusiveJson(root, `.agents/private/state/storage-migrations/${plan.id}.json`, plan);
+      ids.push(plan.id);
+    }
+    body = {
+      schema_version: 1,
+      generation: generation.id,
+      task: handoff.task_id,
+      run: handoff.run_id,
+      initial: initial.ids,
+      ids,
+    };
+    await exclusiveJson(root, name, { ...body, id: digest(JSON.stringify(body)) });
+  }
+  for (const id of body.ids) {
+    const plan = await loadStoragePlan(root, id);
+    assert.equal(plan.family, "hooks");
+    assert.equal(plan.batch.index, initial.ids.length);
+    assert.equal(plan.batch.previous_id, initial.ids.at(-1) ?? null);
+    assert(
+      plan.rows.every((row) => observationPath.test(row.source)),
+      "Non-observation tail row",
+    );
+  }
+  return {
+    ids: body.ids,
+    selection: selection.map((group) =>
+      group.family === "hooks" ? { ...group, ids: [...group.ids, ...body.ids] } : group,
+    ),
+  };
+}

package/templates/.agents/skills/zaip-skill-worktree-recovery/scripts/durable-state-permissions.mjs

@@ -0,0 +1,52 @@
+import { chmod, lstat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { execute } from "../../../tools/cloud-runner-process.mjs";
+
+/** `protect` is only for objects just created by this migration, never EEXIST. */
+export async function privatePermissions(root, paths, operation = "verify") {
+  if (!["protect", "verify"].includes(operation))
+    throw new Error("Invalid private permission operation");
+  const selected = [...new Set(paths)].filter(
+    (path) => path === ".agents/private" || path.startsWith(".agents/private/"),
+  );
+  if (!selected.length) return;
+  if (process.platform === "win32") {
+    // Keep stdin below the fixed PowerShell 8 MiB bound, without one process per
+    // tiny group. Paths remain validated individually; output is still bounded.
+    if (
+      selected.length > 2000 ||
+      Buffer.byteLength(JSON.stringify({ root, paths: selected })) > 4 * 1024 * 1024
+    ) {
+      if (selected.length === 1) throw new Error("Private state ACL path exceeds bound");
+      const middle = Math.ceil(selected.length / 2);
+      await privatePermissions(root, selected.slice(0, middle), operation);
+      await privatePermissions(root, selected.slice(middle), operation);
+      return;
+    }
+    const result = await execute(
+      "powershell.exe",
+      [
+        "-NoProfile",
+        "-NonInteractive",
+        "-File",
+        fileURLToPath(new URL("./durable-state-acl.ps1", import.meta.url)),
+        "-Operation",
+        operation,
+      ],
+      { input: JSON.stringify({ root, paths: selected }), timeout: 60000, maxOutput: 2048 },
+    );
+    if (result.code !== 0 || result.stdout.trim() !== "private_state_acl_verified")
+      throw new Error("Private state effective DACL/owner verification failed");
+    return;
+  }
+  for (const path of selected) {
+    const absolute = `${root}/${path}`;
+    const info = await lstat(absolute);
+    if (info.isSymbolicLink() || (!info.isFile() && !info.isDirectory()))
+      throw new Error("Invalid private state entry");
+    if (operation === "protect") await chmod(absolute, info.isDirectory() ? 0o700 : 0o600);
+    const current = await lstat(absolute);
+    if (current.uid !== process.getuid() || (current.mode & 0o077) !== 0)
+      throw new Error("Private state permissions are too broad");
+  }
+}

package/templates/.agents/skills/zaip-skill-worktree-recovery/scripts/durable-state-plan.mjs

@@ -0,0 +1,143 @@
+import { lstat, readdir, readFile, realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { digest, hashFile, physical } from "./durable-state-files.mjs";
+import { selectedFamily, stateMapping } from "./durable-state-layout.mjs";
+
+export async function optional(path) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+export async function noActiveOwner(root, handoff) {
+  const authority = handoff
+    ? await import(
+        pathToFileURL(resolve(root, ".agents/private/state/storage-cutover/runtime/zaip.mjs")).href
+      )
+    : null;
+  if (authority) authority.assertStorageHandoffCapability(handoff);
+  for (const name of [
+    ".local/locks",
+    ".agents/private/state/locks",
+    ".local/task-workspaces/shared-writer.json",
+    ".agents/private/state/task-workspaces/shared-writer.json",
+    ".local/task-workspaces/claims",
+    ".agents/private/state/task-workspaces/claims",
+  ]) {
+    const info = await optional(resolve(root, name));
+    if (!info) continue;
+    await physical(root, name);
+    if (
+      info.isFile() &&
+      authority?.storageHandoffOwnsFile(
+        handoff,
+        root,
+        name,
+        await readFile(resolve(root, name), "utf8"),
+      )
+    )
+      continue;
+    if (info.isFile() || (await readdir(resolve(root, name))).length) {
+      throw new Error("State migration requires canonical writer closure and quiescent locks");
+    }
+  }
+}
+
+async function files(root, name, result) {
+  const path = await physical(root, name);
+  const info = await lstat(path);
+  if (/\.(?:lock|execution-lease)$/.test(name))
+    throw new Error("Active or unresolved state lease blocks migration");
+  if (name.split("/").includes(".git"))
+    throw new Error("Registered worktrees require canonical Git relocation");
+  if (info.isDirectory()) {
+    for (const child of (await readdir(path)).sort()) await files(root, `${name}/${child}`, result);
+  } else if (info.isFile()) {
+    result.push(name);
+    if (result.length > 50000) throw new Error("State migration file bound exceeded");
+  } else throw new Error("Unsupported state entry");
+}
+
+export async function portableFacts(root, source, mapping) {
+  if (mapping.privacy !== "canonical") return;
+  const info = await lstat(await physical(root, source));
+  if (info.size > 4 * 1024 * 1024 || !source.endsWith(".json"))
+    throw new Error("Portable state must be bounded JSON facts");
+  const value = JSON.parse(await readFile(resolve(root, source), "utf8"));
+  const walk = (item) => {
+    if (Array.isArray(item)) return item.forEach(walk);
+    if (item && typeof item === "object") {
+      for (const [key, child] of Object.entries(item)) {
+        if (/password|secret|token|private.?key|transcript|authorization|credential/i.test(key)) {
+          throw new Error("Private material cannot migrate into portable state");
+        }
+        walk(child);
+      }
+    }
+  };
+  walk(value);
+  if (source.startsWith(".local/autonomous/astra-diagnostic-quota/")) {
+    const keys = [
+      "task_id",
+      "invocation_id",
+      "execution_id",
+      "run_id",
+      "evidence_fingerprint",
+      "reserved_at",
+    ];
+    if (
+      !value ||
+      Object.keys(value).length !== keys.length ||
+      Object.keys(value).some((key) => !keys.includes(key)) ||
+      !/^TASK-[A-Z0-9-]+$/.test(value.task_id) ||
+      !/^EXEC-[A-Z0-9-]+$/.test(value.execution_id) ||
+      typeof value.invocation_id !== "string" ||
+      !/^[a-f0-9]{64}$/.test(value.evidence_fingerprint) ||
+      !Number.isFinite(Date.parse(value.reserved_at)) ||
+      (value.run_id !== null && !/^RUN-[A-Z0-9-]+$/.test(value.run_id))
+    ) {
+      throw new Error("Invalid portable diagnostic reservation");
+    }
+  } else if (
+    value?.version !== 1 ||
+    !/^TASK-[A-Z0-9-]+$/.test(value.task_id) ||
+    !Array.isArray(value.entries)
+  ) {
+    throw new Error("Invalid portable recovery ledger");
+  }
+}
+
+export async function durableStateRow(root, source) {
+  const target = stateMapping(source);
+  await portableFacts(root, source, target);
+  const identity = await hashFile(root, source);
+  if (await optional(resolve(root, target.destination))) {
+    const existing = await hashFile(root, target.destination);
+    if (existing.sha256 !== identity.sha256) throw new Error("Divergent durable state collision");
+  }
+  return { source, destination: target.destination, privacy: target.privacy, ...identity };
+}
+
+/** Hash only explicitly selected known families, never the entire .local archive. */
+export async function planDurableState(workspace, family) {
+  const root = await realpath(workspace);
+  const mapping = selectedFamily(family);
+  const sourceFiles = [];
+  if (await optional(resolve(root, mapping.from))) await files(root, mapping.from, sourceFiles);
+  const rows = [];
+  const destinations = new Set();
+  for (const source of sourceFiles) {
+    const target = stateMapping(source);
+    if (target.from !== mapping.from) continue;
+    const key = target.destination.toLowerCase();
+    if (destinations.has(key)) throw new Error("Case-insensitive state collision");
+    destinations.add(key);
+    rows.push(await durableStateRow(root, source));
+  }
+  const body = { schema_version: 1, family, rows };
+  return { ...body, id: digest(JSON.stringify(body)) };
+}

package/templates/.agents/skills/zaip-skill-worktree-recovery/scripts/durable-state-preparation.mjs

@@ -0,0 +1,110 @@
+import assert from "node:assert/strict";
+import { lstat, open, readdir, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { digest, hashFile, physical } from "./durable-state-files.mjs";
+import { readStorageGeneration, verifyInstalledGeneration } from "./durable-state-generation.mjs";
+import { loadStoragePlan } from "./durable-state-journal.mjs";
+import { exclusiveJson } from "./durable-state-migration.mjs";
+import { optional } from "./durable-state-plan.mjs";
+import { preservePreparedTelemetryVersion } from "./durable-state-telemetry-version.mjs";
+
+/** Retire only a preparation that never activated files. Verify and retain copies.
+ * appends history under native ownership; it does not mark migration completed. */
+export async function retireStoragePreparations(root, handoff, generation) {
+  const authority = await import(
+    pathToFileURL(resolve(root, ".agents/private/state/storage-cutover/runtime/zaip.mjs")).href
+  );
+  authority.assertStorageHandoffCapability(handoff);
+  const base = ".agents/private/state/storage-cutover";
+  assert(
+    !(await optional(await physical(root, `${base}/active.lock`, true))),
+    "Active cutover blocks preparation retirement",
+  );
+  for (const name of await readdir(await physical(root, base))) {
+    if (!/^[a-f0-9]{64}\.jsonl$/.test(name) || name === `${generation.id}.jsonl`) continue;
+    const path = await physical(root, `${base}/${name}`),
+      info = await lstat(path);
+    assert(info.size <= 16 * 1024 * 1024, "Oversized former journal");
+    const text = await readFile(path, "utf8");
+    assert(text.endsWith("\n"), "Truncated former journal requires recovery");
+    const events = text
+      .trimEnd()
+      .split("\n")
+      .map((line) => JSON.parse(line));
+    if (events[0]?.task !== handoff.task_id || events[0]?.run !== handoff.run_id) continue;
+    if (events.some((event) => !["started", "interrupted", "copied"].includes(event.type)))
+      continue;
+    assert(
+      events
+        .slice(1)
+        .every(
+          (event) =>
+            event.type === "copied" ||
+            (event.activated === false && event.deletion_started === false),
+        ),
+      "Former operational effects unknown",
+    );
+    const previous = await readStorageGeneration(
+      root,
+      `${base}/generations/${name.slice(0, -6)}.json`,
+    );
+    await verifyInstalledGeneration(root, previous, false);
+    for (const event of events.filter((row) => row.type === "copied")) {
+      const plan = await loadStoragePlan(root, event.id);
+      assert.equal(plan.family, event.family);
+      let cursor = 0;
+      const changes = [];
+      // Bounded parallel read-only verification; recovery mutations stay sequential.
+      await Promise.all(
+        Array.from({ length: 8 }, async () => {
+          while (cursor < plan.rows.length) {
+            const row = plan.rows[cursor++];
+            const current = await hashFile(root, row.source);
+            if (current.sha256 !== row.sha256) changes.push({ row, current });
+            else
+              assert.equal(
+                (await hashFile(root, row.destination)).sha256,
+                row.sha256,
+                "Prepared copy changed; retain its generation",
+              );
+          }
+        }),
+      );
+      for (const { row, current } of changes)
+        await preservePreparedTelemetryVersion(root, row, current, handoff, generation, plan.id);
+    }
+    const receipt = {
+      schema_version: 1,
+      status: events.some((event) => event.type === "copied")
+        ? "preparation_superseded_before_activation"
+        : "preparation_cancelled_before_copy",
+      generation: previous.id,
+      replacement: generation.id,
+      task: handoff.task_id,
+      run: handoff.run_id,
+      journal_sha256: digest(text),
+    };
+    await exclusiveJson(
+      root,
+      `.agents/state/storage-migrations/preparation-${previous.id}.json`,
+      receipt,
+    );
+    const current = await lstat(path);
+    assert(
+      current.ino === info.ino &&
+        current.dev === info.dev &&
+        (await readFile(path, "utf8")) === text,
+      "Former journal changed",
+    );
+    const file = await open(path, "a");
+    try {
+      await file.writeFile(
+        `${JSON.stringify({ type: "preparation_cancelled", replacement: generation.id, journal_sha256: receipt.journal_sha256 })}\n`,
+      );
+      await file.sync();
+    } finally {
+      await file.close();
+    }
+  }
+}