agentlas 1.0.65 → 1.0.66

package/engine/commands/list.cjs

@@ -7,6 +7,10 @@
 const { activeRuntimeRow, listAvailableCliRuntimes } = require("../runtimes/detect.cjs");
 const { resolvedModelRole } = require("../runtimes/roles.cjs");
 const { listAgents } = require("../agents/registry.cjs");
+const { render, single } = require("../cli-output.cjs");
+
+const LIST_OUTPUT_SCHEMA = Object.freeze({ idField: "slug", columns: [] });
+const LIST_OUTPUT_FLAGS = new Set(["--json", "--yaml", "--quiet", "-q", "--no-headers", "--no-color"]);
 
 function roleRuntimeLabel(selection, role, en) {
   if (!selection) return en ? "(not set)" : "(미설정)";
@@ -25,6 +29,12 @@ function roleRuntimeLabel(selection, role, en) {
 }
 
 function run(ctx, args = []) {
+  const invalidArgs = args.filter((arg) => !LIST_OUTPUT_FLAGS.has(arg));
+  if (invalidArgs.length) {
+    const error = new Error(`Usage: agentlas list [--json|--yaml|--quiet|--no-headers|--no-color]. Unknown argument: ${invalidArgs[0]}`);
+    error.code = "INVALID_ARGUMENT";
+    throw error;
+  }
   const db = ctx.db();
   // 프라이버시 정책(웹 전용/백그라운드 제외)은 registry가 소유한다 — 직접 SQL 금지.
   const agents = listAgents(db).map((a) => ({
@@ -33,18 +43,40 @@ function run(ctx, args = []) {
   const firms = ctx.tableExists(db, "firms")
     ? db.prepare("SELECT id, slug, name FROM firms ORDER BY name").all()
     : [];
+  const output = ctx.output || {};
+  let format = output.format || "table";
+  for (const arg of args) {
+    if (arg === "--json") format = "json";
+    if (arg === "--yaml") format = "yaml";
+  }
+  const quiet = Boolean(output.quiet) || args.includes("--quiet") || args.includes("-q");
+  const noHeaders = Boolean(output.noHeaders) || args.includes("--no-headers");
+  const noColor = Boolean(output.noColor) || args.includes("--no-color");
+  const payload = () => ({
+    agents,
+    firms,
+    modelRoles: {
+      orchestrator: resolvedModelRole(db, "orchestrator"),
+      worker: resolvedModelRole(db, "worker"),
+      multimodal: resolvedModelRole(db, "multimodal"),
+    },
+  });
 
-  // clig.dev: 스크립트 소비자는 사람용 표를 파싱하게 두지 말 것 — --json 은
-  // 사람용 출력과 같은 사실을 기계 계약으로 준다.
-  if (ctx.output?.format === "json" || args.includes("--json")) {
-    const orchestrator = resolvedModelRole(db, "orchestrator");
-    const worker = resolvedModelRole(db, "worker");
-    ctx.out(JSON.stringify({ agents, firms, modelRoles: { orchestrator, worker } }, null, 2));
+  // clig.dev: 스크립트 소비자는 사람용 표를 파싱하게 두지 말 것 — 공통 출력
+  // renderer가 quiet 우선과 JSON/YAML 형식을 한 곳에서 해석한다.
+  if (quiet) {
+    const ids = agents.map((agent) => agent.slug).concat(firms.map((firm) => firm.slug || firm.id));
+    if (ids.length) ctx.out(ids.join("\n"));
+    return 0;
+  }
+  if (format === "json" || format === "yaml") {
+    ctx.out(render(single(payload(), LIST_OUTPUT_SCHEMA), { ...output, format, quiet: false }));
     return 0;
   }
 
   const en = ctx.lang === "en";
-  ctx.out(ctx.ui.bold(en ? "Installed agents" : "설치된 에이전트"));
+  const paint = (name, value) => noColor ? String(value) : ctx.ui[name](value);
+  if (!noHeaders) ctx.out(paint("bold", en ? "Installed agents" : "설치된 에이전트"));
   if (!agents.length) {
     ctx.out("  " + (en ? "(none yet — try: agentlas search \"what you need\")" : "  (아직 없음 — agentlas search \"필요한 것\" 으로 찾아보세요)"));
   }
@@ -104,31 +136,39 @@ function run(ctx, args = []) {
     // 2 indent + slug + space + name + " — " + tagline must fit one line.
     const budget = Math.max(20, cols - (2 + slugWidth + 1 + displayWidth(name) + 3));
     const shown = tag ? clampTag(tag, budget) : "";
-    ctx.out(`  ${ctx.ui.accent(clampSlug(a.slug))} ${name}${shown ? ctx.ui.dim(" — " + shown) : ""}`);
+    ctx.out(`  ${paint("accent", clampSlug(a.slug))} ${name}${shown ? paint("dim", " — " + shown) : ""}`);
   }
   if (firms.length) {
-    ctx.out("");
-    ctx.out(ctx.ui.bold(en ? "Companies" : "회사"));
+    if (!noHeaders) {
+      ctx.out("");
+      ctx.out(paint("bold", en ? "Companies" : "회사"));
+    }
     for (const f of firms) {
       const callable = String(f.slug || f.id);
-      ctx.out(`  ${ctx.ui.accent(callable.padEnd(28))} ${f.name}`);
+      ctx.out(`  ${paint("accent", callable.padEnd(28))} ${f.name}`);
     }
-    ctx.out(ctx.ui.dim(en
+    ctx.out(paint("dim", en
       ? "  Run one with: agentlas firm <company-key> \"<task>\""
       : "  실행: agentlas firm <회사 키> \"<작업>\""));
   }
 
   const active = activeRuntimeRow(db);
   const clis = listAvailableCliRuntimes();
-  ctx.out("");
-  ctx.out(ctx.ui.bold(en ? "Model roles" : "모델 역할"));
+  if (!noHeaders) {
+    ctx.out("");
+    ctx.out(paint("bold", en ? "Model roles" : "모델 역할"));
+  }
   const orchestrator = resolvedModelRole(db, "orchestrator");
   const worker = resolvedModelRole(db, "worker");
+  const multimodal = resolvedModelRole(db, "multimodal");
   ctx.out(`  orchestrator: ${roleRuntimeLabel(orchestrator, "orchestrator", en)}`);
   ctx.out(`  worker:       ${roleRuntimeLabel(worker, "worker", en)}`);
+  ctx.out(`  multimodal:   ${roleRuntimeLabel(multimodal, "multimodal", en)}`);
 
-  ctx.out("");
-  ctx.out(ctx.ui.bold(en ? "Legacy runtime compatibility" : "레거시 런타임 호환"));
+  if (!noHeaders) {
+    ctx.out("");
+    ctx.out(paint("bold", en ? "Legacy runtime compatibility" : "레거시 런타임 호환"));
+  }
   if (active) {
     ctx.out(`  active: ${active.kind}${active.model ? ` (${active.model})` : ""}${active.backend ? ` via ${active.backend}` : ""}`);
   } else {

package/engine/commands/login.cjs

@@ -9,6 +9,11 @@ const auth = require("../cloud/auth.cjs");
 
 async function run(ctx, args = []) {
   const ko = ctx.lang === "ko";
+  if (args.some((arg) => arg !== "--force") || args.filter((arg) => arg === "--force").length > 1) {
+    const error = new Error("usage: agentlas login [--force]");
+    error.code = "INVALID_ARGUMENT";
+    throw error;
+  }
   const force = args.includes("--force");
   if (!force) {
     const existing = auth.cloudSessionCookie();

package/engine/commands/logout.cjs

@@ -5,8 +5,13 @@
  */
 const auth = require("../cloud/auth.cjs");
 
-function run(ctx) {
+function run(ctx, args = []) {
   const ko = ctx.lang === "ko";
+  if (args.length) {
+    const error = new Error("usage: agentlas logout");
+    error.code = "INVALID_ARGUMENT";
+    throw error;
+  }
   let result;
   try {
     result = auth.deleteCliSession();

package/engine/commands/mcp.cjs

@@ -34,7 +34,7 @@ function list(ctx) {
 async function probe(ctx, args) {
   const en = ctx.lang === "en";
   const ref = String(args[0] || "").trim();
-  if (!ref) {
+  if (!ref || args.length !== 1 || ref.startsWith("-")) {
     ctx.err(en ? "Usage: agentlas mcp probe <server-id|catalog-id>" : "사용법: agentlas mcp probe <server-id|catalog-id>");
     return 1;
   }
@@ -83,7 +83,13 @@ function run(ctx, args = []) {
   // 무인자 기본 동작이 목록인데 이름으로 부르면 거부되는 비대칭이 있었다
   // (2026-08-05 감사 결함 G): 다른 명령들(cloud list, plugin list)이 만든
   // "list를 붙이는" 습관이 여기서만 usage 오류가 됐다.
-  if (sub === "list" || sub === "ls") return list(ctx);
+  if (sub === "list" || sub === "ls") {
+    if (rest.length) {
+      ctx.err(ctx.lang === "en" ? "Usage: agentlas mcp list" : "사용법: agentlas mcp list");
+      return 1;
+    }
+    return list(ctx);
+  }
   if (sub === "probe") return probe(ctx, rest);
   const en = ctx.lang === "en";
   ctx.err(en

package/engine/commands/memory.cjs

@@ -6,11 +6,12 @@
  * engine/agentlas-memory-import.cjs 가 소유한다(여기서는 주입만).
  * v1의 fail(process.exit)은 v2에서 throw 로 바꿔 엔진이 stderr+exit 1 처리한다.
  */
-const { cmdMemory } = require("../agentlas-memory-import.cjs");
+const { cmdMemory, parseMemoryArgs } = require("../agentlas-memory-import.cjs");
 
 function run(ctx, args) {
+  const parsed = parseMemoryArgs(args);
   cmdMemory({
-    db: ctx.db(),
+    db: parsed.help ? null : ctx.db(),
     args,
     out: ctx.out,
     fail: (msg) => { throw new Error(String(msg ?? "")); },

package/engine/commands/multimodal.cjs

@@ -51,6 +51,18 @@ function saveSettings(db, patch) {
 
 function run(ctx, args) {
   const ko = ctx.lang === "ko";
+  const usage = ko
+    ? "사용법: agentlas multimodal [set <image|video|audio> <provider-id>]"
+    : "Usage: agentlas multimodal [set <image|video|audio> <provider-id>]";
+  if (args.length === 1 && ["help", "--help", "-h"].includes(args[0])) {
+    ctx.out(usage);
+    return 0;
+  }
+  if (args.length !== 0 && !(args.length === 3 && args[0] === "set")) {
+    const error = new Error(usage);
+    error.code = "INVALID_ARGUMENT";
+    throw error;
+  }
   const db = ctx.db();
 
   if (args[0] === "set") {

package/engine/commands/native.cjs

@@ -8,6 +8,10 @@ function run(ctx, args) {
   const sub = String(args[0] || "help");
   const query = args[1];
   if (sub === "help" || sub === "--help" || sub === "-h") {
+    if (args.length > 1) {
+      ctx.err(ko ? "사용법: agentlas native help" : "usage: agentlas native help");
+      return 1;
+    }
     // SELF_HELP_COMMANDS 계약: --help 는 스텁이 아니라 실제 안내여야 한다 —
     // 무엇이 만들어지고 언제 필요한지까지 말한다.
     ctx.out(ko
@@ -29,7 +33,7 @@ function run(ctx, args) {
       ].join("\n"));
     return 0;
   }
-  if (sub !== "prepare" || !query) {
+  if (sub !== "prepare" || !query || args.length !== 2) {
     ctx.err(ko ? "사용법: agentlas native prepare <에이전트>" : "usage: agentlas native prepare <agent>");
     return 1;
   }

package/engine/commands/one.cjs

@@ -20,6 +20,7 @@
  *   agentlas one --list                One 대화 목록
  *   agentlas one --new "<프롬프트>"      새 One 대화로 시작
  *   agentlas one --chat <id> "<p>"     특정 One 대화에 이어 붙임
+ *   agentlas one -- "list 같은 옵션 모양의 프롬프트"
  *   공통: -p/--print · --runtime · --model · --effort · --permission
  */
 const readline = require("node:readline");
@@ -30,7 +31,7 @@ const { Renderer } = require("../ui/renderer.cjs");
 const permissions = require("../agentlas-permissions.cjs");
 const { EFFORTS } = require("../agentlas-workload-routing.cjs");
 const { projectCwd } = require("../project/paths.cjs");
-const { columnExists, runWriteTransaction } = require("../core/db.cjs");
+const { runWriteTransaction } = require("../core/db.cjs");
 const store = require("../sessions/store.cjs");
 
 /** 데스크탑 정본 신원(electron/architecture/manifest.ts + builtinAgentId). */
@@ -45,13 +46,8 @@ const ONE_ORIGIN_SURFACE = "one";
  * 걸러 낸다(설계). One 은 라우팅 후보가 아니라 **신원 행**이므로 직접 읽는다.
  */
 function resolveOneAgent(db) {
-  let row = null;
-  try {
-    row = db.prepare("SELECT * FROM installed_agents WHERE id=?").get(ONE_AGENT_ID)
-      || db.prepare("SELECT * FROM installed_agents WHERE slug=?").get(ONE_AGENT_SLUG);
-  } catch {
-    row = null;
-  }
+  const row = db.prepare("SELECT * FROM installed_agents WHERE id=?").get(ONE_AGENT_ID)
+    || db.prepare("SELECT * FROM installed_agents WHERE slug=?").get(ONE_AGENT_SLUG);
   return rowToAgent(row);
 }
 
@@ -78,26 +74,22 @@ function desktopOnePersona() {
 }
 
 function chatsHaveOriginSurface(db) {
-  return columnExists(db, "chats", "origin_surface");
+  return db.prepare("PRAGMA table_info(chats)").all().some((column) => column.name === "origin_surface");
 }
 
 /** One 소유 대화 목록(최근 순). origin_surface 열이 없는 구형 DB 는 에이전트 소유로 폴백. */
 function listOneChats(db, limit = 20) {
   const bounded = Math.max(1, Math.min(Number(limit) || 20, 200));
-  try {
-    if (chatsHaveOriginSurface(db)) {
-      return db.prepare(
-        "SELECT id, title, updated_at, origin_surface FROM chats " +
-        "WHERE origin_surface = ? ORDER BY updated_at DESC, rowid DESC LIMIT ?",
-      ).all(ONE_ORIGIN_SURFACE, bounded);
-    }
+  if (chatsHaveOriginSurface(db)) {
     return db.prepare(
-      "SELECT id, title, updated_at FROM chats WHERE agent_id IN (?, ?) AND (kind IS NULL OR kind <> 'division') " +
-      "ORDER BY updated_at DESC, rowid DESC LIMIT ?",
-    ).all(ONE_AGENT_ID, ONE_AGENT_SLUG, bounded);
-  } catch {
-    return [];
+      "SELECT id, title, updated_at, origin_surface FROM chats " +
+      "WHERE origin_surface = ? ORDER BY updated_at DESC, rowid DESC LIMIT ?",
+    ).all(ONE_ORIGIN_SURFACE, bounded);
   }
+  return db.prepare(
+    "SELECT id, title, updated_at FROM chats WHERE agent_id IN (?, ?) AND (kind IS NULL OR kind <> 'division') " +
+    "ORDER BY updated_at DESC, rowid DESC LIMIT ?",
+  ).all(ONE_AGENT_ID, ONE_AGENT_SLUG, bounded);
 }
 
 /**
@@ -121,19 +113,48 @@ function createOneChat(db, { agentId, title, workingFolder }) {
 }
 
 function parseArgs(args) {
-  const out = { print: false, list: false, fresh: false, chatId: null, runtime: null, model: null, effort: null, permission: null, rest: [] };
+  const out = { print: false, list: false, fresh: false, chatId: null, runtime: null, model: null, effort: null, permission: null, rest: [], error: null };
+  const readValue = (index, flag) => {
+    const value = args[index + 1];
+    if (typeof value !== "string" || !value || value === "--" || value.startsWith("--")) {
+      out.error = `${flag} requires a value`;
+      return null;
+    }
+    return value;
+  };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
+    if (a === "--") {
+      out.rest.push(...args.slice(i + 1));
+      break;
+    }
     if (a === "-p" || a === "--print") out.print = true;
-    else if (a === "--list" || a === "list") out.list = true;
-    else if (a === "--new" || a === "new") out.fresh = true;
-    else if (a === "--chat") out.chatId = args[++i];
-    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 === "--permission") out.permission = args[++i];
+    else if (a === "--list") out.list = true;
+    else if (a === "--new") out.fresh = true;
+    else if (["--chat", "--runtime", "--model", "--effort", "--permission"].includes(a)) {
+      const value = readValue(i, a);
+      if (value === null) break;
+      if (a === "--chat") out.chatId = value;
+      else if (a === "--runtime") out.runtime = value;
+      else if (a === "--model") out.model = value;
+      else if (a === "--effort") out.effort = value;
+      else out.permission = value;
+      i += 1;
+    }
+    else if (a.startsWith("-")) {
+      out.error = `unknown option ${a}`;
+      break;
+    }
     else out.rest.push(a);
   }
+  if (!out.error && out.list && (
+    out.fresh || out.chatId || out.runtime || out.model || out.effort || out.permission || out.rest.length > 0
+  )) {
+    out.error = "--list cannot be combined with a prompt or execution options";
+  }
+  if (!out.error && out.fresh && out.chatId) {
+    out.error = "--new cannot be combined with --chat";
+  }
   return out;
 }
 
@@ -153,6 +174,10 @@ function renderList(ctx, rows) {
 
 async function runOne(ctx, args) {
   const parsed = parseArgs(args);
+  if (parsed.error) {
+    ctx.err(`invalid one arguments: ${parsed.error}`);
+    return 1;
+  }
   if (parsed.permission && !permissions.LEVELS.includes(String(parsed.permission))) {
     ctx.err(`unknown --permission ${parsed.permission} (use: ${permissions.LEVELS.join(" | ")})`);
     return 1;
@@ -163,12 +188,29 @@ async function runOne(ctx, args) {
   }
 
   const db = ctx.db();
+  const readChats = (limit) => {
+    try {
+      return listOneChats(db, limit);
+    } catch (error) {
+      ctx.err(`Could not read One conversations: ${String((error && error.message) || error)}`);
+      return null;
+    }
+  };
 
   // 목록은 신원 행이 없어도 답할 수 있어야 한다 — 대화는 chats 에 있고, One 행은
   // 실행에만 필요하다. 조회를 실행 전제조건 뒤에 두면 "볼 수도 없는" 화면이 된다.
-  if (parsed.list) return renderList(ctx, listOneChats(db, 20));
+  if (parsed.list) {
+    const rows = readChats(20);
+    return rows ? renderList(ctx, rows) : 1;
+  }
 
-  const agent = resolveOneAgent(db);
+  let agent;
+  try {
+    agent = resolveOneAgent(db);
+  } catch (error) {
+    ctx.err(`Could not read the Agentlas One identity: ${String((error && error.message) || error)}`);
+    return 1;
+  }
   if (!agent) {
     ctx.err(
       "Agentlas One is not present in the shared database yet.\n" +
@@ -212,14 +254,17 @@ async function runOne(ctx, args) {
   let chatId = null;
   let created = false;
   if (parsed.chatId) {
-    const row = listOneChats(db, 200).find((item) => item.id === parsed.chatId);
+    const rows = readChats(200);
+    if (!rows) return 1;
+    const row = rows.find((item) => item.id === parsed.chatId);
     if (!row) {
       ctx.err(`No One conversation with id ${parsed.chatId} (see: agentlas one --list)`);
       return 1;
     }
     chatId = row.id;
   } else if (!parsed.fresh) {
-    const recent = listOneChats(db, 1);
+    const recent = readChats(1);
+    if (!recent) return 1;
     if (recent.length) chatId = recent[0].id;
   }
   if (!chatId) {

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 };