agentlas 1.0.12 → 1.0.15

package/engine/cloud-assets/cas.cjs

@@ -42,9 +42,14 @@ function cloudCasResponseError(response, label) {
   let message = `${label} failed with HTTP ${response.status}`;
   if (response.status === 412 && code === "cloud_agent_revision_conflict") {
     const current = body && body.current ? body.current : body && body.conflict && body.conflict.current;
+    // 서버가 알려준 사실만 사람 말로 전달한다. 내부 개념(precondition, base, 연결)은
+    // 사용자에게 아무 의미가 없다 — 기준은 "이 이름이 내 계정 것인가" 하나다.
     message = current
-      ? `다른 PC에서 이 Agent Cloud 자산이 변경되었습니다. 자동 덮어쓰기는 중단했습니다. \`agentlas cloud list\`로 최신 revision을 확인하고 \`agentlas cloud restore ${current.slug || "<slug>"}\`로 복원한 뒤 변경 사항을 병합하세요.`
-      : "이 Agent Cloud 자산은 다른 PC에서 삭제되었거나 다른 식별자로 다시 생성되었습니다. 자동 재생성은 중단했습니다. `agentlas cloud list`로 현재 상태를 확인하세요.";
+      ? `업로드하지 않았습니다. "${current.slug || "이 이름"}"의 서버 버전이 지금 보낸 것과 맞지 않습니다` +
+        `${current.updatedAt ? ` (서버 쪽 마지막 저장: ${current.updatedAt})` : ""}.\n` +
+        `  내 계정 자산이면: agentlas cloud restore ${current.slug || "<slug>"} 로 받아서 확인한 뒤 다시 저장하세요.\n` +
+        `  (서버 cloudId ${current.cloudId || "?"} · revision ${current.revision || "?"})`
+      : "업로드하지 않았습니다. 이 이름의 자산이 삭제됐거나 다른 계정 소유입니다. `agentlas cloud list`로 내 자산을 확인하세요.";
   } else if (response.status === 428 && code === "client_upgrade_required") {
     message = "No base revision is available to safely update the existing Cloud asset. The server revision will not be copied automatically. Check `agentlas cloud list`, restore with `agentlas cloud restore <slug>`, then save again.";
   } else if (response.status === 503 && code === "cloud_mutations_maintenance") {

package/engine/cloud-assets/commands.cjs

@@ -103,6 +103,7 @@ const CLOUD_HELP = [
   "  publish <path> [--dry-run] [--slug name]",
   "                                      explicitly publish to the public Agentlas Hub",
   "  package <path> [--json] [--visibility private-link|marketplace]",
+  "  --overwrite                         서버에 더 새 버전이 있어도 지금 폴더 내용으로 덮어쓰기",
   "                                      package only; defaults to private-save checks",
   "  list [--json]                       list packages in your private Agent Cloud",
   "  restore <slug> [--json]             restore an owned Cloud package on this machine",
@@ -241,6 +242,7 @@ async function runCloud(ctx, args) {
     slug: typeof flags.slug === "string" ? flags.slug : undefined,
     visibility,
     llmReview: Boolean(flags["llm-review"]),
+    overwriteRemote: Boolean(flags.overwrite),
     dryRun,
   });
   if (flags.json) {

package/engine/cloud-assets/package.cjs

@@ -33,10 +33,12 @@ const {
   cloudPortablePathConflict,
   cloudPackageHashVersion,
   cloudHashPackage,
+  normalizeCloudAssetDescriptor,
 } = require("../hub/install.cjs");
 const { SECRET_PATTERNS } = require("../agentlas-secret-patterns.cjs");
 const { userDataDir } = require("../core/paths.cjs");
 const state = require("./state.cjs");
+const { cargoSearchAgents } = require("./cargo.cjs");
 const cas = require("./cas.cjs");
 
 const CLOUD_TEXT_EXTS = new Set([".cfg", ".cjs", ".conf", ".config", ".css", ".csv", ".env", ".html", ".ini", ".js", ".json", ".jsonl", ".md", ".mjs", ".properties", ".ps1", ".psd1", ".psm1", ".py", ".sh", ".toml", ".ts", ".tsx", ".txt", ".xml", ".yaml", ".yml"]);
@@ -748,6 +750,28 @@ function cloudSecuritySummary(findings) {
 
 // ── 메인: 패키지(+등록) ──
 
+/**
+ * 이 계정이 소유한 자산의 현재 리비전을 서버에서 조회한다.
+ * 로컬 관측 기록이 전혀 없는 새 PC/새 클론에서 갱신을 가능하게 하는 유일한 경로다.
+ * 소유자 세션이 없거나 자산이 없으면 null — 조용한 폴백은 만들지 않는다.
+ */
+async function lookupOwnedCloudDescriptor(slug, scope) {
+  let response;
+  try {
+    response = await cargoSearchAgents({ q: slug, limit: 20 });
+  } catch {
+    return null;
+  }
+  const rows = Array.isArray(response && response.results) ? response.results : [];
+  const row = rows.find((item) => item && item.slug === slug && item.scope === scope);
+  if (!row) return null;
+  try {
+    return normalizeCloudAssetDescriptor(row, "owner cloud search result");
+  } catch {
+    return null;
+  }
+}
+
 async function packageCloudAgent(db, root, opts = {}) {
   const requestedRoot = path.resolve(root);
   let st;
@@ -796,7 +820,7 @@ async function packageCloudAgent(db, root, opts = {}) {
   const name = cloudReadName(snapshot, path.basename(rootPath));
   const slug = cloudSlug(opts.slug || cloudReadStableSlug(snapshot) || name || path.basename(rootPath));
   const scope = cas.cloudScopeForVisibility(visibility);
-  const baseDescriptor = state.cloudBaseDescriptorForSource(scan.localPackageMarker, rootPath, slug, scope);
+  let baseDescriptor = state.cloudBaseDescriptorForSource(scan.localPackageMarker, rootPath, slug, scope);
   const packageHashVersion = CLOUD_PACKAGE_HASH_V2;
   const packageHash = cloudHashPackage(scan.included, packageHashVersion);
   const manifest = {
@@ -844,6 +868,30 @@ async function packageCloudAgent(db, root, opts = {}) {
   let registration = null;
   let status = blocked ? "blocked" : opts.dryRun ? "dry-run" : "ready";
   if (!blocked && !opts.dryRun) {
+    // 자산의 정체성은 (로그인 계정, slug)다 — 어느 폴더에서 올리는지는 중요하지 않다.
+    // 쓰기 전에 서버가 들고 있는 내 자산의 현재 버전을 조회해서:
+    //   · 이 폴더에 기록이 없으면(새 PC, 새 클론) 그 버전을 기준으로 업데이트한다.
+    //   · 이 폴더 기록이 서버보다 오래됐으면(다른 곳에서 먼저 올림) 덮어쓰기 전에 멈춘다.
+    // 이것은 412 뒤의 자동 재시도가 아니라 쓰기 전 refresh다. 등록 자체는 여전히
+    // 조회한 정확한 리비전에 대한 조건부 쓰기(If-Match)라 경합은 서버가 막는다.
+    const remote = await lookupOwnedCloudDescriptor(slug, scope);
+    if (!baseDescriptor && remote) {
+      baseDescriptor = state.rememberCloudAssetDescriptor(remote, { sourceRoot: rootPath });
+    } else if (baseDescriptor && remote && baseDescriptor.revision !== remote.revision) {
+      if (opts.overwriteRemote) {
+        baseDescriptor = state.rememberCloudAssetDescriptor(remote, { sourceRoot: rootPath });
+      } else {
+        const error = new Error(
+          `업로드하지 않았습니다. "${slug}"에 더 새 버전이 있습니다 (${remote.updatedAt || "시각 미상"}에 다른 곳에서 저장됨).\n` +
+          `  지금 폴더 내용으로 그 버전을 덮어쓰려면: --overwrite\n` +
+          `  먼저 그 버전을 받아서 비교하려면:      agentlas cloud restore ${slug}\n` +
+          `  (서버 cloudId ${remote.cloudId} · revision ${remote.revision})`,
+        );
+        error.code = "cloud_agent_revision_conflict";
+        error.current = remote;
+        throw error;
+      }
+    }
     registration = await cas.registerCloudAgent(manifest, bundlePath, review, visibility, { baseDescriptor });
     let descriptor;
     try {

package/engine/cloud-assets/state.cjs

@@ -174,6 +174,39 @@ function cloudBaseDescriptorFromMarker(marker, slug, scope) {
  * 톰스톤에 걸린 마커 디스크립터는 무시(삭제 후 재저장은 새 생성이어야 한다).
  * 둘 다 있으면 같은 cloudId에서 더 최신 관측을 채택한다.
  */
+/**
+ * 이 slug/scope의 관측된 리비전은 있는데, 이 소스 루트에는 아직 연결되지 않은
+ * 경우를 돌려준다.
+ *
+ * 이 구분이 없으면 base 조회가 null을 돌려주고, 호출부는 그것을 "새 자산"으로
+ * 읽어 create precondition을 보낸다. 서버에는 자산이 멀쩡히 존재하므로 412로
+ * 거절되고, 사용자는 "다른 PC에서 변경됨 / restore 하세요"라는 엉뚱한 안내를
+ * 받는다. restore는 디스크립터를 설치 경로에 묶으므로 소스 루트에서 발행하는
+ * 한 영원히 해소되지 않는다. 모름을 그럴듯한 값으로 메꾸지 않기 위한 분기다.
+ */
+function cloudUnboundDescriptorForSource(rootPath, slug, scope) {
+  const state = readCloudAssetState();
+  const entry = state.assets[`${scope}:${slug}`];
+  if (!entry) return null;
+  return entry.sourceRoots.includes(path.resolve(rootPath)) ? null : entry.descriptor;
+}
+
+/** 이 소스 루트를 이미 관측된 클라우드 자산에 명시적으로 연결한다. */
+function bindCloudAssetSourceRoot(rootPath, slug, scope) {
+  const state = readCloudAssetState();
+  const key = `${scope}:${slug}`;
+  const entry = state.assets[key];
+  if (!entry) throw new Error(`No observed Cloud revision for ${key} to bind.`);
+  const normalizedRoot = path.resolve(rootPath);
+  const roots = [...new Set([...entry.sourceRoots, normalizedRoot])].slice(0, 32);
+  state.assets[key] = { descriptor: entry.descriptor, sourceRoots: roots };
+  state.deletedBases = state.deletedBases.filter(
+    (item) => !(item.rootPath === normalizedRoot && item.slug === slug && item.scope === scope),
+  );
+  writeCloudAssetState(state);
+  return entry.descriptor;
+}
+
 function cloudBaseDescriptorForSource(marker, rootPath, slug, scope) {
   const state = readCloudAssetState();
   const normalizedRoot = path.resolve(rootPath);
@@ -263,6 +296,8 @@ module.exports = {
   cloudMarkerDescriptors,
   cloudBaseDescriptorFromMarker,
   cloudBaseDescriptorForSource,
+  cloudUnboundDescriptorForSource,
+  bindCloudAssetSourceRoot,
   writeCloudSourceMarker,
   readCloudSourceMarker,
 };

package/engine/commands/automation.cjs

@@ -92,6 +92,14 @@ async function run(ctx, args) {
       targetId = f.id;
       targetLabel = f.name;
     }
+    // 잘못된 IANA 존이면 nextCronRun 이 cron 파싱 실패와 똑같이 null 을 돌려준다.
+    // 그대로 두면 멀쩡한 cron 을 범인으로 지목해서, 사용자가 cron 만 계속 고쳐 쓰며
+    // 매번 같은 실패를 본다. 존을 먼저 검증해 틀린 필드를 정확히 지목한다.
+    if (flags.tz && !schedule.isValidTimezone(flags.tz)) {
+      return fail(ko
+        ? `타임존을 해석하지 못했습니다: "${flags.tz}" (IANA 형식이 필요합니다 — 예: Asia/Seoul, UTC, America/New_York)`
+        : `Could not parse timezone: "${flags.tz}" (needs IANA format — e.g. Asia/Seoul, UTC, America/New_York)`);
+    }
     const next = schedule.nextCronRun(flags.cron, new Date(), flags.tz || null);
     if (!next) {
       return fail(ko

package/engine/commands/chats.cjs

@@ -20,8 +20,13 @@ function run(ctx, args) {
   }
   for (const r of rows) {
     const when = String(r.updated_at || "").replace("T", " ").slice(0, 16);
-    ctx.out(`  ${ctx.ui.dim(when)}  ${ctx.ui.accent((r.agent_slug || "?").padEnd(20))} ${r.title}`);
+    // id 앞 8자를 먼저 찍는다 — `open <id 앞부분>`이 유일한 재개 경로인데
+    // 목록에 id가 없으면 SQLite를 직접 열지 않는 한 재개가 불가능했다.
+    // 8자는 open.cjs의 모호성 안내(id.slice(0,8))와 같은 규약.
+    const id = String(r.id || "").slice(0, 8);
+    ctx.out(`  ${ctx.ui.bold(id)}  ${ctx.ui.dim(when)}  ${ctx.ui.accent((r.agent_slug || "?").padEnd(20))} ${r.title}`);
   }
+  ctx.out(ctx.ui.dim(ctx.lang === "en" ? "  resume: agentlas open <id>" : "  재개: agentlas open <id>"));
   return 0;
 }
 

package/engine/commands/firm.cjs

@@ -73,6 +73,13 @@ async function run(ctx, args) {
     const { EFFORTS, TIERS } = require("../agentlas-workload-routing.cjs");
     const { Orchestrator } = require("../sessions/orchestrator.cjs");
     const permissions = require("../agentlas-permissions.cjs");
+    // 플래그 검증은 CEO 계획 턴을 부르기 전에. normalize는 모르는 값을 read로 fail-closed
+    // 강등하는데, firm은 그 권한을 CEO·본부 전 세션·종합 턴까지 그대로 물려주므로 조용히
+    // 강등하면 full을 요청한 사용자가 쓰기 차단된 채 3-tier 전체를 돌린 줄 모른다 (run.cjs 동일 가드).
+    if (flags.permission && !permissions.LEVELS.includes(String(flags.permission))) {
+      ctx.err(`unknown --permission ${flags.permission} (use: ${permissions.LEVELS.join(" | ")})`);
+      return 1;
+    }
     if (flags.effort && !EFFORTS.includes(String(flags.effort))) {
       ctx.err(`unknown --effort ${flags.effort} (use: ${EFFORTS.join(" | ")})`);
       return 1;

package/engine/commands/help.cjs

@@ -22,12 +22,13 @@ AGENTS & HUB
   import <path> · cd · native prepare  local folder agents
   list                     installed agents/companies + orchestrator/worker runtimes
   experience <sub>         portable Experience: list|inspect|validate|save|publish|status|export|unpublish
-  variant resolve          local variant selection
+  variant resolve --base-release <id>   local variant selection (variant help)
 
 EXECUTE
   storm <goal>             Goal+UltraCode harness: plan → allocate → execute → verify  [--research]
   swarm <goal>             emergent agent swarm  [--parallel N]
   workforce | network <request>   Agent Workforce Ontology route
+  hep-local | hep-cloud | hep-hub "<request>"   same, restricted to one source scope
   call "a,b" "<ctx>" · browser · route "<req>" [--json] · research <sub>
 
 KNOWLEDGE
@@ -65,4 +66,24 @@ function run(ctx) {
   return 0;
 }
 
-module.exports = { run, HELP };
+function runForCommand(ctx, command) {
+  const name = String(command || "").trim();
+  const rows = HELP.split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line && !line.endsWith(":"))
+    .filter((line) => {
+      const commandColumn = line.split(/\s{2,}/, 1)[0];
+      return commandColumn
+        .split(/\s*·\s*|\s*\|\s*/)
+        .some((entry) => entry === name || entry.startsWith(`${name} `));
+    });
+  ctx.out(`Usage: agentlas ${name} [options]`);
+  if (rows.length > 0) {
+    for (const row of rows) ctx.out(`  ${row}`);
+  } else {
+    ctx.out(`  See "agentlas help" for the full command list.`);
+  }
+  return 0;
+}
+
+module.exports = { run, runForCommand, HELP };

package/engine/commands/hep-cloud.cjs

@@ -0,0 +1,31 @@
+"use strict";
+/*
+ * hep-cloud — 로그인한 오너의 Agent Cloud 에이전트만으로 임시 태스크포스 편성.
+ *
+ * WHY 이 파일이 따로 있는가 (2026-07-28 수리):
+ *   COMMAND_ALIASES 가 `hep-cloud → cloud` 로 접혀 있었다. `cloud` 는 이름만 같은
+ *   전혀 다른 명령 — 클라우드 자산 보관함(save|publish|package|list|restore|
+ *   install|delete|field-test)이다. 그래서 `agentlas hep-cloud "<과제>"` 는
+ *   과제를 서브커맨드로 읽고 `usage: agentlas cloud <save|…>` 를 뱉으며 exit 1 —
+ *   hep-cloud 를 한 글자도 언급하지 않는 에러라 사용자에게 다음 수가 없었다.
+ *   스코프(오너 Cloud 한정)를 실제로 지키는 표면은 Hephaestus 네이티브 런타임
+ *   (`hephaestus hep-cloud`)뿐이므로 build/call/legacy-network 와 동일한
+ *   패스스루 계약으로 그쪽에 넘긴다. 자산 보관함은 계속 `agentlas cloud …` 다.
+ *
+ * v1 인자 가드 그대로: help 토큰 → usage 0, 무인자 → usage 실패 exit 1.
+ */
+const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
+
+async function run(ctx, args) {
+  if (args.some(isHelpToken)) {
+    ctx.out(usageFor("hep-cloud", ctx.lang));
+    return 0;
+  }
+  if (!args.length) {
+    ctx.err("✖ " + usageFor("hep-cloud", ctx.lang));
+    return 1;
+  }
+  return create(ctx).cmdHep(["hep-cloud", ...args]);
+}
+
+module.exports = { run };

package/engine/commands/hep-hub.cjs

@@ -0,0 +1,30 @@
+"use strict";
+/*
+ * hep-hub — 공개 Agentlas Hub 에이전트만으로 임시 태스크포스 편성.
+ *
+ * WHY 이 파일이 따로 있는가 (2026-07-28 수리):
+ *   COMMAND_ALIASES 가 `hep-hub → search` 로 접혀 있었다. search 는 스태핑이 아니라
+ *   마켓플레이스 디렉터리 나열이고(그마저 Cloud+Hub 혼합 표면이다), 실행은 하지
+ *   않는다. 그래서 `agentlas hep-hub "<과제>"` 는 과제를 검색어로 읽고 슬러그
+ *   목록만 찍은 뒤 exit 0 — 아무것도 실행하지 않고 성공한 척했다(가짜 성공 금지).
+ *   공개 Hub 한정 스태핑을 실제로 수행하는 표면은 Hephaestus 네이티브 런타임
+ *   (`hephaestus hep-hub`)이므로 그쪽에 그대로 넘긴다. 후보만 보고 싶으면
+ *   기존 `agentlas search`(=hep-search)가 그대로 남아 있다.
+ *
+ * v1 인자 가드 그대로: help 토큰 → usage 0, 무인자 → usage 실패 exit 1.
+ */
+const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
+
+async function run(ctx, args) {
+  if (args.some(isHelpToken)) {
+    ctx.out(usageFor("hep-hub", ctx.lang));
+    return 0;
+  }
+  if (!args.length) {
+    ctx.err("✖ " + usageFor("hep-hub", ctx.lang));
+    return 1;
+  }
+  return create(ctx).cmdHep(["hep-hub", ...args]);
+}
+
+module.exports = { run };

package/engine/commands/hep-local.cjs

@@ -0,0 +1,32 @@
+"use strict";
+/*
+ * hep-local — 이 머신에 등록된 Local 에이전트만으로 임시 태스크포스 편성.
+ *
+ * WHY 이 파일이 따로 있는가 (2026-07-28 수리):
+ *   COMMAND_ALIASES 가 `hep-local → workforce` 로 접혀 있었다. 터미널 workforce 는
+ *   공개 Hub 메뉴로 스태핑하는 Agent Workforce Ontology 경로이고(엔드포인트:
+ *   AGENTLAS_MCP_BASE_URL, search_candidates 스키마에 sourceScope 자체가 없음),
+ *   cmdWorkforce 는 스코프 플래그를 받지 않는다. 즉 "등록된 로컬만" 이라고
+ *   문서화된 명령이 조용히 Local+Cloud+공개 Hub 전체로 넓혀 실행됐다 —
+ *   사용자가 의도하지 않은 Hub 크레딧 소모까지 포함해서. 스코프는 이름의 전부다.
+ *   스코프를 지킬 수 있는 표면은 Hephaestus 네이티브 런타임(`hephaestus hep-local`)
+ *   뿐이므로, build/call/legacy-network 와 동일한 패스스루 계약으로 그쪽에 넘긴다.
+ *
+ * v1 인자 가드 그대로: help 토큰 → usage 0, 무인자 → usage 실패 exit 1
+ * (요청 문자열 없는 호출이 자연어 라우팅으로 새는 것 방지).
+ */
+const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
+
+async function run(ctx, args) {
+  if (args.some(isHelpToken)) {
+    ctx.out(usageFor("hep-local", ctx.lang));
+    return 0;
+  }
+  if (!args.length) {
+    ctx.err("✖ " + usageFor("hep-local", ctx.lang));
+    return 1;
+  }
+  return create(ctx).cmdHep(["hep-local", ...args]);
+}
+
+module.exports = { run };

package/engine/commands/hep-network.cjs

@@ -0,0 +1,43 @@
+"use strict";
+/*
+ * hep-network — 등록된 Local + 오너 Cloud + 공개 Hub 를 연합해 임시 태스크포스 편성.
+ *
+ * WHY 이 파일이 따로 있는가 (2026-07-28 수리):
+ *   COMMAND_ALIASES 가 `hep-network → workforce` 로 접혀 있었다. hep-local/hep-cloud/
+ *   hep-hub 와 정확히 같은 결함이다 — 별칭은 이름만 바꿔주고 스코프는 어디에도
+ *   전달하지 않는다. 터미널 workforce(cmdWorkforce)는 callHubTool 로
+ *   AGENTLAS_MCP_BASE_URL(기본 https://agentlas.cloud/api/mcp/v1)을 직접 치고
+ *   `{workOrder}` 만 보낸다(engine/agentlas-workforce.cjs:3043). 그 서버는
+ *   sourceScope 가 없으면 "hub" 로 기본값을 잡는다
+ *   (agentlas/AgentsAtlas/app/src/lib/mcp/workforce.ts:228). 결과:
+ *
+ *     - 로컬 에이전트와 오너 Cloud 에이전트는 후보 집합에 들어간 적이 없다.
+ *     - 그런데 영수증의 로스터 핀은 전부 source:"hub" 로 기록된다
+ *       (engine/workforce/deps.cjs). "네트워크 전량을 봤다" 로 읽힌다.
+ *
+ *   연합(federation)은 Core 가 소유한다: 세 소스 메뉴를 각각 받아 출처·계보를
+ *   증명하고 하나의 CandidateSet 으로 합친 뒤, 선택은 호스트 LLM 이 한다. 터미널이
+ *   Hub 를 직접 치는 경로에는 그 계층이 통째로 없다. 그래서 build/call/hep-local
+ *   과 동일한 패스스루 계약으로 Hephaestus 네이티브 표면에 넘긴다.
+ *
+ *   `agentlas workforce` 자체는 남겨둔다 — 공개 Hub 스태핑을 그 이름으로 명시해
+ *   부르는 것은 정직한 사용이다. 이름이 소스 스코프를 약속하는 hep-* 만 옮긴다.
+ *
+ * v1 인자 가드 그대로: help 토큰 → usage 0, 무인자 → usage 실패 exit 1
+ * (요청 문자열 없는 호출이 자연어 라우팅으로 새는 것 방지).
+ */
+const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
+
+async function run(ctx, args) {
+  if (args.some(isHelpToken)) {
+    ctx.out(usageFor("hep-network", ctx.lang));
+    return 0;
+  }
+  if (!args.length) {
+    ctx.err("✖ " + usageFor("hep-network", ctx.lang));
+    return 1;
+  }
+  return create(ctx).cmdHep(["hep-network", ...args]);
+}
+
+module.exports = { run };

package/engine/commands/index.cjs

@@ -47,6 +47,12 @@ const COMMANDS = {
   evolve: () => require("./evolve.cjs"),
   variant: () => require("./variant.cjs"),
   hep: () => require("./hep.cjs"),
+  // 소스 스코프 스태핑 3종은 1급 명령이다 — 별칭으로 접으면 스코프가 사라진다.
+  // (아래 COMMAND_ALIASES 주석의 2026-07-28 수리 참조.)
+  "hep-network": () => require("./hep-network.cjs"),
+  "hep-local": () => require("./hep-local.cjs"),
+  "hep-cloud": () => require("./hep-cloud.cjs"),
+  "hep-hub": () => require("./hep-hub.cjs"),
   build: () => require("./build.cjs"),
   connect: () => require("./connect.cjs"),
   call: () => require("./call.cjs"),
@@ -106,10 +112,25 @@ const GUARDED_NO_ARG = new Set(["search", "install", "upload"]);
 // 플랫폼 간 이름 통일(오너 결정 2026-07-27): 클로드코드/코덱스에서 부르는 hep-*
 // 스킬명과 터미널 명령이 서로 다르면 사용자가 어느 표면에 있는지에 따라 이름을
 // 바꿔 써야 한다. 같은 기능은 어디서든 같은 이름으로 부른다.
+//
+// 불변식(2026-07-28 수리): 별칭은 "같은 기능"에만 건다. 소스 스코프를 이름에
+// 달고 있는 hep-local / hep-cloud / hep-hub 는 여기 넣으면 안 된다 — 별칭은
+// 이름만 바꿔주고 스코프는 어디에도 전달되지 않기 때문이다. 실제로 그랬다:
+//   hep-cloud → cloud      : 자산 보관함 명령. 과제 문자열을 서브커맨드로 읽어
+//                            `usage: agentlas cloud <save|…>` + exit 1.
+//   hep-local → workforce  : cmdWorkforce 는 스코프 플래그를 받지 않는다(전량
+//                            공개 Hub 메뉴 스태핑). "로컬 전용"이 조용히 넓어짐.
+//   hep-hub   → search     : 디렉터리 나열만 하고 아무것도 실행하지 않음.
+// 세 명령은 스코프를 실제로 지키는 Hephaestus 네이티브 표면으로 가는 1급 명령
+// (COMMANDS 의 hep-local/hep-cloud/hep-hub)으로 승격했다.
+//
+// 같은 이유로 hep-network 도 별칭에서 뺐다(2026-07-28). 이름은 "Local + owner
+// Cloud + public Hub"인데 cmdWorkforce 는 스코프를 어디에도 싣지 않고
+// agentlas.cloud/api/mcp/v1 을 직접 친다. 그 서버는 sourceScope 가 없으면 "hub"
+// 로 기본값을 잡으므로(agentlas/.../lib/mcp/workforce.ts:228) 로컬·클라우드
+// 에이전트는 후보에 들어간 적이 없는데 결과는 네트워크 전량을 본 것처럼 남았다.
+// 연합은 Core 가 소유한다 — 네이티브 표면으로 넘긴다.
 const COMMAND_ALIASES = {
-  "hep-network": "workforce",
-  network: "workforce",
-  "hep-cloud": "cloud",
   "hep-build": "build",
   "hep-call": "call",
   "hep-search": "search",
@@ -117,8 +138,6 @@ const COMMAND_ALIASES = {
   "hep-storm": "storm",
   "hep-browser": "browser",
   "hep-connect": "connect",
-  "hep-local": "workforce",
-  "hep-hub": "search",
 };
 
 function resolveCommandName(cmd) {
@@ -139,8 +158,20 @@ function dispatch(ctx, argv) {
     return 1;
   }
 
-  if (DESKTOP_ONLY_SURFACES[cmd] && rest.length === 0) {
-    ctx.err(`${DESKTOP_ONLY_SURFACES[cmd]}\nIt was not run as a prompt — rerun with quotes if you meant a task: agentlas "${cmd} …"`);
+  /*
+   * 인자 유무와 무관하게 막는다. `rest.length === 0` 조건이 붙어 있던 동안은
+   * 단어 하나만 더 붙이면(`agentlas settings theme`, `marketplace browse`)
+   * 가드를 그냥 지나쳐 dispatch가 undefined를 반환했고, 엔진은 그걸 프롬프트로
+   * 보고 실제 에이전트를 띄웠다 — 제품이 "데스크탑 전용"이라고 선언한 화면
+   * 이름에 토큰이 청구되고 에이전트가 사용자 저장소에서 셸까지 돌렸다(실사용
+   * 실증: settings theme → System Optimizer가 Bash 실행, marketplace browse →
+   * 20883 토큰 소진). agentlas.cjs의 오타 가드는 `normalized.length === 1`
+   * 이라 이 경로를 못 받는다. 여기가 유일한 차단 지점이므로 arity를 보지 않는다.
+   * 진짜 작업이면 안내대로 따옴표로 묶어 하나의 프롬프트로 넘긴다.
+   */
+  if (DESKTOP_ONLY_SURFACES[cmd]) {
+    const asTask = [rawCmd, ...rest].join(" ");
+    ctx.err(`${DESKTOP_ONLY_SURFACES[cmd]}\nIt was not run as a prompt — rerun with quotes if you meant a task: agentlas "${asTask}"`);
     return 1;
   }
 

package/engine/commands/open.cjs

@@ -25,7 +25,11 @@ function run(ctx, args) {
     return 1;
   }
   if (rows.length > 1) {
-    ctx.err(ko ? `모호합니다 — 더 긴 접두사를 쓰세요 (${rows.map((r) => r.id.slice(0, 8)).join(", ")})` : `Ambiguous — use a longer prefix (${rows.map((r) => r.id.slice(0, 8)).join(", ")})`);
+    // 안내 접두사는 사용자가 입력한 것보다 반드시 길어야 한다 — chats 목록이
+    // 8자를 찍으므로, 8자로 고정하면 8자 충돌 시 같은 문자열 두 개를 돌려주는
+    // 막다른 길이 된다("더 긴 접두사"를 만들 방법이 없음).
+    const hintLen = Math.max(8, prefix.length + 4);
+    ctx.err(ko ? `모호합니다 — 더 긴 접두사를 쓰세요 (${rows.map((r) => r.id.slice(0, hintLen)).join(", ")})` : `Ambiguous — use a longer prefix (${rows.map((r) => r.id.slice(0, hintLen)).join(", ")})`);
     return 1;
   }
   const chat = rows[0];

package/engine/commands/run.cjs

@@ -26,6 +26,8 @@ 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) => {
@@ -164,12 +166,20 @@ async function runOnce(ctx, args) {
     }
   }
 
+  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),
   });
 

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;