agentlas 1.0.65 → 1.0.67

package/engine/commands/creds.cjs

@@ -24,6 +24,9 @@ const {
   upsertLocalCredentialMapCli,
   projectScopedGlobalEnvKeyCli,
   safeCredentialDestRelCli,
+  credentialProjectRootCli,
+  resolveCredentialDestinationCli,
+  copyCredentialFileAtomicCli,
 } = require("../project/credentials.cjs");
 
 // 데스크탑과 공유하는 키체인 서비스/키 접두어 (v1 상수 그대로).
@@ -41,19 +44,27 @@ function readKeytar() {
   }
 }
 
-function parseCredFlags(args) {
+function parseCredFlags(args, schema) {
   const f = {};
+  const values = new Set(schema.values || []);
+  const booleans = new Set(schema.booleans || []);
   for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a && a.startsWith("--")) {
-      const next = args[i + 1];
-      if (next !== undefined && !String(next).startsWith("--")) {
-        f[a.slice(2)] = next;
-        i++;
-      } else {
-        f[a.slice(2)] = true;
-      }
+    const token = String(args[i]);
+    if (!token.startsWith("--") || token === "--") throw new Error(`unexpected argument: ${token}`);
+    const at = token.indexOf("=");
+    const key = token.slice(2, at >= 0 ? at : undefined);
+    if (!values.has(key) && !booleans.has(key)) throw new Error(`unknown option: --${key}`);
+    if (Object.prototype.hasOwnProperty.call(f, key)) throw new Error(`duplicate option: --${key}`);
+    if (booleans.has(key)) {
+      if (at >= 0) throw new Error(`--${key} does not take a value`);
+      f[key] = true;
+      continue;
     }
+    const next = at >= 0 ? token.slice(at + 1) : args[++i];
+    if (next === undefined || next === "" || (at < 0 && String(next).startsWith("--"))) {
+      throw new Error(`--${key} requires a value`);
+    }
+    f[key] = String(next);
   }
   return f;
 }
@@ -66,20 +77,35 @@ function resolveCredentialSourcePath(source, cwd) {
 
 async function cmdCredsFile(ctx, args) {
   const fail = (msg) => { ctx.err(msg); return 1; };
-  const f = parseCredFlags(args);
+  let f;
+  try {
+    f = parseCredFlags(args, {
+      values: ["source", "path", "provider", "env", "dest", "project", "id", "requiredFor", "staleCheck"],
+      booleans: ["force"],
+    });
+  } catch (error) { return fail(String((error && error.message) || error)); }
+  if (f.source !== undefined && f.path !== undefined) return fail("use only one of --source or --path");
   const source = typeof f.source === "string" ? f.source : typeof f.path === "string" ? f.path : "";
   if (!source) return fail("usage: agentlas creds file --source <path> [--provider <name>] [--env <ENV_NAME>] [--dest <relative-path>] [--project <path>] [--force]");
-  const project = typeof f.project === "string" && f.project ? f.project : activeProjectPath(ctx.db());
-  if (!project) return fail("creds file requires a project path");
+  const requestedProject = typeof f.project === "string" && f.project ? f.project : activeProjectPath(ctx.db());
+  if (!requestedProject) return fail("creds file requires a project path");
+  let project;
+  try { project = credentialProjectRootCli(requestedProject); }
+  catch (error) { return fail(`credential project is unsafe: ${String((error && error.message) || error)}`); }
   const provider = typeof f.provider === "string" && f.provider ? f.provider : "credential_file";
+  if (provider.length > 128 || /[\u0000-\u001f\u007f]/.test(provider)) return fail("credential provider name contains unsafe text");
   const envKey = typeof f.env === "string" && f.env ? f.env.trim() : "";
   if (envKey && !/^[A-Z][A-Z0-9_]*$/.test(envKey)) return fail("credential env name must look like ENV_NAME");
 
   const arch = loadArch();
   const cfg = localCredentialConfigCli(arch);
   const projectName = path.basename(project) || "Project";
-  ensureLocalCredentialStoreCli(project, projectName, arch);
-  ensureSoulCredentialIndexCli(project, projectName, arch);
+  try {
+    ensureLocalCredentialStoreCli(project, projectName, arch);
+    ensureSoulCredentialIndexCli(project, projectName, arch);
+  } catch (error) {
+    return fail(`credential store is unsafe: ${String((error && error.message) || error)}`);
+  }
 
   const sourceAbs = resolveCredentialSourcePath(source);
   let stat;
@@ -99,15 +125,13 @@ async function cmdCredsFile(ctx, args) {
   } catch (e) {
     return fail(String((e && e.message) || e));
   }
-  const destAbs = path.join(project, destRel);
-  if (!path.resolve(destAbs).startsWith(path.resolve(project) + path.sep)) {
-    return fail("credential destination must stay inside the project");
+  let destAbs;
+  try {
+    destAbs = resolveCredentialDestinationCli(project, destRel);
+    copyCredentialFileAtomicCli(sourceAbs, destAbs, { force: Boolean(f.force) });
+  } catch (error) {
+    return fail(`credential copy refused: ${String((error && error.message) || error)}`);
   }
-  if (fs.existsSync(destAbs) && !f.force) return fail(`credential destination already exists: ${destRel} (use --force to replace)`);
-
-  fs.mkdirSync(path.dirname(destAbs), { recursive: true });
-  fs.copyFileSync(sourceAbs, destAbs);
-  try { fs.chmodSync(destAbs, 0o600); } catch { /* best-effort */ }
 
   const targets = [destRel];
   if (envKey) {
@@ -185,11 +209,20 @@ async function run(ctx, args) {
   const fail = (msg) => { ctx.err(msg); return 1; };
   const sub = args[0];
   if (sub === "file") return cmdCredsFile(ctx, args.slice(1));
-  if (sub === "list" || sub === "ls") return cmdCredsList(ctx);
+  if (sub === "list" || sub === "ls") {
+    if (args.length !== 1) return fail(`unexpected argument: ${String(args[1])}`);
+    return cmdCredsList(ctx);
+  }
   if (sub !== "save") {
     return fail('usage: agentlas creds save --provider <name> --key <ENV_NAME> --value <value> [--project <path>] OR agentlas creds file --source <path> [--env <ENV_NAME>] OR agentlas creds list');
   }
-  const f = parseCredFlags(args.slice(1));
+  let f;
+  try {
+    f = parseCredFlags(args.slice(1), {
+      values: ["provider", "key", "value", "project"],
+      booleans: [],
+    });
+  } catch (error) { return fail(String((error && error.message) || error)); }
   const key = typeof f.key === "string" ? f.key.trim() : "";
   let value = f.value === undefined || f.value === true ? "" : String(f.value);
   /*
@@ -207,14 +240,26 @@ async function run(ctx, args) {
       : "Note: a secret passed via --value lands in shell history and `ps`. Prefer stdin next time: printf '%s' \"$SECRET\" | agentlas creds save --key X --value -");
   }
   if (!key || !value) return fail("creds save requires --key and --value (use `--value -` to read the secret from stdin)");
+  if (!/^[A-Z][A-Z0-9_]*$/.test(key)) return fail("credential env name must look like ENV_NAME");
+  if (/[\u0000\r\n]/.test(value)) return fail("credential env value must be a single line; use `agentlas creds file` for multiline credentials");
   const provider = typeof f.provider === "string" && f.provider ? f.provider : key;
-  const project = typeof f.project === "string" && f.project ? f.project : activeProjectPath(ctx.db());
+  if (provider.length > 128 || /[\u0000-\u001f\u007f]/.test(provider)) return fail("credential provider name contains unsafe text");
+  const requestedProject = typeof f.project === "string" && f.project ? f.project : activeProjectPath(ctx.db());
+  let project = null;
+  if (requestedProject) {
+    try { project = credentialProjectRootCli(requestedProject); }
+    catch (error) { return fail(`credential project is unsafe: ${String((error && error.message) || error)}`); }
+  }
   const targets = [];
   const arch = loadArch();
   const projectName = project ? path.basename(project) || "Project" : "Project";
   if (project) {
-    ensureLocalCredentialStoreCli(project, projectName, arch);
-    ensureSoulCredentialIndexCli(project, projectName, arch);
+    try {
+      ensureLocalCredentialStoreCli(project, projectName, arch);
+      ensureSoulCredentialIndexCli(project, projectName, arch);
+    } catch (error) {
+      return fail(`credential store is unsafe: ${String((error && error.message) || error)}`);
+    }
   }
 
   // 1) keychain vault — project-scoped when a project is active.
@@ -262,4 +307,4 @@ async function run(ctx, args) {
   return 0;
 }
 
-module.exports = { run, resolveCredentialSourcePath };
+module.exports = { run, resolveCredentialSourcePath, parseCredFlags };

package/engine/commands/doctor.cjs

@@ -14,6 +14,14 @@ const { runtimeAuthEvidence } = require("../runtimes/auth-evidence.cjs");
 const { sharedRuntimeKind } = require("../runtimes/resolve.cjs");
 const { resolvedModelRole } = require("../runtimes/roles.cjs");
 
+function hasCloudSessionCredential() {
+  try {
+    return Boolean(require("../cloud/auth.cjs").cloudSessionCookie());
+  } catch {
+    return false;
+  }
+}
+
 function roleDetail(selection, role, en) {
   if (!selection) return en ? "not set" : "미설정";
   const provider = selection.kind === "byok" ? selection.backend || "byok" : selection.kind;
@@ -28,6 +36,12 @@ function roleDetail(selection, role, en) {
 
 async function run(ctx, args = []) {
   const en = ctx.lang === "en";
+  const unknown = args.filter((arg) => arg !== "--json");
+  if (unknown.length || args.filter((arg) => arg === "--json").length > 1) {
+    const error = new Error("usage: agentlas doctor [--json]");
+    error.code = "INVALID_ARGUMENT";
+    throw error;
+  }
   // clig.dev: 스크립트 소비자를 위한 기계 계약. 사람용 줄과 같은 사실만 담는다.
   if (ctx.output?.format === "json" || args.includes("--json")) {
     const db = ctx.db();
@@ -43,7 +57,9 @@ async function run(ctx, args = []) {
           orchestrator: resolvedModelRole(db, "orchestrator"),
           worker: resolvedModelRole(db, "worker"),
         },
-        cloudSession: Boolean(process.env.AGENTLAS_SESSION) || fs.existsSync(path.join(userDataDir(), "auth", "cli-session.v1.json")),
+        // JSON is intentionally offline, but it must use the same validated
+        // credential interpretation as the human path rather than file existence.
+        cloudSession: hasCloudSessionCredential(),
       }, null, 2));
       return 0;
     })();

package/engine/commands/document.cjs

@@ -26,13 +26,42 @@ function toUrl(src) {
   return "file://" + path.resolve(src);                            // 로컬 파일
 }
 
+function documentArgumentError(message) {
+  const error = new Error(message);
+  error.code = "INVALID_ARGUMENT";
+  return error;
+}
+
+function parsePdfArgs(args, ko) {
+  let landscape = false;
+  let out = null;
+  let src = null;
+  for (let index = 0; index < args.length; index += 1) {
+    const token = String(args[index]);
+    if (token === "--landscape") {
+      if (landscape) throw documentArgumentError(usage(ko));
+      landscape = true;
+      continue;
+    }
+    if (token === "-o") {
+      if (out !== null) throw documentArgumentError(usage(ko));
+      const value = args[index + 1];
+      if (!value || String(value).startsWith("-")) throw documentArgumentError(usage(ko));
+      out = String(value);
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("-")) throw documentArgumentError(usage(ko));
+    if (src !== null) throw documentArgumentError(usage(ko));
+    src = token;
+  }
+  if (!src) throw documentArgumentError(usage(ko));
+  return { landscape, out, src };
+}
+
 async function toPdf(ctx, args) {
   const ko = ctx.lang === "ko";
-  const flags = { landscape: args.includes("--landscape") };
-  const oi = args.indexOf("-o");
-  const out = oi >= 0 && args[oi + 1] ? args[oi + 1] : null;
-  const src = args.find((a, i) => a && !String(a).startsWith("-") && (oi < 0 || i !== oi + 1));
-  if (!src) { ctx.err(usage(ko)); return 1; }
+  const { landscape, out, src } = parsePdfArgs(args, ko);
 
   // 로컬 파일이면 존재 확인(없는 걸 조용히 빈 PDF 로 굽지 않는다).
   if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(src) && !fs.existsSync(path.resolve(src))) {
@@ -54,7 +83,7 @@ async function toPdf(ctx, args) {
     page = await cdp.attachPage({ selection: "new" });
     await page.navigate(url, { waitMs: 1800 });
     await page.waitFor("document.readyState === 'complete'", { timeoutMs: 8000 });
-    const r = await page.printPdf(outPath, { landscape: flags.landscape });
+    const r = await page.printPdf(outPath, { landscape });
     if (typeof ctx.ui.stopSpinner === "function") ctx.ui.stopSpinner();
     ctx.out(`${ctx.ui.green("✓")} ${ko ? "PDF 를 만들었습니다" : "wrote PDF"}: ${r.path} ${ctx.ui.dim(`(${Math.round(r.bytes / 1024)} KB)`)}`);
     return 0;
@@ -70,10 +99,9 @@ async function toPdf(ctx, args) {
 async function run(ctx, args) {
   const ko = ctx.lang === "ko";
   const sub = String(args[0] || "").toLowerCase();
-  if (!sub || sub === "help" || sub === "-h" || sub === "--help") { ctx.out(usage(ko)); return 0; }
+  if (!sub || (["help", "-h", "--help"].includes(sub) && args.length === 1)) { ctx.out(usage(ko)); return 0; }
   if (sub === "pdf") return toPdf(ctx, args.slice(1));
-  ctx.err(usage(ko));
-  return 1;
+  throw documentArgumentError(usage(ko));
 }
 
-module.exports = { run };
+module.exports = { run, parsePdfArgs };

package/engine/commands/env.cjs

@@ -21,7 +21,12 @@ function sharedEnvKeys() {
   return Object.keys(fromFiles).sort();
 }
 
-function run(ctx) {
+function run(ctx, args = []) {
+  if (args.length) {
+    const error = new Error("usage: agentlas env");
+    error.code = "INVALID_ARGUMENT";
+    throw error;
+  }
   const keys = sharedEnvKeys();
   ctx.out(`Shared env keys: ${keys.length} (values hidden; from credentials.env):`);
   for (const k of keys) ctx.out(`  ${k}`);

package/engine/commands/firm.cjs

@@ -9,6 +9,42 @@
  */
 const { rowToAgent } = require("../agents/registry.cjs");
 
+function parseFirmArgs(args) {
+  const flags = { runtime: null, model: null, effort: null, tier: null, permission: null, task: [] };
+  const fields = new Map([
+    ["--runtime", "runtime"],
+    ["--model", "model"],
+    ["--effort", "effort"],
+    ["--tier", "tier"],
+    ["--permission", "permission"],
+  ]);
+  const seen = new Set();
+  let passthrough = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const token = String(args[i]);
+    if (passthrough) { flags.task.push(token); continue; }
+    if (token === "--") { passthrough = true; continue; }
+    const at = token.indexOf("=");
+    const option = at >= 0 ? token.slice(0, at) : token;
+    const field = fields.get(option);
+    if (field) {
+      if (seen.has(field)) throw new Error(`duplicate option: ${option}`);
+      seen.add(field);
+      const value = at >= 0 ? token.slice(at + 1) : args[++i];
+      if (value === undefined || value === "" || (at < 0 && String(value).startsWith("--"))) {
+        throw new Error(`${option} requires a value`);
+      }
+      flags[field] = String(value);
+      continue;
+    }
+    if (token.startsWith("-")) {
+      throw new Error(`unknown option: ${token} (use -- before a task that starts with '-')`);
+    }
+    flags.task.push(token);
+  }
+  return flags;
+}
+
 function findFirm(db, token) {
   const q = String(token || "").trim().toLowerCase();
   if (!q) return null;
@@ -50,17 +86,11 @@ async function run(ctx, args) {
   }
   const ceo = rowToAgent(ceoRow);
 
-  // 간단 플래그 파싱 — 명령끼리 참조 금지 규칙상 run.cjs 미차용.
-  const rest = args.slice(1);
-  const flags = { runtime: null, model: null, effort: null, tier: null, permission: null, task: [] };
-  for (let i = 0; i < rest.length; i++) {
-    if (rest[i] === "--runtime") flags.runtime = rest[++i];
-    else if (rest[i] === "--model") flags.model = rest[++i];
-    else if (rest[i] === "--effort") flags.effort = rest[++i];
-    else if (rest[i] === "--tier") flags.tier = rest[++i];
-    else if (rest[i] === "--permission") flags.permission = rest[++i];
-    else flags.task.push(rest[i]);
-  }
+  // 명령끼리 참조 금지 규칙상 run.cjs 미차용. 오타 옵션은 CEO 계획 턴으로
+  // 흘리지 않고, 대시로 시작하는 실제 작업은 `--` 뒤에서만 받는다.
+  let flags;
+  try { flags = parseFirmArgs(args.slice(1)); }
+  catch (error) { ctx.err(String((error && error.message) || error)); return 1; }
   const task = flags.task.join(" ").trim();
   if (task) {
     // 3-tier 위임 실행 — PLAN → DELEGATE → SYNTHESIZE (firms/orchestrate.cjs).
@@ -176,4 +206,4 @@ async function run(ctx, args) {
   return startRepl(ctx, { agent: ceo.slug });
 }
 
-module.exports = { run, findFirm };
+module.exports = { run, findFirm, parseFirmArgs };

package/engine/commands/graph.cjs

@@ -15,7 +15,11 @@ const fs = require("node:fs");
 const path = require("node:path");
 const pkgLib = require("../graph/package.cjs");
 const desktopCore = require("../core/desktop-core.cjs");
+const { terminalTextOf } = require("../cli-output.cjs");
 
+function inlineText(value, maxLength = 500) {
+  return terminalTextOf(value, maxLength).replace(/\s+/g, " ").trim();
+}
 
 
 function graphRows(ctx, db) {
@@ -116,7 +120,7 @@ function describe(ctx, row, graph, en) {
   const kindLabel = kind === "cron"
     ? (en ? "schedule" : "예약")
     : (en ? "input" : "입력");
-  return `${ctx.ui.bold(row.name)}  ${ctx.ui.dim(`${kindLabel} · ${nodeCount} ${en ? "steps" : "단계"} · ${state} · ${when}`)}`;
+  return `${ctx.ui.bold(inlineText(row.name))}  ${ctx.ui.dim(`${kindLabel} · ${nodeCount} ${en ? "steps" : "단계"} · ${state} · ${inlineText(when)}`)}`;
 }
 
 function findGraph(rows, needle) {
@@ -135,9 +139,9 @@ function findGraph(rows, needle) {
 /** 이름이 여러 개 걸렸을 때, 고르지 말고 후보를 보여준다. */
 function reportAmbiguous(ctx, needle, matches, en) {
   ctx.err(en
-    ? `"${needle}" matches ${matches.length} automations. Say which one:`
-    : `"${needle}"에 자동화 ${matches.length}개가 걸립니다. 어느 것인지 정확히 적어 주세요:`);
-  for (const row of matches) ctx.err(`  · ${row.name}`);
+    ? `"${inlineText(needle)}" matches ${matches.length} automations. Say which one:`
+    : `"${inlineText(needle)}"에 자동화 ${matches.length}개가 걸립니다. 어느 것인지 정확히 적어 주세요:`);
+  for (const row of matches) ctx.err(`  · ${inlineText(row.name)}`);
 }
 
 function listGraphs(ctx) {
@@ -240,8 +244,8 @@ async function reconcileGraph(ctx, needle, flags, en) {
   const view = reconciliation.get(row.id);
   if (!view) {
     ctx.out(en
-      ? `"${row.name}" has nothing waiting to be reconciled.`
-      : `"${row.name}"에는 재조정을 기다리는 것이 없습니다.`);
+      ? `"${inlineText(row.name)}" has nothing waiting to be reconciled.`
+      : `"${inlineText(row.name)}"에는 재조정을 기다리는 것이 없습니다.`);
     return 0;
   }
 
@@ -255,34 +259,34 @@ async function reconcileGraph(ctx, needle, flags, en) {
 
   if (done.size === 0 && notDone.size === 0) {
     ctx.out(en
-      ? `"${row.name}" stopped with steps whose effect cannot be told from the record.`
-      : `"${row.name}"은(는) 기록만으로는 일어났는지 알 수 없는 단계가 있어 멈춰 있습니다.`);
+      ? `"${inlineText(row.name)}" stopped with steps whose effect cannot be told from the record.`
+      : `"${inlineText(row.name)}"은(는) 기록만으로는 일어났는지 알 수 없는 단계가 있어 멈춰 있습니다.`);
     ctx.out("");
     for (const node of view.nodes) {
       const needs = node.outputRequired
         ? (en ? `  (needs --output ${node.nodeId}=<value> when done)` : `  (일어났다면 --output ${node.nodeId}=<값> 필요)`)
         : "";
-      ctx.out(`  ${node.nodeId}  ${node.label}${needs}`);
+      ctx.out(`  ${inlineText(node.nodeId)}  ${inlineText(node.label)}${inlineText(needs)}`);
     }
     ctx.out("");
     ctx.out(ctx.ui.dim(en
-      ? `Decide each one: agentlas graph reconcile "${row.name}" --done <node> --not-done <node>`
-      : `각각 정하세요: agentlas graph reconcile "${row.name}" --done <노드> --not-done <노드>`));
+      ? `Decide each one: agentlas graph reconcile "${inlineText(row.name)}" --done <node> --not-done <node>`
+      : `각각 정하세요: agentlas graph reconcile "${inlineText(row.name)}" --done <노드> --not-done <노드>`));
     return 0;
   }
 
   const undecided = view.nodes.filter((n) => !done.has(n.nodeId) && !notDone.has(n.nodeId));
   if (undecided.length > 0) {
     ctx.err(en
-      ? `Still undecided: ${undecided.map((n) => n.nodeId).join(", ")}. Every step needs one answer.`
-      : `아직 안 정한 단계가 있습니다: ${undecided.map((n) => n.nodeId).join(", ")}. 모든 단계에 답이 필요합니다.`);
+      ? `Still undecided: ${undecided.map((n) => inlineText(n.nodeId)).join(", ")}. Every step needs one answer.`
+      : `아직 안 정한 단계가 있습니다: ${undecided.map((n) => inlineText(n.nodeId)).join(", ")}. 모든 단계에 답이 필요합니다.`);
     return 1;
   }
   const missingOutput = view.nodes.filter((n) => done.has(n.nodeId) && n.outputRequired && !outputs.has(n.nodeId));
   if (missingOutput.length > 0) {
     ctx.err(en
-      ? `These steps populate a value, so completing them needs it: ${missingOutput.map((n) => `--output ${n.nodeId}=<value>`).join(" ")}`
-      : `값을 만드는 단계라 "일어났다"로 두려면 값이 필요합니다: ${missingOutput.map((n) => `--output ${n.nodeId}=<값>`).join(" ")}`);
+      ? `These steps populate a value, so completing them needs it: ${missingOutput.map((n) => `--output ${inlineText(n.nodeId)}=<value>`).join(" ")}`
+      : `값을 만드는 단계라 "일어났다"로 두려면 값이 필요합니다: ${missingOutput.map((n) => `--output ${inlineText(n.nodeId)}=<값>`).join(" ")}`);
     return 1;
   }
 
@@ -304,8 +308,8 @@ async function reconcileGraph(ctx, needle, flags, en) {
       ? `Reconciled. ${result.completedNodeIds.length} step(s) marked as done, ${result.retryNodeIds.length} to redo.`
       : `재조정했습니다. ${result.completedNodeIds.length}개는 일어난 것으로, ${result.retryNodeIds.length}개는 다시 하는 것으로 두었습니다.`);
     ctx.out(ctx.ui.dim(en
-      ? `Now run it: agentlas graph run "${row.name}"`
-      : `이제 실행하세요: agentlas graph run "${row.name}"`));
+      ? `Now run it: agentlas graph run "${inlineText(row.name)}"`
+      : `이제 실행하세요: agentlas graph run "${inlineText(row.name)}"`));
     return 0;
   } catch (error) {
     ctx.err(en
@@ -342,8 +346,8 @@ function showGraph(ctx, needle) {
   const requirement = graphInputRequirement(graph, en);
   if (requirement) {
     ctx.out("  " + ctx.ui.dim(en
-      ? `Starts from a value you provide — ${requirement.label}`
-      : `시작할 때 값을 받습니다 — ${requirement.label}`));
+      ? `Starts from a value you provide — ${inlineText(requirement.label)}`
+      : `시작할 때 값을 받습니다 — ${inlineText(requirement.label)}`));
   }
   ctx.out("");
   renderGraphTree(ctx, graph, en);
@@ -354,8 +358,8 @@ function showGraph(ctx, needle) {
       ? `This graph will stop when it runs (${problems.length}):`
       : `이대로 실행하면 도중에 멈춥니다 (${problems.length}건):`));
     for (const p of problems) {
-      ctx.out(`  ⚠ ${p.what}`);
-      ctx.out(`    ${ctx.ui.dim(p.fix)}`);
+      ctx.out(`  ⚠ ${inlineText(p.what, 1000)}`);
+      ctx.out(`    ${ctx.ui.dim(inlineText(p.fix, 1000))}`);
     }
   }
   // 그대로 복사해 쓸 수 있는 명령. 예전에는 값이 필요한 그래프인지 화면에서만 알려주고
@@ -363,8 +367,8 @@ function showGraph(ctx, needle) {
   ctx.out("");
   ctx.out(ctx.ui.dim(en ? "Run it with:" : "실행하려면:"));
   ctx.out(requirement
-    ? `  agentlas graph run "${row.name}" --input "<${requirement.label}>"`
-    : `  agentlas graph run "${row.name}"`);
+    ? `  agentlas graph run "${inlineText(row.name)}" --input "<${inlineText(requirement.label)}>"`
+    : `  agentlas graph run "${inlineText(row.name)}"`);
   return 0;
 }
 
@@ -469,17 +473,17 @@ function nodeLine(ctx, node, en) {
     const rule = conditionRule(node, en);
     if (rule) marks.unshift(rule);
   }
-  return `${ctx.ui.accent(kindWord(node.type, en))}  ${node.label || node.id}`
-    + (marks.length ? ctx.ui.dim(`  — ${marks.join(", ")}`) : "");
+  return `${ctx.ui.accent(inlineText(kindWord(node.type, en)))}  ${inlineText(node.label || node.id)}`
+    + (marks.length ? ctx.ui.dim(`  — ${marks.map((mark) => inlineText(mark)).join(", ")}`) : "");
 }
 
 /** 갈림길이 실제로 무엇을 보는지 한 줄로. 모르는 연산은 지어내지 않고 그대로 보여준다. */
 function conditionRule(node, en) {
   const cfg = node.config || {};
-  const v = cfg.var;
+  const v = inlineText(cfg.var);
   if (typeof v !== "string" || !v.trim()) return null;
   const value = cfg.value;
-  const shown = typeof value === "string" ? `"${value}"` : String(value ?? "");
+  const shown = typeof value === "string" ? `"${inlineText(value)}"` : inlineText(value);
   switch (cfg.op) {
     case "contains": return en ? `yes when {{${v}}} contains ${shown}` : `{{${v}}}에 ${shown}이(가) 들어 있으면 예`;
     case "truthy": return en ? `yes when {{${v}}} has a value` : `{{${v}}}에 값이 있으면 예`;
@@ -488,7 +492,7 @@ function conditionRule(node, en) {
     case "neq": return en ? `yes when {{${v}}} differs from ${shown}` : `{{${v}}}이(가) ${shown}과 다르면 예`;
     case "gt": return en ? `yes when {{${v}}} > ${shown}` : `{{${v}}}이(가) ${shown}보다 크면 예`;
     case "lt": return en ? `yes when {{${v}}} < ${shown}` : `{{${v}}}이(가) ${shown}보다 작으면 예`;
-    default: return en ? `checks {{${v}}} with "${cfg.op ?? "?"}"` : `{{${v}}}을(를) "${cfg.op ?? "?"}"(으)로 검사`;
+    default: return en ? `checks {{${v}}} with "${inlineText(cfg.op ?? "?")}"` : `{{${v}}}을(를) "${inlineText(cfg.op ?? "?")}"(으)로 검사`;
   }
 }
 
@@ -525,7 +529,7 @@ function kindWord(type, en) {
   const read = vocabulary.readEnum(type, vocabulary.GRAPH_NODE_KINDS);
   if ("unknown" in read) {
     // 이 버전이 모르는 종류 — 지어내지 않고 그렇다고 말한다(원문 보존).
-    return vocabulary.degradedLabel(read, en ? "en" : "ko");
+    return vocabulary.degradedLabel({ unknown: inlineText(read.unknown) }, en ? "en" : "ko");
   }
   return (en ? enWords[read.known] : ko[read.known]) || read.known;
 }
@@ -557,8 +561,8 @@ function renderGraphTree(ctx, graph, en) {
         ? (en ? " — no repeat limit set, so it will refuse to run" : " — 반복 횟수가 정해져 있지 않아 실행이 거절됩니다")
         : (en ? ` — up to ${cap} more time(s)` : ` — 최대 ${cap}바퀴까지`);
       ctx.out(`${indent}${prefix}↩ ${ctx.ui.dim(en
-        ? `back to "${node.label || node.id}"${capText}`
-        : `"${node.label || node.id}"(으)로 되돌아감${capText}`)}`);
+        ? `back to "${inlineText(node.label || node.id)}"${capText}`
+        : `"${inlineText(node.label || node.id)}"(으)로 되돌아감${capText}`)}`);
       return;
     }
     seen.add(nodeId);
@@ -568,7 +572,7 @@ function renderGraphTree(ctx, graph, en) {
       for (const item of items) {
         if (!item || typeof item.text !== "string" || !item.text.trim()) continue;
         const mark = item.kind === "mustNot" ? (en ? "must not" : "하면 안 됨") : (en ? "must" : "있어야 함");
-        ctx.out(`${indent}  ${ctx.ui.dim(`· [${mark}] ${item.text.trim()}`)}`);
+        ctx.out(`${indent}  ${ctx.ui.dim(`· [${mark}] ${inlineText(item.text, 1000)}`)}`);
       }
     }
     const edges = outgoing.get(nodeId) ?? [];

package/engine/commands/help.cjs

@@ -10,9 +10,19 @@
 const catalog = require("../ui/commands-catalog.cjs");
 
 function run(ctx, args = []) {
+  if (!Array.isArray(args) || args.length > 1) {
+    const error = new Error("usage: agentlas help [all|<command>]");
+    error.code = "INVALID_ARGUMENT";
+    throw error;
+  }
   const first = String((args && args[0]) || "").trim();
+  if (first.startsWith("-")) {
+    const error = new Error("usage: agentlas help [all|<command>]");
+    error.code = "INVALID_ARGUMENT";
+    throw error;
+  }
   const all = first.toLowerCase() === "all";
-  const name = !all && first && !first.startsWith("-") ? first : null;
+  const name = !all && first ? first : null;
   if (name) return runForCommand(ctx, name);
   ctx.out(catalog.renderHelp({ lang: ctx.lang, surface: "cli", all }));
   return 0;

package/engine/commands/hep.cjs

@@ -13,7 +13,7 @@
 const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
 
 async function run(ctx, args) {
-  if (args.length && args.some(isHelpToken)) {
+  if (args.length === 1 && isHelpToken(args[0])) {
     ctx.out(usageFor("hep", ctx.lang));
     return 0;
   }

package/engine/commands/import.cjs

@@ -4,11 +4,12 @@ const { importLocalFolder } = require("../agents/import-local.cjs");
 
 function run(ctx, args) {
   const ko = ctx.lang === "ko";
-  const absPath = args[0];
-  if (!absPath) {
-    ctx.err(ko ? "사용법: agentlas import <폴더-경로>" : "Usage: agentlas import <folder-path>");
-    return 1;
+  if (args.length !== 1) {
+    const error = new Error(ko ? "사용법: agentlas import <폴더-경로>" : "Usage: agentlas import <folder-path>");
+    error.code = "INVALID_ARGUMENT";
+    throw error;
   }
+  const absPath = args[0];
   let r;
   try {
     r = importLocalFolder(ctx.db(), absPath);

package/engine/commands/index.cjs

@@ -181,7 +181,7 @@ function resolveCommandName(cmd) {
  * 인자로 읽는다(`agentlas run --help` 가 "help"라는 이름을 찾는 식). 추측하지 않는다.
  * `test/command-help-contract.cjs` 가 이 목록과 실제 분기를 대조한다.
  */
-const SELF_HELP_COMMANDS = new Set(["graph", "plugin", "billing", "roles", "native"]);
+const SELF_HELP_COMMANDS = new Set(["graph", "plugin", "billing", "roles", "native", "research"]);
 
 function dispatch(ctx, argv) {
   const [rawCmd, ...rest] = argv;

package/engine/commands/install.cjs

@@ -7,11 +7,13 @@
 const { installHubAgent } = require("../hub/install.cjs");
 
 async function run(ctx, args) {
-  const slug = (args[0] || "").trim();
-  if (!slug) {
-    ctx.err("usage: agentlas install <slug>");
-    return 1;
+  if (args.length !== 1 || String(args[0] || "").startsWith("-")) {
+    const error = new Error("usage: agentlas install <slug>");
+    error.code = "INVALID_ARGUMENT";
+    throw error;
   }
+  const slug = String(args[0]).trim();
+  if (!slug) throw Object.assign(new Error("usage: agentlas install <slug>"), { code: "INVALID_ARGUMENT" });
   let agent;
   try {
     agent = await installHubAgent(ctx.db(), slug);