agentlas 1.0.11 → 1.0.14

package/engine/commands/run.cjs

@@ -3,6 +3,9 @@
  * run — 원샷 실행: agentlas run [agent] [prompt…]
  *   -p | --print          최종 답만 stdout에 (스트리밍 UI 없음)
  *   --runtime <kind>      claude-code | codex | gemini
+ *   --model <id>          exact provider model id
+ *   --effort <level>      none | minimal | low | medium | high | xhigh | max
+ *   --tier <tier>         economy | balanced | frontier (requires --model)
  *   --permission <level>  read | write | full
  * 프롬프트가 없고 stdin이 TTY가 아니면 stdin을 읽는다.
  *
@@ -10,15 +13,21 @@
  * 판정(resolveAutoRoute)이 최적 에이전트를 고른다 — 어휘 점수는 후보 모집 전용이다.
  * 판정 런타임이 없으면 기본 에이전트로 정직 폴백하되 note를 stderr에 반드시 출력한다
  * (조용한 오라우팅/폴백 금지 — 오너 결정).
- * 런타임 사다리: 명시(--runtime) > 에이전트별 오버라이드(agent_runtime_overrides) >
- * prefs > active_runtime > detected (runtimes/overrides.cjs).
+ * 런타임 사다리: 명시 핀 > 에이전트별 오버라이드(agent_runtime_overrides) >
+ * model_roles[orchestrator] > active_runtime > detected (runtimes/overrides.cjs).
  */
 const { findAgent, listAgents } = require("../agents/registry.cjs");
-const { resolveRuntime } = require("../runtimes/resolve.cjs");
-const { resolveRuntimeForAgent, unavailableOverrideNote } = require("../runtimes/overrides.cjs");
+const {
+  resolveRuntimeForAgent,
+  unavailableOverrideNote,
+  unavailableRoleNote,
+} = require("../runtimes/overrides.cjs");
 const { Orchestrator } = require("../sessions/orchestrator.cjs");
 const { Renderer } = require("../ui/renderer.cjs");
 const permissions = require("../agentlas-permissions.cjs");
+const { EFFORTS, TIERS } = require("../agentlas-workload-routing.cjs");
+const { projectCwd } = require("../project/paths.cjs");
+const { ensureTerminalProjectForExecutionCli } = require("../project/state.cjs");
 
 function readStdin() {
   return new Promise((resolve) => {
@@ -30,11 +39,22 @@ function readStdin() {
 }
 
 function parseArgs(args) {
-  const out = { print: false, runtime: null, permission: null, rest: [] };
+  const out = {
+    print: false,
+    runtime: null,
+    model: null,
+    effort: null,
+    tier: null,
+    permission: null,
+    rest: [],
+  };
   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);
   }
@@ -49,6 +69,18 @@ async function runOnce(ctx, args) {
     ctx.err(`unknown --permission ${parsed.permission} (use: read | write | full)`);
     return 1;
   }
+  if (parsed.effort && !EFFORTS.includes(String(parsed.effort))) {
+    ctx.err(`unknown --effort ${parsed.effort} (use: ${EFFORTS.join(" | ")})`);
+    return 1;
+  }
+  if (parsed.tier && !TIERS.includes(String(parsed.tier))) {
+    ctx.err(`unknown --tier ${parsed.tier} (use: ${TIERS.join(" | ")})`);
+    return 1;
+  }
+  if (parsed.tier && !parsed.model) {
+    ctx.err("--tier requires --model: Terminal never guesses a provider model id from a cost tier");
+    return 1;
+  }
   const db = ctx.db();
 
   let agent = null;
@@ -70,7 +102,15 @@ async function runOnce(ctx, args) {
   // 기본 런타임을 먼저 확정한다 — 판정 러너(자동 라우팅)도 이 런타임을 쓴다.
   let runtime;
   try {
-    runtime = resolveRuntime({ db, prefs: ctx.prefs, explicit: parsed.runtime });
+    runtime = resolveRuntimeForAgent({
+      db,
+      prefs: ctx.prefs,
+      explicit: parsed.runtime,
+      model: parsed.model,
+      effort: parsed.effort,
+      role: "orchestrator",
+    });
+    if (parsed.tier) runtime.modelTier = parsed.tier;
   } catch (e) {
     ctx.err(String((e && e.message) || e));
     return 1;
@@ -103,21 +143,43 @@ async function runOnce(ctx, args) {
     if (choice && choice.note) ctx.err(ctx.uiInstance.c.dim(choice.note));
   }
 
-  // 에이전트가 확정된 뒤 에이전트별 런타임 오버라이드를 얹는다(명시 --runtime이 항상 우선).
-  if (!parsed.runtime && agent && agent.id) {
+  // 에이전트가 확정된 뒤 에이전트별 오버라이드를 포함한 전체 사다리를 다시 해석한다.
+  // 명시 runtime/model/effort 핀은 항상 최상단이라 에이전트 기본값보다 우선한다.
+  if (agent && agent.id) {
     try {
-      const layered = resolveRuntimeForAgent({ db, prefs: ctx.prefs, explicit: null, agentId: agent.id });
+      const layered = resolveRuntimeForAgent({
+        db,
+        prefs: ctx.prefs,
+        explicit: parsed.runtime,
+        model: parsed.model,
+        effort: parsed.effort,
+        role: "orchestrator",
+        agentId: agent.id,
+      });
       if (layered.unavailableOverride) ctx.err(ctx.uiInstance.c.dim(unavailableOverrideNote(layered, ctx.lang)));
+      if (layered.unavailableRoleSelection) ctx.err(ctx.uiInstance.c.dim(unavailableRoleNote(layered, ctx.lang)));
+      if (parsed.tier) layered.modelTier = parsed.tier;
       runtime = layered;
-    } catch { /* 오버라이드 층 실패 → 이미 확정된 기본 런타임 유지 */ }
+    } catch (e) {
+      ctx.err(String((e && e.message) || e));
+      return 1;
+    }
   }
 
+  const permission = permissions.normalize(parsed.permission || (ctx.prefs && ctx.prefs.permission) || "write");
+  const cwd = projectCwd();
+  try {
+    ensureTerminalProjectForExecutionCli(db, cwd, permission, "terminal-run");
+  } catch (e) {
+    ctx.err(String((e && e.message) || e));
+    return 1;
+  }
   const orch = new Orchestrator({ db, lang: ctx.lang });
   const session = orch.spawn({
     agent,
     runtime,
-    permission: permissions.normalize(parsed.permission || (ctx.prefs && ctx.prefs.permission) || "write"),
-    cwd: process.cwd(),
+    permission,
+    cwd,
     title: prompt.slice(0, 60),
   });
 
@@ -125,7 +187,9 @@ async function runOnce(ctx, args) {
   if (!parsed.print) {
     renderer = new Renderer(ctx.uiInstance);
     renderer.attach(session, { replay: false });
-    ctx.err(ctx.uiInstance.c.dim(`${agent.slug} · ${runtime.kind}`));
+    ctx.err(ctx.uiInstance.c.dim(
+      `${agent.slug} · ${runtime.kind}${runtime.model ? ` · ${runtime.model}` : ""}${runtime.effort ? ` · ${runtime.effort}` : ""}`,
+    ));
   }
 
   const res = await session.send(prompt);

package/engine/commands/setup.cjs

@@ -10,20 +10,20 @@ const { userDataDir } = require("../core/paths.cjs");
 const { RUNTIME_BIN, whichSync } = require("../runtimes/detect.cjs");
 
 async function runWizard(ctx, rl) {
-  const result = await runOnboard({
+  // 저장을 마법사 "밖"에서 하면 이미 "완료" 문구가 찍힌 뒤다. 저장 함수를 넘겨
+  // 성공 문구보다 먼저 쓰게 하고, updatePrefs가 던지는 실패를 그대로 올려보낸다
+  // (예전엔 반환값을 버려서 잠금 경합·읽기전용 디렉터리에서도 exit 0으로 거짓말).
+  return runOnboard({
     ui: ctx.uiInstance,
     rl,
     helpers: { RUNTIME_BIN, which: whichSync },
-  });
-  if (result && result.onboarded) {
-    updatePrefs(userDataDir(), {
+    persist: (choices) => updatePrefs(userDataDir(), {
       onboarded: true,
-      ...(result.lang ? { language: result.lang } : {}),
-      ...(result.runtime ? { runtime: result.runtime } : {}),
-      ...(result.permission ? { permission: result.permission } : {}),
-    });
-  }
-  return result;
+      ...(choices.lang ? { language: choices.lang } : {}),
+      ...(choices.runtime ? { runtime: choices.runtime } : {}),
+      ...(choices.permission ? { permission: choices.permission } : {}),
+    }),
+  });
 }
 
 async function run(ctx) {
@@ -36,7 +36,8 @@ async function run(ctx) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   try {
     const result = await runWizard(ctx, rl);
-    return result && result.onboarded ? 0 : 1;
+    // 저장까지 성공해야 0 — 설정이 디스크에 없으면 사용자에겐 아무것도 안 한 것과 같다.
+    return result && result.onboarded && result.saved ? 0 : 1;
   } finally {
     rl.close();
   }

package/engine/commands/storm.cjs

@@ -10,16 +10,12 @@
  * stormbreaker-core-harness-unavailable 로 멈춘다 — 하네스의 로컬 모조 실행 금지.
  * 런타임 부재는 resolveRuntime의 code="no_runtime" throw가 그대로 전파돼 exit 1.
  *
- * projectPath 에 대한 정직한 메모: v1은 ensureTerminalProjectForExecutionCli(db,
- * cwd, permission, "terminal-storm")로 프로젝트 상태 머신을 돌려 활성 프로젝트
- * 경로를 만들었다. 그 프로젝트-상태 기계는 아직 v2로 포팅되지 않았다. storm/swarm 이
- * projectPath 를 쓰는 곳은 buildChildEnv 의 프로젝트 dotenv 스코핑뿐이고 부재 시
- * fail-closed 의존이 없다 — 그래서 여기서는 cwd 를 projectPath 로 넘긴다
- * (commands/workforce.cjs 와 동일한 결정·동일한 근거). 프로젝트-상태 모듈이 v2에
- * 착륙하면 이 자리를 그 결과로 교체한다.
+ * Write-capable first contact now runs the canonical Core project bootstrap
+ * for the exact current folder. Read-only execution remains passive.
  */
 const { buildStormDeps } = require("../storm/deps.cjs");
 const { projectCwd } = require("../workforce/capture.cjs");
+const { ensureTerminalProjectForExecutionCli } = require("../project/state.cjs");
 
 function assertPermissionFlag(value) {
   if (value && !["read", "write", "full"].includes(String(value))) {
@@ -62,11 +58,11 @@ async function run(ctx, args) {
   const db = ctx.db();
   const cwd = projectCwd();
   const permission = resolvePermission(ctx);
+  const projectPath = ensureTerminalProjectForExecutionCli(db, cwd, permission, "terminal-storm") || cwd;
   const storm = require("../storm/storm.cjs").create(buildStormDeps(ctx));
   const r = await storm.cmdStorm(db, rest, runtimeOverride, {
     cwd,
-    // v1 ensureTerminalProjectForExecutionCli 미포팅 — 위 파일 머리 주석 참조.
-    projectPath: cwd,
+    projectPath,
     permission,
   });
   return r && r.ok ? 0 : 1;

package/engine/commands/swarm.cjs

@@ -11,11 +11,11 @@
  * agentlas-workload-routing 이 검증만 하고, 거부 시 fail-closed 다.
  * 런타임 부재는 resolveRuntime의 code="no_runtime" throw가 그대로 전파돼 exit 1.
  *
- * projectPath: v1 ensureTerminalProjectForExecutionCli 미포팅 —
- * commands/storm.cjs 파일 머리 주석과 동일한 결정·동일한 근거로 cwd 를 넘긴다.
+ * Write-capable first contact bootstraps the exact current project through Core.
  */
 const { buildStormDeps } = require("../storm/deps.cjs");
 const { projectCwd } = require("../workforce/capture.cjs");
+const { ensureTerminalProjectForExecutionCli } = require("../project/state.cjs");
 
 function assertPermissionFlag(value) {
   if (value && !["read", "write", "full"].includes(String(value))) {
@@ -62,11 +62,11 @@ async function run(ctx, args) {
   const db = ctx.db();
   const cwd = projectCwd();
   const permission = resolvePermission(ctx);
+  const projectPath = ensureTerminalProjectForExecutionCli(db, cwd, permission, "terminal-swarm") || cwd;
   const swarm = require("../storm/swarm.cjs").create(buildStormDeps(ctx));
   const r = await swarm.cmdSwarm(db, rest, runtimeOverride, {
     cwd,
-    // v1 ensureTerminalProjectForExecutionCli 미포팅 — commands/storm.cjs 주석 참조.
-    projectPath: cwd,
+    projectPath,
     permission,
   });
   return r && r.ok ? 0 : 1;

package/engine/commands/uninstall.cjs

@@ -11,7 +11,8 @@ const { runWriteTransaction } = require("../agentlas-sqlite-policy.cjs");
 
 function run(ctx, args) {
   const ko = ctx.lang === "ko";
-  const token = args[0];
+  // 동의 플래그를 슬러그보다 앞에 써도 되도록 첫 번째 비플래그 인자를 대상으로 본다.
+  const token = args.find((a) => !String(a).startsWith("-"));
   if (!token) {
     ctx.err(ko ? "사용법: agentlas uninstall <agent>" : "Usage: agentlas uninstall <agent>");
     return 1;
@@ -45,6 +46,35 @@ function run(ctx, args) {
     }
   }
 
+  /*
+   * 대화 파괴 게이트 — bootstrap-schema.sql:50 chats.agent_id 는
+   * `ON DELETE CASCADE`, :61 chat_messages.chat_id 도 CASCADE 다. 즉
+   * installed_agents 행 하나를 지우면 그 에이전트의 모든 챗과 메시지가 같이
+   * 사라진다(데스크탑과 공유하는 SQLite라 데스크탑 쪽 이력도 함께 증발한다).
+   * 그런데 이 명령은 그 사실을 한 줄도 알리지 않고 `✓ 제거됨`만 찍었다 —
+   * 되돌릴 수 없는 삭제가 무고지·무확인으로 일어나던 자리다.
+   * 그래서 지우기 "전에" 파급 건수를 세고, 대화가 있으면 명시적 동의
+   * (--yes/-y/--force) 없이는 아무것도 지우지 않는다. 대화가 0건이면
+   * 파괴할 이력이 없으므로 종전대로 그냥 진행한다(불필요한 마찰 금지).
+   */
+  const consented = args.some((a) => a === "--yes" || a === "-y" || a === "--force");
+  let chatCount = 0;
+  let messageCount = 0;
+  if (ctx.tableExists(db, "chats")) {
+    chatCount = db.prepare("SELECT COUNT(*) AS n FROM chats WHERE agent_id=?").get(agent.id).n;
+    if (chatCount && ctx.tableExists(db, "chat_messages")) {
+      messageCount = db.prepare(
+        "SELECT COUNT(*) AS n FROM chat_messages WHERE chat_id IN (SELECT id FROM chats WHERE agent_id=?)",
+      ).get(agent.id).n;
+    }
+  }
+  if (chatCount && !consented) {
+    ctx.err(ko
+      ? `"${agent.slug}" 제거는 대화 ${chatCount}개와 메시지 ${messageCount}개를 함께 영구 삭제합니다 (데스크탑 앱과 공유하는 DB이며 되돌릴 수 없습니다).\n계속하려면: agentlas uninstall ${agent.slug} --yes`
+      : `Uninstalling "${agent.slug}" will also permanently delete ${chatCount} chat(s) and ${messageCount} message(s) (shared with the Desktop app; this cannot be undone).\nRe-run to confirm: agentlas uninstall ${agent.slug} --yes`);
+    return 1;
+  }
+
   let deleted = false;
   runWriteTransaction(db, () => {
     deleted = db.prepare("DELETE FROM installed_agents WHERE id=?").run(agent.id).changes > 0;
@@ -58,7 +88,11 @@ function run(ctx, args) {
         saveRoutes(routes);
       }
     } catch { /* 라우트 정리는 best-effort */ }
-    ctx.out(`${ctx.ui.green("✓")} ${ko ? "제거됨" : "Uninstalled"}: ${agent.slug}`);
+    // 실제로 무엇이 사라졌는지 성공 줄에 남긴다 — 조용한 파괴 금지.
+    const cascade = chatCount
+      ? (ko ? ` (대화 ${chatCount}개 · 메시지 ${messageCount}개 삭제됨)` : ` (deleted ${chatCount} chat(s), ${messageCount} message(s))`)
+      : "";
+    ctx.out(`${ctx.ui.green("✓")} ${ko ? "제거됨" : "Uninstalled"}: ${agent.slug}${cascade}`);
     return 0;
   }
   ctx.err(ko ? "제거하지 못했습니다." : "Nothing was uninstalled.");

package/engine/commands/version.cjs

@@ -1,8 +1,37 @@
 "use strict";
+/*
+ * version — 터미널 버전과 함께 **지금 붙어 있는 Agentlas-OS Core** 를 보고한다.
+ *
+ * 왜 Core 도 같이 찍나 (2026-07-28):
+ *   터미널의 계약 표면(build/upload/workforce/context/…)은 Core 릴리스가 소유한다.
+ *   Core 는 스스로 갱신되고(agentlas_cloud/update.py), 셸은 그때그때 해석된 루트에
+ *   붙는다. 그런데 `version`·`--where`·`doctor` 어디에서도 Core 를 찍지 않아서,
+ *   사용자도 지원 담당도 **어떤 Core 위에서 돌고 있는지 알 방법이 없었다**.
+ *   "최신인데 안 맞는다" 류의 오진이 그 공백에서 나온다. 붙은 대상을 보여주는 것이
+ *   진단의 출발점이다.
+ *
+ * Core 가 없어도 실패하지 않는다 — 56개 명령은 Core 없이 동작한다. 없으면 없다고
+ * 정직하게 적는다(조용한 생략 금지).
+ */
 const { readVersion } = require("../agentlas-banner.cjs");
 
+function coreLine() {
+  try {
+    const core = require("../agentlas-core-harness.cjs");
+    const root = core.resolveCoreRuntimeRoot();
+    if (!root) return "agentlas-os  not attached (install: hephaestus update)";
+    const version = core.readCoreRuntimeVersion(root);
+    // 버전을 못 읽는 루트는 "낡음"이 아니라 "모름"이다. 두 상태를 구분해 적는다 —
+    // 모름을 그럴듯한 값으로 메꾸면 그 순간 진단이 거짓이 된다.
+    return `agentlas-os  ${version || "unknown version"}  (${root})`;
+  } catch (error) {
+    return `agentlas-os  unavailable (${(error && error.message) || error})`;
+  }
+}
+
 function run(ctx) {
   ctx.out(`agentlas ${readVersion()}`);
+  ctx.out(coreLine());
   return 0;
 }
 

package/engine/commands/workforce.cjs

@@ -11,17 +11,12 @@
  * parity().cmdHep(["hep-network", ...]) 호환 탈출구였는데, 그 parity 모듈이 아직
  * v2에 없으므로 정직 정지로 안내만 한다(가짜 성공 금지).
  *
- * projectPath 에 대한 정직한 메모: v1은 ensureTerminalProjectForExecutionCli(db,
- * cwd, permission, "terminal-workforce")로 프로젝트 상태 머신을 돌려 활성 프로젝트
- * 경로를 만들었다. 그 프로젝트-상태 기계(폴더 방문 기록/활성화 판정)는 아직 v2로
- * 포팅되지 않았다. cmdWorkforce 가 projectPath 를 쓰는 곳은 buildChildEnv 의
- * 프로젝트 dotenv 스코핑뿐이고(agentlas-workforce.cjs 1926행) 부재 시 fail-closed
- * 의존이 없음을 확인했다 — 그래서 여기서는 cwd 를 projectPath 로 넘긴다(같은 폴더
- * 의 .env/.env.local 이 비신뢰 소스로 한 번 더 스캔될 뿐, 권한이 넓어지지 않는다).
- * 프로젝트-상태 모듈이 v2에 착륙하면 이 자리를 그 결과로 교체한다.
+ * Write-capable first contact bootstraps the exact current project through the
+ * canonical Core merge-only boundary. Read-only inspection remains passive.
  */
 const { workforceRuntime } = require("../workforce/deps.cjs");
 const { projectCwd } = require("../workforce/capture.cjs");
+const { ensureTerminalProjectForExecutionCli } = require("../project/state.cjs");
 
 function resolvePermission(ctx) {
   // v1 resolveTerminalPermission 포팅: 저장된 `full` 은 세션 한정 계약이라
@@ -70,11 +65,16 @@ async function dispatch(ctx, command, args) {
       const db = ctx.db();
       const cwd = projectCwd();
       const permission = resolvePermission(ctx);
+      const projectPath = ensureTerminalProjectForExecutionCli(
+        db,
+        cwd,
+        permission,
+        `terminal-${command}`,
+      ) || cwd;
       const runtime = workforceRuntime({ lang: ctx.lang, out: ctx.out });
       const result = await runtime.cmdWorkforce(db, rest, runtimeOverride, {
         cwd,
-        // v1 ensureTerminalProjectForExecutionCli 미포팅 — 위 파일 머리 주석 참조.
-        projectPath: cwd,
+        projectPath,
         permission,
       });
       return result && result.ok ? 0 : 1;

package/engine/core/schema-ensure.cjs

@@ -0,0 +1,75 @@
+"use strict";
+/*
+ * core/schema-ensure — 공유 SQLite 에 대한 스키마 보정을 **커넥션당 한 번만** 한다.
+ *
+ * 왜 (2026-07-28 실측):
+ *   `agentlas.sqlite` 는 데스크탑 앱과 공유하는 파일이다(제품 계약, `core/paths.cjs`).
+ *   그런데 터미널이 **매 턴** 그 파일에 DDL 을 날리고 있었다 —
+ *     · `ALTER TABLE memory_entries ADD COLUMN context_json` (사본 3벌)
+ *     · `CREATE TABLE IF NOT EXISTS terminal_memory_*` 4개 + 인덱스 5개
+ *   전부 `IF NOT EXISTS`/조건부라 결과는 멱등이지만, **쓰기 락을 잡는 것은 매번**이다.
+ *   데스크탑이 마이그레이션 트랜잭션 중이면 15초 busy_timeout 을 소진하고, 호출부가
+ *   전부 빈 catch 라 그 실패가 조용히 사라진다.
+ *
+ *   스키마 소유자는 데스크탑이다(`core/db.cjs:7-9`). 터미널의 이 보정은 "앱보다 먼저
+ *   깔린 DB" 같은 경우를 위한 안전망이지 상시 작업이 아니다. 프로세스가 사는 동안
+ *   한 번이면 충분하다.
+ *
+ * 왜 커넥션당인가 (프로세스당이 아니라):
+ *   테스트와 일부 명령이 임시 DB 를 따로 연다. 프로세스 단위로 기억하면 두 번째
+ *   DB 가 보정을 건너뛰어 조용히 깨진다. WeakMap 이면 커넥션이 사라질 때 같이 사라진다.
+ */
+const applied = new WeakMap();
+
+/**
+ * `key` 작업을 이 커넥션에서 아직 안 했으면 실행한다.
+ * 실패는 삼키되 **기억하지 않는다** — 다음 호출이 다시 시도할 수 있어야 한다.
+ * (일시적 락 경합으로 실패한 것을 "완료"로 기억하면 스키마가 영구히 안 맞는다.)
+ */
+function ensureOnce(db, key, fn) {
+  if (!db) return false;
+  let done = applied.get(db);
+  if (!done) {
+    done = new Set();
+    applied.set(db, done);
+  }
+  if (done.has(key)) return true;
+  try {
+    fn(db);
+    done.add(key);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function tableExists(db, name) {
+  try {
+    return Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(name));
+  } catch {
+    return false;
+  }
+}
+
+function columnExists(db, table, column) {
+  try {
+    return db.prepare(`PRAGMA table_info(${table})`).all().some((row) => row.name === column);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `memory_entries.context_json` 보정. 이전에는 이 함수가 세 파일에 각각 복제돼 있었고
+ * (`sessions/prompt.cjs`, `project/memory-context.cjs`, `memory-cli/curate.cjs`)
+ * 그중 하나는 매 턴 호출됐다. 하나로 합치고 커넥션당 1회로 줄인다.
+ */
+function ensureMemoryContextColumn(db) {
+  return ensureOnce(db, "memory_entries.context_json", (conn) => {
+    if (tableExists(conn, "memory_entries") && !columnExists(conn, "memory_entries", "context_json")) {
+      conn.exec("ALTER TABLE memory_entries ADD COLUMN context_json TEXT NOT NULL DEFAULT '{}'");
+    }
+  });
+}
+
+module.exports = { ensureOnce, ensureMemoryContextColumn, tableExists, columnExists };

package/engine/experience/variant.cjs

@@ -139,6 +139,37 @@ function resolveVariantCandidates(options) {
   };
 }
 
+/*
+ * usage/설명은 사람 출력 전용이다 — JSON 결과(schemaVersion v1)와 decision 어휘는
+ * 손대지 않는다. README·`agentlas help`가 광고하는 `agentlas variant resolve`는
+ * 인자 없이 부르면 항상 decision=error 로 끝나는데, 그동안 사람에게 보인 건
+ * 내부 enum 한 줄(`error: EXACT_BASE_RELEASE_REQUIRED`) 뿐이라 필요한 플래그
+ * 이름이 소스 주석에만 존재했다. 그래서 (1) error 코드마다 사람이 읽고 바로
+ * 고칠 수 있는 사유 + usage 를 붙이고, (2) help 서브커맨드를 뚫는다.
+ */
+const VARIANT_USAGE_LINES = Object.freeze([
+  "usage: agentlas variant resolve [candidates.json] [--base-release <agent-release-id>]",
+  "                                [--prefer <variant-id>] [--no-base-only] [--json]",
+  "  --base-release <id>  required: the exact base agent release to resolve against.",
+  "                       May instead come from candidates.json's baseAgentReleaseId.",
+  "  candidates.json      variant candidates: a JSON array, or {baseAgentReleaseId, candidates[]}.",
+  "  --prefer <id>        preferred variant; picking another one reports decision=fallback.",
+  "  --no-base-only       fail instead of falling back to the base release with no Experience Pack.",
+  "  --json               emit the agentlas.terminal-variant-resolution.v1 document.",
+  "Local advisory preview only: it never authorizes execution, rental, or reputation.",
+]);
+
+const VARIANT_ERROR_HINTS = Object.freeze({
+  EXACT_BASE_RELEASE_REQUIRED:
+    "no base agent release was given — pass --base-release <agent-release-id>, or a candidates.json carrying baseAgentReleaseId.",
+  NO_ELIGIBLE_VARIANT_AND_NO_BASE_FALLBACK:
+    "no candidate survived the checks above and --no-base-only forbids the base-only fallback.",
+});
+
+function variantUsage() {
+  return VARIANT_USAGE_LINES.join("\n");
+}
+
 function renderVariantResolution(result) {
   const lines = [
     `VARIANT RESOLUTION: ${result.decision}`,
@@ -148,17 +179,29 @@ function renderVariantResolution(result) {
   if (result.decision === "selected") lines.push(`selected: ${result.selectedVariantId}`);
   else if (result.decision === "fallback") lines.push(`fallback selected: ${result.selectedVariantId}`);
   else if (result.decision === "base-only") lines.push(`base-only: ${result.baseAgentReleaseId} (no Experience Pack attached)`);
-  else lines.push(`error: ${result.code}`);
+  else {
+    lines.push(`error: ${result.code}`);
+    const hint = VARIANT_ERROR_HINTS[result.code];
+    if (hint) lines.push(hint);
+  }
   if (result.fallbackOrder.length) lines.push(`next fallbacks: ${result.fallbackOrder.join(", ")}`);
   for (const excluded of result.excluded) lines.push(`excluded only ${excluded.variantId}: ${excluded.reasons.join(", ")}`);
   lines.push("Required MCP shortages exclude only the affected variant; they never create an agent-wide shortage.");
+  // 실패했을 때만 usage를 붙인다 — 성공 출력은 v1과 바이트 동일하게 유지한다.
+  if (result.decision === "error") lines.push("", variantUsage());
   return lines.join("\n");
 }
 
 function cmdVariant(options) {
   const args = options.args || [];
   const sub = args[0] || "resolve";
-  if (sub !== "resolve") throw new Error(`unknown variant subcommand: ${sub} (resolve)`);
+  // help 탈출구: 상위 라우터가 -h/--help 를 "help" 로 정규화하지만, 직접 호출도
+  // 받도록 셋 다 인정한다. usage는 성공(exit 0)이지 알 수 없는 서브커맨드가 아니다.
+  if (sub === "help" || sub === "--help" || sub === "-h") {
+    (options.out || console.log)(variantUsage());
+    return null;
+  }
+  if (sub !== "resolve") throw new Error(`unknown variant subcommand: ${sub} (resolve|help)`);
   const flags = parseSimpleFlags(args.slice(1));
   let candidates = [];
   let baseAgentReleaseId = flags["base-release"] || null;
@@ -192,5 +235,6 @@ module.exports = {
   validateVariantCandidate,
   resolveVariantCandidates,
   renderVariantResolution,
+  variantUsage,
   cmdVariant,
 };

package/engine/firms/orchestrate.cjs

@@ -204,13 +204,15 @@ function turnText(res) {
  * 회사 1태스크 실행: PLAN → DELEGATE → SYNTHESIZE.
  * @param {object} p
  *   db, orch(Orchestrator), firm(firms 행), ceoAgent(rowToAgent 결과),
- *   task, runtime, permission, cwd, onEvent?({phase,...}),
+ *   task, runtime(orchestrator), workerRuntime?, resolveWorkerRuntime?(division),
+ *   permission, cwd, onEvent?({phase,...}),
  *   spawnImplFor?({kind:'ceo'|'division', role?}) — 계약 테스트 전용 fake spawn 주입,
  *   timeoutConfig? — 테스트 전용.
  * @returns {ok, text, chatId, plan:{text,delegations}, divisions:[{role,name,ok,text,chatId}]}
  */
 async function runFirmTurn(p) {
   const { db, orch, firm, ceoAgent, task, runtime, permission, cwd } = p;
+  const workerRuntime = p.workerRuntime || runtime;
   const onEvent = typeof p.onEvent === "function" ? p.onEvent : () => {};
   const parseDelegations = loadDelegateParser();
   const divisions = resolveDivisions(db, firm, ceoAgent);
@@ -269,15 +271,20 @@ async function runFirmTurn(p) {
   // kind='division' + parent_chat_id(CEO 챗)로 영속된다. 한 본부의 실패는 격리한다.
   onEvent({ phase: "delegate", targets: matched.map((m) => ({ role: m.node.role, name: m.node.name, brief: m.brief })) });
   const divisionResults = await parallelCap(matched, maxParallel(), async (m) => {
+    const divisionRuntime = typeof p.resolveWorkerRuntime === "function"
+      ? p.resolveWorkerRuntime(m.node)
+      : workerRuntime;
     const session = orch.spawn({
       agent: m.node.agent,
-      runtime,
+      runtime: divisionRuntime,
       permission,
       cwd,
       title: `division: ${m.node.role}`,
       parentKey: ceoSession.key,
       activate: false,
-      spawnImpl: p.spawnImplFor ? p.spawnImplFor({ kind: "division", role: m.node.role }) : undefined,
+      spawnImpl: p.spawnImplFor
+        ? p.spawnImplFor({ kind: "division", role: m.node.role, runtime: divisionRuntime })
+        : undefined,
       timeoutConfig: p.timeoutConfig,
     });
     // 본부 세션도 generic 자동 위임을 끈다 — 터미널 firm 은 아직 tier-3(전문가) 배선이

package/engine/hephaestus/runtime.cjs

@@ -40,6 +40,13 @@ const USAGE = Object.freeze({
   call: 'usage: agentlas call "<agent-slugs>" "<context>"',
   connect: "usage: agentlas connect [status|telegram|help]",
   hep: "usage: agentlas hep <subcommand> [args]",
+  // 소스 스코프를 지키는 스태핑 표면 3종. 이름이 곧 계약이라 usage 도 스코프를
+  // 문장으로 적는다 — 이전에는 별칭이 스코프를 버려 hep-cloud 가 자산 보관함
+  // usage 를, hep-hub 가 검색 목록을 뱉었다(2026-07-28 수리).
+  "hep-network": 'usage: agentlas hep-network "<request>"  # Local + owner Cloud + public Hub, federated by Core',
+  "hep-local": 'usage: agentlas hep-local "<request>"   # registered Local agents only',
+  "hep-cloud": 'usage: agentlas hep-cloud "<request>"   # owner Agent Cloud agents only',
+  "hep-hub": 'usage: agentlas hep-hub "<request>"     # public Agentlas Hub agents only',
   hephaestus: "usage: agentlas hephaestus <subcommand> [args]",
   journal: "usage: agentlas journal <status|verify|repair|gate> --run-id <id> | --journal <path>",
   "legacy-network": 'usage: agentlas legacy-network "<request>"',

package/engine/memory-cli/curate.cjs

@@ -31,13 +31,9 @@ function loadArch() {
   return _arch;
 }
 
-function ensureMemoryContextColumn(db) {
-  try {
-    if (tableExists(db, "memory_entries") && !columnExists(db, "memory_entries", "context_json")) {
-      db.exec("ALTER TABLE memory_entries ADD COLUMN context_json TEXT NOT NULL DEFAULT '{}'");
-    }
-  } catch { /* ignore */ }
-}
+// 사본 3벌을 하나로 합치고 커넥션당 1회로 줄였다 — 이 보정이 매 턴 공유 DB 에
+// 쓰기 락을 잡고 있었다(2026-07-28). 소유자는 데스크탑 스키마다.
+const { ensureMemoryContextColumn } = require("../core/schema-ensure.cjs");
 
 const SECRET_RE = [/\b(?:sk|pk|rk)-[A-Za-z0-9]{16,}/, /AKIA[0-9A-Z]{16}/, /ghp_[A-Za-z0-9]{20,}/, /xox[baprs]-[A-Za-z0-9-]{10,}/, /-----BEGIN [A-Z ]*PRIVATE KEY-----/, /\b(?:password|passwd|secret|api[_-]?key|access[_-]?token|bearer)\b\s*[:=]\s*\S+/i];
 

package/engine/project/memory-context.cjs

@@ -32,13 +32,9 @@ function sha(value) {
   return crypto.createHash("sha256").update(value).digest("hex");
 }
 
-function ensureMemoryContextColumn(db) {
-  try {
-    if (tableExists(db, "memory_entries") && !columnExists(db, "memory_entries", "context_json")) {
-      db.exec("ALTER TABLE memory_entries ADD COLUMN context_json TEXT NOT NULL DEFAULT '{}'");
-    }
-  } catch { /* ignore */ }
-}
+// 사본 3벌을 하나로 합치고 커넥션당 1회로 줄였다 — 이 보정이 매 턴 공유 DB 에
+// 쓰기 락을 잡고 있었다(2026-07-28). 소유자는 데스크탑 스키마다.
+const { ensureMemoryContextColumn } = require("../core/schema-ensure.cjs");
 
 function prefsLangCli() {
   try {