agentlas 1.0.66 → 1.0.67

package/engine/commands/mcp.cjs

@@ -13,21 +13,112 @@
 const { userDataDir } = require("../core/paths.cjs");
 const { materializeTrustedSystemMcpServer } = require("../mcp/inventory.cjs");
 const { probeSystemMcpServerConnection } = require("../mcp/probe.cjs");
+const {
+  DEFAULT_OPTIONS,
+  list: outputList,
+  render,
+  single,
+  parseOutputFlags,
+  displayWidth,
+  terminalTextOf,
+} = require("../cli-output.cjs");
+
+const OUTPUT_FLAGS = new Set(["--json", "--yaml", "--quiet", "-q", "--no-headers", "--no-color"]);
+
+function commandError(message, code = "INVALID_ARGUMENT", details) {
+  const error = new Error(message);
+  error.code = code;
+  if (details !== undefined) error.details = details;
+  return error;
+}
+
+function withOutputFlags(ctx, args) {
+  if (!args.some((arg) => OUTPUT_FLAGS.has(arg))) return { ctx, args };
+  const parsed = parseOutputFlags(args);
+  return {
+    ctx: { ...ctx, output: { ...(ctx.output || DEFAULT_OPTIONS), ...parsed.options } },
+    args: parsed.rest,
+  };
+}
+
+function emit(ctx, result) {
+  if (typeof ctx.emit === "function") {
+    ctx.emit(result);
+    return;
+  }
+  ctx.out(render(result, ctx.output || DEFAULT_OPTIONS));
+}
+
+function ansi(options, code, value) {
+  const text = String(value);
+  return options?.noColor ? text : `\u001b[${code}m${text}\u001b[0m`;
+}
+
+function isMachineOutput(ctx) {
+  const output = ctx.output || DEFAULT_OPTIONS;
+  return output.quiet || output.format === "json" || output.format === "yaml";
+}
+
+function mcpListSchema(en) {
+  return Object.freeze({
+    idField: "id",
+    columns: [
+      { header: "id", field: "id" },
+      { header: en ? "name" : "이름", field: "name" },
+    ],
+    renderHuman(result, options = {}) {
+      const rows = Array.isArray(result.data) ? result.data : [];
+      if (!rows.length) {
+        return options.noHeaders ? "" : (en ? "No MCP servers registered." : "등록된 MCP 서버가 없습니다.");
+      }
+      const lines = [];
+      if (!options.noHeaders) lines.push(ansi(options, 1, en ? "MCP servers" : "MCP 서버"));
+      for (const row of rows) {
+        const id = terminalTextOf(row.id, 256);
+        const name = terminalTextOf(row.name, 4096);
+        const padding = " ".repeat(Math.max(1, 28 - displayWidth(id)));
+        lines.push(`  ${ansi(options, 36, id)}${padding}${name}`);
+      }
+      return lines.join("\n");
+    },
+  });
+}
+
+function mcpProbeSchema(en) {
+  return Object.freeze({
+    idField: "serverId",
+    columns: [
+      { header: en ? "server" : "서버", field: "serverId" },
+      { header: en ? "status" : "상태", field: "status" },
+      { header: en ? "tools" : "툴", field: "toolCount" },
+    ],
+    renderHuman(result, options = {}) {
+      const row = result.data || {};
+      const serverId = terminalTextOf(row.serverId, 256);
+      const toolCount = Number.isSafeInteger(row.toolCount) ? row.toolCount : 0;
+      const status = row.connected ? ansi(options, 32, en ? "connected" : "연결됨") : ansi(options, 31, en ? "failed" : "실패");
+      const toolLabel = en ? `${toolCount} tool(s) listed` : `툴 ${toolCount}개 확인`;
+      const note = en
+        ? "Preflight only: connection readiness does not imply tool-call success."
+        : "프리플라이트일 뿐입니다: 연결 준비됨 ≠ 툴 호출 성공.";
+      return [
+        `${status} ${ansi(options, 1, serverId)} · ${toolLabel}`,
+        ansi(options, 2, note),
+      ].join("\n");
+    },
+  });
+}
 
 function list(ctx) {
   const en = ctx.lang === "en";
   const db = ctx.db();
-  if (!ctx.tableExists(db, "mcp_servers")) {
-    ctx.out(en ? "No MCP servers registered." : "등록된 MCP 서버가 없습니다.");
-    return 0;
-  }
-  const rows = db.prepare("SELECT id, name FROM mcp_servers ORDER BY name").all();
-  if (!rows.length) {
-    ctx.out(en ? "No MCP servers registered." : "등록된 MCP 서버가 없습니다.");
-    return 0;
-  }
-  ctx.out(ctx.ui.bold(en ? "MCP servers" : "MCP 서버"));
-  for (const r of rows) ctx.out(`  ${ctx.ui.accent(String(r.id).padEnd(28))} ${r.name || ""}`);
+  const rows = ctx.tableExists(db, "mcp_servers")
+    ? db.prepare("SELECT id, name FROM mcp_servers ORDER BY name").all().map((row) => ({
+      id: String(row.id || ""),
+      name: String(row.name || ""),
+    }))
+    : [];
+  emit(ctx, outputList(rows, mcpListSchema(en)));
   return 0;
 }
 
@@ -35,13 +126,11 @@ async function probe(ctx, args) {
   const en = ctx.lang === "en";
   const ref = String(args[0] || "").trim();
   if (!ref || args.length !== 1 || ref.startsWith("-")) {
-    ctx.err(en ? "Usage: agentlas mcp probe <server-id|catalog-id>" : "사용법: agentlas mcp probe <server-id|catalog-id>");
-    return 1;
+    throw commandError(en ? "Usage: agentlas mcp probe <server-id|catalog-id>" : "사용법: agentlas mcp probe <server-id|catalog-id>");
   }
   const db = ctx.db();
   if (!ctx.tableExists(db, "mcp_servers")) {
-    ctx.err(en ? "No MCP servers registered." : "등록된 MCP 서버가 없습니다.");
-    return 1;
+    throw commandError(en ? "No MCP servers registered." : "등록된 MCP 서버가 없습니다.", "MCP_SERVER_NOT_FOUND");
   }
   // catalog_id는 데스크탑 스키마 열 — 오래된 DB에는 없을 수 있어 방어적으로 조회.
   const byCatalog = ctx.columnExists(db, "mcp_servers", "catalog_id");
@@ -49,35 +138,55 @@ async function probe(ctx, args) {
     ? db.prepare("SELECT id, catalog_id, name, name_en, transport, command, args_json, env_keys_json, enabled FROM mcp_servers WHERE id=? OR catalog_id=? LIMIT 1").get(ref, ref)
     : db.prepare("SELECT id, NULL AS catalog_id, name, name_en, transport, command, args_json, env_keys_json, enabled FROM mcp_servers WHERE id=? LIMIT 1").get(ref);
   if (!row) {
-    ctx.err(en ? `MCP server not found: ${ref}` : `MCP 서버를 찾을 수 없습니다: ${ref}`);
-    return 1;
+    throw commandError(
+      en ? `MCP server not found: ${ref}` : `MCP 서버를 찾을 수 없습니다: ${ref}`,
+      "MCP_SERVER_NOT_FOUND",
+      { serverId: ref },
+    );
   }
   const server = materializeTrustedSystemMcpServer(row, { userDataDir: userDataDir() });
   if (!server) {
     // 이유를 지어내지 않는다 — materialize는 비활성/비-stdio/안전하지 않은
     // 정의를 하나의 fail-closed로 접기 때문에 관찰 가능한 사실만 알린다.
-    ctx.err(en
-      ? `'${ref}' is not probe-eligible (disabled, non-stdio transport, or an unsafe runtime definition).`
-      : `'${ref}' 은(는) probe 대상이 아닙니다 (비활성, stdio가 아닌 transport, 또는 안전하지 않은 실행 정의).`);
-    return 1;
+    throw commandError(
+      en
+        ? `'${ref}' is not probe-eligible (disabled, non-stdio transport, or an unsafe runtime definition).`
+        : `'${ref}' 은(는) probe 대상이 아닙니다 (비활성, stdio가 아닌 transport, 또는 안전하지 않은 실행 정의).`,
+      "MCP_PROBE_INELIGIBLE",
+      { serverId: ref },
+    );
+  }
+  if (!isMachineOutput(ctx)) {
+    const options = ctx.output || DEFAULT_OPTIONS;
+    ctx.out(ansi(options, 2, en
+      ? `Probing ${server.catalog_id} (isolated child env, handshake only)…`
+      : `${server.catalog_id} 연결 확인 중 (격리 자식 env, 핸드셰이크만)…`));
   }
-  ctx.out(ctx.ui.dim(en
-    ? `Probing ${server.catalog_id} (isolated child env, handshake only)…`
-    : `${server.catalog_id} 연결 확인 중 (격리 자식 env, 핸드셰이크만)…`));
   const result = await probeSystemMcpServerConnection(server, { userDataDir: userDataDir(), cwd: process.cwd() });
-  if (result.connected) {
-    const toolCount = Array.isArray(result.tools) ? result.tools.length : 0;
-    ctx.out(`${ctx.ui.green("connected")} ${ctx.ui.bold(server.catalog_id)} · ${en ? `${toolCount} tool(s) listed` : `툴 ${toolCount}개 확인`}`);
-    ctx.out(ctx.ui.dim(en
-      ? "Preflight only: connection readiness does not imply tool-call success."
-      : "프리플라이트일 뿐입니다: 연결 준비됨 ≠ 툴 호출 성공."));
-    return 0;
+  if (!result.connected) {
+    throw commandError(
+      en
+        ? `MCP probe failed: ${server.catalog_id} · ${result.reason || "connection_failed"}`
+        : `MCP 연결 확인 실패: ${server.catalog_id} · ${result.reason || "connection_failed"}`,
+      "MCP_PROBE_FAILED",
+      { serverId: server.catalog_id, reason: result.reason || "connection_failed" },
+    );
   }
-  ctx.err(`${ctx.ui.red("failed")} ${ctx.ui.bold(server.catalog_id)} · ${result.reason}`);
-  return 1;
+  const toolCount = Array.isArray(result.tools) ? result.tools.length : 0;
+  emit(ctx, single({
+    serverId: server.catalog_id,
+    status: "connected",
+    connected: true,
+    reason: result.reason || "connected",
+    toolCount,
+  }, mcpProbeSchema(en)));
+  return 0;
 }
 
 function run(ctx, args = []) {
+  const normalized = withOutputFlags(ctx, args);
+  ctx = normalized.ctx;
+  args = normalized.args;
   const [sub, ...rest] = args;
   if (!sub) return list(ctx);
   // 무인자 기본 동작이 목록인데 이름으로 부르면 거부되는 비대칭이 있었다
@@ -85,17 +194,15 @@ function run(ctx, args = []) {
   // "list를 붙이는" 습관이 여기서만 usage 오류가 됐다.
   if (sub === "list" || sub === "ls") {
     if (rest.length) {
-      ctx.err(ctx.lang === "en" ? "Usage: agentlas mcp list" : "사용법: agentlas mcp list");
-      return 1;
+      throw commandError(ctx.lang === "en" ? "Usage: agentlas mcp list" : "사용법: agentlas mcp list");
     }
     return list(ctx);
   }
   if (sub === "probe") return probe(ctx, rest);
   const en = ctx.lang === "en";
-  ctx.err(en
+  throw commandError(en
     ? `unknown mcp subcommand: ${sub} (available: list · probe)`
     : `알 수 없는 mcp 하위 명령: ${sub} (사용 가능: list · probe)`);
-  return 1;
 }
 
 module.exports = { run };

package/engine/experience/intents.cjs

@@ -192,6 +192,12 @@ function validateExperiencePack(value) {
   assertUniqueIds(value.evidenceReceiptIds, "experience pack.evidenceReceiptIds");
   if (!Array.isArray(value.mcpRequirements) || value.mcpRequirements.length > 64) throw new Error("experience pack.mcpRequirements is invalid");
   value.mcpRequirements.forEach((requirement, index) => validateMcpRequirement(requirement, `experience pack.mcpRequirements[${index}]`));
+  const requirementIds = value.mcpRequirements.map((requirement) => requirement.requirementId);
+  if (new Set(requirementIds).size !== requirementIds.length) {
+    const error = new Error("experience pack.mcpRequirements requirementId values must be unique");
+    error.code = "duplicate_mcp_requirement_id";
+    throw error;
+  }
   // base 패키지 복사 반입 금지 — 참조만 허용(오너 결정, 완화 불가).
   if (value.containsBasePackageMaterial !== false) throw new Error("experience pack must reference the base release; copied base material is forbidden");
   if (!HASH_RE.test(String(value.contentHash || ""))) throw new Error("experience pack.contentHash is invalid");

package/engine/hub/install.cjs

@@ -255,20 +255,79 @@ function cloudApplyPortableFileMode(filePath, mode, platform = process.platform)
   ) throw new Error(`cloud restore file mode verification failed: ${filePath}`);
 }
 
+function cloudDirectoryAnchor(target, label, { allowMissing = true, containedBy = null } = {}) {
+  let stat;
+  try { stat = fs.lstatSync(target); } catch (error) {
+    if (allowMissing && error && error.code === "ENOENT") return null;
+    throw error;
+  }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error(`${label} is not a safe managed directory`);
+  }
+  let realpath;
+  try { realpath = fs.realpathSync.native(target); }
+  catch (error) { throw new Error(`${label} could not be canonicalized: ${error.message}`); }
+  if (containedBy && !(
+    realpath === containedBy.realpath || realpath.startsWith(`${containedBy.realpath}${path.sep}`)
+  )) {
+    throw new Error(`${label} escapes its managed root`);
+  }
+  return { path: target, realpath, dev: stat.dev, ino: stat.ino, nlink: stat.nlink, stat };
+}
+
+function cloudAssertDirectoryAnchor(anchor, label, containedBy = null) {
+  const current = cloudDirectoryAnchor(anchor.path, label, { allowMissing: false, containedBy });
+  if (
+    current.realpath !== anchor.realpath || current.dev !== anchor.dev ||
+    current.ino !== anchor.ino || current.nlink !== anchor.nlink
+  ) {
+    throw new Error(`${label} changed while it was being used`);
+  }
+  return current;
+}
+
+function cloudRefreshDirectoryAnchor(anchor, label, containedBy = null) {
+  const current = cloudDirectoryAnchor(anchor.path, label, { allowMissing: false, containedBy });
+  if (
+    current.realpath !== anchor.realpath || current.dev !== anchor.dev ||
+    current.ino !== anchor.ino
+  ) {
+    throw new Error(`${label} changed while it was being used`);
+  }
+  return current;
+}
+
+function cloudSameRegularFile(left, right) {
+  return Boolean(
+    left && right && left.isFile() && right.isFile() &&
+    !left.isSymbolicLink() && !right.isSymbolicLink() &&
+    left.dev === right.dev && left.ino === right.ino && left.nlink === right.nlink,
+  );
+}
+
 function cloudEnsurePrivateSubdirectory(root, directory) {
   const relative = path.relative(root, directory);
   if (relative.startsWith("..") || path.isAbsolute(relative)) {
     throw new Error("cloud restore subdirectory escapes staging");
   }
   let current = root;
-  cloudManagedDirectoryState(root, "cloud restore staging", { allowMissing: false });
+  const rootAnchor = cloudDirectoryAnchor(root, "cloud restore staging", { allowMissing: false });
+  const managedPaths = [root];
   for (const part of relative.split(path.sep).filter(Boolean)) {
     current = path.join(current, part);
     try { fs.mkdirSync(current, { recursive: false, mode: 0o700 }); }
     catch (error) { if (!error || error.code !== "EEXIST") throw error; }
-    cloudManagedDirectoryState(current, "cloud restore package directory", { allowMissing: false });
     cloudApplyPrivateDirectoryMode(current);
+    managedPaths.push(current);
   }
+  // Directory nlink changes when a child directory is added, so take every
+  // anchor after the complete path is present rather than before a descendant
+  // mkdir can legitimately change an ancestor's nlink.
+  return managedPaths.map((managedPath, index) => cloudDirectoryAnchor(
+    managedPath,
+    index === 0 ? "cloud restore staging" : "cloud restore package directory",
+    { allowMissing: false, ...(index === 0 ? {} : { containedBy: rootAnchor }) },
+  ));
 }
 
 // ── 스테이징 스냅샷 전수 검증 (심링크/특수 엔트리/모드/무결성) ──
@@ -387,18 +446,43 @@ function cloudManagedDirectoryState(target, label, { allowMissing = true } = {})
   return stat;
 }
 
-function cloudRemoveManagedDirectory(target, label) {
-  if (!cloudManagedDirectoryState(target, label)) return false;
+function cloudRemoveManagedDirectory(target, label, { anchor = null, containedBy = null } = {}) {
+  if (anchor) {
+    let current;
+    try {
+      current = cloudDirectoryAnchor(target, label, { allowMissing: true, containedBy });
+    } catch (error) {
+      if (error && error.code === "ENOENT") return false;
+      throw error;
+    }
+    if (!current) return false;
+    if (
+      current.realpath !== anchor.realpath || current.dev !== anchor.dev ||
+      current.ino !== anchor.ino
+    ) throw new Error(`${label} changed while it was being removed`);
+  } else if (containedBy) {
+    if (!cloudDirectoryAnchor(target, label, { allowMissing: true, containedBy })) return false;
+  } else if (!cloudManagedDirectoryState(target, label)) return false;
   fs.rmSync(target, { recursive: true, force: false });
   return true;
 }
 
-function cloudRenameManagedDirectory(source, destination, label) {
-  cloudManagedDirectoryState(source, `${label} source`, { allowMissing: false });
+function cloudRenameManagedDirectory(source, destination, label, { sourceAnchor = null, parentAnchor = null } = {}) {
+  if (parentAnchor) cloudRefreshDirectoryAnchor(parentAnchor, `${label} parent`);
+  if (sourceAnchor) {
+    cloudRefreshDirectoryAnchor(sourceAnchor, `${label} source`, parentAnchor);
+  } else {
+    cloudManagedDirectoryState(source, `${label} source`, { allowMissing: false });
+  }
   if (cloudManagedDirectoryState(destination, `${label} destination`)) {
     throw new Error(`${label} destination already exists`);
   }
+  if (parentAnchor) cloudRefreshDirectoryAnchor(parentAnchor, `${label} parent`);
   fs.renameSync(source, destination);
+  if (parentAnchor) {
+    cloudRefreshDirectoryAnchor(parentAnchor, `${label} parent`);
+    cloudDirectoryAnchor(destination, `${label} destination`, { allowMissing: false, containedBy: parentAnchor });
+  }
 }
 
 function cloudReadInstallJournal(journalPath) {
@@ -472,12 +556,36 @@ function cloudFsyncDirectory(directory) {
   finally { if (fd !== undefined) try { fs.closeSync(fd); } catch { /* best-effort */ } }
 }
 
-function rollbackCloudInstallSwap({ destination, staging, backup, movedExisting, installed }) {
-  if (installed) cloudRemoveManagedDirectory(destination, "cloud install destination");
+function rollbackCloudInstallSwap({
+  destination,
+  staging,
+  backup,
+  movedExisting,
+  installed,
+  parentAnchor = null,
+  stagingAnchor = null,
+  backupAnchor = null,
+  destinationAnchor = null,
+}) {
+  const safeParent = parentAnchor
+    ? cloudRefreshDirectoryAnchor(parentAnchor, "cloud install parent rollback")
+    : null;
+  if (installed) {
+    cloudRemoveManagedDirectory(destination, "cloud install destination", {
+      anchor: destinationAnchor,
+      containedBy: safeParent,
+    });
+  }
   if (movedExisting && cloudManagedDirectoryState(backup, "cloud install backup")) {
-    cloudRenameManagedDirectory(backup, destination, "cloud install rollback");
+    cloudRenameManagedDirectory(backup, destination, "cloud install rollback", {
+      sourceAnchor: backupAnchor,
+      parentAnchor: safeParent,
+    });
   }
-  cloudRemoveManagedDirectory(staging, "cloud install staging");
+  cloudRemoveManagedDirectory(staging, "cloud install staging", {
+    anchor: stagingAnchor,
+    containedBy: safeParent,
+  });
   cloudFsyncDirectory(path.dirname(destination));
 }
 
@@ -660,17 +768,33 @@ function materializeCloudListing(agentId, slug, listing, options = {}) {
   if (pathConflict) throw new Error(pathConflict.message);
   const layout = cloudInstallLayout(slug, { createParent: true });
   const { destination: dir, parent, journalPath: journal } = layout;
+  let parentAnchor = cloudDirectoryAnchor(parent, "cloud install parent", { allowMissing: false });
   const nonce = `${process.pid}-${Date.now()}-${crypto.randomBytes(4).toString("hex")}`;
   const staging = path.join(parent, `.${path.basename(dir)}.installing-${nonce}`);
   const backup = path.join(parent, `.${path.basename(dir)}.backup-${nonce}`);
+  const managedAnchors = new Map();
   const seen = new Set();
   const verifiedFiles = [];
   let verifiedTotalBytes = 0;
   let movedExisting = false;
   let installed = false;
+  let stagingAnchor = null;
+  let destinationAnchor = null;
+  let backupAnchor = null;
+  let installedDestinationAnchor = null;
   try {
+    cloudAssertDirectoryAnchor(parentAnchor, "cloud install parent");
     fs.mkdirSync(staging, { recursive: false, mode: 0o700 });
+    // Creating the staging directory legitimately changes the parent's nlink;
+    // refresh that field while retaining the original dev/ino/realpath anchor.
+    parentAnchor = cloudRefreshDirectoryAnchor(parentAnchor, "cloud install parent");
     cloudApplyPrivateDirectoryMode(staging);
+    stagingAnchor = cloudDirectoryAnchor(staging, "cloud install staging", {
+      allowMissing: false,
+      containedBy: parentAnchor,
+    });
+    managedAnchors.set(staging, stagingAnchor);
+    cloudAssertDirectoryAnchor(parentAnchor, "cloud install parent");
     for (const file of pkg.files) {
       const target = resolveCloudInstallPath(staging, file.path);
       const normalizedPath = path.relative(staging, target).split(path.sep).join("/");
@@ -700,19 +824,62 @@ function materializeCloudListing(agentId, slug, listing, options = {}) {
       });
       verifiedTotalBytes += bytes.length;
       if (verifiedTotalBytes > CLOUD_MAX_TOTAL_BYTES) throw new Error("cloud package exceeds total byte limit");
-      cloudEnsurePrivateSubdirectory(staging, path.dirname(target));
+      for (const anchor of cloudEnsurePrivateSubdirectory(staging, path.dirname(target))) {
+        managedAnchors.set(anchor.path, anchor);
+      }
+      stagingAnchor = managedAnchors.get(staging);
+      cloudAssertDirectoryAnchor(parentAnchor, "cloud install parent");
+      for (const anchor of managedAnchors.values()) {
+        cloudAssertDirectoryAnchor(anchor, "cloud install managed directory", stagingAnchor);
+      }
       const mode = packageHashVersion === CLOUD_PACKAGE_HASH_V2 && file.executable ? 0o700 : 0o600;
-      const fileFd = fs.openSync(
-        target,
-        fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | (fs.constants.O_NOFOLLOW || 0),
-        mode,
-      );
+      let fileFd;
+      let fileWritten = false;
       try {
+        fileFd = fs.openSync(
+          target,
+          fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | (fs.constants.O_NOFOLLOW || 0),
+          mode,
+        );
+        // A parent swap can happen during open. Do not write until the
+        // directory anchors and the opened file identity still agree.
+        cloudAssertDirectoryAnchor(parentAnchor, "cloud install parent");
+        // O_CREAT may legitimately change a directory's nlink on some
+        // filesystems, so refresh that field after the open while retaining
+        // the dev/ino/realpath identity and containment checks.
+        stagingAnchor = cloudRefreshDirectoryAnchor(stagingAnchor, "cloud install staging", parentAnchor);
+        managedAnchors.set(staging, stagingAnchor);
+        for (const [anchorPath, anchor] of managedAnchors.entries()) {
+          if (anchorPath === staging) continue;
+          managedAnchors.set(anchorPath, cloudRefreshDirectoryAnchor(
+            anchor,
+            "cloud install managed directory",
+            stagingAnchor,
+          ));
+        }
+        const opened = fs.fstatSync(fileFd);
+        const listed = fs.lstatSync(target);
+        if (!cloudSameRegularFile(opened, listed) || opened.size !== 0) {
+          throw new Error(`cloud package target changed while opening: ${file.path}`);
+        }
         fs.writeFileSync(fileFd, bytes);
         if (process.platform !== "win32") fs.fchmodSync(fileFd, mode);
         fs.fsyncSync(fileFd);
+        fileWritten = true;
       } finally {
-        fs.closeSync(fileFd);
+        if (fileFd !== undefined) {
+          if (!fileWritten) {
+            // O_EXCL creates a zero-byte file before the final anchor check
+            // can reject a swapped parent. Remove it only when the path still
+            // names the exact descriptor we opened; never unlink a successor.
+            try {
+              const opened = fs.fstatSync(fileFd);
+              const listed = fs.lstatSync(target);
+              if (cloudSameRegularFile(opened, listed)) fs.unlinkSync(target);
+            } catch { /* outer rollback retains any unknown successor */ }
+          }
+          fs.closeSync(fileFd);
+        }
       }
     }
     const expectedPackageHash = String(pkg.packageHash || "").toLowerCase().replace(/^sha256:/, "");
@@ -732,12 +899,33 @@ function materializeCloudListing(agentId, slug, listing, options = {}) {
     if (verifiedTotalBytes !== pkg.totalBytes) throw new Error("cloud package total byte count does not match its files");
     const restoredAt = new Date().toISOString();
     const markerPath = path.join(staging, CLOUD_RESTORE_MARKER_PATH);
-    const markerFd = fs.openSync(
-      markerPath,
-      fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | (fs.constants.O_NOFOLLOW || 0),
-      0o600,
-    );
+    stagingAnchor = cloudDirectoryAnchor(staging, "cloud install staging", {
+      allowMissing: false,
+      containedBy: parentAnchor,
+    });
+    managedAnchors.set(staging, stagingAnchor);
+    cloudAssertDirectoryAnchor(parentAnchor, "cloud install parent");
+    for (const anchor of managedAnchors.values()) {
+      cloudAssertDirectoryAnchor(anchor, "cloud install managed directory", stagingAnchor);
+    }
+    let markerFd;
+    let markerWritten = false;
     try {
+      markerFd = fs.openSync(
+        markerPath,
+        fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY | (fs.constants.O_NOFOLLOW || 0),
+        0o600,
+      );
+      cloudAssertDirectoryAnchor(parentAnchor, "cloud install parent");
+      // As with package files, creating the marker can update the staging
+      // directory nlink; refresh it before writing and keep identity strict.
+      stagingAnchor = cloudRefreshDirectoryAnchor(stagingAnchor, "cloud install staging", parentAnchor);
+      managedAnchors.set(staging, stagingAnchor);
+      const opened = fs.fstatSync(markerFd);
+      const listed = fs.lstatSync(markerPath);
+      if (!cloudSameRegularFile(opened, listed) || opened.size !== 0) {
+        throw new Error("cloud restore marker changed while opening");
+      }
       fs.writeFileSync(markerFd, JSON.stringify({
         schemaVersion: 1,
         source: "agentlas-cloud",
@@ -761,8 +949,22 @@ function materializeCloudListing(agentId, slug, listing, options = {}) {
       }, null, 2) + "\n", "utf8");
       if (process.platform !== "win32") fs.fchmodSync(markerFd, 0o600);
       fs.fsyncSync(markerFd);
+      markerWritten = true;
     } finally {
-      fs.closeSync(markerFd);
+      if (markerFd !== undefined) {
+        if (!markerWritten) {
+          try {
+            const opened = fs.fstatSync(markerFd);
+            const listed = fs.lstatSync(markerPath);
+            if (cloudSameRegularFile(opened, listed)) fs.unlinkSync(markerPath);
+          } catch { /* outer rollback retains any unknown successor */ }
+        }
+        fs.closeSync(markerFd);
+      }
+    }
+    cloudAssertDirectoryAnchor(parentAnchor, "cloud install parent");
+    for (const anchor of managedAnchors.values()) {
+      cloudAssertDirectoryAnchor(anchor, "cloud install managed directory", stagingAnchor);
     }
     cloudVerifyRestoredSnapshot(staging, verifiedFiles, {
       slug,
@@ -773,6 +975,7 @@ function materializeCloudListing(agentId, slug, listing, options = {}) {
     });
 
     if (options.deferCommit) {
+      cloudAssertDirectoryAnchor(parentAnchor, "cloud install parent");
       writeCloudInstallJournal(journal, {
         schemaVersion: 1,
         slug,
@@ -783,15 +986,42 @@ function materializeCloudListing(agentId, slug, listing, options = {}) {
         hadExisting: Boolean(cloudManagedDirectoryState(dir, "cloud install destination")),
         dbExpected: options.dbExpected || {},
       });
+      // The recovery journal is a file in the managed parent and may update
+      // that directory's nlink; refresh the field before publication checks.
+      parentAnchor = cloudRefreshDirectoryAnchor(parentAnchor, "cloud install parent");
     }
 
     // A Cloud agent is an immutable asset snapshot. Replace the managed install
     // as a whole so removed files and local mutations cannot leak across versions.
+    cloudAssertDirectoryAnchor(parentAnchor, "cloud install parent");
+    for (const anchor of managedAnchors.values()) {
+      cloudAssertDirectoryAnchor(anchor, "cloud install managed directory", stagingAnchor);
+    }
     if (cloudManagedDirectoryState(dir, "cloud install destination")) {
-      cloudRenameManagedDirectory(dir, backup, "cloud install snapshot swap");
+      destinationAnchor = cloudDirectoryAnchor(dir, "cloud install destination", {
+        allowMissing: false,
+        containedBy: parentAnchor,
+      });
+      cloudRenameManagedDirectory(dir, backup, "cloud install snapshot swap", {
+        sourceAnchor: destinationAnchor,
+        parentAnchor,
+      });
       movedExisting = true;
+      backupAnchor = cloudDirectoryAnchor(backup, "cloud install backup", {
+        allowMissing: false,
+        containedBy: parentAnchor,
+      });
     }
-    cloudRenameManagedDirectory(staging, dir, "cloud install staging swap");
+    cloudAssertDirectoryAnchor(parentAnchor, "cloud install parent");
+    cloudRenameManagedDirectory(staging, dir, "cloud install staging swap", {
+      sourceAnchor: stagingAnchor,
+      parentAnchor,
+    });
+    cloudAssertDirectoryAnchor(parentAnchor, "cloud install parent");
+    installedDestinationAnchor = cloudDirectoryAnchor(dir, "cloud install destination", {
+      allowMissing: false,
+      containedBy: parentAnchor,
+    });
     cloudFsyncDirectory(parent);
     installed = true;
     if (options.deferCommit) {
@@ -807,12 +1037,34 @@ function materializeCloudListing(agentId, slug, listing, options = {}) {
       });
     }
   } catch (error) {
-    rollbackCloudInstallSwap({ destination: dir, staging, backup, movedExisting, installed });
+    rollbackCloudInstallSwap({
+      destination: dir,
+      staging,
+      backup,
+      movedExisting,
+      installed,
+      parentAnchor,
+      stagingAnchor,
+      backupAnchor,
+      destinationAnchor: installedDestinationAnchor,
+    });
     try { if (fs.existsSync(journal)) cloudUnlinkInstallJournal(journal); } catch { /* best-effort */ }
     throw error;
   } finally {
-    try { cloudRemoveManagedDirectory(staging, "cloud install staging"); } catch { /* best-effort */ }
-    try { if (!options.deferCommit && installed) cloudRemoveManagedDirectory(backup, "cloud install backup"); } catch { /* best-effort */ }
+    try {
+      cloudRemoveManagedDirectory(staging, "cloud install staging", {
+        anchor: stagingAnchor,
+        containedBy: parentAnchor,
+      });
+    } catch { /* best-effort */ }
+    try {
+      if (!options.deferCommit && installed) {
+        cloudRemoveManagedDirectory(backup, "cloud install backup", {
+          anchor: backupAnchor,
+          containedBy: parentAnchor,
+        });
+      }
+    } catch { /* best-effort */ }
   }
   if (!options.deferCommit) return dir;
   let settled = false;