@zaip-ai/cli 6.2.0 → 7.5.0

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

@@ -0,0 +1,7 @@
+param([int]$OwnerProcess)
+$ErrorActionPreference='Stop'
+if($OwnerProcess -le 0) { throw 'Invalid receipt process' }
+$process=Get-Process -Id $OwnerProcess -ErrorAction SilentlyContinue
+if(!$process) { [Console]::Out.WriteLine('absent'); exit 0 }
+$started=$process.StartTime.ToUniversalTime()
+[Console]::Out.WriteLine(([DateTimeOffset]$started).ToUnixTimeMilliseconds())

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

@@ -0,0 +1,11 @@
+param([string]$WorkspaceRoot, [int]$OwnerProcess)
+$ErrorActionPreference = 'Stop'
+$root = [IO.Path]::GetFullPath($WorkspaceRoot)
+if (!(Test-Path -LiteralPath $root -PathType Container) -or $OwnerProcess -le 0) { throw 'Invalid quiescence scope' }
+$escaped = [Regex]::Escape($root)
+$conflicts = @(Get-CimInstance Win32_Process -Filter "Name = 'node.exe'" | Where-Object {
+  $_.ProcessId -ne $OwnerProcess -and
+  ($_.CommandLine.Replace('/','\') -match $escaped -or $_.CommandLine -match '(?:^|\s)"?(?:\.[/\\])?(?:\.agents[/\\]runtime|\.codex[/\\]hooks|scripts[/\\]local-catalog-(?:controller|executor))')
+} | Select-Object -ExpandProperty ProcessId)
+if ($conflicts.Count -gt 0) { throw ('Storage cutover has other possible runtime writers: ' + ($conflicts -join ',')) }
+[Console]::Out.WriteLine('storage_runtime_quiescent')

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

@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import { lstat, readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { execute } from "../../../tools/cloud-runner-process.mjs";
+import { digest, physical } from "./durable-state-files.mjs";
+
+const proofs = new Map();
+/** Preserve obsolete receipt lease bytes without replaying any historical event.
+ * Only this exact known lease format may be classified; unknown/live locks fail. */
+export async function assertInactiveReceiptLease(root, name) {
+  const match = /^\.local\/hooks\/subagent-pending\/([a-f0-9]{64})\.json\.lock$/.exec(name);
+  assert(match, `Active or unresolved state lease blocks migration: ${name}`);
+  const path = await physical(root, name),
+    info = await lstat(path);
+  assert(info.size <= 128, "Unexpected receipt lease size");
+  const text = await readFile(path, "utf8"),
+    owner = JSON.parse(text);
+  assert(
+    Object.keys(owner).join() === "pid" && Number.isSafeInteger(owner.pid) && owner.pid > 0,
+    "Unknown receipt lease owner",
+  );
+  const receiptPath = await physical(root, name.slice(0, -5));
+  assert((await lstat(receiptPath)).size <= 1048576, "Oversized receipt");
+  const receipt = JSON.parse(await readFile(receiptPath, "utf8"));
+  assert(
+    receipt.schema_version === 1 &&
+      typeof receipt.cli === "string" &&
+      Array.isArray(receipt.capture_arguments),
+    "Unknown pending receipt",
+  );
+  assert.equal(
+    digest(JSON.stringify({ cli: receipt.cli, arguments: receipt.capture_arguments })),
+    match[1],
+    "Pending receipt identity differs",
+  );
+  const key = `${root}/${name}/${info.ino}/${info.mtimeMs}/${text}`;
+  if (proofs.has(key)) return;
+  try {
+    process.kill(owner.pid, 0);
+  } catch (error) {
+    if (error.code === "ESRCH") {
+      proofs.set(key, true);
+      return;
+    }
+    throw error;
+  }
+  assert.equal(process.platform, "win32", "Live receipt PID requires platform identity proof");
+  const result = await execute(
+    "powershell.exe",
+    [
+      "-NoProfile",
+      "-NonInteractive",
+      "-File",
+      fileURLToPath(new URL("./durable-state-process-start.ps1", import.meta.url)),
+      "-OwnerProcess",
+      String(owner.pid),
+    ],
+    { timeout: 15000, maxOutput: 256 },
+  );
+  assert.equal(result.code, 0, "Receipt process identity unavailable");
+  const started = result.stdout.trim();
+  assert(
+    started === "absent" || (/^\d+$/.test(started) && Number(started) > info.mtimeMs + 2000),
+    `Active receipt writer prevents migration: ${name}`,
+  );
+  proofs.set(key, true);
+}

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

@@ -0,0 +1,68 @@
+import { realpath } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { createHistoricalAliasPublisher } from "./durable-state-alias.mjs";
+import { hashFile, physical } from "./durable-state-files.mjs";
+import { checkedPlan } from "./durable-state-migration.mjs";
+import { privatePermissions } from "./durable-state-permissions.mjs";
+
+/** Readonly reuse is not an activation grant. The coordinator still verifies
+ * coverage, quiescence, generation and native authority immediately before flip.
+ */
+export async function reusePreparedState(workspace, input, handoff) {
+  const root = await realpath(workspace);
+  const authority = await import(
+    pathToFileURL(await physical(root, ".agents/private/state/storage-cutover/runtime/zaip.mjs"))
+      .href
+  );
+  authority.assertStorageHandoffCapability(handoff);
+  if ((await realpath(handoff.root)) !== root)
+    throw new Error("Storage reuse capability root differs");
+  const plan = checkedPlan(input);
+  // Protect verification from caller mutation while the bounded read workers await IO.
+  const selected = checkedPlan(structuredClone(plan));
+  const permissions = new Set([
+    ".agents/private",
+    `.agents/private/state/storage-migrations/${selected.id}.json`,
+  ]);
+  const related = new Set();
+  let index = 0;
+  const missing = new Set();
+  const failures = [];
+  let publisher;
+  try {
+    publisher = await createHistoricalAliasPublisher(root, selected);
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return { related: [], missing: selected.rows.map((row) => row.source) };
+    throw error;
+  }
+  async function worker() {
+    while (index < selected.rows.length) {
+      const row = selected.rows[index++];
+      try {
+        const rowPermissions = new Set();
+        for (const name of [row.source, row.destination]) {
+          const identity = await hashFile(root, name);
+          if (identity.sha256 !== row.sha256 || identity.bytes !== row.bytes)
+            throw new Error("Prepared storage reuse bytes differ");
+        }
+        rowPermissions.add(row.destination);
+        const alias = await publisher.verify(row, rowPermissions);
+        for (const path of rowPermissions) permissions.add(path);
+        related.add(alias.transaction);
+      } catch (error) {
+        if (error.code === "ENOENT") missing.add(row.source);
+        else failures.push(error);
+      }
+    }
+  }
+  const completed = await Promise.allSettled(
+    Array.from({ length: Math.min(8, selected.rows.length) }, worker),
+  );
+  for (const result of completed) if (result.status === "rejected") failures.push(result.reason);
+  // Missing work must never hide another row's corruption or a permission failure.
+  if (failures.length) throw failures[0];
+  await privatePermissions(root, [...permissions]);
+  authority.assertStorageHandoffCapability(handoff);
+  return { related: [...related].sort(), missing: [...missing].sort() };
+}

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

@@ -0,0 +1,187 @@
+import assert from "node:assert/strict";
+import { lstat, readFile, rename } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { digest, directory, hashFile, physical } from "./durable-state-files.mjs";
+import { loadStoragePlan } from "./durable-state-journal.mjs";
+import { exclusiveJson } from "./durable-state-migration.mjs";
+import { optional } from "./durable-state-plan.mjs";
+
+/** Only non-authorizing telemetry transitions may supersede a prepared copy. */
+export function assertTelemetryVersion(source, before, after) {
+  assert(
+    Buffer.byteLength(before) <= 4 * 1024 * 1024 && Buffer.byteLength(after) <= 4 * 1024 * 1024,
+  );
+  if (source === ".local/hooks/observations/replay-cursor.txt") {
+    assert(
+      [before, after].every((text) => /^[a-f0-9]{64}\.json\s*$/.test(text)),
+      "Invalid telemetry cursor",
+    );
+    return;
+  }
+  if (source === ".local/hooks/subagent-lifecycle.ndjson") {
+    assert(
+      before.endsWith("\n") && after.endsWith("\n") && after.startsWith(before),
+      "Telemetry log must remain append-only",
+    );
+    const lines = after.slice(before.length).trimEnd().split("\n");
+    assert(lines.length <= 1000, "Telemetry append exceeds transition bound");
+    for (const line of lines) {
+      const row = JSON.parse(line);
+      assert(Object.keys(row).sort().join() === "code,detail,occurred_at,source");
+      assert(row.source === "zaip-subagent-lifecycle-runner");
+      assert(typeof row.code === "string" && row.code.length <= 200);
+      assert(typeof row.occurred_at === "string" && Number.isFinite(Date.parse(row.occurred_at)));
+      assert(
+        row.detail !== null &&
+          (typeof row.detail === "string" ||
+            (typeof row.detail === "object" && !Array.isArray(row.detail))),
+      );
+      assert(Buffer.byteLength(JSON.stringify(row.detail)) <= 4096, "Oversized telemetry detail");
+    }
+    return;
+  }
+  const match = /^\.local\/hooks\/observations\/([a-f0-9]{64})\.json$/.exec(source);
+  assert(match, "Changed state is not supported telemetry");
+  assert(Buffer.byteLength(before) <= 16384 && Buffer.byteLength(after) <= 16384);
+  const old = JSON.parse(before),
+    current = JSON.parse(after);
+  assert(old.schema_version === 1 && old.event_id === `HOBS-${match[1]}`);
+  assert(
+    old.state === "pending" && current.state === "persisted",
+    "Observation must advance pending to persisted",
+  );
+  assert(
+    old.run_id === undefined && /^RUN-[A-Z0-9-]+$/.test(current.run_id),
+    "Invalid persisted observation Run",
+  );
+  assert(
+    old.last_error === undefined ||
+      (typeof old.last_error === "string" &&
+        /^(observation_|native_child_|governed_run_)[a-z_]+$/.test(old.last_error)),
+    "Invalid sanitized observation error",
+  );
+  assert(current.last_error === undefined, "Persisted observation must clear its pending error");
+  const { state: oldState, run_id: oldRun, last_error: oldError, ...oldFacts } = old;
+  const { state: nextState, run_id: nextRun, ...nextFacts } = current;
+  assert.deepEqual(nextFacts, oldFacts, "Observation identity or facts changed");
+}
+
+async function boundedBytes(root, name) {
+  const path = await physical(root, name);
+  assert((await lstat(path)).size <= 4 * 1024 * 1024, "Oversized telemetry version");
+  return readFile(path, "utf8");
+}
+
+/** Old signed locators retain their immutable blob; live state keeps its newer version. */
+export async function assertHistoricalTelemetryVersion(root, old, current) {
+  assert(
+    old.source === current.source &&
+      old.destination === current.destination &&
+      old.privacy === "private" &&
+      current.privacy === "private",
+  );
+  const before = await boundedBytes(
+    root,
+    `.agents/private/state/storage-migrations/artifacts/${old.sha256}`,
+  );
+  const after = await boundedBytes(root, current.destination);
+  assert.equal(digest(before), old.sha256);
+  assert.equal(digest(after), current.sha256);
+  assertTelemetryVersion(old.source, before, after);
+}
+
+/** Called only inside authenticated, quiescent preparation retirement, before activation. */
+export async function preservePreparedTelemetryVersion(
+  root,
+  row,
+  current,
+  handoff,
+  generation,
+  preparedPlanId,
+) {
+  const authority = await import(
+    pathToFileURL(resolve(root, ".agents/private/state/storage-cutover/runtime/zaip.mjs")).href
+  );
+  authority.assertStorageHandoffCapability(handoff);
+  assert(row.privacy === "private");
+  const prepared = await loadStoragePlan(root, preparedPlanId);
+  assert(
+    prepared.rows.some((member) => JSON.stringify(member) === JSON.stringify(row)),
+    "Prepared telemetry row is outside its plan",
+  );
+  const alias = JSON.parse(
+    await boundedBytes(
+      root,
+      `.agents/private/state/storage-migrations/aliases/${digest(row.source)}.json`,
+    ),
+  );
+  assert(
+    alias.source === row.source &&
+      alias.destination === row.destination &&
+      /^[a-f0-9]{64}$/.test(alias.sha256),
+  );
+  const historical = await loadStoragePlan(root, alias.transaction);
+  assert(
+    historical.rows.some(
+      (member) =>
+        member.source === row.source &&
+        member.destination === row.destination &&
+        member.sha256 === alias.sha256,
+    ),
+  );
+  const before = await boundedBytes(
+    root,
+    `.agents/private/state/storage-migrations/artifacts/${row.sha256}`,
+  );
+  const after = await boundedBytes(root, row.source);
+  assert.equal(digest(before), row.sha256);
+  assert.equal(digest(after), current.sha256);
+  if (alias.sha256 !== row.sha256) {
+    const earliest = await boundedBytes(
+      root,
+      `.agents/private/state/storage-migrations/artifacts/${alias.sha256}`,
+    );
+    assert.equal(digest(earliest), alias.sha256);
+    assertTelemetryVersion(row.source, earliest, before);
+  }
+  assertTelemetryVersion(row.source, before, after);
+  const base = ".agents/private/state/storage-cutover/telemetry-versions";
+  const saved = `${base}/before/${digest(row.source)}-${row.sha256}`;
+  const proof = {
+    schema_version: 1,
+    generation: generation.id,
+    task: handoff.task_id,
+    run: handoff.run_id,
+    source: row.source,
+    destination: row.destination,
+    before: row.sha256,
+    after: current.sha256,
+    historical_transaction: alias.transaction,
+    prepared_transaction: preparedPlanId,
+    preserved_copy: saved,
+  };
+  await exclusiveJson(root, `${base}/${digest(JSON.stringify(proof))}.json`, proof);
+  await directory(root, dirname(saved).replaceAll("\\", "/"));
+  const originalCopy = await physical(root, row.destination, true);
+  const savedPath = await physical(root, saved, true);
+  if (await optional(originalCopy)) {
+    assert.equal(
+      (await hashFile(root, row.destination)).sha256,
+      row.sha256,
+      "Prepared telemetry copy changed",
+    );
+    assert(!(await optional(savedPath)), "Duplicate prepared telemetry before-image");
+    await rename(originalCopy, savedPath);
+  }
+  assert.equal(
+    (await hashFile(root, saved)).sha256,
+    row.sha256,
+    "Prepared telemetry before-image differs",
+  );
+  assert.equal(
+    (await hashFile(root, row.source)).sha256,
+    current.sha256,
+    "Telemetry changed during recovery",
+  );
+}

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

@@ -0,0 +1,85 @@
+import assert from "node:assert/strict";
+import { execFileSync, spawn } from "node:child_process";
+
+export function assertGitEnvironment() {
+  for (const key of [
+    "GIT_DIR",
+    "GIT_WORK_TREE",
+    "GIT_COMMON_DIR",
+    "GIT_INDEX_FILE",
+    "GIT_OBJECT_DIRECTORY",
+    "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+  ])
+    assert(!process.env[key], `Git state override is forbidden: ${key}`);
+}
+
+/** Bound the observed process tree, including the Windows Git launcher and its children. */
+export function runProcess(root, command, args, timeout = 15000, env = process.env) {
+  assert(Number.isFinite(timeout) && timeout > 0 && timeout <= 120000, "Invalid command budget");
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: root,
+      env,
+      windowsHide: true,
+      detached: process.platform !== "win32",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "",
+      stderr = "",
+      failure = null,
+      settled = false;
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearTimeout(fallback);
+      error ? reject(error) : resolve(value);
+    };
+    let fallback;
+    const stop = (reason) => {
+      if (failure) return;
+      failure = new Error(reason);
+      if (child.exitCode === null && child.pid) {
+        try {
+          if (process.platform === "win32")
+            execFileSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], {
+              windowsHide: true,
+              timeout: 5000,
+              stdio: "ignore",
+            });
+          else process.kill(-child.pid, "SIGKILL");
+        } catch {
+          child.kill("SIGKILL");
+        }
+      }
+      fallback = setTimeout(() => {
+        child.stdout.destroy();
+        child.stderr.destroy();
+        child.unref();
+        finish(new Error(`${reason}; descendant termination unconfirmed; preserve partial output`));
+      }, 1000);
+    };
+    const timer = setTimeout(
+      () => stop("Recovery command deadline exceeded; no successful receipt"),
+      timeout,
+    );
+    child.stdout.on("data", (bytes) => {
+      stdout += bytes;
+      if (Buffer.byteLength(stdout) > 16 * 1024 * 1024) stop("Recovery output exceeds bound");
+    });
+    child.stderr.on("data", (bytes) => {
+      stderr = (stderr + bytes).slice(-4096);
+    });
+    child.once("error", (error) => finish(error));
+    child.once("close", (code) =>
+      finish(
+        failure ?? (code === 0 ? null : new Error(`Recovery command failed (${code}): ${stderr}`)),
+        stdout.trimEnd(),
+      ),
+    );
+  });
+}
+export function query(root, args, timeout = 15000) {
+  assertGitEnvironment();
+  return runProcess(root, "git", args, timeout, { ...process.env, GIT_OPTIONAL_LOCKS: "0" });
+}