agentlas 1.0.29 → 1.0.36

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## 1.0.34 — 2026-08-06
+
+Telegram, standalone. The terminal can now connect a Telegram bot with no desktop app.
+
+- `connect telegram <agent|firm>` reads a bot token from stdin (never argv), verifies it
+  against api.telegram.org, stores it 0600, polls getUpdates and pairs the first private
+  chat, then sends a confirmation.
+- `connect test <id>` / `connect remove <id>` / `connect status`. The connection core is
+  plain HTTPS ported from the desktop; no Electron, no plugin, no raw JSON dump.
+
+Not yet standalone: auto-creating the bot by piloting BotFather in a browser (the CDP
+browser hardpoint makes this a tractable next layer; it needs a live Telegram web session).
+
+## 1.0.33 — 2026-08-06
+
+Defect sweep: ran every command with a real prompt and fixed what dumped or stalled.
+
+- `connect telegram` / `connect status` no longer dump the raw Hephaestus router JSON —
+  they show the local Telegram binding table and honestly note that bot issuance/pairing
+  still live in Desktop Connect.
+- `route "<request>"` shows a progress spinner during its ~13s Hub round-trip instead of
+  sitting silent.
+
+## 1.0.32 — 2026-08-06
+
+Standalone: the terminal no longer requires Desktop or the plugin for its core flows.
+(They share artifacts and settings; they are not a prerequisite.)
+
+- `project use <agent>` / `project team <agent>…` connect the current folder as a
+  project and set an ordered team, entirely from the terminal — so `run "<task>"` and
+  plain REPL input work without ever opening Desktop. `project status` shows the team.
+- `build "<request>"` now builds locally: the terminal runtime produces an installable
+  agent package (AGENTS.md + manifest.md + README.md) and auto-installs it, instead of
+  printing "open the Claude Code / Codex plugin and run /hep-build".
+- Honest-stops in a project-less folder point at `project use`, not "open Desktop".
+
+Verified standalone end-to-end: project use → run answered correctly; build produced and
+installed an agent that then ran correctly.
+
+## 1.0.31 — 2026-08-06
+
+Interactive UX, measured against first-class REPLs with a real PTY.
+
+- The empty prompt now guides: a dim ghost hint ("type a task · / commands · @ files
+  · ? shortcuts"), `?` prints a shortcuts card, a second empty Enter points the way.
+- Tab-completing a command that takes arguments appends the space, so you can type the
+  argument immediately; no-arg commands are unchanged.
+- A plain-language task in a folder with no connected project now says exactly why and how
+  to run anyway (localized), instead of a single "recovering…" line that hid the reason.
+  Every controller honest-stop carries a machine code so this can never be swallowed again.
+- New PTY-driven gates (repl-guidance, honest-stop-not-swallowed) — these paths live inside
+  the readline session and are invisible to spawnSync tests.
+
+## 1.0.30 — 2026-08-06
+
+CLI-conventions hardening, measured against clig.dev and first-class CLIs.
+
+- A closed pipe is a reader saying stop: `agentlas … | head` no longer crashes with EPIPE.
+- Unexpected crashes now print a one-line summary and a pre-filled GitHub issue URL, not just a raw stack.
+- `TERM=dumb` disables ANSI colors (editor shells, some CI).
+- Secrets stop landing in shell history: `creds save --value -` reads the secret from stdin;
+  passing it via argv now prints an exposure notice.
+- `list --json`, `doctor --json`, `roles --json` — machine contracts for scripts.
+- Workforce staffing survives transient API failures: a typed transient error
+  (connection closed mid-response, timeouts, overload) on a no-authority/read-only stage
+  is retried exactly once; write-capable stages are never retried. A 40-minute, 2.1M-token
+  live run previously died on the final re-verification call for exactly this.
+- New gate: clig-conventions-contract; retry contract added to the workforce runtime gate.
+
 ## 1.0.29 — 2026-08-05
 
 Terminal-wide audit release. Every command was executed for real; what follows fixes what that audit found.

package/bin/agentlas.cjs

@@ -18,6 +18,21 @@
  */
 "use strict";
 
+/*
+ * EPIPE 방어 — 발행본 실설치 검증에서 발견(2026-08-06): `agentlas version | head -1`
+ * 처럼 파이프 소비자가 먼저 닫히면 stdout write가 EPIPE를 던져 스택트레이스로
+ * 크래시했다. `| head` `| less` `| grep -m1`은 CLI의 일상 사용 패턴이다.
+ * 파이프 단절은 오류가 아니라 "그만 읽겠다"는 신호 — 조용히 성공 종료한다.
+ * (시나리오 게이트가 못 잡았던 이유: spawnSync는 파이프를 끝까지 읽는다.
+ *  test/user-scenarios-contract.cjs 의 파이프 시나리오가 이 계약을 잠근다.)
+ */
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on("error", (error) => {
+    if (error && error.code === "EPIPE") process.exit(0);
+    throw error;
+  });
+}
+
 const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");

package/engine/agentlas-cloud-runtime.cjs

@@ -38,11 +38,56 @@ function collectFiles(root) {
   return files.sort((a, b) => a.path.localeCompare(b.path));
 }
 
+// Local sourcePackage identity — the wizard manifest's `packageHash`.
+//
+// This is NOT the delivered Agent Cloud artifact hash. That one is
+// `path-sha256-executable-v2` and lives in engine/cloud-assets/package.cjs,
+// byte-identical with Desktop's hashPackage and Agentlas-OS upload.py. The two
+// are separate contracts on purpose (upload.py: "distinct from agentlas.json's
+// local sourcePackage hash contract").
+//
+// The canonical definition of THIS hash is the kernel's
+// `canonical_package_hash_hex` in Agentlas-OS/agentlas_cloud/runtime.py. This
+// file mirrors it and must produce the same digest for the same folder; the
+// two used to disagree on every input because this copy had no version prefix
+// and skipped only agentlas.json. Keep the three constants below in step with
+// the kernel: PACKAGE_HASH_VERSION, PACKAGE_HASH_EXCLUDED_PATHS, and the
+// experience-lineage rule.
+const PACKAGE_HASH_VERSION = "agentlas-package-hash/v2";
+const LOCAL_EXPERIENCE_LINEAGE_PATH = ".agentlas/experience-relations.jsonl";
+const PACKAGE_HASH_EXCLUDED_PATHS = new Set([
+  "agentlas.json",
+  ".agentlas/brief.json",
+  ".agentlas/security-scan.json",
+  ".agentlas/security-llm-judgment.json",
+  ".agentlas/field-test-report.json",
+  LOCAL_EXPERIENCE_LINEAGE_PATH,
+]);
+
+function isLocalExperienceLineagePath(filePath) {
+  const normalized = String(filePath || "").replaceAll("\\", "/");
+  return (
+    normalized === LOCAL_EXPERIENCE_LINEAGE_PATH ||
+    normalized.startsWith(`${LOCAL_EXPERIENCE_LINEAGE_PATH}.`) ||
+    normalized.startsWith(".agentlas/.experience-relations.jsonl.")
+  );
+}
+
+function packageHashIncludes(filePath) {
+  const normalized = String(filePath || "").replaceAll("\\", "/");
+  return !PACKAGE_HASH_EXCLUDED_PATHS.has(normalized) && !isLocalExperienceLineagePath(normalized);
+}
+
 function hashPackage(files) {
   const h = crypto.createHash("sha256");
-  for (const file of files) {
-    if (file.path === "agentlas.json") continue;
-    h.update(file.path);
+  h.update(PACKAGE_HASH_VERSION);
+  h.update("\0");
+  // Codepoint order, not localeCompare: the kernel sorts by raw string order.
+  const ordered = [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  for (const file of ordered) {
+    const normalized = String(file.path || "").replaceAll("\\", "/");
+    if (!packageHashIncludes(normalized)) continue;
+    h.update(normalized);
     h.update("\0");
     h.update(file.content);
     h.update("\0");
@@ -55,9 +100,14 @@ function inferEntry(files) {
   return ["AGENTS.md", "agent.md", "CLAUDE.md", "README.md"].find((candidate) => paths.has(candidate)) || files[0]?.path || "AGENTS.md";
 }
 
+// Skills actually present in the package. An empty result stays empty.
+// A package with no skills used to be given a literal placeholder skill id.
+// Once skills live outside the core that placeholder fires on every modular
+// agent and fills the Workforce index with a skill nobody has.
+// An absent value is an empty list, never a stand-in.
 function inferSkills(files) {
   const skills = files.map((file) => file.path.match(/(?:^|\/)skills\/([^/]+)\/SKILL\.md$/)?.[1]).filter(Boolean);
-  return [...new Set(skills)].sort().length ? [...new Set(skills)].sort() : ["agentlas-package"];
+  return [...new Set(skills)].sort();
 }
 
 function buildManifest(root, options = {}) {

package/engine/agentlas-input.cjs

@@ -704,7 +704,16 @@ function attachSlashPalette(rl, opts = {}) {
     const list = rows();
     if (!list.length) return false;
     if (state.selected < 0 || state.selected >= list.length) state.selected = 0;
-    state.selectedCommand = list[state.selected].command;
+    const row = list[state.selected];
+    /*
+     * 인자를 받는 명령은 확정 즉시 스페이스까지 넣는다 (2026-08-06, 레퍼런스
+     * 대조): Tab 후 바로 인자를 타이핑하게 — 스페이스를 손으로 넣는 한 박자가
+     * 모든 인자형 명령에서 반복되는 마찰이었다. 인자 없는 명령(/help 등)은
+     * 그대로 — Enter 로 즉시 실행하는 흐름을 깨지 않는다.
+     */
+    const takesArgs = Boolean(String(row.usage || row.args || "").trim())
+      && String(row.usage || `${row.command} ${row.args || ""}`).trim() !== row.command;
+    state.selectedCommand = row.command + (takesArgs ? " " : "");
     replaceLine(state.selectedCommand);
     clear();
     return true;

package/engine/agentlas-native-host.cjs

@@ -13,6 +13,7 @@
  * 스키마는 실측으로 확인됨 (cli/agentlas.cjs 상단 주석 참고).
  */
 const { execFileSync, spawn } = require("node:child_process");
+const { detectRuntimeRefusal } = require("./runtime-refusal.cjs");
 const crypto = require("node:crypto");
 const fs = require("node:fs");
 const os = require("node:os");
@@ -421,11 +422,26 @@ function handleClaudeLine(line, st, ui) {
         cost_usd: obj.total_cost_usd,
         duration_ms: obj.duration_ms,
       };
-      if (obj.is_error) st.error = obj.result || "claude error";
+      if (obj.is_error) {
+        st.error = obj.result || "claude error";
+        // api_error_status:429·error:"rate_limit"이 실려 오는 실측 형태 — 한도는 quota.
+        st.errorKind = obj.api_error_status === 429 || obj.terminal_reason === "api_error"
+          ? "quota" : "exit";
+        st.errorSource = "marker";
+      }
       return;
     case "rate_limit_event":
+      /*
+       * ★한도 거절은 **표식이다** — 경고만 찍고 버리면 안 된다.
+       * 실측(2026-08-06): 이 이벤트가 왔는데도 error가 비어 있어, 뒤따르는 거절문
+       * ("You've hit your weekly limit")이 정상 답으로 세어졌다. 살아 있는 다른
+       * 런타임으로 폴백이 안 걸린 진범. status:rejected면 그 자체로 실패다.
+       */
       if (obj.rate_limit_info && obj.rate_limit_info.status === "rejected") {
         ui.warn(uiText(ui, "runtime.rateLimit", "Claude"));
+        if (!st.error) st.error = "claude rate limit rejected";
+        st.errorKind = "quota";
+        st.errorSource = "marker";
       }
       return;
     default:
@@ -501,6 +517,8 @@ function handleCodexLine(line, st, ui) {
     case "turn.failed":
     case "error":
       st.error = (obj.error && (obj.error.message || obj.error)) || "codex error";
+      st.errorKind = "exit";
+      st.errorSource = "marker";
       ui.error(String(st.error));
       st.errorShown = true;
       return;
@@ -756,9 +774,24 @@ function handleGeminiLine(line, st, ui) {
         duration_ms: s.duration_ms,
       };
       st.finalText = st.text;
-      if (obj.status && obj.status !== "success") st.error = `gemini ${obj.status}`;
+      // error 이벤트가 이미 구체 사유를 남겼으면 뭉뚱그린 상태 문자열로 덮지 않는다.
+      if (obj.status && obj.status !== "success" && !st.error) {
+        st.error = `gemini ${obj.status}`;
+        st.errorKind = "exit";
+        st.errorSource = "marker";
+      }
       return;
     }
+    case "error":
+      /*
+       * ★프로토콜이 선언하는 이벤트인데 핸들러가 없어 조용히 버려졌다
+       * (capture.cjs는 목록에 적어 두고도 안 읽었다). 인증 실패("IneligibleTierError")
+       * 같은 것이 여기로 온다 — 버리면 빈 성공이 된다.
+       */
+      st.error = (obj.error && (obj.error.message || obj.error)) || "gemini error";
+      st.errorKind = /auth|login|credential|tier|eligib/i.test(String(st.error)) ? "auth" : "exit";
+      st.errorSource = "marker";
+      return;
     default:
       return;
   }
@@ -806,8 +839,20 @@ function runNativeTurn(req) {
     } else if (kind === "gemini") {
       args = geminiArgs(launchReq);
       lineHandler = (l) => handleGeminiLine(l, st, ui);
+    } else if (kind === "agy") {
+      /*
+       * Antigravity CLI — stream-json이 없다(실측 1.1.10). 평문 stdout을 그대로 텍스트로.
+       * ★--prompt는 값 플래그가 아니라 --print의 별칭이다(실측: 프롬프트가 조용히 유실됐던
+       * 사고) — 프롬프트는 반드시 위치 인자로 넘긴다. 시스템 프롬프트는 본문에 앞세운다.
+       */
+      const agyPrompt = launchReq.systemPrompt
+        ? `${launchReq.systemPrompt}\n\n---\n\n${launchReq.prompt}`
+        : launchReq.prompt;
+      args = ["--print", agyPrompt, ...(launchReq.model ? ["--model", launchReq.model] : [])];
+      plainStream = true;
+      lineHandler = null;
     } else {
-      return Promise.resolve({ text: "", session: st.session, error: `unknown runtime: ${kind}` });
+      return Promise.resolve({ text: "", session: st.session, error: `unknown runtime: ${kind}`, errorKind: "unsupported", errorSource: "marker" });
     }
   } catch (error) {
     const message = error && error.message ? error.message : String(error);
@@ -883,6 +928,8 @@ function runNativeTurn(req) {
         session: st.session,
         usage: st.usage,
         error: termination ? termination.message : "native runtime stopped",
+        errorKind: "timeout",
+        errorSource: "marker",
         terminationVerified: Boolean(termination?.verified),
       });
     };
@@ -976,13 +1023,31 @@ function runNativeTurn(req) {
       ui.stopSpinner();
       const text = (st.finalText || st.text || "").trim();
       if (st.usage) ui.cost(st.usage);
+      /*
+       * ★표식 없이 완주했는데 산출물이 거절 고지문인 경우 — 실측: codex 한도는
+       * 거절문이 agent_message로 오고 turn.completed로 끝난다(표식 0, exit 0).
+       * 이 한 자리에서만 텍스트 판별을 허용하고, 출처를 heuristic으로 남긴다
+       * (판별 규칙은 runtime-refusal.cjs 한 곳 — 여기서 정규식을 다시 쓰지 않는다).
+       */
+      if (code === 0 && !st.error) {
+        const refusal = detectRuntimeRefusal(text);
+        if (refusal) {
+          st.error = refusal.message;
+          st.errorKind = refusal.kind;
+          st.errorSource = "heuristic";
+        }
+      }
       const exitError = code === 0
         ? st.error
         : st.error || [
             `${kind} exited with code ${code == null ? "unknown" : code}`,
             stripAnsi(stderrBuf).slice(-4000),
           ].filter(Boolean).join("\n");
-      finish({ text, session: st.session, usage: st.usage, error: exitError });
+      if (exitError && !st.errorKind) { st.errorKind = "exit"; st.errorSource = st.errorSource || "exit"; }
+      finish({
+        text, session: st.session, usage: st.usage, error: exitError,
+        ...(exitError ? { errorKind: st.errorKind, errorSource: st.errorSource } : {}),
+      });
     });
 
     armIdle();

package/engine/agentlas-ui.cjs

@@ -15,6 +15,8 @@ const RESET = "\x1b[0m";
 
 function colorEnabled() {
   if (process.env.NO_COLOR != null && process.env.NO_COLOR !== "") return false;
+  // clig.dev: TERM=dumb 인 터미널(에디터 내장 셸, 일부 CI)은 ANSI를 렌더하지 못한다.
+  if (process.env.TERM === "dumb") return false;
   if (process.env.FORCE_COLOR === "1" || process.env.FORCE_COLOR === "true") return true;
   if (process.env.AGENTLAS_NO_COLOR === "1") return false;
   return !!process.stdout.isTTY;

package/engine/agentlas-workforce.cjs

@@ -2120,6 +2120,28 @@ function create(deps = {}) {
     tokenLedger.push({ role: role || "stage", runtime: runtimeKind || "?", model: modelPin || null, input, output, cached });
   }
 
+  /*
+   * 일시 API 오류 1회 재시도 (실측 2026-08-05: 4슬롯·2.1M 토큰 편성이 마지막
+   * 재검증 호출의 "Connection closed mid-response" 하나로 전멸).
+   * 재시도의 근거는 부수효과 부재가 아니라 **일시 오류의 기계 표식**이고,
+   * 부수효과가 가능한 write 권한 단계는 표식이 있어도 재시도하지 않는다
+   * (자동화 스케줄러와 같은 원칙). D.runModel 주입·CLI 캡처·API 백엔드
+   * 세 경로 모두 이 관문을 지난다 — 하니스가 단위로 검증할 수 있는 이유.
+   */
+  // 한도·429는 재시도 분류에 들어가야 한다 — 빠져 있으면 같은 막힌 런타임에 즉시 재도전만 한다.
+const TRANSIENT_MODEL_ERROR_RE = /Connection closed mid-response|"terminal_reason":"api_error"|ECONNRESET|ETIMEDOUT|socket hang up|overloaded_error|rate.?limit|quota|\b429\b|usage limit|weekly limit/i;
+  async function withTransientModelRetry(authorityMode, invoke) {
+    try {
+      return await invoke();
+    } catch (error) {
+      const replaySafeAuthority = authorityMode === "no-authority" || authorityMode === "read-only";
+      const transient = TRANSIENT_MODEL_ERROR_RE.test(String((error && error.message) || error));
+      if (!replaySafeAuthority || !transient) throw error;
+      process.stderr.write(`workforce: transient api error on a ${authorityMode} stage — retrying once\n`);
+      return invoke();
+    }
+  }
+
   async function runModel(runtime, system, prompt, context) {
     const invocation = stageInvocation(runtime, context);
     const executionRuntime = invocation.executionRuntime;
@@ -2134,7 +2156,7 @@ function create(deps = {}) {
       ? `${system}\n\n${localContextSlice}`
       : system;
     if (typeof D.runModel === "function") {
-      return normalizeModelResult(await D.runModel({
+      return withTransientModelRetry(context.authorityMode || "no-authority", async () => normalizeModelResult(await D.runModel({
         runtime: executionRuntime,
         system: effectiveSystem,
         prompt,
@@ -2145,7 +2167,7 @@ function create(deps = {}) {
           modelPin: invocation.modelPin,
           effortPin: invocation.effort,
         },
-      }));
+      })));
     }
     if (executionRuntime.mode === "cli") {
       const authorityMode = context.authorityMode || "no-authority";
@@ -2174,7 +2196,7 @@ function create(deps = {}) {
         }
         noteIsolationWeakness(executionRuntime.kind, invocation.role);
       }
-      const captured = normalizeModelResult(await D.captureRuntime(executionRuntime.kind, effectiveSystem, prompt, {
+      const captureOnce = async () => normalizeModelResult(await D.captureRuntime(executionRuntime.kind, effectiveSystem, prompt, {
         cwd: context.cwd,
         env: context.env,
         permission: context.permission,
@@ -2187,16 +2209,17 @@ function create(deps = {}) {
         outputLimitBytes: authorityMode === "read-only" ? 24 * 1024 * 1024 : undefined,
         envelope: true,
       }));
+      const captured = await withTransientModelRetry(authorityMode, captureOnce);
       recordStageTokens(invocation.role, executionRuntime.kind, invocation.modelPin, captured.usage);
       return captured;
     }
-    const viaApi = normalizeModelResult(await D.runApi(
+    const viaApi = await withTransientModelRetry(context.authorityMode || "no-authority", async () => normalizeModelResult(await D.runApi(
       executionRuntime.backend,
       invocation.modelPin,
       effectiveSystem,
       prompt,
       { effort: invocation.effort, envelope: true },
-    ));
+    )));
     recordStageTokens(invocation.role, executionRuntime.backend, invocation.modelPin, viaApi.usage);
     return viaApi;
   }

package/engine/agentlas.cjs

@@ -14,10 +14,51 @@
  *   ctx.out/err       stdout/stderr 한 줄 출력
  *   ctx.tableExists / ctx.columnExists
  */
+/*
+ * EPIPE 방어 — 발행본 1.0.29 실설치 검증에서 발견(2026-08-06):
+ * `agentlas version | head -1` 처럼 파이프 소비자가 먼저 닫히면 stdout write가
+ * EPIPE를 던져 스택트레이스로 크래시했다(실측: version.cjs → ctx.out → EPIPE).
+ * `| head` `| less` `| grep -m1` 은 CLI의 일상 사용 패턴이고, 파이프 단절은
+ * 오류가 아니라 "그만 읽겠다"는 신호다 — 조용히 성공 종료한다. 런처(bin)는
+ * 엔진을 stdio:"inherit" 로 spawn 하므로 이 방어는 엔진 프로세스에 있어야 한다.
+ */
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on("error", (error) => {
+    if (error && error.code === "EPIPE") process.exit(0);
+    throw error;
+  });
+}
+
+/*
+ * 예상 못 한 크래시의 마지막 예의 (clig.dev: unexpected error에는 디버그 정보와
+ * 버그 리포트 경로를, 리포트는 미리 채워진 URL로 손쉽게).
+ * 예전에는 Node 기본 동작(원시 스택트레이스)이 그대로 사용자에게 쏟아졌다 —
+ * EPIPE 크래시(1.0.29 실측)가 정확히 그 모습이었다. 스택은 진단에 필요하므로
+ * 숨기지 않되, 한 줄 요약과 이슈 URL(제목 미리 채움)을 함께 준다.
+ * 종료 코드는 관례대로 1. 여기서 복구를 시도하지 않는다(crash-only).
+ */
+function reportCrash(kind, error) {
+  const message = String((error && error.stack) || error);
+  const title = encodeURIComponent(`crash: ${String((error && error.message) || error).slice(0, 100)}`);
+  process.stderr.write([
+    "",
+    `agentlas hit an unexpected error (${kind}).`,
+    message,
+    "",
+    `Report it (pre-filled): https://github.com/agentlas-ai/agentlas-terminal/issues/new?title=${title}`,
+    `Include: your command, agentlas ${(() => { try { return require("./agentlas-banner.cjs").readVersion(); } catch { return "?"; } })()}, node ${process.version}, ${process.platform}.`,
+    "",
+  ].join("\n"));
+  process.exit(1);
+}
+process.on("uncaughtException", (error) => reportCrash("uncaughtException", error));
+process.on("unhandledRejection", (error) => reportCrash("unhandledRejection", error));
+
 const { openDb, seedBuiltins, tableExists, columnExists } = require("./core/db.cjs");
 const { userDataDir } = require("./core/paths.cjs");
 const { loadPrefs } = require("./agentlas-config.cjs");
 const { Ui } = require("./agentlas-ui.cjs");
+const { parseOutputFlags, render, renderError, isRichUi } = require("./cli-output.cjs");
 const commands = require("./commands/index.cjs");
 
 const SUPPORTED_LANGS = new Set(["ko", "en"]);
@@ -61,6 +102,22 @@ function buildCtx() {
     },
     out: (s = "") => process.stdout.write(s + "\n"),
     err: (s = "") => process.stderr.write(s + "\n"),
+    /*
+     * 출력 계약 — 명령은 문자열이 아니라 {데이터+스키마}를 준다(cli-output.cjs).
+     * 형식(--json/--yaml/--quiet/--no-headers/--no-color) 해석은 여기 한 곳이라,
+     * 명령마다 --json 유무가 갈리거나 에러 형식이 달라지는 일이 없다.
+     */
+    output: { ...require("./cli-output.cjs").DEFAULT_OPTIONS },
+    emit(result) {
+      const text = render(result, this.output);
+      if (text) process.stdout.write(text + "\n");
+    },
+    fail(error) {
+      process.stderr.write(renderError(error, this.output) + "\n");
+    },
+    get richUi() {
+      return isRichUi(this.output);
+    },
     db: () => {
       if (_db) return _db;
       _db = openDb();
@@ -123,12 +180,17 @@ function main() {
     return a;
   });
 
+  // 전역 출력 플래그는 명령에 닿기 전에 한 곳에서 뜯어낸다 —
+  // 명령마다 --json 유무가 갈리던 것을 구조로 막는다.
+  const { options: outputOptions, rest: commandArgv } = parseOutputFlags(normalized);
   const ctx = buildCtx();
+  ctx.output = outputOptions;
   let code;
   try {
-    code = commands.dispatch(ctx, normalized);
+    code = commands.dispatch(ctx, commandArgv);
   } catch (e) {
-    ctx.err(String((e && e.message) || e));
+    // 에러도 같은 형식 규율을 따른다: --json 이면 {"error":{code,message}}.
+    ctx.fail(e);
     process.exit(1);
   }
 

package/engine/agents/builder.cjs

@@ -0,0 +1,84 @@
+"use strict";
+/*
+ * agents/builder — 터미널 소유 로컬 에이전트 빌더 (독립).
+ *
+ * 배경(2026-08-06 오너 원칙): 데스크탑/플러그인은 산출물·설정을 공유할 뿐 선행
+ * 전제가 아니다. 그런데 `agentlas build "<req>"`는 Hephaestus 네이티브
+ * 패스스루라 "Open Claude Code or Codex with the plugin, then /hep-build"라는
+ * 스텁만 냈다 — 플러그인 강제. 터미널은 자체 런타임(claude-code/codex/gemini)이
+ * 있으므로 빌더를 로컬로 돌린다.
+ *
+ * 계약: 빌더 에이전트를 멱등 시드(installed_agents)하고, `run`과 같은 실행
+ * 인프라(Orchestrator 세션)로 돌린다. 산출물은 `import`가 읽는 로컬 폴더 형식
+ * (AGENTS.md=시스템 프롬프트, manifest.md=이름/태그라인). 빌더가 마지막 줄에
+ * `BUILT: <folder>`를 찍으면 그 폴더를 자동 import 한다. 실패해도 폴더는 남아
+ * `agentlas import <folder>`로 언제든 설치할 수 있다.
+ */
+const crypto = require("node:crypto");
+const { runWriteTransaction } = require("../agentlas-sqlite-policy.cjs");
+const { columnExists } = require("../core/db.cjs");
+
+const BUILDER_SLUG = "agentlas-builder";
+const BUILDER_ID = "builtin-agentlas-builder";
+
+const BUILDER_SYSTEM_PROMPT = [
+  "You are the Agentlas local agent builder, running inside the Agentlas terminal.",
+  "Your job: turn the user's request into an installable Agentlas agent, entirely on this machine — no external plugin, no desktop app.",
+  "",
+  "Produce a folder the terminal can import. In the current working directory create a folder named after the agent (kebab-case slug), containing exactly:",
+  "  - AGENTS.md — the agent's full system prompt / soul: who it is, what it does, how it behaves, its guardrails. Write it as the instructions the agent itself will run under. Be specific and production-ready, not a description of the agent.",
+  "  - manifest.md — first line `# <Agent Name>`, second line a one-sentence tagline.",
+  "  - README.md — a short human-facing summary of what the agent does and how to use it.",
+  "",
+  "Rules:",
+  "  - Decide the agent's scope from the request; if the request is thin, choose sensible, specific defaults and state them in README.md rather than asking endless questions.",
+  "  - Do not invent credentials, API keys, or secrets. If the agent needs an env var, name it in README.md as something the user provides later.",
+  "  - Keep everything inside the new folder. Do not modify files outside it.",
+  "  - When finished, print exactly one final line: `BUILT: <relative-folder-path>` so the terminal can install it.",
+].join("\n");
+
+/** 빌더 에이전트를 멱등 보장한다(installed_agents). 반환: 에이전트 행 형태. */
+function ensureBuilderAgent(db) {
+  const now = new Date().toISOString();
+  const hasVisibility = columnExists(db, "installed_agents", "visibility");
+  runWriteTransaction(db, () => {
+    const existing = db.prepare("SELECT id FROM installed_agents WHERE id=? OR slug=?").get(BUILDER_ID, BUILDER_SLUG);
+    if (existing) {
+      db.prepare("UPDATE installed_agents SET system_prompt=?, name=?, name_en=?, tagline=?, tagline_en=? WHERE id=?")
+        .run(BUILDER_SYSTEM_PROMPT, "Agent Builder", "Agent Builder", "Builds Agentlas agents locally", "Builds Agentlas agents locally", existing.id);
+      return;
+    }
+    if (hasVisibility) {
+      db.prepare(
+        "INSERT INTO installed_agents (id, slug, name, name_en, tagline, tagline_en, system_prompt, mcp_servers_json, env_requirements_json, preferred_backend, trust_grade, installed_at, tone, builtin, role, visibility) " +
+        "VALUES (?,?,?,?,?,?,?,'[]','[]',NULL,'A',?,?,1,?,?)",
+      ).run(BUILDER_ID, BUILDER_SLUG, "Agent Builder", "Agent Builder", "Builds Agentlas agents locally", "Builds Agentlas agents locally", BUILDER_SYSTEM_PROMPT, now, "blue", "orchestrator", "visible");
+    } else {
+      db.prepare(
+        "INSERT INTO installed_agents (id, slug, name, name_en, tagline, tagline_en, system_prompt, mcp_servers_json, env_requirements_json, preferred_backend, trust_grade, installed_at, tone, builtin, role) " +
+        "VALUES (?,?,?,?,?,?,?,'[]','[]',NULL,'A',?,?,1,?)",
+      ).run(BUILDER_ID, BUILDER_SLUG, "Agent Builder", "Agent Builder", "Builds Agentlas agents locally", "Builds Agentlas agents locally", BUILDER_SYSTEM_PROMPT, now, "blue", "orchestrator");
+    }
+  });
+  return {
+    id: BUILDER_ID,
+    slug: BUILDER_SLUG,
+    name: "Agent Builder",
+    nameEn: "Agent Builder",
+    systemPrompt: BUILDER_SYSTEM_PROMPT,
+    builtin: true,
+    role: "orchestrator",
+  };
+}
+
+/** 빌더 산출물 마지막 줄에서 `BUILT: <folder>`를 뽑는다. */
+function parseBuiltFolder(finalText) {
+  const lines = String(finalText || "").split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const m = lines[i].match(/^BUILT:\s*(.+)$/);
+    if (m) return m[1].trim();
+  }
+  return null;
+}
+
+module.exports = { ensureBuilderAgent, parseBuiltFolder, BUILDER_SLUG, BUILDER_ID, BUILDER_SYSTEM_PROMPT };

package/engine/agents/router.cjs

@@ -49,8 +49,14 @@ function ensureJudgeRunner(db, runtime) {
           model: resolved.model || undefined,
           signal,
         });
-      } catch {
-        return "";
+      } catch (error) {
+        /*
+         * ★사유를 ""로 지우지 않는다 — 여기서 지우면 판정 서비스는 "no connected model
+         * reached a valid judgment"라는 거짓 문장만 남긴다(모델은 닿았고, 한도라고
+         * 말했다). 러너 계약은 문자열이므로 예외를 그대로 올려 judgeLabels가 사유를
+         * 싣게 한다.
+         */
+        throw error;
       }
     });
     return judgment;