@zaip-ai/cli 6.3.0 → 7.6.0

package/templates/.agents/skills/zaip-skill-worktree-recovery/scripts/durable-local-archive.mjs

@@ -0,0 +1,162 @@
+import assert from "node:assert/strict";
+import { lstat, readdir, readFile, realpath, rename, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { execute } from "../../../tools/cloud-runner-process.mjs";
+import { assertArchiveGitSafe } from "./durable-local-git.mjs";
+import { digest, directory, hashFile, physical } from "./durable-state-files.mjs";
+import {
+  assertStorageRuntimeQuiescent,
+  verifyInstalledGeneration,
+} from "./durable-state-generation.mjs";
+import { STATE_MAPPINGS } from "./durable-state-layout.mjs";
+import { exclusiveJson } from "./durable-state-migration.mjs";
+import { noActiveOwner, optional } from "./durable-state-plan.mjs";
+
+const archiveRoot = ".agents/private/state/local-legacy";
+const indexPath = `${archiveRoot}/index.json`;
+export async function planLocalArchive(root) {
+  const git = await execute("git", ["worktree", "list", "--porcelain", "-z"], {
+    cwd: root,
+    timeout: 15000,
+    maxOutput: 1048576,
+  });
+  assert.equal(git.code, 0, "Registered Git trees must be inspected before archival");
+  const local = resolve(root, ".local").toLowerCase();
+  for (const field of git.stdout.split("\0"))
+    if (field.startsWith("worktree ")) {
+      const path = resolve(field.slice(9)).toLowerCase();
+      assert(
+        path !== local && !path.startsWith(`${local}\\`) && !path.startsWith(`${local}/`),
+        "Registered Git worktree requires canonical Git relocation",
+      );
+    }
+  const rows = [];
+  for (const name of (await readdir(await physical(root, ".local"))).sort()) {
+    const source = `.local/${name}`,
+      path = await physical(root, source),
+      info = await lstat(path);
+    assert(
+      info.isDirectory() || info.isFile(),
+      "Unsupported top-level legacy entry must be preserved in place",
+    );
+    const mapping = STATE_MAPPINGS.find((entry) => entry.from === source);
+    if (info.isDirectory()) await assertArchiveGitSafe(root, source);
+    let destination =
+      mapping?.to ?? `${archiveRoot}/${info.isFile() ? "files" : "directories"}/${name}`;
+    if (source === ".local/hooks" && (await optional(resolve(root, destination)))) {
+      assert.deepEqual(
+        await readdir(path),
+        ["activation"],
+        "Unexpected unmigrated hook authority remains",
+      );
+      destination = `${archiveRoot}/directories/hooks`;
+    }
+    assert(
+      !(await optional(resolve(root, destination))),
+      "Archive destination exists; inspect its journal instead of overwriting",
+    );
+    rows.push({
+      source,
+      destination,
+      kind: info.isFile() ? "file" : "directory",
+      dev: info.dev,
+      ino: info.ino,
+      ...(info.isFile()
+        ? await hashFile(root, source)
+        : { contents: "opaque-preserved-by-atomic-rename" }),
+    });
+  }
+  const body = { schema_version: 1, root, rows };
+  assert(rows.length <= 20000, "Archive index exceeds supported reader bound");
+  return { ...body, id: digest(JSON.stringify(body)) };
+}
+/** Opaque retention, never a cleanup policy or a grant to execute archived content. */
+export async function organizeLegacyStorage(handoff, generation) {
+  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 noActiveOwner(root, handoff);
+  await verifyInstalledGeneration(root, generation);
+  await assertStorageRuntimeQuiescent(root);
+  await directory(root, archiveRoot);
+  let plan;
+  if (await optional(await physical(root, indexPath, true))) {
+    const path = await physical(root, indexPath);
+    assert((await lstat(path)).size <= 8 * 1024 * 1024);
+    plan = JSON.parse(await readFile(path, "utf8"));
+    const { id, ...body } = plan;
+    assert.equal(id, digest(JSON.stringify(body)), "Archive plan changed");
+    assert.equal(plan.root, root);
+  } else plan = await planLocalArchive(root);
+  await exclusiveJson(root, `${archiveRoot}/plan-${plan.id}.json`, plan);
+  // Readers can recover moved entries even if the process stops after any rename.
+  await exclusiveJson(root, indexPath, plan);
+  await exclusiveJson(root, ".agents/state/storage-migrations/local-archive.json", {
+    schema_version: 1,
+    id: plan.id,
+    manifest_sha256: digest(JSON.stringify(plan)),
+    entries: plan.rows.length,
+    classified_disposable: false,
+    generation: generation.id,
+  });
+  const completedPath = `${archiveRoot}/completed-${plan.id}.json`;
+  const completed = await optional(await physical(root, completedPath, true));
+  // Atomic same-volume renames preserve file identities and original ACLs; no links are followed.
+  for (const row of plan.rows) {
+    await directory(root, dirname(row.destination).replaceAll("\\", "/"));
+    const source = await physical(root, row.source, true),
+      destination = await physical(root, row.destination, true);
+    const exists = completed ? undefined : await optional(source);
+    const before = exists ?? (await lstat(await physical(root, row.destination)));
+    assert(
+      before.dev === row.dev && before.ino === row.ino,
+      "Archive source changed since inventory",
+    );
+    if (exists) {
+      assert(!(await optional(destination)), "Archive destination appeared concurrently");
+      if (row.kind === "file") assert.equal((await hashFile(root, row.source)).sha256, row.sha256);
+      await rename(source, destination);
+    }
+    const after = await lstat(await physical(root, row.destination));
+    assert(
+      after.dev === row.dev && after.ino === row.ino,
+      "Archive did not retain physical identity",
+    );
+    if (row.kind === "file")
+      assert.equal((await hashFile(root, row.destination)).sha256, row.sha256);
+    await exclusiveJson(root, `${archiveRoot}/moves/${digest(row.source)}.json`, {
+      plan: plan.id,
+      ...row,
+    });
+  }
+  await exclusiveJson(root, indexPath, plan);
+  await exclusiveJson(root, ".agents/state/storage-migrations/local-archive.json", {
+    schema_version: 1,
+    id: plan.id,
+    manifest_sha256: digest(JSON.stringify(plan)),
+    entries: plan.rows.length,
+    classified_disposable: false,
+    generation: generation.id,
+  });
+  await exclusiveJson(root, completedPath, { id: plan.id, entries: plan.rows.length });
+  for (const folder of ["temp", "cache", "sqlite"]) await directory(root, `.local/${folder}`);
+  const readme =
+    "# Arquivos locais reconstruíveis\n\n- `temp/`: trabalho temporário próprio; limpar só após encerrar seus processos.\n- `cache/`: caches reconstruíveis.\n- `sqlite/`: projeções do dashboard; fechar o dashboard antes de limpar.\n\nEstado indispensável: `.agents/records`, `.agents/state` e `.agents/private/state`.\nO legado foi preservado em `.agents/private/state/local-legacy`, com inventário de movimentação.\nNão arquivar credenciais, provas únicas ou controles de execução nesta pasta.\n";
+  const readmePath = await physical(root, ".local/README.md", true);
+  if (await optional(readmePath)) assert.equal(await readFile(readmePath, "utf8"), readme);
+  else await writeFile(readmePath, readme, { flag: "wx" });
+  await exclusiveJson(root, `${archiveRoot}/completed-${plan.id}.json`, {
+    id: plan.id,
+    entries: plan.rows.length,
+  });
+  return {
+    status: "organized_and_preserved",
+    entries: plan.rows.length,
+    id: plan.id,
+    local: ["README.md", "temp", "cache", "sqlite"],
+    legacy_disposable: false,
+  };
+}

package/templates/.agents/skills/zaip-skill-worktree-recovery/scripts/durable-local-git.mjs

@@ -0,0 +1,111 @@
+import assert from "node:assert/strict";
+import { lstat, readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { execute } from "../../../tools/cloud-runner-process.mjs";
+import { physical } from "./durable-state-files.mjs";
+import { optional } from "./durable-state-plan.mjs";
+
+async function registrations(root, gitDir) {
+  const result = await execute(
+    "git",
+    ["--git-dir", gitDir, "worktree", "list", "--porcelain", "-z"],
+    { cwd: root, timeout: 15000, maxOutput: 1048576 },
+  );
+  assert.equal(result.code, 0, "Cannot inspect Git registration; retain tree");
+  return result.stdout
+    .split("\0")
+    .filter((field) => field.startsWith("worktree "))
+    .map((field) => resolve(field.slice(9)));
+}
+async function checkGitFile(root, name) {
+  const file = await physical(root, name),
+    info = await lstat(file);
+  assert(info.size <= 65536, "Oversized Git marker");
+  const match = /^gitdir: ([^\r\n]+)\r?\n?$/.exec(await readFile(file, "utf8"));
+  assert(match, "Invalid Git marker; retain tree");
+  const gitDir = resolve(dirname(file), match[1]);
+  if (!(await optional(gitDir))) return; // Preserved orphan, never repaired or executed.
+  const commonMarker = resolve(gitDir, "commondir");
+  const common = await optional(commonMarker);
+  if (common)
+    assert(
+      common.isFile() && !common.isSymbolicLink() && common.size <= 65536,
+      "Unsafe Git common-dir marker",
+    );
+  const commonDir = common
+    ? resolve(gitDir, (await readFile(commonMarker, "utf8")).trim())
+    : gitDir;
+  const checkout = dirname(file).toLowerCase();
+  assert(
+    !(await registrations(root, commonDir)).some((path) => path.toLowerCase() === checkout),
+    `Registered Git worktree requires canonical Git relocation: ${name}`,
+  );
+}
+
+/** Inspect metadata without traversing links or Git object stores. A foreign
+ * linked checkout cannot be relocated by an opaque filesystem rename. */
+export async function assertArchiveGitSafe(root, name) {
+  await physical(root, name);
+  // rg enumerates names natively without following directory links or opening
+  // vendor files. Bound metadata output, rather than the number of vendor dirs.
+  const result = await execute(
+    "rg",
+    [
+      "--files",
+      "--hidden",
+      "--no-ignore",
+      "--null",
+      "-g",
+      ".git",
+      "-g",
+      "**/.git/config",
+      "-g",
+      "**/.git/HEAD",
+      "-g",
+      "**/.git/commondir",
+      name,
+    ],
+    { cwd: root, timeout: 600000, maxOutput: 16 * 1024 * 1024 },
+  );
+  assert(
+    !result.timedOut && !result.overflow && [0, 1].includes(result.code) && !result.stderr.trim(),
+    "Git metadata inventory incomplete; retain tree",
+  );
+  const markers = new Set();
+  for (const raw of result.stdout.split("\0").filter(Boolean)) {
+    const path = raw.replaceAll("\\", "/");
+    assert(path.startsWith(`${name}/`), "Git inventory escaped archive scope");
+    const index = path.lastIndexOf("/.git");
+    assert(index >= 0);
+    markers.add(path.slice(0, index + 5));
+  }
+  for (const child of markers) {
+    const entry = await lstat(await physical(root, child));
+    if (entry.isFile()) {
+      await checkGitFile(root, child);
+      continue;
+    }
+    assert(entry.isDirectory(), "Unsupported Git metadata");
+    const git = await physical(root, child);
+    assert(
+      !(await optional(resolve(git, "commondir"))),
+      "Git common directory alias; preserve in place",
+    );
+    if (await optional(resolve(git, "worktrees"))) {
+      const checkout = dirname(git).toLowerCase();
+      for (const path of await registrations(root, git))
+        if (path.toLowerCase() !== checkout && (await optional(path)))
+          throw new Error(`Git common directory has live linked worktrees: ${child}`);
+    }
+    const config = await optional(resolve(git, "config"));
+    if (config) {
+      assert(config.size <= 1048576, "Oversized Git configuration");
+      assert(
+        !/^\s*(?:worktree|worktreeConfig)\s*=/im.test(
+          await readFile(await physical(root, `${child}/config`), "utf8"),
+        ),
+        "Git has an explicit worktree configuration; canonical relocation required",
+      );
+    }
+  }
+}

package/templates/.agents/skills/zaip-skill-worktree-recovery/scripts/durable-state-acl.ps1

@@ -0,0 +1,37 @@
+param([ValidateSet('protect', 'verify')][string]$Operation)
+$ErrorActionPreference = 'Stop'
+$inputText = [Console]::In.ReadToEnd()
+if ($inputText.Length -gt 8388608) { throw 'Private state ACL input exceeds bound' }
+$request = $inputText | ConvertFrom-Json
+$root = [System.IO.Path]::GetFullPath($request.root)
+$privateRoot = [System.IO.Path]::Combine($root, '.agents', 'private')
+$sid = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+if ($request.paths.Count -gt 50000) { throw 'Private state ACL path bound exceeded' }
+foreach ($relative in $request.paths) {
+  $path = [System.IO.Path]::GetFullPath([System.IO.Path]::Combine($root, $relative))
+  if ($path -ne $privateRoot -and -not $path.StartsWith($privateRoot + '\', [System.StringComparison]::OrdinalIgnoreCase)) { throw 'Private state ACL path escaped root' }
+  $entry = Get-Item -LiteralPath $path -Force
+  if (($entry.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0) { throw 'Private state ACL refuses reparse points' }
+  $acl = Get-Acl -LiteralPath $path
+  if ($acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $sid.Value) { throw 'Private state owner differs' }
+  if ($Operation -eq 'protect') {
+    if ($entry.PSIsContainer) {
+      $replacement = New-Object System.Security.AccessControl.DirectorySecurity
+      $inheritance = 'ContainerInherit,ObjectInherit'
+    } else {
+      $replacement = New-Object System.Security.AccessControl.FileSecurity
+      $inheritance = 'None'
+    }
+    $replacement.SetOwner($sid)
+    $replacement.SetAccessRuleProtection($true, $false)
+    $rule = New-Object System.Security.AccessControl.FileSystemAccessRule($sid, 'FullControl', $inheritance, 'None', 'Allow')
+    $replacement.AddAccessRule($rule)
+    Set-Acl -LiteralPath $path -AclObject $replacement
+    $acl = Get-Acl -LiteralPath $path
+  }
+  foreach ($rule in $acl.Access) {
+    $identity = $rule.IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value
+    if ($rule.AccessControlType -eq 'Allow' -and $identity -notin @($sid.Value, 'S-1-5-18', 'S-1-5-32-544')) { throw 'Private state DACL permits another identity' }
+  }
+}
+[Console]::Out.WriteLine('private_state_acl_verified')

package/templates/.agents/skills/zaip-skill-worktree-recovery/scripts/durable-state-activate.ps1

@@ -0,0 +1,66 @@
+param([ValidateSet('apply','rollback')][string]$Operation = 'apply')
+$ErrorActionPreference = 'Stop'
+$request = [Console]::In.ReadToEnd() | ConvertFrom-Json
+$root = [IO.Path]::GetFullPath($request.root)
+if ($request.id -notmatch '^[a-f0-9]{64}$' -or $request.files.Count -gt 128) { throw 'Invalid generation' }
+$backupRoot = '.agents/private/state/storage-cutover/activations/' + $request.id
+function Checked([string]$name, [bool]$allowMissing = $false) {
+  if ($name -match '(^|/)\.\.(/|$)|[\\:]' -or [IO.Path]::IsPathRooted($name)) { throw 'Invalid generation path' }
+  $path = [IO.Path]::GetFullPath([IO.Path]::Combine($root,$name))
+  if (!$path.StartsWith($root + '\',[StringComparison]::OrdinalIgnoreCase)) { throw 'Generation escaped root' }
+  $cursor = $root
+  foreach ($part in $name.Split('/')) {
+    $cursor = [IO.Path]::Combine($cursor,$part)
+    if (!(Test-Path -LiteralPath $cursor)) { if ($allowMissing) { return $path }; throw 'Missing generation path' }
+    if ((Get-Item -LiteralPath $cursor -Force).Attributes -band [IO.FileAttributes]::ReparsePoint) { throw 'Linked generation path' }
+  }
+  return $path
+}
+foreach ($entry in $request.files) {
+  if ($entry.path -notmatch '^\.agents/runtime/[A-Za-z0-9./_-]+$|^\.codex/hooks/zaip-[a-z0-9-]+\.mjs$|^\.codex/config\.toml$' -or $entry.sha256 -notmatch '^[a-f0-9]{64}$') { throw 'Generation target is not an installed runtime or hook' }
+  $target = Checked $entry.path $true
+  $backup = Checked ($backupRoot + '/' + $entry.path) $true
+  if ($Operation -eq 'rollback') {
+    if (!(Test-Path -LiteralPath $target)) { if ($null -eq $entry.before_sha256) { continue }; throw 'Rollback target missing' }
+    $currentHash = (Get-FileHash -LiteralPath $target -Algorithm SHA256).Hash.ToLower()
+    if ($currentHash -eq $entry.before_sha256) { continue }
+    if ($currentHash -ne $entry.sha256) { throw 'Rollback target changed concurrently' }
+    if ($null -eq $entry.before_sha256) { [IO.File]::Delete($target); continue }
+    if ((Get-FileHash -LiteralPath (Checked ($backupRoot + '/' + $entry.path)) -Algorithm SHA256).Hash.ToLower() -ne $entry.before_sha256) { throw 'Rollback backup differs' }
+    $source = $backup
+    $expected = $entry.before_sha256
+  } else {
+    if (Test-Path -LiteralPath $backup) {
+      if ($null -eq $entry.before_sha256 -or (Get-FileHash -LiteralPath $backup -Algorithm SHA256).Hash.ToLower() -ne $entry.before_sha256) { throw 'Generation backup differs' }
+    }
+    if ($entry.staged -notmatch '^\.agents/private/state/storage-cutover/staging/[a-f0-9-]+/') { throw 'Unexpected staged generation' }
+    $source = Checked $entry.staged
+    $expected = $entry.sha256
+    if ((Get-FileHash -LiteralPath $source -Algorithm SHA256).Hash.ToLower() -ne $expected) { throw 'Staged generation differs' }
+    if ((Test-Path -LiteralPath $target) -and (Get-FileHash -LiteralPath $target -Algorithm SHA256).Hash.ToLower() -eq $expected) {
+      if ($entry.before_sha256 -eq $entry.sha256) { continue }
+      if ($null -ne $entry.before_sha256 -and !(Test-Path -LiteralPath $backup)) { throw 'Applied generation has no before-image' }
+      continue
+    }
+    if ($null -eq $entry.before_sha256) {
+      if (Test-Path -LiteralPath $target) { throw 'Unexpected existing generation target' }
+    } elseif ((Get-FileHash -LiteralPath (Checked $entry.path) -Algorithm SHA256).Hash.ToLower() -ne $entry.before_sha256) { throw 'Installed generation changed' }
+  }
+  $temporary = $target + '.storage-' + [Guid]::NewGuid().ToString('N')
+  $bytes = [IO.File]::ReadAllBytes($source)
+  $stream = [IO.File]::Open($temporary,[IO.FileMode]::CreateNew,[IO.FileAccess]::Write,[IO.FileShare]::None)
+  try { $stream.Write($bytes,0,$bytes.Length); $stream.Flush($true) } finally { $stream.Dispose() }
+  if (Test-Path -LiteralPath $target) {
+    $acl = (Get-Acl -LiteralPath $target).Sddl
+    $replaceBackup = $backup
+    if ($Operation -eq 'apply' -and (Test-Path -LiteralPath $backup)) { $replaceBackup = $backup + '.reapply-' + [Guid]::NewGuid().ToString('N') }
+    if ($Operation -eq 'rollback') {
+      $replaceBackup = $backup + '.rolled-back-candidate'
+      if (Test-Path -LiteralPath $replaceBackup) { throw 'Rollback candidate backup already exists' }
+    }
+    [IO.File]::Replace($temporary,$target,$replaceBackup,$false)
+    if ((Get-Acl -LiteralPath $target).Sddl -ne $acl) { throw 'Installed generation ACL changed' }
+  } else { [IO.File]::Move($temporary,$target) }
+  if ((Get-FileHash -LiteralPath $target -Algorithm SHA256).Hash.ToLower() -ne $expected) { throw 'Generation activation verification failed' }
+}
+[Console]::Out.WriteLine('storage_generation_' + $Operation + '_verified')

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

@@ -0,0 +1,202 @@
+import { randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { link, lstat, open, readFile, unlink } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { digest, directory, hashFile, physical } from "./durable-state-files.mjs";
+import { stateMapping } from "./durable-state-layout.mjs";
+import { checkedPlan } from "./durable-state-migration.mjs";
+import { privatePermissions } from "./durable-state-permissions.mjs";
+import { assertHistoricalTelemetryVersion } from "./durable-state-telemetry-version.mjs";
+
+async function publish(root, name, write, expectedHash, permissionCollector, readOnly) {
+  if (!readOnly) await directory(root, dirname(name).replaceAll("\\", "/"));
+  const target = await physical(root, name, !readOnly);
+  try {
+    await lstat(target);
+    if ((await hashFile(root, name)).sha256 !== expectedHash)
+      throw new Error("Historical artifact collision");
+    if (permissionCollector) permissionCollector.add(name);
+    else await privatePermissions(root, [name]);
+    return;
+  } catch (error) {
+    if (error.code !== "ENOENT" || readOnly) throw error;
+  }
+  const stage = `${name}.stage-${randomUUID()}`;
+  const handle = await open(resolve(root, stage), "wx", 0o600);
+  try {
+    await write(handle);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    if ((await hashFile(root, stage)).sha256 !== expectedHash)
+      throw new Error("Historical artifact staging differs");
+    try {
+      await link(resolve(root, stage), target);
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      if ((await hashFile(root, name)).sha256 !== expectedHash)
+        throw new Error("Historical artifact collision");
+    }
+  } finally {
+    await unlink(resolve(root, stage));
+  }
+  if (permissionCollector) permissionCollector.add(name);
+  else await privatePermissions(root, [name]);
+}
+
+async function publishAliasRow(
+  root,
+  row,
+  transaction,
+  permissionCollector,
+  previousPlans,
+  readOnly,
+) {
+  if (permissionCollector !== undefined && !(permissionCollector instanceof Set))
+    throw new Error("Invalid internal permission collector");
+  if (!/^[a-f0-9]{64}$/.test(transaction) || !/^[a-f0-9]{64}$/.test(row.sha256))
+    throw new Error("Invalid alias identity");
+  const mapping = stateMapping(row.source);
+  if (mapping.destination !== row.destination) throw new Error("Alias mapping differs");
+  const aliasPath = `.agents/private/state/storage-migrations/aliases/${digest(row.source)}.json`;
+  let historicalAlias;
+  try {
+    const path = await physical(root, aliasPath);
+    if ((await lstat(path)).size > 4096) throw new Error("Oversized existing alias");
+    const existing = JSON.parse(await readFile(path, "utf8"));
+    if (
+      existing.schema_version !== 1 ||
+      Object.keys(existing).sort().join() !==
+        "destination,schema_version,sha256,source,transaction" ||
+      existing.source !== row.source ||
+      existing.destination !== row.destination ||
+      !/^[a-f0-9]{64}$/.test(existing.sha256) ||
+      !/^[a-f0-9]{64}$/.test(existing.transaction)
+    )
+      throw new Error("Historical artifact collision");
+    if (!previousPlans.has(existing.transaction)) {
+      const planPath = await physical(
+        root,
+        `.agents/private/state/storage-migrations/${existing.transaction}.json`,
+      );
+      if ((await lstat(planPath)).size > 32 * 1024 * 1024)
+        throw new Error("Oversized previous alias plan");
+      const plan = checkedPlan(JSON.parse(await readFile(planPath, "utf8")));
+      if (plan.id !== existing.transaction) throw new Error("Previous alias transaction differs");
+      previousPlans.set(plan.id, new Map(plan.rows.map((member) => [member.source, member])));
+    }
+    const member = previousPlans.get(existing.transaction).get(row.source);
+    if (!member || member.sha256 !== existing.sha256 || member.destination !== row.destination)
+      throw new Error("Previous alias is outside its plan");
+    if (Object.keys(row).some((key) => member[key] !== row[key]))
+      await assertHistoricalTelemetryVersion(root, member, row);
+    transaction = existing.transaction;
+    historicalAlias = existing;
+    if (readOnly) {
+      const paths = [
+        `.agents/private/state/storage-migrations/${transaction}.json`,
+        `.agents/private/state/storage-migrations/artifacts/${existing.sha256}`,
+      ];
+      if (permissionCollector) for (const path of paths) permissionCollector.add(path);
+      else await privatePermissions(root, paths);
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT" || readOnly) throw error;
+  }
+  const blob = `.agents/private/state/storage-migrations/artifacts/${row.sha256}`;
+  const source = await physical(root, row.destination);
+  if ((await hashFile(root, row.destination)).sha256 !== row.sha256)
+    throw new Error("Alias source bytes changed");
+  await publish(
+    root,
+    blob,
+    async (handle) => {
+      for await (const chunk of createReadStream(source)) await handle.writeFile(chunk);
+    },
+    row.sha256,
+    permissionCollector,
+    readOnly,
+  );
+  const alias = historicalAlias ?? {
+    schema_version: 1,
+    source: row.source,
+    destination: row.destination,
+    sha256: row.sha256,
+    transaction,
+  };
+  const aliasText = `${JSON.stringify(alias)}\n`;
+  await publish(
+    root,
+    aliasPath,
+    (handle) => handle.writeFile(aliasText),
+    digest(aliasText),
+    permissionCollector,
+    readOnly,
+  );
+  return { source: row.source, sha256: alias.sha256, transaction };
+}
+
+/** Validate the physical immutable transaction once per batch, not once per row.
+ * This readonly publisher grants no activation or source-deletion capability.
+ */
+export async function createHistoricalAliasPublisher(root, input) {
+  const plan = checkedPlan(input);
+  const storedPath = await physical(
+    root,
+    `.agents/private/state/storage-migrations/${plan.id}.json`,
+  );
+  if ((await lstat(storedPath)).size > 32 * 1024 * 1024) throw new Error("Oversized alias plan");
+  const stored = checkedPlan(JSON.parse(await readFile(storedPath, "utf8")));
+  if (JSON.stringify(stored) !== JSON.stringify(plan))
+    throw new Error("Alias transaction differs from the selected plan");
+  const transaction = plan.id;
+  const members = new Map(stored.rows.map((row) => [row.source, Object.freeze({ ...row })]));
+  const previousPlans = new Map([[plan.id, members]]);
+  function memberFor(row) {
+    const member = members.get(row?.source);
+    if (
+      !member ||
+      Object.keys(row).length !== 5 ||
+      Object.keys(member).some((key) => member[key] !== row[key])
+    )
+      throw new Error("Alias is outside the migration transaction");
+    return member;
+  }
+  return Object.freeze({
+    async publish(row, permissionCollector) {
+      return publishAliasRow(
+        root,
+        memberFor(row),
+        transaction,
+        permissionCollector,
+        previousPlans,
+        false,
+      );
+    },
+    async verify(row, permissionCollector) {
+      return publishAliasRow(
+        root,
+        memberFor(row),
+        transaction,
+        permissionCollector,
+        previousPlans,
+        true,
+      );
+    },
+  });
+}
+
+/** Compatibility entry point. Batch callers should reuse createHistoricalAliasPublisher. */
+export async function publishHistoricalStateAlias(root, row, transaction, permissionCollector) {
+  if (!/^[a-f0-9]{64}$/.test(transaction)) throw new Error("Invalid alias identity");
+  const plan = JSON.parse(
+    await readFile(
+      await physical(root, `.agents/private/state/storage-migrations/${transaction}.json`),
+      "utf8",
+    ),
+  );
+  if (plan.id !== transaction) throw new Error("Alias transaction differs");
+  return (await createHistoricalAliasPublisher(root, plan)).publish(row, permissionCollector);
+}

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

@@ -0,0 +1,88 @@
+import { lstat, opendir, realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import { digest, physical } from "./durable-state-files.mjs";
+import { selectedFamily, stateMapping } from "./durable-state-layout.mjs";
+import { durableStateRow, optional } from "./durable-state-plan.mjs";
+import { assertInactiveReceiptLease } from "./durable-state-receipt-lease.mjs";
+
+function checkedSize(size) {
+  if (!Number.isSafeInteger(size) || size < 1 || size > 5000)
+    throw new Error("Invalid state migration batch size");
+}
+
+/** Pure bounded partitioner: no filesystem access and no authority semantics. */
+export async function* partitionDurableRows(rows, batchSize = 5000) {
+  checkedSize(batchSize);
+  let page = [];
+  for await (const row of rows) {
+    page.push(row);
+    if (page.length === batchSize) {
+      yield page;
+      page = [];
+    }
+  }
+  if (page.length) yield page;
+}
+
+/** Streaming names, including physical checks; never retain a whole directory listing. */
+export async function* durableStateSources(root, name, familyFrom) {
+  // Activation observations are overwritten by each host tool. Preserve their
+  // final directory after switching writers, separately from immutable state.
+  if (familyFrom === ".local/hooks" && name === ".local/hooks/activation") return;
+  if (stateMapping(name).from !== familyFrom) return;
+  const path = await physical(root, name);
+  const info = await lstat(path);
+  if (/\.(?:lock|execution-lease)$/.test(name)) await assertInactiveReceiptLease(root, name);
+  if (name.split("/").includes(".git"))
+    throw new Error("Registered worktrees require canonical Git relocation");
+  if (info.isDirectory()) {
+    const directory = await opendir(path);
+    for await (const child of directory)
+      yield* durableStateSources(root, `${name}/${child.name}`, familyFrom);
+  } else if (info.isFile()) yield name;
+  else throw new Error("Unsupported state entry");
+}
+
+/** Explicit-source selectors are hashed, not a claim of a complete family snapshot.
+ * The native cutover coordinator must verify complete coverage under its barrier.
+ */
+export async function* planDurableStateBatches(workspace, family, { batchSize = 5000 } = {}) {
+  checkedSize(batchSize);
+  const root = await realpath(workspace);
+  const mapping = selectedFamily(family);
+  if (!(await optional(resolve(root, mapping.from)))) return;
+  async function* rows() {
+    for await (const source of durableStateSources(root, mapping.from, mapping.from))
+      yield await durableStateRow(root, source);
+  }
+  let index = 0;
+  let previous_id = null;
+  for await (const rowsPage of partitionDurableRows(rows(), batchSize)) {
+    const names = new Set(rowsPage.map((row) => row.source.toLowerCase()));
+    if (names.size !== rowsPage.length) throw new Error("Case-insensitive state collision");
+    const body = {
+      schema_version: 1,
+      family,
+      batch: { kind: "explicit-sources", index, batch_size: batchSize, previous_id },
+      rows: rowsPage,
+    };
+    const plan = { ...body, id: digest(JSON.stringify(body)) };
+    yield plan;
+    previous_id = plan.id;
+    index++;
+  }
+}
+
+export async function revalidateDurableStatePlan(root, plan) {
+  let cursor = 0;
+  // Independent reads only; no copying, receipt writes or source removal here.
+  await Promise.all(
+    Array.from({ length: Math.min(8, plan.rows.length) }, async () => {
+      while (cursor < plan.rows.length) {
+        const row = plan.rows[cursor++];
+        if (JSON.stringify(await durableStateRow(root, row.source)) !== JSON.stringify(row))
+          throw new Error("State selector changed after dry-run");
+      }
+    }),
+  );
+}