triflux 10.14.1 → 10.14.3

package/hub/team/conductor.mjs

@@ -696,8 +696,10 @@ export function createConductor(opts = {}) {
       },
       {
         ...probeOpts,
+        // #165: default off → on. atomic write (#162) 로 race 제거됨.
+        // opt-out: TFX_PROBE_WRITE_STATE=0 명시.
         writeStateFile:
-          probeOpts.writeStateFile ?? process.env.TFX_PROBE_WRITE_STATE === "1",
+          probeOpts.writeStateFile ?? process.env.TFX_PROBE_WRITE_STATE !== "0",
         onProbe: (result) => handleProbeResult(session, result),
       },
     );

package/hub/team/health-probe.mjs

@@ -2,7 +2,7 @@
 // 기존 cli-adapter-base.mjs:stallThresholdMs(30s)와 headless.mjs:STALL_DEFAULTS(120s)를
 // 4단계 probe 모델로 교체. stdout+stderr 통합 스트림으로 평가 (F3 해결).
 
-import { mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 
@@ -84,6 +84,16 @@ export function createHealthProbe(session, opts = {}) {
   const config = { ...PROBE_DEFAULTS, ...opts };
   let timer = null;
   let started = false;
+  // stopped flag는 in-flight probe()가 stop() 사이의 await 점에서
+  // writeState/unlink 와 race 하는 것을 막는다. start() 시 false 로 reset.
+  let stopped = false;
+  // P0 (#167 review): start() 마다 증가. probe() 가 시작 시 캡처 → writeState() 가 epoch
+  // 비교로 stop()→start() 사이의 in-flight 가 새 run 의 state 를 덮는 race 차단.
+  // stopped flag 만으로는 start() 가 stopped=false 로 reset 한 직후 race 못 막음.
+  let runEpoch = 0;
+  // P1-1 (#167 review): Set 으로 모든 in-flight probe 추적. interval 이 빨라 N+1 이 N 끝나기
+  // 전에 시작되면 단일 var 는 N 을 덮어써 stopAndDrain() 시 N 이 누락된다.
+  const inFlightProbes = new Set();
 
   // L1 tracking
   let lastOutputBytes = 0;
@@ -120,28 +130,76 @@ export function createHealthProbe(session, opts = {}) {
     return "active";
   }
 
-  function writeState(result) {
+  function writeState(result, probeEpoch) {
+    // stop() 직후 in-flight probe()의 재생성 방지.
+    // P0 (#167): probeEpoch !== runEpoch 면 이전 run 의 stale probe 가 새 run 의 state 를
+    // 덮으려는 시도 → skip.
+    if (stopped) return;
+    if (probeEpoch !== undefined && probeEpoch !== runEpoch) return;
     if (!config.writeStateFile && !config.stateFile) return;
     const stateFile = getStateFilePath();
     if (!stateFile) return;
+    const payload =
+      JSON.stringify(
+        {
+          pid: session.pid ?? null,
+          state: deriveState(result),
+          result,
+          updatedAt: new Date(result.ts).toISOString(),
+        },
+        null,
+        2,
+      ) + "\n";
+    // tmp+rename 으로 atomic write — heartbeat 의 sed 가 부분 파일을 읽는 race 제거.
+    // tmp 는 같은 디렉토리에 둬야 EXDEV (cross-device link) 가 안 난다.
+    const tmpPath = `${stateFile}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     try {
       mkdirSync(dirname(stateFile), { recursive: true });
-      writeFileSync(
-        stateFile,
-        JSON.stringify(
-          {
-            pid: session.pid ?? null,
-            state: deriveState(result),
-            result,
-            updatedAt: new Date(result.ts).toISOString(),
-          },
-          null,
-          2,
-        ) + "\n",
-        "utf8",
-      );
+      writeFileSync(tmpPath, payload, "utf8");
+      try {
+        renameSync(tmpPath, stateFile);
+      } catch (renameErr) {
+        // Windows: 대상이 존재할 때 EPERM/EACCES.
+        // P1-2 (#167 review): backup-then-swap 으로 기존 파일 보존. 옛 unlinkSync→renameSync
+        // 패턴은 1차 unlink 후 2차 rename 실패 시 기존 파일과 tmp 둘 다 잃었다.
+        if (
+          renameErr?.code === "EEXIST" ||
+          renameErr?.code === "EPERM" ||
+          renameErr?.code === "EACCES"
+        ) {
+          const backupPath = `${stateFile}.old-${process.pid}-${Date.now()}`;
+          let backupCreated = false;
+          try {
+            renameSync(stateFile, backupPath);
+            backupCreated = true;
+          } catch {
+            // backup 실패 (대상 없음/잠김) — 그래도 진행 (tmp→stateFile 시도)
+          }
+          try {
+            renameSync(tmpPath, stateFile);
+            if (backupCreated) {
+              try {
+                unlinkSync(backupPath);
+              } catch {}
+            }
+          } catch (secondErr) {
+            // 2차도 실패 → backup 복구해서 기존 파일 보존
+            if (backupCreated) {
+              try {
+                renameSync(backupPath, stateFile);
+              } catch {}
+            }
+            throw secondErr;
+          }
+        } else {
+          throw renameErr;
+        }
+      }
     } catch {
-      // probe state is advisory only.
+      // probe state is advisory only — tmp cleanup
+      try {
+        unlinkSync(tmpPath);
+      } catch {}
     }
   }
 
@@ -264,30 +322,44 @@ export function createHealthProbe(session, opts = {}) {
 
   /**
    * 전체 probe 실행 (L0→L1→L2→L3).
-   * @returns {Promise<object>} probe 결과
+   * @returns {Promise<object|null>} probe 결과. stop() 이후 호출이면 null.
    */
   async function probe() {
-    const result = {
-      l0: probeL0(),
-      l1: probeL1(),
-      l2: await probeL2(),
-      l3: probeL3(),
-      inputWaitPattern: status.inputWaitPattern,
-      ts: Date.now(),
-    };
-    status.lastProbeAt = result.ts;
-    writeState(result);
-
-    if (typeof config.onProbe === "function") {
-      config.onProbe(result);
-    }
+    if (stopped) return null;
+    // P0 (#167): probe 시작 시 epoch 캡처. start() 가 새 epoch 로 바꾸면 이 probe 의
+    // writeState 는 stale 로 판정 → skip.
+    const probeEpoch = runEpoch;
+    const promise = (async () => {
+      const result = {
+        l0: probeL0(),
+        l1: probeL1(),
+        l2: await probeL2(),
+        l3: probeL3(),
+        inputWaitPattern: status.inputWaitPattern,
+        ts: Date.now(),
+      };
+      status.lastProbeAt = result.ts;
+      writeState(result, probeEpoch);
+
+      if (typeof config.onProbe === "function") {
+        config.onProbe(result);
+      }
 
-    return result;
+      return result;
+    })();
+    // P1-1 (#167): Set 으로 모든 in-flight 추적. 단일 var 패턴은 N+1 이 N 끝나기 전에
+    // 시작되면 N 을 덮어써 stopAndDrain() 시 N 이 누락된다.
+    inFlightProbes.add(promise);
+    promise.finally(() => inFlightProbes.delete(promise));
+    return promise;
   }
 
   function start() {
     if (started) return;
     started = true;
+    stopped = false;
+    // P0 (#167): epoch 증가 — 이전 run 의 in-flight probe 가 새 run 의 state 를 덮지 못하게.
+    runEpoch += 1;
     spawnedAt = Date.now();
     lastOutputChangeAt = Date.now();
     lastOutputBytes = 0;
@@ -305,6 +377,9 @@ export function createHealthProbe(session, opts = {}) {
   function stop() {
     if (!started) return;
     started = false;
+    // stopped 를 먼저 set 해야 in-flight probe()의 writeState() 가 skip 된다.
+    // 이후 unlink — in-flight 가 끝나도 writeState 가 no-op 이므로 재생성 없음.
+    stopped = true;
     if (timer) {
       clearInterval(timer);
       timer = null;
@@ -317,6 +392,19 @@ export function createHealthProbe(session, opts = {}) {
     }
   }
 
+  /**
+   * stop() 후 in-flight probe() 가 완료될 때까지 대기.
+   * 결정적 종료가 필요한 테스트/teardown 용. conductor 의 sync stop() 호출자는
+   * 그대로 stop() 만 호출하면 stopped flag 가 race 를 막는다.
+   */
+  async function stopAndDrain() {
+    stop();
+    // P1-1 (#167): 모든 in-flight probe 대기. allSettled 로 unhandled rejection 방지.
+    if (inFlightProbes.size > 0) {
+      await Promise.allSettled(Array.from(inFlightProbes));
+    }
+  }
+
   /** L1 tracking 리셋 (restart 후 호출) */
   function resetTracking() {
     lastOutputBytes = 0;
@@ -333,6 +421,7 @@ export function createHealthProbe(session, opts = {}) {
   return Object.freeze({
     start,
     stop,
+    stopAndDrain,
     probe,
     resetTracking,
     getStatus: () => ({ ...status }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "10.14.1",
+  "version": "10.14.3",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {

package/scripts/__tests__/mcp-guard-engine.test.mjs

@@ -101,14 +101,16 @@ describe("mcp guard engine", () => {
     );
   });
 
-  it("replaces stdio MCP entries with tfx-hub and writes a backup", () => {
+  it("replaces stdio MCP entries with tfx-hub and writes a backup (TFX_HUB_PORT env overrides)", () => {
     const homeDir = createHomeDir();
     withHome(homeDir);
+    process.env.TFX_HUB_PORT = "30123";
 
+    // hub.pid port 는 무시되어야 한다 (PR #158: pid = host hint only).
     const pidPath = join(homeDir, ".claude", "cache", "tfx-hub", "hub.pid");
     writeFileSync(
       pidPath,
-      JSON.stringify({ host: "127.0.0.1", port: 30123 }),
+      JSON.stringify({ host: "127.0.0.1", port: 40404 }),
       "utf8",
     );
 
@@ -141,9 +143,18 @@ describe("mcp guard engine", () => {
     assert.equal(Object.hasOwn(updated.mcpServers, "unsafe-stdio"), false);
   });
 
-  it("uses hub.pid port before registry fallback when resolving Hub URL", () => {
+  it("uses TFX_HUB_PORT env as single source when resolving Hub URL", () => {
     const homeDir = createHomeDir();
     withHome(homeDir);
+    process.env.TFX_HUB_PORT = "29991";
+
+    assert.equal(resolveHubUrl(), "http://127.0.0.1:29991/mcp");
+  });
+
+  it("ignores hub.pid port (pid is host hint only, PR #158 policy)", () => {
+    const homeDir = createHomeDir();
+    withHome(homeDir);
+    delete process.env.TFX_HUB_PORT;
 
     writeFileSync(
       join(homeDir, ".claude", "cache", "tfx-hub", "hub.pid"),
@@ -151,6 +162,8 @@ describe("mcp guard engine", () => {
       "utf8",
     );
 
-    assert.equal(resolveHubUrl(), "http://127.0.0.1:29991/mcp");
+    // env 없음 + hub.pid port 존재 → registry/default 27888 fallback.
+    // pid port cascade 가 제거되어 29991 이 쓰이면 안 됨.
+    assert.equal(resolveHubUrl(), "http://127.0.0.1:27888/mcp");
   });
 });

package/scripts/lib/mcp-guard-engine.mjs

@@ -851,14 +851,13 @@ export function resolveHubUrl() {
         : DEFAULT_HUB_PATH,
   };
 
+  // PR #158 정책: port = TFX_HUB_PORT env (없으면 registry/default 27888) single source.
+  // hub.pid 는 loopback host 힌트 전용. 과거 pid port cascade 는 오염된 port 영속화의
+  // 원인이었고 hub-ensure.resolveHubTarget 에서 이미 제거됨. 여기도 일관 적용.
   const hubPidPath = join(homedir(), ".claude", "cache", "tfx-hub", "hub.pid");
   if (existsSync(hubPidPath)) {
     try {
       const info = readJsonFile(hubPidPath);
-      if (!envPort) {
-        const pidPort = Number(info?.port);
-        if (Number.isFinite(pidPort) && pidPort > 0) target.port = pidPort;
-      }
       if (typeof info?.host === "string") {
         const host = info.host.trim();
         if (LOOPBACK_HOSTS.has(host)) target.host = host;

package/scripts/tfx-route.sh

@@ -320,6 +320,12 @@ read_probe_state() {
   local pid="$1"
   local state_file="${TFX_PROBE_STATE_FILE:-${TFX_PROBE_DIR}/${pid}.json}"
   [[ -f "$state_file" ]] || return 1
+  # 2-step read (#162): health-probe.mjs 의 atomic write (tmp+rename) 가 도입되었지만
+  # writer 쪽 OS race 또는 race-free 보장을 못 받는 환경 (예: 일부 FS) 에서 빈/부분 파일
+  # 을 sed 가 읽고 stale state 를 반환하는 것을 방지하기 위해 size 가 너무 작으면 무시.
+  local size
+  size=$(wc -c < "$state_file" 2>/dev/null || printf '0')
+  [[ "$size" -ge 20 ]] || return 1
   sed -n 's/.*"state"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$state_file" 2>/dev/null | head -1
 }
 RUN_ID="${TIMESTAMP}-$$-${RANDOM}"
@@ -1422,12 +1428,25 @@ heartbeat_monitor() {
         stall_count=0
         echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B${expected_suffix} status=${probe_state}(probe-grace)" >&2
       elif [[ "$stall_count" -ge "$stall_threshold" ]]; then
-        # STALL kill (#144/#66 regression guard): stall=threshold+grace 이상 지속 시 SIGTERM→SIGKILL.
-        # 땜빵(PLANNING P4 구현 전): default 1 → 0. false kill >> true stuck 비용이 압도적이라
-        # opt-in 으로 전환. debug 필요 시 TFX_STALL_KILL=1 로 명시 활성화. classify mode는 차기.
-        local kill_on_stall="${TFX_STALL_KILL:-0}"
+        # STALL 판정 modes (#165 PLANNING P4):
+        #   off  (alias: 0, disabled)  — silent. kill 안 함, STALL_CLASSIFY 로그도 없음
+        #   classify (default)          — kill 안 함. STALL_CLASSIFY 로그로 evidence 노출
+        #   kill (alias: 1, on)         — threshold+grace 초과 시 SIGTERM→SIGKILL
+        # PR #160 에서 default 1 → 0 으로 임시 후퇴 (false kill 방지). 본 PR(#165) 에서
+        # classify 로 승격 — evidence 는 남기되 false kill 리스크 없음.
+        local kill_on_stall="${TFX_STALL_KILL:-classify}"
+        [[ -z "$kill_on_stall" ]] && kill_on_stall="classify"
         local kill_grace="${TFX_STALL_KILL_GRACE:-30}"
-        if [[ "$kill_on_stall" -eq 1 && "$stall_count" -ge $((stall_threshold + kill_grace)) ]]; then
+        local _should_kill=0
+        case "$kill_on_stall" in
+          1|on|kill) _should_kill=1 ;;
+          classify|0|off|disabled) ;;
+          *)
+            echo "[tfx-heartbeat] pid=$pid warning TFX_STALL_KILL=$kill_on_stall unknown, fallback classify" >&2
+            kill_on_stall="classify"
+            ;;
+        esac
+        if [[ "$_should_kill" -eq 1 && "$stall_count" -ge $((stall_threshold + kill_grace)) ]]; then
           echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B${expected_suffix} status=STALL_KILL stall=${stall_count}s — SIGTERM" >&2
           # Snapshot child PIDs before SIGTERM — wrapper 가 SIGTERM 을 수용해 죽으면
           # 부모 소멸 후 taskkill /T 가 자식 트리를 탐색하지 못해 codex 자식이 orphan 으로 남는다.
@@ -1476,6 +1495,9 @@ heartbeat_monitor() {
           fi
           break
         fi
+        if [[ "$kill_on_stall" == "classify" && "$stall_count" -ge $((stall_threshold + kill_grace)) ]]; then
+          echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B${expected_suffix} status=STALL_CLASSIFY stall=${stall_count}s (no-kill — TFX_STALL_KILL=classify)" >&2
+        fi
         echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B${expected_suffix} status=STALL stall=${stall_count}s" >&2
       else
         echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B${expected_suffix} status=quiet stall=${stall_count}s" >&2