@zaip-ai/cli 6.3.0 → 7.5.0

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

@@ -0,0 +1,84 @@
+import { open, readFile, realpath, unlink } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { digest, directory, physical } from "./durable-state-files.mjs";
+import { selectedFamily } from "./durable-state-layout.mjs";
+import { applyDurableState, planDurableState } from "./durable-state-migration.mjs";
+import { noActiveOwner } from "./durable-state-plan.mjs";
+
+/** Stage one durable copy under a live native capability. No namespace flip or deletion. */
+export async function copyStorageSession(handoff, selector) {
+  const root = await realpath(handoff.root);
+  const entry = await import(
+    pathToFileURL(resolve(root, ".agents/private/state/storage-cutover/runtime/zaip.mjs")).href
+  );
+  entry.assertStorageHandoffCapability(handoff);
+  if (
+    !/^\.agents\/private\/state\/storage-cutover\/generations\/[a-f0-9]{64}\.json$/.test(selector)
+  )
+    throw new Error("Invalid reviewed storage copy selector");
+  const path = await physical(root, selector);
+  const text = await readFile(path, "utf8");
+  if (Buffer.byteLength(text) > 16384) throw new Error("Oversized storage copy selector");
+  const selection = JSON.parse(text);
+  if (
+    Object.keys(selection).sort().join() !== "families,schema_version" ||
+    selection.schema_version !== 1 ||
+    !Array.isArray(selection.families) ||
+    !selection.families.length ||
+    selection.families.length > 64 ||
+    new Set(selection.families).size !== selection.families.length ||
+    selector !==
+      `.agents/private/state/storage-cutover/generations/${digest(JSON.stringify(selection))}.json`
+  )
+    throw new Error("Storage copy selection differs from its locator");
+  for (const family of selection.families) {
+    selectedFamily(family);
+    if (
+      [
+        "locks",
+        "backup-worktrees",
+        "backup-branchs",
+        "worktrees",
+        "task-workspaces",
+        "local-catalog-controller-lease",
+      ].includes(family)
+    )
+      throw new Error("Owner/archive family requires coordinated final cutover, not copy staging");
+  }
+  await noActiveOwner(root, handoff);
+  await directory(root, ".agents/private/state/storage-cutover");
+  const lockPath = await physical(
+    root,
+    ".agents/private/state/storage-cutover/copy-session.lock",
+    true,
+  );
+  const lock = await open(lockPath, "wx", 0o600);
+  const lockText = `${process.pid}\n${handoff.context_sha256}\n`;
+  try {
+    await lock.writeFile(lockText);
+    await lock.sync();
+    const copies = [];
+    for (const family of selection.families) {
+      await noActiveOwner(root, handoff);
+      const plan = await planDurableState(root, family);
+      const result = await applyDurableState(root, plan, handoff);
+      copies.push({ family, id: result.id, files: result.files, status: result.status });
+    }
+    await noActiveOwner(root, handoff);
+    return {
+      schema_version: 1,
+      task_id: handoff.task_id,
+      run_id: handoff.run_id,
+      claim_sha256: handoff.claim_sha256,
+      copies,
+      status: "copied_pending_activation",
+      sources_retained: true,
+      namespace_changed: false,
+      publication: false,
+    };
+  } finally {
+    await lock.close();
+    if ((await readFile(lockPath, "utf8")) === lockText) await unlink(lockPath);
+  }
+}

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

@@ -0,0 +1,350 @@
+import assert from "node:assert/strict";
+import { lstat, readdir, realpath, rmdir, unlink } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { organizeLegacyStorage } from "./durable-local-archive.mjs";
+import { createHistoricalAliasPublisher } from "./durable-state-alias.mjs";
+import { durableStateSources, revalidateDurableStatePlan } from "./durable-state-batches.mjs";
+import { digest, directory, hashFile, physical } from "./durable-state-files.mjs";
+import {
+  assertStorageRuntimeQuiescent,
+  readStorageGeneration,
+  replaceStorageGeneration,
+  verifyGenerationSources,
+  verifyInstalledGeneration,
+} from "./durable-state-generation.mjs";
+import {
+  loadStoragePlan as loadPlan,
+  sealStorageSelection,
+  storageJournal,
+} from "./durable-state-journal.mjs";
+import { STATE_MAPPINGS, selectedFamily } from "./durable-state-layout.mjs";
+import { acquireStorageLock } from "./durable-state-lock.mjs";
+import { applyDurableState, checkedPlan, exclusiveJson } from "./durable-state-migration.mjs";
+import {
+  assertObservationTailSource,
+  sealObservationTail,
+} from "./durable-state-observation-tail.mjs";
+import { privatePermissions } from "./durable-state-permissions.mjs";
+import { noActiveOwner, optional } from "./durable-state-plan.mjs";
+import { retireStoragePreparations } from "./durable-state-preparation.mjs";
+import { reusePreparedState } from "./durable-state-reuse.mjs";
+import { assertHistoricalTelemetryVersion } from "./durable-state-telemetry-version.mjs";
+
+// These trees are preserved by the separate archival/registered-Git procedure.
+const archiveFamilies = new Set([
+  "backup-worktrees",
+  "backup-branchs",
+  "worktrees",
+  "w",
+  "git",
+  "terraform",
+  "ci",
+]);
+async function permissionsInBatches(root, names) {
+  const rows = [...names];
+  for (let offset = 0; offset < rows.length; offset += 250)
+    await privatePermissions(root, rows.slice(offset, offset + 250));
+}
+async function publishPlanReceipt(root, plan, generation, selector) {
+  await exclusiveJson(root, `.agents/state/storage-migrations/${plan.id}.json`, {
+    schema_version: 1,
+    id: plan.id,
+    family: plan.family,
+    files: plan.rows.length,
+    bytes: plan.rows.reduce((sum, row) => sum + row.bytes, 0),
+    manifest_sha256: digest(JSON.stringify(plan)),
+    hook_sha256: generation.id,
+    generation: selector,
+  });
+}
+async function verifyRelatedPlans(root, selection, related) {
+  if (!related.size) return;
+  const selected = new Map();
+  for (const group of selection)
+    for (const id of group.ids)
+      for (const row of (await loadPlan(root, id)).rows) selected.set(row.source, row);
+  for (const id of related)
+    for (const row of (await loadPlan(root, id)).rows) {
+      const current = selected.get(row.source);
+      assert(current, "Previous alias plan is not covered by this migration");
+      if (Object.keys(row).some((key) => row[key] !== current[key]))
+        await assertHistoricalTelemetryVersion(root, row, current);
+    }
+}
+export async function assertCompleteStorageCoverage(
+  root,
+  family,
+  plans,
+  { observationTail = false } = {},
+) {
+  const mapping = selectedFamily(family),
+    names = new Set();
+  let previous = null,
+    index = 0;
+  for await (const plan of plans) {
+    checkedPlan(plan);
+    assert.equal(plan.family, family);
+    assert.equal(plan.batch.index, index++);
+    assert.equal(plan.batch.previous_id, previous);
+    previous = plan.id;
+    for (const row of plan.rows) {
+      assert(!names.has(row.source.toLowerCase()), "Duplicate source across storage batches");
+      names.add(row.source.toLowerCase());
+    }
+  }
+  if (await optional(resolve(root, mapping.from))) {
+    for await (const source of durableStateSources(root, mapping.from, mapping.from)) {
+      if (names.delete(source.toLowerCase())) continue;
+      assert(
+        observationTail && family === "hooks",
+        "Unplanned legacy state appeared before activation",
+      );
+      await assertObservationTailSource(root, source);
+    }
+  }
+  assert.equal(names.size, 0, "Legacy state disappeared before activation");
+}
+async function pruneEmpty(root, name) {
+  const info = await optional(resolve(root, name));
+  if (!info?.isDirectory()) return;
+  const path = await physical(root, name);
+  for (const entry of await readdir(path, { withFileTypes: true })) {
+    if (entry.isDirectory()) await pruneEmpty(root, `${name}/${entry.name}`);
+  }
+  try {
+    await rmdir(path);
+  } catch (error) {
+    if (error.code !== "ENOTEMPTY") throw error;
+  }
+}
+/** Native authority is required in-process. A manifest alone never authorizes a cutover. */
+export async function cutoverStorageSession(handoff, selector) {
+  const root = await realpath(handoff.root);
+  const authority = await import(
+    pathToFileURL(resolve(root, ".agents/private/state/storage-cutover/runtime/zaip.mjs")).href
+  );
+  authority.assertStorageHandoffCapability(handoff);
+  await assertStorageRuntimeQuiescent(root);
+  const generation = await readStorageGeneration(root, selector);
+  await noActiveOwner(root, handoff);
+  const families = STATE_MAPPINGS.map((row) => row.from.slice(7)).filter(
+    (family) => !archiveFamilies.has(family),
+  );
+  await directory(root, ".agents/private/state/storage-cutover");
+  if (!(await optional(resolve(root, ".agents/private/state/storage-cutover/active.lock"))))
+    await retireStoragePreparations(root, handoff, generation);
+  const {
+    file: lock,
+    identity,
+    path: lockPath,
+  } = await acquireStorageLock(root, generation, handoff);
+  let journal;
+  const writeEvent = async (event) => journal?.write(event);
+  let activated = false,
+    deletionStarted = false;
+  try {
+    journal = await storageJournal(root, generation, handoff);
+    const related = new Set(journal.events.flatMap((event) => event.related ?? []));
+    const activationStarted = journal.events.some((event) => event.type === "activation_started");
+    activated = journal.events.some((event) => event.type === "activated");
+    deletionStarted = journal.events.some((event) => event.type === "deletion_started");
+    await verifyGenerationSources(root, generation, activationStarted ? "either" : false);
+    let selection = await sealStorageSelection(root, generation, families);
+    const copyPlan = async (plan) => {
+      const reused = await reusePreparedState(root, plan, handoff);
+      if (!reused.missing.length) {
+        const previous = reused.related.filter((id) => id !== plan.id);
+        for (const id of previous) related.add(id);
+        await writeEvent({
+          type: "copied",
+          family: plan.family,
+          id: plan.id,
+          files: plan.rows.length,
+          related: previous,
+          reused: true,
+        });
+        return "reused_verified";
+      }
+      // A sealed subset repairs only absent copies/aliases. Original selection
+      // remains the coverage boundary; related subset receipts are verified too.
+      const absent = new Set(reused.missing);
+      const body = {
+        schema_version: 1,
+        family: plan.family,
+        batch: { kind: "explicit-sources", index: 0, batch_size: 5000, previous_id: null },
+        rows: plan.rows.filter((row) => absent.has(row.source)),
+      };
+      const repair = checkedPlan({ ...body, id: digest(JSON.stringify(body)) });
+      await exclusiveJson(
+        root,
+        `.agents/private/state/storage-migrations/${repair.id}.json`,
+        repair,
+      );
+      await applyDurableState(root, repair, handoff);
+      const publisher = await createHistoricalAliasPublisher(root, repair),
+        permissions = new Set();
+      const batchRelated = new Set(reused.related.filter((id) => id !== plan.id));
+      for (const id of batchRelated) related.add(id);
+      for (const row of repair.rows) {
+        const alias = await publisher.publish(row, permissions);
+        if (alias.transaction !== plan.id) {
+          related.add(alias.transaction);
+          batchRelated.add(alias.transaction);
+        }
+      }
+      await permissionsInBatches(root, permissions);
+      await writeEvent({
+        type: "copied",
+        family: plan.family,
+        id: plan.id,
+        files: plan.rows.length,
+        repaired_files: repair.rows.length,
+        related: [...batchRelated],
+      });
+      return reused.missing.length === plan.rows.length
+        ? "copied_verified"
+        : "partially_reused_verified";
+    };
+    if (activationStarted && !activated) {
+      for (const group of selection) {
+        async function* plans() {
+          for (const id of group.ids) yield await loadPlan(root, id);
+        }
+        await assertCompleteStorageCoverage(root, group.family, plans(), { observationTail: true });
+        for (const id of group.ids)
+          await revalidateDurableStatePlan(root, await loadPlan(root, id));
+      }
+      // Roll forward only exact before/new target hashes; never restore operational counters.
+      await replaceStorageGeneration(root, generation, "apply");
+      activated = true;
+      await writeEvent({ type: "activated", generation: generation.id });
+    }
+    await verifyGenerationSources(root, generation, activated);
+    await verifyInstalledGeneration(root, generation, activated);
+    if (!activated)
+      for (const { family, ids } of selection) {
+        for (const id of ids) {
+          const plan = await loadPlan(root, id);
+          const status = await copyPlan(plan);
+          console.error(
+            JSON.stringify({
+              storage: status,
+              family,
+              batch: plan.batch.index + 1,
+              batches: ids.length,
+              files: plan.rows.length,
+            }),
+          );
+        }
+      }
+    // One complete coverage check, then per-batch hashes. No loop that grows an authorization.
+    if (!activated)
+      for (const group of selection) {
+        async function* selectedPlans() {
+          for (const id of group.ids) yield await loadPlan(root, id);
+        }
+        await assertCompleteStorageCoverage(root, group.family, selectedPlans(), {
+          observationTail: true,
+        });
+        for (const id of group.ids)
+          await revalidateDurableStatePlan(root, await loadPlan(root, id));
+      }
+    if (!activated) await verifyRelatedPlans(root, selection, related);
+    if (!activated) {
+      await noActiveOwner(root, handoff);
+      await verifyGenerationSources(root, generation);
+      await verifyInstalledGeneration(root, generation, false);
+      await assertStorageRuntimeQuiescent(root);
+      await writeEvent({ type: "activation_started" });
+      try {
+        await replaceStorageGeneration(root, generation, "apply");
+        activated = true;
+      } catch (error) {
+        await replaceStorageGeneration(root, generation, "rollback");
+        await writeEvent({ type: "activation_rolled_back", originals_retained: true });
+        throw error;
+      }
+      await noActiveOwner(root, handoff);
+      await writeEvent({ type: "activated", generation: generation.id });
+    }
+    await verifyInstalledGeneration(root, generation);
+    // Old writers have stopped. Preserve observations emitted while copying, without
+    // admitting new grants/claims or altering the original immutable selection.
+    const tail = await sealObservationTail(root, generation, handoff, selection, {
+      required: deletionStarted,
+    });
+    selection = tail.selection;
+    if (!deletionStarted) {
+      for (const id of tail.ids) await copyPlan(await loadPlan(root, id));
+      for (const group of selection) {
+        async function* completePlans() {
+          for (const id of group.ids) yield await loadPlan(root, id);
+        }
+        await assertCompleteStorageCoverage(root, group.family, completePlans());
+      }
+      await verifyRelatedPlans(root, selection, related);
+      await writeEvent({ type: "observation_tail_prepared", ids: tail.ids });
+    }
+    for (const id of related)
+      await publishPlanReceipt(root, await loadPlan(root, id), generation, selector);
+    await writeEvent({ type: "deletion_started" });
+    deletionStarted = true;
+    for (const group of selection) {
+      for (const id of group.ids) {
+        const plan = await loadPlan(root, id);
+        await verifyInstalledGeneration(root, generation);
+        await publishPlanReceipt(root, plan, generation, selector);
+        for (const row of plan.rows) {
+          const exists = await optional(await physical(root, row.source, true));
+          if (exists)
+            assert.equal(
+              (await hashFile(root, row.source)).sha256,
+              row.sha256,
+              "Concurrent legacy write after activation",
+            );
+          assert.equal(
+            (await hashFile(root, row.destination)).sha256,
+            row.sha256,
+            "Concurrent durable write after activation",
+          );
+          if (exists) await unlink(await physical(root, row.source));
+        }
+        await writeEvent({ type: "finalized", id });
+      }
+      await pruneEmpty(root, selectedFamily(group.family).from);
+    }
+    await verifyInstalledGeneration(root, generation);
+    const result = {
+      status: "operational_cutover_verified",
+      generation: generation.id,
+      selection,
+      task_id: handoff.task_id,
+      run_id: handoff.run_id,
+      archive_pending: [...archiveFamilies],
+      publication: false,
+    };
+    await exclusiveJson(
+      root,
+      `.agents/state/storage-migrations/cutover-${generation.id}.json`,
+      result,
+    );
+    const archive = await organizeLegacyStorage(handoff, generation);
+    await writeEvent({ type: "completed" });
+    return { ...result, archive_pending: [], archive };
+  } catch (error) {
+    await writeEvent({
+      type: "interrupted",
+      activated,
+      deletion_started: deletionStarted,
+      reason: error.message,
+    });
+    // Never roll back counters/receipts or silently remove ownership after a partial finalization.
+    throw error;
+  } finally {
+    await journal?.close();
+    await lock.close();
+    const current = await lstat(lockPath);
+    if (current.dev === identity.dev && current.ino === identity.ino) await unlink(lockPath);
+  }
+}

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

@@ -0,0 +1,109 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { privatePermissions } from "./durable-state-permissions.mjs";
+
+const checkedPrivateRoots = new Set();
+export const clearPrivatePermissionChecks = (root) => checkedPrivateRoots.delete(root);
+
+export const digest = (value) => createHash("sha256").update(value).digest("hex");
+const same = (a, b) =>
+  process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+
+/** Check every physical ancestor; paths supplied by a plan never grant access. */
+export async function physical(root, name, missing = false) {
+  if (
+    typeof name !== "string" ||
+    /[\\:]/.test(name) ||
+    [...name].some((character) => character.charCodeAt(0) < 32) ||
+    name.split("/").some((part) => !part || part === "." || part === "..")
+  ) {
+    throw new Error("Invalid durable state path");
+  }
+  const target = resolve(root, name);
+  const rel = relative(root, target);
+  if (!rel || rel.startsWith("..") || isAbsolute(rel)) throw new Error("State path escaped root");
+  const rootInfo = await lstat(root);
+  if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink() || !same(await realpath(root), root))
+    throw new Error("State migration refuses linked roots");
+  // realpath resolves the complete ancestor chain. Checking the final resolved
+  // path avoids resolving every ancestor again for every small receipt file.
+  // For creation, validate the closest existing parent before returning a name.
+  let cursor = target;
+  while (true) {
+    let info;
+    try {
+      info = await lstat(cursor);
+    } catch (error) {
+      if (missing && error.code === "ENOENT" && cursor !== root) {
+        cursor = dirname(cursor);
+        continue;
+      }
+      throw error;
+    }
+    if (
+      info.isSymbolicLink() ||
+      !same(await realpath(cursor), cursor) ||
+      (info.isFile() && info.nlink !== 1)
+    ) {
+      throw new Error("State migration refuses links, aliases and hardlinks");
+    }
+    if (cursor !== target && !info.isDirectory()) throw new Error("Non-directory state ancestor");
+    break;
+  }
+  return target;
+}
+
+export async function directory(root, name) {
+  try {
+    const path = await physical(root, name);
+    if (!(await lstat(path)).isDirectory()) throw new Error("Invalid state directory");
+    if (
+      (name === ".agents/private" || name.startsWith(".agents/private/")) &&
+      !checkedPrivateRoots.has(root)
+    ) {
+      await privatePermissions(root, [".agents/private"]);
+      checkedPrivateRoots.add(root);
+    }
+    return;
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  let current = "";
+  for (const part of name.split("/")) {
+    current = current ? `${current}/${part}` : part;
+    await physical(root, current, true);
+    let created = false;
+    try {
+      await mkdir(resolve(root, current), { mode: 0o700 });
+      created = true;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+    }
+    if (!(await lstat(await physical(root, current))).isDirectory())
+      throw new Error("Invalid state directory");
+    if (current === ".agents/private" && !checkedPrivateRoots.has(root)) {
+      await privatePermissions(root, [current], created ? "protect" : "verify");
+      checkedPrivateRoots.add(root);
+    }
+  }
+}
+
+export async function hashFile(root, name) {
+  const path = await physical(root, name);
+  const before = await lstat(path);
+  if (!before.isFile()) throw new Error("State migration requires a regular file");
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(path)) hash.update(chunk);
+  const after = await lstat(await physical(root, name));
+  if (
+    before.dev !== after.dev ||
+    before.ino !== after.ino ||
+    before.size !== after.size ||
+    before.mtimeMs !== after.mtimeMs
+  ) {
+    throw new Error("State changed during hashing");
+  }
+  return { sha256: hash.digest("hex"), bytes: after.size };
+}