triflux 4.2.9 → 5.0.0

package/bin/tfx-doctor.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // tfx-doctor — triflux doctor 바로가기
 import { dirname } from "path";
 import { fileURLToPath } from "url";

package/bin/tfx-setup.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // tfx-setup — triflux setup 바로가기
 import { dirname } from "path";
 import { fileURLToPath } from "url";

package/bin/triflux.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // triflux CLI — setup, doctor, version
 import { copyFileSync, existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, readdirSync, unlinkSync, rmSync, statSync, openSync, closeSync } from "fs";
 import { join, dirname } from "path";

package/hub/middleware/request-logger.mjs

@@ -0,0 +1,81 @@
+/**
+ * Hub HTTP 서버 요청 로깅 미들웨어.
+ *
+ * raw http.createServer에 맞춘 래퍼. Express가 아닌 triflux Hub 전용.
+ *
+ * 사용법 (server.mjs에서):
+ *   import { wrapRequestHandler } from './middleware/request-logger.mjs';
+ *   const httpServer = createHttpServer(wrapRequestHandler(originalHandler));
+ *
+ * 각 요청에 correlationId를 할당하고, 응답 완료 시 구조화 로그를 남긴다.
+ * health/status 체크는 로깅을 건너뛴다.
+ */
+import { withRequestContext, getCorrelationId } from '../../scripts/lib/context.mjs';
+import { createModuleLogger } from '../../scripts/lib/logger.mjs';
+
+const log = createModuleLogger('hub');
+
+const SKIP_PATHS = new Set(['/health', '/healthz', '/status', '/ready']);
+
+/**
+ * 원본 request handler를 래핑하여 로깅 + 컨텍스트 전파를 추가한다.
+ *
+ * @param {function(import('http').IncomingMessage, import('http').ServerResponse): void} handler
+ * @returns {function(import('http').IncomingMessage, import('http').ServerResponse): void}
+ */
+export function wrapRequestHandler(handler) {
+  return (req, res) => {
+    const path = getRequestPath(req.url);
+
+    if (SKIP_PATHS.has(path)) {
+      return handler(req, res);
+    }
+
+    const correlationId =
+      req.headers['x-correlation-id'] ||
+      req.headers['x-request-id'] ||
+      undefined; // withRequestContext will generate one
+
+    withRequestContext(
+      {
+        correlationId,
+        method: req.method,
+        path,
+      },
+      () => {
+        const startTime = process.hrtime.bigint();
+
+        // 응답 헤더에 상관 ID 포함
+        const cid = getCorrelationId();
+        if (cid) res.setHeader('X-Correlation-ID', cid);
+
+        // 응답 완료 시 로깅
+        res.on('finish', () => {
+          const duration = Number(process.hrtime.bigint() - startTime) / 1_000_000;
+          const level = res.statusCode >= 500 ? 'error'
+            : res.statusCode >= 400 ? 'warn'
+            : 'info';
+
+          log[level](
+            {
+              status: res.statusCode,
+              duration: Math.round(duration * 100) / 100,
+              contentLength: res.getHeader('content-length') || 0,
+            },
+            'http.response',
+          );
+        });
+
+        handler(req, res);
+      },
+    );
+  };
+}
+
+function getRequestPath(url = '/') {
+  try {
+    return new URL(url, 'http://127.0.0.1').pathname;
+  } catch {
+    return String(url).replace(/\?.*/, '') || '/';
+  }
+}

package/hub/pipeline/index.mjs

@@ -2,6 +2,9 @@
 //
 // 상태(state.mjs) + 전이(transitions.mjs) 통합 인터페이스
 
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
 import { canTransition, transitionPhase, ralphRestart, TERMINAL } from './transitions.mjs';
 import {
   ensurePipelineTable,
@@ -92,6 +95,22 @@ export function createPipeline(db, teamName, opts = {}) {
       state = updatePipelineState(db, teamName, { artifacts });
     },
 
+    /**
+     * Plan 파일을 .tfx/plans/{teamName}-plan.md 에 기록하고
+     * artifact('plan_path')에 절대 경로를 저장한다.
+     * @param {string} content - Plan markdown 내용
+     * @returns {string} 절대 경로
+     */
+    writePlanFile(content) {
+      const safeName = teamName.replace(/[<>:"/\\|?*\x00-\x1f]/g, '_');
+      const planDir = resolve(process.cwd(), '.tfx', 'plans');
+      mkdirSync(planDir, { recursive: true });
+      const planPath = join(planDir, `${safeName}-plan.md`);
+      writeFileSync(planPath, content, 'utf8');
+      this.setArtifact('plan_path', planPath);
+      return planPath;
+    },
+
     /**
      * 터미널 상태 여부
      */

package/hub/server.mjs

@@ -19,6 +19,10 @@ import { createTools } from './tools.mjs';
 import { ensurePipelineStateDbPath } from './pipeline/state.mjs';
 import { DelegatorService } from './delegator/index.mjs';
 import { createDelegatorMcpWorker } from './workers/delegator-mcp.mjs';
+import { createModuleLogger } from '../scripts/lib/logger.mjs';
+import { wrapRequestHandler } from './middleware/request-logger.mjs';
+
+const hubLog = createModuleLogger('hub');
 
 const MAX_BODY_SIZE = 1024 * 1024;
 const PUBLIC_PATHS = new Set(['/', '/status', '/health', '/healthz']);
@@ -230,7 +234,7 @@ function servePublicFile(res, path) {
 
   mkdirSync(PUBLIC_DIR, { recursive: true });
   if (!existsSync(filePath)) {
-    console.warn(`[tfx-hub] 정적 파일 없음: ${filePath}`);
+    hubLog.warn({ filePath }, 'static.not_found');
     res.writeHead(404);
     res.end('Not Found (static file missing)');
     return true;
@@ -326,7 +330,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
     return mcp;
   }
 
-  const httpServer = createHttpServer(async (req, res) => {
+  const httpServer = createHttpServer(wrapRequestHandler(async (req, res) => {
     const path = getRequestPath(req.url);
     const corsAllowed = applyCorsHeaders(req, res);
 
@@ -685,7 +689,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
         res.end('Method Not Allowed');
       }
     } catch (error) {
-      console.error('[tfx-hub] 요청 처리 에러:', error.message);
+      hubLog.error({ err: error }, 'http.error');
       if (!res.headersSent) {
         const code = error.statusCode === 413 ? 413
           : error instanceof SyntaxError ? 400 : 500;
@@ -699,7 +703,7 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
         }));
       }
     }
-  });
+  }));
 
   router.startSweeper();
 
@@ -751,8 +755,8 @@ export async function startHub({ port = 27888, dbPath, host = '127.0.0.1', sessi
         started: Date.now(),
       }));
 
-      console.log(`[tfx-hub] MCP 서버 시작: ${info.url} / pipe ${pipe.path} / assign-callback ${assignCallbacks.path} (PID ${process.pid})`);
-      console.log(`[tfx-hub] PUBLIC_DIR: ${PUBLIC_DIR} (exists: ${existsSync(PUBLIC_DIR)}, dashboard: ${existsSync(resolve(PUBLIC_DIR, 'dashboard.html'))})`);
+      hubLog.info({ url: info.url, pipePath: pipe.path, assignCallbackPath: assignCallbacks.path, pid: process.pid }, 'hub.started');
+      hubLog.debug({ publicDir: PUBLIC_DIR, exists: existsSync(PUBLIC_DIR), hasDashboard: existsSync(resolve(PUBLIC_DIR, 'dashboard.html')) }, 'hub.public_dir');
 
       const stopFn = async () => {
         router.stopSweeper();
@@ -805,14 +809,14 @@ if (selfRun) {
 
   startHub({ port, dbPath }).then((info) => {
     const shutdown = async (signal) => {
-      console.log(`\n[tfx-hub] ${signal} 수신, 종료 중...`);
+      hubLog.info({ signal }, 'hub.stopping');
       await info.stop();
       process.exit(0);
     };
     process.on('SIGINT', () => shutdown('SIGINT'));
     process.on('SIGTERM', () => shutdown('SIGTERM'));
   }).catch((error) => {
-    console.error('[tfx-hub] 시작 실패:', error.message);
+    hubLog.fatal({ err: error }, 'hub.start_failed');
     process.exit(1);
   });
 }

package/hub/team/native.mjs

@@ -10,9 +10,17 @@ import * as fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 
-const ROUTE_SCRIPT = "~/.claude/scripts/tfx-route.sh";
-export const SLIM_WRAPPER_SUBAGENT_TYPE = "slim-wrapper";
-const ROUTE_LOG_RE = /\[tfx-route\]/i;
+const ROUTE_SCRIPT = "~/.claude/scripts/tfx-route.sh";
+export const SLIM_WRAPPER_SUBAGENT_TYPE = "slim-wrapper";
+/** scout 역할 기본 설정 — read-only 탐색 전용 */
+export const SCOUT_ROLE_CONFIG = {
+  cli: "codex",
+  role: "scientist",
+  mcp_profile: "analyze",
+  maxIterations: 2,
+  readOnly: true,
+};
+const ROUTE_LOG_RE = /\[tfx-route\]/i;
 const ROUTE_COMMAND_RE = /(?:^|[\s"'`])(?:bash\s+)?(?:[^"'`\s]*\/)?tfx-route\.sh\b/i;
 const ROUTE_PROMPT_RE = /tfx-route\.sh/i;
 const DIRECT_TOOL_BYPASS_RE = /\b(?:Read|Edit|Write)\s*\(/;
@@ -143,9 +151,10 @@ function getRouteTimeout(role, _mcpProfile) {
  * @param {number} [opts.workerIndex] — 검색 힌트 회전에 사용할 워커 인덱스(1-based)
  * @param {string} [opts.searchTool] — 전용 검색 도구 힌트(brave-search|tavily|exa)
  * @param {number} [opts.bashTimeout] — (deprecated, async에서는 무시됨)
+ * @param {number} [opts.maxIterations=3] — 피드백 루프 최대 반복 횟수
  * @returns {string} 슬림 래퍼 프롬프트
  */
-export function buildSlimWrapperPrompt(cli, opts = {}) {
+export function buildSlimWrapperPrompt(cli, opts = {}) {
   const {
     subtask,
     role = "executor",
@@ -157,30 +166,36 @@ export function buildSlimWrapperPrompt(cli, opts = {}) {
     workerIndex,
     searchTool = "",
     pipelinePhase = "",
+    maxIterations = 3,
   } = opts;
 
   const routeTimeoutSec = getRouteTimeout(role, mcp_profile);
   const escaped = subtask.replace(/'/g, "'\\''");
-  const pipelineHint = pipelinePhase
-    ? `\n파이프라인 단계: ${pipelinePhase}`
-    : '';
-  const routeEnvPrefix = buildRouteEnvPrefix(agentName, workerIndex, searchTool);
+  const pipelineHint = pipelinePhase
+    ? `\n파이프라인 단계: ${pipelinePhase}`
+    : '';
+  const routeEnvPrefix = buildRouteEnvPrefix(agentName, workerIndex, searchTool);
+  const scoutConstraint = (role === "scout" || role === "scientist")
+    ? "\n이 워커는 scout(탐색 전용)이다. 코드를 수정하거나 파일을 생성하지 마라. 기존 코드를 읽고 분석하여 보고만 하라."
+    : "";
 
   // Bash 도구 timeout (모두 600초 이내)
   const launchTimeoutMs = 15000;   // Step 1: fork + job_id 반환
   const waitTimeoutMs = 570000;    // Step 2: 내부 폴링 (540초 대기 + 여유)
   const resultTimeoutMs = 30000;   // Step 3: 결과 읽기
 
-  return `실행 프로토콜 (subagent_type="${SLIM_WRAPPER_SUBAGENT_TYPE}", async):
-1. --async로 백그라운드 시작 → JOB_ID 수신
-2. --job-wait로 완료 대기 (내부 15초 간격 폴링, 최대 540초)
-3. "still_running"이면 Step 2 반복, "done"이면 --job-result로 결과 수집
-4. TaskUpdate + SendMessage → 종료${pipelineHint}
+  return `실행 프로토콜 (subagent_type="${SLIM_WRAPPER_SUBAGENT_TYPE}", async + feedback):
+MAX_ITERATIONS = ${maxIterations}
+ITERATION = 0${pipelineHint}
 
-[HARD CONSTRAINT] 허용 도구: Bash, TaskUpdate, TaskGet, TaskList, SendMessage만 사용한다.
-Read, Edit, Write, Grep, Glob, Agent, WebSearch, WebFetch 등 다른 모든 도구 사용을 금지한다.
-코드를 직접 읽거나 수정하면 안 된다. 반드시 아래 Bash 명령(tfx-route.sh)을 통해 Codex/Gemini에 위임하라.
-이 규칙을 위반하면 작업 실패로 간주한다.
+Step 0 — 시작 보고 (턴 경계 생성):
+TaskUpdate(taskId: "${taskId}", status: "in_progress")
+SendMessage(type: "message", recipient: "${leadName}", content: "작업 시작: ${agentName}", summary: "task ${taskId} started")
+
+[HARD CONSTRAINT] 허용 도구: Bash, TaskUpdate, TaskGet, TaskList, SendMessage만 사용한다.
+Read, Edit, Write, Grep, Glob, Agent, WebSearch, WebFetch 등 다른 모든 도구 사용을 금지한다.
+코드를 직접 읽거나 수정하면 안 된다. 반드시 아래 Bash 명령(tfx-route.sh)을 통해 Codex/Gemini에 위임하라.
+이 규칙을 위반하면 작업 실패로 간주한다.${scoutConstraint}
 
 gemini/codex를 직접 호출하지 마라. 반드시 tfx-route.sh를 거쳐야 한다.
 프롬프트를 파일로 저장하지 마라. tfx-route.sh가 인자로 받는다.
@@ -193,29 +208,64 @@ Step 2 — 완료 대기 (내부 폴링, 최대 540초):
 Bash(command: 'bash ${ROUTE_SCRIPT} --job-wait JOB_ID 540', timeout: ${waitTimeoutMs})
 → 주기적 "waiting elapsed=Ns progress=NB" 출력 후 최종 상태:
   "done" → Step 3으로
-  "timeout" 또는 "failed ..." → Step 4로 (실패 보고)
+  "timeout" 또는 "failed ..." → Step 4로 (실패 상태로)
   "still_running ..." → Step 2 반복 (같은 명령 재실행)
 
 Step 3 — 결과 수집:
 Bash(command: 'bash ${ROUTE_SCRIPT} --job-result JOB_ID', timeout: ${resultTimeoutMs})
-→ 출력이 워커 실행 결과이다.
+→ RESULT에 저장.
 
-Step 4 — Claude Code 태스크 동기화 (반드시 실행):
+Step 4 — 결과 보고 (턴 경계 생성, TaskUpdate 하지 않음):
 "done"이면:
-  TaskUpdate(taskId: "${taskId}", status: "completed", metadata: {result: "success"})
-  SendMessage(type: "message", recipient: "${leadName}", content: "완료: ${agentName}", summary: "task ${taskId} success")
+  SendMessage(type: "message", recipient: "${leadName}", content: "결과 (iteration ITERATION): ${agentName} 성공\\n{결과 요약}", summary: "task ${taskId} iteration ITERATION done")
 "timeout" 또는 "failed"이면:
-  TaskUpdate(taskId: "${taskId}", status: "completed", metadata: {result: "failed", error: "상태 메시지"})
-  SendMessage(type: "message", recipient: "${leadName}", content: "실패: ${agentName} (상태)", summary: "task ${taskId} failed")
+  SendMessage(type: "message", recipient: "${leadName}", content: "결과 (iteration ITERATION): ${agentName} 실패\\n{에러 요약}", summary: "task ${taskId} iteration ITERATION failed")
 TFX_NEEDS_FALLBACK 출력 감지 시:
-  TaskUpdate(taskId: "${taskId}", status: "completed", metadata: {result: "fallback", reason: "claude-native"})
-  SendMessage(type: "message", recipient: "${leadName}", content: "fallback 필요: ${agentName} — claude-native 역할은 Claude Agent로 위임 필요", summary: "task ${taskId} fallback")
-
-Step 5 — TaskUpdate + SendMessage 후 즉시 종료. 추가 도구 호출 금지.`;
-}
-
-/**
- * v3 하이브리드 래퍼 프롬프트 생성
+  → Step 6으로 즉시 이동 (fallback은 재실행 불가)
+
+Step 5 — 피드백 대기:
+SendMessage 후 너는 IDLE 상태가 된다. 리드의 응답을 기다려라.
+수신 메시지에 따라:
+  - "재실행:" 포함 → ITERATION++ → ITERATION < MAX_ITERATIONS이면 메시지의 지시를 반영하여 Step 1로. ITERATION >= MAX_ITERATIONS이면 Step 6으로 (반복 한도 초과)
+  - "승인" 또는 기타 → Step 6으로
+  - 메시지 없이 팀이 삭제되면 자동 종료 (처리 불필요)
+
+Step 6 — 최종 종료 (반드시 실행):
+TaskUpdate(taskId: "${taskId}", status: "completed", metadata: {result: "success"|"failed"|"fallback", iterations: ITERATION})
+SendMessage(type: "message", recipient: "${leadName}", content: "최종 완료: ${agentName} (ITERATION회 실행)", summary: "task ${taskId} final")
+→ 종료. 이후 추가 도구 호출 금지.`;
+}
+
+/**
+ * scout 파견용 프롬프트 생성
+ * @param {object} opts
+ * @param {string} opts.question — 탐색 질문
+ * @param {string} [opts.scope] — 탐색 범위 힌트 (파일 패턴)
+ * @param {string} [opts.teamName] — 팀 이름
+ * @param {string} [opts.taskId] — 태스크 ID
+ * @param {string} [opts.agentName] — 에이전트 이름
+ * @param {string} [opts.leadName] — 리드 이름
+ * @returns {string} slim wrapper 프롬프트
+ */
+export function buildScoutDispatchPrompt(opts = {}) {
+  const { question, scope = "", teamName, taskId, agentName, leadName } = opts;
+  const subtask = scope
+    ? `${question} 탐색 범위: ${scope}`
+    : question;
+  return buildSlimWrapperPrompt("codex", {
+    subtask,
+    role: "scientist",
+    teamName,
+    taskId,
+    agentName,
+    leadName,
+    mcp_profile: "analyze",
+    maxIterations: SCOUT_ROLE_CONFIG.maxIterations,
+  });
+}
+
+/**
+ * v3 하이브리드 래퍼 프롬프트 생성
  * psmux pane 기반 비동기 실행 + polling 패턴.
  * Agent가 idle 상태를 유지하여 인터럽트 수신이 가능하다.
  *

package/hub/team/routing.mjs

@@ -0,0 +1,154 @@
+/**
+ * 라우팅 결정 함수
+ * @param {object} opts
+ * @param {Array<{id:string, description?:string, agent?:string, depends_on?:string[], complexity?:string}>} opts.subtasks
+ * @param {string} opts.graph_type - "INDEPENDENT" | "SEQUENTIAL" | "DAG"
+ * @param {boolean} opts.thorough - thorough 모드 여부
+ * @returns {{
+ *   strategy: "quick_single" | "thorough_single" | "quick_team" | "thorough_team" | "batch_single",
+ *   reason: string,
+ *   dag_width: number,
+ *   max_complexity: string
+ * }}
+ */
+export function resolveRoutingStrategy({ subtasks, graph_type, thorough }) {
+  const N = subtasks.length;
+  if (N === 0) {
+    return { strategy: 'quick_single', reason: 'empty_subtasks', dag_width: 0, max_complexity: 'S' };
+  }
+
+  const dag_width = computeDagWidth(subtasks, graph_type);
+  const max_complexity = getMaxComplexity(subtasks);
+  const isHighComplexity = ['L', 'XL'].includes(max_complexity);
+  const allSameAgent = new Set(subtasks.map((s) => s.agent)).size === 1;
+  const allSmall = subtasks.every((s) => normalizeComplexity(s.complexity) === 'S');
+
+  // N==1: 단일 태스크
+  if (N === 1) {
+    if (thorough || isHighComplexity) {
+      return {
+        strategy: 'thorough_single',
+        reason: 'single_high_complexity',
+        dag_width,
+        max_complexity,
+      };
+    }
+    return {
+      strategy: 'quick_single',
+      reason: 'single_low_complexity',
+      dag_width,
+      max_complexity,
+    };
+  }
+
+  // dag_width==1: 사실상 순차 -> single
+  if (dag_width === 1) {
+    if (thorough || isHighComplexity) {
+      return {
+        strategy: 'thorough_single',
+        reason: 'sequential_chain',
+        dag_width,
+        max_complexity,
+      };
+    }
+    return {
+      strategy: 'quick_single',
+      reason: 'sequential_chain',
+      dag_width,
+      max_complexity,
+    };
+  }
+
+  // 동일 에이전트 + 모두 S: 프롬프트 병합 -> batch single
+  if (allSameAgent && allSmall) {
+    return {
+      strategy: 'batch_single',
+      reason: 'same_agent_small_batch',
+      dag_width,
+      max_complexity,
+    };
+  }
+
+  // dag_width >= 2: 팀
+  if (thorough || isHighComplexity) {
+    return {
+      strategy: 'thorough_team',
+      reason: 'parallel_high_complexity',
+      dag_width,
+      max_complexity,
+    };
+  }
+  return {
+    strategy: 'quick_team',
+    reason: 'parallel_low_complexity',
+    dag_width,
+    max_complexity,
+  };
+}
+
+/**
+ * DAG 폭 계산 - 레벨별 최대 병렬 태스크 수
+ * @param {Array<{id:string, depends_on?:string[]}>} subtasks
+ * @param {string} graph_type
+ * @returns {number}
+ */
+function computeDagWidth(subtasks, graph_type) {
+  if (graph_type === 'SEQUENTIAL') return 1;
+  if (graph_type === 'INDEPENDENT') return subtasks.length;
+
+  // DAG: 레벨별 계산 (순환 의존 방어)
+  const levels = {};
+  const visiting = new Set();
+
+  function getLevel(task) {
+    if (levels[task.id] !== undefined) return levels[task.id];
+    if (visiting.has(task.id)) {
+      levels[task.id] = 0; // 순환 끊기
+      return 0;
+    }
+    if (!task.depends_on || task.depends_on.length === 0) {
+      levels[task.id] = 0;
+      return 0;
+    }
+    visiting.add(task.id);
+    const depLevels = task.depends_on.map((depId) => {
+      const dep = subtasks.find((s) => s.id === depId);
+      return dep ? getLevel(dep) : 0;
+    });
+    visiting.delete(task.id);
+    levels[task.id] = Math.max(...depLevels) + 1;
+    return levels[task.id];
+  }
+
+  subtasks.forEach(getLevel);
+
+  const levelCounts = {};
+  for (const level of Object.values(levels)) {
+    levelCounts[level] = (levelCounts[level] || 0) + 1;
+  }
+  return Math.max(...Object.values(levelCounts), 1);
+}
+
+/**
+ * 최대 복잡도 추출
+ * @param {Array<{complexity?:string}>} subtasks
+ * @returns {"S" | "M" | "L" | "XL"}
+ */
+function getMaxComplexity(subtasks) {
+  const order = { S: 0, M: 1, L: 2, XL: 3 };
+  let max = 'S';
+  for (const s of subtasks) {
+    const complexity = normalizeComplexity(s.complexity);
+    if (order[complexity] > order[max]) max = complexity;
+  }
+  return max;
+}
+
+/**
+ * complexity 기본값 보정
+ * @param {string | undefined} complexity
+ * @returns {"S" | "M" | "L" | "XL"}
+ */
+function normalizeComplexity(complexity) {
+  return ['S', 'M', 'L', 'XL'].includes(complexity) ? complexity : 'M';
+}

package/hub/tools.mjs

@@ -472,7 +472,72 @@ export function createTools(store, router, hitl, pipe = null) {
       }),
     },
 
-    // ── 19. pipeline_list ──
+    // ── 19. pipeline_advance_gated (HITL 승인 게이트) ──
+    {
+      name: 'pipeline_advance_gated',
+      description: 'HITL 승인 게이트가 포함된 파이프라인 전이. 지정 단계로의 전이 전 사용자 승인을 요청하고, 승인 후 전이를 실행합니다. deadline 초과 시 default_action에 따라 자동 처리됩니다.',
+      inputSchema: {
+        type: 'object',
+        required: ['team_name', 'phase'],
+        properties: {
+          team_name: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]*$' },
+          phase: { type: 'string', enum: ['plan', 'prd', 'exec', 'verify', 'fix', 'complete', 'failed'] },
+          prompt: { type: 'string', description: '사용자에게 표시할 승인 요청 메시지' },
+          deadline_ms: { type: 'integer', minimum: 5000, maximum: 600000, default: 120000 },
+          default_action: { type: 'string', enum: ['timeout_continue', 'timeout_abort'], default: 'timeout_continue' },
+          requester_agent: { type: 'string', description: '요청자 에이전트 이름' },
+        },
+      },
+      handler: wrap('PIPELINE_ADVANCE_GATED_FAILED', (args) => {
+        ensurePipelineTable(store.db);
+        const pipeline = createPipeline(store.db, args.team_name);
+
+        // 전이 가능 여부 사전 확인
+        if (!pipeline.canAdvance(args.phase)) {
+          const current = pipeline.getState();
+          return {
+            ok: false,
+            error: {
+              code: 'TRANSITION_BLOCKED',
+              message: `전이 불가: ${current.phase} → ${args.phase}`,
+            },
+          };
+        }
+
+        // HITL 승인 요청 생성
+        const approvalPrompt = args.prompt || `파이프라인 ${args.team_name}: ${pipeline.getState().phase} → ${args.phase} 전이를 승인하시겠습니까?`;
+        const deadlineMs = args.deadline_ms || 120000;
+        const now = Date.now();
+
+        const hitlResult = hitl.requestHumanInput({
+          requester_agent: args.requester_agent || `pipeline:${args.team_name}`,
+          kind: 'approval',
+          prompt: approvalPrompt,
+          deadline_ms: now + deadlineMs,
+          default_action: args.default_action || 'timeout_continue',
+        });
+
+        if (!hitlResult.ok) {
+          return hitlResult;
+        }
+
+        return {
+          ok: true,
+          data: {
+            pending: true,
+            request_id: hitlResult.data.request_id,
+            team_name: args.team_name,
+            target_phase: args.phase,
+            current_phase: pipeline.getState().phase,
+            deadline_ms: now + deadlineMs,
+            default_action: args.default_action || 'timeout_continue',
+            message: `승인 대기 중. ID: ${hitlResult.data.request_id}. ${Math.round(deadlineMs / 1000)}초 후 ${args.default_action || 'timeout_continue'} 자동 실행.`,
+          },
+        };
+      }),
+    },
+
+    // ── 20. pipeline_list ──
     {
       name: 'pipeline_list',
       description: '활성 파이프라인 목록을 조회합니다',