agentlas 1.0.64 → 1.0.66

package/engine/cloud/auth.cjs

@@ -23,6 +23,95 @@ const { userDataDir } = require("../core/paths.cjs");
 const LOGIN_CALLBACK_PATH = "/callback";
 const LOGIN_TIMEOUT_MS = 180_000;
 const MAX_LOGIN_SESSION_BYTES = 16 * 1024;
+const MAX_LOGIN_SESSION_FILE_BYTES = MAX_LOGIN_SESSION_BYTES * 2;
+const O_NOFOLLOW = fs.constants.O_NOFOLLOW || 0;
+
+function sameFileIdentity(left, right) {
+  return !!left && !!right
+    && left.dev === right.dev
+    && left.ino === right.ino
+    && left.nlink === right.nlink;
+}
+
+function sameDirectoryIdentity(info) {
+  try {
+    const current = fs.lstatSync(info.path);
+    return current.isDirectory()
+      && !current.isSymbolicLink()
+      && current.dev === info.stat.dev
+      && current.ino === info.stat.ino;
+  } catch {
+    return false;
+  }
+}
+
+function ensureRealDirectory(directory, { create = false } = {}) {
+  const resolved = path.resolve(String(directory || ""));
+  if (create) fs.mkdirSync(resolved, { recursive: true, mode: 0o700 });
+  const stat = fs.lstatSync(resolved);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error("Refusing to use a symbolic-link Agentlas session directory.");
+  }
+  return { path: resolved, stat, realpath: fs.realpathSync.native(resolved) };
+}
+
+function ensureAuthDirectory({ create = false } = {}) {
+  const root = ensureRealDirectory(userDataDir(), { create });
+  const info = ensureRealDirectory(path.join(root.path, "auth"), { create });
+  // The auth directory must be a child of the configured user-data directory,
+  // not a mounted/symlinked redirect that merely passes the final lstat.
+  if (path.dirname(info.realpath) !== root.realpath) {
+    throw new Error("Refusing to use a redirected Agentlas session directory.");
+  }
+  return info;
+}
+
+function readBoundedFd(fd, maxBytes) {
+  const chunks = [];
+  let total = 0;
+  while (total <= maxBytes) {
+    const want = Math.min(8192, maxBytes - total + 1);
+    const buffer = Buffer.allocUnsafe(want);
+    const count = fs.readSync(fd, buffer, 0, want, null);
+    if (!count) break;
+    total += count;
+    if (total > maxBytes) return null;
+    chunks.push(buffer.subarray(0, count));
+  }
+  return Buffer.concat(chunks, total);
+}
+
+function readPrivateBoundedFile(filePath, maxBytes) {
+  let before;
+  let fd = null;
+  try {
+    before = fs.lstatSync(filePath);
+    if (before.isSymbolicLink() || !before.isFile() || before.nlink !== 1 || before.size > maxBytes) return null;
+    fd = fs.openSync(filePath, fs.constants.O_RDONLY | O_NOFOLLOW);
+    const opened = fs.fstatSync(fd);
+    if (!opened.isFile() || opened.nlink !== 1
+      || opened.size > maxBytes || !sameFileIdentity(before, opened)) return null;
+    const contents = readBoundedFd(fd, maxBytes);
+    const after = fs.fstatSync(fd);
+    if (
+      contents === null || !after.isFile() || after.nlink !== 1 || !sameFileIdentity(opened, after) ||
+      after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs ||
+      after.size !== contents.length
+    ) return null;
+    return contents.toString("utf8");
+  } catch {
+    return null;
+  } finally {
+    if (fd !== null) {
+      try { fs.closeSync(fd); } catch { /* ignore */ }
+    }
+  }
+}
+
+function writeAll(fd, buffer) {
+  let offset = 0;
+  while (offset < buffer.length) offset += fs.writeSync(fd, buffer, offset, buffer.length - offset);
+}
 
 function validLoginSessionValue(value) {
   return typeof value === "string" && value.length > 0 &&
@@ -230,9 +319,11 @@ function cliSessionPath() {
 function readCliSessionValue() {
   try {
     const p = cliSessionPath();
-    const stat = fs.lstatSync(p);
-    if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_LOGIN_SESSION_BYTES * 2) return null;
-    const j = JSON.parse(fs.readFileSync(p, "utf8"));
+    const authDir = ensureAuthDirectory();
+    const raw = readPrivateBoundedFile(p, MAX_LOGIN_SESSION_FILE_BYTES);
+    if (raw === null) return null;
+    if (!sameDirectoryIdentity(authDir)) return null;
+    const j = JSON.parse(raw);
     return j && validLoginSessionValue(j.value) ? j.value : null;
   } catch {
     return null;
@@ -243,29 +334,56 @@ function saveCliSession(value) {
   if (!validLoginSessionValue(value)) throw new Error("Refusing to save an invalid Agentlas login session value.");
   const p = cliSessionPath();
   // 디렉터리 0700 + 파일 0600 — 기본 umask(0644)로 세션이 world-readable 이 되는 것을 막는다.
-  const dir = path.dirname(p);
-  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const authDir = ensureAuthDirectory({ create: true });
+  const dir = authDir.path;
   try { fs.chmodSync(dir, 0o700); } catch { /* win32 */ }
   const temp = path.join(dir, `.cli-session.${process.pid}.${crypto.randomUUID()}.tmp`);
+  const payload = Buffer.from(JSON.stringify({ version: 1, value, updatedAt: new Date().toISOString() }, null, 2) + "\n", "utf8");
+  if (payload.length > MAX_LOGIN_SESSION_FILE_BYTES) throw new Error("Refusing to save an oversized Agentlas login session.");
+  let fd = null;
   try {
-    fs.writeFileSync(temp, JSON.stringify({ version: 1, value, updatedAt: new Date().toISOString() }, null, 2) + "\n", {
-      encoding: "utf8",
-      mode: 0o600,
-      flag: "wx",
-    });
+    fd = fs.openSync(temp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, 0o600);
+    const created = fs.fstatSync(fd);
+    if (!created.isFile() || created.nlink !== 1) throw new Error("Refusing to create an unsafe Agentlas login session file.");
+    writeAll(fd, payload);
+    fs.fsyncSync(fd);
+    const written = fs.fstatSync(fd);
+    if (!sameFileIdentity(created, written) || written.size !== payload.length) throw new Error("Agentlas login session changed while saving.");
+    fs.closeSync(fd);
+    fd = null;
+    if (!sameDirectoryIdentity(authDir)) throw new Error("Agentlas login session directory changed while saving.");
     fs.renameSync(temp, p);
+    const installed = fs.lstatSync(p);
+    if (installed.isSymbolicLink() || !installed.isFile() || installed.nlink !== 1) throw new Error("Refusing to install an unsafe Agentlas login session file.");
   } catch (error) {
+    if (fd !== null) {
+      try { fs.closeSync(fd); } catch { /* preserve original */ }
+    }
     try { fs.rmSync(temp, { force: true }); } catch { /* preserve original */ }
     throw error;
   }
-  try { fs.chmodSync(p, 0o600); } catch { /* win32 */ }
   return p;
 }
 
 function deleteCliSession() {
   const p = cliSessionPath();
-  if (!fs.existsSync(p)) return { existed: false, path: p };
-  fs.rmSync(p);
+  let authDir;
+  try { authDir = ensureAuthDirectory(); } catch (error) {
+    if (error?.code === "ENOENT") return { existed: false, path: p };
+    throw error;
+  }
+  let stat;
+  try { stat = fs.lstatSync(p); } catch (error) {
+    if (error?.code === "ENOENT") return { existed: false, path: p };
+    throw error;
+  }
+  if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1) {
+    throw new Error("Refusing to delete an unsafe Agentlas login session file.");
+  }
+  if (!sameDirectoryIdentity(authDir)) throw new Error("Agentlas login session directory changed while deleting.");
+  const current = fs.lstatSync(p);
+  if (!sameFileIdentity(stat, current)) throw new Error("Agentlas login session changed while deleting.");
+  fs.unlinkSync(p);
   return { existed: true, path: p };
 }
 

package/engine/cloud/hub-client.cjs

@@ -8,9 +8,9 @@
  *  - 업스트림 AbortSignal 전파
  * 세션 쿠키 해석 순서: AGENTLAS_SESSION env → auth/cli-session.v1.json → (레거시) keytar.
  */
-const fs = require("node:fs");
 const path = require("node:path");
 const { userDataDir } = require("../core/paths.cjs");
+const { readJsonFile } = require("../mcp/contract.cjs");
 
 const HUB_RESPONSE_MAX_BYTES = 16 * 1024 * 1024;
 const HUB_TIMEOUT_DEFAULTS = Object.freeze({ connectMs: 15_000, idleMs: 30_000, totalMs: 180_000 });
@@ -69,6 +69,7 @@ async function fetchHub(url, init = {}, options = {}) {
   let idleTimer = null;
   let totalTimer = null;
   let reader = null;
+  let iterator = null;
   let terminalError = null;
   let rejectTerminal;
   const terminal = new Promise((_, reject) => { rejectTerminal = reject; });
@@ -106,27 +107,46 @@ async function fetchHub(url, init = {}, options = {}) {
     const chunks = [];
     let bytes = 0;
     armIdle();
+    const acceptChunk = (value) => {
+      armIdle();
+      const chunk = Buffer.from(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);
+    };
     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);
+        acceptChunk(part.value);
       }
+    } else if (response.body && typeof response.body[Symbol.asyncIterator] === "function") {
+      iterator = response.body[Symbol.asyncIterator]();
+      while (true) {
+        // Node streams and test adapters can expose only an async iterator. A
+        // plain `for await` leaves us stuck inside next() after idle/total expiry,
+        // even though the request's AbortController has already fired.
+        const part = await Promise.race([
+          Promise.resolve().then(() => iterator.next()),
+          terminal,
+        ]);
+        if (part.done) break;
+        acceptChunk(part.value);
+      }
+    } else if (response.body == null) {
+      // Standards-compliant empty/HEAD/204 response. There is no body to read.
     } else {
-      const raw = Buffer.from(await Promise.race([response.arrayBuffer(), terminal]));
-      bytes = raw.length;
-      if (bytes > HUB_RESPONSE_MAX_BYTES) throw new Error(`Hub response exceeds the allowed size (${HUB_RESPONSE_MAX_BYTES} bytes).`);
-      chunks.push(raw);
+      // arrayBuffer()/text() allocates the complete attacker-controlled body
+      // before a size check can run, defeating the 16 MiB contract.
+      const error = new Error("Hub response body is not stream-readable; refusing an unbounded buffered read.");
+      error.code = "AGENTLAS_HUB_RESPONSE_NOT_STREAMABLE";
+      throw error;
     }
     if (idleTimer) clearTimeout(idleTimer);
     idleTimer = null;
@@ -143,6 +163,11 @@ async function fetchHub(url, init = {}, options = {}) {
     if (reader && terminalError) {
       try { await reader.cancel(terminalError); } catch { /* ignore */ }
     }
+    if (iterator && terminalError && typeof iterator.return === "function") {
+      // Do not await an untrusted iterator's cleanup hook: the timeout must
+      // remain a hard upper bound even when return() itself never settles.
+      Promise.resolve().then(() => iterator.return()).catch(() => {});
+    }
   }
 }
 
@@ -161,7 +186,7 @@ function cliSessionPath() {
 
 function readCliSessionValue() {
   try {
-    const j = JSON.parse(fs.readFileSync(cliSessionPath(), "utf8"));
+    const { value: j } = readJsonFile(cliSessionPath(), "Agentlas CLI session");
     return (j && typeof j.value === "string" && j.value) || null;
   } catch {
     return null;

package/engine/cloud-assets/cas.cjs

@@ -224,18 +224,27 @@ async function deleteCloudAgent(slug, options = {}) {
   ) {
     throw new Error("Agentlas Cloud delete returned an invalid or mismatched deletion receipt.");
   }
-  const stateValue = state.readCloudAssetState();
   const key = state.cloudDescriptorKey(descriptor);
-  const roots = stateValue.assets[key]?.sourceRoots || [];
+  // The server delete used this exact observed descriptor. Keep its roots even
+  // if another local process advances the same key before the local journal
+  // update; tombstones authenticate the deleted revision, not a later one.
+  const roots = [...(localEntry.sourceRoots || [])];
   const warnings = [];
-  for (const rootPath of roots) {
-    // 톰스톤: 삭제된 베이스는 재저장 시 절대 If-Match 베이스로 재사용되지 않는다.
-    stateValue.deletedBases.push({ rootPath, slug: descriptor.slug, scope: descriptor.scope, cloudId: descriptor.cloudId, revision: descriptor.revision });
-  }
-  delete stateValue.assets[key];
-  stateValue.deletedBases = stateValue.deletedBases.slice(-256);
   try {
-    state.writeCloudAssetState(stateValue);
+    state.updateCloudAssetState((stateValue) => {
+      for (const rootPath of roots) {
+        // 톰스톤: 삭제된 베이스는 재저장 시 절대 If-Match 베이스로 재사용되지 않는다.
+        stateValue.deletedBases.push({ rootPath, slug: descriptor.slug, scope: descriptor.scope, cloudId: descriptor.cloudId, revision: descriptor.revision });
+      }
+      const current = stateValue.assets[key];
+      if (
+        current && current.descriptor.cloudId === descriptor.cloudId &&
+        current.descriptor.revision === descriptor.revision
+      ) {
+        delete stateValue.assets[key];
+      }
+      stateValue.deletedBases = stateValue.deletedBases.slice(-256);
+    });
   } catch (error) {
     const stateError = new Error(
       `Cloud delete committed on the server, but this machine could not persist the deletion tombstone. ` +

package/engine/cloud-assets/commands.cjs

@@ -166,30 +166,80 @@ function writePurposeRepairCopy(root, projection) {
   return tempRoot;
 }
 
-function parseCloudFlags(args) {
+const CLOUD_VALUE_FLAGS = ["limit", "name", "purpose", "scope", "slug", "visibility"];
+const CLOUD_BOOLEAN_FLAGS = ["dry-run", "json", "llm-review", "overwrite", "strict"];
+
+function cloudArgumentError(message) {
+  const error = new Error(message);
+  error.code = "INVALID_ARGUMENT";
+  return error;
+}
+
+function parseCloudFlags(args, spec = {}) {
+  const values = new Set(spec.values || CLOUD_VALUE_FLAGS);
+  const booleans = new Set(spec.booleans || CLOUD_BOOLEAN_FLAGS);
   const flags = { _: [] };
+  const seen = new Set();
+  let positionalOnly = false;
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
-    if (a && a.startsWith("--")) {
-      const key = a.slice(2);
-      const next = args[i + 1];
-      if (next !== undefined && !String(next).startsWith("--")) {
-        flags[key] = next;
-        i++;
-      } else {
-        flags[key] = true;
-      }
-    } else {
+    if (positionalOnly) {
       flags._.push(a);
+      continue;
     }
+    if (a === "--") {
+      positionalOnly = true;
+      continue;
+    }
+    if (!String(a).startsWith("-")) {
+      flags._.push(a);
+      continue;
+    }
+    if (!String(a).startsWith("--")) throw cloudArgumentError(`unknown option: ${a}`);
+    const equal = String(a).indexOf("=");
+    const key = String(a).slice(2, equal === -1 ? undefined : equal);
+    if (!key || (!values.has(key) && !booleans.has(key))) throw cloudArgumentError(`unknown option: --${key || ""}`);
+    if (seen.has(key)) throw cloudArgumentError(`duplicate option: --${key}`);
+    seen.add(key);
+    if (booleans.has(key)) {
+      if (equal !== -1) throw cloudArgumentError(`--${key} does not take a value`);
+      flags[key] = true;
+      continue;
+    }
+    let value;
+    if (equal !== -1) {
+      value = String(a).slice(equal + 1);
+    } else {
+      const next = args[i + 1];
+      if (next === undefined || String(next).startsWith("--")) throw cloudArgumentError(`--${key} requires a value`);
+      value = String(next);
+      i++;
+    }
+    if (!value) throw cloudArgumentError(`--${key} requires a non-empty value`);
+    flags[key] = value;
   }
   return flags;
 }
 
+function requireCloudPositionals(flags, min, max, usage) {
+  if (flags._.length < min || flags._.length > max) throw cloudArgumentError(usage);
+  return flags;
+}
+
+function positiveIntegerFlag(value, fallback, name, max) {
+  if (value == null) return fallback;
+  if (!/^\d+$/.test(String(value))) throw cloudArgumentError(`--${name} must be a positive integer`);
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > max) {
+    throw cloudArgumentError(`--${name} must be between 1 and ${max}`);
+  }
+  return parsed;
+}
+
 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");
+  throw cloudArgumentError("--visibility must be private-link or marketplace");
 }
 
 function cloudVisibilityForAction(sub, flags) {
@@ -213,7 +263,10 @@ function cloudVisibilityForAction(sub, flags) {
 
 /** 최상위 `upload`의 실제 동작 결정: 기본 save, 명시적 marketplace만 publish. */
 function cloudActionForTopLevelUpload(args) {
-  const flags = parseCloudFlags(args);
+  const flags = requireCloudPositionals(parseCloudFlags(args, {
+    values: ["purpose", "slug", "visibility"],
+    booleans: ["dry-run", "json", "llm-review", "overwrite"],
+  }), 1, 1, "usage: agentlas upload <path> [--visibility marketplace]");
   return cloudVisibilityFlag(flags.visibility) === "marketplace" ? "publish" : "save";
 }
 
@@ -269,17 +322,20 @@ const CLOUD_HELP = [
 async function runCloud(ctx, args) {
   const sub = args[0] || "help";
   if (sub === "help" || sub === "--help" || sub === "-h") {
+    requireCloudPositionals(parseCloudFlags(args.slice(1), { values: [], booleans: ["json"] }), 0, 0, "usage: agentlas cloud help");
     ctx.out(CLOUD_HELP);
     return 0;
   }
   if (sub === "search") {
-    const flags = parseCloudFlags(args.slice(1));
+    const flags = requireCloudPositionals(parseCloudFlags(args.slice(1), {
+      values: ["limit"], booleans: ["json"],
+    }), 1, Number.MAX_SAFE_INTEGER, 'usage: agentlas cloud search "<what you need>" [--limit 10]');
     const query = flags._.join(" ").trim();
     if (!query) {
       ctx.err('usage: agentlas cloud search "<what you need>" [--limit 10]');
       return 1;
     }
-    const limit = Math.max(1, Math.min(30, Number(flags.limit) || 10));
+    const limit = positiveIntegerFlag(flags.limit, 10, "limit", 30);
     let result;
     try {
       result = await callHubTool("marketplace.search_agents", { q: query, limit });
@@ -287,6 +343,7 @@ async function runCloud(ctx, args) {
       ctx.err(e instanceof HubError ? e.message : `Marketplace connection failed: ${(e && e.message) || e}`);
       return 1;
     }
+    if (flags.json) { ctx.out(JSON.stringify(result, null, 2)); return 0; }
     const items = (result && (result.results || result.agents || result.items)) || [];
     if (!Array.isArray(items) || !items.length) {
       ctx.out(`No results for "${query}"`);
@@ -298,8 +355,10 @@ async function runCloud(ctx, args) {
     return 0;
   }
   if (sub === "list") {
-    const flags = parseCloudFlags(args.slice(1));
-    const result = await listOwnedCloudAgents(Number(flags.limit || 100));
+    const flags = requireCloudPositionals(parseCloudFlags(args.slice(1), {
+      values: ["limit"], booleans: ["json"],
+    }), 0, 0, "usage: agentlas cloud list [--limit 100] [--json]");
+    const result = await listOwnedCloudAgents(positiveIntegerFlag(flags.limit, 100, "limit", 1000));
     if (flags.json) { ctx.out(JSON.stringify(result, null, 2)); return 0; }
     const agents = Array.isArray(result.results) ? result.results : [];
     if (!agents.length) { ctx.out("No agents are stored in Private Agent Cloud."); return 0; }
@@ -332,7 +391,9 @@ async function runCloud(ctx, args) {
     return 0;
   }
   if (sub === "restore") {
-    const flags = parseCloudFlags(args.slice(1));
+    const flags = requireCloudPositionals(parseCloudFlags(args.slice(1), {
+      values: [], booleans: ["json"],
+    }), 1, 1, "usage: agentlas cloud restore <slug> [--json]");
     const slug = flags._[0];
     if (!slug) { ctx.err("usage: agentlas cloud restore <slug> [--json]"); return 1; }
     const result = await restoreOwnedCloudAgent(ctx.db(), slug);
@@ -344,7 +405,9 @@ async function runCloud(ctx, args) {
     return 0;
   }
   if (sub === "delete" || sub === "unpublish") {
-    const flags = parseCloudFlags(args.slice(1));
+    const flags = requireCloudPositionals(parseCloudFlags(args.slice(1), {
+      values: ["scope"], booleans: ["json"],
+    }), 1, 1, `usage: agentlas cloud ${sub} <slug> [--scope owner-private|hub-public] [--json]`);
     const slug = flags._[0];
     if (!slug) { ctx.err(`usage: agentlas cloud ${sub} <slug> [--json]`); return 1; }
     const result = await deleteCloudAgent(slug, { scope: flags.scope });
@@ -356,7 +419,9 @@ async function runCloud(ctx, args) {
   }
   // ── agentlas-cloud-runtime 소비 지점 (스캔/매니페스트/lazy-read/필드테스트) ──
   if (sub === "wizard") {
-    const flags = parseCloudFlags(args.slice(1));
+    const flags = requireCloudPositionals(parseCloudFlags(args.slice(1), {
+      values: ["name"], booleans: ["json"],
+    }), 1, 1, "usage: agentlas cloud wizard <path> [--name name] [--json]");
     const root = flags._[0];
     if (!root) { ctx.err("usage: agentlas cloud wizard <path> [--name name]"); return 1; }
     const result = cloudRuntime.runWizard(root, { name: typeof flags.name === "string" ? flags.name : undefined });
@@ -365,7 +430,9 @@ async function runCloud(ctx, args) {
   }
   if (sub === "security") {
     if (args[1] !== "scan") { ctx.err("usage: agentlas cloud security scan <path> [--strict]"); return 1; }
-    const flags = parseCloudFlags(args.slice(2));
+    const flags = requireCloudPositionals(parseCloudFlags(args.slice(2), {
+      values: [], booleans: ["json", "strict"],
+    }), 1, 1, "usage: agentlas cloud security scan <path> [--strict]");
     const root = flags._[0];
     if (!root) { ctx.err("usage: agentlas cloud security scan <path> [--strict]"); return 1; }
     const report = cloudRuntime.scanFolder(root);
@@ -375,15 +442,18 @@ async function runCloud(ctx, args) {
   if (sub === "runtime") {
     const action = args[1];
     if (action === "bundle") {
-      const root = args[2];
-      if (!root) { ctx.err("usage: agentlas cloud runtime bundle <path>"); return 1; }
+      const flags = requireCloudPositionals(parseCloudFlags(args.slice(2), {
+        values: [], booleans: ["json"],
+      }), 1, 1, "usage: agentlas cloud runtime bundle <path> [--json]");
+      const root = flags._[0];
       ctx.out(JSON.stringify(cloudRuntime.compileBundle(root), null, 2));
       return 0;
     }
     if (action === "read-agent-file") {
-      const root = args[2];
-      const targetPath = args[3];
-      if (!root || !targetPath) { ctx.err("usage: agentlas cloud runtime read-agent-file <path> <file>"); return 1; }
+      const flags = requireCloudPositionals(parseCloudFlags(args.slice(2), {
+        values: [], booleans: ["json"],
+      }), 2, 2, "usage: agentlas cloud runtime read-agent-file <path> <file> [--json]");
+      const [root, targetPath] = flags._;
       ctx.out(JSON.stringify(cloudRuntime.readAgentFile(root, targetPath), null, 2));
       return 0;
     }
@@ -391,15 +461,20 @@ async function runCloud(ctx, args) {
     return 1;
   }
   if (sub === "field-test") {
-    const flags = parseCloudFlags(args.slice(1));
+    const flags = requireCloudPositionals(parseCloudFlags(args.slice(1), {
+      values: [], booleans: ["json"],
+    }), 0, 0, "usage: agentlas cloud field-test [--json]");
     const result = cloudRuntime.runFieldTest();
     ctx.out(flags.json ? JSON.stringify(result, null, 2) : `${result.suite}: ${result.status}`);
     return result.status === "PASS" ? 0 : 1;
   }
   if (sub === "install") {
-    const slug = args[1];
-    if (!slug) { ctx.err("usage: agentlas cloud install <slug>"); return 1; }
+    const flags = requireCloudPositionals(parseCloudFlags(args.slice(1), {
+      values: [], booleans: ["json"],
+    }), 1, 1, "usage: agentlas cloud install <slug> [--json]");
+    const slug = flags._[0];
     const agent = await installHubAgent(ctx.db(), slug);
+    if (flags.json) { ctx.out(JSON.stringify(agent, null, 2)); return 0; }
     ctx.out(`${ctx.ui.green("✓")} Hub installed ${agent.slug} — ${agent.name}`);
     if (agent.localPath) ctx.out(`  files: ${agent.localPath}`);
     return 0;
@@ -408,7 +483,10 @@ async function runCloud(ctx, args) {
     ctx.err("usage: agentlas cloud <save|publish|package|list|restore|install|delete|field-test> ...");
     return 1;
   }
-  const flags = parseCloudFlags(args.slice(1));
+  const flags = requireCloudPositionals(parseCloudFlags(args.slice(1), {
+    values: ["purpose", "slug", "visibility"],
+    booleans: ["dry-run", "json", "llm-review", "overwrite"],
+  }), 1, 1, `usage: agentlas cloud ${sub} <path>`);
   const root = flags._[0];
   if (!root) { ctx.err(`usage: agentlas cloud ${sub} <path>`); return 1; }
   const visibility = cloudVisibilityForAction(sub, flags);