agentlas 1.0.65 → 1.0.67

package/engine/commands/plugin.cjs

@@ -157,18 +157,29 @@ function parsePluginListFlags(args) {
     errors: [],
     positionals: [],
   };
+  const seen = new Set();
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--global") {
+      if (seen.has("global")) {
+        flags.errors.push("duplicate flag: --global");
+        return flags;
+      }
+      seen.add("global");
       flags.global = true;
       continue;
     }
     if (arg === "--project") {
+      if (seen.has("project")) {
+        flags.errors.push("duplicate flag: --project");
+        return flags;
+      }
       const next = args[i + 1];
       if (!next || next.startsWith("-")) {
         flags.errors.push("usage: agentlas plugin list --project <path>");
         return flags;
       }
+      seen.add("project");
       flags.project = next;
       i += 1;
       continue;
@@ -207,7 +218,7 @@ function run(ctx, args) {
   // SELF_HELP_COMMANDS 계약(index.cjs): `plugin --help` 는 여기로 ["help"] 가 되어
   // 들어온다. help 분기가 없으면 unknown action → usage exit 1 이라, 도움말을
   // 요청한 사용자가 오류 코드를 받는다.
-  if (action === "help" || action === "--help" || action === "-h") {
+  if ((action === "help" || action === "--help" || action === "-h") && args.length === 1) {
     const ko = ctx.lang !== "en";
     ctx.out(ko
       ? [
@@ -227,7 +238,7 @@ function run(ctx, args) {
     return 0;
   }
   if (action === "add") {
-    if (args.length !== 2) {
+    if (args.length !== 2 || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(String(args[1] || ""))) {
       ctx.err("usage: agentlas plugin add <slug>   (run agentlas plugin list first)");
       return 1;
     }

package/engine/commands/project.cjs

@@ -56,10 +56,21 @@ function run(ctx, args) {
   const action = String(args[0] || "status").toLowerCase();
   const cwd = projectCwd();
   const ko = ctx.lang === "ko";
+  const invalid = () => {
+    const error = new Error(ko
+      ? "사용법: agentlas project [status | init | use <에이전트> | team <에이전트>...]"
+      : "Usage: agentlas project [status | init | use <agent> | team <agent>...]");
+    error.code = "INVALID_ARGUMENT";
+    throw error;
+  };
 
-  if (action === "status") return showStatus(ctx, cwd, ko);
+  if (action === "status") {
+    if (args.length > 1) return invalid();
+    return showStatus(ctx, cwd, ko);
+  }
 
   if (action === "init") {
+    if (args.length !== 1) return invalid();
     ctx.out(ko
       ? "비공개 Agentlas 프로젝트 상태를 초기화합니다. .agentlas/ 생성, .gitignore 갱신, 로컬 자격증명·서명 템플릿 추가가 포함될 수 있습니다."
       : "Initializing private Agentlas project state. This may create .agentlas/, update .gitignore, and add local credential/signing templates.");
@@ -79,13 +90,8 @@ function run(ctx, args) {
    * 둘 다 데스크탑 없이 동작한다.
    */
   if (action === "use" || action === "team") {
-    const tokens = args.slice(1).filter((t) => t && !String(t).startsWith("-"));
-    if (!tokens.length) {
-      ctx.err(ko
-        ? `사용법: agentlas project ${action} <에이전트> ${action === "team" ? "[<에이전트>...]" : ""}  ·  에이전트 목록: agentlas list`
-        : `Usage: agentlas project ${action} <agent> ${action === "team" ? "[<agent>...]" : ""}  ·  list agents: agentlas list`);
-      return 1;
-    }
+    const tokens = args.slice(1);
+    if (!tokens.length || tokens.some((token) => !token || String(token).startsWith("-")) || (action === "use" && tokens.length !== 1)) return invalid();
     try {
       const result = connectProjectTeam(ctx.db(), cwd, tokens, {});
       reportTeam(ctx, result, ko);
@@ -101,10 +107,7 @@ function run(ctx, args) {
     }
   }
 
-  ctx.err(ko
-    ? "사용법: agentlas project [status | init | use <에이전트> | team <에이전트>...]"
-    : "Usage: agentlas project [status | init | use <agent> | team <agent>...]");
-  return 1;
+  return invalid();
 }
 
 module.exports = { run };

package/engine/commands/research.cjs

@@ -1,6 +1,6 @@
 "use strict";
 /*
- * research — Research Engine (status|gather|search|read|plan).
+ * research — Agentlas OS Research Engine.
  *
  * v1 디스패처 매핑 그대로:
  *   `agentlas research <sub…>` → cmdHep(["research", ...rest])
@@ -10,22 +10,33 @@
  * v1 가드 그대로:
  *   - help 토큰 → 로컬 usage가 아니라 Hephaestus 네이티브 help 패스스루
  *     (v1: parity().cmdHep(null, ["research", ...rest]) 특례).
- *   - 첫 인자가 status|gather|search|read|plan 밖 → usage 실패 exit 1
+ *   - 첫 인자가 현재 Agentlas OS Research 명령 밖 → usage 실패 exit 1
  *     (자연어가 리서치 서브커맨드 자리로 새는 것 방지; ko 문구 v1 그대로).
  */
 const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
 
-const RESEARCH_SUBCOMMANDS = ["status", "gather", "search", "read", "plan"];
+// Agentlas OS 1.2.37의 공개 `hephaestus research --help` 표면. Terminal이
+// 옛 다섯 개만 허용하면 설치된 Core의 진단·검증·하드포인트·loadout 명령이
+// 물리적으로 도달 불가능해진다. 알 수 없는 값은 계속 로컬에서 fail-closed 한다.
+const RESEARCH_SUBCOMMANDS = new Set([
+  "doctor", "status", "credentials", "social-fallbacks", "proofs", "verify",
+  "hardpoints", "modules", "armory", "profile", "recommend", "preflight",
+  "bridge-contract", "browser-candidates", "bridge-check", "platform-contract",
+  "platform-check", "loadouts", "plan", "read", "search", "gather",
+]);
 
 async function run(ctx, args) {
   const runtime = create(ctx);
   if (args.some(isHelpToken)) {
-    return runtime.cmdHep(["research", ...args]);
+    // The top-level router canonicalizes `<command> --help` to the command's
+    // `help` branch. argparse behind Agentlas OS expects `--help`, not a
+    // positional `help` research subcommand.
+    return runtime.cmdHep(["research", ...args.map((arg) => arg === "help" ? "--help" : arg)]);
   }
-  if (!RESEARCH_SUBCOMMANDS.includes(args[0])) {
+  if (!RESEARCH_SUBCOMMANDS.has(args[0])) {
     ctx.err(
       "✖ " + (ctx.lang === "ko"
-        ? "사용법: agentlas research <status|gather|search|read|plan> [인자]"
+        ? "사용법: agentlas research <하위-명령> [인자] (전체 목록: agentlas research --help)"
         : usageFor("research", ctx.lang)),
     );
     return 1;
@@ -33,4 +44,4 @@ async function run(ctx, args) {
   return runtime.cmdHep(["research", ...args]);
 }
 
-module.exports = { run };
+module.exports = { run, RESEARCH_SUBCOMMANDS };

package/engine/commands/roles.cjs

@@ -1,6 +1,6 @@
 "use strict";
 /*
- * roles — 오케스트레이터/워커 모델 역할 조회·설정.
+ * roles — 오케스트레이터/워커/멀티모달 모델 역할 조회·설정.
  *
  * 배경(2026-08-05 감사, 결함 C): `list`와 `doctor`는 model_roles를 보여주는데
  * 터미널 어디에도 쓰기 경로가 없었다(전 코드베이스 SELECT만). 바꾸려면 데스크탑을
@@ -18,7 +18,7 @@
 const { RUNTIME_BIN, whichSync } = require("../runtimes/detect.cjs");
 const { runtimeAuthEvidence } = require("../runtimes/auth-evidence.cjs");
 const { canonicalRuntimeKind, storedRuntimeKind } = require("../runtimes/kinds.cjs");
-const { MODEL_ROLE_TABLE, VALID_ROLES, resolvedModelRole, roleMembers } = require("../runtimes/roles.cjs");
+const { MODEL_ROLE_TABLE, MODEL_ROLE_MEMBER_TABLE, VALID_ROLES, resolvedModelRole, roleMembers } = require("../runtimes/roles.cjs");
 const { runWriteTransaction } = require("../agentlas-sqlite-policy.cjs");
 const { EFFORTS } = require("../agentlas-workload-routing.cjs");
 
@@ -43,12 +43,17 @@ function show(ctx, args = []) {
     ctx.out(JSON.stringify({
       orchestrator: resolvedModelRole(db, "orchestrator"),
       worker: resolvedModelRole(db, "worker"),
-      pools: { orchestrator: roleMembers(db, "orchestrator"), worker: roleMembers(db, "worker") },
+      multimodal: resolvedModelRole(db, "multimodal"),
+      pools: {
+        orchestrator: roleMembers(db, "orchestrator"),
+        worker: roleMembers(db, "worker"),
+        multimodal: roleMembers(db, "multimodal"),
+      },
     }, null, 2));
     return 0;
   }
   ctx.out(ctx.ui.bold(en ? "Model roles" : "모델 역할"));
-  for (const role of ["orchestrator", "worker"]) {
+  for (const role of VALID_ROLES) {
     const resolved = resolvedModelRole(db, role);
     ctx.out(`  ${role.padEnd(13)} ${fmt(resolved, en)}`);
     const pool = roleMembers(db, role);
@@ -58,21 +63,35 @@ function show(ctx, args = []) {
   }
   ctx.out("");
   ctx.out(ctx.ui.dim(en
-    ? 'Change: agentlas roles set <orchestrator|worker> <runtime> [--model <id>] [--effort <level>]  ·  worker inherit: agentlas roles set worker --inherit'
-    : '변경: agentlas roles set <orchestrator|worker> <runtime> [--model <id>] [--effort <level>]  ·  워커 상속: agentlas roles set worker --inherit'));
+    ? 'Change: agentlas roles set <orchestrator|worker|multimodal> <runtime> [--model <id>] [--effort <level>]  ·  worker inherit: agentlas roles set worker --inherit'
+    : '변경: agentlas roles set <orchestrator|worker|multimodal> <runtime> [--model <id>] [--effort <level>]  ·  워커 상속: agentlas roles set worker --inherit'));
   return 0;
 }
 
 function parseSetFlags(args) {
   const rest = [];
   const flags = {};
+  const seen = new Set();
+  const take = (name, raw) => {
+    if (seen.has(name)) throw new Error(`duplicate option: --${name}`);
+    const value = String(raw ?? "").trim();
+    if (!value || value.startsWith("--")) throw new Error(`missing value: --${name}`);
+    seen.add(name);
+    return value;
+  };
   for (let i = 0; i < args.length; i += 1) {
-    const arg = args[i];
-    if (arg === "--model") { flags.model = String(args[++i] ?? "").trim(); continue; }
-    if (arg.startsWith("--model=")) { flags.model = arg.slice(8).trim(); continue; }
-    if (arg === "--effort") { flags.effort = String(args[++i] ?? "").trim().toLowerCase(); continue; }
-    if (arg.startsWith("--effort=")) { flags.effort = arg.slice(9).trim().toLowerCase(); continue; }
-    if (arg === "--inherit") { flags.inherit = true; continue; }
+    const arg = String(args[i] ?? "");
+    if (arg === "--model") { flags.model = take("model", args[++i]); continue; }
+    if (arg.startsWith("--model=")) { flags.model = take("model", arg.slice(8)); continue; }
+    if (arg === "--effort") { flags.effort = take("effort", args[++i]).toLowerCase(); continue; }
+    if (arg.startsWith("--effort=")) { flags.effort = take("effort", arg.slice(9)).toLowerCase(); continue; }
+    if (arg === "--inherit") {
+      if (seen.has("inherit")) throw new Error("duplicate option: --inherit");
+      seen.add("inherit");
+      flags.inherit = true;
+      continue;
+    }
+    if (arg.startsWith("-")) throw new Error(`unknown option: ${arg}`);
     rest.push(arg);
   }
   return { rest, flags };
@@ -81,19 +100,33 @@ function parseSetFlags(args) {
 function set(ctx, args) {
   const en = ctx.lang === "ko" ? false : true;
   const ko = !en;
-  const { rest, flags } = parseSetFlags(args);
+  let parsed;
+  try {
+    parsed = parseSetFlags(args);
+  } catch (error) {
+    ctx.err(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+  const { rest, flags } = parsed;
   const role = String(rest[0] || "").toLowerCase();
   const kindArg = rest[1] ? String(rest[1]).toLowerCase() : null;
 
   const usage = ko
-    ? "사용법: agentlas roles set <orchestrator|worker> <runtime> [--model <id>] [--effort <level>] | agentlas roles set worker --inherit"
-    : "Usage: agentlas roles set <orchestrator|worker> <runtime> [--model <id>] [--effort <level>] | agentlas roles set worker --inherit";
+    ? "사용법: agentlas roles set <orchestrator|worker|multimodal> <runtime> [--model <id>] [--effort <level>] | agentlas roles set worker --inherit"
+    : "Usage: agentlas roles set <orchestrator|worker|multimodal> <runtime> [--model <id>] [--effort <level>] | agentlas roles set worker --inherit";
 
   if (!VALID_ROLES.has(role)) { ctx.err(usage); return 1; }
+  if (rest.length > 2) { ctx.err(usage); return 1; }
   if (flags.inherit && role !== "worker") {
     ctx.err(ko ? "--inherit 는 worker 역할에만 씁니다 (스키마 계약)." : "--inherit applies to the worker role only (schema contract).");
     return 1;
   }
+  if (flags.inherit && (kindArg || flags.model !== undefined || flags.effort !== undefined)) {
+    ctx.err(ko
+      ? "--inherit 는 runtime, --model, --effort 와 함께 쓸 수 없습니다. 오케스트레이터 설정 전체를 따릅니다."
+      : "--inherit cannot be combined with a runtime, --model, or --effort. It follows the complete orchestrator selection.");
+    return 1;
+  }
   if (!flags.inherit && !kindArg) { ctx.err(usage); return 1; }
   if (kindArg && !KNOWN_KINDS.has(kindArg)) {
     ctx.err((ko ? "모르는 런타임 종류: " : "unknown runtime kind: ") + kindArg);
@@ -119,6 +152,7 @@ function set(ctx, args) {
   let kind = kindArg;
   let model = flags.model !== undefined ? (flags.model || null) : undefined;
   let inherit = 0;
+  let inheritedSelection = null;
   if (flags.inherit) {
     // 상속 = 워커가 오케스트레이터를 따른다. 스키마상 kind NOT NULL이라
     // 현재 오케스트레이터의 좌표를 복사해 두되 inherit=1로 표시한다(리더 부재 시 정직 정지).
@@ -129,32 +163,72 @@ function set(ctx, args) {
     }
     kind = orchestrator.kind;
     if (model === undefined) model = orchestrator.model;
+    inheritedSelection = orchestrator;
     inherit = 1;
   }
 
   const now = new Date().toISOString();
   runWriteTransaction(db, () => {
     const existing = db.prepare("SELECT * FROM model_roles WHERE role=?").get(role);
+    const sameKind = existing && canonicalRuntimeKind(existing.kind) === kind;
+    const storedKind = storedRuntimeKind(kind);
+    // kind가 바뀌면 이전 모델/백엔드/출처는 새 런타임의 좌표가 아니다
+    // (예: kimi에 opus, codex에 google backend). 명시하지 않은 값은 지운다.
+    const savedModel = model === undefined ? (sameKind ? existing.model : null) : model;
+    const savedEffort = flags.effort === undefined
+      ? (inheritedSelection ? inheritedSelection.effort : existing?.effort) || null
+      : (flags.effort === "none" ? null : flags.effort);
+    const savedBackend = inheritedSelection
+      ? inheritedSelection.backend || null
+      : sameKind ? existing.backend || null : null;
+    const savedSource = inheritedSelection
+      ? inheritedSelection.source || null
+      : sameKind ? existing.source || null : null;
+    const savedLongContext = inheritedSelection
+      ? (inheritedSelection.longContext ? 1 : 0)
+      : sameKind && existing.long_context ? 1 : 0;
     if (existing) {
-      // kind가 바뀌면 이전 모델 id는 새 런타임의 어휘가 아니다(예: kimi에 opus).
-      // --model 미지정 시 유지가 아니라 초기화 — 무의미한 좌표를 승계하지 않는다.
-      const keepModel = canonicalRuntimeKind(existing.kind) === kind ? existing.model : null;
       db.prepare(
-        "UPDATE model_roles SET kind=?, model=?, effort=?, inherit=?, updated_at=? WHERE role=?",
+        `UPDATE model_roles
+         SET kind=?, backend=?, source=?, model=?, effort=?, long_context=?, inherit=?, updated_at=?
+         WHERE role=?`,
       ).run(
         // 공유 DB 는 데스크탑 어휘로 적는다(runtimes/kinds.cjs) — 여기서 이 저장소의
         // 이름을 그대로 넣으면 데스크탑이 그 역할을 못 읽는다.
-        storedRuntimeKind(kind),
-        model === undefined ? keepModel : model,
-        flags.effort === undefined ? existing.effort : (flags.effort === "none" ? null : flags.effort),
+        storedKind,
+        savedBackend,
+        savedSource,
+        savedModel,
+        savedEffort,
+        savedLongContext,
         inherit,
         now,
         role,
       );
     } else {
       db.prepare(
-        "INSERT INTO model_roles (role, kind, model, effort, inherit, updated_at) VALUES (?,?,?,?,?,?)",
-      ).run(role, storedRuntimeKind(kind), model === undefined ? null : model, flags.effort === undefined || flags.effort === "none" ? null : flags.effort, inherit, now);
+        `INSERT INTO model_roles
+         (role, kind, backend, source, model, effort, long_context, inherit, updated_at)
+         VALUES (?,?,?,?,?,?,?,?,?)`,
+      ).run(role, storedKind, savedBackend, savedSource, savedModel, savedEffort, savedLongContext, inherit, now);
+    }
+
+    // Desktop v80과 같은 단일 설정 계약: model_roles만 바꿔 실제 실행이
+    // 계속 옛 pool 1순위를 고르는 split-brain을 만들지 않는다.
+    if (ctx.tableExists(db, MODEL_ROLE_MEMBER_TABLE)) {
+      const hasMembers = Number(
+        db.prepare("SELECT COUNT(*) AS n FROM model_role_members WHERE role=?").get(role)?.n || 0,
+      ) > 0;
+      if (hasMembers && inherit) {
+        // 빈 worker 풀 자체가 orchestrator 풀 상속을 뜻한다.
+        db.prepare("DELETE FROM model_role_members WHERE role=?").run(role);
+      } else if (hasMembers) {
+        db.prepare(
+          `UPDATE model_role_members
+           SET kind=?, backend=?, source=?, model=?, effort=?, long_context=?, updated_at=?
+           WHERE role=? AND position=1`,
+        ).run(storedKind, savedBackend, savedSource, savedModel, savedEffort, savedLongContext, now, role);
+      }
     }
   });
 
@@ -188,18 +262,20 @@ function run(ctx, args = []) {
     // SELF_HELP_COMMANDS 계약: --help 는 스텁이 아니라 실제 안내여야 한다.
     ctx.out(en
       ? [
-        "agentlas roles — orchestrator/worker model roles (persisted, shared with Desktop)",
-        "  roles                                  show both roles and their pools",
+        "agentlas roles — orchestrator/worker/multimodal model roles (persisted, shared with Desktop)",
+        "  roles                                  show all three roles and their pools",
         "  roles set <orchestrator|worker> <runtime> [--model <id>] [--effort <level>]",
+        "  roles set multimodal <runtime> [--model <id>] [--effort <level>]",
         "  roles set worker --inherit             worker follows the orchestrator",
         "",
         `  runtimes: ${[...KNOWN_KINDS].join(" · ")}`,
         "  REPL /model and /runtime are session-scoped — this command is the persistent path.",
       ].join("\n")
       : [
-        "agentlas roles — 오케스트레이터/워커 모델 역할 (영구 저장, 데스크탑과 공유)",
-        "  roles                                  두 역할과 풀 조회",
+        "agentlas roles — 오케스트레이터/워커/멀티모달 모델 역할 (영구 저장, 데스크탑과 공유)",
+        "  roles                                  세 역할과 풀 조회",
         "  roles set <orchestrator|worker> <runtime> [--model <id>] [--effort <level>]",
+        "  roles set multimodal <runtime> [--model <id>] [--effort <level>]",
         "  roles set worker --inherit             워커가 오케스트레이터를 따름",
         "",
         `  런타임: ${[...KNOWN_KINDS].join(" · ")}`,

package/engine/commands/route.cjs

@@ -9,14 +9,14 @@
  *     넘기고, --json이면 human:false 원본 패스스루로 내려간다.
  *
  * v1 인자 가드 그대로:
- *   - help 토큰 → usage, exit 0
+ *   - 단독 help 토큰 → usage, exit 0
  *   - 인자가 없거나 --json뿐 → usage 실패 exit 1
  *     (빈 쿼리가 라우터로 새는 것 방지)
  */
 const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
 
 async function run(ctx, args) {
-  if (args.some(isHelpToken)) {
+  if (args.length === 1 && isHelpToken(args[0])) {
     ctx.out(usageFor("route", ctx.lang));
     return 0;
   }

package/engine/commands/run.cjs

@@ -7,6 +7,7 @@
  *   --effort <level>      none | minimal | low | medium | high | xhigh | max
  *   --tier <tier>         economy | balanced | frontier (requires --model)
  *   --permission <level>  read | write | full
+ *   --                     뒤의 토큰은 옵션처럼 보여도 프롬프트로 전달
  * 프롬프트가 없고 stdin이 TTY가 아니면 stdin을 읽는다.
  *
  * 첫 토큰이 정확한 에이전트이면 고급 직접 호출이다. 그 외 일반 실행은 현재 폴더에
@@ -48,21 +49,53 @@ function parseArgs(args) {
     permission: null,
     rest: [],
   };
+  const seen = new Set();
+  const valueFlags = new Map([
+    ["--runtime", "runtime"],
+    ["--model", "model"],
+    ["--effort", "effort"],
+    ["--tier", "tier"],
+    ["--permission", "permission"],
+  ]);
+  let passthrough = false;
   for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a === "-p" || a === "--print") out.print = true;
-    else if (a === "--runtime") out.runtime = args[++i];
-    else if (a === "--model") out.model = args[++i];
-    else if (a === "--effort") out.effort = args[++i];
-    else if (a === "--tier") out.tier = args[++i];
-    else if (a === "--permission") out.permission = args[++i];
-    else out.rest.push(a);
+    const a = String(args[i]);
+    if (passthrough) { out.rest.push(a); continue; }
+    if (a === "--") { passthrough = true; continue; }
+    if (a === "-p" || a === "--print") {
+      if (seen.has("print")) throw new Error("duplicate option: --print");
+      seen.add("print");
+      out.print = true;
+      continue;
+    }
+    const equalAt = a.indexOf("=");
+    const option = equalAt >= 0 ? a.slice(0, equalAt) : a;
+    const field = valueFlags.get(option);
+    if (field) {
+      if (seen.has(field)) throw new Error(`duplicate option: ${option}`);
+      seen.add(field);
+      const value = equalAt >= 0 ? a.slice(equalAt + 1) : args[++i];
+      if (value === undefined || value === "" || (equalAt < 0 && String(value).startsWith("--"))) {
+        throw new Error(`${option} requires a value`);
+      }
+      out[field] = String(value);
+      continue;
+    }
+    if (a.startsWith("-")) {
+      throw new Error(`unknown option: ${a} (use -- before a prompt that starts with '-')`);
+    }
+    out.rest.push(a);
   }
   return out;
 }
 
 async function runOnce(ctx, args) {
-  const parsed = parseArgs(args);
+  let parsed;
+  try { parsed = parseArgs(args); }
+  catch (error) {
+    ctx.err(String((error && error.message) || error));
+    return 1;
+  }
   // 플래그 검증은 모델을 부르기 전에. normalize는 알 수 없는 값을 read로 fail-closed
   // 강등하는데, 조용히 강등하면 full을 요청한 사용자가 read로 도는 걸 모른다.
   if (parsed.permission && !["read", "write", "full"].includes(String(parsed.permission))) {

package/engine/commands/search.cjs

@@ -15,9 +15,30 @@ function isInternalAgentSlug(slug) {
 async function run(ctx, args) {
   let limit = 10;
   const rest = [];
+  let seenLimit = false;
+  let passthrough = false;
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--limit") limit = Math.max(1, Math.min(30, Number(args[++i]) || 10));
-    else rest.push(args[i]);
+    const token = String(args[i]);
+    if (passthrough) { rest.push(token); continue; }
+    if (token === "--") { passthrough = true; continue; }
+    if (token === "--limit" || token.startsWith("--limit=")) {
+      if (seenLimit) { ctx.err("duplicate option: --limit"); return 1; }
+      seenLimit = true;
+      const inline = token.startsWith("--limit=");
+      const raw = inline ? token.slice(8) : args[++i];
+      const parsed = Number(raw);
+      if (raw === undefined || raw === "" || !Number.isInteger(parsed) || parsed < 1 || parsed > 30) {
+        ctx.err("--limit requires an integer from 1 to 30");
+        return 1;
+      }
+      limit = parsed;
+      continue;
+    }
+    if (token.startsWith("-")) {
+      ctx.err(`unknown option: ${token} (use -- before a query that starts with '-')`);
+      return 1;
+    }
+    rest.push(token);
   }
   const query = rest.join(" ").trim();
   if (!query) {

package/engine/commands/setup.cjs

@@ -26,7 +26,12 @@ async function runWizard(ctx, rl) {
   });
 }
 
-async function run(ctx) {
+async function run(ctx, args = []) {
+  if (args.length) {
+    const error = new Error("usage: agentlas setup");
+    error.code = "INVALID_ARGUMENT";
+    throw error;
+  }
   if (!process.stdin.isTTY) {
     // 비-TTY에서 마법사를 돌리면 EOF로 이벤트 루프가 비어 exit 0으로 "조용히 성공"
     // 하는 함정이 있다 — 정직하게 거부한다.

package/engine/commands/storm.cjs

@@ -38,20 +38,58 @@ function resolvePermission(ctx) {
 function splitRuntimeOverride(args) {
   const rest = [];
   let runtimeOverride = null;
+  let seen = false;
+  let passthrough = false;
   for (let i = 0; i < args.length; i += 1) {
-    if (args[i] === "--runtime" && args[i + 1]) {
-      runtimeOverride = String(args[++i]);
+    const token = String(args[i]);
+    if (passthrough) { rest.push(token); continue; }
+    if (token === "--") { passthrough = true; rest.push(token); continue; }
+    if (token === "--runtime" || token.startsWith("--runtime=")) {
+      if (seen) throw new Error("duplicate option: --runtime");
+      seen = true;
+      const inline = token.startsWith("--runtime=");
+      const value = inline ? token.slice(10) : args[++i];
+      if (value === undefined || value === "" || (!inline && String(value).startsWith("--"))) {
+        throw new Error("--runtime requires a value");
+      }
+      runtimeOverride = String(value);
       continue;
     }
-    rest.push(args[i]);
+    rest.push(token);
   }
   return { rest, runtimeOverride };
 }
 
+function validateStormArgs(args) {
+  const seen = new Set();
+  let passthrough = false;
+  let hasGoal = false;
+  for (const raw of args) {
+    const token = String(raw);
+    if (passthrough) { hasGoal = true; continue; }
+    if (token === "--") { passthrough = true; continue; }
+    if (token === "--research" || token === "--research-evidence") {
+      if (seen.has("research")) return { error: "duplicate option: --research", hasGoal };
+      seen.add("research");
+    } else if (token === "--background") {
+      if (seen.has("background")) return { error: "duplicate option: --background", hasGoal };
+      seen.add("background");
+    } else if (token.startsWith("-")) {
+      return { error: `unknown option: ${token} (use -- before a goal token that starts with '-')`, hasGoal };
+    } else hasGoal = true;
+  }
+  return { error: null, hasGoal };
+}
+
 async function run(ctx, args) {
-  const { rest, runtimeOverride } = splitRuntimeOverride(args);
+  let parsed;
+  try { parsed = splitRuntimeOverride(args); }
+  catch (error) { ctx.err(String((error && error.message) || error)); return 1; }
+  const { rest, runtimeOverride } = parsed;
+  const validation = validateStormArgs(rest);
+  if (validation.error) { ctx.err(validation.error); return 1; }
   // usage 경로(목표 텍스트 없음)는 SQLite를 열 이유가 없다.
-  if (!rest.some((token) => !["--research", "--research-evidence", "--background"].includes(String(token)))) {
+  if (!validation.hasGoal) {
     ctx.err("usage: agentlas storm <goal>  [--research] [--background] [--runtime <kind>]");
     return 1;
   }
@@ -68,4 +106,4 @@ async function run(ctx, args) {
   return r && r.ok ? 0 : 1;
 }
 
-module.exports = { run, splitRuntimeOverride };
+module.exports = { run, splitRuntimeOverride, validateStormArgs };