agentlas 1.0.65 → 1.0.67

package/engine/graph/interview.cjs

@@ -280,8 +280,14 @@ function triggerQuestion() {
  */
 function autofillOutputChecks(bp) {
   if (!bp || !Array.isArray(bp.steps)) return bp;
+  // 잘못된 모델 출력을 빈 목록으로 고쳐 쓰지 않는다. validateBlueprint가 retry 사유로
+  // 돌려줘야 모델이 자기 형식을 바로잡을 수 있다.
+  if (bp.checks != null && !Array.isArray(bp.checks)) return bp;
   const checks = Array.isArray(bp.checks) ? [...bp.checks] : [];
-  const checked = new Set(checks.map((c) => (c.subject || "").trim()).filter(Boolean));
+  const checked = new Set(checks
+    .filter((check) => check && typeof check === "object")
+    .map((check) => String(check.subject || "").trim())
+    .filter(Boolean));
   bp.steps.forEach((step, index) => {
     if (step.effect !== "mutation") return;
     for (const value of Array.isArray(step.consumes) ? step.consumes : []) {
@@ -310,10 +316,14 @@ function validateBlueprint(bp, ctx = {}) {
   const problems = [];
   const push = (reason, ask = null) => problems.push({ reason, ask });
   if (!bp || typeof bp !== "object") { push("만들 내용을 읽지 못했습니다."); return problems; }
-  if (!String(bp.name || "").trim()) {
+  if (typeof bp.name !== "string") {
+    push("이름(name)의 형식이 올바르지 않습니다.");
+  } else if (!bp.name.trim()) {
     push("이름이 없습니다.", { id: "name", question: "이 자동화를 뭐라고 부를까요?", why: "목록에서 이 이름으로 찾게 됩니다." });
   }
-  if (!String(bp.goal || "").trim()) {
+  if (typeof bp.goal !== "string") {
+    push("목표(goal)의 형식이 올바르지 않습니다.");
+  } else if (!bp.goal.trim()) {
     push("무엇을 위한 자동화인지가 없습니다.", {
       id: "goal", question: "이 자동화로 무엇을 얻고 싶으신가요? 한 문장이면 됩니다.",
       why: "나중에 목록에서 보고 무엇이었는지 알아보려면 필요합니다.",
@@ -323,7 +333,9 @@ function validateBlueprint(bp, ctx = {}) {
   if (!trigger || typeof trigger !== "object") {
     push("언제 시작하는지가 없습니다.", triggerQuestion());
   } else if (trigger.kind === "cron") {
-    if (!String(trigger.schedule || "").trim()) {
+    if (typeof trigger.schedule !== "string") {
+      push("실행 시각(schedule)의 형식이 올바르지 않습니다.");
+    } else if (!trigger.schedule.trim()) {
       push("실행 시각이 없습니다.", {
         id: "schedule", question: "몇 시에 돌릴까요?",
         why: "시각을 대신 정하면, 보지 않는 시간에 조용히 돌게 됩니다.",
@@ -331,18 +343,22 @@ function validateBlueprint(bp, ctx = {}) {
       });
     }
   } else if (trigger.kind === "input") {
-    if (!String(trigger.label || "").trim()) {
+    if (typeof trigger.label !== "string") {
+      push("입력 안내(label)의 형식이 올바르지 않습니다.");
+    } else if (!trigger.label.trim()) {
       push("무엇을 입력받는지가 없습니다.", {
         id: "input-label", question: "시작할 때 무엇을 입력받을까요? (예: 만들 프로젝트의 주제)",
         why: "입력창에 이 문구가 그대로 보입니다.",
       });
     }
-    if (!VAR_RE.test(String(trigger.varName || ""))) push("입력값의 이름이 올바르지 않습니다.");
+    if (typeof trigger.varName !== "string" || !VAR_RE.test(trigger.varName)) push("입력값의 이름이 올바르지 않습니다.");
   } else {
     push("언제 시작하는지를 알 수 없습니다.", triggerQuestion());
   }
 
   const steps = Array.isArray(bp.steps) ? bp.steps : [];
+  const checks = Array.isArray(bp.checks) ? bp.checks : [];
+  const branches = Array.isArray(bp.branches) ? bp.branches : [];
   if (steps.length === 0) {
     push("할 일이 하나도 없습니다.", {
       id: "steps", question: "무슨 일을 해야 하나요? 순서대로 적어 주세요.",
@@ -350,14 +366,19 @@ function validateBlueprint(bp, ctx = {}) {
     });
   }
   if (steps.length > MAX_STEPS) push(`단계가 ${steps.length}개입니다. 한 번에 만들 수 있는 것은 ${MAX_STEPS}개까지입니다.`);
+  if (bp.checks != null && !Array.isArray(bp.checks)) push("검증 목록(checks)의 형식이 올바르지 않습니다.");
+  if (bp.branches != null && !Array.isArray(bp.branches)) push("갈림길 목록(branches)의 형식이 올바르지 않습니다.");
 
   const produced = new Set();
   if (trigger && trigger.kind === "input" && trigger.varName) produced.add(trigger.varName);
   steps.forEach((step, index) => {
     const at = `${index + 1}번째 단계`;
     if (!step || typeof step !== "object") { push(`${at}를 읽지 못했습니다.`); return; }
-    if (!String(step.title || "").trim()) push(`${at}에 이름이 없습니다.`);
-    if (!String(step.instruction || "").trim()) {
+    if (typeof step.title !== "string") push(`${at}의 이름(title) 형식이 올바르지 않습니다.`);
+    else if (!step.title.trim()) push(`${at}에 이름이 없습니다.`);
+    if (typeof step.instruction !== "string") {
+      push(`${at}의 지시(instruction) 형식이 올바르지 않습니다.`);
+    } else if (!step.instruction.trim()) {
       push(`${at}가 무엇을 할지 적혀 있지 않습니다.`, {
         id: `step-${index}-instruction`,
         question: `"${step.title || at}" 단계에서 정확히 무엇을 해야 하나요?`,
@@ -372,11 +393,14 @@ function validateBlueprint(bp, ctx = {}) {
         choices: ["아니요, 만들기만 합니다", "네, 바깥으로 나갑니다"],
       });
     }
+    if (step.kind != null && !["agent", "code", "runGraph"].includes(step.kind)) {
+      push(`${at}의 실행 종류(kind) 형식이 올바르지 않습니다.`);
+    }
     // ★부를 자동화는 실재해야 한다(데스크탑 shared/graph-blueprint.ts와 같은 규칙). 이름이
     //   아니라 id로 가리키는 이유도 같다 — 이름은 바뀌고 지어낸 id는 실행에서 죽는다.
     //   목록을 모르는 호출부에서는 형식만 본다(ctx.knownGraphs 없으면 건너뜀).
     if (step.kind === "runGraph") {
-      const ref = String(step.graphRef || "").trim();
+      const ref = typeof step.graphRef === "string" ? step.graphRef.trim() : "";
       if (!ref) {
         push(`${at}가 어느 자동화를 부를지 정하지 않았습니다.`);
       } else if (ctx.selfId && ref === ctx.selfId) {
@@ -388,7 +412,9 @@ function validateBlueprint(bp, ctx = {}) {
     // ★코드 스텝은 스크립트가 있어야 한다. 없으면 "코드로 하겠다"고 해 놓고 빈 채로 저장돼
     //   실행에서 CODE_NODE_EMPTY로 죽는다(데스크탑과 같은 규칙, 저작 시점에 막는다).
     if (step.kind === "code") {
-      if (!String(step.code || "").trim()) {
+      if (typeof step.code !== "string") {
+        push(`${at}의 코드(code) 형식이 올바르지 않습니다.`);
+      } else if (!step.code.trim()) {
         push(`${at}는 코드로 실행한다고 했는데 스크립트가 비어 있습니다.`, {
           id: `step-${index}-code`,
           question: `"${step.title || at}" 단계에서 무엇을 계산·가공하나요? (AI가 스크립트를 채웁니다)`,
@@ -398,8 +424,19 @@ function validateBlueprint(bp, ctx = {}) {
       if (step.codeLang && step.codeLang !== "python" && step.codeLang !== "js") {
         push(`${at}의 코드 언어 "${step.codeLang}"을(를) 이 제품이 모릅니다(python 또는 js).`);
       }
+      if (step.packages != null && !Array.isArray(step.packages)) {
+        push(`${at}의 코드 패키지 목록(packages) 형식이 올바르지 않습니다.`);
+      } else if (Array.isArray(step.packages) && step.packages.some((value) => typeof value !== "string" || !value.trim())) {
+        push(`${at}의 코드 패키지 이름 하나가 올바르지 않습니다.`);
+      }
     }
-    for (const name of step.consumes || []) {
+    const consumes = Array.isArray(step.consumes) ? step.consumes : [];
+    if (step.consumes != null && !Array.isArray(step.consumes)) push(`${at}의 입력값 목록(consumes) 형식이 올바르지 않습니다.`);
+    for (const name of consumes) {
+      if (typeof name !== "string" || !VAR_RE.test(name)) {
+        push(`${at}의 입력값 이름 하나가 올바르지 않습니다.`);
+        continue;
+      }
       if (!produced.has(name)) {
         push(`${at}가 쓰는 "${name}" 값을 아무도 만들지 않습니다.`, {
           id: `step-${index}-consumes-${name}`,
@@ -409,7 +446,9 @@ function validateBlueprint(bp, ctx = {}) {
       }
     }
 
-    for (const use of step.uses || []) {
+    const uses = Array.isArray(step.uses) ? step.uses : [];
+    if (step.uses != null && !Array.isArray(step.uses)) push(`${at}의 도구 목록(uses) 형식이 올바르지 않습니다.`);
+    for (const use of uses) {
       if (!use || typeof use !== "object") { push(`${at}의 도구 선언을 읽지 못했습니다.`); continue; }
       if (!CAPABILITIES.includes(use.capability)) {
         push(`${at}가 이 제품이 모르는 도구("${use.capability}")를 쓰려고 합니다.`, {
@@ -430,15 +469,20 @@ function validateBlueprint(bp, ctx = {}) {
       }
     }
     if (step.produces) {
-      if (!VAR_RE.test(step.produces)) push(`${at}의 결과 이름 "${step.produces}"은(는) 쓸 수 없습니다.`);
+      if (typeof step.produces !== "string" || !VAR_RE.test(step.produces)) push(`${at}의 결과 이름 "${step.produces}"은(는) 쓸 수 없습니다.`);
       else produced.add(step.produces);
+    } else if (step.produces != null && typeof step.produces !== "string") {
+      push(`${at}의 결과 이름은 문자열이어야 합니다.`);
     }
+    if (step.role != null && typeof step.role !== "string") push(`${at}의 역할(role) 형식이 올바르지 않습니다.`);
+    if (step.roleEn != null && typeof step.roleEn !== "string") push(`${at}의 영어 역할(roleEn) 형식이 올바르지 않습니다.`);
   });
 
 
   // 검증 단계
   const checkVerdicts = new Set();
-  for (const check of bp.checks || []) {
+  for (const check of checks) {
+    if (!check || typeof check !== "object") { push("검증 항목 하나의 형식이 올바르지 않습니다."); continue; }
     const at = `${(check.afterStep ?? 0) + 1}번째 단계 뒤의 검증`;
     if (!steps[check.afterStep]) { push(`${at}가 없는 단계를 가리킵니다.`); continue; }
     if (!check.subject || !produced.has(check.subject)) {
@@ -478,7 +522,10 @@ function validateBlueprint(bp, ctx = {}) {
    */
   {
     const checkedSubjects = new Set(
-      (bp.checks || []).map((check) => (check.subject || "").trim()).filter(Boolean),
+      checks
+        .filter((check) => check && typeof check === "object")
+        .map((check) => String(check.subject || "").trim())
+        .filter(Boolean),
     );
     steps.forEach((step, index) => {
       if (step.effect !== "mutation") return;
@@ -514,8 +561,9 @@ function validateBlueprint(bp, ctx = {}) {
    */
   {
     const resultChecks = new Map();
-    for (const check of bp.checks || []) {
-      const subj = (check.subject || "").trim();
+    for (const check of checks) {
+      if (!check || typeof check !== "object") continue;
+      const subj = String(check.subject || "").trim();
       if (subj) resultChecks.set(subj, check);
     }
     steps.forEach((step, index) => {
@@ -552,7 +600,8 @@ function validateBlueprint(bp, ctx = {}) {
   }
 
   // 반복이 있는데 검증이 없으면 "마음에 들 때까지"를 글자 찾기로 흉내 내게 된다(실측).
-  for (const branch of bp.branches || []) {
+  for (const branch of branches) {
+    if (!branch || typeof branch !== "object") { push("갈림길 항목 하나의 형식이 올바르지 않습니다."); continue; }
     if (branch.repeatStep === undefined) continue;
     if (!checkVerdicts.has(branch.var)) {
       push(`${(branch.afterStep ?? 0) + 1}번째 단계 뒤의 반복이 검증 결과가 아니라 "${branch.var}"의 내용을 보고 돌지 말지 정합니다.`, {
@@ -569,15 +618,16 @@ function validateBlueprint(bp, ctx = {}) {
    *   정본은 데스크탑 shared/graph-blueprint.ts — 이 파일은 손복사본이고 패리티 게이트가 지킨다.
    */
   const emptinessTestedVars = new Set(
-    (bp.branches || [])
-      .filter((branch) => branch.op === "truthy" || branch.op === "falsy")
+    branches
+      .filter((branch) => branch && typeof branch === "object" && (branch.op === "truthy" || branch.op === "falsy"))
       .map((branch) => String(branch.var || "").trim())
       .filter(Boolean),
   );
-  for (const check of bp.checks || []) {
+  for (const check of checks) {
+    if (!check || typeof check !== "object") continue;
     const subject = String(check.subject || "").trim();
     if (!subject || !emptinessTestedVars.has(subject)) continue;
-    const branch = (bp.branches || []).find((b) => String(b.var || "").trim() === subject);
+    const branch = branches.find((b) => b && typeof b === "object" && String(b.var || "").trim() === subject);
     if (!branch) continue;
     // 위치를 본다 — 갈림길 뒤 값-있는 쪽의 검증은 비는 날 아예 안 돌므로 문제가 아니다.
     const at = typeof check.afterStep === "number" ? check.afterStep : -1;
@@ -599,7 +649,8 @@ function validateBlueprint(bp, ctx = {}) {
     );
   }
 
-  for (const branch of bp.branches || []) {
+  for (const branch of branches) {
+    if (!branch || typeof branch !== "object") continue;
     const at = `${(branch.afterStep ?? 0) + 1}번째 단계 뒤의 갈림길`;
     if (!steps[branch.afterStep]) { push(`${at}가 없는 단계를 가리킵니다.`); continue; }
     if (!OPS.has(branch.op)) { push(`${at}의 판단 방법을 알 수 없습니다.`); continue; }

package/engine/graph/package.cjs

@@ -35,14 +35,55 @@ const PERSONAL_PATH_RE = /(\/Users\/[^/\s"']+|\/home\/[^/\s"']+|C:\\Users\\[^\\\
 
 
 
-function vaultKeyFor(nodeId, key) {
-  return `${String(key).replace(/[^A-Za-z0-9]+/g, "_").toUpperCase()}`;
+function vaultKeyFor(fieldPath) {
+  return String(fieldPath).replace(/[^A-Za-z0-9]+/g, "_").toUpperCase();
 }
 
 function looksSecretValue(value) {
   return typeof value === "string" && SECRET_VALUE_PATTERNS.some((re) => re.test(value));
 }
 
+function scrubNestedConfigValue(nodeId, fieldPath, value, state) {
+  if (Array.isArray(value)) {
+    return value.map((item, index) => scrubNestedConfigValue(nodeId, `${fieldPath}[${index}]`, item, state));
+  }
+  if (!value || typeof value !== "object") return value;
+
+  const out = {};
+  for (const [key, child] of Object.entries(value)) {
+    const childPath = fieldPath ? `${fieldPath}.${key}` : key;
+    if (SECRET_KEY_RE.test(key)) {
+      const vaultKey = vaultKeyFor(childPath);
+      out[key] = `\${vault.${vaultKey}}`;
+      state.vaultTemplate.push({ key: vaultKey, kind: "secret", requiredBy: [nodeId], sourceField: childPath });
+      state.findings.push({ rule: "secret-field", nodeId, field: childPath, action: `templated:${vaultKey}` });
+      continue;
+    }
+    if (looksSecretValue(child)) {
+      state.blockers.push({
+        nodeId,
+        field: childPath,
+        reason: `"${childPath}" 값이 자격증명처럼 보입니다. 어떤 키인지 알 수 없어 자동으로 빈칸 처리할 수 없습니다.`,
+        nextAction: `이 값을 금고 변수로 바꾼 뒤(예: \${vault.MY_TOKEN}) 다시 내보내세요.`,
+      });
+      out[key] = child;
+      continue;
+    }
+    if (typeof child === "string") {
+      PERSONAL_PATH_RE.lastIndex = 0;
+      if (PERSONAL_PATH_RE.test(child)) {
+        PERSONAL_PATH_RE.lastIndex = 0;
+        out[key] = child.replace(PERSONAL_PATH_RE, "<사용자 폴더>");
+        PERSONAL_PATH_RE.lastIndex = 0;
+        state.findings.push({ rule: "personal-path", nodeId, field: childPath, action: "removed" });
+        continue;
+      }
+    }
+    out[key] = scrubNestedConfigValue(nodeId, childPath, child, state);
+  }
+  return out;
+}
+
 /**
  * 노드 설정을 훑어 비밀·모델핀·개인 경로를 처리한다.
  * 반환: { config, findings, vaultTemplate, blockers }
@@ -55,7 +96,7 @@ function scrubNodeConfig(nodeId, config) {
   for (const [key, value] of Object.entries(config || {})) {
     // 1) 비밀로 선언된 칸 — 값 유무와 무관하게 금고 변수로 바꾼다.
     if (SECRET_KEY_RE.test(key)) {
-      const vaultKey = vaultKeyFor(nodeId, key);
+      const vaultKey = vaultKeyFor(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}` });
@@ -86,7 +127,7 @@ function scrubNodeConfig(nodeId, config) {
       PERSONAL_PATH_RE.lastIndex = 0;
       continue;
     }
-    out[key] = value;
+    out[key] = scrubNestedConfigValue(nodeId, key, value, { findings, vaultTemplate, blockers });
   }
   return { config: out, findings, vaultTemplate, blockers };
 }
@@ -134,8 +175,13 @@ function buildPackage(input) {
       }
     }
     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 (typeof server === "string" && server) {
+      const existingMcp = dependencies.mcp.find((item) => item.serverSlug === server);
+      if (existingMcp) {
+        if (!existingMcp.requiredBy.includes(node.id)) existingMcp.requiredBy.push(node.id);
+      } else {
+        dependencies.mcp.push({ serverSlug: server, requiredBy: [node.id] });
+      }
     }
   }
 
@@ -210,11 +256,20 @@ function verifyPackage(pkg) {
   if (!graph || !Array.isArray(graph.nodes) || graph.nodes.length === 0) {
     problems.push("그래프에 단계가 없습니다.");
   }
-  if (manifest?.integrity?.graphDigest && graph) {
-    if (digestOf(graph) !== manifest.integrity.graphDigest) {
+  const integrity = manifest?.integrity;
+  if (integrity && typeof integrity.graphDigest === "string" && graph) {
+    if (digestOf(graph) !== integrity.graphDigest) {
       problems.push("그래프 내용이 매니페스트 지문과 다릅니다(전송 중 변형되었을 수 있습니다).");
     }
   }
+  if (!integrity || typeof integrity.graphDigest !== "string" || typeof integrity.manifestDigest !== "string") {
+    problems.push("매니페스트 무결성 지문이 없습니다.");
+  } else if (digestOf({
+    ...manifest,
+    integrity: { graphDigest: integrity.graphDigest, manifestDigest: null },
+  }) !== integrity.manifestDigest) {
+    problems.push("매니페스트 내용이 자체 지문과 다릅니다(전송 중 변형되었을 수 있습니다).");
+  }
   return problems;
 }
 

package/engine/hephaestus/local-core.cjs

@@ -22,6 +22,8 @@ const os = require("node:os");
 const path = require("node:path");
 const { spawn } = require("node:child_process");
 
+const MAX_CORE_STDOUT_LINE_BYTES = 16 * 1024 * 1024;
+
 function localCoreBin() {
   const candidates = [
     process.env.HEPHAESTUS_BIN,
@@ -66,7 +68,7 @@ function createLocalCoreClient({ cwd, timeoutMs = 60_000 } = {}) {
   // 세션에서 `hephaestus mcp serve` 17개 누적. exit 훅으로 반드시 걷는다.
   const reap = () => { try { child.kill(); } catch { /* already gone */ } };
   process.once("exit", reap);
-  let buffer = "";
+  let buffer = Buffer.alloc(0);
   let nextId = 0;
   let initialized = null;
   const pending = new Map();
@@ -93,10 +95,21 @@ function createLocalCoreClient({ cwd, timeoutMs = 60_000 } = {}) {
     failPending("local_core_transport_error", `the local core input stream failed: ${(error && error.message) || error}`);
   });
   child.stdout.on("data", (chunk) => {
-    buffer += chunk;
+    if (exited) return;
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    if (buffer.length + bytes.length > MAX_CORE_STDOUT_LINE_BYTES) {
+      failPending(
+        "local_core_response_too_large",
+        `the local core emitted a response line larger than ${MAX_CORE_STDOUT_LINE_BYTES} bytes`,
+      );
+      buffer = Buffer.alloc(0);
+      try { child.kill(); } catch { /* already gone */ }
+      return;
+    }
+    buffer = buffer.length ? Buffer.concat([buffer, bytes]) : bytes;
     let index;
-    while ((index = buffer.indexOf("\n")) >= 0) {
-      const line = buffer.slice(0, index);
+    while ((index = buffer.indexOf(0x0a)) >= 0) {
+      const line = buffer.subarray(0, index).toString("utf8");
       buffer = buffer.slice(index + 1);
       if (!line.trim()) continue;
       let message;
@@ -191,4 +204,4 @@ function createLocalCoreClient({ cwd, timeoutMs = 60_000 } = {}) {
   return { call, close };
 }
 
-module.exports = { createLocalCoreClient, localCoreBin };
+module.exports = { createLocalCoreClient, localCoreBin, MAX_CORE_STDOUT_LINE_BYTES };

package/engine/hephaestus/runtime.cjs

@@ -10,10 +10,8 @@
  *
  * v2 이식 규칙:
  *   - D.out → ctx.out, D.prefsLang() → ctx.lang.
- *   - D.runCwd — v1 검증 결과: AGENTLAS_RUN_CWD 같은 env는 v1에 존재하지 않았다.
- *     v1 runCwd()의 실제 동작 = userDataDir()/agent-cwd 샌드박스(mkdir, 실패 시
- *     homedir 폴백). 그 동작을 그대로 보존해 여기 로컬로 이식했다. (프로젝트
- *     실행 위치가 필요한 곳은 v1과 동일하게 projectCwd()를 쓴다.)
+ *   - D.runCwd — Terminal 정본(project/paths.cjs)의 private agent-cwd 경계를 쓴다.
+ *     생성 실패 시 홈 폴더로 권한을 넓히지 않는다.
  *   - 런타임 발견은 engine/agentlas-core-harness.cjs(복원본)를 소비만 한다.
  *   - 런타임 부재 = 정직 정지(exit 1) + v1 설치 안내 문구 그대로. 폴백 금지.
  *
@@ -30,8 +28,10 @@ const { Ui } = require("../agentlas-ui.cjs");
 const { truncateWidth, visWidth, wrapWidth } = require("../ui/width.cjs");
 const coreHarness = require("../agentlas-core-harness.cjs");
 const { userDataDir } = require("../core/paths.cjs");
+const { runCwd, projectCwd } = require("../project/paths.cjs");
 
 const { CONTEXT_MAP_MIN_CORE_VERSION, resolveContextMapCoreRoot } = coreHarness;
+const CAPTURE_KILL_GRACE_MS = 250;
 
 // ── 명령 usage 문자열 (v1 TOP_LEVEL_COMMAND_USAGE에서 hephaestus 클러스터만 발췌) ──
 const USAGE = Object.freeze({
@@ -47,7 +47,7 @@ const USAGE = Object.freeze({
   hephaestus: "usage: agentlas hephaestus <subcommand> [args]",
   journal: "usage: agentlas journal <status|verify|repair|gate> --run-id <id> | --journal <path>",
   netadmin: "usage: agentlas netadmin <init|status|reindex|bench|add-source> [args]",
-  research: "usage: agentlas research <status|gather|search|read|plan> [args]",
+  research: "usage: agentlas research <subcommand> [args] (full list: agentlas research --help)",
   route: 'usage: agentlas route "<request>" [--json]',
 });
 
@@ -66,6 +66,13 @@ function isHelpToken(value) {
   return value === "help" || value === "--help" || value === "-h";
 }
 
+function isHelpRequest(args) {
+  if (!Array.isArray(args) || !args.length) return false;
+  if (args.length === 1) return isHelpToken(args[0]);
+  if (args.length === 2 && args[1] === "help") return true;
+  return args.some((value) => value === "--help" || value === "-h");
+}
+
 // ── 라우팅/리서치 미리보기 모델 (v1 module-level 순수 함수, 그대로) ──
 function routePreviewModel(value) {
   const json = value && typeof value === "object" ? value : {};
@@ -204,31 +211,6 @@ function create(ctx, deps = {}) {
     return new Ui({ lang: uiLang || lang() });
   }
 
-  // v1 agentlas.cjs runCwd() 그대로: 에이전트 전용 안전 샌드박스 폴더.
-  // (검증: v1에 AGENTLAS_RUN_CWD env는 없었다 — process.cwd() 매핑이 아니라
-  //  이 샌드박스가 원래 동작이므로 그대로 보존한다.)
-  function runCwd() {
-    const dir = path.join(userDataDir(), "agent-cwd");
-    try {
-      fs.mkdirSync(dir, { recursive: true });
-      return dir;
-    } catch {
-      return os.homedir();
-    }
-  }
-
-  // v1: 에이전트가 실제로 실행될 작업 폴더 = 사용자가 명령을 친 현재 디렉터리.
-  // 단, home/userData/agent-cwd 같은 "프로젝트 아님" 위치면 샌드박스로 폴백.
-  function projectCwd() {
-    try {
-      const cwd = process.cwd();
-      if (!cwd || cwd === os.homedir() || cwd === userDataDir() || cwd === runCwd()) return runCwd();
-      return cwd;
-    } catch {
-      return runCwd();
-    }
-  }
-
   // ── Hephaestus 런타임 해석 (설치 런처 우선, 앱 번들 폴백) ──
   // v1 후보 순서 그대로: HEPHAESTUS_BIN → ~/.agentlas/runtime/current/bin/hephaestus
   // → Core python 모듈(resolveCoreRuntimeRoot). win32는 bin 후보를 건너뛴다(v1 동일).
@@ -300,29 +282,44 @@ function create(ctx, deps = {}) {
       let overflow = false;
       let timedOut = false;
       let settled = false;
+      let forceKillTimer = null;
+      const terminate = () => {
+        if (settled) return;
+        try { child.kill("SIGTERM"); } catch { /* already gone */ }
+        if (forceKillTimer) return;
+        forceKillTimer = setTimeout(() => {
+          forceKillTimer = null;
+          if (!settled) {
+            try { child.kill("SIGKILL"); } catch { /* already gone */ }
+          }
+        }, CAPTURE_KILL_GRACE_MS);
+        if (forceKillTimer.unref) forceKillTimer.unref();
+      };
       const append = (target, chunk) => {
         if (overflow) return;
         bytes += chunk.length;
         if (bytes > maxBytes) {
           overflow = true;
-          child.kill("SIGTERM");
+          terminate();
           return;
         }
         target.push(chunk);
       };
       child.stdout.on("data", (chunk) => append(stdout, Buffer.from(chunk)));
       child.stderr.on("data", (chunk) => append(stderr, Buffer.from(chunk)));
-      const onInterrupt = () => child.kill("SIGINT");
+      const onInterrupt = () => terminate();
       process.once("SIGINT", onInterrupt);
       const timer = setTimeout(() => {
         timedOut = true;
-        child.kill("SIGTERM");
+        terminate();
       }, timeoutMs);
       if (timer.unref) timer.unref();
       const done = (code, error) => {
         if (settled) return;
         settled = true;
         clearTimeout(timer);
+        if (forceKillTimer) clearTimeout(forceKillTimer);
+        forceKillTimer = null;
         process.removeListener("SIGINT", onInterrupt);
         resolve({
           code: overflow || timedOut || error ? 1 : (code ?? 0),
@@ -426,14 +423,15 @@ function create(ctx, deps = {}) {
         ui.line("  " + (index === 0 ? ui.c.paw("✗ ") : "  ") + ui.c.text(line));
       });
     };
-    if (json) renderRoutePreview(json, ui);
+    if (result.overflow || result.timedOut) {
+      if (result.overflow) renderError(ui.lang === "ko" ? "라우팅 출력이 2MB 제한을 넘었습니다." : "Route output exceeded the 2 MB limit.");
+      if (result.timedOut) renderError(ui.lang === "ko" ? "라우팅이 30초 제한을 넘었습니다." : "Route timed out after 30 seconds.");
+    } else if (json) renderRoutePreview(json, ui);
     else {
       const detail = (result.stderr || result.stdout || "").trim();
       const message = detail || (ui.lang === "ko" ? "라우팅 결과를 읽지 못했습니다." : "Could not read the route result.");
       renderError(message);
     }
-    if (result.overflow) renderError(ui.lang === "ko" ? "라우팅 출력이 2MB 제한을 넘었습니다." : "Route output exceeded the 2 MB limit.");
-    if (result.timedOut) renderError(ui.lang === "ko" ? "라우팅이 30초 제한을 넘었습니다." : "Route timed out after 30 seconds.");
     return result.code;
   }
 
@@ -551,7 +549,7 @@ function create(ctx, deps = {}) {
   }
 
   async function runHephaestusResearch(args, opts = {}) {
-    if (args.some((arg) => arg === "--help" || arg === "-h" || arg === "help")) {
+    if (isHelpRequest(args)) {
       return runHephaestusInteractive(args, { ...opts, human: false });
     }
     const raw = args.includes("--json");
@@ -573,8 +571,13 @@ function create(ctx, deps = {}) {
     const preview = json ? researchPreviewModel(json) : null;
     const code = result.code !== 0 || preview?.totalEvidenceFailure ? 1 : 0;
     if (raw) {
-      if (result.stdout) process.stdout.write(result.stdout);
-      if (result.stderr) process.stderr.write(result.stderr);
+      if (!result.overflow && !result.timedOut) {
+        if (result.stdout) process.stdout.write(result.stdout);
+        if (result.stderr) process.stderr.write(result.stderr);
+      } else {
+        if (result.overflow) process.stderr.write("Research output exceeded the 2 MB limit.\n");
+        if (result.timedOut) process.stderr.write("Research timed out after 60 seconds.\n");
+      }
       return code;
     }
     const renderError = (message) => {
@@ -583,15 +586,16 @@ function create(ctx, deps = {}) {
         ui.line("  " + (index === 0 ? ui.c.paw("✗ ") : "  ") + ui.c.text(line));
       });
     };
-    if (json) {
+    if (result.overflow || result.timedOut) {
+      if (result.overflow) renderError(ui.lang === "ko" ? "리서치 출력이 2MB 제한을 넘었습니다." : "Research output exceeded the 2 MB limit.");
+      if (result.timedOut) renderError(ui.lang === "ko" ? "리서치가 60초 제한을 넘었습니다." : "Research timed out after 60 seconds.");
+    } else if (json) {
       renderResearchPreview(json, ui);
     } else {
       const message = (result.stderr || result.stdout || "").trim()
         || (ui.lang === "ko" ? "리서치 결과를 읽지 못했습니다." : "Could not read the research result.");
       renderError(message);
     }
-    if (result.overflow) renderError(ui.lang === "ko" ? "리서치 출력이 2MB 제한을 넘었습니다." : "Research output exceeded the 2 MB limit.");
-    if (result.timedOut) renderError(ui.lang === "ko" ? "리서치가 60초 제한을 넘었습니다." : "Research timed out after 60 seconds.");
     return code;
   }
 
@@ -638,7 +642,7 @@ function create(ctx, deps = {}) {
       }
       return Promise.resolve(1);
     }
-    const helpOnly = args.some((arg) => arg === "--help" || arg === "-h" || arg === "help");
+    const helpOnly = isHelpRequest(args);
     const cwd = opts.cwd || (helpOnly ? process.cwd() : runCwd());
     const moduleName = found.kind === "python" && isCareerGraph ? "career_graph" : "agentlas_cloud";
     const moduleArgs = moduleName === "career_graph" ? args.slice(1) : args;
@@ -744,5 +748,6 @@ module.exports = {
   USAGE,
   usageFor,
   isHelpToken,
+  isHelpRequest,
   CONTEXT_MAP_MIN_CORE_VERSION,
 };