agentlas 1.0.27 → 1.0.29

package/engine/graph/layout.cjs

@@ -0,0 +1,137 @@
+// 결정적 좌→우 그래프 배치. **데스크탑 `shared/graph-layout.ts`의 미러다.**
+//
+// 왜 사본이 있나: 터미널은 독립 패키지라 데스크탑 소스를 임포트할 수 없다. 이 저장소는
+// 같은 이유로 `interview.cjs`(청사진 컴파일러)도 이미 미러로 두고, **패리티 게이트**가
+// 두 벌이 같은 판단을 하는지 대조한다(`test/graph-interview-parity.cjs`). 배치도 같은 규율:
+// 여기서 바꾸면 데스크탑도 바꾸고, 게이트가 그 둘을 붙잡는다.
+//
+// ★규칙이 갈라지면 같은 그래프가 표면마다 다르게 그려지고, 사용자는 자기 자동화를
+//   어느 쪽이 맞는지 알 수 없게 된다.
+"use strict";
+
+const COL_W = 280;
+const ROW_H = 120;
+const NODE_ORIGIN_X = 0;
+const NODE_ORIGIN_Y = 120;
+
+/** 노드 카드의 실측 크기 — 이보다 가까우면 화면에서 겹쳐 글자를 못 읽는다. */
+const NODE_W = 230;
+const NODE_H = 90;
+
+/** 위상 순서로 각 노드에 컬럼 depth를 매긴다(진입 엣지 없는 노드 = depth 0). */
+function computeDepths(graph) {
+  const indeg = new Map();
+  const adj = new Map();
+  for (const n of graph.nodes) {
+    indeg.set(n.id, 0);
+    adj.set(n.id, []);
+  }
+  for (const e of graph.edges || []) {
+    if (!indeg.has(e.target) || !adj.has(e.source)) continue; // dangling edge 방어
+    indeg.set(e.target, (indeg.get(e.target) || 0) + 1);
+    adj.get(e.source).push(e.target);
+  }
+  const depth = new Map();
+  const frontier = graph.nodes.filter((n) => (indeg.get(n.id) || 0) === 0).map((n) => n.id);
+  for (const id of frontier) depth.set(id, 0);
+  const remaining = new Map(indeg);
+  const queue = [...frontier];
+  while (queue.length) {
+    const id = queue.shift();
+    const d = depth.get(id) || 0;
+    for (const next of adj.get(id) || []) {
+      depth.set(next, Math.max(depth.get(next) || 0, d + 1));
+      const left = (remaining.get(next) == null ? 1 : remaining.get(next)) - 1;
+      remaining.set(next, left);
+      if (left <= 0) queue.push(next);
+    }
+  }
+  // 사이클(반복 그래프) 등으로 depth 미할당된 노드는 순서 인덱스로 폴백.
+  graph.nodes.forEach((n, i) => {
+    if (!depth.has(n.id)) depth.set(n.id, i);
+  });
+  return depth;
+}
+
+/** 한 띠(band)에 넣을 컬럼 수 — 데스크탑 columnsPerBand와 같은 식. */
+function columnsPerBand(totalCols) {
+  if (totalCols <= 4) return totalCols;
+  return Math.max(4, Math.ceil(Math.sqrt(totalCols * 2)));
+}
+
+/**
+ * 그래프를 결정적 사행(蛇行) 배치로 재배치한 새 노드 배열.
+ * 긴 사슬은 띠로 접어 좌→우 / 우→좌로 번갈아 흐르고(뱀 모양), 같은 컬럼은 세로 분산.
+ * (일직선은 14단계에서 폭 4,000px가 되어 아무도 못 읽었다 — 실측 항목 3.)
+ */
+function layoutGraph(graph) {
+  const depth = computeDepths(graph);
+  const byCol = new Map();
+  for (const n of graph.nodes) {
+    const d = depth.get(n.id) || 0;
+    if (!byCol.has(d)) byCol.set(d, []);
+    byCol.get(d).push(n);
+  }
+  const cols = [...byCol.keys()].sort((a, b) => a - b);
+  const colOrder = new Map(cols.map((c, i) => [c, i]));
+  const totalCols = cols.length;
+  const perBand = columnsPerBand(totalCols);
+
+  const bandCount = Math.ceil(totalCols / perBand);
+  const bandHeight = [];
+  for (let b = 0; b < bandCount; b += 1) {
+    let maxRows = 1;
+    for (const [c, i] of colOrder) {
+      if (Math.floor(i / perBand) === b) maxRows = Math.max(maxRows, byCol.get(c).length);
+    }
+    bandHeight.push(maxRows * ROW_H + ROW_H);
+  }
+  const bandTop = [];
+  let acc = 0;
+  for (let b = 0; b < bandCount; b += 1) { bandTop.push(acc); acc += bandHeight[b]; }
+
+  const out = [];
+  for (const [col, nodes] of byCol) {
+    const i = colOrder.get(col) || 0;
+    const band = Math.floor(i / perBand);
+    let c = i % perBand;
+    if (band % 2 === 1) c = perBand - 1 - c;
+    const count = nodes.length;
+    nodes.forEach((n, row) => {
+      const offset = (row - (count - 1) / 2) * ROW_H;
+      out.push({
+        ...n,
+        position: {
+          x: NODE_ORIGIN_X + c * COL_W,
+          y: NODE_ORIGIN_Y + bandTop[band] + (bandHeight[band] - ROW_H) / 2 + offset,
+        },
+      });
+    });
+  }
+  // 원래 순서 보존(렌더러 key 안정).
+  const orderIndex = new Map(graph.nodes.map((n, i) => [n.id, i]));
+  out.sort((a, b) => (orderIndex.get(a.id) || 0) - (orderIndex.get(b.id) || 0));
+  return out;
+}
+
+/**
+ * 재배치가 필요한가 — **실제로 겹치는가**로 판단한다.
+ * ★예전에는 좌표가 완전히 같을 때만 재배치해서, 검증을 +70·갈림길을 +140만 띄운
+ *   그래프(노드 폭 230)가 "다른 좌표"라 통과했고 카드가 서로 가렸다(실측 2026-08-05).
+ */
+function needsLayout(graph) {
+  if (!graph || !Array.isArray(graph.nodes) || graph.nodes.length <= 1) return false;
+  const placed = graph.nodes.map((n) => ({
+    x: Math.round((n.position && n.position.x) || 0),
+    y: Math.round((n.position && n.position.y) || 0),
+  }));
+  for (let i = 0; i < placed.length; i += 1) {
+    for (let j = i + 1; j < placed.length; j += 1) {
+      if (Math.abs(placed[i].x - placed[j].x) < NODE_W
+        && Math.abs(placed[i].y - placed[j].y) < NODE_H) return true;
+    }
+  }
+  return false;
+}
+
+module.exports = { layoutGraph, needsLayout, columnsPerBand, COL_W, ROW_H, NODE_W, NODE_H };

package/engine/graph/package.cjs

@@ -0,0 +1,223 @@
+"use strict";
+/*
+ * .agentgraph 패키징 — 그래프를 남에게 줄 수 있는 형태로 만든다.
+ *
+ * 핵심 계약 두 줄:
+ *  1) 지울 수 없는 비밀이 하나라도 남으면 **내보내지 않는다**. 몰래 지우고 통과시키면
+ *     사용자는 자기 키가 빠진 줄 알고 공유하게 된다.
+ *  2) 모델 고정은 유통될 수 없다. 받는 사람의 기본 모델로 돌아야 하므로 등급 힌트로 바꾼다.
+ *
+ * 여기서 만드는 건 파일 하나(JSON)다. 허브 업로드는 별도 표면이며, 이 모듈은
+ * "무엇을 지웠고 무엇을 채워야 하는지"까지 파일 안에 적어 둔다.
+ */
+const crypto = require("node:crypto");
+
+const SCHEMA_VERSION = "agentgraph/1.0";
+
+/** 값이 자격증명처럼 보이는가 — 형태 판정만 한다(의미 판정 아님). */
+const SECRET_VALUE_PATTERNS = [
+  /\bsk-[A-Za-z0-9_-]{16,}/,
+  /\bAKIA[0-9A-Z]{16}\b/,
+  /\bghp_[A-Za-z0-9]{20,}/,
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}/,
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+  /\bBearer\s+[A-Za-z0-9._-]{20,}/i,
+  /\beyJ[A-Za-z0-9._-]{30,}/,
+];
+
+/** 키 이름이 비밀을 담기로 되어 있는가. 값이 비어 있어도 템플릿 대상이다. */
+const SECRET_KEY_RE = /(token|secret|password|passwd|apikey|api_key|credential|private_key|access_key)/i;
+
+/** 로컬 사용자 경로 — 남의 기계에서 의미가 없고, 계정명이 그대로 드러난다. */
+const PERSONAL_PATH_RE = /(\/Users\/[^/\s"']+|\/home\/[^/\s"']+|C:\\Users\\[^\\\s"']+)/g;
+
+function vaultKeyFor(nodeId, key) {
+  return `${String(key).replace(/[^A-Za-z0-9]+/g, "_").toUpperCase()}`;
+}
+
+function looksSecretValue(value) {
+  return typeof value === "string" && SECRET_VALUE_PATTERNS.some((re) => re.test(value));
+}
+
+/**
+ * 노드 설정을 훑어 비밀·모델핀·개인 경로를 처리한다.
+ * 반환: { config, findings, vaultTemplate, blockers }
+ */
+function scrubNodeConfig(nodeId, config) {
+  const out = {};
+  const findings = [];
+  const vaultTemplate = [];
+  const blockers = [];
+  for (const [key, value] of Object.entries(config || {})) {
+    // 1) 비밀로 선언된 칸 — 값 유무와 무관하게 금고 변수로 바꾼다.
+    if (SECRET_KEY_RE.test(key)) {
+      const vaultKey = vaultKeyFor(nodeId, key);
+      out[key] = `$\{vault.${vaultKey}}`;
+      vaultTemplate.push({ key: vaultKey, kind: "secret", requiredBy: [nodeId], sourceField: key });
+      findings.push({ rule: "secret-field", nodeId, field: key, action: `templated:${vaultKey}` });
+      continue;
+    }
+    // 2) 비밀처럼 생긴 값이 엉뚱한 칸에 있으면 — 자동 치환하지 않고 막는다.
+    //    이름 없는 칸의 비밀은 무엇을 채워야 하는지 우리가 알 수 없다.
+    if (looksSecretValue(value)) {
+      blockers.push({
+        nodeId,
+        field: key,
+        reason: `"${key}" 값이 자격증명처럼 보입니다. 어떤 키인지 알 수 없어 자동으로 빈칸 처리할 수 없습니다.`,
+        nextAction: `이 값을 금고 변수로 바꾼 뒤(예: $\{vault.MY_TOKEN}) 다시 내보내세요.`,
+      });
+      out[key] = value;
+      continue;
+    }
+    // 3) 모델 고정 — 받는 사람 기계엔 그 모델이 없다. 등급 힌트로 바꾼다.
+    if (key === "model" && typeof value === "string" && value) {
+      out.tierHint = "standard";
+      findings.push({ rule: "model-pin", nodeId, field: key, action: "replaced:runner-primary" });
+      continue;
+    }
+    // 4) 개인 경로 — 계정명이 그대로 드러난다.
+    if (typeof value === "string" && PERSONAL_PATH_RE.test(value)) {
+      out[key] = value.replace(PERSONAL_PATH_RE, "<사용자 폴더>");
+      findings.push({ rule: "personal-path", nodeId, field: key, action: "removed" });
+      PERSONAL_PATH_RE.lastIndex = 0;
+      continue;
+    }
+    out[key] = value;
+  }
+  return { config: out, findings, vaultTemplate, blockers };
+}
+
+function digestOf(value) {
+  return `sha256:${crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+}
+
+/**
+ * 그래프 하나를 .agentgraph 패키지로 만든다.
+ * 막을 사유가 있으면 { blocked: true, blockers } 를 돌려주고 패키지를 만들지 않는다.
+ */
+function buildPackage(input) {
+  const { automation, graph } = input;
+  const findings = [];
+  const vaultTemplate = [];
+  const blockers = [];
+  const nodes = [];
+  const dependencies = { agents: [], mcp: [], subGraphs: [] };
+
+  for (const node of graph.nodes || []) {
+    const scrubbed = scrubNodeConfig(node.id, node.config);
+    findings.push(...scrubbed.findings);
+    vaultTemplate.push(...scrubbed.vaultTemplate);
+    blockers.push(...scrubbed.blockers);
+    nodes.push({ ...node, config: scrubbed.config });
+
+    // 에이전트 참조는 핀으로 남긴다 — 받는 사람이 무엇을 빌려야 하는지 알아야 한다.
+    // 노드가 ref를 선언하지 않으면 자동화의 대상 에이전트를 상속한다(제품의 실제 동작).
+    // 그 경우를 빼면 패키지가 "채울 것 없음"이라고 거짓말한다.
+    const isAgentish = node.type === "agent" || node.type === "action" || node.type === "output";
+    const ref = typeof node.config?.ref === "string" && node.config.ref ? node.config.ref : null;
+    const inheritedSlug = automation.target_id || null;
+    const slug = ref || (isAgentish && node.type === "agent" ? inheritedSlug : null);
+    if (isAgentish && slug) {
+      const source = (ref ? node.config?.targetType : automation.target_type) === "hub" ? "hub" : "local";
+      if (!dependencies.agents.some((dep) => dep.slug === slug)) {
+        dependencies.agents.push({
+          nodeId: node.id,
+          slug,
+          source,
+          ...(ref ? {} : { inheritedFromAutomation: true }),
+        });
+      }
+    }
+    const server = node.config?.mcpServer;
+    if (typeof server === "string" && server && !dependencies.mcp.some((m) => m.serverSlug === server)) {
+      dependencies.mcp.push({ serverSlug: server, requiredBy: [node.id] });
+    }
+  }
+
+  if (blockers.length > 0) {
+    return { blocked: true, blockers, findings };
+  }
+
+  const mutationNodes = nodes
+    .filter((n) => n.config?.effect === "mutation")
+    .map((n) => ({ nodeId: n.id, label: n.label || n.id }));
+
+  const scrubbedGraph = { version: graph.version ?? 1, nodes, edges: graph.edges || [] };
+  if (graph.budget) scrubbedGraph.budget = graph.budget;
+
+  const manifest = {
+    schemaVersion: SCHEMA_VERSION,
+    slug: String(automation.name || "graph").trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, ""),
+    name: automation.name,
+    version: input.version || "1.0.0",
+    exportedAt: new Date().toISOString(),
+    trigger: {
+      kind: automation.trigger_type && automation.trigger_type !== "schedule" ? "input" : "cron",
+      schedule: automation.schedule ?? null,
+    },
+    dependencies,
+    vaultTemplate,
+    modelPolicy: { binding: "runner-primary" },
+    // 받는 사람이 설치 전에 알아야 하는 것 — 무엇이 바깥으로 나가는가.
+    permissionsSummary: {
+      mutationNodes,
+      leasedAgents: dependencies.agents.filter((d) => d.source === "hub").map((d) => d.slug),
+    },
+    scrubReport: { rulesVersion: "scrub/1.0", scrubbedAt: new Date().toISOString(), findings },
+  };
+  manifest.integrity = { graphDigest: digestOf(scrubbedGraph), manifestDigest: null };
+  manifest.integrity.manifestDigest = digestOf({ ...manifest, integrity: { graphDigest: manifest.integrity.graphDigest, manifestDigest: null } });
+
+  return { blocked: false, blockers: [], findings, package: { manifest, graph: scrubbedGraph } };
+}
+
+/**
+ * 패키지를 받았을 때 실행 전에 채워야 하는 것들.
+ * "설치했으니 이제 돌아간다"가 아니라 "무엇이 비어 있는가"를 먼저 말한다.
+ */
+function bindingChecklist(pkg) {
+  const manifest = pkg?.manifest || {};
+  const items = [];
+  for (const entry of manifest.vaultTemplate || []) {
+    items.push({
+      kind: "vault-key",
+      key: entry.key,
+      requiredBy: entry.requiredBy || [],
+      done: false,
+    });
+  }
+  for (const dep of manifest.dependencies?.agents || []) {
+    items.push({ kind: "agent", slug: dep.slug, source: dep.source, nodeId: dep.nodeId, done: false });
+  }
+  for (const dep of manifest.dependencies?.mcp || []) {
+    items.push({ kind: "mcp-server", serverSlug: dep.serverSlug, done: false });
+  }
+  return items;
+}
+
+function verifyPackage(pkg) {
+  const problems = [];
+  if (!pkg || typeof pkg !== "object") return ["패키지 형식이 아닙니다."];
+  const { manifest, graph } = pkg;
+  if (!manifest || manifest.schemaVersion !== SCHEMA_VERSION) {
+    problems.push(`이 버전이 읽을 수 없는 패키지 형식입니다(${manifest?.schemaVersion ?? "형식 없음"}).`);
+  }
+  if (!graph || !Array.isArray(graph.nodes) || graph.nodes.length === 0) {
+    problems.push("그래프에 단계가 없습니다.");
+  }
+  if (manifest?.integrity?.graphDigest && graph) {
+    if (digestOf(graph) !== manifest.integrity.graphDigest) {
+      problems.push("그래프 내용이 매니페스트 지문과 다릅니다(전송 중 변형되었을 수 있습니다).");
+    }
+  }
+  return problems;
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  buildPackage,
+  bindingChecklist,
+  verifyPackage,
+  scrubNodeConfig,
+  digestOf,
+};

package/engine/graph/vocabulary.generated.cjs

@@ -0,0 +1,30 @@
+// ⚠️ 생성된 파일입니다. 손으로 고치지 마세요.
+// 정본: agentlas_desktop/shared/graph-registry/*.json
+// 생성: (agentlas_desktop) node scripts/gen-graph-registry.cjs
+//
+// 터미널은 데스크탑과 같은 DB를 읽지만 스키마 판이 뒤따라온다. 모르는 값을 만나는 것은
+// 고장이 아니라 정상이며, 그때 **그 항목만** 강등하고 나머지는 정상 처리한다.
+"use strict";
+
+const GRAPH_WIRE = "graph/1";
+const GRAPH_ERROR_CODES = ["APPROVAL_REJECTED","APPROVAL_REQUIRED","APPROVAL_TIMED_OUT","ARCHITECT_NO_CHANGE","ARCHITECT_NO_REQUEST","ARCHITECT_OUTPUT_MALFORMED","ARCHITECT_OUTPUT_TOO_LARGE","ARCHITECT_OUTPUT_UNREADABLE","ARCHITECT_UNAVAILABLE","AUTOMATION_NOT_CONNECTED","BUDGET_EXHAUSTED","CODE_DEPENDENCY_MISSING","CODE_NODE_EMPTY","CODE_STEP_FAILED","CREATE_INPUT_INVALID","EDGE_CONDITION_UNRESOLVED","EVAL_INCOMPLETE","EVAL_STUCK","EVAL_UNAVAILABLE","INTERVIEW_MODEL_UNAVAILABLE","INTERVIEW_OUTPUT_UNREADABLE","INTERVIEW_REPEATED_QUESTIONS","INTERVIEW_SELF_CORRECTION_EXHAUSTED","INTERVIEW_STATE_INVALID","LOOP_BOUND_INVALID","LOOP_BOUND_UNDECLARED","LOOP_LIMIT_REACHED","LOOP_WITHOUT_EXIT","MUTATION_UNVERIFIED","NODE_FAILED","NODE_INPUT_MISSING","NODE_NEVER_REACHED","NODE_NO_RESULT","NODE_TIMEOUT","NODE_TYPE_UNSUPPORTED","NO_MATCHING_EDGE","OUTPUT_NODE_EMPTY","PATCH_CODE_EMPTY","PATCH_EDGE_CONFLICT","PATCH_EDGE_DANGLING","PATCH_EDGE_HANDLE_MISSING","PATCH_EDGE_MISSING","PATCH_EMPTY","PATCH_LOOP_BOUND_MISSING","PATCH_NODE_CONFLICT","PATCH_NODE_MISSING","PATCH_NO_GRAPH","PATCH_OP_UNKNOWN","REDUCER_MERGE_CONFLICT","REDUCER_WRITE_CONFLICT","RESUME_CONFLICT","RUN_REQUEST_DISABLED","RUN_REQUEST_INPUT_REQUIRED","RUN_REQUEST_NOT_FOUND","RUN_REQUEST_QUEUE_UNAVAILABLE","RUN_REQUEST_REF_AMBIGUOUS","RUN_REQUEST_REF_MISSING","SUBGRAPH_DEPTH_EXCEEDED","SUBGRAPH_FAILED","SUBGRAPH_NOT_FOUND","SUBGRAPH_NO_RESULT","SUBGRAPH_SELF_CALL","SWAP_CAPABILITY_MISMATCH","SWAP_HUB_RELEASE_UNPINNED","SWAP_NODE_NOT_FOUND","SWAP_NOT_AGENT_NODE","SWAP_NO_MATCH","SWAP_UNKNOWN_PROVIDER","TOOL_BROKER_CALL_UNREADABLE","TOOL_BROKER_MUTATION_IN_SIMULATION","TOOL_BROKER_PLAN_UNREADABLE","TOOL_BROKER_TOOL_NOT_DECLARED","TOOL_NODE_UNATTACHED","TOOL_NODE_UNCONFIGURED","TRANSFORM_MODE_UNKNOWN","TRANSFORM_NODE_UNCONFIGURED"];
+const GRAPH_JOURNAL_KINDS = ["blob_externalized","node_failed","node_intent","node_reserved","node_retry","node_routed","node_settled","resumed","run_completed","run_created","run_failed","run_validated","suspended"];
+const GRAPH_NODE_KINDS = ["action","agent","code","condition","eval","output","subgraph","tool","transform","trigger"];
+const GRAPH_BLOCK_UI = {"trigger":{"section":"none","placeable":false,"placeReason":"그래프마다 하나뿐이고 처음 만들 때 함께 지어진다"},"agent":{"section":"inventory","placeable":true},"eval":{"section":"flow","placeable":true},"condition":{"section":"flow","placeable":true},"transform":{"section":"flow","placeable":true},"code":{"section":"flow","placeable":true},"tool":{"section":"inventory","placeable":true},"action":{"section":"actions","placeable":true},"output":{"section":"flow","placeable":true},"loop":{"section":"none","placeable":false,"placeReason":"노드가 아니라 되돌아가는 연결의 성질이다 — 엣지를 이어서 만든다"},"subgraph":{"section":"flow","placeable":true}};
+
+/** 모르는 값은 원문을 보존한 채 항목 단위로 강등한다. 집합 폐기 금지. */
+function readEnum(value, allowed) {
+  const text = typeof value === "string" ? value : String(value == null ? "" : value);
+  return allowed.includes(text) ? { known: text } : { unknown: text };
+}
+
+function degradedLabel(value, lang) {
+  if (value && typeof value === "object" && "known" in value) return value.known;
+  const raw = value && value.unknown ? value.unknown : "";
+  return lang === "en" ? `unknown (raw: ${raw})` : `알 수 없음 (원문: ${raw})`;
+}
+
+module.exports = {
+  GRAPH_WIRE, GRAPH_ERROR_CODES, GRAPH_JOURNAL_KINDS, GRAPH_NODE_KINDS, GRAPH_BLOCK_UI,
+  readEnum, degradedLabel,
+};

package/engine/hephaestus/local-core.cjs

@@ -0,0 +1,159 @@
+"use strict";
+/*
+ * hephaestus/local-core — 로컬 Agentlas Core(`hephaestus mcp serve`)의 stdio MCP 클라이언트.
+ *
+ * 배경(2026-08-05, 감사 결함 E): 터미널의 편성 루프(agentlas-workforce.cjs)는 원격
+ * agentlas.cloud MCP만 쳤다. 그 서버는 공개 Hub 메뉴만 주므로 로컬·오너 Cloud를
+ * 포함한 연합(sourceScope network/local/cloud)은 물리적으로 불가능했고, hep-*
+ * 명령들은 외부 CLI 스텁(exit 3 host_llm_required)에 배선돼 있었다. 연합을
+ * 소유한 것은 로컬 Core다 — 실측(2026-08-05): `hephaestus mcp serve`가
+ * workforce.search_candidates/validate_selection/prepare_execution을 전부 노출하고,
+ * sourceScope:"local" 검색이 CandidateSet v1(reference-first)을 반환했다.
+ *
+ * 계약:
+ *  - 프로세스 수명 = 클라이언트 수명. 명령이 끝나면 반드시 close(). 데몬화 금지.
+ *  - 폴백 금지: Core 바이너리가 없으면 code="local_core_unavailable"로 정직하게
+ *    던진다 — 원격 Hub로 조용히 내려가면 스코프가 거짓이 된다.
+ *  - 응답은 MCP content[0].text의 JSON. Core가 {status:"rejected", error:…}를 주면
+ *    그 코드를 그대로 던진다(거절 원문 보존 — 재작성 금지).
+ */
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+function localCoreBin() {
+  const candidates = [
+    process.env.HEPHAESTUS_BIN,
+    path.join(os.homedir(), ".agentlas", "runtime", "current", "bin", "hephaestus"),
+  ];
+  if (process.platform === "win32") return null;
+  for (const candidate of candidates) {
+    try {
+      if (candidate && fs.existsSync(candidate)) return candidate;
+    } catch { /* keep looking */ }
+  }
+  return null;
+}
+
+function coreError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+/**
+ * createLocalCoreClient({cwd, timeoutMs}) → { call(name,args), close() }
+ * call은 initialize를 게으르게 1회 수행한 뒤 tools/call을 보낸다.
+ */
+function createLocalCoreClient({ cwd, timeoutMs = 60_000 } = {}) {
+  const bin = localCoreBin();
+  if (!bin) {
+    throw coreError(
+      "local_core_unavailable",
+      "Agentlas-OS local core (hephaestus) is not installed — federated staffing needs it. Install Agentlas-OS or set HEPHAESTUS_BIN.",
+    );
+  }
+  const child = spawn(bin, ["mcp", "serve"], {
+    cwd: cwd || process.cwd(),
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  // 프로세스 수명 = 클라이언트 수명 계약의 백스톱. close() 를 못 부르고 부모가
+  // 죽는 경로(오류 → process.exit)에서 Core 가 고아로 남는다 — 실측: 프로브
+  // 세션에서 `hephaestus mcp serve` 17개 누적. exit 훅으로 반드시 걷는다.
+  const reap = () => { try { child.kill(); } catch { /* already gone */ } };
+  process.once("exit", reap);
+  let buffer = "";
+  let nextId = 0;
+  let initialized = null;
+  const pending = new Map();
+  let exited = false;
+
+  child.on("exit", () => {
+    exited = true;
+    for (const [, entry] of pending) {
+      entry.reject(coreError("local_core_exited", "the local core process exited before responding"));
+    }
+    pending.clear();
+  });
+  child.stdout.on("data", (chunk) => {
+    buffer += chunk;
+    let index;
+    while ((index = buffer.indexOf("\n")) >= 0) {
+      const line = buffer.slice(0, index);
+      buffer = buffer.slice(index + 1);
+      if (!line.trim()) continue;
+      let message;
+      try { message = JSON.parse(line); } catch { continue; }
+      const entry = message && message.id != null ? pending.get(message.id) : null;
+      if (entry) {
+        pending.delete(message.id);
+        entry.resolve(message);
+      }
+    }
+  });
+
+  const rpc = (method, params) => new Promise((resolve, reject) => {
+    if (exited) { reject(coreError("local_core_exited", "the local core process already exited")); return; }
+    const id = ++nextId;
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(coreError("local_core_timeout", `${method} did not respond within ${timeoutMs}ms`));
+    }, timeoutMs);
+    pending.set(id, {
+      resolve: (message) => { clearTimeout(timer); resolve(message); },
+      reject: (error) => { clearTimeout(timer); reject(error); },
+    });
+    child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+  });
+
+  async function ensureInitialized() {
+    if (!initialized) {
+      initialized = rpc("initialize", {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "agentlas-terminal", version: "2" },
+      });
+    }
+    return initialized;
+  }
+
+  async function call(name, args) {
+    await ensureInitialized();
+    const response = await rpc("tools/call", { name, arguments: args });
+    if (response.error) {
+      throw coreError("local_core_rpc_error", `${name}: ${response.error.message || JSON.stringify(response.error)}`);
+    }
+    const text = response?.result?.content?.[0]?.text;
+    if (typeof text !== "string") {
+      throw coreError("local_core_invalid_response", `${name} returned no text content`);
+    }
+    let parsed;
+    try { parsed = JSON.parse(text); } catch {
+      throw coreError("local_core_invalid_response", `${name} returned non-JSON content`);
+    }
+    // Core의 거절/오류는 원문 코드로 전파한다 — 사람 문장으로 바꾸면 기계 표식이
+    // 죽는다. (실측: 경계 거절은 status:"rejected", 계약 오류는 status:"error".)
+    if (parsed && (parsed.status === "rejected" || parsed.status === "error")) {
+      const code = typeof parsed.error === "string" ? parsed.error : `local_core_${parsed.status}`;
+      // 경계 거절의 issues(무엇이 어느 path에서 걸렸나)는 유일한 진단 근거다 —
+      // 코드만 전파하면 다음 사람이 다시 프로브부터 시작한다(2026-08-05 실측 2회).
+      const issues = Array.isArray(parsed?.boundary?.issues)
+        ? parsed.boundary.issues.map((issue) => `${issue.code}@${issue.path}`).join(", ")
+        : "";
+      const error = coreError(code, `${name} ${parsed.status}: ${code}${issues ? ` [${issues}]` : ""}`);
+      error.detail = parsed;
+      throw error;
+    }
+    return parsed;
+  }
+
+  function close() {
+    process.removeListener("exit", reap);
+    try { child.kill(); } catch { /* already gone */ }
+  }
+
+  return { call, close };
+}
+
+module.exports = { createLocalCoreClient, localCoreBin };

package/engine/hephaestus/runtime.cjs

@@ -40,16 +40,12 @@ 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',
+  // 소스 스코프 스태핑(hep-network/hep-local/hep-cloud/hep-hub)과 legacy-network 의
+  // usage 는 2026-08-05 에 삭제했다. 네이티브가 편성을 수행하지 않고 exit 3 +
+  // host_llm_required 만 반환하므로, 여기에 usage 를 두면 "쓸 수 있는 명령"으로
+  // 읽힌다. 차단과 안내는 commands/index.cjs 의 HOST_LLM_ONLY_SURFACES 가 한다.
   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>"',
   netadmin: "usage: agentlas netadmin <init|status|reindex|bench|add-source> [args]",
   research: "usage: agentlas research <status|gather|search|read|plan> [args]",
   route: 'usage: agentlas route "<request>" [--json]',
@@ -644,15 +640,53 @@ function create(ctx, deps = {}) {
       process.stderr.write("Hephaestus failed: Python 3.9+ was not found.\n");
       return Promise.resolve(1);
     }
+    // Core writes nothing until its final payload. `hep search` measured 29.7s
+    // of complete silence on every stream — indistinguishable from a hang, and
+    // the command that takes longest is the one a newcomer tries first.
+    // stdout carries machine-readable JSON, so the heartbeat goes to stderr
+    // only, and only when stderr is a terminal: piping or redirecting must stay
+    // byte-identical for anything parsing this.
+    const stopHeartbeat = helpOnly ? null : startQuietChildHeartbeat(args);
     return new Promise((resolve) => {
       child.on("error", (e) => {
+        if (stopHeartbeat) stopHeartbeat();
         process.stderr.write(`Hephaestus failed: ${e.message}\n`);
         resolve(1);
       });
-      child.on("close", (code) => resolve(code == null ? 0 : code));
+      child.on("close", (code) => {
+        if (stopHeartbeat) stopHeartbeat();
+        resolve(code == null ? 0 : code);
+      });
     });
   }
 
+  /**
+   * Report elapsed time on stderr while a passthrough child stays quiet.
+   * Returns a stop function; returns null when there is nothing safe to write to.
+   */
+  function startQuietChildHeartbeat(args) {
+    if (!process.stderr.isTTY) return null;
+    const label = args.filter((a) => !String(a).startsWith("-")).slice(0, 2).join(" ") || "hephaestus";
+    const started = Date.now();
+    let painted = false;
+    const paint = () => {
+      const secs = Math.round((Date.now() - started) / 1000);
+      process.stderr.write(`\r${label} … ${secs}s`);
+      painted = true;
+    };
+    // Stay silent through the common fast case; only speak once it is slow
+    // enough that a user would start wondering.
+    const first = setTimeout(() => { paint(); }, 1500);
+    const timer = setInterval(paint, 1000);
+    if (typeof timer.unref === "function") timer.unref();
+    if (typeof first.unref === "function") first.unref();
+    return () => {
+      clearTimeout(first);
+      clearInterval(timer);
+      if (painted) process.stderr.write("\r");
+    };
+  }
+
   const HEP_USAGE = [
     "agentlas hep <hephaestus 서브커맨드…>   — 엔진 전 기능 네이티브 패스스루",
     "",