@triflux/remote 10.1.0 → 10.25.1

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 };

package/hub/team/routing.mjs

@@ -15,31 +15,55 @@
 export function resolveRoutingStrategy({ subtasks, graph_type, thorough }) {
   const N = subtasks.length;
   if (N === 0) {
-    const dagContext = { dag_width: 0, levels: {}, edges: [], max_complexity: 'S', taskResults: {} };
-    return { strategy: 'quick_single', reason: 'empty_subtasks', dag_width: 0, max_complexity: 'S', dagContext };
+    const dagContext = {
+      dag_width: 0,
+      levels: {},
+      edges: [],
+      max_complexity: "S",
+      taskResults: {},
+    };
+    return {
+      strategy: "quick_single",
+      reason: "empty_subtasks",
+      dag_width: 0,
+      max_complexity: "S",
+      dagContext,
+    };
   }
 
-  const { width: dag_width, levels, edges } = computeDagInfo(subtasks, graph_type);
+  const {
+    width: dag_width,
+    levels,
+    edges,
+  } = computeDagInfo(subtasks, graph_type);
   const max_complexity = getMaxComplexity(subtasks);
-  const dagContext = { dag_width, levels, edges, max_complexity, taskResults: {} };
-  const isHighComplexity = ['L', 'XL'].includes(max_complexity);
+  const dagContext = {
+    dag_width,
+    levels,
+    edges,
+    max_complexity,
+    taskResults: {},
+  };
+  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');
+  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',
+        strategy: "thorough_single",
+        reason: "single_high_complexity",
         dag_width,
         max_complexity,
         dagContext,
       };
     }
     return {
-      strategy: 'quick_single',
-      reason: 'single_low_complexity',
+      strategy: "quick_single",
+      reason: "single_low_complexity",
       dag_width,
       max_complexity,
       dagContext,
@@ -50,16 +74,16 @@ export function resolveRoutingStrategy({ subtasks, graph_type, thorough }) {
   if (dag_width === 1) {
     if (thorough || isHighComplexity) {
       return {
-        strategy: 'thorough_single',
-        reason: 'sequential_chain',
+        strategy: "thorough_single",
+        reason: "sequential_chain",
         dag_width,
         max_complexity,
         dagContext,
       };
     }
     return {
-      strategy: 'quick_single',
-      reason: 'sequential_chain',
+      strategy: "quick_single",
+      reason: "sequential_chain",
       dag_width,
       max_complexity,
       dagContext,
@@ -69,8 +93,8 @@ export function resolveRoutingStrategy({ subtasks, graph_type, thorough }) {
   // 동일 에이전트 + 모두 S: 프롬프트 병합 -> batch single
   if (allSameAgent && allSmall) {
     return {
-      strategy: 'batch_single',
-      reason: 'same_agent_small_batch',
+      strategy: "batch_single",
+      reason: "same_agent_small_batch",
       dag_width,
       max_complexity,
       dagContext,
@@ -80,16 +104,16 @@ export function resolveRoutingStrategy({ subtasks, graph_type, thorough }) {
   // dag_width >= 2: 팀
   if (thorough || isHighComplexity) {
     return {
-      strategy: 'thorough_team',
-      reason: 'parallel_high_complexity',
+      strategy: "thorough_team",
+      reason: "parallel_high_complexity",
       dag_width,
       max_complexity,
       dagContext,
     };
   }
   return {
-    strategy: 'quick_team',
-    reason: 'parallel_low_complexity',
+    strategy: "quick_team",
+    reason: "parallel_low_complexity",
     dag_width,
     max_complexity,
     dagContext,
@@ -103,7 +127,7 @@ export function resolveRoutingStrategy({ subtasks, graph_type, thorough }) {
  * @returns {{ width: number, levels: Record<number, string[]>, edges: Array<{from:string, to:string}> }}
  */
 function computeDagInfo(subtasks, graph_type) {
-  if (graph_type === 'SEQUENTIAL') {
+  if (graph_type === "SEQUENTIAL") {
     const levels = {};
     const edges = [];
     subtasks.forEach((t, i) => {
@@ -112,7 +136,7 @@ function computeDagInfo(subtasks, graph_type) {
     });
     return { width: 1, levels, edges };
   }
-  if (graph_type === 'INDEPENDENT') {
+  if (graph_type === "INDEPENDENT") {
     const levels = { 0: subtasks.map((t) => t.id) };
     return { width: subtasks.length, levels, edges: [] };
   }
@@ -173,7 +197,9 @@ function computeDagInfo(subtasks, graph_type) {
 export function getUpstreamResults(taskId, pipelineState) {
   const ctx = pipelineState?.dagContext;
   if (!ctx) return {};
-  const upstreamIds = ctx.edges.filter((e) => e.to === taskId).map((e) => e.from);
+  const upstreamIds = ctx.edges
+    .filter((e) => e.to === taskId)
+    .map((e) => e.from);
   const results = {};
   for (const id of upstreamIds) {
     if (id in (ctx.taskResults || {})) {
@@ -205,7 +231,7 @@ export function updateTaskResult(taskId, result, pipelineState) {
  */
 function getMaxComplexity(subtasks) {
   const order = { S: 0, M: 1, L: 2, XL: 3 };
-  let max = 'S';
+  let max = "S";
   for (const s of subtasks) {
     const complexity = normalizeComplexity(s.complexity);
     if (order[complexity] > order[max]) max = complexity;
@@ -219,5 +245,5 @@ function getMaxComplexity(subtasks) {
  * @returns {"S" | "M" | "L" | "XL"}
  */
 function normalizeComplexity(complexity) {
-  return ['S', 'M', 'L', 'XL'].includes(complexity) ? complexity : 'M';
+  return ["S", "M", "L", "XL"].includes(complexity) ? complexity : "M";
 }

package/hub/team/runtime-strategy.mjs

@@ -0,0 +1,200 @@
+import {
+  createPsmuxSession,
+  killPsmuxSession,
+  psmuxSessionExists,
+} from "./psmux.mjs";
+import { tmuxExec } from "./session.mjs";
+
+/**
+ * @typedef {object} RuntimeStatus
+ * @property {string} name
+ * @property {string} sessionName
+ * @property {boolean} alive
+ */
+
+/**
+ * @typedef {object} TeamRuntime
+ * @property {(sessionName: string, opts?: object) => unknown} start
+ * @property {(sessionName: string) => void} stop
+ * @property {(sessionName: string) => boolean} isAlive
+ * @property {(sessionName: string) => RuntimeStatus} getStatus
+ */
+
+const defaultPsmuxAdapter = {
+  createSession: createPsmuxSession,
+  killSession: killPsmuxSession,
+  hasSession: psmuxSessionExists,
+};
+
+/**
+ * @param {{
+ *   createSession: typeof createPsmuxSession,
+ *   killSession: typeof killPsmuxSession,
+ *   hasSession: typeof psmuxSessionExists,
+ * }} [adapter]
+ * @returns {TeamRuntime & { name: "psmux" }}
+ */
+export function createPsmuxRuntime(adapter = defaultPsmuxAdapter) {
+  return {
+    name: "psmux",
+    start(sessionName, opts = {}) {
+      return adapter.createSession(sessionName, opts);
+    },
+    stop(sessionName) {
+      adapter.killSession(sessionName);
+    },
+    isAlive(sessionName) {
+      return adapter.hasSession(sessionName);
+    },
+    getStatus(sessionName) {
+      return {
+        name: "psmux",
+        sessionName,
+        alive: adapter.hasSession(sessionName),
+      };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// tmux 어댑터
+// ---------------------------------------------------------------------------
+
+// tmux 세션 이름은 tmuxExec 명령 문자열에 직접 보간되므로 shell 메타문자가 들어오면 위험.
+// 현 호출처는 모두 safe identifier (slug/uuid 류) 이지만 어댑터 export 가 contract 를
+// 강제하지 않아 외부 호출자가 임의 문자열을 주입할 수 있다 → 보수적으로 검증.
+const TMUX_SAFE_SESSION_NAME = /^[A-Za-z0-9_.:-]+$/;
+
+function assertSafeTmuxSessionName(sessionName) {
+  const value = String(sessionName ?? "");
+  if (!TMUX_SAFE_SESSION_NAME.test(value)) {
+    throw new Error(
+      `Unsafe tmux session name: ${JSON.stringify(value)} (allowed: A-Za-z0-9_.:-)`,
+    );
+  }
+  return value;
+}
+
+function tmuxSessionExists(sessionName) {
+  const safe = assertSafeTmuxSessionName(sessionName);
+  try {
+    tmuxExec(`has-session -t ${safe}`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function createTmuxSession(sessionName, opts = {}) {
+  const safe = assertSafeTmuxSessionName(sessionName);
+  tmuxExec(`new-session -d -s ${safe} -x 220 -y 55`);
+}
+
+function sendPromptToTmuxSession(sessionName, prompt) {
+  const safe = assertSafeTmuxSessionName(sessionName);
+  const quotedPrompt = String(prompt).replace(/'/g, "'\\''");
+  tmuxExec(`send-keys -t ${safe}:0.0 '${quotedPrompt}' Enter`);
+}
+
+function killTmuxSessionByName(sessionName) {
+  let safe;
+  try {
+    safe = assertSafeTmuxSessionName(sessionName);
+  } catch {
+    return;
+  }
+  try {
+    tmuxExec(`kill-session -t ${safe}`);
+  } catch {
+    // 이미 종료된 세션 — 무시
+  }
+}
+
+const defaultTmuxAdapter = {
+  createSession: createTmuxSession,
+  sendPrompt: sendPromptToTmuxSession,
+  killSession: killTmuxSessionByName,
+  hasSession: tmuxSessionExists,
+};
+
+/**
+ * @param {{
+ *   createSession: typeof createTmuxSession,
+ *   sendPrompt: typeof sendPromptToTmuxSession,
+ *   killSession: typeof killTmuxSessionByName,
+ *   hasSession: typeof tmuxSessionExists,
+ * }} [opts.adapter]
+ * @param {string} [opts.sessionName]
+ * @returns {{
+ *   name: "tmux",
+ *   kind: "tmux",
+ *   sessionName: string,
+ *   createSession: (opts?: object) => unknown,
+ *   sendPrompt: (prompt: string) => unknown,
+ *   start: (sessionName: string, opts?: object) => unknown,
+ *   stop: (sessionName: string) => void,
+ *   isAlive: (sessionName: string) => boolean,
+ *   getStatus: (sessionName: string) => RuntimeStatus,
+ * }}
+ */
+export function createTmuxRuntime(opts = {}) {
+  const { adapter = defaultTmuxAdapter, sessionName = "" } = opts;
+
+  return {
+    name: "tmux",
+    kind: "tmux",
+    sessionName,
+    // start() 와 동일하게 첫 인자로 sessionName override 를 받는다.
+    // 첫 인자가 string 이 아니면 (옵션 객체 등) closure sessionName 을 사용하는 legacy 형태로 폴백.
+    createSession(sessionNameArg, opts) {
+      if (typeof sessionNameArg === "string") {
+        return adapter.createSession(sessionNameArg, opts ?? {});
+      }
+      return adapter.createSession(sessionName, sessionNameArg ?? {});
+    },
+    sendPrompt(prompt, sessionNameArg = sessionName) {
+      return adapter.sendPrompt(sessionNameArg, prompt);
+    },
+    start(sessionNameArg = sessionName, opts = {}) {
+      return adapter.createSession(sessionNameArg, opts);
+    },
+    stop(sessionNameArg = sessionName) {
+      adapter.killSession(sessionNameArg);
+    },
+    isAlive(sessionNameArg = sessionName) {
+      return adapter.hasSession(sessionNameArg);
+    },
+    getStatus(sessionNameArg = sessionName) {
+      return {
+        name: "tmux",
+        sessionName: sessionNameArg,
+        alive: adapter.hasSession(sessionNameArg),
+      };
+    },
+  };
+}
+
+/**
+ * @param {string} mode
+ * @param {object} [opts]
+ * @returns {TeamRuntime & { name: string }}
+ */
+export function createRuntime(mode, opts = {}) {
+  const normalizedMode = String(mode || "")
+    .trim()
+    .toLowerCase();
+
+  if (normalizedMode === "psmux") {
+    return createPsmuxRuntime();
+  }
+
+  if (normalizedMode === "tmux") {
+    return createTmuxRuntime(opts);
+  }
+
+  if (normalizedMode === "native" || normalizedMode === "wt") {
+    throw new Error(`Runtime mode "${normalizedMode}" is not implemented yet.`);
+  }
+
+  throw new Error(`Unsupported runtime mode: ${mode}`);
+}

package/hub/team/schemas/worker-completion.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "WorkerCompletion",
+  "description": "Self-reported worker completion payload emitted by a swarm shard worker.",
+  "type": "object",
+  "required": ["status"],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["ok", "skipped", "failed"]
+    },
+    "shard": { "type": "string" },
+    "reason": { "type": "string" },
+    "commits_made": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["sha"],
+        "properties": {
+          "sha": { "type": "string", "minLength": 7 },
+          "message": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true,
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "const": "ok" } } },
+      "then": {
+        "required": ["commits_made"],
+        "properties": {
+          "commits_made": { "minItems": 1 }
+        }
+      }
+    }
+  ]
+}