@triflux/core 10.1.0 → 10.25.1

package/hub/bridge.mjs

@@ -1,23 +1,47 @@
 #!/usr/bin/env node
+
 // hub/bridge.mjs — tfx-route.sh ↔ tfx-hub 브릿지 CLI
 //
 // Named Pipe/Unix Socket 제어 채널을 우선 사용하고,
 // 연결이 없을 때만 HTTP /bridge/* 엔드포인트로 내려간다.
 
-import net from 'node:net';
-import { readFileSync, writeFileSync, existsSync, mkdirSync, openSync } from 'node:fs';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
-import { spawn } from 'node:child_process';
-import { parseArgs as nodeParseArgs } from 'node:util';
-import { randomUUID } from 'node:crypto';
-import { fileURLToPath } from 'node:url';
-
-import { getPipelineStateDbPath } from './pipeline/state.mjs';
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import net from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs as nodeParseArgs } from "node:util";
+
+import { getPipelineStateDbPath } from "./pipeline/state.mjs";
+import {
+  createRetryStateMachine,
+  loadSnapshot,
+  saveSnapshot,
+} from "./team/retry-state-machine.mjs";
+
+const HUB_PID_FILE = join(homedir(), ".claude", "cache", "tfx-hub", "hub.pid");
+const HUB_TOKEN_FILE = join(homedir(), ".claude", ".tfx-hub-token");
+const PROJECT_ROOT = fileURLToPath(new URL("..", import.meta.url));
+const HUB_DEFAULT_PORT = 27888;
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
+
+function formatHostForUrl(host) {
+  return host.includes(":") ? `[${host}]` : host;
+}
 
-const HUB_PID_FILE = join(homedir(), '.claude', 'cache', 'tfx-hub', 'hub.pid');
-const HUB_TOKEN_FILE = join(homedir(), '.claude', '.tfx-hub-token');
-const PROJECT_ROOT = fileURLToPath(new URL('..', import.meta.url));
+function normalizeLoopbackHost(host) {
+  if (typeof host !== "string") return "127.0.0.1";
+  const candidate = host.trim();
+  return LOOPBACK_HOSTS.has(candidate) ? candidate : "127.0.0.1";
+}
 
 function normalizeToken(raw) {
   if (raw == null) return null;
@@ -30,26 +54,31 @@ function readHubToken() {
   const envToken = normalizeToken(process.env.TFX_HUB_TOKEN);
   if (envToken) return envToken;
   try {
-    return normalizeToken(readFileSync(HUB_TOKEN_FILE, 'utf8'));
+    return normalizeToken(readFileSync(HUB_TOKEN_FILE, "utf8"));
   } catch {
     return null;
   }
 }
 
 export function getHubUrl() {
-  if (process.env.TFX_HUB_URL) return process.env.TFX_HUB_URL.replace(/\/mcp$/, '');
+  if (process.env.TFX_HUB_URL)
+    return process.env.TFX_HUB_URL.replace(/\/mcp$/, "");
+
+  const envPort = Number.parseInt(String(process.env.TFX_HUB_PORT ?? ""), 10);
+  const port =
+    Number.isFinite(envPort) && envPort > 0 ? envPort : HUB_DEFAULT_PORT;
+  let host = "127.0.0.1";
 
   if (existsSync(HUB_PID_FILE)) {
     try {
-      const info = JSON.parse(readFileSync(HUB_PID_FILE, 'utf8'));
-      return `http://${info.host || '127.0.0.1'}:${info.port || 27888}`;
+      const info = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
+      host = normalizeLoopbackHost(info?.host);
     } catch {
       // 무시
     }
   }
 
-  const port = process.env.TFX_HUB_PORT || '27888';
-  return `http://127.0.0.1:${port}`;
+  return `http://${formatHostForUrl(host)}:${port}`;
 }
 
 export function getHubPipePath() {
@@ -57,7 +86,7 @@ export function getHubPipePath() {
 
   if (!existsSync(HUB_PID_FILE)) return null;
   try {
-    const info = JSON.parse(readFileSync(HUB_PID_FILE, 'utf8'));
+    const info = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
     return info.pipe_path || info.pipePath || null;
   } catch {
     return null;
@@ -65,30 +94,144 @@ export function getHubPipePath() {
 }
 
 const HUB_OPERATIONS = Object.freeze({
-  register: { transport: 'command', action: 'register', httpPath: '/bridge/register' },
-  result: { transport: 'command', action: 'result', httpPath: '/bridge/result' },
-  control: { transport: 'command', action: 'control', httpPath: '/bridge/control' },
-  context: { transport: 'query', action: 'drain', httpPath: '/bridge/context' },
-  deregister: { transport: 'command', action: 'deregister', httpPath: '/bridge/deregister' },
-  assignAsync: { transport: 'command', action: 'assign', httpPath: '/bridge/assign/async' },
-  assignResult: { transport: 'command', action: 'assign_result', httpPath: '/bridge/assign/result' },
-  assignStatus: { transport: 'query', action: 'assign_status', httpPath: '/bridge/assign/status' },
-  assignRetry: { transport: 'command', action: 'assign_retry', httpPath: '/bridge/assign/retry' },
-  teamInfo: { transport: 'query', action: 'team_info', httpPath: '/bridge/team/info' },
-  teamTaskList: { transport: 'query', action: 'team_task_list', httpPath: '/bridge/team/task-list' },
-  teamTaskUpdate: { transport: 'command', action: 'team_task_update', httpPath: '/bridge/team/task-update' },
-  teamSendMessage: { transport: 'command', action: 'team_send_message', httpPath: '/bridge/team/send-message' },
-  pipelineState: { transport: 'query', action: 'pipeline_state', httpPath: '/bridge/pipeline/state' },
-  pipelineAdvance: { transport: 'command', action: 'pipeline_advance', httpPath: '/bridge/pipeline/advance' },
-  pipelineInit: { transport: 'command', action: 'pipeline_init', httpPath: '/bridge/pipeline/init' },
-  pipelineList: { transport: 'query', action: 'pipeline_list', httpPath: '/bridge/pipeline/list' },
-  hubStatus: { transport: 'query', action: 'status', httpPath: '/status', httpMethod: 'GET' },
-  delegatorDelegate: { transport: 'command', action: 'delegator_delegate', httpPath: '/bridge/delegator/delegate' },
-  delegatorReply: { transport: 'command', action: 'delegator_reply', httpPath: '/bridge/delegator/reply' },
-  delegatorStatus: { transport: 'query', action: 'delegator_status', httpPath: '/bridge/delegator/status' },
+  register: {
+    transport: "command",
+    action: "register",
+    httpPath: "/bridge/register",
+  },
+  result: {
+    transport: "command",
+    action: "result",
+    httpPath: "/bridge/result",
+  },
+  control: {
+    transport: "command",
+    action: "control",
+    httpPath: "/bridge/control",
+  },
+  handoff: {
+    transport: "command",
+    action: "handoff",
+    httpPath: "/bridge/handoff",
+  },
+  publish: {
+    transport: "command",
+    action: "publish",
+    httpPath: "/bridge/publish",
+  },
+  sendInput: {
+    transport: "command",
+    action: "send_input",
+    httpPath: "/bridge/send-input",
+  },
+  context: { transport: "query", action: "drain", httpPath: "/bridge/context" },
+  deregister: {
+    transport: "command",
+    action: "deregister",
+    httpPath: "/bridge/deregister",
+  },
+  assignAsync: {
+    transport: "command",
+    action: "assign",
+    httpPath: "/bridge/assign/async",
+  },
+  assignResult: {
+    transport: "command",
+    action: "assign_result",
+    httpPath: "/bridge/assign/result",
+  },
+  assignStatus: {
+    transport: "query",
+    action: "assign_status",
+    httpPath: "/bridge/assign/status",
+  },
+  assignRetry: {
+    transport: "command",
+    action: "assign_retry",
+    httpPath: "/bridge/assign/retry",
+  },
+  teamInfo: {
+    transport: "query",
+    action: "team_info",
+    httpPath: "/bridge/team/info",
+  },
+  teamTaskList: {
+    transport: "query",
+    action: "team_task_list",
+    httpPath: "/bridge/team/task-list",
+  },
+  teamTaskUpdate: {
+    transport: "command",
+    action: "team_task_update",
+    httpPath: "/bridge/team/task-update",
+  },
+  teamSendMessage: {
+    transport: "command",
+    action: "team_send_message",
+    httpPath: "/bridge/team/send-message",
+  },
+  pipelineState: {
+    transport: "query",
+    action: "pipeline_state",
+    httpPath: "/bridge/pipeline/state",
+  },
+  pipelineAdvance: {
+    transport: "command",
+    action: "pipeline_advance",
+    httpPath: "/bridge/pipeline/advance",
+  },
+  pipelineInit: {
+    transport: "command",
+    action: "pipeline_init",
+    httpPath: "/bridge/pipeline/init",
+  },
+  pipelineList: {
+    transport: "query",
+    action: "pipeline_list",
+    httpPath: "/bridge/pipeline/list",
+  },
+  hubStatus: {
+    transport: "query",
+    action: "status",
+    httpPath: "/status",
+    httpMethod: "GET",
+  },
+  delegatorDelegate: {
+    transport: "command",
+    action: "delegator_delegate",
+    httpPath: "/bridge/delegator/delegate",
+  },
+  delegatorReply: {
+    transport: "command",
+    action: "delegator_reply",
+    httpPath: "/bridge/delegator/reply",
+  },
+  delegatorStatus: {
+    transport: "query",
+    action: "delegator_status",
+    httpPath: "/bridge/delegator/status",
+  },
+  "hitl-request": {
+    transport: "command",
+    action: "hitl_request",
+    httpPath: "/bridge/hitl/request",
+  },
+  "hitl-submit": {
+    transport: "command",
+    action: "hitl_submit",
+    httpPath: "/bridge/hitl/submit",
+  },
+  "hitl-pending": {
+    transport: "query",
+    action: "hitl_pending",
+    httpPath: "/bridge/hitl/pending",
+  },
 });
 
-export async function requestJson(path, { method = 'POST', body, timeoutMs = 5000 } = {}) {
+export async function requestJson(
+  path,
+  { method = "POST", body, timeoutMs = 5000 } = {},
+) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
 
@@ -99,7 +242,7 @@ export async function requestJson(path, { method = 'POST', body, timeoutMs = 500
       headers.Authorization = `Bearer ${token}`;
     }
     if (body !== undefined) {
-      headers['Content-Type'] = 'application/json';
+      headers["Content-Type"] = "application/json";
     }
 
     const res = await fetch(`${getHubUrl()}${path}`, {
@@ -117,7 +260,7 @@ export async function requestJson(path, { method = 'POST', body, timeoutMs = 500
 }
 
 export async function post(path, body, timeoutMs = 5000) {
-  return await requestJson(path, { method: 'POST', body, timeoutMs });
+  return await requestJson(path, { method: "POST", body, timeoutMs });
 }
 
 export async function connectPipe(timeoutMs = 1200) {
@@ -127,19 +270,23 @@ export async function connectPipe(timeoutMs = 1200) {
   return await new Promise((resolve) => {
     const socket = net.createConnection(pipePath);
     const timer = setTimeout(() => {
-      try { socket.destroy(); } catch {}
+      try {
+        socket.destroy();
+      } catch {}
       resolve(null);
     }, timeoutMs);
 
-    socket.once('connect', () => {
+    socket.once("connect", () => {
       clearTimeout(timer);
-      socket.setEncoding('utf8');
+      socket.setEncoding("utf8");
       resolve(socket);
     });
 
-    socket.once('error', () => {
+    socket.once("error", () => {
       clearTimeout(timer);
-      try { socket.destroy(); } catch {}
+      try {
+        socket.destroy();
+      } catch {}
       resolve(null);
     });
   });
@@ -151,7 +298,7 @@ async function pipeRequest(type, action, payload, timeoutMs = 3000) {
 
   return await new Promise((resolve) => {
     const requestId = randomUUID();
-    let buffer = '';
+    let buffer = "";
     let settled = false;
     const timer = setTimeout(() => {
       finish(null);
@@ -161,17 +308,19 @@ async function pipeRequest(type, action, payload, timeoutMs = 3000) {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
-      try { socket.end(); } catch {}
+      try {
+        socket.end();
+      } catch {}
       resolve(result);
     };
 
-    socket.on('data', (chunk) => {
+    socket.on("data", (chunk) => {
       buffer += chunk;
-      let newlineIndex = buffer.indexOf('\n');
+      let newlineIndex = buffer.indexOf("\n");
       while (newlineIndex >= 0) {
         const line = buffer.slice(0, newlineIndex).trim();
         buffer = buffer.slice(newlineIndex + 1);
-        newlineIndex = buffer.indexOf('\n');
+        newlineIndex = buffer.indexOf("\n");
         if (!line) continue;
 
         let frame;
@@ -181,7 +330,8 @@ async function pipeRequest(type, action, payload, timeoutMs = 3000) {
           continue;
         }
 
-        if (frame?.type !== 'response' || frame.request_id !== requestId) continue;
+        if (frame?.type !== "response" || frame.request_id !== requestId)
+          continue;
         finish({
           ok: frame.ok,
           error: frame.error,
@@ -191,89 +341,102 @@ async function pipeRequest(type, action, payload, timeoutMs = 3000) {
       }
     });
 
-    socket.on('error', () => finish(null));
-    socket.write(JSON.stringify({
-      type,
-      request_id: requestId,
-      payload: { action, ...payload },
-    }) + '\n');
+    socket.on("error", () => finish(null));
+    socket.write(
+      JSON.stringify({
+        type,
+        request_id: requestId,
+        payload: { action, ...payload },
+      }) + "\n",
+    );
   });
 }
 
 async function pipeCommand(action, payload, timeoutMs = 3000) {
-  return await pipeRequest('command', action, payload, timeoutMs);
+  return await pipeRequest("command", action, payload, timeoutMs);
 }
 
 async function pipeQuery(action, payload, timeoutMs = 3000) {
-  return await pipeRequest('query', action, payload, timeoutMs);
+  return await pipeRequest("query", action, payload, timeoutMs);
 }
 
 export function parseArgs(argv) {
-  const { values } = nodeParseArgs({
+  const { values, positionals } = nodeParseArgs({
     args: argv,
     options: {
-      agent: { type: 'string' },
-      cli: { type: 'string' },
-      timeout: { type: 'string' },
-      topics: { type: 'string' },
-      capabilities: { type: 'string' },
-      file: { type: 'string' },
-      payload: { type: 'string' },
-      topic: { type: 'string' },
-      trace: { type: 'string' },
-      correlation: { type: 'string' },
-      'exit-code': { type: 'string' },
-      max: { type: 'string' },
-      out: { type: 'string' },
-      team: { type: 'string' },
-      'task-id': { type: 'string' },
-      'job-id': { type: 'string' },
-      owner: { type: 'string' },
-      status: { type: 'string' },
-      statuses: { type: 'string' },
-      claim: { type: 'boolean' },
-      actor: { type: 'string' },
-      command: { type: 'string' },
-      reason: { type: 'string' },
-      from: { type: 'string' },
-      to: { type: 'string' },
-      text: { type: 'string' },
-      task: { type: 'string' },
-      'supervisor-agent': { type: 'string' },
-      'worker-agent': { type: 'string' },
-      priority: { type: 'string' },
-      'ttl-ms': { type: 'string' },
-      'timeout-ms': { type: 'string' },
-      'max-retries': { type: 'string' },
-      attempt: { type: 'string' },
-      result: { type: 'string' },
-      error: { type: 'string' },
-      metadata: { type: 'string' },
-      'requested-by': { type: 'string' },
-      summary: { type: 'string' },
-      color: { type: 'string' },
-      limit: { type: 'string' },
-      'include-internal': { type: 'boolean' },
-      subject: { type: 'string' },
-      description: { type: 'string' },
-      'fix-max': { type: 'string' },
-      'ralph-max': { type: 'string' },
-      'active-form': { type: 'string' },
-      'add-blocks': { type: 'string' },
-      'add-blocked-by': { type: 'string' },
-      'metadata-patch': { type: 'string' },
-      'if-match-mtime-ms': { type: 'string' },
-      provider: { type: 'string' },
-      mode: { type: 'string' },
-      prompt: { type: 'string' },
-      reply: { type: 'string' },
-      done: { type: 'boolean' },
-      'mcp-profile': { type: 'string' },
-      'session-key': { type: 'string' },
+      agent: { type: "string" },
+      cli: { type: "string" },
+      timeout: { type: "string" },
+      topics: { type: "string" },
+      capabilities: { type: "string" },
+      file: { type: "string" },
+      payload: { type: "string" },
+      topic: { type: "string" },
+      trace: { type: "string" },
+      correlation: { type: "string" },
+      "exit-code": { type: "string" },
+      max: { type: "string" },
+      out: { type: "string" },
+      team: { type: "string" },
+      "task-id": { type: "string" },
+      "job-id": { type: "string" },
+      owner: { type: "string" },
+      status: { type: "string" },
+      statuses: { type: "string" },
+      claim: { type: "boolean" },
+      actor: { type: "string" },
+      command: { type: "string" },
+      "session-id": { type: "string" },
+      reason: { type: "string" },
+      type: { type: "string" },
+      from: { type: "string" },
+      to: { type: "string" },
+      text: { type: "string" },
+      task: { type: "string" },
+      "supervisor-agent": { type: "string" },
+      "worker-agent": { type: "string" },
+      priority: { type: "string" },
+      "ttl-ms": { type: "string" },
+      "timeout-ms": { type: "string" },
+      "max-retries": { type: "string" },
+      attempt: { type: "string" },
+      result: { type: "string" },
+      error: { type: "string" },
+      metadata: { type: "string" },
+      "requested-by": { type: "string" },
+      summary: { type: "string" },
+      color: { type: "string" },
+      limit: { type: "string" },
+      "include-internal": { type: "boolean" },
+      subject: { type: "string" },
+      description: { type: "string" },
+      "fix-max": { type: "string" },
+      "ralph-max": { type: "string" },
+      "active-form": { type: "string" },
+      "add-blocks": { type: "string" },
+      "add-blocked-by": { type: "string" },
+      "metadata-patch": { type: "string" },
+      "if-match-mtime-ms": { type: "string" },
+      provider: { type: "string" },
+      mode: { type: "string" },
+      prompt: { type: "string" },
+      reply: { type: "string" },
+      done: { type: "boolean" },
+      "mcp-profile": { type: "string" },
+      "session-key": { type: "string" },
+      snapshot: { type: "string" },
+      "snapshot-file": { type: "string" },
+      event: { type: "string" },
+      "max-iterations": { type: "string" },
     },
+    allowPositionals: true,
     strict: false,
   });
-  return values;
+  const parsed = { ...values, _: positionals };
+  positionals.forEach((value, index) => {
+    parsed[index + 1] = value;
+  });
+  return parsed;
 }
 
 export function parseJsonSafe(raw, fallback = null) {
@@ -285,29 +448,63 @@ export function parseJsonSafe(raw, fallback = null) {
   }
 }
 
+function normalizeBridgePayload(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return {};
+  }
+  return payload;
+}
+
+function buildHandoffBody(from, to, payload) {
+  const normalizedPayload = normalizeBridgePayload(payload);
+  return {
+    ...normalizedPayload,
+    from,
+    to,
+    payload: normalizedPayload,
+  };
+}
+
+function buildPublishBody(from, to, type, payload) {
+  const normalizedPayload = normalizeBridgePayload(payload);
+  return {
+    ...normalizedPayload,
+    from,
+    to,
+    type,
+    message_type: type,
+    payload: normalizedPayload,
+  };
+}
+
 // Hub 자동 재시작 (Pipe+HTTP 모두 실패 시 1회 시도, 최대 4초 대기)
 async function tryRestartHub() {
-  const serverPath = join(PROJECT_ROOT, 'hub', 'server.mjs');
+  const serverPath = join(PROJECT_ROOT, "hub", "server.mjs");
   if (!existsSync(serverPath)) return false;
 
   if (existsSync(HUB_PID_FILE)) {
     try {
-      const info = JSON.parse(readFileSync(HUB_PID_FILE, 'utf8'));
+      const info = JSON.parse(readFileSync(HUB_PID_FILE, "utf8"));
       if (info.pid) {
-        try { process.kill(info.pid, 0); return false; } // still alive
-        catch (e) { if (e.code === 'EPERM') return false; } // alive, no permission
+        try {
+          process.kill(info.pid, 0);
+          return false;
+        } catch (e) {
+          // still alive
+          if (e.code === "EPERM") return false;
+        } // alive, no permission
       }
     } catch {} // corrupt PID file, proceed with restart
   }
 
   try {
-    const logDir = join(process.cwd(), '.tfx', 'logs');
+    const logDir = join(process.cwd(), ".tfx", "logs");
     if (!existsSync(logDir)) mkdirSync(logDir, { recursive: true });
-    const logFile = join(logDir, 'hub-restart.log');
-    const logFd = openSync(logFile, 'a');
+    const logFile = join(logDir, "hub-restart.log");
+    const logFd = openSync(logFile, "a");
     const child = spawn(process.execPath, [serverPath], {
       detached: true,
-      stdio: ['ignore', 'ignore', logFd],
+      stdio: ["ignore", "ignore", logFd],
       windowsHide: true,
     });
     child.unref();
@@ -323,7 +520,7 @@ async function tryRestartHub() {
       });
       if (res.ok) {
         const data = await res.json();
-        if (data?.hub?.state === 'healthy') return true;
+        if (data?.hub?.state === "healthy") return true;
       }
     } catch {}
   }
@@ -331,52 +528,54 @@ async function tryRestartHub() {
 }
 
 async function requestHub(operation, body, timeoutMs = 3000, fallback = null) {
-  const viaPipe = operation.transport === 'command'
-    ? await pipeCommand(operation.action, body, timeoutMs)
-    : await pipeQuery(operation.action, body, timeoutMs);
+  const viaPipe =
+    operation.transport === "command"
+      ? await pipeCommand(operation.action, body, timeoutMs)
+      : await pipeQuery(operation.action, body, timeoutMs);
   if (viaPipe) {
-    return { transport: 'pipe', result: viaPipe };
+    return { transport: "pipe", result: viaPipe };
   }
 
   const viaHttp = operation.httpPath
     ? await requestJson(operation.httpPath, {
-      method: operation.httpMethod || 'POST',
-      body: operation.httpMethod === 'GET' ? undefined : body,
-      timeoutMs: Math.max(timeoutMs, 5000),
-    })
+        method: operation.httpMethod || "POST",
+        body: operation.httpMethod === "GET" ? undefined : body,
+        timeoutMs: Math.max(timeoutMs, 5000),
+      })
     : null;
   if (viaHttp) {
-    return { transport: 'http', result: viaHttp };
+    return { transport: "http", result: viaHttp };
   }
 
   // Hub 재시작 시도 → Pipe/HTTP 재시도
   if (await tryRestartHub()) {
-    const retryPipe = operation.transport === 'command'
-      ? await pipeCommand(operation.action, body, timeoutMs)
-      : await pipeQuery(operation.action, body, timeoutMs);
+    const retryPipe =
+      operation.transport === "command"
+        ? await pipeCommand(operation.action, body, timeoutMs)
+        : await pipeQuery(operation.action, body, timeoutMs);
     if (retryPipe) {
-      return { transport: 'pipe', result: retryPipe };
+      return { transport: "pipe", result: retryPipe };
     }
     const retryHttp = operation.httpPath
       ? await requestJson(operation.httpPath, {
-        method: operation.httpMethod || 'POST',
-        body: operation.httpMethod === 'GET' ? undefined : body,
-        timeoutMs: Math.max(timeoutMs, 5000),
-      })
+          method: operation.httpMethod || "POST",
+          body: operation.httpMethod === "GET" ? undefined : body,
+          timeoutMs: Math.max(timeoutMs, 5000),
+        })
       : null;
     if (retryHttp) {
-      return { transport: 'http', result: retryHttp };
+      return { transport: "http", result: retryHttp };
     }
   }
 
   if (!fallback) return null;
   const viaFallback = await fallback();
   if (!viaFallback) return null;
-  return { transport: 'fallback', result: viaFallback };
+  return { transport: "fallback", result: viaFallback };
 }
 
 function unavailableResult() {
-  return { ok: false, reason: 'hub_unavailable' };
+  return { ok: false, reason: "hub_unavailable" };
 }
 
 function emitJson(payload) {
@@ -388,14 +587,14 @@ function emitJson(payload) {
 
 async function cmdRegister(args) {
   const agentId = args.agent;
-  const timeoutSec = parseInt(args.timeout || '600', 10);
+  const timeoutSec = parseInt(args.timeout || "600", 10);
   const outcome = await requestHub(HUB_OPERATIONS.register, {
     agent_id: agentId,
-    cli: args.cli || 'other',
+    cli: args.cli || "other",
     timeout_sec: timeoutSec,
     heartbeat_ttl_ms: (timeoutSec + 120) * 1000,
-    topics: args.topics ? args.topics.split(',') : [],
-    capabilities: args.capabilities ? args.capabilities.split(',') : ['code'],
+    topics: args.topics ? args.topics.split(",") : [],
+    capabilities: args.capabilities ? args.capabilities.split(",") : ["code"],
     metadata: {
       pid: process.ppid,
       registered_at: Date.now(),
@@ -416,14 +615,14 @@ async function cmdRegister(args) {
 }
 
 async function cmdResult(args) {
-  let output = '';
+  let output = "";
   if (args.file && existsSync(args.file)) {
-    output = readFileSync(args.file, 'utf8').slice(0, 49152);
+    output = readFileSync(args.file, "utf8").slice(0, 49152);
   }
 
   const defaultPayload = {
     agent_id: args.agent,
-    exit_code: parseInt(args['exit-code'] || '0', 10),
+    exit_code: parseInt(args["exit-code"] || "0", 10),
     output_length: output.length,
     output_preview: output.slice(0, 4096),
     output_file: args.file || null,
@@ -432,8 +631,10 @@ async function cmdResult(args) {
 
   const outcome = await requestHub(HUB_OPERATIONS.result, {
     agent_id: args.agent,
-    topic: args.topic || 'task.result',
-    payload: args.payload ? parseJsonSafe(args.payload, defaultPayload) : defaultPayload,
+    topic: args.topic || "task.result",
+    payload: args.payload
+      ? parseJsonSafe(args.payload, defaultPayload)
+      : defaultPayload,
     trace_id: args.trace || undefined,
     correlation_id: args.correlation || undefined,
   });
@@ -448,14 +649,48 @@ async function cmdResult(args) {
 
 async function cmdControl(args) {
   const outcome = await requestHub(HUB_OPERATIONS.control, {
-    from_agent: args.from || 'lead',
+    from_agent: args.from || "lead",
     to_agent: args.to,
     command: args.command,
-    reason: args.reason || '',
+    reason: args.reason || "",
     payload: args.payload ? parseJsonSafe(args.payload, {}) : {},
     trace_id: args.trace || undefined,
     correlation_id: args.correlation || undefined,
-    ttl_ms: args['ttl-ms'] != null ? Number(args['ttl-ms']) : undefined,
+    ttl_ms: args["ttl-ms"] != null ? Number(args["ttl-ms"]) : undefined,
+  });
+  const result = outcome?.result;
+  return emitJson(result || unavailableResult());
+}
+
+async function cmdHandoff(args) {
+  const from = args.from || args[1];
+  const to = args.to || args[2];
+  const payload = parseJsonSafe(args.payload || args[3] || "{}", {});
+  const outcome = await requestHub(
+    HUB_OPERATIONS.handoff,
+    buildHandoffBody(from, to, payload),
+  );
+  const result = outcome?.result;
+  return emitJson(result || unavailableResult());
+}
+
+async function cmdPublish(args) {
+  const from = args.from || args[1];
+  const to = args.to || args[2];
+  const type = args.type || args[3] || "event";
+  const payload = parseJsonSafe(args.payload || args[4] || "{}", {});
+  const outcome = await requestHub(
+    HUB_OPERATIONS.publish,
+    buildPublishBody(from, to, type, payload),
+  );
+  const result = outcome?.result;
+  return emitJson(result || unavailableResult());
+}
+
+async function cmdSendInput(args) {
+  const outcome = await requestHub(HUB_OPERATIONS.sendInput, {
+    session_id: args["session-id"],
+    text: args.text,
   });
   const result = outcome?.result;
   return emitJson(result || unavailableResult());
@@ -464,26 +699,35 @@ async function cmdControl(args) {
 async function cmdContext(args) {
   const outcome = await requestHub(HUB_OPERATIONS.context, {
     agent_id: args.agent,
-    topics: args.topics ? args.topics.split(',') : undefined,
-    max_messages: parseInt(args.max || '10', 10),
+    topics: args.topics ? args.topics.split(",") : undefined,
+    max_messages: parseInt(args.max || "10", 10),
     auto_ack: true,
   });
   const result = outcome?.result;
 
   if (result?.ok && result.data?.messages?.length) {
     const parts = result.data.messages.map((message, index) => {
-      const payload = typeof message.payload === 'string'
-        ? message.payload
-        : JSON.stringify(message.payload, null, 2);
-      return `=== Context ${index + 1}: ${message.from_agent || 'unknown'} (${message.topic || 'unknown'}) ===\n${payload}`;
+      const payload =
+        typeof message.payload === "string"
+          ? message.payload
+          : JSON.stringify(message.payload, null, 2);
+      return `=== Context ${index + 1}: ${message.from_agent || "unknown"} (${message.topic || "unknown"}) ===\n${payload}`;
     });
-    const combined = parts.join('\n\n');
+    const combined = parts.join("\n\n");
 
     if (args.out) {
-      writeFileSync(args.out, combined, 'utf8');
-      return emitJson({ ok: true, count: result.data.messages.length, file: args.out });
+      writeFileSync(args.out, combined, "utf8");
+      return emitJson({
+        ok: true,
+        count: result.data.messages.length,
+        file: args.out,
+      });
     } else {
-      return emitJson({ ok: true, count: result.data.messages.length, context: combined });
+      return emitJson({
+        ok: true,
+        count: result.data.messages.length,
+        context: combined,
+      });
     }
   }
 
@@ -491,7 +735,7 @@ async function cmdContext(args) {
     if (args.out) {
       return emitJson({ ok: true, count: 0 });
     }
-    return emitJson({ ok: true, count: 0, context: '' });
+    return emitJson({ ok: true, count: 0, context: "" });
   }
 
   return emitJson(result || unavailableResult());
@@ -504,7 +748,7 @@ async function cmdDeregister(args) {
   const result = outcome?.result;
 
   if (result?.ok) {
-    return emitJson({ ok: true, agent_id: args.agent, status: 'offline' });
+    return emitJson({ ok: true, agent_id: args.agent, status: "offline" });
   }
 
   return emitJson(result || unavailableResult());
@@ -512,15 +756,17 @@ async function cmdDeregister(args) {
 
 async function cmdAssignAsync(args) {
   const outcome = await requestHub(HUB_OPERATIONS.assignAsync, {
-    supervisor_agent: args['supervisor-agent'],
-    worker_agent: args['worker-agent'],
+    supervisor_agent: args["supervisor-agent"],
+    worker_agent: args["worker-agent"],
     task: args.task,
-    topic: args.topic || 'assign.job',
+    topic: args.topic || "assign.job",
     payload: args.payload ? parseJsonSafe(args.payload, {}) : {},
     priority: args.priority != null ? Number(args.priority) : undefined,
-    ttl_ms: args['ttl-ms'] != null ? Number(args['ttl-ms']) : undefined,
-    timeout_ms: args['timeout-ms'] != null ? Number(args['timeout-ms']) : undefined,
-    max_retries: args['max-retries'] != null ? Number(args['max-retries']) : undefined,
+    ttl_ms: args["ttl-ms"] != null ? Number(args["ttl-ms"]) : undefined,
+    timeout_ms:
+      args["timeout-ms"] != null ? Number(args["timeout-ms"]) : undefined,
+    max_retries:
+      args["max-retries"] != null ? Number(args["max-retries"]) : undefined,
     trace_id: args.trace || undefined,
     correlation_id: args.correlation || undefined,
   });
@@ -530,8 +776,8 @@ async function cmdAssignAsync(args) {
 
 async function cmdAssignResult(args) {
   const outcome = await requestHub(HUB_OPERATIONS.assignResult, {
-    job_id: args['job-id'],
-    worker_agent: args['worker-agent'],
+    job_id: args["job-id"],
+    worker_agent: args["worker-agent"],
     status: args.status,
     attempt: args.attempt != null ? Number(args.attempt) : undefined,
     result: args.result ? parseJsonSafe(args.result, null) : undefined,
@@ -545,7 +791,7 @@ async function cmdAssignResult(args) {
 
 async function cmdAssignStatus(args) {
   const outcome = await requestHub(HUB_OPERATIONS.assignStatus, {
-    job_id: args['job-id'],
+    job_id: args["job-id"],
   });
   const result = outcome?.result;
   return emitJson(result || unavailableResult());
@@ -553,9 +799,9 @@ async function cmdAssignStatus(args) {
 
 async function cmdAssignRetry(args) {
   const outcome = await requestHub(HUB_OPERATIONS.assignRetry, {
-    job_id: args['job-id'],
+    job_id: args["job-id"],
     reason: args.reason,
-    requested_by: args['requested-by'],
+    requested_by: args["requested-by"],
   });
   const result = outcome?.result;
   return emitJson(result || unavailableResult());
@@ -567,10 +813,15 @@ async function cmdTeamInfo(args) {
     include_members: true,
     include_paths: true,
   };
-  const outcome = await requestHub(HUB_OPERATIONS.teamInfo, body, 3000, async () => {
-    const { teamInfo } = await import('./team/nativeProxy.mjs');
-    return await teamInfo(body);
-  });
+  const outcome = await requestHub(
+    HUB_OPERATIONS.teamInfo,
+    body,
+    3000,
+    async () => {
+      const { teamInfo } = await import("./team/nativeProxy.mjs");
+      return await teamInfo(body);
+    },
+  );
   const result = outcome?.result;
   return emitJson(result || unavailableResult());
 }
@@ -579,14 +830,24 @@ async function cmdTeamTaskList(args) {
   const body = {
     team_name: args.team,
     owner: args.owner,
-    statuses: args.statuses ? args.statuses.split(',').map((status) => status.trim()).filter(Boolean) : [],
-    include_internal: !!args['include-internal'],
-    limit: parseInt(args.limit || '200', 10),
+    statuses: args.statuses
+      ? args.statuses
+          .split(",")
+          .map((status) => status.trim())
+          .filter(Boolean)
+      : [],
+    include_internal: !!args["include-internal"],
+    limit: parseInt(args.limit || "200", 10),
   };
-  const outcome = await requestHub(HUB_OPERATIONS.teamTaskList, body, 3000, async () => {
-    const { teamTaskList } = await import('./team/nativeProxy.mjs');
-    return await teamTaskList(body);
-  });
+  const outcome = await requestHub(
+    HUB_OPERATIONS.teamTaskList,
+    body,
+    3000,
+    async () => {
+      const { teamTaskList } = await import("./team/nativeProxy.mjs");
+      return await teamTaskList(body);
+    },
+  );
   const result = outcome?.result;
   return emitJson(result || unavailableResult());
 }
@@ -594,23 +855,43 @@ async function cmdTeamTaskList(args) {
 async function cmdTeamTaskUpdate(args) {
   const body = {
     team_name: args.team,
-    task_id: args['task-id'],
+    task_id: args["task-id"],
     claim: !!args.claim,
     owner: args.owner,
     status: args.status,
     subject: args.subject,
     description: args.description,
-    activeForm: args['active-form'],
-    add_blocks: args['add-blocks'] ? args['add-blocks'].split(',').map((value) => value.trim()).filter(Boolean) : undefined,
-    add_blocked_by: args['add-blocked-by'] ? args['add-blocked-by'].split(',').map((value) => value.trim()).filter(Boolean) : undefined,
-    metadata_patch: args['metadata-patch'] ? parseJsonSafe(args['metadata-patch'], null) : undefined,
-    if_match_mtime_ms: args['if-match-mtime-ms'] != null ? Number(args['if-match-mtime-ms']) : undefined,
+    activeForm: args["active-form"],
+    add_blocks: args["add-blocks"]
+      ? args["add-blocks"]
+          .split(",")
+          .map((value) => value.trim())
+          .filter(Boolean)
+      : undefined,
+    add_blocked_by: args["add-blocked-by"]
+      ? args["add-blocked-by"]
+          .split(",")
+          .map((value) => value.trim())
+          .filter(Boolean)
+      : undefined,
+    metadata_patch: args["metadata-patch"]
+      ? parseJsonSafe(args["metadata-patch"], null)
+      : undefined,
+    if_match_mtime_ms:
+      args["if-match-mtime-ms"] != null
+        ? Number(args["if-match-mtime-ms"])
+        : undefined,
     actor: args.actor,
   };
-  const outcome = await requestHub(HUB_OPERATIONS.teamTaskUpdate, body, 3000, async () => {
-    const { teamTaskUpdate } = await import('./team/nativeProxy.mjs');
-    return await teamTaskUpdate(body);
-  });
+  const outcome = await requestHub(
+    HUB_OPERATIONS.teamTaskUpdate,
+    body,
+    3000,
+    async () => {
+      const { teamTaskUpdate } = await import("./team/nativeProxy.mjs");
+      return await teamTaskUpdate(body);
+    },
+  );
   const result = outcome?.result;
   return emitJson(result || unavailableResult());
 }
@@ -619,15 +900,20 @@ async function cmdTeamSendMessage(args) {
   const body = {
     team_name: args.team,
     from: args.from,
-    to: args.to || 'team-lead',
+    to: args.to || "team-lead",
     text: args.text,
     summary: args.summary,
-    color: args.color || 'blue',
+    color: args.color || "blue",
   };
-  const outcome = await requestHub(HUB_OPERATIONS.teamSendMessage, body, 3000, async () => {
-    const { teamSendMessage } = await import('./team/nativeProxy.mjs');
-    return await teamSendMessage(body);
-  });
+  const outcome = await requestHub(
+    HUB_OPERATIONS.teamSendMessage,
+    body,
+    3000,
+    async () => {
+      const { teamSendMessage } = await import("./team/nativeProxy.mjs");
+      return await teamSendMessage(body);
+    },
+  );
   const result = outcome?.result;
   return emitJson(result || unavailableResult());
 }
@@ -637,62 +923,122 @@ function getHubDbPath() {
 }
 
 async function cmdPipelineState(args) {
-  const outcome = await requestHub(HUB_OPERATIONS.pipelineState, { team_name: args.team }, 3000, async () => {
-    try {
-      const { default: Database } = await import('better-sqlite3');
-      const { ensurePipelineTable, readPipelineState } = await import('./pipeline/state.mjs');
-      const dbPath = getHubDbPath();
-      if (!existsSync(dbPath)) {
-        return { ok: false, error: 'hub_db_not_found' };
+  const outcome = await requestHub(
+    HUB_OPERATIONS.pipelineState,
+    { team_name: args.team },
+    3000,
+    async () => {
+      try {
+        const { default: Database } = await import("better-sqlite3");
+        const { ensurePipelineTable, readPipelineState } = await import(
+          "./pipeline/state.mjs"
+        );
+        const dbPath = getHubDbPath();
+        if (!existsSync(dbPath)) {
+          return { ok: false, error: "hub_db_not_found" };
+        }
+        const db = new Database(dbPath, { readonly: true });
+        ensurePipelineTable(db);
+        const state = readPipelineState(db, args.team);
+        db.close();
+        return state
+          ? { ok: true, data: state }
+          : { ok: false, error: "pipeline_not_found" };
+      } catch (e) {
+        return { ok: false, error: e.message };
       }
-      const db = new Database(dbPath, { readonly: true });
-      ensurePipelineTable(db);
-      const state = readPipelineState(db, args.team);
-      db.close();
-      return state
-        ? { ok: true, data: state }
-        : { ok: false, error: 'pipeline_not_found' };
-    } catch (e) {
-      return { ok: false, error: e.message };
-    }
-  });
+    },
+  );
   const result = outcome?.result;
   return emitJson(result || unavailableResult());
 }
 
+// Best-effort phase-manager bridge (silent on failure — pipeline 동작 영향 X)
+async function writePhaseSafely(runId, phase, status) {
+  if (!runId) return;
+  try {
+    const mod = await import("./lib/phase-manager.mjs");
+    if (typeof mod?.writePhase === "function") {
+      await mod.writePhase(runId, phase, status);
+    }
+    if (typeof mod?.syncToGstack === "function") {
+      const slug = process.cwd().split(/[\\/]/).pop();
+      await mod.syncToGstack(runId, slug);
+    }
+  } catch {
+    /* silent — phase tracking is best-effort */
+  }
+}
+
+async function writePhaseSafelyFromLegacy(runId, legacyStatus) {
+  if (!runId || !legacyStatus) return;
+  try {
+    const mod = await import("./lib/phase-manager.mjs");
+    if (typeof mod?.coerceLegacyPhase !== "function") return;
+    const coerced = mod.coerceLegacyPhase(legacyStatus);
+    if (!coerced) return;
+    if (coerced === "complete") {
+      const current =
+        typeof mod.readPhase === "function" ? await mod.readPhase(runId) : null;
+      const lastPhase = current?.phase || current?.lastPhase;
+      if (lastPhase) await mod.writePhase(runId, lastPhase, "complete");
+      return;
+    }
+    await mod.writePhase(runId, coerced, "active");
+    if (typeof mod?.syncToGstack === "function") {
+      const slug = process.cwd().split(/[\\/]/).pop();
+      await mod.syncToGstack(runId, slug);
+    }
+  } catch {
+    /* silent */
+  }
+}
+
 async function cmdPipelineAdvance(args) {
   const body = {
     team_name: args.team,
     phase: args.status, // --status를 phase로 재활용
   };
-  const outcome = await requestHub(HUB_OPERATIONS.pipelineAdvance, body, 3000, async () => {
-    try {
-      const { default: Database } = await import('better-sqlite3');
-      const { createPipeline } = await import('./pipeline/index.mjs');
-      const dbPath = getHubDbPath();
-      if (!existsSync(dbPath)) {
-        return { ok: false, error: 'hub_db_not_found' };
+  const outcome = await requestHub(
+    HUB_OPERATIONS.pipelineAdvance,
+    body,
+    3000,
+    async () => {
+      try {
+        const { default: Database } = await import("better-sqlite3");
+        const { createPipeline } = await import("./pipeline/index.mjs");
+        const dbPath = getHubDbPath();
+        if (!existsSync(dbPath)) {
+          return { ok: false, error: "hub_db_not_found" };
+        }
+        const db = new Database(dbPath);
+        const pipeline = createPipeline(db, args.team);
+        const advanceResult = pipeline.advance(args.status);
+        db.close();
+        return advanceResult;
+      } catch (e) {
+        return { ok: false, error: e.message };
       }
-      const db = new Database(dbPath);
-      const pipeline = createPipeline(db, args.team);
-      const advanceResult = pipeline.advance(args.status);
-      db.close();
-      return advanceResult;
-    } catch (e) {
-      return { ok: false, error: e.message };
-    }
-  });
+    },
+  );
   const result = outcome?.result;
+  if (args.team && args.status && result?.ok !== false) {
+    void writePhaseSafelyFromLegacy(args.team, args.status);
+  }
   return emitJson(result || unavailableResult());
 }
 
 async function cmdPipelineInit(args) {
   const outcome = await requestHub(HUB_OPERATIONS.pipelineInit, {
     team_name: args.team,
-    fix_max: args['fix-max'] != null ? Number(args['fix-max']) : undefined,
-    ralph_max: args['ralph-max'] != null ? Number(args['ralph-max']) : undefined,
+    fix_max: args["fix-max"] != null ? Number(args["fix-max"]) : undefined,
+    ralph_max:
+      args["ralph-max"] != null ? Number(args["ralph-max"]) : undefined,
   });
   const result = outcome?.result;
+  if (args.team && result?.ok !== false) {
+    void writePhaseSafely(args.team, "Strategy", "active");
+  }
   return emitJson(result || unavailableResult());
 }
 
@@ -703,25 +1049,29 @@ async function cmdPipelineList() {
 }
 
 async function cmdPing() {
-  const outcome = await requestHub(HUB_OPERATIONS.hubStatus, { scope: 'hub' }, 2000);
+  const outcome = await requestHub(
+    HUB_OPERATIONS.hubStatus,
+    { scope: "hub" },
+    2000,
+  );
 
-  if (outcome?.transport === 'pipe' && outcome.result?.ok) {
+  if (outcome?.transport === "pipe" && outcome.result?.ok) {
     return emitJson({
       ok: true,
-      hub: outcome.result.data?.hub?.state || 'healthy',
+      hub: outcome.result.data?.hub?.state || "healthy",
       pipe_path: getHubPipePath(),
-      transport: 'pipe',
+      transport: "pipe",
     });
   }
 
-  if (outcome?.transport === 'http' && outcome.result) {
+  if (outcome?.transport === "http" && outcome.result) {
     const data = outcome.result;
     return emitJson({
       ok: true,
       hub: data.hub?.state,
       sessions: data.sessions,
       pipe_path: data.pipe?.path || data.pipe_path || null,
-      transport: 'http',
+      transport: "http",
     });
   }
 
@@ -731,21 +1081,26 @@ async function cmdPing() {
 async function cmdDelegatorDelegate(args) {
   const body = {
     prompt: args.text || args.prompt,
-    provider: args.provider || 'auto',
-    mode: args.mode || 'sync',
-    agent_type: args.agent || 'executor',
-    mcp_profile: args['mcp-profile'] || 'auto',
-    session_key: args['session-key'] || undefined,
-    timeout_ms: args['timeout-ms'] != null ? Number(args['timeout-ms']) : undefined,
+    provider: args.provider || "auto",
+    mode: args.mode || "sync",
+    agent_type: args.agent || "executor",
+    mcp_profile: args["mcp-profile"] || "auto",
+    session_key: args["session-key"] || undefined,
+    timeout_ms:
+      args["timeout-ms"] != null ? Number(args["timeout-ms"]) : undefined,
   };
-  const timeoutMs = body.mode === 'async' ? 10000 : 120000;
-  const outcome = await requestHub(HUB_OPERATIONS.delegatorDelegate, body, timeoutMs);
+  const timeoutMs = body.mode === "async" ? 10000 : 120000;
+  const outcome = await requestHub(
+    HUB_OPERATIONS.delegatorDelegate,
+    body,
+    timeoutMs,
+  );
   return emitJson(outcome?.result || unavailableResult());
 }
 
 async function cmdDelegatorReply(args) {
   const body = {
-    job_id: args['job-id'],
+    job_id: args["job-id"],
     reply: args.text || args.reply,
     done: !!args.done,
   };
@@ -755,45 +1110,231 @@ async function cmdDelegatorReply(args) {
 
 async function cmdDelegatorStatus(args) {
   const body = {
-    job_id: args['job-id'],
+    job_id: args["job-id"],
   };
   const outcome = await requestHub(HUB_OPERATIONS.delegatorStatus, body, 5000);
   return emitJson(outcome?.result || unavailableResult());
 }
 
+async function cmdHitlRequest(args) {
+  const body = {
+    kind: args[1],
+    prompt: args[2],
+    requester_agent: args[3] || "cli",
+  };
+  const outcome = await requestHub(
+    HUB_OPERATIONS["hitl-request"],
+    body,
+    120000,
+  );
+  return emitJson(outcome?.result || unavailableResult());
+}
+
+async function cmdHitlSubmit(args) {
+  const body = {
+    request_id: args[1],
+    action: args[2] || "accept",
+    content: args[3],
+  };
+  const outcome = await requestHub(HUB_OPERATIONS["hitl-submit"], body, 120000);
+  return emitJson(outcome?.result || unavailableResult());
+}
+
+async function cmdHitlPending() {
+  const outcome = await requestHub(HUB_OPERATIONS["hitl-pending"], {}, 5000);
+  return emitJson(outcome?.result || unavailableResult());
+}
+
+// ---------------------------------------------------------------------------
+// retry-run / retry-status — Phase 3 Step C2 bridge 서브커맨드.
+// retry-state-machine.mjs 를 multi-process safe 하게 외부 호출용 wrap.
+// 사용자 워크플로우:
+//   1) 첫 호출: retry-run --snapshot X --mode ralph --event start
+//      → 새 SM 생성, PLANNING → EXECUTING transition, snapshot 저장
+//   2) verify 성공 시: retry-run --snapshot X --event verify-success
+//      → DONE, 종료 판단 반환
+//   3) verify 실패 시: retry-run --snapshot X --event verify-fail --reason R
+//      → DIAGNOSING 또는 STUCK/BUDGET_EXCEEDED, 종료 판단 반환
+//   4) 다음 iter 시작: retry-run --snapshot X --event start
+// 출력: {ok, current, iterations, done, shouldStop, reason?, cli?} JSON.
+// ---------------------------------------------------------------------------
+
+function buildRetrySmFromArgs(args, snapshot) {
+  const mode = args.mode || snapshot?.mode || "bounded";
+  const maxIterations =
+    args["max-iterations"] !== undefined
+      ? Number(args["max-iterations"])
+      : snapshot?.maxIterations;
+  const sessionId = args["session-id"] || snapshot?.sessionId || null;
+  const cliChain = snapshot?.cliChain;
+
+  const sm = createRetryStateMachine({
+    mode,
+    maxIterations,
+    sessionId,
+    cliChain,
+  });
+  if (snapshot) sm.applySnapshot(snapshot);
+  return sm;
+}
+
+async function cmdRetryRun(args) {
+  const snapshotFile = args.snapshot || args["snapshot-file"];
+  const event = args.event;
+  const reason = args.reason || "";
+
+  if (!snapshotFile) {
+    console.error("--snapshot <path> required");
+    return false;
+  }
+  if (!event) {
+    console.error("--event <start|verify-success|verify-fail> required");
+    return false;
+  }
+
+  const existing = loadSnapshot(snapshotFile);
+  const sm = buildRetrySmFromArgs(args, existing);
+
+  let result;
+  switch (event) {
+    case "start":
+      result = sm.startIteration();
+      break;
+    case "verify-success":
+      result = sm.reportVerifySuccess();
+      break;
+    case "verify-fail":
+      result = sm.reportVerifyFail(reason || "unspecified");
+      break;
+    default:
+      console.error(`unknown --event: ${event}`);
+      return false;
+  }
+
+  const snap = sm.serialize();
+  saveSnapshot(snapshotFile, snap);
+
+  const terminal = ["DONE", "STUCK", "BUDGET_EXCEEDED"].includes(snap.current);
+  const cli = snap.cliChain?.[snap.cliIndex] || null;
+  const out = {
+    ok: true,
+    current: snap.current,
+    iterations: snap.iterations,
+    cliIndex: snap.cliIndex,
+    cli,
+    done: snap.current === "DONE",
+    shouldStop: terminal,
+    stuckCounter: snap.stuckCounter,
+    lastFailureReason: snap.lastFailureReason,
+    transition: result,
+  };
+  console.log(JSON.stringify(out));
+  return true;
+}
+
+async function cmdRetryStatus(args) {
+  const snapshotFile = args.snapshot || args["snapshot-file"];
+  if (!snapshotFile) {
+    console.error("--snapshot <path> required");
+    return false;
+  }
+  const snap = loadSnapshot(snapshotFile);
+  if (!snap) {
+    console.log(JSON.stringify({ ok: true, exists: false }));
+    return true;
+  }
+  const terminal = ["DONE", "STUCK", "BUDGET_EXCEEDED"].includes(snap.current);
+  const cli = snap.cliChain?.[snap.cliIndex] || null;
+  console.log(
+    JSON.stringify({
+      ok: true,
+      exists: true,
+      current: snap.current,
+      iterations: snap.iterations,
+      maxIterations: snap.maxIterations,
+      cliIndex: snap.cliIndex,
+      cli,
+      mode: snap.mode,
+      shouldStop: terminal,
+      stuckCounter: snap.stuckCounter,
+      lastFailureReason: snap.lastFailureReason,
+    }),
+  );
+  return true;
+}
+
 export async function main(argv = process.argv.slice(2)) {
   const cmd = argv[0];
   const args = parseArgs(argv.slice(1));
 
   switch (cmd) {
-    case 'register': return await cmdRegister(args);
-    case 'result': return await cmdResult(args);
-    case 'control': return await cmdControl(args);
-    case 'context': return await cmdContext(args);
-    case 'deregister': return await cmdDeregister(args);
-    case 'assign-async': return await cmdAssignAsync(args);
-    case 'assign-result': return await cmdAssignResult(args);
-    case 'assign-status': return await cmdAssignStatus(args);
-    case 'assign-retry': return await cmdAssignRetry(args);
-    case 'team-info': return await cmdTeamInfo(args);
-    case 'team-task-list': return await cmdTeamTaskList(args);
-    case 'team-task-update': return await cmdTeamTaskUpdate(args);
-    case 'team-send-message': return await cmdTeamSendMessage(args);
-    case 'pipeline-state': return await cmdPipelineState(args);
-    case 'pipeline-advance': return await cmdPipelineAdvance(args);
-    case 'pipeline-init': return await cmdPipelineInit(args);
-    case 'pipeline-list': return await cmdPipelineList(args);
-    case 'ping': return await cmdPing(args);
-    case 'delegator-delegate': return await cmdDelegatorDelegate(args);
-    case 'delegator-reply': return await cmdDelegatorReply(args);
-    case 'delegator-status': return await cmdDelegatorStatus(args);
+    case "register":
+      return await cmdRegister(args);
+    case "result":
+      return await cmdResult(args);
+    case "control":
+      return await cmdControl(args);
+    case "handoff":
+      return await cmdHandoff(args);
+    case "publish":
+      return await cmdPublish(args);
+    case "send-input":
+      return await cmdSendInput(args);
+    case "context":
+      return await cmdContext(args);
+    case "deregister":
+      return await cmdDeregister(args);
+    case "assign-async":
+      return await cmdAssignAsync(args);
+    case "assign-result":
+      return await cmdAssignResult(args);
+    case "assign-status":
+      return await cmdAssignStatus(args);
+    case "assign-retry":
+      return await cmdAssignRetry(args);
+    case "team-info":
+      return await cmdTeamInfo(args);
+    case "team-task-list":
+      return await cmdTeamTaskList(args);
+    case "team-task-update":
+      return await cmdTeamTaskUpdate(args);
+    case "team-send-message":
+      return await cmdTeamSendMessage(args);
+    case "pipeline-state":
+      return await cmdPipelineState(args);
+    case "pipeline-advance":
+      return await cmdPipelineAdvance(args);
+    case "pipeline-init":
+      return await cmdPipelineInit(args);
+    case "pipeline-list":
+      return await cmdPipelineList(args);
+    case "ping":
+      return await cmdPing(args);
+    case "delegator-delegate":
+      return await cmdDelegatorDelegate(args);
+    case "delegator-reply":
+      return await cmdDelegatorReply(args);
+    case "delegator-status":
+      return await cmdDelegatorStatus(args);
+    case "hitl-request":
+      return await cmdHitlRequest(args);
+    case "hitl-submit":
+      return await cmdHitlSubmit(args);
+    case "hitl-pending":
+      return await cmdHitlPending(args);
+    case "retry-run":
+      return await cmdRetryRun(args);
+    case "retry-status":
+      return await cmdRetryStatus(args);
     default:
-      console.error('사용법: bridge.mjs <register|result|control|context|deregister|assign-async|assign-result|assign-status|assign-retry|team-info|team-task-list|team-task-update|team-send-message|pipeline-state|pipeline-advance|pipeline-init|pipeline-list|ping|delegator-delegate|delegator-reply|delegator-status> [--옵션]');
+      console.error(
+        "사용법: bridge.mjs <register|result|control|handoff|publish|send-input|context|deregister|assign-async|assign-result|assign-status|assign-retry|team-info|team-task-list|team-task-update|team-send-message|pipeline-state|pipeline-advance|pipeline-init|pipeline-list|ping|delegator-delegate|delegator-reply|delegator-status|hitl-request|hitl-submit|hitl-pending|retry-run|retry-status> [--옵션]",
+      );
       process.exit(1);
   }
 }
 
-const selfRun = process.argv[1]?.replace(/\\/g, '/').endsWith('hub/bridge.mjs');
+const selfRun = process.argv[1]?.replace(/\\/g, "/").endsWith("hub/bridge.mjs");
 if (selfRun) {
-  process.exitCode = await main() ? 0 : 1;
+  process.exitCode = (await main()) ? 0 : 1;
 }