agentlas 0.5.2 → 0.5.5

package/engine/agentlas.cjs

@@ -28,6 +28,7 @@ const os = require("node:os");
 const fs = require("node:fs");
 const { spawn } = require("node:child_process");
 const crypto = require("node:crypto");
+const { compareSemVer, normalizeSemVer, parseSemVer } = require("./semver.cjs");
 
 // ── 앱과 동일한 userData 경로 (electron app.getPath('userData')와 일치) ──
 function userDataDir() {
@@ -138,6 +139,8 @@ function loadMultimodalCatalog() {
   } catch {
     const providers = [
       { id: "codex-cli-image", modality: "image", label: "Codex CLI image", labelKo: "Codex CLI 이미지", envKeys: [], billing: "subscription", defaultModel: "runtime-default" },
+      { id: "grok-cli-image", modality: "image", label: "Grok CLI image (Imagine)", labelKo: "Grok CLI 이미지 (Imagine)", envKeys: [], billing: "subscription", defaultModel: "runtime-default" },
+      { id: "grok-cli-video", modality: "video", label: "Grok CLI video (Imagine)", labelKo: "Grok CLI 영상 (Imagine)", envKeys: [], billing: "subscription", defaultModel: "runtime-default" },
       { id: "openai-image", modality: "image", label: "OpenAI Images API", labelKo: "OpenAI 이미지 API", envKeys: ["OPENAI_API_KEY"], billing: "paid-api", defaultModel: "gpt-image-2" },
       { id: "google-image", modality: "image", label: "Google Gemini Image", labelKo: "Google Gemini 이미지", envKeys: ["GOOGLE_API_KEY"], billing: "paid-api", defaultModel: "gemini-image" },
       { id: "runway-video", modality: "video", label: "Runway API", labelKo: "Runway API", envKeys: ["RUNWAY_API_KEY"], billing: "paid-api", defaultModel: "gen4.5" },
@@ -544,8 +547,13 @@ function agentFolder(agent) {
   const routes = routesMap();
   const r = routes[agent.id];
   if (r && r.path) return r.path; // 로컬 임포트는 원본 폴더
+  const cloudRoot = path.join(userDataDir(), "cloud-agent-installs", cloudSlug(agent.slug));
+  if (exists(path.join(cloudRoot, CLOUD_RESTORE_MARKER_PATH))) return cloudRoot;
   return path.join(userDataDir(), "agents", agent.slug);
 }
+function agentSystemPromptCli(agent) {
+  return agent && agent.system_prompt ? agent.system_prompt : `You are ${agent?.name || "an Agentlas agent"}.`;
+}
 
 // ── 로컬 폴더 임포트 (앱의 electron/agents/import-local.ts 와 동일 규칙) ──
 // 터미널에서 "폴더 드래그" = `agentlas import <path>`. 앱과 같은 DB/라우트를 공유한다.
@@ -767,10 +775,15 @@ function cmdImport(db, absPath) {
 const CLOUD_MAX_TOTAL_BYTES = 3 * 1024 * 1024;
 const CLOUD_MAX_FILE_BYTES = 512 * 1024;
 const CLOUD_MAX_FILES = 400;
-const CLOUD_TEXT_EXTS = new Set([".cjs", ".css", ".csv", ".html", ".js", ".json", ".jsonl", ".md", ".mjs", ".py", ".sh", ".toml", ".ts", ".tsx", ".txt", ".yaml", ".yml"]);
+const CLOUD_PACKAGE_HASH_V1 = "path-sha256-v1";
+const CLOUD_PACKAGE_HASH_V2 = "path-sha256-executable-v2";
+const CLOUD_RESTORE_MARKER_PATH = ".agentlas-cloud-package.json";
+const CLOUD_ASSET_STATE_FILE = "cloud-asset-state.v1.json";
+const CLOUD_ASSET_SCOPES = new Set(["owner-private", "hub-public"]);
+const CLOUD_TEXT_EXTS = new Set([".cfg", ".cjs", ".conf", ".config", ".css", ".csv", ".env", ".html", ".ini", ".js", ".json", ".jsonl", ".md", ".mjs", ".properties", ".ps1", ".psd1", ".psm1", ".py", ".sh", ".toml", ".ts", ".tsx", ".txt", ".xml", ".yaml", ".yml"]);
 const CLOUD_AGENT_FILES = new Set(["AGENT.md", "AGENTS.md", "CLAUDE.md", "GEMINI.md", "README.md", "agent.md", "manifest.md", "system-prompt.md"]);
 const CLOUD_SKIP_DIRS = new Set([".git", ".next", ".studio-runtime", ".turbo", "build", "coverage", "dist", "node_modules", "out", "release"]);
-const CLOUD_BLOCKED_FILE_RE = [/^\.env(?:\..*)?$/i, /^id_rsa(?:\.pub)?$/i, /^credentials(?:\..*)?$/i, /^secrets?(?:\..*)?$/i, /(?:^|[._-])service-account(?:[._-]|$)/i, /\.(?:key|pem|p12|pfx|mobileprovision)$/i];
+const CLOUD_BLOCKED_FILE_RE = [/^\.env(?:\..*)?$/i, /^id_rsa(?:\.pub)?$/i, /^credentials(?:\..*)?$/i, /^secrets?(?:\..*)?$/i, /^cloud-asset-state\.v1\.json$/i, /(?:^|[._-])service-account(?:[._-]|$)/i, /\.(?:key|pem|p12|pfx|mobileprovision)$/i];
 const CLOUD_ROUTING_CARD_PATH = ".agentlas/routing-card.json";
 const CLOUD_ROUTING_CARD_CAPABILITY_RE = /^[a-z][a-z0-9]*(_[a-z0-9]+)+$/;
 const CLOUD_ROUTING_CARD_STATUSES = new Set(["draft", "searchable", "candidate", "routing_ready", "trusted"]);
@@ -778,11 +791,149 @@ const CLOUD_SECRET_RE = [
   ["private-key", /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/i, "private key material"],
   ["openai-key", /\bsk-[A-Za-z0-9_-]{20,}\b/, "OpenAI-style API key"],
   ["github-token", /\bgh[pousr]_[A-Za-z0-9_]{30,}\b/, "GitHub token"],
+  ["gitlab-token", /\bglpat-[A-Za-z0-9_-]{20,}\b/, "GitLab token"],
+  ["google-api-key", /\bAIza[0-9A-Za-z_-]{35}\b/, "Google API key"],
+  ["npm-token", /\bnpm_[A-Za-z0-9]{30,}\b/, "npm access token"],
+  ["stripe-secret", /\bsk_(?:live|test)_[A-Za-z0-9]{16,}\b/, "Stripe secret key"],
   ["slack-token", /\bxox[baprs]-[A-Za-z0-9-]{20,}\b/, "Slack token"],
   ["aws-key", /\bAKIA[0-9A-Z]{16}\b/, "AWS access key"],
   ["generic-secret", /\b(?:api[_-]?key|secret|token|password)\s*[:=]\s*['"][^'"]{8,}['"]/i, "hard-coded credential"],
 ];
 
+const HUB_RESPONSE_MAX_BYTES = 16 * 1024 * 1024;
+const HUB_TIMEOUT_DEFAULTS = Object.freeze({ connectMs: 15_000, idleMs: 30_000, totalMs: 180_000 });
+
+function finiteTimeoutMs(value, fallback, min, max) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(max, Math.max(min, Math.trunc(parsed)));
+}
+
+function hubTimeoutConfig(env = process.env) {
+  const totalMs = finiteTimeoutMs(env.AGENTLAS_HUB_TOTAL_TIMEOUT_MS, HUB_TIMEOUT_DEFAULTS.totalMs, 5_000, 900_000);
+  return {
+    connectMs: Math.min(totalMs, finiteTimeoutMs(env.AGENTLAS_HUB_CONNECT_TIMEOUT_MS, HUB_TIMEOUT_DEFAULTS.connectMs, 1_000, 120_000)),
+    idleMs: Math.min(totalMs, finiteTimeoutMs(env.AGENTLAS_HUB_IDLE_TIMEOUT_MS, HUB_TIMEOUT_DEFAULTS.idleMs, 1_000, 300_000)),
+    totalMs,
+  };
+}
+
+function directHubTimeoutConfig(value = {}) {
+  const totalMs = finiteTimeoutMs(value.totalMs, HUB_TIMEOUT_DEFAULTS.totalMs, 10, 900_000);
+  return {
+    connectMs: Math.min(totalMs, finiteTimeoutMs(value.connectMs, HUB_TIMEOUT_DEFAULTS.connectMs, 10, 120_000)),
+    idleMs: Math.min(totalMs, finiteTimeoutMs(value.idleMs, HUB_TIMEOUT_DEFAULTS.idleMs, 10, 300_000)),
+    totalMs,
+  };
+}
+
+function hubTimeoutError(kind, ms) {
+  const message = kind === "connect"
+    ? `Hub 연결 제한 시간(${ms}ms)을 초과했습니다.`
+    : kind === "idle"
+      ? `Hub 응답이 ${ms}ms 동안 멈췄습니다.`
+      : `Hub 요청 전체 제한 시간(${ms}ms)을 초과했습니다.`;
+  const error = new Error(message);
+  error.code = `AGENTLAS_HUB_${kind.toUpperCase()}_TIMEOUT`;
+  return error;
+}
+
+/** Hub/Cloud fetch + body reader. Headers 전 connect, chunk 사이 idle, 전 구간 total timeout. */
+async function fetchHubCli(url, init = {}, options = {}) {
+  const fetchImpl = options.fetch || globalThis.fetch;
+  if (typeof fetchImpl !== "function") throw new Error("이 런타임에 fetch가 없습니다.");
+  const timeout = options.timeoutConfig ? directHubTimeoutConfig(options.timeoutConfig) : hubTimeoutConfig(options.env || process.env);
+  const controller = new AbortController();
+  const upstreamSignal = init.signal;
+  let connectTimer = null;
+  let idleTimer = null;
+  let totalTimer = null;
+  let reader = null;
+  let terminalError = null;
+  let rejectTerminal;
+  const terminal = new Promise((_, reject) => { rejectTerminal = reject; });
+  const stop = (error) => {
+    if (terminalError) return;
+    terminalError = error;
+    try { controller.abort(error); } catch { controller.abort(); }
+    rejectTerminal(error);
+  };
+  const onUpstreamAbort = () => {
+    const reason = upstreamSignal && upstreamSignal.reason;
+    const error = reason instanceof Error ? reason : new Error("Hub 요청이 취소되었습니다.");
+    if (!error.code) error.code = "ABORT_ERR";
+    stop(error);
+  };
+  const armIdle = () => {
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => stop(hubTimeoutError("idle", timeout.idleMs)), timeout.idleMs);
+  };
+
+  if (upstreamSignal) {
+    if (upstreamSignal.aborted) onUpstreamAbort();
+    else upstreamSignal.addEventListener("abort", onUpstreamAbort, { once: true });
+  }
+  connectTimer = setTimeout(() => stop(hubTimeoutError("connect", timeout.connectMs)), timeout.connectMs);
+  totalTimer = setTimeout(() => stop(hubTimeoutError("total", timeout.totalMs)), timeout.totalMs);
+
+  try {
+    const response = await Promise.race([
+      Promise.resolve().then(() => fetchImpl(url, { ...init, signal: controller.signal })),
+      terminal,
+    ]);
+    if (connectTimer) clearTimeout(connectTimer);
+    connectTimer = null;
+    const chunks = [];
+    let bytes = 0;
+    armIdle();
+    if (response.body && typeof response.body.getReader === "function") {
+      reader = response.body.getReader();
+      while (true) {
+        const part = await Promise.race([reader.read(), terminal]);
+        if (part.done) break;
+        armIdle();
+        const chunk = Buffer.from(part.value || []);
+        bytes += chunk.length;
+        if (bytes > HUB_RESPONSE_MAX_BYTES) {
+          const error = new Error(`Hub 응답이 허용 크기(${HUB_RESPONSE_MAX_BYTES} bytes)를 초과했습니다.`);
+          error.code = "AGENTLAS_HUB_RESPONSE_TOO_LARGE";
+          stop(error);
+          throw error;
+        }
+        chunks.push(chunk);
+      }
+    } else {
+      const raw = Buffer.from(await Promise.race([response.arrayBuffer(), terminal]));
+      bytes = raw.length;
+      if (bytes > HUB_RESPONSE_MAX_BYTES) throw new Error(`Hub 응답이 허용 크기(${HUB_RESPONSE_MAX_BYTES} bytes)를 초과했습니다.`);
+      chunks.push(raw);
+    }
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = null;
+    const text = Buffer.concat(chunks, bytes).toString("utf8");
+    return { ok: response.ok, status: response.status, headers: response.headers, text };
+  } catch (error) {
+    if (terminalError) throw terminalError;
+    throw error;
+  } finally {
+    if (connectTimer) clearTimeout(connectTimer);
+    if (idleTimer) clearTimeout(idleTimer);
+    if (totalTimer) clearTimeout(totalTimer);
+    if (upstreamSignal) upstreamSignal.removeEventListener?.("abort", onUpstreamAbort);
+    if (reader && terminalError) {
+      try { await reader.cancel(terminalError); } catch { /* ignore */ }
+    }
+  }
+}
+
+function parseHubJsonCli(response, label) {
+  try {
+    return JSON.parse(response.text || "null");
+  } catch {
+    throw new Error(`${label} 응답 JSON 형식이 올바르지 않습니다.`);
+  }
+}
+
 function parseCloudFlags(args) {
   const flags = { _: [] };
   for (let i = 0; i < args.length; i++) {
@@ -803,6 +954,35 @@ function parseCloudFlags(args) {
   return flags;
 }
 
+function cloudVisibilityFlag(value) {
+  if (value == null) return null;
+  if (value === "private-link" || value === "marketplace") return value;
+  throw new Error("--visibility must be private-link or marketplace");
+}
+
+function cloudVisibilityForAction(sub, flags) {
+  const explicit = cloudVisibilityFlag(flags.visibility);
+  if (sub === "save") {
+    if (explicit === "marketplace") {
+      throw new Error("`agentlas cloud save` is owner-private. Use `agentlas cloud publish` for the public Hub.");
+    }
+    return "private-link";
+  }
+  if (sub === "publish") {
+    if (explicit === "private-link") {
+      throw new Error("`agentlas cloud publish` is public Hub publication. Use `agentlas cloud save` for owner-private Agent Cloud storage.");
+    }
+    return "marketplace";
+  }
+  if (explicit) return explicit;
+  return "private-link";
+}
+
+function cloudActionForTopLevelUpload(args) {
+  const flags = parseCloudFlags(args);
+  return cloudVisibilityFlag(flags.visibility) === "marketplace" ? "publish" : "save";
+}
+
 async function cmdCloud(db, args, runtimeOverride) {
   const sub = args[0] || "help";
   if (sub === "help" || sub === "--help" || sub === "-h") {
@@ -815,28 +995,58 @@ async function cmdCloud(db, args, runtimeOverride) {
       "  runtime read-agent-file <path> <file>",
       "                                      lazy read with allow/deny gates",
       "  field-test [--json]                 run local Cloud contract field test",
-      "  package <path> [--json]             package + static security review",
+      "  save <path> [--dry-run] [--slug name]",
+      "                                      save owner-private in Agent Cloud (default upload)",
       "  publish <path> [--dry-run] [--llm-review] [--slug name]",
-      "                                      register with submitter-paid local review",
-      "  install <slug>                      download/install from Agentlas Cloud marketplace",
-      "  delete <slug> [--json]              unpublish one of your cloud marketplace agents",
+      "                                      explicitly publish to the public Agentlas Hub",
+      "  package <path> [--json] [--visibility private-link|marketplace]",
+      "                                      package only; defaults to private-save checks",
+      "  list [--json]                       list packages in your private Agent Cloud",
+      "  restore <slug> [--json]             restore an owned Cloud package on this machine",
+      "  install <slug>                      compatibility alias: install from the public Hub",
+      "  delete <slug> [--scope owner-private|hub-public] [--json]",
+      "                                      conditionally delete one exact observed Cloud revision",
       "  search \"<what you need>\" [--limit 10]",
-      "                                      search the marketplace (no sign-in needed)",
+      "                                      search the public Hub (no sign-in needed)",
       "",
-      "Model cost rule: Agentlas Cloud does not run a platform-owned LLM here.",
-      "--llm-review uses only this machine's active CLI/BYOK/Ollama runtime.",
+      "Private save rule: no public review or routing card; local secret/path/hash checks remain.",
+      "--llm-review applies only to public Hub publishing and uses this machine's runtime.",
     ].join("\n"));
     return;
   }
   if (sub === "search") {
     return parity().cloudSearch(db, args.slice(1));
   }
+  if (sub === "list") {
+    const flags = parseCloudFlags(args.slice(1));
+    const result = await listOwnedCloudAgentsCli(Number(flags.limit || 100));
+    if (flags.json) return out(JSON.stringify(result, null, 2));
+    const agents = Array.isArray(result.results) ? result.results : [];
+    if (!agents.length) return out("Private Agent Cloud에 저장된 에이전트가 없습니다.");
+    for (const agent of agents) out(`${agent.slug}\t${agent.name || agent.nameEn || agent.slug}\t${agent.entityKind || "agent"}`);
+    return;
+  }
+  if (sub === "restore") {
+    const flags = parseCloudFlags(args.slice(1));
+    const slug = flags._[0];
+    if (!slug) fail("usage: agentlas cloud restore <slug> [--json]");
+    const result = await restoreOwnedCloudAgentCli(db, slug);
+    if (flags.json) return out(JSON.stringify(result, null, 2));
+    out(`✓ restored ${result.slug} from private Agent Cloud`);
+    out(`  hash: ${result.packageHash}`);
+    if (result.localPath) out(`  files: ${result.localPath}`);
+    if (result.localStateWarning) out(`  warning: ${result.localStateWarning}`);
+    return;
+  }
   if (sub === "delete" || sub === "unpublish") {
     const flags = parseCloudFlags(args.slice(1));
     const slug = flags._[0];
     if (!slug) fail(`usage: agentlas cloud ${sub} <slug> [--json]`);
-    const result = await deleteCloudAgentCli(slug);
+    const result = await deleteCloudAgentCli(slug, { scope: flags.scope });
     out(flags.json ? JSON.stringify(result, null, 2) : `✓ deleted ${result.slug || slug}`);
+    if (!flags.json && Array.isArray(result.localStateWarnings)) {
+      for (const warning of result.localStateWarnings) out(`  warning: ${warning}`);
+    }
     return;
   }
   const cloudRuntime = require("./agentlas-cloud-runtime.cjs");
@@ -884,14 +1094,15 @@ async function cmdCloud(db, args, runtimeOverride) {
     return;
   }
   if (sub === "install") return cmdCloudInstall(db, args[1]);
-  if (sub !== "package" && sub !== "publish") fail("usage: agentlas cloud <package|publish|install|delete> ...");
+  if (sub !== "package" && sub !== "save" && sub !== "publish") fail("usage: agentlas cloud <save|publish|package|list|restore|install|delete> ...");
   const flags = parseCloudFlags(args.slice(1));
   const root = flags._[0];
   if (!root) fail(`usage: agentlas cloud ${sub} <path>`);
+  const visibility = cloudVisibilityForAction(sub, flags);
   const dryRun = sub === "package" || Boolean(flags["dry-run"]);
   const result = await packageCloudAgentCli(db, root, {
     slug: typeof flags.slug === "string" ? flags.slug : undefined,
-    visibility: flags.visibility === "private-link" ? "private-link" : "marketplace",
+    visibility,
     llmReview: Boolean(flags["llm-review"]),
     dryRun,
     runtimeOverride,
@@ -901,51 +1112,74 @@ async function cmdCloud(db, args, runtimeOverride) {
     return;
   }
   printCloudPackageResult(result);
-  if (sub === "publish" && result.status === "blocked") process.exit(1);
+  if ((sub === "save" || sub === "publish") && result.status === "blocked") process.exit(1);
 }
 
 async function packageCloudAgentCli(db, root, opts) {
-  const rootPath = path.resolve(root);
+  const requestedRoot = path.resolve(root);
   let st;
-  try { st = fs.statSync(rootPath); } catch { fail(`폴더를 찾을 수 없습니다: ${root}`); }
-  if (!st.isDirectory()) fail(`폴더가 아닙니다: ${root}`);
+  try { st = fs.lstatSync(requestedRoot); } catch { throw new Error(`폴더를 찾을 수 없습니다: ${root}`); }
+  if (!st.isDirectory() || st.isSymbolicLink()) throw new Error(`실제 폴더가 아닙니다: ${root}`);
+  const rootPath = fs.realpathSync.native(requestedRoot);
+  const visibility = opts.visibility || "private-link";
+  const isPublicHubPublish = visibility === "marketplace";
   const scan = scanCloudFolderCli(rootPath);
-  const routingCard = readCloudRoutingCardCli(rootPath);
+  let snapshot = cloudPackageSnapshot(scan.included);
+  let careerGraph;
+  if (isPublicHubPublish) {
+    careerGraph = cloudReadPublicCareerCard(snapshot, scan.findings);
+    cloudReplacePublicCareerCard(scan, careerGraph);
+    snapshot = cloudPackageSnapshot(scan.included);
+  }
+  const routingCard = isPublicHubPublish ? readCloudRoutingCardCli(snapshot) : {};
   if (routingCard.finding) scan.findings.push(routingCard.finding);
-  const name = cloudReadName(rootPath);
-  const slug = cloudSlug(opts.slug || cloudReadStableSlug(rootPath) || name || path.basename(rootPath));
-  const packageHash = cloudHashPackage(scan.included);
+  const packageFindings = isPublicHubPublish ? scan.findings : privateCloudSafetyFindingsCli(scan.findings);
+  const name = cloudReadName(snapshot, path.basename(rootPath));
+  const slug = cloudSlug(opts.slug || cloudReadStableSlug(snapshot) || name || path.basename(rootPath));
+  const scope = cloudScopeForVisibility(visibility);
+  const baseDescriptor = cloudBaseDescriptorForSourceCli(scan.localPackageMarker, rootPath, slug, scope);
+  const packageHashVersion = CLOUD_PACKAGE_HASH_V2;
+  const packageHash = cloudHashPackage(scan.included, packageHashVersion);
   const manifest = {
     version: "0.1",
     kind: "agentlas-cloud-agent",
     slug,
     name,
-    tagline: cloudReadTagline(rootPath),
-    agentKind: cloudInferKind(rootPath),
-    runtimeLabels: detectRuntimeLabels(rootPath),
-    visibility: opts.visibility || "marketplace",
-    rootFingerprint: sha(rootPath),
+    tagline: cloudReadTagline(snapshot),
+    agentKind: cloudInferKind(snapshot),
+    runtimeLabels: cloudDetectRuntimeLabels(snapshot),
+    visibility,
+    // Content-derived and host-independent. Never persist an absolute local
+    // path fingerprint into a portable Cloud package.
+    rootFingerprint: sha(`agentlas-package-root:${packageHash}`),
     packageHash,
+    packageHashVersion,
     fileCount: scan.files.length,
     includedFileCount: scan.included.length,
     totalBytes: scan.included.reduce((sum, file) => sum + file.bytes, 0),
     createdAt: new Date().toISOString(),
-    billingMode: opts.llmReview ? "submitter-local-runtime" : "static-only",
-    costOwner: opts.llmReview ? "submitter" : "none",
-    security: cloudSecuritySummary(scan.findings),
+    billingMode: isPublicHubPublish && opts.llmReview ? "submitter-local-runtime" : "static-only",
+    costOwner: isPublicHubPublish && opts.llmReview ? "submitter" : "none",
+    security: cloudSecuritySummary(packageFindings),
+    ...(careerGraph ? { careerGraph } : {}),
   };
   if (routingCard.card) manifest.routingCard = routingCard.card;
   const packageDir = cloudPackageDir(slug);
   fs.mkdirSync(packageDir, { recursive: true });
   const manifestPath = path.join(packageDir, "package.manifest.json");
   const bundlePath = path.join(packageDir, "package.bundle.json");
-  const bundle = { manifest, files: scan.included, source: { packagedBy: "agentlas-cli", packagedAt: manifest.createdAt, costOwner: manifest.costOwner } };
+  const bundle = {
+    manifest,
+    files: scan.included,
+    source: { packagedBy: "agentlas-cli", packagedAt: manifest.createdAt, costOwner: manifest.costOwner },
+    ...(careerGraph ? { careerGraph } : {}),
+  };
   fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
   fs.writeFileSync(bundlePath, JSON.stringify(bundle, null, 2) + "\n", "utf8");
-  const review = opts.llmReview
-    ? await runCloudLocalReviewCli(db, rootPath, manifest, scan.findings, opts.runtimeOverride)
-    : cloudStaticReview(scan.findings);
-  const allFindings = [...scan.findings, ...review.findings.filter((f) => !scan.findings.some((s) => s.id === f.id))];
+  const review = isPublicHubPublish && opts.llmReview
+    ? await runCloudLocalReviewCli(db, rootPath, manifest, packageFindings, opts.runtimeOverride)
+    : cloudStaticReview(packageFindings, isPublicHubPublish ? "hub-public" : "owner-private");
+  const allFindings = [...packageFindings, ...review.findings.filter((f) => !packageFindings.some((s) => s.id === f.id))];
   manifest.security = cloudSecuritySummary(allFindings);
   fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
   fs.writeFileSync(bundlePath, JSON.stringify({ ...bundle, manifest }, null, 2) + "\n", "utf8");
@@ -953,7 +1187,34 @@ async function packageCloudAgentCli(db, root, opts) {
   let registration = null;
   let status = blocked ? "blocked" : opts.dryRun ? "dry-run" : "ready";
   if (!blocked && !opts.dryRun) {
-    registration = await registerCloudAgentCli(manifest, bundlePath, review, opts.visibility || "marketplace");
+    registration = await registerCloudAgentCli(manifest, bundlePath, review, visibility, { baseDescriptor });
+    let descriptor;
+    try {
+      descriptor = rememberCloudAssetDescriptorCli(registration, { sourceRoot: rootPath });
+    } catch (error) {
+      const stateError = new Error(
+        `Cloud save committed on the server, but this machine could not persist revision ${registration.revision}. ` +
+        "Do not retry blindly; run `agentlas cloud list` and restore the asset before the next update. " +
+        `Local state error: ${error.message || error}`,
+      );
+      stateError.code = "AGENTLAS_CLOUD_LOCAL_STATE_COMMIT_FAILED";
+      stateError.receipt = registration;
+      throw stateError;
+    }
+    try {
+      writeCloudSourceMarkerCli(rootPath, scan, descriptor, {
+        previousMarker: scan.localPackageMarker,
+        packageHash,
+        packageHashVersion,
+        fileCount: scan.included.length,
+        totalBytes: manifest.totalBytes,
+        executablePaths: packageHashVersion === CLOUD_PACKAGE_HASH_V2
+          ? scan.included.filter((file) => file.executable).map((file) => file.path).sort()
+          : undefined,
+      });
+    } catch (error) {
+      registration.localStateWarning = `Cloud save succeeded, but the source marker could not be updated: ${error.message || error}`;
+    }
     status = "registered";
   }
   return {
@@ -966,83 +1227,466 @@ async function packageCloudAgentCli(db, root, opts) {
     files: scan.files,
     review,
     registration,
-    summary: status === "registered" ? `Registered ${slug}.` : status === "blocked" ? `Blocked: ${review.summary}` : `Ready: ${slug}.`,
+    summary: status === "registered"
+      ? isPublicHubPublish
+        ? `Published ${slug} publicly to Agentlas Hub.`
+        : `Saved ${slug} privately in Agent Cloud.`
+      : status === "blocked"
+        ? isPublicHubPublish
+          ? `Hub publish blocked: ${review.summary}`
+          : `Private Agent Cloud save blocked: ${review.summary}`
+        : isPublicHubPublish
+          ? `Hub package ready: ${slug}.`
+          : `Private Agent Cloud package ready: ${slug}.`,
   };
 }
 
+function cloudScopeForVisibility(visibility) {
+  return visibility === "marketplace" ? "hub-public" : "owner-private";
+}
+
+function normalizeCloudScopeFlagCli(value) {
+  if (value === "owner-private" || value === "private" || value === "private-link") return "owner-private";
+  if (value === "hub-public" || value === "marketplace" || value === "public") return "hub-public";
+  return null;
+}
+
+function cloudRevisionEtag(revision) {
+  return `"${revision}"`;
+}
+
+function normalizeCloudAssetDescriptorCli(value, label = "cloud asset descriptor") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} is missing`);
+  }
+  const cloudId = typeof value.cloudId === "string" ? value.cloudId.trim() : "";
+  const slug = typeof value.slug === "string" ? value.slug.trim() : "";
+  const scope = value.scope;
+  const packageHash = String(value.packageHash || "").replace(/^sha256:/i, "").toLowerCase();
+  const packageHashVersion = cloudPackageHashVersion(value.packageHashVersion);
+  const revision = typeof value.revision === "string" ? value.revision : "";
+  const etag = typeof value.etag === "string" ? value.etag : cloudRevisionEtag(revision);
+  const updatedAt = typeof value.updatedAt === "string"
+    ? value.updatedAt
+    : typeof value.savedAt === "string"
+      ? value.savedAt
+      : typeof value.registeredAt === "string"
+        ? value.registeredAt
+        : "";
+  if (!/^[A-Za-z0-9_-]{8,128}$/.test(cloudId)) {
+    throw new Error(`${label} cloudId is invalid`);
+  }
+  if (!slug || cloudSlug(slug) !== slug) throw new Error(`${label} slug is invalid`);
+  if (!CLOUD_ASSET_SCOPES.has(scope)) throw new Error(`${label} scope is invalid`);
+  if (!/^[a-f0-9]{64}$/.test(packageHash) || !packageHashVersion) {
+    throw new Error(`${label} package identity is invalid`);
+  }
+  if (!revision || revision.length > 512 || /["\\\u0000-\u001f\u007f]/.test(revision)) {
+    throw new Error(`${label} revision is invalid`);
+  }
+  if (etag !== cloudRevisionEtag(revision)) throw new Error(`${label} ETag does not authenticate revision`);
+  if (!updatedAt || !Number.isFinite(Date.parse(updatedAt))) throw new Error(`${label} updatedAt is invalid`);
+  return { cloudId, slug, scope, packageHash, packageHashVersion, revision, etag, updatedAt };
+}
+
+function cloudDescriptorKey(descriptor) {
+  return `${descriptor.scope}:${descriptor.slug}`;
+}
+
+function cloudAssetStatePathCli() {
+  return path.join(userDataDir(), CLOUD_ASSET_STATE_FILE);
+}
+
+function readCloudAssetStateCli() {
+  const statePath = cloudAssetStatePathCli();
+  if (!fs.existsSync(statePath)) return { schemaVersion: 1, assets: {}, deletedBases: [] };
+  let fd;
+  try {
+    fd = fs.openSync(statePath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || stat.size > 1024 * 1024) throw new Error("state file is not a bounded regular file");
+    const parsed = JSON.parse(fs.readFileSync(fd, "utf8"));
+    if (!parsed || parsed.schemaVersion !== 1 || !parsed.assets || typeof parsed.assets !== "object" || Array.isArray(parsed.assets)) {
+      throw new Error("state schema is invalid");
+    }
+    const assets = {};
+    for (const [key, raw] of Object.entries(parsed.assets)) {
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`state entry ${key} is invalid`);
+      const descriptor = normalizeCloudAssetDescriptorCli(raw.descriptor, `state entry ${key}`);
+      if (key !== cloudDescriptorKey(descriptor)) throw new Error(`state entry ${key} key is invalid`);
+      const sourceRoots = Array.isArray(raw.sourceRoots)
+        ? [...new Set(raw.sourceRoots.filter((item) => typeof item === "string" && path.isAbsolute(item)).map((item) => path.resolve(item)))].slice(0, 32)
+        : [];
+      assets[key] = { descriptor, sourceRoots };
+    }
+    const deletedBases = Array.isArray(parsed.deletedBases)
+      ? parsed.deletedBases.filter((item) =>
+          item && typeof item === "object" && !Array.isArray(item) &&
+          typeof item.rootPath === "string" && path.isAbsolute(item.rootPath) &&
+          typeof item.slug === "string" && cloudSlug(item.slug) === item.slug &&
+          CLOUD_ASSET_SCOPES.has(item.scope) && typeof item.cloudId === "string" &&
+          typeof item.revision === "string"
+        ).map((item) => ({
+          rootPath: path.resolve(item.rootPath),
+          slug: item.slug,
+          scope: item.scope,
+          cloudId: item.cloudId,
+          revision: item.revision,
+        })).slice(-256)
+      : [];
+    return { schemaVersion: 1, assets, deletedBases };
+  } catch (error) {
+    throw new Error(`Agent Cloud local revision state is unreadable: ${error.message || error}`);
+  } finally {
+    if (fd !== undefined) try { fs.closeSync(fd); } catch { /* best-effort */ }
+  }
+}
+
+function writeCloudAssetStateCli(state) {
+  const statePath = cloudAssetStatePathCli();
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  const temp = `${statePath}.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
+  const fd = fs.openSync(temp, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o600);
+  try {
+    fs.writeFileSync(fd, JSON.stringify(state, null, 2) + "\n", "utf8");
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(temp, statePath);
+  cloudApplyPortableFileMode(statePath, 0o600);
+  cloudFsyncDirectoryCli(path.dirname(statePath));
+}
+
+function rememberCloudAssetDescriptorCli(value, options = {}) {
+  const descriptor = normalizeCloudAssetDescriptorCli(value);
+  const state = readCloudAssetStateCli();
+  const key = cloudDescriptorKey(descriptor);
+  const previous = state.assets[key];
+  const sameRevision = previous && previous.descriptor.cloudId === descriptor.cloudId && previous.descriptor.revision === descriptor.revision;
+  const roots = sameRevision ? [...previous.sourceRoots] : [];
+  if (options.sourceRoot) {
+    const sourceRoot = path.resolve(options.sourceRoot);
+    roots.push(sourceRoot);
+    state.deletedBases = state.deletedBases.filter(
+      (item) => !(item.rootPath === sourceRoot && item.slug === descriptor.slug && item.scope === descriptor.scope),
+    );
+  }
+  state.assets[key] = { descriptor, sourceRoots: [...new Set(roots)].slice(0, 32) };
+  writeCloudAssetStateCli(state);
+  return descriptor;
+}
+
+function findCloudAssetDescriptorCli(slug, scope) {
+  const safeSlug = cloudSlug(slug);
+  const state = readCloudAssetStateCli();
+  const matches = Object.values(state.assets).filter(
+    (entry) => entry.descriptor.slug === safeSlug && (!scope || entry.descriptor.scope === scope),
+  );
+  if (!scope && matches.length > 1) {
+    throw new Error(`Cloud asset ${safeSlug} exists in multiple scopes. Retry with --scope owner-private or --scope hub-public.`);
+  }
+  return matches.length === 1 ? matches[0] : null;
+}
+
+function cloudMarkerDescriptorsCli(marker) {
+  const descriptors = {};
+  if (!marker || typeof marker !== "object" || Array.isArray(marker)) return descriptors;
+  if (marker.cloudAssets && typeof marker.cloudAssets === "object" && !Array.isArray(marker.cloudAssets)) {
+    for (const scope of CLOUD_ASSET_SCOPES) {
+      if (!marker.cloudAssets[scope]) continue;
+      try {
+        const descriptor = normalizeCloudAssetDescriptorCli(marker.cloudAssets[scope], `local marker ${scope}`);
+        if (descriptor.scope === scope) descriptors[scope] = descriptor;
+      } catch { /* legacy or corrupt CAS entry is not adopted as a base revision */ }
+    }
+  }
+  if (marker.revision && marker.cloudId && marker.scope) {
+    try {
+      const descriptor = normalizeCloudAssetDescriptorCli(marker, "local marker");
+      if (!descriptors[descriptor.scope]) descriptors[descriptor.scope] = descriptor;
+    } catch { /* legacy marker */ }
+  }
+  return descriptors;
+}
+
+function cloudBaseDescriptorFromMarkerCli(marker, slug, scope) {
+  const descriptor = cloudMarkerDescriptorsCli(marker)[scope];
+  return descriptor && descriptor.slug === slug ? descriptor : null;
+}
+
+function cloudBaseDescriptorForSourceCli(marker, rootPath, slug, scope) {
+  const state = readCloudAssetStateCli();
+  const normalizedRoot = path.resolve(rootPath);
+  let markerDescriptor = cloudBaseDescriptorFromMarkerCli(marker, slug, scope);
+  if (markerDescriptor && state.deletedBases.some((item) =>
+    item.rootPath === normalizedRoot && item.slug === slug && item.scope === scope &&
+    item.cloudId === markerDescriptor.cloudId && item.revision === markerDescriptor.revision
+  )) {
+    markerDescriptor = null;
+  }
+  const entry = state.assets[`${scope}:${slug}`];
+  const stateDescriptor = entry && entry.sourceRoots.includes(normalizedRoot) ? entry.descriptor : null;
+  if (!markerDescriptor) return stateDescriptor;
+  if (!stateDescriptor) return markerDescriptor;
+  return stateDescriptor.cloudId === markerDescriptor.cloudId && stateDescriptor.updatedAt >= markerDescriptor.updatedAt
+    ? stateDescriptor
+    : markerDescriptor;
+}
+
+function writeCloudSourceMarkerCli(rootPath, scan, descriptor, options = {}) {
+  const markerPath = path.join(rootPath, CLOUD_RESTORE_MARKER_PATH);
+  if (fs.existsSync(markerPath)) {
+    const stat = fs.lstatSync(markerPath);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("Agent Cloud revision marker is not a regular file");
+  }
+  const descriptors = cloudMarkerDescriptorsCli(options.previousMarker);
+  if (descriptor) descriptors[descriptor.scope] = descriptor;
+  if (options.removeDescriptor) {
+    const current = descriptors[options.removeDescriptor.scope];
+    if (current && current.cloudId === options.removeDescriptor.cloudId && current.revision === options.removeDescriptor.revision) {
+      delete descriptors[options.removeDescriptor.scope];
+    }
+  }
+  const latest = descriptor || Object.values(descriptors)[0] || null;
+  const marker = {
+    schemaVersion: 1,
+    source: "agentlas-cloud",
+    slug: latest?.slug || options.removeDescriptor?.slug || cloudSlug(path.basename(rootPath)),
+    packageHash: descriptor?.packageHash || options.packageHash || options.previousMarker?.packageHash || "",
+    packageHashVersion: descriptor?.packageHashVersion || options.packageHashVersion || options.previousMarker?.packageHashVersion || CLOUD_PACKAGE_HASH_V1,
+    fileCount: Number.isSafeInteger(options.fileCount) ? options.fileCount : (options.previousMarker?.fileCount || 0),
+    totalBytes: Number.isSafeInteger(options.totalBytes) ? options.totalBytes : (options.previousMarker?.totalBytes || 0),
+    executablePaths: Array.isArray(options.executablePaths) ? options.executablePaths : options.previousMarker?.executablePaths,
+    cloudAssets: descriptors,
+    ...(latest ? latest : {}),
+    restoredAt: options.previousMarker?.restoredAt,
+    savedAt: new Date().toISOString(),
+  };
+  for (const key of Object.keys(marker)) if (marker[key] === undefined) delete marker[key];
+  const temp = path.join(rootPath, `.${CLOUD_RESTORE_MARKER_PATH}.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`);
+  const fd = fs.openSync(temp, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o600);
+  try {
+    fs.writeFileSync(fd, JSON.stringify(marker, null, 2) + "\n", "utf8");
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(temp, markerPath);
+  cloudApplyPortableFileMode(markerPath, 0o600);
+  cloudFsyncDirectoryCli(rootPath);
+  return marker;
+}
+
+function readCloudSourceMarkerCli(rootPath) {
+  const markerPath = path.join(rootPath, CLOUD_RESTORE_MARKER_PATH);
+  if (!fs.existsSync(markerPath)) return null;
+  let fd;
+  try {
+    fd = fs.openSync(markerPath, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    const stat = fs.fstatSync(fd);
+    if (!stat.isFile() || stat.size > 1024 * 1024) throw new Error("marker is not a bounded regular file");
+    return JSON.parse(fs.readFileSync(fd, "utf8"));
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
 function scanCloudFolderCli(rootPath) {
   const files = [];
   const included = [];
   const findings = [];
+  const restoredExecutablePaths = cloudReadRestoreExecutablePaths(rootPath);
+  let localPackageMarker = null;
   let totalBytes = 0;
   let count = 0;
   let hasDefinition = false;
   function addFinding(kind, severity, category, message, file, remediation) {
     findings.push({ id: `${kind}-${sha(file || message).slice(0, 10)}`, severity, category, message, ...(file ? { file } : {}), ...(remediation ? { remediation } : {}) });
   }
+  function insideRoot(candidate) {
+    const relative = path.relative(rootPath, candidate);
+    return relative === "" || (relative && !relative.startsWith("..") && !path.isAbsolute(relative));
+  }
+  function readStableFile(file, rel) {
+    const beforeReal = fs.realpathSync.native(file);
+    if (!insideRoot(beforeReal)) throw new Error("file resolves outside the approved package root");
+    const noFollow = fs.constants.O_NOFOLLOW || 0;
+    const nonBlock = fs.constants.O_NONBLOCK || 0;
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow | nonBlock);
+    try {
+      const before = fs.fstatSync(fd);
+      if (!before.isFile()) throw new Error("package entry is not a regular file");
+      if (before.size > CLOUD_MAX_FILE_BYTES) throw new Error(`file exceeds ${CLOUD_MAX_FILE_BYTES} bytes`);
+      const chunks = [];
+      let actualBytes = 0;
+      for (;;) {
+        const capacity = Math.min(64 * 1024, CLOUD_MAX_FILE_BYTES + 1 - actualBytes);
+        if (capacity <= 0) throw new Error(`file exceeds ${CLOUD_MAX_FILE_BYTES} bytes`);
+        const chunk = Buffer.allocUnsafe(capacity);
+        const read = fs.readSync(fd, chunk, 0, chunk.length, null);
+        if (read === 0) break;
+        actualBytes += read;
+        if (actualBytes > CLOUD_MAX_FILE_BYTES) throw new Error(`file exceeds ${CLOUD_MAX_FILE_BYTES} bytes`);
+        chunks.push(chunk.subarray(0, read));
+      }
+      const after = fs.fstatSync(fd);
+      const afterReal = fs.realpathSync.native(file);
+      const pathStat = fs.statSync(file);
+      if (
+        !insideRoot(afterReal) || beforeReal !== afterReal ||
+        before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size ||
+        before.mode !== after.mode || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs ||
+        after.dev !== pathStat.dev || after.ino !== pathStat.ino || after.mode !== pathStat.mode ||
+        actualBytes !== after.size
+      ) {
+        throw new Error("package entry changed while it was being read");
+      }
+      return {
+        bytes: Buffer.concat(chunks, actualBytes),
+        executable: cloudPortableExecutableForFile(rel, after.mode, restoredExecutablePaths),
+      };
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
   function walk(dir) {
-    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    let directoryBefore;
+    let directoryRealBefore;
+    try {
+      directoryBefore = fs.lstatSync(dir);
+      directoryRealBefore = fs.realpathSync.native(dir);
+      if (!directoryBefore.isDirectory() || directoryBefore.isSymbolicLink() || !insideRoot(directoryRealBefore)) {
+        throw new Error("directory is not stable inside the approved root");
+      }
+    } catch (error) {
+      addFinding("unsafe-directory", "blocker", "policy", `Package directory could not be read safely: ${error.message || error}`, path.relative(rootPath, dir).split(path.sep).join("/"), "Remove linked or changing directories and retry.");
+      return;
+    }
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (error) {
+      addFinding("unsafe-directory", "blocker", "policy", `Package directory could not be read safely: ${error.message || error}`, path.relative(rootPath, dir).split(path.sep).join("/"), "Remove linked or changing directories and retry.");
+      return;
+    }
     for (const entry of entries) {
       if (entry.name.startsWith("._")) continue;
       const abs = path.join(dir, entry.name);
       const rel = path.relative(rootPath, abs).split(path.sep).join("/");
+      if (cloudPortablePathKey(rel) === cloudPortablePathKey(CLOUD_RESTORE_MARKER_PATH)) {
+        // Local restore/CAS metadata is runtime state, never portable asset
+        // data, but it must be captured with the same no-follow stability gate.
+        if (entry.isSymbolicLink() || !entry.isFile()) {
+          addFinding("unsafe-local-state", "blocker", "policy", "Agent Cloud local revision marker must be a stable regular file.", rel, "Remove the linked or special marker and restore/list the asset again.");
+          continue;
+        }
+        try {
+          const stableMarker = readStableFile(abs, rel);
+          localPackageMarker = JSON.parse(stableMarker.bytes.toString("utf8"));
+        } catch (error) {
+          addFinding("invalid-local-state", "blocker", "policy", `Agent Cloud local revision marker could not be read safely: ${error.message || error}`, rel, "Repair or remove the marker, then restore/list the asset again.");
+        }
+        continue;
+      }
       if (entry.isSymbolicLink()) {
         addFinding("symlink", "blocker", "policy", "Symbolic links are not allowed in cloud agent packages.", rel, "Replace the symlink with an ordinary file or remove it.");
         files.push({ path: rel, bytes: 0, sha256: "", kind: "binary", included: false, reason: "symlink-blocked" });
         continue;
       }
       if (entry.isDirectory()) {
-        if (!CLOUD_SKIP_DIRS.has(entry.name)) walk(abs);
+        if (CLOUD_SKIP_DIRS.has(entry.name)) continue;
+        walk(abs);
+        continue;
+      }
+      if (!entry.isFile()) {
+        addFinding("unsupported-entry", "blocker", "policy", "Only stable ordinary files and directories are allowed in Cloud packages.", rel, "Remove sockets, FIFOs, devices, and other special filesystem entries.");
+        files.push({ path: rel, bytes: 0, sha256: "", kind: "binary", included: false, reason: "unsupported-entry" });
+        continue;
+      }
+      if (!cloudPortableRelativePath(rel)) {
+        addFinding("unsafe-path", "blocker", "policy", "File path is not portable across supported hosts.", rel, "Rename the file to a Unicode NFC, relative, cross-platform-safe path.");
+        files.push({ path: rel, bytes: 0, sha256: "", kind: "binary", included: false, reason: "unsafe-path" });
         continue;
       }
-      if (!entry.isFile()) continue;
       count++;
       if (count > CLOUD_MAX_FILES) {
         addFinding("file-count-limit", "blocker", "size", `Package has more than ${CLOUD_MAX_FILES} files.`, "", "Publish a focused agent/team folder.");
         continue;
       }
       if (CLOUD_AGENT_FILES.has(entry.name)) hasDefinition = true;
-      const stat = fs.statSync(abs);
-      totalBytes += stat.size;
-      const digest = sha(fs.readFileSync(abs));
+      let hint;
+      try { hint = fs.lstatSync(abs); } catch { hint = { size: 0 }; }
       if (CLOUD_BLOCKED_FILE_RE.some((re) => re.test(entry.name))) {
         addFinding("blocked-file", "blocker", "secret", "Secret-bearing file names are not allowed in cloud packages.", rel, "Remove credentials and publish only env key names.");
-        files.push({ path: rel, bytes: stat.size, sha256: digest, kind: "binary", included: false, reason: "secret-file-blocked" });
+        files.push({ path: rel, bytes: Number(hint.size) || 0, sha256: "", kind: "binary", included: false, reason: "secret-file-blocked" });
         continue;
       }
-      if (stat.size > CLOUD_MAX_FILE_BYTES) {
-        addFinding("large-file", "high", "size", `File exceeds ${CLOUD_MAX_FILE_BYTES} bytes.`, rel, "Move large assets out of the package.");
-        files.push({ path: rel, bytes: stat.size, sha256: digest, kind: "binary", included: false, reason: "file-too-large" });
+      if (Number(hint.size) > CLOUD_MAX_FILE_BYTES) {
+        addFinding("large-file", "blocker", "size", `File exceeds ${CLOUD_MAX_FILE_BYTES} bytes.`, rel, "Move large assets out of the package.");
+        files.push({ path: rel, bytes: Number(hint.size), sha256: "", kind: "binary", included: false, reason: "file-too-large" });
         continue;
       }
       const ext = path.extname(entry.name).toLowerCase();
       const isText = CLOUD_TEXT_EXTS.has(ext) || CLOUD_AGENT_FILES.has(entry.name);
-      if (!isText) {
-        files.push({ path: rel, bytes: stat.size, sha256: digest, kind: "binary", included: false, reason: "binary-skipped" });
+      let stable;
+      try {
+        stable = readStableFile(abs, rel);
+      } catch (error) {
+        addFinding("unstable-file", "blocker", "policy", `Package file could not be read safely: ${error.message || error}`, rel, "Remove linked or concurrently changing files and retry.");
+        files.push({ path: rel, bytes: Number(hint.size) || 0, sha256: "", kind: isText ? "text" : "binary", included: false, reason: "unstable-file" });
         continue;
       }
-      const text = fs.readFileSync(abs, "utf8");
-      for (const [id, re, label] of CLOUD_SECRET_RE) {
-        if (re.test(text)) addFinding(id, "blocker", "secret", `Possible ${label} found in package content.`, rel, "Remove the value and require users to configure their own key.");
+      const content = stable.bytes;
+      const executable = stable.executable;
+      totalBytes += content.length;
+      const digest = sha(content);
+      cloudAddSecretFindingsFromBytes(content, rel, addFinding);
+      if (isText) {
+        const decoded = cloudDecodeTextAsset(content);
+        if (!decoded.ok) {
+          addFinding("invalid-text-encoding", "blocker", "policy", "A text agent asset is not valid UTF-8 or BOM-marked UTF-16.", rel, "Save the file as UTF-8 or BOM-marked UTF-16 before packaging.");
+          files.push({ path: rel, bytes: content.length, sha256: digest, kind: "text", executable, included: false, reason: "invalid-text-encoding" });
+          continue;
+        }
+        const text = decoded.text;
+        if (/(?:curl|wget)[^\n|&;]+[|]\s*(?:sh|bash)/i.test(text)) {
+          addFinding("curl-pipe-shell", "high", "network", "Remote shell install pattern detected.", rel, "Use explicit, reviewable install steps.");
+        }
       }
-      if (/(?:curl|wget)[^\n|&;]+[|]\s*(?:sh|bash)/i.test(text)) {
-        addFinding("curl-pipe-shell", "high", "network", "Remote shell install pattern detected.", rel, "Use explicit, reviewable install steps.");
+      files.push({ path: rel, bytes: content.length, sha256: digest, kind: isText ? "text" : "binary", executable, included: true });
+      included.push({ path: rel, bytes: content.length, sha256: digest, executable, contentBase64: content.toString("base64") });
+    }
+    try {
+      const directoryAfter = fs.lstatSync(dir);
+      const directoryRealAfter = fs.realpathSync.native(dir);
+      if (
+        !directoryAfter.isDirectory() || directoryAfter.isSymbolicLink() || !insideRoot(directoryRealAfter) ||
+        directoryRealBefore !== directoryRealAfter || directoryBefore.dev !== directoryAfter.dev ||
+        directoryBefore.ino !== directoryAfter.ino || directoryBefore.mtimeMs !== directoryAfter.mtimeMs ||
+        directoryBefore.ctimeMs !== directoryAfter.ctimeMs
+      ) {
+        throw new Error("directory changed while it was scanned");
       }
-      files.push({ path: rel, bytes: stat.size, sha256: digest, kind: "text", included: true });
-      included.push({ path: rel, bytes: stat.size, sha256: digest, contentBase64: Buffer.from(text, "utf8").toString("base64") });
+    } catch (error) {
+      addFinding("unstable-directory", "blocker", "policy", `Package directory changed while it was scanned: ${error.message || error}`, path.relative(rootPath, dir).split(path.sep).join("/"), "Stop concurrent edits and retry.");
     }
   }
   walk(rootPath);
+  const pathConflict = cloudPortablePathConflict(included.map((file) => file.path));
+  if (pathConflict) {
+    addFinding(pathConflict.code, "blocker", "policy", pathConflict.message, "", "Rename aliased paths so every file and ancestor directory has one portable identity.");
+  }
   if (!hasDefinition) addFinding("missing-agent-definition", "blocker", "structure", "No agent definition file was found.", "", "Add AGENTS.md, CLAUDE.md, GEMINI.md, AGENT.md, or README.md at the package root.");
   if (totalBytes > CLOUD_MAX_TOTAL_BYTES) addFinding("package-size-limit", "blocker", "size", `Package exceeds ${CLOUD_MAX_TOTAL_BYTES} bytes.`, "", "Publish a smaller agent folder.");
-  files.sort((a, b) => a.path.localeCompare(b.path));
-  included.sort((a, b) => a.path.localeCompare(b.path));
-  return { files, included, findings, totalBytes };
+  files.sort(cloudCodePointPathOrder);
+  included.sort(cloudCodePointPathOrder);
+  return { files, included, findings, totalBytes, localPackageMarker };
 }
 
-function readCloudRoutingCardCli(rootPath) {
-  const abs = path.join(rootPath, CLOUD_ROUTING_CARD_PATH);
-  if (!fs.existsSync(abs)) {
+function readCloudRoutingCardCli(snapshot) {
+  const file = snapshot.get(CLOUD_ROUTING_CARD_PATH);
+  if (!file) {
     return {
       finding: {
         id: "routing-card-required",
@@ -1055,7 +1699,7 @@ function readCloudRoutingCardCli(rootPath) {
     };
   }
   try {
-    const parsed = JSON.parse(fs.readFileSync(abs, "utf8"));
+    const parsed = JSON.parse(Buffer.from(file.contentBase64, "base64").toString("utf8"));
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return cloudRoutingCardFinding("routing-card-invalid", "Routing card must be a JSON object.", "Replace .agentlas/routing-card.json with a routing-card/2.0 object.");
     }
@@ -1100,14 +1744,25 @@ function cloudRoutingCardProblem(card) {
   return null;
 }
 
-function cloudStaticReview(findings) {
+function privateCloudSafetyFindingsCli(findings) {
+  return findings.filter((finding) =>
+    (finding.severity === "blocker" && !finding.id.startsWith("missing-agent-definition"))
+    || finding.category === "secret"
+    || finding.category === "size");
+}
+
+function cloudStaticReview(findings, scope = "hub-public") {
   const blockers = findings.filter((f) => f.severity === "blocker").length;
   const high = findings.filter((f) => f.severity === "high").length;
   return {
     mode: "static-only",
     verdict: blockers ? "fail" : high ? "needs-review" : "pass",
     costOwner: "none",
-    summary: blockers || high ? `${blockers} blocker(s), ${high} high-risk finding(s).` : "Static package review passed.",
+    summary: blockers || high
+      ? `${blockers} blocker(s), ${high} high-risk finding(s).`
+      : scope === "owner-private"
+        ? "Private Agent Cloud safety checks passed."
+        : "Static public package review passed.",
     findings,
     reviewedAt: new Date().toISOString(),
   };
@@ -1153,42 +1808,178 @@ async function runCloudLocalReviewCli(db, rootPath, manifest, staticFindings, ru
   };
 }
 
-async function registerCloudAgentCli(manifest, bundlePath, review, visibility) {
+function cloudCasResponseErrorCli(response, label) {
+  let body = null;
+  try { body = JSON.parse(response.text || "null"); } catch { /* generic below */ }
+  const code = body && typeof body.code === "string" ? body.code : "cloud_request_failed";
+  let message = `${label} 실패 ${response.status}`;
+  if (response.status === 412 && code === "cloud_agent_revision_conflict") {
+    const current = body && body.current ? body.current : body && body.conflict && body.conflict.current;
+    message = current
+      ? `다른 PC에서 이 Agent Cloud 자산이 변경되었습니다. 자동 덮어쓰기는 중단했습니다. \`agentlas cloud list\`로 최신 revision을 확인하고 \`agentlas cloud restore ${current.slug || "<slug>"}\`로 복원한 뒤 변경 사항을 병합하세요.`
+      : "이 Agent Cloud 자산은 다른 PC에서 삭제되었거나 다른 식별자로 다시 생성되었습니다. 자동 재생성은 중단했습니다. `agentlas cloud list`로 현재 상태를 확인하세요.";
+  } else if (response.status === 428 && code === "client_upgrade_required") {
+    message = "기존 Cloud 자산을 안전하게 갱신할 base revision이 없습니다. 서버 revision을 자동 복사하지 않습니다. `agentlas cloud list`로 확인하고 `agentlas cloud restore <slug>`로 복원한 뒤 다시 저장하세요.";
+  } else if (response.status === 503 && code === "cloud_mutations_maintenance") {
+    const retryAfter = response.headers && typeof response.headers.get === "function" ? response.headers.get("retry-after") : null;
+    message = `Agent Cloud 저장/삭제가 잠시 점검 중입니다${retryAfter ? ` (약 ${retryAfter}초 후 재시도)` : ""}. 읽기·목록·복원은 계속 사용할 수 있습니다.`;
+  } else if (body && typeof body.error === "string") {
+    message = `${label} 실패 ${response.status}: ${body.error.slice(0, 300)}`;
+  }
+  const error = new Error(message);
+  error.code = code;
+  error.status = response.status;
+  if (body && body.current) error.current = body.current;
+  if (body && body.conflict) error.conflict = body.conflict;
+  return error;
+}
+
+async function registerCloudAgentCli(manifest, bundlePath, review, visibility, options = {}) {
   const cookie = await cloudSessionCookieCli();
   if (!cookie) fail("agentlas.cloud 로그인이 필요합니다. 데스크톱 앱에서 로그인하거나 AGENTLAS_SESSION을 설정하세요.");
   if (typeof fetch !== "function") fail("이 런타임에 fetch가 없습니다(앱 런타임으로 실행 필요).");
   const base = (process.env.AGENTLAS_WEB_BASE_URL || "https://agentlas.cloud").replace(/\/$/, "");
   const bundle = JSON.parse(fs.readFileSync(bundlePath, "utf8"));
-  const resp = await fetch(`${base}/api/cloud-agents/v1/register`, {
+  const expectedScope = cloudScopeForVisibility(visibility);
+  const baseDescriptor = options.baseDescriptor
+    ? normalizeCloudAssetDescriptorCli(options.baseDescriptor, "base revision")
+    : null;
+  if (baseDescriptor && (baseDescriptor.slug !== manifest.slug || baseDescriptor.scope !== expectedScope)) {
+    throw new Error("Agent Cloud base revision does not match the requested slug/scope.");
+  }
+  const headers = { "content-type": "application/json", cookie, origin: base };
+  if (baseDescriptor) {
+    headers["if-match"] = baseDescriptor.etag;
+    headers["x-agentlas-cloud-id"] = baseDescriptor.cloudId;
+  } else {
+    headers["if-none-match"] = "*";
+  }
+  const resp = await fetchHubCli(`${base}/api/cloud-agents/v1/register`, {
     method: "POST",
-    headers: { "content-type": "application/json", cookie, origin: base },
+    headers,
     body: JSON.stringify({ manifest, bundle, review, visibility, billing: { modelCallsPaidBy: review.costOwner, localRuntime: review.runtimeLabel || null } }),
   });
-  if (!resp.ok) fail(`Agentlas Cloud 등록 실패 ${resp.status}: ${(await resp.text().catch(() => "")).slice(0, 300)}`);
-  const json = await resp.json();
+  if (!resp.ok) throw cloudCasResponseErrorCli(resp, "Agentlas Cloud 등록");
+  const json = parseHubJsonCli(resp, "Agentlas Cloud 등록");
+  const expectedSource = visibility === "marketplace" ? "hub" : "agent-cloud";
+  const expectedVisibility = visibility === "marketplace" ? "marketplace" : "owner-private";
+  const etag = resp.headers && typeof resp.headers.get === "function" ? resp.headers.get("etag") : null;
+  const cacheControl = resp.headers && typeof resp.headers.get === "function" ? resp.headers.get("cache-control") : null;
+  const expectedOperations = baseDescriptor ? new Set(["updated", "unchanged"]) : new Set(["created"]);
+  if (
+    json.schema !== "agentlas.agent_cloud.registration.v1" ||
+    !expectedOperations.has(json.operation) ||
+    json.source !== expectedSource ||
+    json.visibility !== expectedVisibility ||
+    json.scope !== expectedScope ||
+    json.owner !== true ||
+    json.publicHubPublished !== (visibility === "marketplace") ||
+    json.dryRun !== false ||
+    typeof json.cloudId !== "string" || !json.cloudId.trim() ||
+    json.slug !== manifest.slug ||
+    json.packageHash !== manifest.packageHash ||
+    json.packageHashVersion !== manifest.packageHashVersion ||
+    typeof json.revision !== "string" || etag !== cloudRevisionEtag(json.revision) ||
+    typeof json.registeredAt !== "string" || !Number.isFinite(Date.parse(json.registeredAt)) ||
+    !String(cacheControl || "").toLowerCase().includes("no-store") ||
+    (baseDescriptor && json.cloudId !== baseDescriptor.cloudId)
+  ) {
+    throw new Error("Agentlas Cloud register returned an invalid or mismatched registration receipt.");
+  }
+  const descriptor = normalizeCloudAssetDescriptorCli({
+    cloudId: json.cloudId,
+    slug: json.slug,
+    scope: json.scope,
+    packageHash: json.packageHash,
+    packageHashVersion: json.packageHashVersion,
+    revision: json.revision,
+    etag,
+    updatedAt: json.savedAt || json.registeredAt,
+  }, "registration receipt");
   return {
-    cloudId: json.cloudId || crypto.randomUUID(),
-    slug: json.slug || manifest.slug,
-    url: json.url,
-    marketplaceUrl: json.marketplaceUrl,
-    registeredAt: json.registeredAt || new Date().toISOString(),
+    ...descriptor,
+    operation: json.operation,
+    ...(typeof json.url === "string" ? { url: json.url } : {}),
+    ...(typeof json.marketplaceUrl === "string" ? { marketplaceUrl: json.marketplaceUrl } : {}),
+    registeredAt: json.registeredAt,
     dryRun: false,
   };
 }
 
-async function deleteCloudAgentCli(slug) {
+async function deleteCloudAgentCli(slug, options = {}) {
   const safeSlug = String(slug || "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
   if (!safeSlug) fail("usage: agentlas cloud delete <slug> [--json]");
   const cookie = await cloudSessionCookieCli();
   if (!cookie) fail("agentlas.cloud 로그인이 필요합니다. 데스크톱 앱에서 로그인하거나 AGENTLAS_SESSION을 설정하세요.");
   if (typeof fetch !== "function") fail("이 런타임에 fetch가 없습니다(앱 런타임으로 실행 필요).");
+  const scope = options.scope == null ? null : normalizeCloudScopeFlagCli(options.scope);
+  if (options.scope != null && !scope) throw new Error("--scope must be owner-private or hub-public");
+  const localEntry = findCloudAssetDescriptorCli(safeSlug, scope);
+  if (!localEntry) {
+    throw new Error(`No observed base revision for ${safeSlug}${scope ? ` (${scope})` : ""}. Run \`agentlas cloud list\` first, then retry the exact asset deletion.`);
+  }
+  const descriptor = localEntry.descriptor;
   const base = (process.env.AGENTLAS_WEB_BASE_URL || "https://agentlas.cloud").replace(/\/$/, "");
-  const resp = await fetch(`${base}/api/cloud-agents/v1/register?slug=${encodeURIComponent(safeSlug)}`, {
+  const query = new URLSearchParams({ slug: safeSlug, scope: descriptor.scope, cloudId: descriptor.cloudId });
+  const resp = await fetchHubCli(`${base}/api/cloud-agents/v1/register?${query.toString()}`, {
     method: "DELETE",
-    headers: { "content-type": "application/json", cookie, origin: base },
+    headers: {
+      "content-type": "application/json",
+      cookie,
+      origin: base,
+      "if-match": descriptor.etag,
+      "x-agentlas-cloud-id": descriptor.cloudId,
+    },
   });
-  if (!resp.ok) fail(`Agentlas Cloud 삭제 실패 ${resp.status}: ${(await resp.text().catch(() => "")).slice(0, 300)}`);
-  return resp.json();
+  if (!resp.ok) throw cloudCasResponseErrorCli(resp, "Agentlas Cloud 삭제");
+  const json = parseHubJsonCli(resp, "Agentlas Cloud 삭제");
+  const responseEtag = resp.headers && typeof resp.headers.get === "function" ? resp.headers.get("etag") : null;
+  const cacheControl = resp.headers && typeof resp.headers.get === "function" ? resp.headers.get("cache-control") : null;
+  const expectedSource = descriptor.scope === "hub-public" ? "hub" : "agent-cloud";
+  const expectedVisibility = descriptor.scope === "hub-public" ? "marketplace" : "owner-private";
+  const deletionTimestamp = descriptor.scope === "hub-public" ? json.unpublishedAt : json.deletedAt;
+  if (
+    json.schema !== "agentlas.agent_cloud.delete.v1" || json.ok !== true ||
+    json.source !== expectedSource || json.visibility !== expectedVisibility ||
+    json.scope !== descriptor.scope || json.cloudId !== descriptor.cloudId || json.slug !== descriptor.slug ||
+    json.packageHash !== descriptor.packageHash || json.packageHashVersion !== descriptor.packageHashVersion ||
+    json.revision !== descriptor.revision ||
+    responseEtag !== descriptor.etag || !String(cacheControl || "").toLowerCase().includes("no-store") ||
+    (descriptor.scope === "hub-public" && json.operation !== "unpublished") ||
+    typeof deletionTimestamp !== "string" || !Number.isFinite(Date.parse(deletionTimestamp))
+  ) {
+    throw new Error("Agentlas Cloud delete returned an invalid or mismatched deletion receipt.");
+  }
+  const state = readCloudAssetStateCli();
+  const key = cloudDescriptorKey(descriptor);
+  const roots = state.assets[key]?.sourceRoots || [];
+  const warnings = [];
+  for (const rootPath of roots) {
+    state.deletedBases.push({ rootPath, slug: descriptor.slug, scope: descriptor.scope, cloudId: descriptor.cloudId, revision: descriptor.revision });
+  }
+  delete state.assets[key];
+  state.deletedBases = state.deletedBases.slice(-256);
+  try {
+    writeCloudAssetStateCli(state);
+  } catch (error) {
+    const stateError = new Error(
+      `Cloud delete committed on the server, but this machine could not persist the deletion tombstone. ` +
+      "Run `agentlas cloud list` before saving this slug again. " +
+      `Local state error: ${error.message || error}`,
+    );
+    stateError.code = "AGENTLAS_CLOUD_LOCAL_STATE_COMMIT_FAILED";
+    stateError.receipt = json;
+    throw stateError;
+  }
+  for (const rootPath of roots) {
+    try {
+      const marker = readCloudSourceMarkerCli(rootPath);
+      if (marker) writeCloudSourceMarkerCli(rootPath, null, null, { previousMarker: marker, removeDescriptor: descriptor });
+    } catch (error) {
+      warnings.push(`Could not clear ${rootPath}: ${error.message || error}`);
+    }
+  }
+  return { ...json, ...(warnings.length ? { localStateWarnings: warnings } : {}) };
 }
 
 // `agentlas login`이 저장하는 CLI 세션 파일 (평문·0600 — 데스크탑의 safeStorage 파일과 별개).
@@ -1223,101 +2014,635 @@ async function cloudSessionCookieCli() {
 async function cmdCloudInstall(db, slug) {
   if (!slug) fail("usage: agentlas cloud install <slug>");
   const listing = await fetchCloudManifestCli(slug);
-  if (!listing) fail(`cloud agent를 찾을 수 없습니다: ${slug}`);
+  if (!listing) fail(`Hub agent를 찾을 수 없습니다: ${slug}`);
+  if (listing.delivery && listing.delivery.mode === "call_only") {
+    fail(`이 Hub 에이전트는 소스 설치가 허용되지 않은 call-only 자산입니다. 실행: agentlas call ${slug}`);
+  }
   const agent = persistCloudListingCli(db, listing);
-  out(`✓ installed ${agent.slug} — ${agent.name}`);
+  out(`✓ Hub installed ${agent.slug} — ${agent.name}`);
   if (agent.localPath) out(`  files: ${agent.localPath}`);
 }
 
-async function fetchCloudManifestCli(slug) {
+async function callAgentlasMcpToolCli(name, args, { requireSession = false } = {}) {
   if (typeof fetch !== "function") fail("이 런타임에 fetch가 없습니다(앱 런타임으로 실행 필요).");
   const base = process.env.AGENTLAS_MCP_BASE_URL || "https://agentlas.cloud/api/mcp/v1";
   const headers = { "content-type": "application/json" };
   const cookie = await cloudSessionCookieCli();
+  if (requireSession && !cookie) fail("Agent Cloud에는 로그인이 필요합니다. 먼저 `agentlas login`을 실행하세요.");
   if (cookie) headers.cookie = cookie;
-  const resp = await fetch(`${base.replace(/\/$/, "")}/tools/call`, {
+  const resp = await fetchHubCli(`${base.replace(/\/$/, "")}/tools/call`, {
     method: "POST",
     headers,
-    body: JSON.stringify({ method: "marketplace.get_manifest", params: { name: "marketplace.get_manifest", arguments: { kind: "agent", slug } } }),
+    body: JSON.stringify({ method: name, params: { name, arguments: args || {} } }),
   });
-  if (!resp.ok) fail(`marketplace.get_manifest 실패 ${resp.status}`);
-  const json = await resp.json();
-  if (json.error) fail(`marketplace.get_manifest: ${json.error.message || "unknown error"}`);
+  if (!resp.ok) fail(`${name} 실패 ${resp.status}`);
+  const json = parseHubJsonCli(resp, name);
+  if (json.error) fail(`${name}: ${json.error.message || "unknown error"}`);
   return json.result || null;
 }
 
+async function fetchCloudManifestCli(slug) {
+  return callAgentlasMcpToolCli("marketplace.get_manifest", { kind: "agent", slug });
+}
+
+async function listOwnedCloudAgentsCli(limit = 100) {
+  const safeLimit = Math.max(1, Math.min(100, Number.isFinite(limit) ? Math.floor(limit) : 100));
+  const result = (await callAgentlasMcpToolCli("cargo.search_agents", { q: "", limit: safeLimit }, { requireSession: true })) || {
+    schema: "agentlas.agent_cloud.search.v1",
+    source: "cloud",
+    status: "ok",
+    count: 0,
+    total: 0,
+    results: [],
+  };
+  if (!Array.isArray(result.results)) throw new Error("Agent Cloud list returned an invalid results contract.");
+  if (result.results.length) {
+    const state = readCloudAssetStateCli();
+    for (const raw of result.results) {
+      const descriptor = normalizeCloudAssetDescriptorCli(raw, "Agent Cloud list result");
+      const key = cloudDescriptorKey(descriptor);
+      const previous = state.assets[key];
+      const preserveRoots = previous && previous.descriptor.cloudId === descriptor.cloudId && previous.descriptor.revision === descriptor.revision;
+      state.assets[key] = { descriptor, sourceRoots: preserveRoots ? previous.sourceRoots : [] };
+    }
+    writeCloudAssetStateCli(state);
+  }
+  return result;
+}
+
+async function restoreOwnedCloudAgentCli(db, slug) {
+  const raw = await callAgentlasMcpToolCli("cargo.restore_package", { slug }, { requireSession: true });
+  if (!raw || raw.error) {
+    const code = raw && raw.error ? raw.error : "agent_not_found";
+    const message = raw && raw.message ? raw.message : `Agent Cloud package not found: ${slug}`;
+    throw new Error(`${code}: ${message}`);
+  }
+  const restored = normalizeOwnerRestorePayloadCli(raw, slug);
+  const cloudPackage = restored.cloudPackage;
+  const listing = {
+    slug: restored.slug || slug,
+    name: restored.name || restored.nameEn || restored.slug || slug,
+    nameEn: restored.nameEn || restored.name || restored.slug || slug,
+    tagline: restored.tagline || restored.taglineEn || "",
+    taglineEn: restored.taglineEn || restored.tagline || "",
+    trustGrade: "A",
+    visibility: "visible",
+    source: "cloud",
+    assetDescriptor: restored.descriptor,
+    cloudPackage,
+  };
+  const agent = persistCloudListingCli(db, listing);
+  let descriptor = restored.descriptor;
+  let localStateWarning;
+  try {
+    descriptor = rememberCloudAssetDescriptorCli(restored.descriptor, { sourceRoot: agent.localPath || undefined });
+  } catch (error) {
+    localStateWarning = `Restore completed, but observed revision state could not be indexed: ${error.message || error}`;
+  }
+  return {
+    schema: restored.schema || "agentlas.agent_cloud.restore.v1",
+    source: "cloud",
+    slug: agent.slug,
+    name: agent.name,
+    packageHash: cloudPackage.packageHash,
+    packageHashVersion: cloudPackage.packageHashVersion || CLOUD_PACKAGE_HASH_V1,
+    cloudId: descriptor.cloudId,
+    scope: descriptor.scope,
+    revision: descriptor.revision,
+    etag: descriptor.etag,
+    updatedAt: descriptor.updatedAt,
+    localPath: agent.localPath || null,
+    ...(localStateWarning ? { localStateWarning } : {}),
+  };
+}
+
+function normalizeOwnerRestorePayloadCli(raw, expectedSlug) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("invalid_restore_contract");
+  if (raw.schema !== "agentlas.agent_cloud.restore.v1" || raw.source !== "cloud" || raw.owner !== true) {
+    throw new Error("invalid_restore_contract");
+  }
+  if (typeof raw.slug !== "string" || !raw.slug || raw.slug !== expectedSlug) {
+    throw new Error(`restore_slug_mismatch: requested ${expectedSlug}; received ${String(raw.slug || "")}`);
+  }
+  const pkg = raw.cloudPackage;
+  if (!pkg || typeof pkg !== "object" || Array.isArray(pkg) || !Array.isArray(pkg.files)) {
+    throw new Error("invalid_restore_contract");
+  }
+  const version = cloudPackageHashVersion(pkg.packageHashVersion);
+  if (!version || !/^[a-f0-9]{64}$/i.test(String(pkg.packageHash || "").replace(/^sha256:/i, ""))) {
+    throw new Error("invalid_restore_contract");
+  }
+  let descriptor;
+  let nestedDescriptor;
+  try {
+    descriptor = normalizeCloudAssetDescriptorCli(raw, "owner restore receipt");
+    nestedDescriptor = normalizeCloudAssetDescriptorCli({
+      ...pkg,
+      slug: raw.slug,
+      etag: raw.etag,
+    }, "owner restore package receipt");
+  } catch (error) {
+    throw new Error(`invalid_restore_contract: ${error.message || error}`);
+  }
+  if (JSON.stringify(descriptor) !== JSON.stringify(nestedDescriptor)) {
+    throw new Error("invalid_restore_contract: restore revision envelope and cloudPackage disagree");
+  }
+  if (!["agent", "team", "repo"].includes(pkg.agentKind) || !Number.isSafeInteger(pkg.fileCount) || !Number.isSafeInteger(pkg.totalBytes)) {
+    throw new Error("invalid_restore_contract");
+  }
+  for (const file of pkg.files) {
+    if (!file || typeof file !== "object" || typeof file.path !== "string" || !Number.isSafeInteger(file.bytes) || typeof file.sha256 !== "string" || typeof file.contentBase64 !== "string") {
+      throw new Error("invalid_restore_contract");
+    }
+  }
+  const outerVersion = raw.packageHashVersion == null ? version : cloudPackageHashVersion(raw.packageHashVersion);
+  if (
+    (raw.packageHash != null && String(raw.packageHash) !== String(pkg.packageHash)) ||
+    !outerVersion || outerVersion !== version ||
+    (raw.fileCount != null && raw.fileCount !== pkg.fileCount) ||
+    (raw.totalBytes != null && raw.totalBytes !== pkg.totalBytes) ||
+    (raw.agentKind != null && raw.agentKind !== pkg.agentKind)
+  ) {
+    throw new Error("invalid_restore_contract: restore envelope and cloudPackage disagree");
+  }
+  return {
+    schema: raw.schema,
+    source: raw.source,
+    owner: true,
+    slug: raw.slug,
+    name: typeof raw.name === "string" && raw.name ? raw.name : raw.slug,
+    nameEn: typeof raw.nameEn === "string" && raw.nameEn ? raw.nameEn : (raw.name || raw.slug),
+    tagline: typeof raw.tagline === "string" ? raw.tagline : "",
+    taglineEn: typeof raw.taglineEn === "string" ? raw.taglineEn : (raw.tagline || ""),
+    descriptor,
+    cloudPackage: {
+      cloudId: descriptor.cloudId,
+      scope: descriptor.scope,
+      revision: descriptor.revision,
+      updatedAt: descriptor.updatedAt,
+      packageHash: String(pkg.packageHash).replace(/^sha256:/i, "").toLowerCase(),
+      packageHashVersion: version,
+      fileCount: pkg.fileCount,
+      totalBytes: pkg.totalBytes,
+      agentKind: pkg.agentKind,
+      runtimeLabels: Array.isArray(pkg.runtimeLabels) ? pkg.runtimeLabels.filter((item) => typeof item === "string" && item.trim()) : [],
+      files: pkg.files,
+    },
+  };
+}
+
+function cloudSystemPromptFromPackageCli(listing, slug) {
+  const pkg = listing && listing.cloudPackage;
+  if (!pkg || !Array.isArray(pkg.files) || !pkg.files.length) return "";
+  const byPath = new Map();
+  for (const file of pkg.files) {
+    if (!file || typeof file.path !== "string" || typeof file.contentBase64 !== "string") continue;
+    byPath.set(cloudPortablePathKey(file.path), file);
+  }
+  const readText = (candidate) => {
+    const safe = cloudPortableRelativePath(candidate);
+    if (!safe) return "";
+    const file = byPath.get(cloudPortablePathKey(safe));
+    if (!file) return "";
+    let bytes;
+    try { bytes = Buffer.from(file.contentBase64, "base64"); } catch { return ""; }
+    if (!bytes.length || bytes.includes(0)) return "";
+    const text = bytes.toString("utf8");
+    if (!text.trim() || text.includes("\ufffd")) return "";
+    return text.slice(0, 64 * 1024);
+  };
+  let manifest = null;
+  const manifestFile = byPath.get(cloudPortablePathKey("agentlas.json"));
+  if (manifestFile) {
+    try { manifest = JSON.parse(Buffer.from(manifestFile.contentBase64, "base64").toString("utf8")); }
+    catch { manifest = null; }
+  }
+  const declaredEntry = manifest && typeof manifest === "object" && typeof manifest.entry === "string"
+    ? cloudPortableRelativePath(manifest.entry)
+    : null;
+  const candidates = [
+    declaredEntry,
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md",
+    "AGENT.md",
+    "agent.md",
+    "system-prompt.md",
+    "README.md",
+  ].filter(Boolean);
+  let entryPath = "";
+  let entryText = "";
+  for (const candidate of candidates) {
+    const text = readText(candidate);
+    if (!text) continue;
+    entryPath = candidate;
+    entryText = text;
+    break;
+  }
+  if (!entryText) return "";
+  const installRoot = path.join(userDataDir(), "cloud-agent-installs", slug);
+  return [
+    `You are the Agentlas Cloud agent "${listing.name || slug}".`,
+    `IMMUTABLE CLOUD AGENT ROOT: ${installRoot}`,
+    `CANONICAL ENTRY: ${entryPath}`,
+    `PACKAGE HASH: ${String(pkg.packageHash || "").replace(/^sha256:/i, "")}`,
+    "Resolve package-relative references under IMMUTABLE CLOUD AGENT ROOT. Treat that root as read-only and do work in the user's active project.",
+    "",
+    "--- CLOUD AGENT ENTRY ---",
+    entryText,
+  ].join("\n");
+}
+
 function persistCloudListingCli(db, listing) {
+  if (listing?.delivery?.mode === "call_only") {
+    throw new Error(`call-only Hub asset cannot be source-installed; invoke it with agentlas call ${listing.slug || "<slug>"}`);
+  }
   const slug = cloudSlug(listing.slug || listing.name || "cloud-agent");
+  recoverCloudInstallJournalCli(db, slug);
   const existing = db.prepare("SELECT * FROM installed_agents WHERE slug=?").get(slug);
   const now = new Date().toISOString();
   const envReqs = JSON.stringify(listing.envRequirements || []);
   const mcpServers = JSON.stringify(listing.mcpServers || []);
-  if (existing) {
-    db.prepare("UPDATE installed_agents SET name=?, name_en=?, tagline=?, tagline_en=?, system_prompt=?, mcp_servers_json=?, env_requirements_json=?, trust_grade=?, visibility=? WHERE slug=?")
-      .run(listing.name || slug, listing.nameEn || listing.name || slug, listing.tagline || "", listing.taglineEn || listing.tagline || "", listing.systemPrompt || "", mcpServers, envReqs, listing.trustGrade || "unknown", listing.visibility || "visible", slug);
-    const localPath = materializeCloudListingCli(existing.id, slug, listing);
-    return { ...existing, slug, name: listing.name || slug, ...(localPath ? { localPath } : {}) };
-  }
-  const id = crypto.randomUUID();
+  const id = existing?.id || crypto.randomUUID();
   const hasVisibility = columnExists(db, "installed_agents", "visibility");
-  if (hasVisibility) {
-    db.prepare("INSERT INTO installed_agents (id, slug, name, name_en, tagline, tagline_en, system_prompt, mcp_servers_json, env_requirements_json, preferred_backend, trust_grade, installed_at, tone, visibility) VALUES (?,?,?,?,?,?,?,?,?,NULL,?,?,?,?)")
-      .run(id, slug, listing.name || slug, listing.nameEn || listing.name || slug, listing.tagline || "", listing.taglineEn || listing.tagline || "", listing.systemPrompt || "", mcpServers, envReqs, listing.trustGrade || "unknown", now, listing.tone || "blue", listing.visibility || "visible");
-  } else {
-    db.prepare("INSERT INTO installed_agents (id, slug, name, name_en, tagline, tagline_en, system_prompt, mcp_servers_json, env_requirements_json, preferred_backend, trust_grade, installed_at, tone) VALUES (?,?,?,?,?,?,?,?,?,NULL,?,?,?)")
-      .run(id, slug, listing.name || slug, listing.nameEn || listing.name || slug, listing.tagline || "", listing.taglineEn || listing.tagline || "", listing.systemPrompt || "", mcpServers, envReqs, listing.trustGrade || "unknown", now, listing.tone || "blue");
+  let installedAt = now;
+  if (existing && String(existing.installed_at || "") === installedAt) {
+    installedAt = new Date(Date.now() + 1).toISOString();
+  }
+  const tone = listing.tone || "blue";
+  const packageSystemPrompt = cloudSystemPromptFromPackageCli(listing, slug);
+  const dbExpected = {
+    id,
+    slug,
+    name: listing.name || slug,
+    name_en: listing.nameEn || listing.name || slug,
+    tagline: listing.tagline || "",
+    tagline_en: listing.taglineEn || listing.tagline || "",
+    system_prompt: packageSystemPrompt || listing.systemPrompt || "",
+    mcp_servers_json: mcpServers,
+    env_requirements_json: envReqs,
+    trust_grade: listing.trustGrade || "unknown",
+    installed_at: installedAt,
+    tone,
+    ...(!existing ? { preferred_backend: null } : {}),
+    ...(hasVisibility ? { visibility: listing.visibility || "visible" } : {}),
+  };
+  const restore = materializeCloudListingCli(id, slug, listing, { deferCommit: true, dbExpected });
+  const mutate = () => {
+    if (existing) {
+      if (hasVisibility) {
+        db.prepare("UPDATE installed_agents SET name=?, name_en=?, tagline=?, tagline_en=?, system_prompt=?, mcp_servers_json=?, env_requirements_json=?, trust_grade=?, installed_at=?, tone=?, visibility=? WHERE slug=?")
+          .run(dbExpected.name, dbExpected.name_en, dbExpected.tagline, dbExpected.tagline_en, dbExpected.system_prompt, mcpServers, envReqs, dbExpected.trust_grade, installedAt, tone, dbExpected.visibility, slug);
+      } else {
+        db.prepare("UPDATE installed_agents SET name=?, name_en=?, tagline=?, tagline_en=?, system_prompt=?, mcp_servers_json=?, env_requirements_json=?, trust_grade=?, installed_at=?, tone=? WHERE slug=?")
+          .run(dbExpected.name, dbExpected.name_en, dbExpected.tagline, dbExpected.tagline_en, dbExpected.system_prompt, mcpServers, envReqs, dbExpected.trust_grade, installedAt, tone, slug);
+      }
+      return;
+    }
+    if (hasVisibility) {
+      db.prepare("INSERT INTO installed_agents (id, slug, name, name_en, tagline, tagline_en, system_prompt, mcp_servers_json, env_requirements_json, preferred_backend, trust_grade, installed_at, tone, visibility) VALUES (?,?,?,?,?,?,?,?,?,NULL,?,?,?,?)")
+        .run(id, slug, dbExpected.name, dbExpected.name_en, dbExpected.tagline, dbExpected.tagline_en, dbExpected.system_prompt, mcpServers, envReqs, dbExpected.trust_grade, installedAt, tone, dbExpected.visibility);
+    } else {
+      db.prepare("INSERT INTO installed_agents (id, slug, name, name_en, tagline, tagline_en, system_prompt, mcp_servers_json, env_requirements_json, preferred_backend, trust_grade, installed_at, tone) VALUES (?,?,?,?,?,?,?,?,?,NULL,?,?,?)")
+        .run(id, slug, dbExpected.name, dbExpected.name_en, dbExpected.tagline, dbExpected.tagline_en, dbExpected.system_prompt, mcpServers, envReqs, dbExpected.trust_grade, installedAt, tone);
+    }
+  };
+  let dbCommitted = false;
+  try {
+    if (typeof db.transaction === "function") db.transaction(mutate)();
+    else mutate();
+    dbCommitted = true;
+    restore?.commit();
+  } catch (error) {
+    if (!dbCommitted) restore?.rollback();
+    throw error;
   }
-  const localPath = materializeCloudListingCli(id, slug, listing);
-  return { id, slug, name: listing.name || slug, ...(localPath ? { localPath } : {}) };
+  const localPath = restore?.path || null;
+  return existing
+    ? { ...existing, slug, name: dbExpected.name, ...(localPath ? { localPath } : {}) }
+    : { id, slug, name: dbExpected.name, ...(localPath ? { localPath } : {}) };
 }
 
-function materializeCloudListingCli(agentId, slug, listing) {
+function materializeCloudListingCli(agentId, slug, listing, options = {}) {
   const pkg = listing.cloudPackage;
   if (!pkg || !Array.isArray(pkg.files) || pkg.files.length === 0) return null;
+  if (pkg.files.length > CLOUD_MAX_FILES) throw new Error(`cloud package exceeds ${CLOUD_MAX_FILES} files`);
+  if (!Number.isSafeInteger(pkg.fileCount) || pkg.fileCount !== pkg.files.length) {
+    throw new Error("cloud package file count does not match its manifest");
+  }
+  if (!Number.isSafeInteger(pkg.totalBytes) || pkg.totalBytes < 0 || pkg.totalBytes > CLOUD_MAX_TOTAL_BYTES) {
+    throw new Error("cloud package total byte count is invalid");
+  }
+  const packageHashVersion = cloudPackageHashVersion(pkg.packageHashVersion);
+  if (!packageHashVersion) throw new Error(`unsupported cloud package hash version: ${pkg.packageHashVersion}`);
+  const assetDescriptor = listing.assetDescriptor
+    ? normalizeCloudAssetDescriptorCli(listing.assetDescriptor, "restore asset descriptor")
+    : null;
+  if (assetDescriptor && assetDescriptor.slug !== slug) throw new Error("restore asset descriptor slug mismatch");
+  const pathConflict = cloudPortablePathConflict(pkg.files.map((file) => file && file.path));
+  if (pathConflict) throw new Error(pathConflict.message);
   const dir = path.join(userDataDir(), "cloud-agent-installs", slug);
-  fs.mkdirSync(dir, { recursive: true });
-  const markerPath = path.join(dir, ".agentlas-cloud-package.json");
-  let currentHash = null;
+  const parent = path.dirname(dir);
+  fs.mkdirSync(parent, { recursive: true });
+  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 journal = path.join(parent, `.${path.basename(dir)}.install-journal.json`);
+  const seen = new Set();
+  const verifiedFiles = [];
+  let verifiedTotalBytes = 0;
+  let movedExisting = false;
+  let installed = false;
   try {
-    currentHash = JSON.parse(fs.readFileSync(markerPath, "utf8")).packageHash || null;
-  } catch {}
-  const overwrite = currentHash !== pkg.packageHash;
-  for (const file of pkg.files) {
-    const target = resolveCloudInstallPathCli(dir, file.path);
-    const bytes = Buffer.from(String(file.contentBase64 || ""), "base64");
-    if (bytes.length !== Number(file.bytes) || sha(bytes) !== String(file.sha256 || "").toLowerCase()) {
-      fail(`cloud package file integrity failed: ${file.path}`);
+    fs.mkdirSync(staging, { recursive: false, mode: 0o700 });
+    cloudApplyPrivateDirectoryMode(staging);
+    for (const file of pkg.files) {
+      const target = resolveCloudInstallPathCli(staging, file.path);
+      const normalizedPath = path.relative(staging, target).split(path.sep).join("/");
+      if (seen.has(normalizedPath)) throw new Error(`duplicate cloud package path: ${file.path}`);
+      seen.add(normalizedPath);
+      if (packageHashVersion === CLOUD_PACKAGE_HASH_V2 && typeof file.executable !== "boolean") {
+        throw new Error(`cloud package hash v2 requires executable boolean: ${file.path}`);
+      }
+      if (packageHashVersion === CLOUD_PACKAGE_HASH_V1 && file.executable !== undefined) {
+        throw new Error(`legacy cloud package hash v1 cannot authenticate executable flag: ${file.path}`);
+      }
+      if (!cloudCanonicalBase64(file.contentBase64)) {
+        throw new Error(`cloud package file base64 is not canonical: ${file.path}`);
+      }
+      const bytes = Buffer.from(String(file.contentBase64 || ""), "base64");
+      if (!Number.isSafeInteger(file.bytes) || file.bytes < 0 || file.bytes > CLOUD_MAX_FILE_BYTES) {
+        throw new Error(`cloud package file byte count is invalid: ${file.path}`);
+      }
+      if (bytes.length !== Number(file.bytes) || sha(bytes) !== String(file.sha256 || "").toLowerCase()) {
+        throw new Error(`cloud package file integrity failed: ${file.path}`);
+      }
+      verifiedFiles.push({
+        path: normalizedPath,
+        bytes: bytes.length,
+        sha256: String(file.sha256 || "").toLowerCase(),
+        ...(packageHashVersion === CLOUD_PACKAGE_HASH_V2 ? { executable: file.executable } : {}),
+      });
+      verifiedTotalBytes += bytes.length;
+      if (verifiedTotalBytes > CLOUD_MAX_TOTAL_BYTES) throw new Error("cloud package exceeds total byte limit");
+      fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+      cloudApplyPrivateDirectoryMode(path.dirname(target));
+      const mode = packageHashVersion === CLOUD_PACKAGE_HASH_V2 && file.executable ? 0o700 : 0o600;
+      fs.writeFileSync(target, bytes, { mode });
+      cloudApplyPortableFileMode(target, mode);
+    }
+    const expectedPackageHash = String(pkg.packageHash || "").toLowerCase().replace(/^sha256:/, "");
+    if (!/^[a-f0-9]{64}$/.test(expectedPackageHash)) {
+      throw new Error("cloud package aggregate hash is missing or invalid");
+    }
+    const actualPackageHash = cloudHashPackage(verifiedFiles, packageHashVersion);
+    if (actualPackageHash !== expectedPackageHash) {
+      throw new Error("cloud package aggregate integrity failed");
+    }
+    if (assetDescriptor && (
+      assetDescriptor.packageHash !== expectedPackageHash ||
+      assetDescriptor.packageHashVersion !== packageHashVersion
+    )) {
+      throw new Error("restore asset descriptor package identity mismatch");
+    }
+    if (verifiedTotalBytes !== pkg.totalBytes) throw new Error("cloud package total byte count does not match its files");
+    const restoredAt = new Date().toISOString();
+    fs.writeFileSync(
+      path.join(staging, ".agentlas-cloud-package.json"),
+      JSON.stringify({
+        schemaVersion: 1,
+        source: "agentlas-cloud",
+        slug,
+        packageHash: expectedPackageHash,
+        packageHashVersion,
+        fileCount: verifiedFiles.length,
+        totalBytes: verifiedTotalBytes,
+        executablePaths: packageHashVersion === CLOUD_PACKAGE_HASH_V2
+          ? verifiedFiles.filter((file) => file.executable).map((file) => file.path).sort()
+          : undefined,
+        ...(assetDescriptor ? {
+          cloudId: assetDescriptor.cloudId,
+          scope: assetDescriptor.scope,
+          revision: assetDescriptor.revision,
+          etag: assetDescriptor.etag,
+          updatedAt: assetDescriptor.updatedAt,
+          cloudAssets: { [assetDescriptor.scope]: assetDescriptor },
+        } : {}),
+        restoredAt,
+      }, null, 2) + "\n",
+      { encoding: "utf8", mode: 0o600 },
+    );
+    cloudApplyPortableFileMode(path.join(staging, CLOUD_RESTORE_MARKER_PATH), 0o600);
+    cloudVerifyRestoredSnapshot(staging, verifiedFiles, {
+      slug,
+      packageHash: expectedPackageHash,
+      packageHashVersion,
+      totalBytes: verifiedTotalBytes,
+      assetDescriptor,
+    });
+
+    if (options.deferCommit) {
+      writeCloudInstallJournalCli(journal, {
+        schemaVersion: 1,
+        slug,
+        phase: "prepared",
+        destination: dir,
+        staging,
+        backup,
+        hadExisting: fs.existsSync(dir),
+        dbExpected: options.dbExpected || {},
+      });
     }
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    if (overwrite || !fs.existsSync(target)) fs.writeFileSync(target, bytes);
+
+    // 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.
+    if (fs.existsSync(dir)) {
+      fs.renameSync(dir, backup);
+      movedExisting = true;
+    }
+    fs.renameSync(staging, dir);
+    cloudFsyncDirectoryCli(parent);
+    installed = true;
+    if (options.deferCommit) {
+      writeCloudInstallJournalCli(journal, {
+        schemaVersion: 1,
+        slug,
+        phase: "disk-swapped-db-pending",
+        destination: dir,
+        staging,
+        backup,
+        hadExisting: movedExisting,
+        dbExpected: options.dbExpected || {},
+      });
+    }
+  } catch (error) {
+    rollbackCloudInstallSwapCli({ destination: dir, staging, backup, movedExisting, installed });
+    try { if (fs.existsSync(journal)) fs.unlinkSync(journal); } catch { /* best-effort */ }
+    throw error;
+  } finally {
+    try { if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true }); } catch { /* best-effort */ }
+    try { if (!options.deferCommit && installed && fs.existsSync(backup)) fs.rmSync(backup, { recursive: true, force: true }); } catch { /* best-effort */ }
+  }
+  if (!options.deferCommit) return dir;
+  let settled = false;
+  return {
+    path: dir,
+    commit() {
+      if (settled) return;
+      writeCloudInstallJournalCli(journal, {
+        schemaVersion: 1,
+        slug,
+        phase: "db-committed",
+        destination: dir,
+        staging,
+        backup,
+        hadExisting: movedExisting,
+        dbExpected: options.dbExpected || {},
+      });
+      if (fs.existsSync(backup)) fs.rmSync(backup, { recursive: true, force: true });
+      if (fs.existsSync(journal)) fs.unlinkSync(journal);
+      cloudFsyncDirectoryCli(parent);
+      settled = true;
+    },
+    rollback() {
+      if (settled) return;
+      rollbackCloudInstallSwapCli({ destination: dir, staging, backup, movedExisting, installed });
+      if (fs.existsSync(journal)) fs.unlinkSync(journal);
+      cloudFsyncDirectoryCli(parent);
+      settled = true;
+    },
+  };
+}
+
+function writeCloudInstallJournalCli(journalPath, value) {
+  fs.mkdirSync(path.dirname(journalPath), { recursive: true, mode: 0o700 });
+  const temp = `${journalPath}.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
+  const fd = fs.openSync(temp, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o600);
+  try {
+    fs.writeFileSync(fd, JSON.stringify(value, null, 2) + "\n", "utf8");
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
   }
-  fs.writeFileSync(
-    markerPath,
-    JSON.stringify({ agentId, packageHash: pkg.packageHash, installedAt: new Date().toISOString() }, null, 2) + "\n",
-    "utf8",
+  fs.renameSync(temp, journalPath);
+  cloudApplyPortableFileMode(journalPath, 0o600);
+  cloudFsyncDirectoryCli(path.dirname(journalPath));
+}
+
+function cloudFsyncDirectoryCli(directory) {
+  if (process.platform === "win32") return;
+  let fd;
+  try {
+    fd = fs.openSync(directory, fs.constants.O_RDONLY);
+    fs.fsyncSync(fd);
+  } catch { /* some filesystems do not support directory fsync */ }
+  finally { if (fd !== undefined) try { fs.closeSync(fd); } catch { /* best-effort */ } }
+}
+
+function rollbackCloudInstallSwapCli({ destination, staging, backup, movedExisting, installed }) {
+  if (installed && fs.existsSync(destination)) fs.rmSync(destination, { recursive: true, force: true });
+  if (movedExisting && fs.existsSync(backup) && !fs.existsSync(destination)) fs.renameSync(backup, destination);
+  if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true });
+  cloudFsyncDirectoryCli(path.dirname(destination));
+}
+
+function recoverCloudInstallJournalCli(db, slug) {
+  const destination = path.join(userDataDir(), "cloud-agent-installs", slug);
+  const parent = path.dirname(destination);
+  const journalPath = path.join(parent, `.${path.basename(destination)}.install-journal.json`);
+  if (!fs.existsSync(journalPath)) return;
+  let journal;
+  try { journal = JSON.parse(fs.readFileSync(journalPath, "utf8")); } catch { throw new Error(`cloud install recovery journal is unreadable for ${slug}`); }
+  const safeSibling = (candidate, prefix) =>
+    typeof candidate === "string" && path.dirname(candidate) === parent && path.basename(candidate).startsWith(prefix);
+  if (
+    journal.schemaVersion !== 1 || journal.slug !== slug || journal.destination !== destination ||
+    !["prepared", "disk-swapped-db-pending", "db-committed"].includes(journal.phase) ||
+    typeof journal.hadExisting !== "boolean" ||
+    !safeSibling(journal.staging, `.${path.basename(destination)}.installing-`) ||
+    !safeSibling(journal.backup, `.${path.basename(destination)}.backup-`)
+  ) {
+    throw new Error(`cloud install recovery journal is invalid for ${slug}`);
+  }
+  const row = db.prepare("SELECT * FROM installed_agents WHERE slug=?").get(slug);
+  const expected = journal.dbExpected && typeof journal.dbExpected === "object" ? journal.dbExpected : {};
+  const expectedEntries = Object.entries(expected);
+  const dbMatches = Boolean(row) && expectedEntries.length > 0 && expectedEntries.every(
+    ([key, value]) => String(row[key] ?? "") === String(value ?? ""),
   );
-  return dir;
+  if (journal.phase === "prepared") {
+    // The DB mutation starts only after materializeCloudListingCli returns, so a
+    // prepared journal always represents the pre-DB state. Cover both rename
+    // crash windows: old→backup and staging→destination.
+    if (journal.hadExisting) {
+      if (fs.existsSync(journal.backup)) {
+        if (fs.existsSync(destination)) fs.rmSync(destination, { recursive: true, force: true });
+        fs.renameSync(journal.backup, destination);
+      } else if (!fs.existsSync(destination)) {
+        throw new Error(`prepared cloud install lost both destination and backup for ${slug}`);
+      }
+    } else {
+      if (fs.existsSync(journal.backup)) {
+        throw new Error(`prepared first cloud install has an unexpected backup for ${slug}`);
+      }
+      if (fs.existsSync(destination)) fs.rmSync(destination, { recursive: true, force: true });
+    }
+    if (fs.existsSync(journal.staging)) fs.rmSync(journal.staging, { recursive: true, force: true });
+  } else if (journal.phase === "db-committed" || dbMatches) {
+    if (!fs.existsSync(destination) && fs.existsSync(journal.staging)) fs.renameSync(journal.staging, destination);
+    if (!fs.existsSync(destination)) throw new Error(`committed cloud install is missing for ${slug}`);
+    if (fs.existsSync(journal.backup)) fs.rmSync(journal.backup, { recursive: true, force: true });
+    if (fs.existsSync(journal.staging)) fs.rmSync(journal.staging, { recursive: true, force: true });
+  } else if (journal.phase === "disk-swapped-db-pending") {
+    if (!fs.existsSync(destination)) throw new Error(`pending cloud install destination is missing for ${slug}`);
+    if (journal.hadExisting !== fs.existsSync(journal.backup)) {
+      throw new Error(`pending cloud install backup state is invalid for ${slug}`);
+    }
+    rollbackCloudInstallSwapCli({
+      destination,
+      staging: journal.staging,
+      backup: journal.backup,
+      movedExisting: Boolean(journal.hadExisting),
+      installed: true,
+    });
+  }
+  fs.unlinkSync(journalPath);
+  cloudFsyncDirectoryCli(parent);
 }
 
-function resolveCloudInstallPathCli(root, relPath) {
-  const normalized = String(relPath || "").replace(/\\/g, "/");
-  if (!normalized || normalized.startsWith("/") || normalized.includes("\0")) {
-    fail(`unsafe cloud package path: ${relPath}`);
+function recoverCloudInstallJournalsCli(db) {
+  const parent = path.join(userDataDir(), "cloud-agent-installs");
+  if (!fs.existsSync(parent)) return 0;
+  let recovered = 0;
+  for (const entry of fs.readdirSync(parent, { withFileTypes: true })) {
+    if (!entry.name.endsWith(".install-journal.json")) continue;
+    const match = entry.name.match(/^\.([a-z0-9][a-z0-9-]{0,63})\.install-journal\.json$/);
+    if (!match || cloudSlug(match[1]) !== match[1] || !entry.isFile() || entry.isSymbolicLink()) {
+      throw new Error(`invalid cloud install recovery journal entry: ${entry.name}`);
+    }
+    recoverCloudInstallJournalCli(db, match[1]);
+    recovered += 1;
   }
-  const parts = normalized.split("/").filter((part) => part && part !== ".");
-  if (parts.length === 0 || parts.some((part) => part === "..")) {
-    fail(`unsafe cloud package path: ${relPath}`);
+  return recovered;
+}
+
+function resolveCloudInstallPathCli(root, relPath) {
+  const normalized = cloudPortableRelativePath(relPath);
+  if (!normalized || cloudPortablePathKey(normalized) === cloudPortablePathKey(CLOUD_RESTORE_MARKER_PATH)) {
+    throw new Error(`unsafe cloud package path: ${relPath}`);
   }
+  const parts = normalized.split("/");
   const target = path.resolve(root, ...parts);
   const relative = path.relative(root, target);
   if (relative.startsWith("..") || path.isAbsolute(relative)) {
-    fail(`cloud package path escapes install folder: ${relPath}`);
+    throw new Error(`cloud package path escapes install folder: ${relPath}`);
   }
   return target;
 }
 
 function printCloudPackageResult(result) {
   out(`${result.status === "blocked" ? "✖" : "✓"} ${result.summary}`);
+  out(`  target:  ${result.manifest.visibility === "marketplace" ? "Agentlas Hub (public)" : "Agent Cloud (owner-private)"}`);
   out(`  slug:    ${result.manifest.slug}`);
   out(`  files:   ${result.manifest.includedFileCount}/${result.manifest.fileCount}`);
   out(`  hash:    ${result.manifest.packageHash}`);
@@ -1328,11 +2653,106 @@ function printCloudPackageResult(result) {
     out("  findings:");
     for (const f of findings.slice(0, 20)) out(`    - ${f.severity} ${f.file ? f.file + ": " : ""}${f.message}`);
   }
-  if (result.registration) out(`  cloud:   ${result.registration.marketplaceUrl || result.registration.url || result.registration.cloudId}`);
+  if (result.registration) {
+    const label = result.manifest.visibility === "marketplace" ? "hub" : "cloud";
+    out(`  ${label}:     ${result.registration.marketplaceUrl || result.registration.url || result.registration.cloudId}`);
+    if (result.registration.localStateWarning) out(`  warning: ${result.registration.localStateWarning}`);
+  }
 }
 
-function cloudReadName(rootPath) {
-  const manifest = cloudReadPackageJson(rootPath);
+function cloudPackageSnapshot(files) {
+  return new Map(files.map((file) => [file.path, file]));
+}
+function cloudReadPublicCareerCard(snapshot, findings) {
+  const relativePath = ".agentlas/public-career-card.json";
+  const file = snapshot.get(relativePath);
+  if (!file) return undefined;
+  let parsed;
+  try { parsed = JSON.parse(Buffer.from(file.contentBase64, "base64").toString("utf8")); }
+  catch {
+    findings.push(cloudCareerFinding("career-card-invalid-json", "structure", "Career Graph public card is not valid JSON."));
+    return undefined;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || parsed.kind !== "agentlas-public-career-card") {
+    findings.push(cloudCareerFinding("career-card-invalid-kind", "structure", "Career Graph public card has an invalid kind."));
+    return undefined;
+  }
+  const privacy = parsed.privacy && typeof parsed.privacy === "object" && !Array.isArray(parsed.privacy) ? parsed.privacy : {};
+  for (const key of ["rawLocalPathsIncluded", "rawPromptsIncluded", "rawTranscriptsIncluded", "sourceTextIncluded"]) {
+    if (privacy[key] !== false) findings.push(cloudCareerFinding(`career-card-privacy-${key}`, "policy", `Career Graph public card must set privacy.${key}=false.`));
+  }
+  if (cloudContainsAbsoluteLocalPath(JSON.stringify(parsed))) {
+    findings.push(cloudCareerFinding("career-card-local-path", "policy", "Career Graph public card contains a local absolute path."));
+  }
+  if (findings.some((finding) => finding.severity === "blocker" && finding.id.startsWith("career-card-"))) return undefined;
+  return cloudSanitizePublicCareerCard(parsed);
+}
+function cloudCareerFinding(id, category, message) {
+  return {
+    id,
+    severity: "blocker",
+    category,
+    file: ".agentlas/public-career-card.json",
+    message,
+    remediation: "Regenerate a redacted aggregate-only public Career Graph card before publishing.",
+  };
+}
+function cloudContainsAbsoluteLocalPath(value) {
+  return (
+    (os.homedir() && value.includes(os.homedir())) ||
+    /(?:^|["'\s:(])\/(?:Users|home|var|tmp|private|Volumes|opt|etc)\//i.test(value) ||
+    /(?:^|["'\s:(])[A-Za-z]:[\\/]/.test(value) ||
+    /(?:^|["'\s:(])\\\\[^\\\s]+\\/.test(value)
+  );
+}
+function cloudSanitizePublicCareerCard(parsed) {
+  const card = { kind: "agentlas-public-career-card" };
+  for (const [key, max] of [["schemaVersion", 80], ["generatedAt", 80], ["projectName", 200], ["indexStatus", 80], ["policy", 160]]) {
+    if (typeof parsed[key] === "string" && parsed[key].length <= max) card[key] = parsed[key];
+  }
+  card.privacy = {
+    rawLocalPathsIncluded: false,
+    rawPromptsIncluded: false,
+    rawTranscriptsIncluded: false,
+    sourceTextIncluded: false,
+  };
+  for (const key of ["counts", "sourceKinds", "nodeTypes", "edgeTypes"]) {
+    const safe = cloudSanitizeCountRecord(parsed[key]);
+    if (safe) card[key] = safe;
+  }
+  for (const key of ["canonicalSources", "staleSourceCount"]) {
+    if (Number.isSafeInteger(parsed[key]) && parsed[key] >= 0) card[key] = parsed[key];
+  }
+  return card;
+}
+function cloudSanitizeCountRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const result = {};
+  for (const [key, count] of Object.entries(value).slice(0, 200)) {
+    if (/^[A-Za-z0-9_.:-]{1,80}$/.test(key) && Number.isSafeInteger(count) && count >= 0) result[key] = count;
+  }
+  return Object.keys(result).length ? result : undefined;
+}
+function cloudReplacePublicCareerCard(scan, card) {
+  const relativePath = ".agentlas/public-career-card.json";
+  const includedIndex = scan.included.findIndex((file) => file.path === relativePath);
+  const existing = includedIndex >= 0 ? scan.included[includedIndex] : null;
+  if (includedIndex >= 0) scan.included.splice(includedIndex, 1);
+  const fileRecord = scan.files.find((file) => file.path === relativePath);
+  if (!card) {
+    if (fileRecord) { fileRecord.included = false; fileRecord.reason = "public-career-card-blocked"; }
+    return;
+  }
+  const bytes = Buffer.from(JSON.stringify(card, null, 2) + "\n", "utf8");
+  const replacement = { path: relativePath, bytes: bytes.length, sha256: sha(bytes), contentBase64: bytes.toString("base64"), executable: false };
+  scan.included.push(replacement);
+  scan.included.sort(cloudCodePointPathOrder);
+  scan.totalBytes += bytes.length - (existing?.bytes || 0);
+  if (fileRecord) Object.assign(fileRecord, { bytes: bytes.length, sha256: replacement.sha256, kind: "text", executable: false, included: true, reason: undefined });
+  else scan.files.push({ path: relativePath, bytes: bytes.length, sha256: replacement.sha256, kind: "text", executable: false, included: true });
+}
+function cloudReadName(snapshot, fallbackName) {
+  const manifest = cloudReadPackageJson(snapshot);
   const explicit = stringFirstCli(
     manifest.agentlas?.displayName,
     manifest.agentlas?.name,
@@ -1341,12 +2761,12 @@ function cloudReadName(rootPath) {
     manifest.routingCard?.name,
   );
   if (explicit) return explicit.replace(/\s+/g, " ").trim().slice(0, 80);
-  const text = cloudReadFirst(rootPath, ["agent.md", "AGENT.md", "README.md", "CLAUDE.md", "AGENTS.md"], 2000);
+  const text = cloudReadFirst(snapshot, ["agent.md", "AGENT.md", "README.md", "CLAUDE.md", "AGENTS.md"], 2000);
   const heading = text.match(/^#\s+(.+)$/m);
-  return (heading ? heading[1] : path.basename(rootPath)).replace(/\s+/g, " ").trim().slice(0, 80);
+  return (heading ? heading[1] : fallbackName).replace(/\s+/g, " ").trim().slice(0, 80);
 }
-function cloudReadTagline(rootPath) {
-  const manifest = cloudReadPackageJson(rootPath);
+function cloudReadTagline(snapshot) {
+  const manifest = cloudReadPackageJson(snapshot);
   const explicit = stringFirstCli(
     manifest.agentlas?.summary,
     manifest.agentlas?.description,
@@ -1355,15 +2775,15 @@ function cloudReadTagline(rootPath) {
     manifest.routingCard?.summary,
   );
   if (explicit) return explicit.replace(/\s+/g, " ").trim().slice(0, 160);
-  const text = cloudReadFirst(rootPath, ["README.md", "agent.md", "AGENT.md"], 3000);
+  const text = cloudReadFirst(snapshot, ["README.md", "agent.md", "AGENT.md"], 3000);
   for (const line of text.split(/\r?\n/)) {
     const t = line.trim();
     if (t && !t.startsWith("#") && !t.startsWith(">")) return t.slice(0, 160);
   }
   return "Portable Agentlas cloud agent package.";
 }
-function cloudReadStableSlug(rootPath) {
-  const manifest = cloudReadPackageJson(rootPath);
+function cloudReadStableSlug(snapshot) {
+  const manifest = cloudReadPackageJson(snapshot);
   return stringFirstCli(
     manifest.agentlas?.slug,
     manifest.agentlas?.id,
@@ -1374,52 +2794,321 @@ function cloudReadStableSlug(rootPath) {
     manifest.routingCard?.agent_card_ref?.slug,
   );
 }
-function cloudReadPackageJson(rootPath) {
+function cloudReadPackageJson(snapshot) {
   return {
-    agentlas: readJsonObjectCli(path.join(rootPath, "agentlas.json"), {}),
-    manifest: readJsonObjectCli(path.join(rootPath, "manifest.json"), {}),
-    agentCard: readJsonObjectCli(path.join(rootPath, ".agentlas", "agent-card.json"), {}),
-    routingCard: readJsonObjectCli(path.join(rootPath, ".agentlas", "routing-card.json"), {}),
+    agentlas: cloudReadSnapshotJson(snapshot, "agentlas.json"),
+    manifest: cloudReadSnapshotJson(snapshot, "manifest.json"),
+    agentCard: cloudReadSnapshotJson(snapshot, ".agentlas/agent-card.json"),
+    routingCard: cloudReadSnapshotJson(snapshot, ".agentlas/routing-card.json"),
   };
 }
-function stringFirstCli(...values) {
-  for (const value of values) {
-    if (typeof value === "string" && value.trim()) return value.trim();
+function cloudReadSnapshotJson(snapshot, relativePath) {
+  try {
+    const parsed = JSON.parse(cloudReadSnapshotText(snapshot, relativePath));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch { return {}; }
+}
+function stringFirstCli(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return "";
+}
+function cloudReadFirst(snapshot, names, maxChars) {
+  for (const name of names) {
+    const text = cloudReadSnapshotText(snapshot, name);
+    if (text) return text.slice(0, maxChars);
+  }
+  return "";
+}
+function cloudReadSnapshotText(snapshot, relativePath) {
+  const file = snapshot.get(relativePath);
+  return file ? Buffer.from(file.contentBase64, "base64").toString("utf8") : "";
+}
+function cloudInferKind(snapshot) {
+  const paths = [...snapshot.keys()];
+  if (paths.some((file) => file === "TEAM.md" || file === "team.json" || /^(?:agents|team|departments|hr-departments)\//.test(file))) return "team";
+  return "agent";
+}
+function cloudDetectRuntimeLabels(snapshot) {
+  const paths = new Set(snapshot.keys());
+  const labels = [];
+  if (paths.has("CLAUDE.md") || [...paths].some((file) => file.startsWith(".claude/"))) labels.push("claude-code");
+  if (paths.has("AGENTS.md")) labels.push("codex");
+  if (paths.has("GEMINI.md")) labels.push("gemini");
+  if (paths.has(".cursorrules") || [...paths].some((file) => file.startsWith(".cursor/"))) labels.push("cursor");
+  return labels.length ? labels : ["generic"];
+}
+function cloudPackageDir(slug) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  return path.join(userDataDir(), "cloud-agent-packages", `${slug}-${stamp}`);
+}
+function cloudPackageHashVersion(value) {
+  if (value === undefined || value === null || value === "") return CLOUD_PACKAGE_HASH_V1;
+  if (value === CLOUD_PACKAGE_HASH_V1 || value === CLOUD_PACKAGE_HASH_V2) return value;
+  return null;
+}
+function cloudHashPackage(files, version = CLOUD_PACKAGE_HASH_V1) {
+  const hashVersion = cloudPackageHashVersion(version);
+  if (!hashVersion) throw new Error(`unsupported cloud package hash version: ${version}`);
+  const h = crypto.createHash("sha256");
+  // 서버 package-contract.ts와 바이트 동일해야 한다: 경로 코드포인트 순 정렬.
+  // 정렬 없이 스캔 순서로 해시하면 대소문자 혼합 경로 패키지(AGENTS.md + agents/…)가
+  // 전부 package_hash_mismatch로 거절된다(2026-07-02 근본 수정).
+  for (const file of [...files].sort(cloudCodePointPathOrder)) {
+    h.update(file.path);
+    h.update("\0");
+    h.update(file.sha256);
+    h.update("\0");
+    if (hashVersion === CLOUD_PACKAGE_HASH_V2) {
+      h.update(file.executable ? "x" : "-");
+      h.update("\0");
+    }
+  }
+  return h.digest("hex");
+}
+function cloudCodePointPathOrder(a, b) {
+  return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+}
+function cloudPortablePathKey(value) {
+  return String(value).normalize("NFC").toLowerCase();
+}
+function cloudPortableRelativePath(value) {
+  if (typeof value !== "string" || !value || value !== value.normalize("NFC")) return null;
+  if (value.includes("\\") || value.includes("\0") || value.startsWith("/") || value.endsWith("/")) return null;
+  if (value.includes("//") || value.length > 260) return null;
+  const parts = value.split("/");
+  for (const part of parts) {
+    if (!part || part === "." || part === "..") return null;
+    if (part.length > 255 || Buffer.byteLength(part, "utf8") > 255 || cloudHasUnpairedSurrogate(part)) return null;
+    if (/[<>:"|?*\u0000-\u001f]/.test(part) || /[ .]$/.test(part)) return null;
+    if (/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part)) return null;
+  }
+  return value;
+}
+function cloudHasUnpairedSurrogate(value) {
+  for (let index = 0; index < value.length; index++) {
+    const unit = value.charCodeAt(index);
+    if (unit >= 0xd800 && unit <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) return true;
+      index++;
+    } else if (unit >= 0xdc00 && unit <= 0xdfff) return true;
+  }
+  return false;
+}
+function cloudPortablePathConflict(paths) {
+  const files = new Map();
+  const directories = new Map();
+  for (const value of paths) {
+    if (typeof value !== "string" || !value) continue;
+    const fileKey = cloudPortablePathKey(value);
+    const existingFile = files.get(fileKey);
+    if (existingFile) {
+      if (existingFile.path === value) {
+        return { code: "duplicate-path", message: `Cloud package repeats file path ${JSON.stringify(value)}.` };
+      }
+      return { code: "path-alias-collision", message: `Cloud package paths ${JSON.stringify(existingFile.path)} and ${JSON.stringify(value)} alias after Unicode NFC normalization and case-folding.` };
+    }
+    files.set(fileKey, { path: value });
+    const parts = value.split("/");
+    for (let index = 1; index < parts.length; index++) {
+      const directory = parts.slice(0, index).join("/");
+      const directoryKey = cloudPortablePathKey(directory);
+      const existingDirectory = directories.get(directoryKey);
+      if (existingDirectory && existingDirectory.directory !== directory) {
+        return {
+          code: "path-alias-collision",
+          message: `Ancestor directories ${JSON.stringify(existingDirectory.directory)} (from ${JSON.stringify(existingDirectory.sourcePath)}) and ${JSON.stringify(directory)} (from ${JSON.stringify(value)}) alias after Unicode NFC normalization and case-folding.`,
+        };
+      }
+      if (!existingDirectory) directories.set(directoryKey, { directory, sourcePath: value });
+    }
+  }
+  for (const [key, file] of files) {
+    const directory = directories.get(key);
+    if (!directory) continue;
+    if (file.path === directory.directory) {
+      return { code: "path-type-collision", message: `Cloud package path ${JSON.stringify(file.path)} is both a file and an ancestor directory.` };
+    }
+    return {
+      code: "path-alias-collision",
+      message: `File path ${JSON.stringify(file.path)} aliases ancestor directory ${JSON.stringify(directory.directory)} from ${JSON.stringify(directory.sourcePath)} after Unicode NFC normalization and case-folding.`,
+    };
+  }
+  return null;
+}
+function cloudReadRestoreExecutablePaths(rootPath) {
+  if (process.platform !== "win32") return new Set();
+  const marker = path.join(rootPath, CLOUD_RESTORE_MARKER_PATH);
+  try {
+    const parsed = JSON.parse(fs.readFileSync(marker, "utf8"));
+    if (cloudPackageHashVersion(parsed.packageHashVersion) !== CLOUD_PACKAGE_HASH_V2) return new Set();
+    if (!Array.isArray(parsed.executablePaths)) return new Set();
+    return new Set(parsed.executablePaths
+      .filter((value) => cloudPortableRelativePath(value))
+      .map((value) => cloudPortablePathKey(value)));
+  } catch {
+    return new Set();
+  }
+}
+function cloudPortableExecutableForFile(relativePath, statMode, restoredExecutablePaths, platform = process.platform) {
+  if (platform === "win32") return restoredExecutablePaths.has(cloudPortablePathKey(relativePath));
+  return Boolean(statMode & 0o111);
+}
+function cloudApplyPrivateDirectoryMode(directoryPath, platform = process.platform) {
+  if (platform === "win32") return;
+  fs.chmodSync(directoryPath, 0o700);
+  const actual = fs.statSync(directoryPath).mode & 0o777;
+  if (actual !== 0o700) throw new Error(`cloud restore directory mode verification failed: ${directoryPath}`);
+}
+function cloudApplyPortableFileMode(filePath, mode, platform = process.platform) {
+  if (platform === "win32") return;
+  fs.chmodSync(filePath, mode);
+  const actual = fs.statSync(filePath).mode & 0o777;
+  if (actual !== mode) throw new Error(`cloud restore file mode verification failed: ${filePath}`);
+}
+function cloudVerifyRestoredSnapshot(root, files, expected) {
+  const expectedByPath = new Map(files.map((file) => [file.path, file]));
+  const seen = new Set();
+  function walk(dir) {
+    const dirStat = fs.lstatSync(dir);
+    if (!dirStat.isDirectory() || dirStat.isSymbolicLink()) throw new Error("cloud restore staging contains an unsafe directory");
+    if (process.platform !== "win32" && (dirStat.mode & 0o777) !== 0o700) throw new Error("cloud restore staging directory mode mismatch");
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const absolute = path.join(dir, entry.name);
+      const relative = path.relative(root, absolute).split(path.sep).join("/");
+      if (relative === CLOUD_RESTORE_MARKER_PATH) continue;
+      const stat = fs.lstatSync(absolute);
+      if (stat.isSymbolicLink()) throw new Error("cloud restore staging contains a symbolic link");
+      if (stat.isDirectory()) { walk(absolute); continue; }
+      if (!stat.isFile()) throw new Error("cloud restore staging contains a special filesystem entry");
+      const expectedFile = expectedByPath.get(relative);
+      if (!expectedFile || seen.has(relative)) throw new Error(`cloud restore staging has an unexpected file: ${relative}`);
+      const bytes = fs.readFileSync(absolute);
+      if (bytes.length !== expectedFile.bytes || sha(bytes) !== expectedFile.sha256) {
+        throw new Error(`cloud restore staging file integrity mismatch: ${relative}`);
+      }
+      if (process.platform !== "win32") {
+        const mode = expected.packageHashVersion === CLOUD_PACKAGE_HASH_V2 && expectedFile.executable ? 0o700 : 0o600;
+        if ((stat.mode & 0o777) !== mode) throw new Error(`cloud restore staging file mode mismatch: ${relative}`);
+      }
+      seen.add(relative);
+    }
+  }
+  walk(root);
+  if (seen.size !== expectedByPath.size) throw new Error("cloud restore staging is missing package files");
+  const markerPath = path.join(root, CLOUD_RESTORE_MARKER_PATH);
+  const markerStat = fs.lstatSync(markerPath);
+  if (!markerStat.isFile() || markerStat.isSymbolicLink()) throw new Error("cloud restore marker is unsafe");
+  if (process.platform !== "win32" && (markerStat.mode & 0o777) !== 0o600) throw new Error("cloud restore marker mode mismatch");
+  const marker = JSON.parse(fs.readFileSync(markerPath, "utf8"));
+  const expectedExecutablePaths = expected.packageHashVersion === CLOUD_PACKAGE_HASH_V2
+    ? files.filter((file) => file.executable).map((file) => file.path).sort()
+    : undefined;
+  if (
+    marker.schemaVersion !== 1 || marker.source !== "agentlas-cloud" || marker.slug !== expected.slug ||
+    String(marker.packageHash).replace(/^sha256:/i, "").toLowerCase() !== expected.packageHash ||
+    marker.packageHashVersion !== expected.packageHashVersion || marker.fileCount !== files.length ||
+    marker.totalBytes !== expected.totalBytes || typeof marker.restoredAt !== "string" ||
+    !Number.isFinite(Date.parse(marker.restoredAt)) ||
+    JSON.stringify(marker.executablePaths) !== JSON.stringify(expectedExecutablePaths)
+  ) {
+    throw new Error("cloud restore marker contract mismatch");
+  }
+  if (expected.assetDescriptor) {
+    const descriptor = normalizeCloudAssetDescriptorCli(marker, "cloud restore marker");
+    const nested = normalizeCloudAssetDescriptorCli(marker.cloudAssets?.[descriptor.scope], "cloud restore marker scope");
+    if (
+      JSON.stringify(descriptor) !== JSON.stringify(expected.assetDescriptor) ||
+      JSON.stringify(nested) !== JSON.stringify(expected.assetDescriptor)
+    ) {
+      throw new Error("cloud restore marker revision contract mismatch");
+    }
   }
-  return "";
 }
-function cloudReadFirst(rootPath, names, maxChars) {
-  for (const name of names) {
-    const file = path.join(rootPath, name);
-    try {
-      const stat = fs.statSync(file);
-      if (stat.isFile() && stat.size <= CLOUD_MAX_FILE_BYTES) return fs.readFileSync(file, "utf8").slice(0, maxChars);
-    } catch { /* continue */ }
+function cloudDecodeUtf16CredentialText(bytes) {
+  if (bytes.length < 4) return null;
+  if (bytes[0] === 0xff && bytes[1] === 0xfe) {
+    return bytes.subarray(2, bytes.length - ((bytes.length - 2) % 2)).toString("utf16le");
+  }
+  if (bytes[0] === 0xfe && bytes[1] === 0xff) {
+    const body = Buffer.from(bytes.subarray(2, bytes.length - ((bytes.length - 2) % 2)));
+    body.swap16();
+    return body.toString("utf16le");
+  }
+  const sampleLength = Math.min(bytes.length - (bytes.length % 2), 4096);
+  if (sampleLength < 8) return null;
+  let oddNuls = 0;
+  let evenNuls = 0;
+  for (let index = 0; index < sampleLength; index += 2) {
+    if (bytes[index] === 0) evenNuls++;
+    if (bytes[index + 1] === 0) oddNuls++;
+  }
+  const pairs = sampleLength / 2;
+  const fullLength = bytes.length - (bytes.length % 2);
+  if (oddNuls / pairs > 0.3) return bytes.subarray(0, fullLength).toString("utf16le");
+  if (evenNuls / pairs > 0.3) {
+    const body = Buffer.from(bytes.subarray(0, fullLength));
+    body.swap16();
+    return body.toString("utf16le");
   }
-  return "";
+  return null;
 }
-function cloudInferKind(rootPath) {
-  for (const name of ["TEAM.md", "team.json", "agents", "team", "departments", "hr-departments"]) {
-    if (fs.existsSync(path.join(rootPath, name))) return "team";
+function cloudDecodeTextAsset(bytes) {
+  const utf16 = cloudDecodeUtf16CredentialText(bytes);
+  if (utf16 !== null) return { ok: true, text: utf16 };
+  try {
+    return { ok: true, text: new TextDecoder("utf-8", { fatal: true }).decode(bytes) };
+  } catch {
+    return { ok: false };
   }
-  return "agent";
 }
-function cloudPackageDir(slug) {
-  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-  return path.join(userDataDir(), "cloud-agent-packages", `${slug}-${stamp}`);
+function cloudCredentialValueLooksReal(rawValue) {
+  let value = String(rawValue || "").trim().replace(/^['"]|['"]$/g, "").trim();
+  try { value = decodeURIComponent(value); } catch { /* keep raw */ }
+  if (value.length < 8) return false;
+  if (/^(?:\$\{[^}]+\}|\$[A-Z_][A-Z0-9_]*|\{\{[^}]+\}\}|<[^>]+>)$/i.test(value)) return false;
+  if (/^(?:process\.env\.|os\.environ|env\(|secret\(|vault:)/i.test(value)) return false;
+  const compact = value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+  if (/^(?:your|example|sample|dummy|placeholder|configure|configureonthismachine|changeme|replaceme|replacewith|redacted|masked|notareal|none|null|undefined|x+|star+)(?:api)?(?:key|secret|token|password)?(?:here)?$/.test(compact)) return false;
+  if (/^(?:\*+|x+|_+|-+)$/.test(value)) return false;
+  return true;
 }
-function cloudHashPackage(files) {
-  const h = crypto.createHash("sha256");
-  // 서버(register/route.ts hashPackage)와 바이트 동일해야 한다: 경로 코드포인트 순 정렬.
-  // 정렬 없이 스캔 순서로 해시하면 대소문자 혼합 경로 패키지(AGENTS.md + agents/…)가
-  // 전부 package_hash_mismatch로 거절된다(2026-07-02 근본 수정).
-  for (const file of [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))) {
-    h.update(file.path);
-    h.update("\0");
-    h.update(file.sha256);
-    h.update("\0");
+function cloudTextContainsStructuredCredential(text) {
+  const assignment = /(?:^|\n)\s*["']?(?:api[_-]?key|access[_-]?token|auth[_-]?token|client[_-]?secret|secret|token|password|passwd|pwd)["']?\s*[:=]\s*([^\r\n#;]+)/gi;
+  for (const match of text.matchAll(assignment)) {
+    if (cloudCredentialValueLooksReal(match[1])) return true;
+  }
+  const urlCredential = /\bhttps?:\/\/[^/\s:@]+:([^@\s/]{8,})@/gi;
+  for (const match of text.matchAll(urlCredential)) {
+    if (cloudCredentialValueLooksReal(match[1])) return true;
+  }
+  const queryCredential = /[?&](?:api[_-]?key|access[_-]?token|auth[_-]?token|client[_-]?secret|secret|token|password)=([^&#\s]+)/gi;
+  for (const match of text.matchAll(queryCredential)) {
+    if (cloudCredentialValueLooksReal(match[1])) return true;
+  }
+  return false;
+}
+function cloudAddSecretFindingsFromBytes(bytes, relativePath, addFinding) {
+  const candidates = new Set([bytes.toString("utf8")]);
+  const utf16 = cloudDecodeUtf16CredentialText(bytes);
+  if (utf16) candidates.add(utf16);
+  for (const text of candidates) {
+    for (const [id, re, label] of CLOUD_SECRET_RE) {
+      if (re.test(text)) addFinding(id, "blocker", "secret", `Possible ${label} found in package content.`, relativePath, "Remove the value and require users to configure their own key.");
+    }
+    if (cloudTextContainsStructuredCredential(text)) {
+      addFinding("generic-unquoted-secret", "blocker", "secret", "Possible unquoted or URL-embedded credential found in package content.", relativePath, "Replace the value with an environment/BYOK placeholder.");
+    }
   }
-  return h.digest("hex");
+}
+function cloudCanonicalBase64(value) {
+  if (typeof value !== "string") return false;
+  if (value === "") return true;
+  if (value.length % 4 !== 0) return false;
+  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) return false;
+  return Buffer.from(value, "base64").toString("base64") === value;
 }
 function cloudSecuritySummary(findings) {
   const blockerCount = findings.filter((f) => f.severity === "blocker").length;
@@ -5958,67 +7647,154 @@ function resolveRuntime(db, override) {
 
 // ── API 러너 (BYOK / Ollama) — 비스트리밍, 최종 텍스트 반환 ──
 const DEFAULT_API_MODEL = {
-  anthropic: "claude-sonnet-4-5",
+  anthropic: "claude-sonnet-4-6",
   openai: "gpt-4o-mini",
   google: "gemini-1.5-flash",
   ollama: "llama3.1",
   upstage: "solar-pro2",
+  custom: "deepseek-chat",
+  glm: "glm-4.6",
+  kimi: "kimi-k2-0711-preview",
+  deepseek: "deepseek-chat",
+};
+const ANTHROPIC_COMPAT_API = {
+  glm: { label: "GLM", baseUrl: "https://api.z.ai/api/anthropic" },
+  kimi: { label: "Kimi", baseUrl: "https://api.moonshot.ai/anthropic" },
+  deepseek: { label: "DeepSeek", baseUrl: "https://api.deepseek.com/anthropic" },
 };
+const DEFAULT_CUSTOM_API_BASE_URL = "https://api.openai.com/v1";
+
 async function apiKey(backend) {
   const keytar = readKeytar();
   if (!keytar) return null;
   // 키체인 접근 거부(서명 안 된 standalone Node)는 "키 없음"으로 조용히 처리.
   return keytar.getPassword(SERVICE, "byok:" + backend).catch(() => null);
 }
-async function runApi(backend, model, system, prompt) {
+
+/**
+ * Custom BYOK 키가 전송될 origin을 Terminal에서도 다시 검증한다.
+ * Desktop IPC와 동일하게 공개 주소는 HTTPS만, HTTP는 localhost/LAN만 허용한다.
+ */
+function normalizeCustomApiBaseUrl(raw) {
+  const value = String(raw || "").trim();
+  if (!value) return DEFAULT_CUSTOM_API_BASE_URL;
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error("Custom API base URL이 올바르지 않습니다.");
+  }
+  const host = parsed.hostname.toLowerCase();
+  const isLoopback = host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+  const isPrivateLan =
+    /^10\./.test(host) || /^192\.168\./.test(host) || /^172\.(1[6-9]|2\d|3[01])\./.test(host);
+  if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && (isLoopback || isPrivateLan))) {
+    throw new Error("Custom API base URL은 HTTPS 또는 localhost/LAN의 HTTP여야 합니다.");
+  }
+  return value.replace(/\/+$/, "");
+}
+
+/** Desktop과 공유하는 SQLite meta에서 Custom OpenAI base URL을 읽는다. */
+function readCustomApiBaseUrl() {
+  const p = dbPath();
+  if (!fs.existsSync(p)) return DEFAULT_CUSTOM_API_BASE_URL;
+  let db = null;
+  let raw = "";
+  try {
+    try {
+      const Database = require("better-sqlite3");
+      db = new Database(p, { readonly: true, fileMustExist: true });
+    } catch {
+      db = openNodeSqliteDb(p);
+    }
+    try {
+      const row = db.prepare("SELECT value FROM meta WHERE key = 'custom_base_url'").get();
+      raw = row && row.value ? row.value : "";
+    } catch {
+      // 구버전 DB에 meta 테이블/키가 없으면 Desktop과 동일하게 OpenAI 기본 URL.
+      raw = "";
+    }
+  } catch (e) {
+    throw new Error(`Custom API base URL을 공유 DB에서 읽지 못했습니다: ${(e && e.message) || e}`);
+  } finally {
+    try { if (db && typeof db.close === "function") db.close(); } catch { /* ignore close failure */ }
+  }
+  return normalizeCustomApiBaseUrl(raw);
+}
+
+/**
+ * BYOK/Ollama 한 턴. 재사용 경로(swarm/automation)이므로 절대 process.exit하지 않고
+ * 오류를 throw해 호출자의 catch/finally가 리스 해제·부분 실패를 처리하게 한다.
+ * options는 회귀 테스트의 fetch/키 주입용이며 상용 호출자는 사용하지 않는다.
+ */
+async function runApi(backend, model, system, prompt, options) {
+  options = options || {};
   model = model || DEFAULT_API_MODEL[backend];
-  if (typeof fetch !== "function") fail("이 런타임에 fetch가 없습니다(앱 런타임으로 실행 필요).");
+  const fetchImpl = options.fetch || globalThis.fetch;
+  if (typeof fetchImpl !== "function") throw new Error("이 런타임에 fetch가 없습니다(앱 런타임으로 실행 필요).");
   if (backend === "ollama") {
-    const resp = await fetch("http://127.0.0.1:11434/api/chat", {
+    const resp = await fetchImpl("http://127.0.0.1:11434/api/chat", {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({ model, stream: false, messages: [{ role: "system", content: system }, { role: "user", content: prompt }] }),
     });
-    if (!resp.ok) fail(`Ollama ${resp.status} — 'ollama serve' 실행/모델 확인`);
+    if (!resp.ok) throw new Error(`Ollama ${resp.status} — 'ollama serve' 실행/모델 확인`);
     const j = await resp.json();
     return (j.message && j.message.content) || "";
   }
-  const key = await apiKey(backend);
-  if (!key) fail(`${backend} API 키가 없습니다. 앱 설정 → BYOK에서 키를 등록하세요.`);
-  if (backend === "anthropic") {
-    const resp = await fetch("https://api.anthropic.com/v1/messages", {
+  const supported = backend === "anthropic" || backend === "openai" || backend === "google" ||
+    backend === "upstage" || backend === "custom" || !!ANTHROPIC_COMPAT_API[backend];
+  if (!supported) throw new Error("지원하지 않는 backend: " + backend);
+  const key = Object.prototype.hasOwnProperty.call(options, "apiKey") ? options.apiKey : await apiKey(backend);
+  if (!key) throw new Error(`${backend} API 키가 없습니다. 앱 설정 → BYOK에서 키를 등록하세요.`);
+
+  const anthropicCompat = ANTHROPIC_COMPAT_API[backend];
+  if (backend === "anthropic" || anthropicCompat) {
+    const label = anthropicCompat ? anthropicCompat.label : "Anthropic";
+    const base = anthropicCompat ? anthropicCompat.baseUrl : "https://api.anthropic.com";
+    const authHeaders = anthropicCompat
+      ? { "x-api-key": key, authorization: "Bearer " + key }
+      : { "x-api-key": key };
+    const resp = await fetchImpl(`${base}/v1/messages`, {
       method: "POST",
-      headers: { "content-type": "application/json", "x-api-key": key, "anthropic-version": "2023-06-01" },
+      headers: { "content-type": "application/json", ...authHeaders, "anthropic-version": "2023-06-01" },
       body: JSON.stringify({ model, max_tokens: 4096, system, messages: [{ role: "user", content: prompt }] }),
     });
-    if (!resp.ok) fail(`Anthropic ${resp.status}: ${(await resp.text().catch(() => "")).slice(0, 200)}`);
+    if (!resp.ok) throw new Error(`${label} ${resp.status}: ${(await resp.text().catch(() => "")).slice(0, 200)}`);
     const j = await resp.json();
     return (j.content && j.content[0] && j.content[0].text) || "";
   }
-  if (backend === "openai" || backend === "upstage") {
-    const base = backend === "upstage" ? "https://api.upstage.ai/v1" : "https://api.openai.com/v1";
-    const resp = await fetch(`${base}/chat/completions`, {
+  if (backend === "openai" || backend === "upstage" || backend === "custom") {
+    const base = backend === "upstage"
+      ? "https://api.upstage.ai/v1"
+      : backend === "custom"
+        ? normalizeCustomApiBaseUrl(Object.prototype.hasOwnProperty.call(options, "customBaseUrl")
+          ? options.customBaseUrl
+          : readCustomApiBaseUrl())
+        : "https://api.openai.com/v1";
+    const label = backend === "custom" ? "Custom API" : backend === "upstage" ? "Upstage" : "OpenAI";
+    const resp = await fetchImpl(`${base}/chat/completions`, {
       method: "POST",
       headers: { "content-type": "application/json", authorization: "Bearer " + key },
       body: JSON.stringify({ model, messages: [{ role: "system", content: system }, { role: "user", content: prompt }] }),
     });
-    if (!resp.ok) fail(`OpenAI ${resp.status}: ${(await resp.text().catch(() => "")).slice(0, 200)}`);
+    if (!resp.ok) throw new Error(`${label} ${resp.status}: ${(await resp.text().catch(() => "")).slice(0, 200)}`);
     const j = await resp.json();
     return (j.choices && j.choices[0] && j.choices[0].message && j.choices[0].message.content) || "";
   }
   if (backend === "google") {
     const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${encodeURIComponent(key)}`;
-    const resp = await fetch(url, {
+    const resp = await fetchImpl(url, {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({ systemInstruction: { parts: [{ text: system }] }, contents: [{ role: "user", parts: [{ text: prompt }] }] }),
     });
-    if (!resp.ok) fail(`Google ${resp.status}: ${(await resp.text().catch(() => "")).slice(0, 200)}`);
+    if (!resp.ok) throw new Error(`Google ${resp.status}: ${(await resp.text().catch(() => "")).slice(0, 200)}`);
     const j = await resp.json();
     const c = j.candidates && j.candidates[0];
     return (c && c.content && c.content.parts && c.content.parts[0] && c.content.parts[0].text) || "";
   }
-  fail("지원하지 않는 backend: " + backend);
+  throw new Error("지원하지 않는 backend: " + backend);
 }
 
 // 1회 실행 — CLI면 spawn(스트리밍 stdout), API면 호출 후 텍스트 출력. 종료코드 반환.
@@ -6039,7 +7815,7 @@ async function executeOnce(db, system, prompt, override, ctx) {
     const { Ui } = require("./agentlas-ui.cjs");
     const ui = new Ui({ lang: prefsLang() });
     let mcpServers = [];
-    if (permission !== "read") {
+    if (permission === "full") {
       try {
         mcpServers = db.prepare("SELECT id, name, transport, command, args_json, enabled FROM mcp_servers WHERE enabled=1 AND transport='stdio'").all();
       } catch { /* ignore */ }
@@ -6134,25 +7910,10 @@ function runCwd() {
 }
 
 function cliMcpConfigPath() {
-  const dir = path.join(userDataDir(), "mcp");
-  fs.mkdirSync(dir, { recursive: true });
-  const file = path.join(dir, "agentlas-cli-mcp.json");
-  fs.writeFileSync(
-    file,
-    JSON.stringify({
-      mcpServers: {
-        playwright: { command: "npx", args: ["-y", "@playwright/mcp@latest"] },
-      },
-    }, null, 2),
-    "utf8",
-  );
-  return file;
+  return require("./agentlas-native-host.cjs").cliMcpConfigPath([]).file;
 }
 
-const CODEX_PLAYWRIGHT_MCP_ARGS = [
-  "-c", 'mcp_servers.playwright.command="npx"',
-  "-c", 'mcp_servers.playwright.args=["-y","@playwright/mcp@latest"]',
-];
+const CODEX_PLAYWRIGHT_MCP_ARGS = require("./agentlas-native-host.cjs").codexMcpArgs([]);
 
 // 에이전트가 실제로 실행될 작업 폴더 = 사용자가 명령을 친 현재 디렉터리(= 대상 프로젝트).
 // 단, home/userData/agent-cwd 같은 "프로젝트 아님" 위치면 안전한 전용 폴더로 폴백한다.
@@ -6231,14 +7992,40 @@ function readVaultEnvValuesCli(keys, projectPath) {
     ),
   ).then(() => result);
 }
+
+// 프로젝트/에이전트 dotenv는 일반 API 키 우선순위를 유지하되, 호스트 CLI의 신원·설치·
+// 플러그인 탐색 루트는 바꾸지 못한다. Windows 환경변수도 안전하게 대소문자 무관 비교한다.
+const PROTECTED_CHILD_ENV_KEYS_CLI = new Set([
+  "HOME", "PATH", "PATHEXT", "USERPROFILE", "HOMEDRIVE", "HOMEPATH", "APPDATA", "LOCALAPPDATA",
+  "XDG_CONFIG_HOME", "XDG_DATA_HOME", "CODEX_HOME", "CLAUDE_CONFIG_DIR", "CLAUDE_CODE_SAFE_MODE",
+  "AGENTLAS_CODEX_HOME", "AGENTLAS_USER_DATA_DIR",
+  "CLAUDE_CODE_SIMPLE", "CLAUDE_PLUGIN_ROOT", "CLAUDE_PLUGIN_DATA", "CLAUDE_PROJECT_DIR",
+  "GEMINI_CLI_HOME", "GEMINI_CLI_SYSTEM_SETTINGS_PATH", "GEMINI_CLI_USER_SETTINGS",
+  "GEMINI_CLI_TRUSTED_FOLDERS_PATH", "GEMINI_CLI_TRUST_WORKSPACE", "GEMINI_CLI_EXTENSION_REGISTRY_URI",
+  "HEPHAESTUS_RUNTIME_ROOT", "HEPHAESTUS_RUNTIME_BASE", "HEPHAESTUS_PYTHON", "HEPHAESTUS_AUTO_UPDATE",
+  "HEPHAESTUS_UPDATE_CHECK", "NPM_CONFIG_PREFIX", "NODE_OPTIONS", "NODE_PATH",
+  "PYTHONHOME", "PYTHONPATH", "LD_PRELOAD", "DYLD_INSERT_LIBRARIES", "DYLD_LIBRARY_PATH",
+  "AGENTLAS_HUB_CONNECT_TIMEOUT_MS", "AGENTLAS_HUB_IDLE_TIMEOUT_MS", "AGENTLAS_HUB_TOTAL_TIMEOUT_MS",
+  "AGENTLAS_NATIVE_IDLE_TIMEOUT_MS", "AGENTLAS_NATIVE_TOTAL_TIMEOUT_MS", "AGENTLAS_NATIVE_KILL_GRACE_MS",
+  "AGENTLAS_CAPTURE_MAX_OUTPUT_BYTES",
+]);
+function isProtectedChildEnvKeyCli(key) {
+  return PROTECTED_CHILD_ENV_KEYS_CLI.has(String(key || "").trim().toUpperCase());
+}
+function mergeChildEnvValuesCli(target, values, overwrite) {
+  const injected = [];
+  for (const [key, value] of Object.entries(values || {})) {
+    if (!value || isProtectedChildEnvKeyCli(key)) continue;
+    if (!overwrite && target[key]) continue;
+    target[key] = value;
+    injected.push(key);
+  }
+  return injected;
+}
 async function buildChildEnvCli(db, ctx) {
   const env = { ...process.env };
   const apply = (values, overwrite) => {
-    for (const [key, value] of Object.entries(values || {})) {
-      if (!value) continue;
-      if (!overwrite && env[key]) continue;
-      env[key] = value;
-    }
+    mergeChildEnvValuesCli(env, values, overwrite);
   };
   const globalCredentials = {
     ...readDotEnvFileCli(path.join(userDataDir(), "credentials.env")),
@@ -6265,33 +8052,27 @@ async function buildChildEnvCli(db, ctx) {
   return env;
 }
 
-// 권한 → 네이티브 CLI 권한 모드 매핑 (앱의 claude-code.ts 와 동일 의미).
-//   read=기본(헤드리스에서 위험 툴 자동 거부) · write=편집 허용 · full=셸 포함 전체 자동.
+// One-shot/background capture uses the same permission truth as the interactive host.
+// Keep its plain-output argument shape, but never duplicate the security mapping here.
 function buildArgs(kind, systemPrompt, prompt, permission) {
+  const native = require("./agentlas-native-host.cjs");
+  const level = require("./agentlas-permissions.cjs").normalize(permission);
   if (kind === "claude-code") {
-    const perm =
-      permission === "full"
-        ? ["--permission-mode", "bypassPermissions"]
-        : permission === "write"
-          ? ["--permission-mode", "acceptEdits"]
-          : [];
-    const mcp = permission === "write" || permission === "full"
-      ? ["--mcp-config", cliMcpConfigPath(), "--allowedTools", "mcp__playwright"]
-      : [];
+    const perm = native.claudePermissionArgs(level);
+    const mcp = level === "full"
+      ? ["--strict-mcp-config", "--mcp-config", cliMcpConfigPath(), "--allowedTools", "mcp__playwright"]
+      : native.claudeMcpIsolationArgs();
     return ["-p", prompt, "--append-system-prompt", systemPrompt, ...perm, ...mcp];
   }
   if (kind === "codex") {
-    // codex exec: browser/account setup flows must not stall on approval prompts.
-    const perm =
-      permission === "full" || permission === "write"
-        ? ["--dangerously-bypass-approvals-and-sandbox"]
-        : ["--sandbox", "read-only", "--ask-for-approval", "never"];
-    const mcp = permission === "write" || permission === "full" ? CODEX_PLAYWRIGHT_MCP_ARGS : [];
+    const perm = native.codexPermissionArgs(level);
+    const mcp = level === "full" ? CODEX_PLAYWRIGHT_MCP_ARGS : [];
     return ["exec", "--skip-git-repo-check", ...perm, ...mcp, `[SYSTEM]\n${systemPrompt}\n\n${prompt}`];
   }
   if (kind === "gemini") {
-    const perm = permission === "full" || permission === "write" ? ["--yolo"] : [];
-    return ["--prompt", `[SYSTEM]\n${systemPrompt}\n\n${prompt}`, ...perm];
+    const perm = native.geminiPermissionArgs(level);
+    const mcp = level === "full" ? [] : native.geminiMcpIsolationArgs();
+    return ["--prompt", `[SYSTEM]\n${systemPrompt}\n\n${prompt}`, ...perm, ...mcp];
   }
   return [prompt];
 }
@@ -6307,7 +8088,7 @@ function launchInteractive(db, agent, runtimeOverride) {
     id: agent.id,
     slug: agent.slug,
     label: agent.name,
-    system: agent.system_prompt || `You are ${agent.name}.`,
+    system: agentSystemPromptCli(agent),
     capAgent: agent,
   };
   return launchTui(db, subject, runtimeOverride);
@@ -6338,7 +8119,7 @@ function buildHelpers(db) {
     autoRoutePreamble: (choice, lang) => autoRoutePreamble(choice, lang),
     cliMemoryContext: (db_, pp) => cliMemoryContext(db_, pp),
     importLocal: (db_, p) => importLocalFolderCli(db_, p),
-    // REPL-safe 마켓플레이스 설치: fail()(process.exit) 대신 Error를 throw 해 REPL이 직접 렌더하게 한다.
+    // REPL-safe public Hub install: fail()(process.exit) 대신 Error를 throw 해 REPL이 직접 렌더하게 한다.
     cloudInstall: async (db_, slug) => {
       if (typeof fetch !== "function") throw new Error("이 런타임에 fetch가 없습니다(앱 런타임 필요).");
       const base = process.env.AGENTLAS_MCP_BASE_URL || "https://agentlas.cloud/api/mcp/v1";
@@ -6347,22 +8128,25 @@ function buildHelpers(db) {
       if (cookie) headers.cookie = cookie;
       let resp;
       try {
-        resp = await fetch(`${base.replace(/\/$/, "")}/tools/call`, {
+        resp = await fetchHubCli(`${base.replace(/\/$/, "")}/tools/call`, {
           method: "POST",
           headers,
           body: JSON.stringify({ method: "marketplace.get_manifest", params: { name: "marketplace.get_manifest", arguments: { kind: "agent", slug } } }),
         });
       } catch (e) {
-        throw new Error(`마켓플레이스 연결 실패: ${(e && e.message) || e}`);
+        throw new Error(`Hub 연결 실패: ${(e && e.message) || e}`);
       }
       if (!resp.ok) {
         const authHint = resp.status === 401 || resp.status === 403 ? " — 로그인이 필요합니다 (앱에서 로그인 또는 AGENTLAS_SESSION 설정)" : "";
-        throw new Error(`마켓플레이스 응답 ${resp.status}${authHint}`);
+        throw new Error(`Hub 응답 ${resp.status}${authHint}`);
       }
-      const json = await resp.json();
-      if (json.error) throw new Error(json.error.message || "marketplace error");
+      const json = parseHubJsonCli(resp, "marketplace.get_manifest");
+      if (json.error) throw new Error(json.error.message || "Hub error");
       const listing = json.result;
-      if (!listing) throw new Error(`마켓플레이스에서 찾을 수 없음: ${slug}`);
+      if (!listing) throw new Error(`Hub에서 찾을 수 없음: ${slug}`);
+      if (listing.delivery && listing.delivery.mode === "call_only") {
+        throw new Error(`이 Hub 에이전트는 call-only 자산입니다. 실행: agentlas call ${slug}`);
+      }
       return persistCloudListingCli(db_, listing);
     },
     hasCloudSession: async () => {
@@ -6473,10 +8257,11 @@ function spawnRuntime(kind, systemPrompt, prompt, opts) {
   const cwd = opts.cwd || runCwd();
   return new Promise((resolve) => {
     const bin = which(RUNTIME_BIN[kind]) || RUNTIME_BIN[kind];
+    const env = require("./agentlas-native-host.cjs").runtimeEnvForKind(kind, opts.env || process.env);
     const child = spawn(bin, buildArgs(kind, systemPrompt, prompt, opts.permission), {
       cwd,
       stdio: ["ignore", "inherit", "inherit"],
-      env: opts.env || process.env,
+      env,
     });
     child.on("error", (err) => {
       process.stderr.write(`\n실행 실패(${kind}): ${err.message}\n`);
@@ -6486,32 +8271,160 @@ function spawnRuntime(kind, systemPrompt, prompt, opts) {
   });
 }
 
+const CAPTURE_OUTPUT_DEFAULT_BYTES = 4 * 1024 * 1024;
+function captureOutputLimit(env = process.env) {
+  return finiteTimeoutMs(env.AGENTLAS_CAPTURE_MAX_OUTPUT_BYTES, CAPTURE_OUTPUT_DEFAULT_BYTES, 64 * 1024, 32 * 1024 * 1024);
+}
+function directCaptureOutputLimit(value) {
+  return finiteTimeoutMs(value, CAPTURE_OUTPUT_DEFAULT_BYTES, 128, 32 * 1024 * 1024);
+}
+
 function captureRuntime(kind, systemPrompt, prompt, opts) {
   opts = opts || {};
   const cwd = opts.cwd || runCwd();
+  const { nativeTimeoutConfig, directNativeTimeoutConfig } = require("./agentlas-native-host.cjs");
+  const timeout = opts.timeoutConfig
+    ? directNativeTimeoutConfig(opts.timeoutConfig)
+    : nativeTimeoutConfig(opts.env || process.env);
+  const outputLimit = opts.outputLimitBytes == null
+    ? captureOutputLimit(opts.env || process.env)
+    : directCaptureOutputLimit(opts.outputLimitBytes);
   return new Promise((resolve, reject) => {
     const bin = which(RUNTIME_BIN[kind]) || RUNTIME_BIN[kind];
-    const child = spawn(bin, buildArgs(kind, systemPrompt, prompt, opts.permission), {
-      cwd,
-      stdio: ["ignore", "pipe", "pipe"],
-      env: opts.env || process.env,
-    });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (chunk) => {
-      stdout += chunk.toString();
-    });
-    child.stderr.on("data", (chunk) => {
-      stderr += chunk.toString();
-    });
-    child.on("error", reject);
-    child.on("close", (code) => {
+    let child;
+    try {
+      const spawnImpl = opts.spawn || spawn;
+      const env = require("./agentlas-native-host.cjs").runtimeEnvForKind(kind, opts.env || process.env);
+      child = spawnImpl(bin, buildArgs(kind, systemPrompt, prompt, opts.permission), {
+        cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        env,
+      });
+    } catch (error) {
+      reject(error);
+      return;
+    }
+
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let capturedBytes = 0;
+    let settled = false;
+    let terminationError = null;
+    let idleTimer = null;
+    let totalTimer = null;
+    let killTimer = null;
+    let forceTimer = null;
+    let onStdout = () => {};
+    let onStderr = () => {};
+    let onError = () => {};
+    let onClose = () => {};
+    let onAbort = () => {};
+
+    const clearTimers = () => {
+      if (idleTimer) clearTimeout(idleTimer);
+      if (totalTimer) clearTimeout(totalTimer);
+      if (killTimer) clearTimeout(killTimer);
+      if (forceTimer) clearTimeout(forceTimer);
+      idleTimer = totalTimer = killTimer = forceTimer = null;
+    };
+    const cleanup = () => {
+      clearTimers();
+      child.stdout?.removeListener("data", onStdout);
+      child.stderr?.removeListener("data", onStderr);
+      child.removeListener("error", onError);
+      child.removeListener("close", onClose);
+      if (opts.signal) opts.signal.removeEventListener?.("abort", onAbort);
+    };
+    const finishReject = (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(error);
+    };
+    const finishResolve = (value) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(value);
+    };
+    const requestStop = (error) => {
+      if (settled || terminationError) return;
+      terminationError = error;
+      if (idleTimer) clearTimeout(idleTimer);
+      if (totalTimer) clearTimeout(totalTimer);
+      idleTimer = totalTimer = null;
+      try { child.kill("SIGTERM"); } catch { /* ignore */ }
+      if (settled) return;
+      killTimer = setTimeout(() => {
+        if (settled) return;
+        try { child.kill("SIGKILL"); } catch { /* ignore */ }
+        if (settled) return;
+        forceTimer = setTimeout(() => finishReject(terminationError), Math.max(250, Math.min(1_000, timeout.killGraceMs)));
+      }, timeout.killGraceMs);
+    };
+    const timeoutError = (phase, ms) => {
+      const error = new Error(
+        phase === "idle"
+          ? `${kind} capture idle timeout: ${ms}ms 동안 출력이 없습니다.`
+          : `${kind} capture total timeout: 전체 실행 시간이 ${ms}ms를 초과했습니다.`,
+      );
+      error.code = `AGENTLAS_CAPTURE_${phase.toUpperCase()}_TIMEOUT`;
+      return error;
+    };
+    const armIdle = () => {
+      if (settled || terminationError) return;
+      if (idleTimer) clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => requestStop(timeoutError("idle", timeout.idleMs)), timeout.idleMs);
+    };
+    const append = (target, chunk) => {
+      armIdle();
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      const remaining = Math.max(0, outputLimit - capturedBytes);
+      if (remaining > 0) {
+        const kept = bytes.length > remaining ? bytes.subarray(0, remaining) : bytes;
+        target.push(kept);
+        capturedBytes += kept.length;
+      }
+      if (bytes.length > remaining) {
+        const error = new Error(`${kind} capture output limit: ${outputLimit} bytes를 초과했습니다.`);
+        error.code = "AGENTLAS_CAPTURE_OUTPUT_LIMIT";
+        requestStop(error);
+      }
+    };
+
+    onStdout = (chunk) => append(stdoutChunks, chunk);
+    onStderr = (chunk) => append(stderrChunks, chunk);
+    onError = (error) => finishReject(terminationError || error);
+    onClose = (code) => {
+      if (terminationError) {
+        finishReject(terminationError);
+        return;
+      }
+      const stdout = Buffer.concat(stdoutChunks).toString("utf8");
+      const stderr = Buffer.concat(stderrChunks).toString("utf8");
       if (code && code !== 0) {
-        reject(new Error(`${kind} exited ${code}: ${stderr.slice(0, 500)}`));
+        finishReject(new Error(`${kind} exited ${code}: ${stderr.slice(-500)}`));
         return;
       }
-      resolve(stdout.trim() || stderr.trim());
-    });
+      finishResolve(stdout.trim() || stderr.trim());
+    };
+    onAbort = () => {
+      const reason = opts.signal && opts.signal.reason;
+      const error = reason instanceof Error ? reason : new Error(`${kind} capture aborted`);
+      if (!error.code) error.code = "ABORT_ERR";
+      requestStop(error);
+    };
+
+    child.stdout.on("data", onStdout);
+    child.stderr.on("data", onStderr);
+    child.on("error", onError);
+    child.on("close", onClose);
+    armIdle();
+    totalTimer = setTimeout(() => requestStop(timeoutError("total", timeout.totalMs)), timeout.totalMs);
+    if (opts.signal) {
+      if (opts.signal.aborted) onAbort();
+      else opts.signal.addEventListener("abort", onAbort, { once: true });
+    }
   });
 }
 
@@ -6578,7 +8491,7 @@ function cmdList(db) {
 
 function ensureNativeFiles(agent, folder) {
   fs.mkdirSync(folder, { recursive: true });
-  const sys = agent.system_prompt || `You are ${agent.name}.`;
+  const sys = agentSystemPromptCli(agent);
   writeIfMissing(path.join(folder, "system-prompt.md"), sys);
   const header = `# ${agent.name}\n\n${agent.tagline || ""}\n\n${sys}\n`;
   // 네이티브 CLI가 프로젝트 지시로 자동 인식하는 파일들
@@ -6615,7 +8528,7 @@ async function cmdRun(db, query, prompt, runtimeOverride) {
   if (!userPrompt) userPrompt = await readStdin();
   if (!userPrompt || !userPrompt.trim()) fail("프롬프트가 비어 있습니다. agentlas run <agent> \"...\" 또는 stdin으로 전달하세요.");
   process.stderr.write(`▸ ${agent.name}\n`);
-  const code = await executeOnce(db, agent.system_prompt || "", userPrompt.trim(), runtimeOverride, { projectPath: activeProjectPath(db), agentId: agent.id, permission: PERMISSION });
+  const code = await executeOnce(db, agentSystemPromptCli(agent), userPrompt.trim(), runtimeOverride, { projectPath: activeProjectPath(db), agentId: agent.id, permission: PERMISSION });
   process.exit(code);
 }
 
@@ -6625,7 +8538,7 @@ async function cmdAutoRun(db, prompt, runtimeOverride) {
   if (!choice) fail("자동 라우팅할 에이전트가 없습니다. agentlas list로 설치 상태를 확인하세요.");
   process.stderr.write(`▸ ${choice.agent.name} (auto)\n`);
   process.stderr.write(`  ${autoRouteNote(choice, lang)}\n`);
-  const sys = `${autoRoutePreamble(choice, lang)}\n\n${choice.agent.system_prompt || ""}`;
+  const sys = `${autoRoutePreamble(choice, lang)}\n\n${agentSystemPromptCli(choice.agent)}`;
   const code = await executeOnce(db, sys, prompt.trim(), runtimeOverride, {
     projectPath: activeProjectPath(db),
     agentId: choice.agent.id,
@@ -6722,7 +8635,15 @@ function upsertEnvLine(file, key, value) {
   if (re.test(body)) body = body.replace(re, line);
   else body = body ? body.replace(/\n?$/, "\n") + line + "\n" : line + "\n";
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, body, "utf8");
+  // 이 헬퍼의 모든 호출자는 credential 값/경로를 기록한다. 새 파일뿐 아니라 기존 0644
+  // 파일도 매번 0600으로 수렴시켜 같은 머신의 다른 계정이 읽지 못하게 한다.
+  fs.writeFileSync(file, body, { encoding: "utf8", mode: 0o600 });
+  try { fs.chmodSync(file, 0o600); } catch { /* Windows/읽기전용 FS best-effort */ }
+}
+function resolveCredentialSourcePath(source, cwd) {
+  // `agentlas creds file`은 일반 CLI 명령이므로 상대경로 기준은 사용자가 명령을 실행한
+  // 셸 cwd다. 런타임 격리용 agent-cwd를 쓰면 실제 프로젝트 파일을 조용히 못 찾는다.
+  return path.resolve(cwd || process.cwd(), source);
 }
 async function cmdCredsFile(db, args) {
   const f = parseCredFlags(args);
@@ -6740,7 +8661,7 @@ async function cmdCredsFile(db, args) {
   ensureLocalCredentialStoreCli(project, projectName, arch);
   ensureSoulCredentialIndexCli(project, projectName, arch);
 
-  const sourceAbs = path.resolve(runCwd(), source);
+  const sourceAbs = resolveCredentialSourcePath(source);
   let stat;
   try { stat = fs.statSync(sourceAbs); } catch { fail(`credential source not found: ${source}`); }
   if (!stat.isFile()) fail(`credential source is not a file: ${source}`);
@@ -6993,48 +8914,220 @@ function cmdUpdateHelp() {
   );
 }
 
-function versionParts(value) {
-  return String(value || "")
-    .trim()
-    .replace(/^v/i, "")
-    .split(/[.-]/)
-    .slice(0, 3)
-    .map((part) => {
-      const parsed = Number.parseInt(part, 10);
-      return Number.isFinite(parsed) ? parsed : 0;
-    });
+function macReleaseArch() {
+  if (process.arch === "arm64") return "arm64";
+  if (process.arch === "x64") return "x64";
+  return null;
+}
+
+const UPDATE_METADATA_MAX_BYTES = 1024 * 1024;
+const UPDATE_DOWNLOAD_MAX_BYTES = 1024 * 1024 * 1024;
+const UPDATE_TIMEOUT_DEFAULTS = Object.freeze({
+  metadata: Object.freeze({ connectMs: 15_000, idleMs: 15_000, totalMs: 30_000 }),
+  download: Object.freeze({ connectMs: 20_000, idleMs: 60_000, totalMs: 30 * 60_000 }),
+});
+
+function updateTimeoutConfig(env = process.env, kind = "download") {
+  const selected = kind === "metadata" ? "metadata" : "download";
+  const defaults = UPDATE_TIMEOUT_DEFAULTS[selected];
+  const prefix = selected === "metadata" ? "AGENTLAS_UPDATE_METADATA" : "AGENTLAS_UPDATE_DOWNLOAD";
+  const totalMs = finiteTimeoutMs(env[`${prefix}_TOTAL_TIMEOUT_MS`], defaults.totalMs, 5_000, 60 * 60_000);
+  return {
+    connectMs: Math.min(totalMs, finiteTimeoutMs(env[`${prefix}_CONNECT_TIMEOUT_MS`], defaults.connectMs, 1_000, 120_000)),
+    idleMs: Math.min(totalMs, finiteTimeoutMs(env[`${prefix}_IDLE_TIMEOUT_MS`], defaults.idleMs, 1_000, 300_000)),
+    totalMs,
+  };
 }
 
-function compareVersions(a, b) {
-  const left = versionParts(a);
-  const right = versionParts(b);
-  for (let i = 0; i < 3; i++) {
-    const delta = (left[i] || 0) - (right[i] || 0);
-    if (delta !== 0) return delta;
+function directUpdateTimeoutConfig(value = {}, kind = "download") {
+  const defaults = UPDATE_TIMEOUT_DEFAULTS[kind === "metadata" ? "metadata" : "download"];
+  const totalMs = finiteTimeoutMs(value.totalMs, defaults.totalMs, 10, 60 * 60_000);
+  return {
+    connectMs: Math.min(totalMs, finiteTimeoutMs(value.connectMs, defaults.connectMs, 10, 120_000)),
+    idleMs: Math.min(totalMs, finiteTimeoutMs(value.idleMs, defaults.idleMs, 10, 300_000)),
+    totalMs,
+  };
+}
+
+function updateDownloadMaxBytes(env = process.env) {
+  return finiteTimeoutMs(env.AGENTLAS_UPDATE_DOWNLOAD_MAX_BYTES, UPDATE_DOWNLOAD_MAX_BYTES, 16 * 1024 * 1024, 2 * 1024 * 1024 * 1024);
+}
+
+function updateTransferError(code, message, cause) {
+  const error = new Error(message, cause ? { cause } : undefined);
+  error.code = code;
+  return error;
+}
+
+function updateTimeoutError(kind, ms) {
+  const message = kind === "connect"
+    ? `업데이트 서버 연결 제한 시간(${ms}ms)을 초과했습니다.`
+    : kind === "idle"
+      ? `업데이트 전송이 ${ms}ms 동안 멈췄습니다.`
+      : `업데이트 요청 전체 제한 시간(${ms}ms)을 초과했습니다.`;
+  return updateTransferError(`AGENTLAS_UPDATE_${kind.toUpperCase()}_TIMEOUT`, message);
+}
+
+function parseSafeUpdateUrl(value, label = "업데이트 URL") {
+  let parsed;
+  try {
+    parsed = new URL(String(value || ""));
+  } catch (error) {
+    throw updateTransferError("AGENTLAS_UPDATE_INVALID_URL", `${label} 형식이 올바르지 않습니다.`, error);
+  }
+  const loopback = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "[::1]" || parsed.hostname === "::1";
+  if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && loopback)) {
+    throw updateTransferError("AGENTLAS_UPDATE_INSECURE_URL", `${label}은 HTTPS여야 합니다(로컬 루프백 제외).`);
+  }
+  if (parsed.username || parsed.password) {
+    throw updateTransferError("AGENTLAS_UPDATE_INVALID_URL", `${label}에 사용자 정보가 포함될 수 없습니다.`);
+  }
+  return parsed.toString();
+}
+
+/** Headers 전 connect, chunk 사이 idle, 전체 total 제한을 적용하는 bounded 스트림 reader. */
+async function consumeUpdateResponse(url, init = {}, options = {}) {
+  const fetchImpl = options.fetch || globalThis.fetch;
+  if (typeof fetchImpl !== "function") throw updateTransferError("AGENTLAS_UPDATE_FETCH_UNAVAILABLE", "이 런타임에 fetch가 없습니다.");
+  const kind = options.kind === "metadata" ? "metadata" : "download";
+  const timeout = options.timeoutConfig
+    ? directUpdateTimeoutConfig(options.timeoutConfig, kind)
+    : updateTimeoutConfig(options.env || process.env, kind);
+  const maxBytes = Number.isSafeInteger(options.maxBytes) && options.maxBytes > 0
+    ? options.maxBytes
+    : kind === "metadata" ? UPDATE_METADATA_MAX_BYTES : updateDownloadMaxBytes(options.env || process.env);
+  const expectedBytes = options.expectedBytes == null ? null : Number(options.expectedBytes);
+  const controller = new AbortController();
+  const upstreamSignal = init.signal;
+  let connectTimer = null;
+  let idleTimer = null;
+  let totalTimer = null;
+  let reader = null;
+  let terminalError = null;
+  let caughtError = null;
+  let rejectTerminal;
+  const terminal = new Promise((_, reject) => { rejectTerminal = reject; });
+  const stop = (error) => {
+    if (terminalError) return;
+    terminalError = error;
+    try { controller.abort(error); } catch { controller.abort(); }
+    rejectTerminal(error);
+  };
+  const onUpstreamAbort = () => {
+    const reason = upstreamSignal && upstreamSignal.reason;
+    const error = reason instanceof Error ? reason : updateTransferError("ABORT_ERR", "업데이트 요청이 취소되었습니다.");
+    if (!error.code) error.code = "ABORT_ERR";
+    stop(error);
+  };
+  const armIdle = () => {
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => stop(updateTimeoutError("idle", timeout.idleMs)), timeout.idleMs);
+  };
+
+  if (upstreamSignal) {
+    if (upstreamSignal.aborted) onUpstreamAbort();
+    else upstreamSignal.addEventListener("abort", onUpstreamAbort, { once: true });
+  }
+  connectTimer = setTimeout(() => stop(updateTimeoutError("connect", timeout.connectMs)), timeout.connectMs);
+  totalTimer = setTimeout(() => stop(updateTimeoutError("total", timeout.totalMs)), timeout.totalMs);
+
+  try {
+    const response = await Promise.race([
+      Promise.resolve().then(() => fetchImpl(url, { ...init, signal: controller.signal })),
+      terminal,
+    ]);
+    if (connectTimer) clearTimeout(connectTimer);
+    connectTimer = null;
+    if (!response || typeof response.ok !== "boolean") {
+      throw updateTransferError("AGENTLAS_UPDATE_INVALID_RESPONSE", "업데이트 서버 응답 형식이 올바르지 않습니다.");
+    }
+    if (response.url) parseSafeUpdateUrl(response.url, "리디렉션된 업데이트 URL");
+    if (!response.ok) {
+      throw updateTransferError("AGENTLAS_UPDATE_HTTP_ERROR", `업데이트 요청 실패: HTTP ${response.status}`);
+    }
+    const contentLengthValue = response.headers && response.headers.get ? response.headers.get("content-length") : null;
+    if (contentLengthValue != null && contentLengthValue !== "") {
+      const contentLength = Number(contentLengthValue);
+      if (!Number.isSafeInteger(contentLength) || contentLength < 0) {
+        throw updateTransferError("AGENTLAS_UPDATE_INVALID_CONTENT_LENGTH", "업데이트 서버의 Content-Length가 올바르지 않습니다.");
+      }
+      if (contentLength > maxBytes) {
+        throw updateTransferError("AGENTLAS_UPDATE_TOO_LARGE", `업데이트 응답이 허용 크기(${maxBytes} bytes)를 초과합니다.`);
+      }
+      if (Number.isSafeInteger(expectedBytes) && contentLength !== expectedBytes) {
+        throw updateTransferError("AGENTLAS_UPDATE_SIZE_MISMATCH", `다운로드 크기가 맞지 않습니다: expected=${expectedBytes} header=${contentLength}`);
+      }
+    }
+    if (!response.body || typeof response.body.getReader !== "function") {
+      throw updateTransferError("AGENTLAS_UPDATE_BODY_UNAVAILABLE", "업데이트 응답을 스트림으로 읽을 수 없습니다.");
+    }
+
+    reader = response.body.getReader();
+    let bytes = 0;
+    armIdle();
+    while (true) {
+      const part = await Promise.race([reader.read(), terminal]);
+      if (part.done) break;
+      armIdle();
+      const chunk = Buffer.from(part.value || []);
+      bytes += chunk.length;
+      if (bytes > maxBytes) {
+        const error = updateTransferError("AGENTLAS_UPDATE_TOO_LARGE", `업데이트 응답이 허용 크기(${maxBytes} bytes)를 초과했습니다.`);
+        stop(error);
+        throw error;
+      }
+      if (typeof options.onChunk === "function") await options.onChunk(chunk);
+    }
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = null;
+    return { response, bytes };
+  } catch (error) {
+    caughtError = terminalError || error;
+    try { controller.abort(caughtError); } catch { controller.abort(); }
+    throw caughtError;
+  } finally {
+    if (connectTimer) clearTimeout(connectTimer);
+    if (idleTimer) clearTimeout(idleTimer);
+    if (totalTimer) clearTimeout(totalTimer);
+    if (upstreamSignal) upstreamSignal.removeEventListener?.("abort", onUpstreamAbort);
+    if (reader && caughtError) {
+      try { await reader.cancel(caughtError); } catch { /* ignore */ }
+    }
   }
-  return 0;
 }
 
-function macReleaseArch() {
-  if (process.arch === "arm64") return "arm64";
-  if (process.arch === "x64") return "x64";
-  return null;
+async function fetchUpdateMetadata(url, options = {}) {
+  const safeUrl = parseSafeUpdateUrl(url, "업데이트 메타데이터 URL");
+  const chunks = [];
+  let bytes = 0;
+  await consumeUpdateResponse(safeUrl, { headers: { accept: "application/json", "accept-encoding": "identity" }, signal: options.signal }, {
+    ...options,
+    kind: "metadata",
+    maxBytes: Number.isSafeInteger(options.maxBytes) ? options.maxBytes : UPDATE_METADATA_MAX_BYTES,
+    onChunk(chunk) {
+      bytes += chunk.length;
+      chunks.push(chunk);
+    },
+  });
+  let json;
+  try {
+    json = JSON.parse(Buffer.concat(chunks, bytes).toString("utf8"));
+  } catch (error) {
+    throw updateTransferError("AGENTLAS_UPDATE_INVALID_METADATA", "업데이트 정보가 올바른 JSON이 아닙니다.", error);
+  }
+  if (!json || typeof json !== "object" || Array.isArray(json) || !parseSemVer(json.version)) {
+    throw updateTransferError("AGENTLAS_UPDATE_INVALID_METADATA", "업데이트 정보 형식이 올바르지 않습니다.");
+  }
+  return { ...json, version: normalizeSemVer(json.version) };
 }
 
 async function fetchDesktopRelease(url) {
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), 20_000);
   try {
-    const resp = await fetch(url, { headers: { accept: "application/json" }, signal: controller.signal });
-    if (!resp.ok) fail(`업데이트 정보를 가져오지 못했습니다: ${resp.status}`);
-    const json = await resp.json();
-    if (!json || typeof json !== "object" || !json.version) fail("업데이트 정보 형식이 올바르지 않습니다.");
-    return json;
+    return await fetchUpdateMetadata(url, { signal: controller.signal });
   } catch (error) {
-    const message = error && error.name === "AbortError" ? "요청 시간이 초과되었습니다." : String((error && error.message) || error);
+    const message = String((error && error.message) || error);
     fail(`업데이트 확인 실패: ${message}`);
-  } finally {
-    clearTimeout(timer);
   }
 }
 
@@ -7069,8 +9162,9 @@ async function cmdUpdateStandalone(flags) {
     const resp = await fetch("https://registry.npmjs.org/agentlas/latest", { headers: { accept: "application/json" } });
     if (resp.ok) latestVersion = String((await resp.json()).version || "");
   } catch { /* offline 등 — 아래에서 안내 */ }
+  const comparison = latestVersion ? compareSemVer(currentVersion, latestVersion) : null;
   if (flags.json) {
-    return out(JSON.stringify({ currentVersion, latestVersion, updateAvailable: latestVersion ? compareVersions(currentVersion, latestVersion) < 0 : null, channel: "npm" }, null, 2));
+    return out(JSON.stringify({ currentVersion, latestVersion, updateAvailable: comparison == null ? null : comparison < 0, channel: "npm" }, null, 2));
   }
   out(`현재 버전: ${currentVersion}`);
   if (!latestVersion) {
@@ -7079,7 +9173,9 @@ async function cmdUpdateStandalone(flags) {
     return;
   }
   out(`최신 버전: ${latestVersion}`);
-  if (compareVersions(currentVersion, latestVersion) < 0) {
+  if (comparison == null) {
+    out("버전 형식을 비교하지 못했습니다. 수동 업데이트:  npm i -g agentlas@latest");
+  } else if (comparison < 0) {
     out("업데이트:  npm i -g agentlas@latest");
   } else {
     out("이미 최신 버전입니다.");
@@ -7096,7 +9192,9 @@ async function cmdUpdate(args) {
   const release = await fetchDesktopRelease(flags.url);
   const latestVersion = String(release.version || "");
   const artifact = findCurrentArtifact(release);
-  const updateAvailable = compareVersions(currentVersion, latestVersion) < 0;
+  const comparison = compareSemVer(currentVersion, latestVersion);
+  if (comparison == null) fail(`현재/최신 버전이 SemVer 형식이 아닙니다: current=${currentVersion} latest=${latestVersion}`);
+  const updateAvailable = comparison < 0;
   const status = {
     currentVersion,
     latestVersion,
@@ -7153,17 +9251,80 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-async function downloadUpdateFile(url, destination, artifact) {
-  const resp = await fetch(url);
-  if (!resp.ok) fail(`다운로드 실패: ${resp.status}`);
-  const bytes = Buffer.from(await resp.arrayBuffer());
-  fs.writeFileSync(destination, bytes);
-  if (artifact.sizeBytes && bytes.length !== Number(artifact.sizeBytes)) {
-    fail(`다운로드 크기가 맞지 않습니다: expected=${artifact.sizeBytes} actual=${bytes.length}`);
+function validateDesktopUpdateArtifact(artifact, options = {}) {
+  if (!artifact || typeof artifact !== "object" || Array.isArray(artifact)) {
+    throw updateTransferError("AGENTLAS_UPDATE_INVALID_ARTIFACT", "업데이트 아티팩트 정보가 없습니다.");
+  }
+  const url = parseSafeUpdateUrl(artifact.url, "업데이트 아티팩트 URL");
+  const sha256 = String(artifact.sha256 || "").trim().toLowerCase();
+  if (!/^[a-f0-9]{64}$/.test(sha256)) {
+    throw updateTransferError("AGENTLAS_UPDATE_MISSING_DIGEST", "안전한 자동 업데이트를 위해 64자리 SHA-256이 반드시 필요합니다.");
+  }
+  const sizeBytes = Number(artifact.sizeBytes);
+  if (!Number.isSafeInteger(sizeBytes) || sizeBytes <= 0) {
+    throw updateTransferError("AGENTLAS_UPDATE_MISSING_SIZE", "안전한 자동 업데이트를 위해 정확한 sizeBytes가 반드시 필요합니다.");
+  }
+  const maxBytes = Number.isSafeInteger(options.maxBytes) && options.maxBytes > 0
+    ? options.maxBytes
+    : updateDownloadMaxBytes(options.env || process.env);
+  if (sizeBytes > maxBytes) {
+    throw updateTransferError("AGENTLAS_UPDATE_TOO_LARGE", `업데이트 파일 크기(${sizeBytes} bytes)가 허용 한도(${maxBytes} bytes)를 초과합니다.`);
+  }
+  let fileName = artifact.fileName == null ? "" : String(artifact.fileName).trim();
+  if (fileName) {
+    if (fileName.length > 180 || /[\\/\0]/.test(fileName) || path.basename(fileName) !== fileName || !fileName.toLowerCase().endsWith(".dmg")) {
+      throw updateTransferError("AGENTLAS_UPDATE_INVALID_FILENAME", "업데이트 파일 이름이 안전하지 않습니다.");
+    }
+  }
+  return { ...artifact, url, sha256, sizeBytes, fileName };
+}
+
+async function downloadUpdateFile(url, destination, artifact, options = {}) {
+  const validated = validateDesktopUpdateArtifact({ ...artifact, url }, options);
+  if (fs.existsSync(destination)) {
+    throw updateTransferError("AGENTLAS_UPDATE_DESTINATION_EXISTS", `업데이트 다운로드 대상이 이미 존재합니다: ${destination}`);
+  }
+  const partialPath = options.partialPath || `${destination}.partial.${process.pid}.${crypto.randomBytes(6).toString("hex")}`;
+  if (fs.existsSync(partialPath)) {
+    throw updateTransferError("AGENTLAS_UPDATE_PARTIAL_EXISTS", `업데이트 임시 파일이 이미 존재합니다: ${partialPath}`);
   }
-  if (artifact.sha256) {
-    const actual = crypto.createHash("sha256").update(bytes).digest("hex");
-    if (actual !== artifact.sha256) fail(`다운로드 해시가 맞지 않습니다: ${actual}`);
+  const hash = crypto.createHash("sha256");
+  let fd = null;
+  let actualBytes = 0;
+  try {
+    fd = fs.openSync(partialPath, "wx", 0o600);
+    await consumeUpdateResponse(validated.url, {
+      headers: { accept: "application/octet-stream", "accept-encoding": "identity" },
+      signal: options.signal,
+    }, {
+      ...options,
+      kind: "download",
+      maxBytes: Number.isSafeInteger(options.maxBytes) ? options.maxBytes : updateDownloadMaxBytes(options.env || process.env),
+      expectedBytes: validated.sizeBytes,
+      onChunk(chunk) {
+        fs.writeSync(fd, chunk, 0, chunk.length);
+        hash.update(chunk);
+        actualBytes += chunk.length;
+      },
+    });
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = null;
+    if (actualBytes !== validated.sizeBytes) {
+      throw updateTransferError("AGENTLAS_UPDATE_SIZE_MISMATCH", `다운로드 크기가 맞지 않습니다: expected=${validated.sizeBytes} actual=${actualBytes}`);
+    }
+    const actualSha256 = hash.digest("hex");
+    if (actualSha256 !== validated.sha256) {
+      throw updateTransferError("AGENTLAS_UPDATE_DIGEST_MISMATCH", `다운로드 SHA-256이 맞지 않습니다: expected=${validated.sha256} actual=${actualSha256}`);
+    }
+    fs.renameSync(partialPath, destination);
+    return { bytes: actualBytes, sha256: actualSha256, destination };
+  } catch (error) {
+    if (fd != null) {
+      try { fs.closeSync(fd); } catch { /* ignore */ }
+    }
+    try { fs.rmSync(partialPath, { force: true }); } catch { /* ignore */ }
+    throw error;
   }
 }
 
@@ -7180,10 +9341,199 @@ function macAppInstallPath() {
   return "/Applications/Agentlas.app";
 }
 
+async function verifyMacAppBundle(appPath, options = {}) {
+  const runner = options.runCommand || runCommand;
+  const commands = options.commands || {};
+  if (!commands.codesign || !commands.spctl) {
+    throw updateTransferError("AGENTLAS_UPDATE_VERIFY_TOOL_MISSING", "앱 서명 검증 도구가 지정되지 않았습니다.");
+  }
+  await runner(commands.codesign, ["--verify", "--deep", "--strict", "--verbose=2", appPath]);
+  const detail = await runner(commands.codesign, ["-d", "--verbose=4", appPath], { capture: true });
+  const signatureText = `${(detail && detail.stdout) || ""}\n${(detail && detail.stderr) || ""}`;
+  const identifier = (signatureText.match(/^Identifier=(.+)$/m) || [])[1]?.trim() || "";
+  const teamIdentifier = (signatureText.match(/^TeamIdentifier=(.+)$/m) || [])[1]?.trim() || "";
+  if (identifier !== "com.agentlas.desktop") {
+    throw updateTransferError("AGENTLAS_UPDATE_SIGNER_MISMATCH", `앱 번들 식별자가 올바르지 않습니다: ${identifier || "missing"}`);
+  }
+  if (!teamIdentifier || teamIdentifier.toLowerCase() === "not set") {
+    throw updateTransferError("AGENTLAS_UPDATE_SIGNER_MISSING", "앱 서명에서 Apple TeamIdentifier를 확인하지 못했습니다.");
+  }
+  await runner(commands.spctl, ["-a", "-t", "exec", "-vv", appPath]);
+  return { identifier, teamIdentifier };
+}
+
+function assertSameMacSigningIdentity(expected, actual, phase) {
+  if (!expected || !actual) return;
+  if (expected.identifier !== actual.identifier || expected.teamIdentifier !== actual.teamIdentifier) {
+    throw updateTransferError(
+      "AGENTLAS_UPDATE_SIGNER_MISMATCH",
+      `${phase} 앱의 서명 주체가 다릅니다: expected=${expected.identifier}/${expected.teamIdentifier} actual=${actual.identifier}/${actual.teamIdentifier}`,
+    );
+  }
+}
+
+async function removeUpdatePathChecked(targetPath, options) {
+  const fsImpl = options.fs || fs;
+  if (!fsImpl.existsSync(targetPath)) return;
+  try {
+    await options.runCommand(options.commands.rm, ["-rf", targetPath]);
+  } catch (error) {
+    if (fsImpl.existsSync(targetPath)) throw error;
+  }
+  if (fsImpl.existsSync(targetPath)) {
+    throw updateTransferError("AGENTLAS_UPDATE_REMOVE_FAILED", `업데이트 임시 경로를 제거하지 못했습니다: ${targetPath}`);
+  }
+}
+
+/**
+ * 기존 앱을 같은 디렉터리의 backup으로 원자 이동한 뒤 staging 앱을 검증해 교체한다.
+ * backup이 생긴 이후 어느 단계든 실패하면 원본을 다시 이동하고 서명까지 재검증한다.
+ */
+async function replaceMacAppBundle(options) {
+  const rawPaths = [options.sourceApp, options.targetApp, options.backupPath, options.stagingPath];
+  if (rawPaths.some((value) => typeof value !== "string" || !value.trim())) {
+    throw updateTransferError("AGENTLAS_UPDATE_PATH_MISSING", "업데이트 source/target/backup/staging 경로가 모두 필요합니다.");
+  }
+  const sourceApp = path.resolve(options.sourceApp);
+  const targetApp = path.resolve(options.targetApp);
+  const backupPath = path.resolve(options.backupPath);
+  const stagingPath = path.resolve(options.stagingPath);
+  const runner = options.runCommand || runCommand;
+  const fsImpl = options.fs || fs;
+  const commands = options.commands || {};
+  const verifyApp = options.verifyApp || ((appPath, context) => verifyMacAppBundle(appPath, {
+    runCommand: runner,
+    commands,
+    context,
+  }));
+  if (!commands.mv || !commands.rm || !commands.ditto) {
+    throw updateTransferError("AGENTLAS_UPDATE_INSTALL_TOOL_MISSING", "앱 교체 도구가 지정되지 않았습니다.");
+  }
+  if (!fsImpl.existsSync(sourceApp)) {
+    throw updateTransferError("AGENTLAS_UPDATE_SOURCE_MISSING", `설치할 앱을 찾지 못했습니다: ${sourceApp}`);
+  }
+  if (!sourceApp.toLowerCase().endsWith(".app") || !targetApp.toLowerCase().endsWith(".app")) {
+    throw updateTransferError("AGENTLAS_UPDATE_INVALID_APP_PATH", "업데이트 source와 target은 .app 번들이어야 합니다.");
+  }
+  if (new Set([sourceApp, targetApp, backupPath, stagingPath]).size !== 4) {
+    throw updateTransferError("AGENTLAS_UPDATE_PATH_COLLISION", "업데이트 source/target/backup/staging 경로가 서로 달라야 합니다.");
+  }
+  if (path.dirname(backupPath) !== path.dirname(targetApp) || path.dirname(stagingPath) !== path.dirname(targetApp)) {
+    throw updateTransferError("AGENTLAS_UPDATE_NONATOMIC_PATH", "backup과 staging은 대상 앱과 같은 디렉터리에 있어야 합니다.");
+  }
+  if (fsImpl.existsSync(backupPath) || fsImpl.existsSync(stagingPath)) {
+    throw updateTransferError("AGENTLAS_UPDATE_PATH_EXISTS", "업데이트 backup 또는 staging 경로가 이미 존재합니다.");
+  }
+
+  const hadOriginal = fsImpl.existsSync(targetApp);
+  let sourceIdentity = null;
+  let originalIdentity = null;
+  try {
+    sourceIdentity = await verifyApp(sourceApp, { phase: "source" });
+    if (hadOriginal) {
+      originalIdentity = await verifyApp(targetApp, { phase: "original" });
+      assertSameMacSigningIdentity(originalIdentity, sourceIdentity, "새 릴리즈");
+      await runner(commands.mv, [targetApp, backupPath]);
+      if (fsImpl.existsSync(targetApp) || !fsImpl.existsSync(backupPath)) {
+        throw updateTransferError("AGENTLAS_UPDATE_BACKUP_FAILED", "기존 앱 백업 이동을 확인하지 못했습니다.");
+      }
+      const backupIdentity = await verifyApp(backupPath, { phase: "backup" });
+      assertSameMacSigningIdentity(originalIdentity, backupIdentity, "백업");
+    }
+
+    await runner(commands.ditto, [sourceApp, stagingPath]);
+    if (!fsImpl.existsSync(stagingPath)) {
+      throw updateTransferError("AGENTLAS_UPDATE_STAGE_MISSING", "복사 후 staging 앱을 찾지 못했습니다.");
+    }
+    const stagingIdentity = await verifyApp(stagingPath, { phase: "staging" });
+    assertSameMacSigningIdentity(sourceIdentity, stagingIdentity, "staging");
+    await runner(commands.mv, [stagingPath, targetApp]);
+    if (fsImpl.existsSync(stagingPath) || !fsImpl.existsSync(targetApp)) {
+      throw updateTransferError("AGENTLAS_UPDATE_COMMIT_FAILED", "검증된 앱의 최종 이동을 확인하지 못했습니다.");
+    }
+    const installedIdentity = await verifyApp(targetApp, { phase: "installed" });
+    assertSameMacSigningIdentity(sourceIdentity, installedIdentity, "설치된");
+
+    let backupRetained = false;
+    if (hadOriginal && fsImpl.existsSync(backupPath)) {
+      try {
+        await removeUpdatePathChecked(backupPath, { fs: fsImpl, runCommand: runner, commands });
+      } catch {
+        backupRetained = fsImpl.existsSync(backupPath);
+      }
+    }
+    return { hadOriginal, backupRetained, backupPath: backupRetained ? backupPath : null };
+  } catch (originalError) {
+    if (hadOriginal && fsImpl.existsSync(backupPath)) {
+      let rollbackError = null;
+      try {
+        if (fsImpl.existsSync(stagingPath)) {
+          try { await removeUpdatePathChecked(stagingPath, { fs: fsImpl, runCommand: runner, commands }); } catch { /* does not block original restore */ }
+        }
+        if (fsImpl.existsSync(targetApp)) {
+          await removeUpdatePathChecked(targetApp, { fs: fsImpl, runCommand: runner, commands });
+        }
+        await runner(commands.mv, [backupPath, targetApp]);
+        if (fsImpl.existsSync(backupPath) || !fsImpl.existsSync(targetApp)) {
+          throw updateTransferError("AGENTLAS_UPDATE_RESTORE_MOVE_FAILED", "백업 앱의 원위치 복구를 확인하지 못했습니다.");
+        }
+        const restoredIdentity = await verifyApp(targetApp, { phase: "restored" });
+        assertSameMacSigningIdentity(originalIdentity, restoredIdentity, "복구된");
+      } catch (error) {
+        rollbackError = error;
+      }
+      if (rollbackError) {
+        const critical = updateTransferError(
+          "AGENTLAS_UPDATE_ROLLBACK_FAILED",
+          `앱 교체 실패 후 원본 복구를 완료하지 못했습니다. target=${targetApp} backup=${backupPath}: ${rollbackError.message || rollbackError}`,
+          originalError,
+        );
+        critical.rollbackError = rollbackError;
+        critical.backupPath = fsImpl.existsSync(backupPath) ? backupPath : null;
+        critical.targetPath = fsImpl.existsSync(targetApp) ? targetApp : null;
+        throw critical;
+      }
+      const rolledBack = updateTransferError(
+        "AGENTLAS_UPDATE_REPLACEMENT_FAILED_ROLLED_BACK",
+        `앱 교체에 실패했지만 기존 앱을 복구하고 서명을 확인했습니다: ${originalError.message || originalError}`,
+        originalError,
+      );
+      rolledBack.restoredPath = targetApp;
+      throw rolledBack;
+    }
+
+    try {
+      if (fsImpl.existsSync(stagingPath)) {
+        await removeUpdatePathChecked(stagingPath, { fs: fsImpl, runCommand: runner, commands });
+      }
+      if (!hadOriginal && fsImpl.existsSync(targetApp)) {
+        await removeUpdatePathChecked(targetApp, { fs: fsImpl, runCommand: runner, commands });
+      }
+    } catch (cleanupError) {
+      const cleanupFailure = updateTransferError(
+        "AGENTLAS_UPDATE_CLEANUP_FAILED",
+        `앱 교체 실패 후 임시 앱을 제거하지 못했습니다: ${cleanupError.message || cleanupError}`,
+        originalError,
+      );
+      cleanupFailure.cleanupError = cleanupError;
+      throw cleanupFailure;
+    }
+    if (hadOriginal && !fsImpl.existsSync(targetApp)) {
+      throw updateTransferError(
+        "AGENTLAS_UPDATE_ROLLBACK_FAILED",
+        `앱 교체 실패 후 기존 앱과 백업을 모두 찾지 못했습니다. target=${targetApp} backup=${backupPath}`,
+        originalError,
+      );
+    }
+    throw originalError;
+  }
+}
+
 async function installMacDesktopUpdate(release, artifact, flags) {
   const hdiutil = requirePath("/usr/bin/hdiutil", "hdiutil");
   const xcrun = requirePath("/usr/bin/xcrun", "xcrun");
   const spctl = requirePath("/usr/sbin/spctl", "spctl");
+  const codesign = requirePath("/usr/bin/codesign", "codesign");
   const osascript = requirePath("/usr/bin/osascript", "osascript");
   const ditto = requirePath("/usr/bin/ditto", "ditto");
   const plistBuddy = requirePath("/usr/libexec/PlistBuddy", "PlistBuddy");
@@ -7192,16 +9542,21 @@ async function installMacDesktopUpdate(release, artifact, flags) {
   const open = requirePath("/usr/bin/open", "open");
   const lsregister = "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister";
 
+  const validatedArtifact = validateDesktopUpdateArtifact(artifact);
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agentlas-update."));
-  const fileName = artifact.fileName || `Agentlas-${release.version}-${artifact.arch || macReleaseArch()}.dmg`;
+  const fileName = validatedArtifact.fileName || `Agentlas-${macReleaseArch() || "mac"}.dmg`;
   const dmgPath = path.join(tmpDir, fileName);
   let mountPoint = "";
-  let backupPath = "";
   const targetApp = macAppInstallPath();
+  const transactionId = `${Date.now()}.${process.pid}.${crypto.randomBytes(5).toString("hex")}`;
+  const targetDir = path.dirname(targetApp);
+  const targetName = path.basename(targetApp, path.extname(targetApp));
+  const backupPath = path.join(targetDir, `.${targetName}.backup.${transactionId}.app`);
+  const stagingPath = path.join(targetDir, `.${targetName}.installing.${transactionId}.app`);
 
   try {
     out(`다운로드: ${fileName}`);
-    await downloadUpdateFile(artifact.url, dmgPath, artifact);
+    await downloadUpdateFile(validatedArtifact.url, dmgPath, validatedArtifact);
     out("검증: DMG, notarization, Gatekeeper");
     await runCommand(hdiutil, ["verify", dmgPath]);
     await runCommand(xcrun, ["stapler", "validate", dmgPath]);
@@ -7210,34 +9565,29 @@ async function installMacDesktopUpdate(release, artifact, flags) {
     const mount = await runCommand(hdiutil, ["attach", "-nobrowse", "-readonly", dmgPath], { capture: true });
     mountPoint = parseHdiutilMountPoint(mount.stdout);
     const sourceApp = mountPoint ? path.join(mountPoint, "Agentlas.app") : "";
-    if (!sourceApp || !fs.existsSync(sourceApp)) fail("DMG 안에서 Agentlas.app을 찾지 못했습니다.");
+    if (!sourceApp || !fs.existsSync(sourceApp)) {
+      throw updateTransferError("AGENTLAS_UPDATE_APP_MISSING", "DMG 안에서 Agentlas.app을 찾지 못했습니다.");
+    }
 
     const installedVersion = await runCommand(plistBuddy, ["-c", "Print :CFBundleShortVersionString", path.join(sourceApp, "Contents", "Info.plist")], { capture: true });
     const appVersion = installedVersion.stdout.trim();
-    if (appVersion !== String(release.version)) fail(`앱 버전이 릴리즈와 다릅니다: release=${release.version} app=${appVersion}`);
-    await runCommand(spctl, ["-a", "-vv", sourceApp]);
+    if (appVersion !== String(release.version)) {
+      throw updateTransferError("AGENTLAS_UPDATE_VERSION_MISMATCH", `앱 버전이 릴리즈와 다릅니다: release=${release.version} app=${appVersion}`);
+    }
 
     out("설치: 기존 Agentlas 종료 후 앱 교체");
     await runCommand(osascript, ["-e", 'tell application "Agentlas" to quit'], { capture: true, allowFailure: true });
     await sleep(2_000);
-    if (fs.existsSync(targetApp)) {
-      backupPath = `${targetApp}.backup.${Date.now()}`;
-      await runCommand(mv, [targetApp, backupPath]);
-    }
-    await runCommand(ditto, [sourceApp, targetApp]);
+    const replacement = await replaceMacAppBundle({
+      sourceApp,
+      targetApp,
+      backupPath,
+      stagingPath,
+      runCommand,
+      commands: { codesign, spctl, ditto, mv, rm },
+    });
+    if (replacement.backupRetained) out(`주의: 검증된 새 앱은 설치됐지만 이전 앱 백업을 지우지 못했습니다: ${replacement.backupPath}`);
     if (fs.existsSync(lsregister)) await runCommand(lsregister, ["-f", targetApp], { allowFailure: true });
-
-    try {
-      await runCommand(spctl, ["-a", "-vv", targetApp]);
-    } catch (error) {
-      if (backupPath && fs.existsSync(backupPath)) {
-        await runCommand(rm, ["-rf", targetApp], { allowFailure: true });
-        await runCommand(mv, [backupPath, targetApp], { allowFailure: true });
-      }
-      throw error;
-    }
-
-    if (backupPath && fs.existsSync(backupPath)) await runCommand(rm, ["-rf", backupPath], { allowFailure: true });
     if (flags.launch) await runCommand(open, ["-a", "Agentlas"], { allowFailure: true });
     out(`Agentlas ${release.version} 설치 완료.`);
   } finally {
@@ -7581,7 +9931,8 @@ function cmdHelp() {
       "  search \"<what you need>\" discover agents in the Hub + local            (hep-search)",
       "  install <slug>           install an agent from the Hub                    (hep-cloud)",
       "  build \"<request>\"        build/repair/package an agent or team           (hep-build)",
-      "  upload <path>            package + publish an agent to the Hub            (hep-upload)",
+      "  upload <path>            save owner-private in Agent Cloud (default)       (hep-upload)",
+      "    --visibility marketplace  explicit compatibility flag: publish to Hub",
       "  connect [<sub>]          wire Telegram / platforms to an agent team       (hep-connect)",
       "  import <path>            import a local agent/team folder",
       "  list                     installed agents/companies + active runtime",
@@ -7614,7 +9965,7 @@ function cmdHelp() {
       hdr("ADVANCED"),
       "  hep <sub…>               full Hephaestus passthrough (wizard·security·cards·ao·plugins·meta-agent…)",
       "  netadmin <sub>           local network admin: init|status|reindex|bench|add-source",
-      "  cloud <sub>              agent packaging: wizard|security|bundle|package|publish|field-test",
+      "  cloud <sub>              cloud assets: save|publish|package|list|restore|field-test",
       "  cd <agent>               print the agent folder — cd \"$(agentlas cd seo)\" && claude",
       "  oberon <sub>             AI film render (scaffold|render|list)",
       "",
@@ -7666,6 +10017,10 @@ async function main() {
 
   const db = openDb();
 
+  // Finish or compensate any Cloud install interrupted between the durable
+  // filesystem swap and the SQLite transaction before normal agent resolution.
+  recoverCloudInstallJournalsCli(db);
+
   // Agentlas 아키텍처 빌트인 에이전트를 보장(앱과 동일, 멱등·버전 게이팅). 스키마가 준비됐을 때만.
   try { seedBuiltins(db); } catch { /* best-effort */ }
 
@@ -7724,12 +10079,14 @@ async function main() {
     case "search": // hep-search — 에이전트 디렉터리 발견 (Hub + 로컬)
       if (!rest[1]) return fail('usage: agentlas search "<찾는 일>" [--limit 10]');
       return parity().cloudSearch(db, rest.slice(1));
-    case "install": // hep-cloud import — slug로 에이전트 설치
+    case "install": // public Hub package install — slug로 에이전트 설치
       if (!rest[1]) return fail('usage: agentlas install <slug>   (먼저 agentlas search "할 일" 로 찾으세요)');
       return cmdCloudInstall(db, rest[1]);
-    case "upload": // hep-upload — 컴파일된 에이전트를 Hub로 배포 (경로 필요)
-      if (!rest[1]) return fail("usage: agentlas upload <에이전트 폴더 경로>   (패키징 후 Hub 배포)");
-      return cmdCloud(db, ["publish", ...rest.slice(1)], runtimeOverride);
+    case "upload": { // 기본은 owner-private Agent Cloud, public Hub는 명시 flag로만.
+      if (!rest[1]) return fail("usage: agentlas upload <에이전트 폴더 경로> [--visibility marketplace]");
+      const uploadArgs = rest.slice(1);
+      return cmdCloud(db, [cloudActionForTopLevelUpload(uploadArgs), ...uploadArgs], runtimeOverride);
+    }
     case "connect": // hep-connect — Telegram 등 플랫폼 연결
       return parity().cmdHep(db, ["hep-connect", ...rest.slice(1)]);
     case "browser": // hep-browser — 실제 브라우저 실행 하드포인트
@@ -7791,4 +10148,51 @@ async function main() {
   }
 }
 
-main().catch((e) => fail(String(e && e.stack ? e.stack : e)));
+// 런처가 스폰하는 실행 파일일 때만 CLI main을 돌린다. 회귀 테스트/라이브러리 require는 종료하지 않는다.
+if (require.main === module) {
+  main().catch((e) => fail(String(e && e.stack ? e.stack : e)));
+}
+
+module.exports = {
+  runApi,
+  normalizeCustomApiBaseUrl,
+  readCustomApiBaseUrl,
+  parseDotEnvCli,
+  isProtectedChildEnvKeyCli,
+  mergeChildEnvValuesCli,
+  resolveCredentialSourcePath,
+  upsertEnvLine,
+  fetchHubCli,
+  hubTimeoutConfig,
+  compareSemVer,
+  parseSemVer,
+  updateTimeoutConfig,
+  fetchUpdateMetadata,
+  validateDesktopUpdateArtifact,
+  downloadUpdateFile,
+  verifyMacAppBundle,
+  replaceMacAppBundle,
+  captureRuntime,
+  buildArgs,
+  captureOutputLimit,
+  materializeCloudListingCli,
+  recoverCloudInstallJournalCli,
+  recoverCloudInstallJournalsCli,
+  persistCloudListingCli,
+  cloudSystemPromptFromPackageCli,
+  agentSystemPromptCli,
+  listOwnedCloudAgentsCli,
+  restoreOwnedCloudAgentCli,
+  deleteCloudAgentCli,
+  readCloudAssetStateCli,
+  normalizeCloudAssetDescriptorCli,
+  packageCloudAgentCli,
+  cloudVisibilityForAction,
+  cloudActionForTopLevelUpload,
+  cloudHashPackage,
+  cloudPackageHashVersion,
+  cloudPortablePathConflict,
+  cloudPortableExecutableForFile,
+  DEFAULT_API_MODEL,
+  ANTHROPIC_COMPAT_API,
+};