@zaip-ai/cli 6.2.0 → 7.5.0

package/templates/.agents/tools/cloud-onboarding-configure.mjs

@@ -0,0 +1,146 @@
+import { fail, hash, inside, text } from "./cloud-onboarding-policy.mjs";
+import { sshTransport } from "./cloud-onboarding-ssh.mjs";
+
+// This is a material detector, not authorization to read a credential. The whole
+// script still requires target-bound authorization, a reviewed hash and readback.
+// Recognize only a complete, literal Node statement reading a mounted /run file;
+// do not exempt a whole heredoc or arbitrary expression following a secret name.
+export function hasEmbeddedConfigurationSecret(script) {
+  if (/-----BEGIN/i.test(script)) return true;
+  const publicSource = script.replace(
+    /^[\t ]*const (?:password|passphrase|secret|token|api_key) = fs\.readFileSync\((['"])\/run\/[a-z][a-z0-9-]{0,63}\1, (['"])utf8\2\)\.trim\(\);[\t ]*\r?$/gm,
+    "// Runtime credential reference; no credential material embedded.",
+  );
+  return /(?:password|passphrase|secret|token|api_key)\s*[:=]\s*[^\s$]/i.test(publicSource);
+}
+
+export async function configure(target, operation, ctx) {
+  const phase = operation === "vps:host:configure" ? "host" : "containers";
+  const config = target.configuration?.[phase];
+  if (!config?.authorization_reference || config.previous_access_preserved !== true)
+    fail("configuration_not_authorized");
+  if (config.restrict_previous_access === true)
+    fail("access_restriction_requires_verified_new_access_workflow");
+  if (
+    !/^\.agents\/private\/state\/cloud\/onboarding\/[a-f0-9]{64}\.json$/.test(
+      config.inventory ?? "",
+    )
+  )
+    fail("inventory_required_before_configuration");
+  const inventory = await ctx.files.json(inside(ctx.root, config.inventory));
+  if (
+    inventory.source !== "ssh" ||
+    inventory.target !== target.name ||
+    inventory.access_binding !==
+      hash({ project: ctx.root, ssh: target.ssh, credential: target.credential }) ||
+    hash(inventory) !== config.inventory_sha256 ||
+    !inventory.observed_at ||
+    !Object.values(inventory.fields ?? {}).some((field) => field.state === "observed")
+  )
+    fail("inventory_binding_mismatch");
+  const required = [
+    "os",
+    "os_version",
+    "architecture",
+    "hostname",
+    "disk",
+    "network",
+    "user",
+    "services",
+    "ports",
+    "firewall",
+    "storage",
+    "mounts",
+    "volumes",
+  ];
+  const missing = required.filter((name) => inventory.fields[name]?.state !== "observed");
+  if (
+    missing.some(
+      (name) =>
+        typeof config.accepted_inventory_gaps?.[name] !== "string" ||
+        !config.accepted_inventory_gaps[name].trim(),
+    )
+  )
+    fail("configuration_inventory_incomplete");
+  const load = async (path, expected) => {
+    if (!/^\.agents\/config\/vps-scripts\/[a-z][a-z0-9-]{0,63}\.sh$/.test(path ?? ""))
+      fail("configuration_script_path_denied");
+    const absolute = inside(ctx.root, text(path, 1024));
+    await ctx.files.checked(absolute);
+    const info = await ctx.files.lstat(absolute);
+    if (!info.isFile() || info.nlink !== 1) fail("configuration_script_path_denied");
+    const script = await ctx.files.readFile(absolute, "utf8");
+    if (Buffer.byteLength(script) > 65536 || hash(script) !== expected)
+      fail("configuration_script_mismatch");
+    if (hasEmbeddedConfigurationSecret(script)) fail("configuration_secret_material_denied");
+    return script;
+  };
+  const script = await load(config.script_path, config.script_sha256);
+  const readback = await load(config.readback_script_path, config.readback_sha256);
+  if (!/^[A-Z][A-Z0-9_-]{7,79}$/.test(config.expected_marker ?? ""))
+    fail("configuration_readback_required");
+  const observe = async () => {
+    const { result } = await sshTransport(target, ctx, "sh -s", {
+      input: readback,
+      timeout: 15000,
+      maxOutput: 4096,
+    });
+    return (
+      !result.timedOut &&
+      !result.overflow &&
+      result.code === 0 &&
+      String(result.stdout).trim() === config.expected_marker
+    );
+  };
+  const confirmed = async (idempotent) => {
+    const record = {
+      state: "verified",
+      source: "configuration-readback",
+      phase,
+      target: target.name,
+      access_binding: inventory.access_binding,
+      script_sha256: config.script_sha256,
+      readback_sha256: config.readback_sha256,
+      observed_at: ctx.now(),
+      grants_deployment_claim: false,
+    };
+    const locator = await ctx.files.receipt(
+      ["configuration-confirmed", target.name, phase, record.observed_at],
+      record,
+    );
+    return {
+      state: "verified",
+      phase,
+      idempotent,
+      effect: "readback_confirmed",
+      observation: locator,
+    };
+  };
+  if (await observe()) return confirmed(true);
+  const attemptKey = ["configure-attempt", target.name, phase, config.script_sha256];
+  const attemptPath = inside(
+    ctx.root,
+    `.agents/private/state/cloud/onboarding/${hash(attemptKey)}.json`,
+  );
+  let attempted = false;
+  try {
+    await ctx.files.checked(attemptPath);
+    attempted = true;
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  if (attempted) fail("remote_result_requires_reconciliation");
+  await ctx.files.receipt(attemptKey, {
+    state: "attempted",
+    phase,
+    target: target.name,
+    authorization: config.authorization_reference,
+    observed_at: ctx.now(),
+  });
+  // No implicit retry after a timeout/lost reply. Read back against the pinned target first.
+  try {
+    await sshTransport(target, ctx, "sh -s", { input: script, timeout: 60000, maxOutput: 16384 });
+  } catch {}
+  if (!(await observe())) fail("remote_result_requires_reconciliation");
+  return confirmed(false);
+}

package/templates/.agents/tools/cloud-onboarding-credentials.mjs

@@ -0,0 +1,279 @@
+import { dirname, resolve } from "node:path";
+import { generateNamed } from "./cloud-onboarding-generation.mjs";
+
+export { interactiveKeygen } from "./cloud-onboarding-generation.mjs";
+
+import { fail, fingerprint, hash, inside } from "./cloud-onboarding-policy.mjs";
+
+function signature(stat) {
+  return [stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
+}
+export async function diskEncryption(path, ctx) {
+  if (ctx.diskEncryption) return ctx.diskEncryption(path);
+  if (process.platform !== "win32")
+    return { state: "unavailable", reason: "platform_probe_not_available" };
+  const script =
+    "$ErrorActionPreference='Stop';if(-not(Get-Command Get-BitLockerVolume -ErrorAction SilentlyContinue)){exit 3};try{$v=Get-BitLockerVolume -MountPoint ([System.IO.Path]::GetPathRoot($env:ZAIP_SECURE_PATH));@{protection=[int]$v.ProtectionStatus;volume=[int]$v.VolumeStatus}|ConvertTo-Json -Compress}catch{exit 4}";
+  const result = await ctx.exec(
+    "powershell.exe",
+    ["-NoProfile", "-NonInteractive", "-Command", script],
+    { env: { ZAIP_SECURE_PATH: path }, timeout: 5000, maxOutput: 2048 },
+  );
+  if (result.code === 4) return { state: "permission_denied", reason: "disk_probe_denied" };
+  if (result.code !== 0) return { state: "unavailable", reason: "not_observed" };
+  try {
+    const value = JSON.parse(result.stdout);
+    if (
+      ![0, 1, 2].includes(value.protection) ||
+      !Number.isInteger(value.volume) ||
+      value.volume < 0 ||
+      value.volume > 5
+    )
+      throw Error();
+    return {
+      state: "observed",
+      source: "windows-bitlocker",
+      protection_enabled: value.protection === 2 ? null : value.protection === 1,
+      volume_state: value.volume,
+    };
+  } catch {
+    return { state: "unavailable", reason: "not_observed" };
+  }
+}
+async function publicFingerprint(path, ctx) {
+  await ctx.files.checked(`${path}.pub`, true);
+  const outcome = await ctx.exec("ssh-keygen", ["-l", "-E", "sha256", "-f", path], {
+    timeout: 5000,
+    maxOutput: 4096,
+  });
+  const fingerprints = String(outcome.stdout ?? "").match(/SHA256:[A-Za-z0-9+/]{43}/g) ?? [];
+  if (outcome.code !== 0 || fingerprints.length !== 1)
+    fail("credential_public_identity_unavailable");
+  return fingerprints[0];
+}
+export async function bindExistingCredential(credential, ctx) {
+  const path = resolve(ctx.root, credential.path);
+  if (
+    credential.mode === "external-key" &&
+    (path === ctx.root || path.startsWith(`${ctx.root}/`) || path.startsWith(`${ctx.root}\\`))
+  )
+    fail("external_key_must_be_outside_project");
+  await ctx.files.checked(path);
+  const info = await ctx.files.lstat(path);
+  if (!info.isFile() || info.nlink !== 1) fail("credential_path_invalid");
+  await ctx.files.untracked(path);
+  if (credential.mode !== "agent") await ctx.files.verifyPermissions(path);
+  const observed = await publicFingerprint(path, ctx);
+  if (credential.public_fingerprint && credential.public_fingerprint !== observed)
+    fail("credential_identity_mismatch");
+  credential.public_fingerprint = observed;
+  credential.real_path = path;
+  credential.file_identity = `${info.dev}:${info.ino}`;
+}
+export async function keyProtection(path, credential, ctx) {
+  // OpenSSH inspects only the selected key; never expose its public output or diagnostic text.
+  const result = await ctx.exec("ssh-keygen", ["-y", "-P", "", "-f", path], {
+    timeout: 5000,
+    maxOutput: 16384,
+    env: { LC_ALL: "C" },
+  });
+  if (result.code === 0) {
+    if (credential.unprotected_acceptance !== true) fail("unprotected_key_acceptance_required");
+    return "unprotected_explicitly_accepted";
+  }
+  if (/incorrect passphrase|encrypted|passphrase/i.test(String(result.stderr))) return "protected";
+  fail("key_protection_unverified");
+}
+export async function credentialPath(target, ctx) {
+  const credential = target.credential;
+  const local = inside(ctx.root, `.agents/private/state/ssh/${credential.name}/identity`);
+  const path = ["import", "generate"].includes(credential.mode)
+    ? local
+    : resolve(ctx.root, credential.path);
+  if (
+    credential.mode === "external-key" &&
+    (path === ctx.root || path.startsWith(`${ctx.root}/`) || path.startsWith(`${ctx.root}\\`))
+  )
+    fail("external_key_must_be_outside_project");
+  await ctx.files.checked(path);
+  const stat = await ctx.files.lstat(path);
+  if (!stat.isFile() || stat.nlink !== 1 || (credential.mode === "agent" && stat.size > 16384))
+    fail("credential_path_invalid");
+  if (
+    ["external-key", "agent"].includes(credential.mode) &&
+    credential.real_path &&
+    (credential.real_path !== path || credential.file_identity !== `${stat.dev}:${stat.ino}`)
+  )
+    fail("credential_physical_binding_mismatch");
+  await ctx.files.untracked(path);
+  if (credential.mode !== "agent") await ctx.files.verifyPermissions(path);
+  const expected =
+    credential.public_fingerprint ??
+    (await ctx.files.json(`${local}.reference.json`)).public_fingerprint;
+  const observed = await publicFingerprint(path, ctx);
+  if (observed !== expected) fail("credential_identity_mismatch");
+  if (credential.mode !== "agent") await keyProtection(path, credential, ctx);
+  if (credential.mode === "agent") {
+    // The identity file is PUBLIC, and IdentitiesOnly selects it even with a multi-key agent.
+    const publicText = await ctx.files.readFile(path, "utf8");
+    if (publicText.length > 16384 || fingerprint(publicText) !== expected)
+      fail("agent_public_identity_required");
+    const result = await ctx.exec("ssh-add", ["-l", "-E", "sha256"], {
+      env: { SSH_AUTH_SOCK: credential.agent_endpoint },
+      timeout: 5000,
+      maxOutput: 32768,
+    });
+    if (
+      result.code !== 0 ||
+      !(String(result.stdout).match(/SHA256:[A-Za-z0-9+/]{43}/g) ?? []).includes(expected)
+    )
+      fail("selected_agent_identity_unavailable");
+  }
+  return { path, public_fingerprint: expected, signature: signature(stat) };
+}
+export async function recheckIdentity(identity, ctx) {
+  await ctx.files.checked(identity.path);
+  if (signature(await ctx.files.lstat(identity.path)) !== identity.signature)
+    fail("credential_changed_after_validation");
+}
+export async function selectedPublicKey(target, ctx) {
+  const credential = target.credential;
+  if (!credential) fail("credential_unavailable");
+  const privatePath = ["import", "generate"].includes(credential.mode)
+    ? inside(ctx.root, `.agents/private/state/ssh/${credential.name}/identity`)
+    : resolve(ctx.root, credential.path);
+  const publicPath =
+    credential.mode === "agent"
+      ? privatePath
+      : credential.public_key_path
+        ? resolve(ctx.root, credential.public_key_path)
+        : `${privatePath}.pub`;
+  if (!publicPath.endsWith(".pub")) fail("selected_public_key_path_denied");
+  await ctx.files.checked(publicPath);
+  const info = await ctx.files.lstat(publicPath);
+  if (!info.isFile() || info.nlink !== 1 || info.size > 16384)
+    fail("selected_public_key_unavailable");
+  const content = await ctx.files.readFile(publicPath, "utf8");
+  const observed = fingerprint(content);
+  const expected =
+    credential.public_fingerprint ??
+    (await ctx.files.json(`${privatePath}.reference.json`)).public_fingerprint;
+  if (observed !== expected) fail("public_key_identity_mismatch");
+  return {
+    public_key: content.trim().split(/\s+/).slice(0, 2).join(" "),
+    public_fingerprint: observed,
+  };
+}
+export async function prepareCredential(target, ctx) {
+  const credential = target.credential;
+  if (["external-key", "agent"].includes(credential.mode)) {
+    const identity = await credentialPath(target, ctx);
+    let publicIdentity = { public_key: null };
+    try {
+      publicIdentity = await selectedPublicKey(target, ctx);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    return {
+      state: "verified",
+      mechanism: credential.mode,
+      ...publicIdentity,
+      public_fingerprint: identity.public_fingerprint,
+      disk_encryption: await diskEncryption(identity.path, ctx),
+    };
+  }
+  const path = inside(ctx.root, `.agents/private/state/ssh/${credential.name}/identity`);
+  await ctx.files.localDirectory(dirname(path));
+  await ctx.files.untracked(path);
+  await ctx.files.checked(path, true);
+  let exists = true;
+  try {
+    await ctx.files.lstat(path);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    exists = false;
+  }
+  if (credential.mode === "import") {
+    if (credential.import_authorized !== true) fail("credential_import_not_authorized");
+    const source = resolve(ctx.root, credential.path);
+    await ctx.files.checked(source);
+    const sourceStat = await ctx.files.lstat(source);
+    if (
+      !sourceStat.isFile() ||
+      sourceStat.nlink !== 1 ||
+      (credential.real_path &&
+        (credential.real_path !== source ||
+          credential.file_identity !== `${sourceStat.dev}:${sourceStat.ino}`))
+    )
+      fail("credential_physical_binding_mismatch");
+    await ctx.files.verifyPermissions(source);
+    const before = signature(sourceStat);
+    if ((await publicFingerprint(source, ctx)) !== credential.public_fingerprint)
+      fail("credential_identity_mismatch");
+    if (!exists) await ctx.files.copyFile(source, path, ctx.files.constants.COPYFILE_EXCL);
+    // Only the explicitly authorized import reads bytes, to verify exact preservation.
+    if (
+      before !== signature(await ctx.files.lstat(source)) ||
+      hash(await ctx.files.readFile(source)) !== hash(await ctx.files.readFile(path))
+    )
+      fail("import_requires_reconciliation");
+  } else if (!exists)
+    await generateNamed(path, credential, ctx, { keyProtection, publicFingerprint });
+  await ctx.files.protect(path);
+  const protection = await keyProtection(path, credential, ctx);
+  const observed = await publicFingerprint(path, ctx);
+  if (credential.public_fingerprint && observed !== credential.public_fingerprint)
+    fail("credential_identity_mismatch");
+  // An existing unowned generated key is not silently adopted after an interrupted attempt.
+  if (exists && credential.mode === "generate") {
+    let reference;
+    try {
+      reference = await ctx.files.json(`${path}.reference.json`);
+    } catch {
+      const reconciliation = credential.reconcile_existing_generation;
+      if (
+        reconciliation?.public_fingerprint !== observed ||
+        !reconciliation.authorization_reference
+      )
+        fail("key_generation_requires_reconciliation");
+      reference = { authorization: ctx.authorization, public_fingerprint: observed };
+    }
+    if (reference.authorization !== ctx.authorization || reference.public_fingerprint !== observed)
+      fail("existing_credential_conflict");
+  }
+  await ctx.files.exclusive(
+    `${path}.reference.json`,
+    `${JSON.stringify({
+      public_fingerprint: observed,
+      mechanism: credential.mode,
+      authorization: ctx.authorization,
+    })}\n`,
+  );
+  await ctx.files.protect(`${path}.reference.json`);
+  if (credential.mode === "import") {
+    const sourcePublic = credential.public_key_path
+      ? resolve(ctx.root, credential.public_key_path)
+      : `${resolve(ctx.root, credential.path)}.pub`;
+    if (!sourcePublic.endsWith(".pub")) fail("selected_public_key_path_denied");
+    await ctx.files.checked(sourcePublic);
+    const info = await ctx.files.lstat(sourcePublic);
+    if (!info.isFile() || info.nlink !== 1 || info.size > 16384)
+      fail("selected_public_key_unavailable");
+    const content = await ctx.files.readFile(sourcePublic, "utf8");
+    if (content.length > 16384 || fingerprint(content) !== observed)
+      fail("public_key_identity_mismatch");
+    await ctx.files.exclusive(
+      `${path}.pub`,
+      `${content.trim().split(/\s+/).slice(0, 2).join(" ")}\n`,
+    );
+  }
+  const publicIdentity = await selectedPublicKey(target, ctx);
+  return {
+    state: "verified",
+    mechanism: credential.mode,
+    ...publicIdentity,
+    public_fingerprint: observed,
+    key_protection: protection,
+    disk_encryption: await diskEncryption(path, ctx),
+  };
+}

package/templates/.agents/tools/cloud-onboarding-files.mjs

@@ -0,0 +1,190 @@
+import { constants } from "node:fs";
+import * as fs from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+import { fail, hash, inside, physical, stable } from "./cloud-onboarding-policy.mjs";
+
+export function fileServices(root, exec, injected = {}) {
+  const io = { ...fs, ...injected };
+  const checked = async (path, missing = false) => physical(path, { fs: io, missing });
+  async function json(path, max = 128 * 1024) {
+    await checked(path);
+    const stat = await io.lstat(path);
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > max) fail("invalid_file");
+    return JSON.parse(await io.readFile(path, "utf8"));
+  }
+  async function protect(path, directory = false) {
+    await checked(path);
+    if (process.platform === "win32") {
+      // Fixed script, literal environment path, no interpolated PowerShell or key bytes.
+      const script =
+        "$ErrorActionPreference='Stop';$p=$env:ZAIP_SECURE_PATH;$sid=[System.Security.Principal.WindowsIdentity]::GetCurrent().User;$old=Get-Acl -LiteralPath $p;if($old.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $sid.Value){exit 4};$dir=$env:ZAIP_SECURE_DIR -eq '1';$a=if($dir){New-Object System.Security.AccessControl.DirectorySecurity}else{New-Object System.Security.AccessControl.FileSecurity};$a.SetAccessRuleProtection($true,$false);$inherit=if($dir){'ContainerInherit,ObjectInherit'}else{'None'};$r=New-Object System.Security.AccessControl.FileSystemAccessRule($sid,'FullControl',$inherit,'None','Allow');$a.AddAccessRule($r);if($dir){[System.IO.Directory]::SetAccessControl($p,$a)}else{[System.IO.File]::SetAccessControl($p,$a)};$b=Get-Acl -LiteralPath $p;if(-not $b.AreAccessRulesProtected){exit 2};foreach($r in $b.Access){if($r.IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value -ne $sid.Value -or $r.AccessControlType -ne 'Allow'){exit 3}}";
+      const outcome = await exec(
+        "powershell.exe",
+        ["-NoProfile", "-NonInteractive", "-Command", script],
+        {
+          env: { ZAIP_SECURE_PATH: path, ZAIP_SECURE_DIR: directory ? "1" : "0" },
+          // Cold PowerShell startup on hosted Windows may exceed 15 seconds.
+          // This bounded operation still verifies owner and every resulting ACE.
+          timeout: 60000,
+          maxOutput: 4096,
+        },
+      );
+      if (outcome.code !== 0) fail("acl_verification_failed");
+    } else {
+      await io.chmod(path, directory ? 0o700 : 0o600);
+      const stat = await io.lstat(path);
+      if ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid())
+        fail("permission_verification_failed");
+    }
+    const info = await io.lstat(path);
+    if ((!directory && (!info.isFile() || info.nlink !== 1)) || (directory && !info.isDirectory()))
+      fail("invalid_file");
+  }
+  async function verifyPermissions(path) {
+    await checked(path);
+    if (process.platform === "win32") {
+      const script =
+        "$ErrorActionPreference='Stop';$a=Get-Acl -LiteralPath $env:ZAIP_SECURE_PATH;$sid=[System.Security.Principal.WindowsIdentity]::GetCurrent().User;foreach($r in $a.Access){$id=$r.IdentityReference.Translate([System.Security.Principal.SecurityIdentifier]).Value;if($r.AccessControlType -eq 'Allow' -and $id -notin @($sid.Value,'S-1-5-18','S-1-5-32-544')){exit 3}}";
+      if (
+        (
+          await exec("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script], {
+            env: { ZAIP_SECURE_PATH: path },
+            timeout: 60000,
+            maxOutput: 1024,
+          })
+        ).code !== 0
+      )
+        fail("credential_permissions_too_broad");
+    } else {
+      const stat = await io.lstat(path);
+      if ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid())
+        fail("credential_permissions_too_broad");
+    }
+  }
+  async function localDirectory(path) {
+    const local = inside(root, ".agents/private/state");
+    if (path !== local && !path.startsWith(local + (process.platform === "win32" ? "\\" : "/")))
+      fail("path_outside_local_storage");
+    await checked(path, true);
+    await io.mkdir(local, { recursive: true, mode: 0o700 });
+    const marker = inside(root, ".agents/private/.gitignore");
+    try {
+      await io.writeFile(marker, "*\n!.gitignore\n", { flag: "wx", mode: 0o600 });
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+    }
+    await checked(marker);
+    if ((await io.readFile(marker, "utf8")).replaceAll("\r", "") !== "*\n!.gitignore\n")
+      fail("local_ignore_conflict");
+    await io.mkdir(path, { recursive: true, mode: 0o700 });
+    // The shared .local root is not narrowed; only this operation's storage is.
+    const chain = [];
+    for (let current = path; current !== local; current = dirname(current)) chain.unshift(current);
+    for (const current of chain) await protect(current, true);
+    const ignored = await exec(
+      "git",
+      ["check-ignore", "--quiet", "--", relative(root, resolve(path, "identity"))],
+      { cwd: root, timeout: 5000 },
+    );
+    if (ignored.code !== 0) fail("credential_storage_not_ignored");
+  }
+  async function untracked(path) {
+    if (!resolve(path).startsWith(root + (process.platform === "win32" ? "\\" : "/"))) return;
+    const result = await exec("git", ["ls-files", "--error-unmatch", "--", relative(root, path)], {
+      cwd: root,
+      timeout: 5000,
+      maxOutput: 1024,
+    });
+    if (result.code !== 1) fail("credential_path_tracked_or_unverified");
+  }
+  async function exclusive(path, content, mode = 0o600) {
+    await checked(path, true);
+    await io.mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    try {
+      await io.writeFile(path, content, { flag: "wx", mode });
+      return true;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      await checked(path);
+      if (!Buffer.from(await io.readFile(path)).equals(Buffer.from(content)))
+        fail("existing_file_conflict");
+      return false;
+    }
+  }
+  async function lock(name, action) {
+    const directory = inside(root, ".agents/private/state/cloud/locks");
+    await localDirectory(directory);
+    const path = resolve(directory, `${hash(name)}.lock`);
+    let handle;
+    try {
+      handle = await io.open(path, "wx", 0o600);
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const before = await json(path, 4096);
+      if (
+        before.version !== 1 ||
+        before.operation !== hash(name) ||
+        !Number.isInteger(before.pid) ||
+        before.pid <= 0
+      )
+        fail("onboarding_lock_requires_reconciliation");
+      try {
+        process.kill(before.pid, 0);
+        fail("onboarding_writer_busy");
+      } catch (probe) {
+        if (probe.code !== "ESRCH") throw probe;
+      }
+      // Only a proven-dead owner can be recovered; operation journals still require observation.
+      if (stable(await json(path, 4096)) !== stable(before)) fail("onboarding_writer_busy");
+      await io.unlink(path);
+      try {
+        handle = await io.open(path, "wx", 0o600);
+      } catch {
+        fail("onboarding_writer_busy");
+      }
+    }
+    try {
+      await handle.writeFile(
+        `${JSON.stringify({ version: 1, pid: process.pid, operation: hash(name) })}\n`,
+      );
+      return await action();
+    } finally {
+      await handle.close();
+      await io.unlink(path);
+    }
+  }
+  async function receipt(name, value) {
+    const directory = inside(root, ".agents/private/state/cloud/onboarding");
+    await localDirectory(directory);
+    const path = resolve(directory, `${hash(name)}.json`);
+    const body = `${stable(value)}\n`;
+    await exclusive(path, body);
+    await protect(path);
+    return relative(root, path).replaceAll("\\", "/");
+  }
+  async function replace(path, content, expectedHash) {
+    await checked(path);
+    const before = await io.readFile(path);
+    if (Buffer.from(content).equals(before)) return;
+    if (hash(before) !== expectedHash) fail("concurrent_file_change");
+    const temporary = `${path}.${hash(content)}.pending`;
+    await exclusive(temporary, content);
+    if (hash(await io.readFile(path)) !== expectedHash) fail("concurrent_file_change");
+    await checked(path);
+    await io.rename(temporary, path);
+  }
+  return {
+    ...io,
+    checked,
+    json,
+    protect,
+    verifyPermissions,
+    localDirectory,
+    untracked,
+    exclusive,
+    lock,
+    receipt,
+    replace,
+    constants,
+  };
+}

package/templates/.agents/tools/cloud-onboarding-files.test.mjs

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { diskEncryption } from "./cloud-onboarding-credentials.mjs";
+import { fileServices } from "./cloud-onboarding-files.mjs";
+import { hash } from "./cloud-onboarding-policy.mjs";
+
+test("VPS-37 active writer denies concurrency; dead owner recovery is scoped and malformed ledger denies", async () => {
+  const root = await realpath(await mkdtemp(join(tmpdir(), "zaip-vps-file-lock-")));
+  // Actual filesystem/PID integration; ACL/Git subprocesses are explicit fixture responses here.
+  const files = fileServices(root, async () => ({ code: 0 }));
+  let release, entered;
+  const ready = new Promise((done) => (entered = done)),
+    gate = new Promise((done) => (release = done));
+  try {
+    const first = files.lock("fixture", async () => {
+      entered();
+      await gate;
+      return "first";
+    });
+    await ready;
+    await assert.rejects(
+      files.lock("fixture", async () => "must-not-enter"),
+      /onboarding_writer_busy/,
+    );
+    release();
+    assert.equal(await first, "first");
+    const pid = await new Promise((done) => {
+      const child = spawn(process.execPath, ["--version"], { windowsHide: true, stdio: "ignore" });
+      child.once("close", () => done(child.pid));
+    });
+    const path = join(root, ".agents/private/state/cloud/locks", `${hash("fixture")}.lock`);
+    await writeFile(path, JSON.stringify({ version: 1, pid, operation: hash("fixture") }));
+    assert.equal(await files.lock("fixture", async () => "recovered"), "recovered");
+    await writeFile(path, JSON.stringify({ version: 1, pid: -1, operation: hash("fixture") }));
+    const before = await readFile(path);
+    await assert.rejects(
+      files.lock("fixture", async () => "must-not-enter"),
+      /onboarding_lock_requires_reconciliation/,
+    );
+    assert.deepEqual(await readFile(path), before);
+  } finally {
+    release?.();
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("VPS-21 disk encryption observed, permission denied and unavailable remain distinct fixture results", {
+  skip: process.platform !== "win32" && "Windows BitLocker response fixture",
+}, async () => {
+  const probe = (result) => diskEncryption("C:\\fictional-volume", { exec: async () => result });
+  assert.equal(
+    (await probe({ code: 0, stdout: '{"protection":1,"volume":0}' })).protection_enabled,
+    true,
+  );
+  assert.equal(
+    (await probe({ code: 0, stdout: '{"protection":0,"volume":0}' })).protection_enabled,
+    false,
+  );
+  assert.deepEqual(await probe({ code: 0, stdout: '{"protection":2,"volume":3}' }), {
+    state: "observed",
+    source: "windows-bitlocker",
+    protection_enabled: null,
+    volume_state: 3,
+  });
+  assert.equal((await probe({ code: 4 })).state, "permission_denied");
+  assert.equal((await probe({ code: 3 })).state, "unavailable");
+  assert.equal((await probe({ code: 0, stdout: "invalid fixture" })).state, "unavailable");
+});