triflux 10.13.1 → 10.13.3

package/.claude-plugin/marketplace.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "triflux",
+  "description": "CLI-first multi-model orchestrator — Codex/Gemini/Claude routing with DAG execution, auto-triage, and cost optimization",
+  "owner": {
+    "name": "tellang"
+  },
+  "plugins": [
+    {
+      "name": "triflux",
+      "description": "Tri-CLI orchestrator for Claude Code. Routes tasks across Claude + Codex + Gemini with consensus intelligence, natural language routing, 42 skills, and cross-model review.",
+      "version": "10.13.3",
+      "author": {
+        "name": "tellang"
+      },
+      "source": {
+        "source": "npm",
+        "package": "triflux"
+      },
+      "category": "productivity",
+      "homepage": "https://github.com/tellang/triflux",
+      "tags": [
+        "multi-model",
+        "codex",
+        "gemini",
+        "cli-routing",
+        "orchestration",
+        "cost-optimization",
+        "dag-execution"
+      ]
+    }
+  ],
+  "version": "10.13.3"
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "triflux",
+  "version": "10.13.3",
+  "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
+  "author": {
+    "name": "tellang"
+  },
+  "repository": "https://github.com/tellang/triflux",
+  "homepage": "https://github.com/tellang/triflux",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "codex",
+    "gemini",
+    "cli-routing",
+    "orchestration",
+    "multi-model"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks.json"
+}

package/bin/triflux.mjs

@@ -134,7 +134,8 @@ const CLI_COMMAND_SCHEMAS = Object.freeze({
     ],
   },
   doctor: {
-    usage: "tfx doctor [--fix] [--reset] [--audit] [--diagnose] [--json]",
+    usage:
+      "tfx doctor [--fix] [--reset] [--audit] [--diagnose] [--purge-logs] [--json]",
     description: "설치 상태 진단 및 자동 복구",
     options: [
       {
@@ -158,6 +159,12 @@ const CLI_COMMAND_SCHEMAS = Object.freeze({
         description:
           "진단 번들(zip) 생성: spawn-trace + hook timing + system info",
       },
+      {
+        name: "--purge-logs",
+        type: "boolean",
+        description:
+          "--fix 와 함께 사용. cli-issues.jsonl 에서 7일 초과 항목 물리 삭제 (#144)",
+      },
       {
         name: "--json",
         type: "boolean",
@@ -1742,7 +1749,12 @@ function ensureValidRegistryState() {
 }
 
 async function cmdDoctor(options = {}) {
-  const { fix = false, reset = false, json = false } = options;
+  const {
+    fix = false,
+    reset = false,
+    purgeLogs = false,
+    json = false,
+  } = options;
   const report = {
     status: "ok",
     mode: reset ? "reset" : fix ? "fix" : "check",
@@ -2357,9 +2369,20 @@ async function cmdDoctor(options = {}) {
           info(`업데이트 권장:\n${formatPsmuxUpdateGuidance("  ")}`);
         }
         if (psmuxSupport.missingOptionalCommands?.length > 0) {
+          // #144: 단순히 "detach-first hardening 경로에서만 사용" 만으로는 사용자가
+          // 영향 범위와 해결 방법을 알 수 없다. 각 capability 별 영향과 업그레이드 명령을 명시.
           info(
-            `선택 capability 미지원: ${psmuxSupport.missingOptionalCommands.join(", ")} (detach-first hardening 경로에서만 사용)`,
+            `선택 capability 미지원: ${psmuxSupport.missingOptionalCommands.join(", ")}`,
           );
+          if (psmuxSupport.missingOptionalCommands.includes("detach-client")) {
+            info(
+              "  detach-client: WT 1.24 ConPTY close-race 회피용. WT 기반 병렬 실행(swarm dashboard, tfx-multi wt 모드) 에서 pane freeze/ConPTY hang 위험 증가.",
+            );
+            info(
+              "  해결: psmux v3.4+ 로 업그레이드. 현재 psmux 업그레이드 명령:",
+            );
+            info(`${formatPsmuxUpdateGuidance("    ")}`);
+          }
         }
 
         // 기본 셸 확인: psmux 세션의 기본 셸이 PowerShell인지 cmd.exe인지
@@ -2771,6 +2794,10 @@ async function cmdDoctor(options = {}) {
           ).version;
           let cleaned = 0;
 
+          // #144: 오래된 로그 노이즈 완화 — 7일 초과 항목은 INFO 레벨로 downgrade.
+          // --fix --purge-logs 플래그가 있으면 해당 오래된 항목은 실제 삭제.
+          const STALE_AGE_MS = 7 * 24 * 3600 * 1000;
+          let purged = 0;
           for (const [key, g] of Object.entries(groups)) {
             const fixVer = KNOWN_FIXES[key];
             if (fixVer && semverGte(currentVer, fixVer)) {
@@ -2785,30 +2812,62 @@ async function cmdDoctor(options = {}) {
                 : age < 86400000
                   ? `${Math.round(age / 3600000)}시간 전`
                   : `${Math.round(age / 86400000)}일 전`;
-            const sev =
-              g.severity === "error"
+            const isStale = age >= STALE_AGE_MS;
+            if (isStale && fix && purgeLogs) {
+              purged += g.count;
+              continue;
+            }
+            const sev = isStale
+              ? `${CYAN}INFO${RESET}`
+              : g.severity === "error"
                 ? `${RED}ERROR${RESET}`
                 : `${YELLOW}WARN${RESET}`;
-            warn(`[${sev}] ${g.cli}/${g.pattern} x${g.count} (최근: ${ago})`);
+            const staleTag = isStale ? " [STALE]" : "";
+            if (isStale) {
+              info(
+                `[${sev}]${staleTag} ${g.cli}/${g.pattern} x${g.count} (최근: ${ago})`,
+              );
+            } else {
+              warn(`[${sev}] ${g.cli}/${g.pattern} x${g.count} (최근: ${ago})`);
+            }
             if (g.snippet) info(`  ${g.snippet.substring(0, 120)}`);
             if (fixVer)
               info(`  해결: triflux >= v${fixVer} (npm update -g triflux)`);
-            issues++;
+            if (isStale && !purgeLogs) {
+              info(`  7일 초과 — 삭제: tfx doctor --fix --purge-logs`);
+            }
+            if (!isStale) issues++;
           }
 
-          // 해결된 이슈 자동 정리
-          if (cleaned > 0) {
+          // #144 Codex review P2: 두 filter (stale purge + KNOWN_FIXES) 가 각각 원본 entries 로
+          // write 하면 두 번째 write 가 첫 번째 결과를 되살린다. 단일 통합 필터로 한 번만 저장.
+          if (purged > 0 || cleaned > 0) {
+            const now = Date.now();
             const remaining = entries.filter((e) => {
+              // purge-logs 로 물리 삭제 대상: 7일 초과
+              if (purged > 0 && now - e.ts >= STALE_AGE_MS) return false;
+              // KNOWN_FIXES 해결된 이슈 제거
               const key = `${e.cli}:${e.pattern}`;
               const fixVer = KNOWN_FIXES[key];
-              return !(fixVer && semverGte(currentVer, fixVer));
+              if (fixVer && semverGte(currentVer, fixVer)) return false;
+              return true;
             });
             writeFileSync(
               issuesFile,
               remaining.map((e) => JSON.stringify(e)).join("\n") +
                 (remaining.length ? "\n" : ""),
             );
-            ok(`${cleaned}개 해결된 이슈 자동 정리됨`);
+            if (purged > 0) {
+              ok(`${purged}개 stale 로그 항목 삭제 (7일 초과)`);
+              report.actions.push({
+                name: "purge-stale-logs",
+                status: "applied",
+                count: purged,
+              });
+            }
+            if (cleaned > 0) {
+              ok(`${cleaned}개 해결된 이슈 자동 정리됨`);
+            }
           }
           addDoctorCheck(report, {
             name: "cli-issues",
@@ -3373,6 +3432,56 @@ async function cmdDoctor(options = {}) {
           if (row.actualUrl) info(`actual   ${row.actualUrl}`);
         }
 
+        // #144: --fix 모드에서 tfx-hub URL 불일치를 hub status 기준으로 자동 갱신.
+        // Project MCP (.mcp.json) 와 Codex/Claude/Gemini settings 모두 대상.
+        // Codex review P2: fix 성공 시 issues 집계에서 차감해야 doctor 결과가 ok 로 반영됨.
+        let autoFixedMismatches = 0;
+        if (fix && mismatchRows.some((r) => r.name === "tfx-hub")) {
+          try {
+            const hubUrl = mismatchRows.find(
+              (r) => r.name === "tfx-hub",
+            )?.expectedUrl;
+            if (hubUrl) {
+              const { syncHubMcpSettings, syncProjectMcpJson } = await import(
+                "../scripts/sync-hub-mcp-settings.mjs"
+              );
+              const settingsResult = await syncHubMcpSettings({
+                hubUrl,
+                logger: { log() {}, warn() {}, error() {} },
+              });
+              const projectResult = await syncProjectMcpJson({
+                hubUrl,
+                projectRoot: process.cwd(),
+                logger: { log() {}, warn() {}, error() {} },
+              });
+              const totalUpdated =
+                (settingsResult?.updated?.length || 0) +
+                (projectResult?.updated?.length || 0);
+              if (totalUpdated > 0) {
+                ok(`tfx-hub URL ${totalUpdated}개 파일 자동 갱신 (${hubUrl})`);
+                report.actions.push({
+                  name: "sync-hub-url",
+                  status: "applied",
+                  files: [
+                    ...(settingsResult?.updated || []),
+                    ...(projectResult?.updated || []),
+                  ],
+                });
+                // fix 성공 — mismatchRows 중 tfx-hub 엔트리는 해결된 것으로 집계
+                autoFixedMismatches = mismatchRows.filter(
+                  (r) => r.name === "tfx-hub",
+                ).length;
+              } else {
+                info("tfx-hub URL 자동 갱신: 대상 파일 없음");
+              }
+            }
+          } catch (e) {
+            warn(
+              `tfx-hub URL 자동 갱신 실패: ${e?.message?.split(/\r?\n/)[0] || e}`,
+            );
+          }
+        }
+
         for (const row of missingFileRows) {
           info(
             `${row.label}: ${row.name} 미배치 (${formatPathForDisplay(row.filePath)})`,
@@ -3395,7 +3504,7 @@ async function cmdDoctor(options = {}) {
         }
 
         issues += invalidConfigs.length;
-        issues += mismatchRows.length;
+        issues += Math.max(0, mismatchRows.length - autoFixedMismatches);
         issues += stdioRows.length;
       }
     }
@@ -5508,7 +5617,8 @@ async function main() {
       }
       const fix = cmdArgs.includes("--fix");
       const reset = cmdArgs.includes("--reset");
-      await cmdDoctor({ fix, reset, json: JSON_OUTPUT });
+      const purgeLogs = cmdArgs.includes("--purge-logs");
+      await cmdDoctor({ fix, reset, purgeLogs, json: JSON_OUTPUT });
       return;
     }
     case "mcp":

package/config/mcp-registry.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "mcp-registry-schema",
+  "version": 1,
+  "description": "MCP 서버 중앙 레지스트리 — 진실의 원천",
+  "defaults": {
+    "transport": "hub-url",
+    "hub_base": "http://127.0.0.1:27888"
+  },
+  "servers": {
+    "tfx-hub": {
+      "transport": "hub-url",
+      "url": "http://127.0.0.1:27888/mcp",
+      "safe": true,
+      "targets": ["claude", "gemini", "codex"],
+      "description": "triflux Hub MCP 서버"
+    }
+  },
+  "policies": {
+    "stdio_action": "replace-with-hub",
+    "unknown_server_action": "warn",
+    "watched_paths": [
+      "~/.gemini/settings.json",
+      "~/.codex/config.toml",
+      "~/.claude/settings.json",
+      "~/.claude/settings.local.json",
+      ".mcp.json"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "10.13.1",
+  "version": "10.13.3",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {
@@ -13,26 +13,77 @@
     "tfx-doctor-tui": "bin/tfx-doctor-tui.mjs",
     "tfx-setup-tui": "bin/tfx-setup-tui.mjs"
   },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "@triflux/core": "10.0.1",
-    "@triflux/remote": "^10.0.0-alpha.1"
-  },
   "files": [
     "bin",
+    "tui",
+    "hub",
+    "config",
     "skills",
+    "!skills/tfx-workspace",
+    "!**/failure-reports",
+    "scripts",
     "hooks",
     "hud",
-    "scripts",
-    "hub",
     "mesh",
-    "references",
-    "CLAUDE.md",
+    ".claude-plugin",
     "README.md",
+    "README.ko.md",
     "LICENSE"
   ],
+  "workspaces": [
+    "packages/core",
+    "packages/remote",
+    "packages/triflux"
+  ],
+  "scripts": {
+    "pack": "node scripts/pack.mjs all",
+    "pack:core": "node scripts/pack.mjs core",
+    "pack:remote": "node scripts/pack.mjs remote",
+    "setup": "node scripts/setup.mjs",
+    "preinstall": "node scripts/preinstall.mjs",
+    "postinstall": "node scripts/setup.mjs",
+    "lint": "biome check bin config hooks hub hud mesh scripts tests .claude-plugin .github package.json package-lock.json biome.json",
+    "lint:fix": "biome check --write bin config hooks hub hud mesh scripts tests .claude-plugin .github package.json package-lock.json biome.json",
+    "health": "npm test && npm run lint",
+    "test": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=8 \"tests/**/*.test.mjs\" \"scripts/__tests__/**/*.test.mjs\"",
+    "test:unit": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=8 tests/unit/**/*.test.mjs",
+    "test:integration": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=8 tests/integration/**/*.test.mjs",
+    "test:route-smoke": "node scripts/test-lock.mjs --test scripts/test-tfx-route-no-claude-native.mjs",
+    "test:contract": "node scripts/test-lock.mjs --test --test-force-exit --test-concurrency=8 tests/contract/**/*.test.mjs",
+    "test:coverage": "node --experimental-test-coverage --test-coverage-lines=60 --test-coverage-functions=60 --test --test-force-exit --test-concurrency=8 \"tests/**/*.test.mjs\"",
+    "gen:skill-docs": "node scripts/gen-skill-docs.mjs",
+    "gen:skill-manifest": "node scripts/gen-skill-manifest.mjs",
+    "release:check-sync": "node scripts/release/check-sync.mjs",
+    "release:check-sync:fix": "node scripts/release/check-sync.mjs --fix",
+    "release:check-mirror": "node scripts/release/check-packages-mirror.mjs",
+    "release:check-mirror:fix": "node scripts/release/check-packages-mirror.mjs --fix",
+    "release:bump": "node scripts/release/bump-version.mjs",
+    "release:prepare": "node scripts/release/prepare.mjs",
+    "release:publish": "node scripts/release/publish.mjs",
+    "release:verify": "node scripts/release/verify.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tellang/triflux.git"
+  },
+  "homepage": "https://github.com/tellang/triflux#readme",
+  "author": "tellang",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.6.2",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "systray2": "^2.1.4",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "knip": "^6.3.0"
+  },
   "keywords": [
     "claude-code",
     "plugin",
@@ -43,13 +94,5 @@
     "multi-model",
     "triflux",
     "tfx"
-  ],
-  "author": "tellang",
-  "license": "MIT",
-  "homepage": "https://github.com/tellang/triflux#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/tellang/triflux.git",
-    "directory": "packages/triflux"
-  }
+  ]
 }

package/scripts/__tests__/setup-cleanup-stale-skills.test.mjs

@@ -0,0 +1,105 @@
+// scripts/__tests__/setup-cleanup-stale-skills.test.mjs
+// #144: cleanupStaleSkills 가 nested directory 를 가진 stale 스킬도 재귀 삭제하는지 확인.
+//
+// 이전 구현은 top-level 파일만 unlinkSync → 하위 폴더 있는 과거 스킬
+// (tfx-deep-*, tfx-codex-swarm 등) 은 제거 실패 → "triflux update 돌려도 13개 그대로" UX bug.
+
+import assert from "node:assert/strict";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { after, describe, it } from "node:test";
+
+const SETUP_MJS_URL = new URL("../setup.mjs", import.meta.url).href;
+const { cleanupStaleSkills } = await import(SETUP_MJS_URL);
+
+describe("#144 cleanupStaleSkills — 재귀 삭제", () => {
+  const cleanupDirs = [];
+  after(() => {
+    for (const d of cleanupDirs) rmSync(d, { recursive: true, force: true });
+  });
+
+  function setupFixture() {
+    const root = mkdtempSync(path.join(tmpdir(), "tfx-cleanup-"));
+    cleanupDirs.push(root);
+    const installedDir = path.join(root, "installed");
+    const pkgDir = path.join(root, "pkg");
+    mkdirSync(installedDir, { recursive: true });
+    mkdirSync(pkgDir, { recursive: true });
+    // pkg 에는 tfx-auto 만 있음 (나머지는 installed 에서 stale 로 감지)
+    mkdirSync(path.join(pkgDir, "tfx-auto"), { recursive: true });
+    return { installedDir, pkgDir };
+  }
+
+  it("nested directory 가 있는 stale 스킬도 전부 제거된다 (과거 회귀 bug)", () => {
+    const { installedDir, pkgDir } = setupFixture();
+    // stale 스킬: top-level 파일 + nested 디렉토리
+    const staleSkill = path.join(installedDir, "tfx-deep-review");
+    mkdirSync(staleSkill, { recursive: true });
+    writeFileSync(path.join(staleSkill, "SKILL.md"), "# deprecated");
+    const nested = path.join(staleSkill, "snapshot");
+    mkdirSync(nested, { recursive: true });
+    writeFileSync(path.join(nested, "data.json"), "{}");
+    mkdirSync(path.join(nested, "sub"), { recursive: true });
+    writeFileSync(path.join(nested, "sub", "more.txt"), "xxx");
+
+    // 유지해야 할 스킬 (pkg 에 있음)
+    mkdirSync(path.join(installedDir, "tfx-auto"), { recursive: true });
+    writeFileSync(path.join(installedDir, "tfx-auto", "SKILL.md"), "# ok");
+
+    const result = cleanupStaleSkills(installedDir, pkgDir);
+    assert.equal(result.count, 1);
+    assert.deepEqual(result.removed, ["tfx-deep-review"]);
+    assert.equal(existsSync(staleSkill), false, "nested dir 포함 전부 삭제");
+    assert.equal(
+      existsSync(path.join(installedDir, "tfx-auto")),
+      true,
+      "pkg 에 있는 스킬은 보존",
+    );
+  });
+
+  it("top-level 파일만 있는 stale 스킬도 제거된다 (legacy behavior 회귀 방지)", () => {
+    const { installedDir, pkgDir } = setupFixture();
+    const staleSkill = path.join(installedDir, "tfx-autoresearch");
+    mkdirSync(staleSkill, { recursive: true });
+    writeFileSync(path.join(staleSkill, "SKILL.md"), "# deprecated");
+    writeFileSync(path.join(staleSkill, "config.json"), "{}");
+
+    const result = cleanupStaleSkills(installedDir, pkgDir);
+    assert.equal(result.count, 1);
+    assert.equal(existsSync(staleSkill), false);
+  });
+
+  it("SKILL_ALIASES 에 있는 alias 는 유지된다", () => {
+    const { installedDir, pkgDir } = setupFixture();
+    // alias (tfx-autopilot) 는 SKILL_ALIASES 에 있으므로 pkgNames 에 자동 포함
+    mkdirSync(path.join(installedDir, "tfx-autopilot"), { recursive: true });
+    writeFileSync(
+      path.join(installedDir, "tfx-autopilot", "SKILL.md"),
+      "# alias",
+    );
+
+    const result = cleanupStaleSkills(installedDir, pkgDir);
+    assert.equal(result.count, 0);
+    assert.equal(existsSync(path.join(installedDir, "tfx-autopilot")), true);
+  });
+
+  it("tfx- 접두사 없는 디렉토리는 건드리지 않음", () => {
+    const { installedDir, pkgDir } = setupFixture();
+    mkdirSync(path.join(installedDir, "other-skill"), { recursive: true });
+    writeFileSync(
+      path.join(installedDir, "other-skill", "SKILL.md"),
+      "# other",
+    );
+
+    const result = cleanupStaleSkills(installedDir, pkgDir);
+    assert.equal(result.count, 0);
+    assert.equal(existsSync(path.join(installedDir, "other-skill")), true);
+  });
+});

package/scripts/setup.mjs

@@ -13,6 +13,7 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync,
+  rmSync,
   unlinkSync,
   writeFileSync,
 } from "fs";
@@ -430,17 +431,15 @@ function cleanupStaleSkills(installedDir, pkgDir) {
     if (pkgNames.has(name)) continue;
 
     const skillPath = join(installedDir, name);
+    // #144: 재귀 삭제 필요 — 과거 구현은 파일만 unlink 하여 nested 디렉토리가 있는 스킬을
+    // 온전히 제거하지 못했다. `tfx-deep-*`, `tfx-codex-swarm` 같은 과거 잔재 디렉토리는
+    // workspace/snapshot 같은 하위 폴더를 가지므로 rmSync recursive 가 필수.
     try {
-      const entries = readdirSync(skillPath);
-      for (const f of entries) unlinkSync(join(skillPath, f));
-      // rmdir only works on empty dirs; ignore errors for nested
-      try {
-        readdirSync(skillPath).length === 0 && unlinkSync(skillPath);
-      } catch {}
+      rmSync(skillPath, { recursive: true, force: true });
+      removed.push(name);
     } catch {
-      /* best effort */
+      /* best effort — next setup/update cycle 에서 재시도 */
     }
-    removed.push(name);
   }
   return { count: removed.length, removed };
 }

package/scripts/tfx-route-worker.mjs

@@ -143,7 +143,7 @@ function resolveDefaultMcpConfig(cwd) {
   const legacy = resolve(cwd, ".mcp.json");
   if (existsSync(legacy)) return [legacy];
   process.stderr.write(
-    "[tfx-route-worker] warning: no MCP config found, hub unavailable\n",
+    "[tfx-route-worker] warning: no project MCP config in cwd — hub status unaffected\n",
   );
   return [];
 }

package/scripts/tfx-route.sh

@@ -1348,6 +1348,32 @@ heartbeat_monitor() {
           echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B status=draining(${post_exit_checks}/${max_post_exit_checks})" >&2
         fi
       elif [[ "$stall_count" -ge "$stall_threshold" ]]; then
+        # STALL kill (#144/#66 regression guard): stall=threshold+grace 이상 지속 시 SIGTERM→SIGKILL.
+        # 기본 활성화. TFX_STALL_KILL=0 으로 opt-out. grace=30s (기본) 은 SSE/MCP 정상 handshake 여유.
+        local kill_on_stall="${TFX_STALL_KILL:-1}"
+        local kill_grace="${TFX_STALL_KILL_GRACE:-30}"
+        if [[ "$kill_on_stall" -eq 1 && "$stall_count" -ge $((stall_threshold + kill_grace)) ]]; then
+          echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B status=STALL_KILL stall=${stall_count}s — SIGTERM" >&2
+          kill -TERM "$pid" 2>/dev/null || true
+          local _grace_waited=0
+          while kill -0 "$pid" 2>/dev/null && [[ "$_grace_waited" -lt 5 ]]; do
+            sleep 1
+            _grace_waited=$((_grace_waited + 1))
+          done
+          if kill -0 "$pid" 2>/dev/null; then
+            # Windows/MSYS: POSIX SIGKILL 이 Win32 자식 트리까지 닿지 않는다.
+            # cleanup_workers 와 동일하게 taskkill /T /F 로 트리 종료.
+            case "$(uname -s)" in
+              MINGW*|MSYS*)
+                echo "[tfx-heartbeat] pid=$pid SIGTERM 무시 — taskkill /T /F" >&2
+                MSYS_NO_PATHCONV=1 cmd.exe //c "taskkill /T /F /PID $pid" 2>/dev/null || true ;;
+              *)
+                echo "[tfx-heartbeat] pid=$pid SIGTERM 무시 — SIGKILL 강제" >&2
+                kill -KILL "$pid" 2>/dev/null || true ;;
+            esac
+          fi
+          break
+        fi
         echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B status=STALL stall=${stall_count}s" >&2
       else
         echo "[tfx-heartbeat] pid=$pid elapsed=${elapsed}s output=${current_size}B status=quiet stall=${stall_count}s" >&2
@@ -1453,12 +1479,51 @@ _codex_config_swap() {
       return 0
     fi
 
-    # 백업 생성 (이미 있으면 다른 워커가 swap 중 — 건드리지 않음)
+    # 백업 생성 (이미 있으면 다른 워커가 swap 중 — 단, owner-dead + 백업 안전 복원 시 이어받기)
     if [[ -f "$backup" ]]; then
-      echo "[tfx-route] config.toml swap 스킵: 다른 워커가 사용 중 ($backup)" >&2
-      return 0
+      # Owner PID marker (P1 fix): mtime 만으로 stale 을 판정하면 장시간 정상 실행 워커도 오탐.
+      # $backup.owner 에 생성 워커 PID 기록 → kill -0 로 alive 확인. PID 파일 없거나 죽었으면 stale.
+      # mtime 은 신뢰성 낮아 soft 보조 지표로만 사용 (owner 파일 유실 대비 fallback).
+      local owner_file="${backup}.owner"
+      local owner_alive=false
+      local owner_pid=""
+      if [[ -f "$owner_file" ]]; then
+        owner_pid=$(cat "$owner_file" 2>/dev/null | tr -d '[:space:]')
+        if [[ -n "$owner_pid" ]] && kill -0 "$owner_pid" 2>/dev/null; then
+          owner_alive=true
+        fi
+      fi
+
+      if [[ "$owner_alive" == "true" ]]; then
+        echo "[tfx-route] config.toml swap 스킵: 소유 워커 살아있음 (pid=$owner_pid, $backup)" >&2
+        return 0
+      fi
+
+      # Owner dead or unknown — stale 후보. 다만 backup-loss 방지를 위해 원본 복원 먼저.
+      # P2 fix: `rm -f $backup` 후 현재 config 를 새 backup 으로 cp 하면, 이전 워커가 이미
+      # filter 한 상태에서 crash 했을 때 원본이 영구 소실. 여기서 먼저 restore 를 시도해
+      # backup 이 원본을 담고 있는 한 그것을 살린다.
+      local backup_restore_guard_size
+      backup_restore_guard_size=$(wc -c < "$backup" 2>/dev/null | tr -d ' ') || backup_restore_guard_size=0
+      if [[ "$backup_restore_guard_size" -lt 500 ]]; then
+        # 작은 backup 은 이미 손상된 state. 현재 config 도 필터된 상태일 수 있으므로
+        # 추가 swap 은 상황을 악화시킬 위험. 전체 스킵하고 수동 확인 유도.
+        echo "[tfx-route] stale backup 작음 (size=${backup_restore_guard_size}B, pid=${owner_pid:-?} dead) — swap 스킵, 수동 확인: $backup" >&2
+        return 0
+      fi
+      local stale_tmp="${config}.stale-restore.$$"
+      if cp "$backup" "$stale_tmp" && mv "$stale_tmp" "$config"; then
+        echo "[tfx-route] stale backup 감지 (pid=${owner_pid:-?} dead) — 원본 복원 후 swap 재진행" >&2
+      else
+        echo "[tfx-route] 경고: stale backup 복원 실패, swap 스킵 (수동 확인: $backup)" >&2
+        rm -f "$stale_tmp" 2>/dev/null
+        return 0
+      fi
+      rm -f "$backup" "$owner_file" 2>/dev/null || true
     fi
     cp "$config" "$backup"
+    # Owner marker: 이 워커가 backup 소유자임을 기록. 다음 워커의 stale detection 기준.
+    echo "$$" > "${backup}.owner" 2>/dev/null || true
 
     # awk로 필터링: 비허용 MCP 서버 섹션 제거, 나머지 그대로 유지.
     # keep="" 은 진입 가드에서 return 됐지만 defense-in-depth 유지.
@@ -1526,6 +1591,7 @@ _codex_config_swap() {
     if ! rm -f "$backup"; then
       echo "[tfx-route] 경고: backup 삭제 실패: $backup (수동 정리 필요)" >&2
     fi
+    rm -f "${backup}.owner" 2>/dev/null || true
     echo "[tfx-route] config.toml 복원 완료" >&2
   fi
 }