@triflux/core 10.0.3 → 10.25.1

package/hub/state.mjs

@@ -1,20 +1,34 @@
-import { execSync } from 'node:child_process';
-import { mkdirSync, openSync, closeSync, unlinkSync, writeFileSync, readFileSync, renameSync, existsSync, statSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const PROJECT_ROOT = fileURLToPath(new URL('..', import.meta.url));
-const PID_FILE_NAME = 'hub.pid';
-const LEGACY_STATE_FILE_NAME = 'hub-state.json';
-const LOCK_FILE_NAME = 'hub-start.lock';
+import { execSync } from "node:child_process";
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PROJECT_ROOT = fileURLToPath(new URL("..", import.meta.url));
+const PID_FILE_NAME = "hub.pid";
+const LEGACY_STATE_FILE_NAME = "hub-state.json";
+const LOCK_FILE_NAME = "hub-start.lock";
 
 let heldLockPath = null;
 let heldLockFd = null;
 let cachedVersionHash = null;
 
 function getStateDir(options = {}) {
-  return options.stateDir || process.env.TFX_HUB_STATE_DIR?.trim() || join(homedir(), '.claude', 'cache', 'tfx-hub');
+  return (
+    options.stateDir ||
+    process.env.TFX_HUB_STATE_DIR?.trim() ||
+    join(homedir(), ".claude", "cache", "tfx-hub")
+  );
 }
 
 function getStatePath(options = {}) {
@@ -55,25 +69,32 @@ function safeReplaceFile(tempPath, targetPath) {
   try {
     renameSync(tempPath, targetPath);
   } catch (error) {
-    if (!['EEXIST', 'EPERM', 'EACCES'].includes(error?.code)) {
-      try { unlinkSync(tempPath); } catch {}
+    if (!["EEXIST", "EPERM", "EACCES"].includes(error?.code)) {
+      try {
+        unlinkSync(tempPath);
+      } catch {}
       throw error;
     }
-    try { unlinkSync(targetPath); } catch {}
+    try {
+      unlinkSync(targetPath);
+    } catch {}
     renameSync(tempPath, targetPath);
   }
 }
 
 function writeJsonFile(targetPath, payload) {
   const tempPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
-  writeFileSync(tempPath, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  writeFileSync(tempPath, `${JSON.stringify(payload, null, 2)}\n`, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
   safeReplaceFile(tempPath, targetPath);
 }
 
 function readJsonFile(filePath) {
   try {
     if (!existsSync(filePath)) return null;
-    return parseJson(readFileSync(filePath, 'utf8'), null);
+    return parseJson(readFileSync(filePath, "utf8"), null);
   } catch {
     return null;
   }
@@ -82,7 +103,7 @@ function readJsonFile(filePath) {
 /**
  * 허브의 현재 상태(PID, 포트, 버전 등)를 파일에 기록합니다.
  * 원자적(atomic) 쓰기를 위해 임시 파일을 생성한 후 교체하는 방식을 사용합니다.
- * 
+ *
  * @param {object} payload - 상태 데이터
  * @param {number} payload.pid - 허브 프로세스 ID
  * @param {number} payload.port - 허브 서버 포트
@@ -93,31 +114,39 @@ function readJsonFile(filePath) {
  * @param {string} [options.stateDir] - 상태 파일이 저장될 디렉토리
  * @returns {object} 기록된 상태 데이터
  */
-export function writeState({ pid, port, version, sessionId, startedAt, ...rest }, options = {}) {
+export function writeState(
+  { pid, port, version, sessionId, startedAt, ...rest },
+  options = {},
+) {
   const stateDir = getStateDir(options);
   const statePath = getStatePath(options);
   const payload = { pid, port, version, sessionId, startedAt, ...rest };
 
   mkdirSync(stateDir, { recursive: true });
   writeJsonFile(statePath, payload);
-  try { unlinkSync(getLegacyStatePath(options)); } catch {}
+  try {
+    unlinkSync(getLegacyStatePath(options));
+  } catch {}
   return payload;
 }
 
 /**
  * 파일로부터 허브의 현재 상태를 읽어옵니다.
- * 
+ *
  * @param {object} [options] - 옵션
  * @param {string} [options.stateDir] - 상태 파일이 저장된 디렉토리
  * @returns {object|null} 읽어온 상태 데이터 또는 실패 시 null
  */
 export function readState(options = {}) {
-  return readJsonFile(getStatePath(options)) ?? readJsonFile(getLegacyStatePath(options));
+  return (
+    readJsonFile(getStatePath(options)) ??
+    readJsonFile(getLegacyStatePath(options))
+  );
 }
 
 /**
  * 지정된 포트에서 실행 중인 허브 서버의 헬스 체크를 수행합니다.
- * 
+ *
  * @param {number|string} port - 서버 포트
  * @param {object} [options] - 옵션
  * @param {number} [options.timeoutMs=1000] - 요청 타임아웃
@@ -133,7 +162,7 @@ export async function isServerHealthy(port, options = {}) {
 
   try {
     const response = await fetch(`${baseUrl}/health`, {
-      method: 'GET',
+      method: "GET",
       signal: AbortSignal.timeout(timeoutMs),
     });
     if (!response.ok) return false;
@@ -147,7 +176,7 @@ export async function isServerHealthy(port, options = {}) {
 /**
  * 현재 프로젝트의 버전 해시를 생성합니다.
  * package.json의 버전과 Git commit SHA를 조합합니다.
- * 
+ *
  * @param {object} [options] - 옵션
  * @param {boolean} [options.force=false] - 캐시를 무시하고 새로 생성할지 여부
  * @returns {string} 버전 해시 문자열
@@ -155,21 +184,21 @@ export async function isServerHealthy(port, options = {}) {
 export function getVersionHash(options = {}) {
   if (cachedVersionHash && !options.force) return cachedVersionHash;
 
-  const packageJsonPath = join(PROJECT_ROOT, 'package.json');
-  const pkg = parseJson(readFileSync(packageJsonPath, 'utf8'), {});
-  const version = String(pkg?.version || '0.0.0').trim();
+  const packageJsonPath = join(PROJECT_ROOT, "package.json");
+  const pkg = parseJson(readFileSync(packageJsonPath, "utf8"), {});
+  const version = String(pkg?.version || "0.0.0").trim();
 
-  let sha = String(process.env.TFX_HUB_GIT_SHA || '').trim();
+  let sha = String(process.env.TFX_HUB_GIT_SHA || "").trim();
   if (!sha) {
     try {
-      sha = execSync('git rev-parse --short HEAD', {
+      sha = execSync("git rev-parse --short HEAD", {
         cwd: PROJECT_ROOT,
-        encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'ignore'],
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
         windowsHide: true,
       }).trim();
     } catch {
-      sha = '';
+      sha = "";
     }
   }
 
@@ -180,7 +209,7 @@ export function getVersionHash(options = {}) {
 /**
  * 허브 시작 시 중복 실행을 방지하기 위한 잠금(lock)을 획득합니다.
  * 이미 실행 중인 다른 프로세스가 있는지 확인하고 유효한 잠금을 획득할 때까지 재시도합니다.
- * 
+ *
  * @param {object} [options] - 옵션
  * @param {number} [options.timeoutMs=3000] - 최대 대기 시간
  * @param {number} [options.pollMs=50] - 재시도 간격
@@ -202,27 +231,38 @@ export async function acquireLock(options = {}) {
 
   while (Date.now() <= deadline) {
     try {
-      const fd = openSync(lockPath, 'wx', 0o600);
-      writeFileSync(fd, `${JSON.stringify({
-        pid: process.pid,
-        createdAt: new Date().toISOString(),
-      }, null, 2)}\n`, 'utf8');
+      const fd = openSync(lockPath, "wx", 0o600);
+      writeFileSync(
+        fd,
+        `${JSON.stringify(
+          {
+            pid: process.pid,
+            createdAt: new Date().toISOString(),
+          },
+          null,
+          2,
+        )}\n`,
+        "utf8",
+      );
       heldLockFd = fd;
       heldLockPath = lockPath;
       return { path: lockPath };
     } catch (error) {
-      if (error?.code !== 'EEXIST') {
+      if (error?.code !== "EEXIST") {
         throw error;
       }
 
       try {
-        const raw = readFileSync(lockPath, 'utf8');
+        const raw = readFileSync(lockPath, "utf8");
         const data = parseJson(raw, {});
         const stats = statSync(lockPath);
+        const STALE_LOCK_AGE_MS = 60_000;
         const staleByPid = !isPidAlive(data?.pid);
-        const staleByAge = Date.now() - stats.mtimeMs > timeoutMs;
+        const staleByAge = Date.now() - stats.mtimeMs > STALE_LOCK_AGE_MS;
         if (staleByPid || staleByAge) {
-          try { unlinkSync(lockPath); } catch {}
+          try {
+            unlinkSync(lockPath);
+          } catch {}
           continue;
         }
       } catch {}
@@ -236,7 +276,7 @@ export async function acquireLock(options = {}) {
 
 /**
  * 획득했던 잠금을 해제합니다. 잠금 파일을 삭제하고 관련 리소스를 정리합니다.
- * 
+ *
  * @param {object} [options] - 옵션
  * @param {string} [options.lockPath] - 명시적인 잠금 파일 경로
  */
@@ -244,7 +284,9 @@ export function releaseLock(options = {}) {
   const lockPath = options.lockPath || heldLockPath || getLockPath(options);
 
   if (heldLockFd !== null) {
-    try { closeSync(heldLockFd); } catch {}
+    try {
+      closeSync(heldLockFd);
+    } catch {}
     heldLockFd = null;
   }
 

package/hub/team/retry-state-machine.mjs

@@ -0,0 +1,267 @@
+// hub/team/retry-state-machine.mjs
+// Phase 3 Step A — true ralph / auto-escalate retry state machine.
+// 설계 문서: .triflux/plans/phase3-lead-codex-ralph-escalate.md
+//
+// Modes:
+//   bounded       — --retry 1 (기본): maxIterations 도달 시 BUDGET_EXCEEDED.
+//   ralph         — --retry ralph: maxIterations=0 이면 unlimited. stuck detector 만 종료.
+//   auto-escalate — --retry auto-escalate: BUDGET_EXCEEDED 시 다음 CLI 로 전이.
+//
+// 상태 전이:
+//   PLANNING → EXECUTING → VERIFYING.success → DONE
+//                       → VERIFYING.fail   → DIAGNOSING → EXECUTING …
+//                       → stuckCounter≥3   → STUCK
+//                       → iter≥max         → BUDGET_EXCEEDED (escalate 모드는 다음 CLI)
+
+import { EventEmitter } from "node:events";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+
+export const STATES = Object.freeze({
+  PLANNING: "PLANNING",
+  EXECUTING: "EXECUTING",
+  DIAGNOSING: "DIAGNOSING",
+  STUCK: "STUCK",
+  BUDGET_EXCEEDED: "BUDGET_EXCEEDED",
+  DONE: "DONE",
+});
+
+export const MODES = Object.freeze({
+  BOUNDED: "bounded",
+  RALPH: "ralph",
+  ESCALATE: "auto-escalate",
+});
+
+// Escalation chain (2026-04-25 정책):
+//   1. gpt-5.4-mini   — 비용 최저, fast tier, 단순 task 대부분 해결
+//   2. gpt-5.3-codex  — 가성비 중간, code specialized (Plus/free 모두 OK, fast 미지원)
+//   3. gpt-5.5         — top reasoning + 코드 강함, fast tier
+//   4. claude opus-4-7 — 최종 수단
+// sonnet-4-6 단계는 제거: gpt-5.5 가 코드/추론/비용 모두 우위 + 5.3-codex 가성비
+// 단계가 더 적합한 중간 격상.
+const DEFAULT_ESCALATION_CHAIN = Object.freeze([
+  Object.freeze({ cli: "codex", model: "gpt-5.4-mini" }),
+  Object.freeze({ cli: "codex", model: "gpt-5.3-codex" }),
+  Object.freeze({ cli: "codex", model: "gpt-5.5" }),
+  Object.freeze({ cli: "claude", model: "opus-4-7" }),
+]);
+
+const STUCK_THRESHOLD = 3;
+
+export function createRetryStateMachine(options = {}) {
+  const mode = options.mode || MODES.BOUNDED;
+  const cliChain = Array.isArray(options.cliChain)
+    ? options.cliChain.slice()
+    : DEFAULT_ESCALATION_CHAIN.slice();
+  const maxIterationsInput =
+    typeof options.maxIterations === "number" ? options.maxIterations : null;
+  const maxIterations =
+    maxIterationsInput !== null
+      ? maxIterationsInput
+      : mode === MODES.BOUNDED
+        ? 3
+        : 0;
+  const stateFile = options.stateFile || null;
+  const sessionId = options.sessionId || null;
+
+  const emitter = new EventEmitter();
+  const state = {
+    current: STATES.PLANNING,
+    iterations: 0,
+    maxIterations,
+    stuckCounter: 0,
+    lastFailureReason: null,
+    cliIndex: 0,
+    cliChain,
+    mode,
+    sessionId,
+    stateFile,
+    history: [],
+  };
+
+  function transition(next, meta = {}) {
+    const prev = state.current;
+    state.current = next;
+    const entry = {
+      t: Date.now(),
+      from: prev,
+      to: next,
+      iteration: state.iterations,
+      cliIndex: state.cliIndex,
+      ...meta,
+    };
+    state.history.push(entry);
+    if (stateFile) persistTransition(stateFile, entry);
+    emitter.emit("transition", entry);
+    return entry;
+  }
+
+  function startIteration() {
+    state.iterations += 1;
+    return transition(STATES.EXECUTING, { iteration: state.iterations });
+  }
+
+  function reportVerifySuccess() {
+    return transition(STATES.DONE);
+  }
+
+  function reportVerifyFail(failureReason) {
+    const reason = String(failureReason || "unknown");
+    if (reason === state.lastFailureReason) {
+      state.stuckCounter += 1;
+    } else {
+      state.stuckCounter = 1;
+      state.lastFailureReason = reason;
+    }
+
+    if (state.stuckCounter >= STUCK_THRESHOLD) {
+      return transition(STATES.STUCK, {
+        reason,
+        stuckCounter: state.stuckCounter,
+      });
+    }
+
+    if (state.maxIterations > 0 && state.iterations >= state.maxIterations) {
+      if (state.mode === MODES.ESCALATE) {
+        return escalate();
+      }
+      return transition(STATES.BUDGET_EXCEEDED, {
+        reason,
+        iterations: state.iterations,
+      });
+    }
+
+    return transition(STATES.DIAGNOSING, { reason });
+  }
+
+  function escalate() {
+    if (state.cliIndex + 1 >= state.cliChain.length) {
+      return transition(STATES.BUDGET_EXCEEDED, {
+        reason: "escalation-chain-exhausted",
+        chain: state.cliChain,
+      });
+    }
+    state.cliIndex += 1;
+    state.iterations = 0;
+    state.stuckCounter = 0;
+    state.lastFailureReason = null;
+    return transition(STATES.EXECUTING, {
+      cli: state.cliChain[state.cliIndex],
+      escalated: true,
+    });
+  }
+
+  function getCurrent() {
+    return {
+      current: state.current,
+      iterations: state.iterations,
+      maxIterations: state.maxIterations,
+      stuckCounter: state.stuckCounter,
+      lastFailureReason: state.lastFailureReason,
+      cliIndex: state.cliIndex,
+      cliChain: state.cliChain.slice(),
+      mode: state.mode,
+      sessionId: state.sessionId,
+      history: state.history.slice(),
+    };
+  }
+
+  function on(event, listener) {
+    emitter.on(event, listener);
+    return () => emitter.off(event, listener);
+  }
+
+  function serialize() {
+    return {
+      version: 1,
+      current: state.current,
+      iterations: state.iterations,
+      maxIterations: state.maxIterations,
+      stuckCounter: state.stuckCounter,
+      lastFailureReason: state.lastFailureReason,
+      cliIndex: state.cliIndex,
+      cliChain: state.cliChain.slice(),
+      mode: state.mode,
+      sessionId: state.sessionId,
+      history: state.history.slice(),
+    };
+  }
+
+  function applySnapshot(snapshot) {
+    if (!snapshot || typeof snapshot !== "object") return;
+    state.current = snapshot.current || STATES.PLANNING;
+    state.iterations = Number(snapshot.iterations) || 0;
+    state.maxIterations =
+      snapshot.maxIterations !== undefined
+        ? Number(snapshot.maxIterations)
+        : state.maxIterations;
+    state.stuckCounter = Number(snapshot.stuckCounter) || 0;
+    state.lastFailureReason = snapshot.lastFailureReason || null;
+    state.cliIndex = Number(snapshot.cliIndex) || 0;
+    if (Array.isArray(snapshot.cliChain) && snapshot.cliChain.length > 0) {
+      state.cliChain = snapshot.cliChain.slice();
+    }
+    if (snapshot.mode) state.mode = snapshot.mode;
+    if (snapshot.sessionId !== undefined) state.sessionId = snapshot.sessionId;
+    if (Array.isArray(snapshot.history))
+      state.history = snapshot.history.slice();
+  }
+
+  return {
+    STATES,
+    MODES,
+    getCurrent,
+    startIteration,
+    reportVerifySuccess,
+    reportVerifyFail,
+    escalate,
+    on,
+    serialize,
+    applySnapshot,
+  };
+}
+
+function persistTransition(stateFile, entry) {
+  const dir = dirname(stateFile);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  appendFileSync(stateFile, `${JSON.stringify(entry)}\n`, "utf8");
+}
+
+export function resumeFromStateFile(stateFile) {
+  if (!existsSync(stateFile)) return null;
+  const raw = readFileSync(stateFile, "utf8").trim();
+  if (!raw) return null;
+  const lines = raw.split("\n").filter(Boolean);
+  if (lines.length === 0) return null;
+  return JSON.parse(lines[lines.length - 1]);
+}
+
+// Full-snapshot 기반 stateFile I/O — bridge retry-run 에서 multi-process state 복원용.
+// transition event log (resumeFromStateFile) 와 별도 파일로 관리하는 것을 권장.
+export function loadSnapshot(snapshotFile) {
+  if (!existsSync(snapshotFile)) return null;
+  const raw = readFileSync(snapshotFile, "utf8").trim();
+  if (!raw) return null;
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== "object") return null;
+  if (parsed.version !== 1) {
+    throw new Error(
+      `unsupported snapshot version: ${parsed.version} (expected 1)`,
+    );
+  }
+  return parsed;
+}
+
+export function saveSnapshot(snapshotFile, snapshot) {
+  const dir = dirname(snapshotFile);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(snapshotFile, JSON.stringify(snapshot), "utf8");
+}
+
+export { DEFAULT_ESCALATION_CHAIN, STUCK_THRESHOLD };