triflux 10.18.0 → 10.18.1

package/CLAUDE.md

@@ -157,6 +157,7 @@ background로 실행한 headless 결과는 **반드시 task-notification 완료
 | `.claude/rules/tfx-autoplan-principles.md` | gstack autoplan의 6 decision principles, phase 우선순위, 충돌 해소 규칙 추출본 |
 | `.claude/rules/tfx-update-logic.md` | triflux / OMC / gstack / Codex / Gemini 업데이트 로직 |
 | `.claude/rules/tfx-stack-coexistence.md` | gstack / superpowers / triflux 공존 원칙, 레이어 분리, 의존 방향, 충돌 해소 |
+| `.claude/rules/tfx-mirror-policy.md` | packages/ 3-layer mirror 정책 (core 단순 cp / remote import 변환 / triflux byte-identical), tests 제외 룰, drift 차단 |
 
 Claude Code는 `.claude/rules/*.md` 를 자동 로드한다. Codex CLI는 `@import` 미지원이므로 필요 시 `AGENTS.md` 를 독립 유지한다.
 

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 tellang
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 tellang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin/triflux.mjs

@@ -43,6 +43,12 @@ import {
   ensureTfxSection,
   getLatestRoutingTable,
 } from "../scripts/claudemd-sync.mjs";
+import {
+  applyPluginRootHookFallbacks,
+  commandExists,
+  findPluginRootHookIssues,
+  inspectMacTimeoutDependency,
+} from "../scripts/lib/doctor-env-checks.mjs";
 import { ensureGeminiProfiles } from "../scripts/lib/gemini-profiles.mjs";
 import { serializeHandoff } from "../scripts/lib/handoff.mjs";
 import {
@@ -2041,6 +2047,60 @@ async function cmdDoctor(options = {}) {
       for (const target of SYNC_MAP) {
         syncFile(target.src, target.dst, target.label);
       }
+      const macTimeoutForFix = inspectMacTimeoutDependency();
+      if (!macTimeoutForFix.ok) {
+        if (commandExists("brew")) {
+          if (process.stdin.isTTY && process.stdout.isTTY) {
+            info("macOS GNU timeout 부재: coreutils 설치 가능");
+            process.stdout.write(
+              "      brew install coreutils 실행할까요? [y/N] ",
+            );
+            let answer = "";
+            try {
+              const buf = Buffer.alloc(128);
+              const n = readSync(0, buf, 0, 128);
+              answer = buf.toString("utf8", 0, n).trim().toLowerCase();
+            } catch {
+              answer = "";
+            }
+            if (answer.startsWith("y")) {
+              try {
+                execFileSync("brew", ["install", "coreutils"], {
+                  stdio: "inherit",
+                  timeout: 600000,
+                  windowsHide: true,
+                });
+                report.actions.push({
+                  type: "install",
+                  name: "coreutils",
+                  status: "ok",
+                });
+                ok("coreutils 설치 완료");
+              } catch (error) {
+                report.actions.push({
+                  type: "install",
+                  name: "coreutils",
+                  status: "failed",
+                  message: error.message,
+                });
+                warn(
+                  `coreutils 설치 실패: ${renderErrorMessage(error.message)}`,
+                );
+              }
+            } else {
+              info("건너뜀: brew install coreutils");
+            }
+          } else {
+            warn(
+              "macOS GNU timeout 부재 — 비대화형 모드에서는 자동 설치하지 않습니다.",
+            );
+            info("수동 설치: brew install coreutils");
+          }
+        } else {
+          warn("macOS GNU timeout 부재 — Homebrew를 찾지 못했습니다.");
+          info("Homebrew 설치 후: brew install coreutils");
+        }
+      }
       {
         const claudeGuide = ensureGlobalClaudeRoutingSection(CLAUDE_DIR);
         if (
@@ -2197,6 +2257,34 @@ async function cmdDoctor(options = {}) {
       issues++;
     }
 
+    // macOS GNU timeout/coreutils
+    section("macOS timeout");
+    const macTimeout = inspectMacTimeoutDependency();
+    if (macTimeout.status === "skipped") {
+      addDoctorCheck(report, {
+        name: "macos-timeout",
+        status: "skipped",
+        platform: process.platform,
+      });
+      info("macOS 아님 — 건너뜀");
+    } else if (macTimeout.ok) {
+      addDoctorCheck(report, {
+        name: "macos-timeout",
+        status: "ok",
+        provider: macTimeout.provider,
+      });
+      ok(`timeout provider: ${macTimeout.provider}`);
+    } else {
+      addDoctorCheck(report, {
+        name: "macos-timeout",
+        status: "missing",
+        fix: macTimeout.fix,
+      });
+      warn("GNU timeout/gtimeout 미설치");
+      info("수정: brew install coreutils");
+      issues++;
+    }
+
     // 2. HUD
     section("HUD");
     const hud = join(CLAUDE_DIR, "hud", "hud-qos-status.mjs");
@@ -3813,6 +3901,55 @@ async function cmdDoctor(options = {}) {
         }
 
         if (settings) {
+          let pluginRootHookIssues = findPluginRootHookIssues(settings);
+          if (pluginRootHookIssues.length > 0 && fix) {
+            const fallbackResult = applyPluginRootHookFallbacks(settings, {
+              pluginRoot: PKG_ROOT,
+            });
+            if (fallbackResult.changed) {
+              writeFileSync(
+                settingsPath,
+                JSON.stringify(settings, null, 2) + "\n",
+                "utf8",
+              );
+              ok(
+                `PLUGIN_ROOT fallback ${fallbackResult.count}개 hook command에 적용됨`,
+              );
+              try {
+                settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+                pluginRootHookIssues = findPluginRootHookIssues(settings);
+              } catch (error) {
+                warn(`PLUGIN_ROOT fallback 재검증 실패: ${error.message}`);
+              }
+            }
+          }
+
+          addDoctorCheck(report, {
+            name: "hook-plugin-root",
+            status:
+              pluginRootHookIssues.length === 0 ? "ok" : "missing-fallback",
+            count: pluginRootHookIssues.length,
+            examples: pluginRootHookIssues.slice(0, 3).map((issue) => ({
+              event: issue.event,
+              reason: issue.reason,
+              command: issue.command,
+            })),
+            ...(pluginRootHookIssues.length > 0
+              ? { fix: "tfx doctor --fix 또는 tfx setup" }
+              : {}),
+          });
+          if (pluginRootHookIssues.length === 0) {
+            ok("PLUGIN_ROOT hook fallback 확인됨");
+          } else {
+            warn(
+              `PLUGIN_ROOT fallback 없는 hook ${pluginRootHookIssues.length}개 감지`,
+            );
+            info(
+              "영향: npm 단독 설치에서 /hooks/... 경로로 붕괴할 수 있습니다.",
+            );
+            issues += pluginRootHookIssues.length;
+          }
+
           let coverage = computeHookCoverage(settings, managedHooks);
 
           if (coverage.missing.length > 0 && fix) {

package/hub/codex-adapter.mjs

@@ -184,7 +184,10 @@ function buildLeaseSpawnEnv(lease) {
 
 function dirnameOf(filePath) {
   if (typeof filePath !== "string" || !filePath) return null;
-  const lastSep = Math.max(filePath.lastIndexOf("/"), filePath.lastIndexOf("\\"));
+  const lastSep = Math.max(
+    filePath.lastIndexOf("/"),
+    filePath.lastIndexOf("\\"),
+  );
   if (lastSep < 0) return null;
   return filePath.slice(0, lastSep);
 }

package/hud/providers/claude.mjs

@@ -2,7 +2,7 @@
 // Claude Usage API (api.anthropic.com/api/oauth/usage)
 // ============================================================================
 
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { existsSync, writeFileSync } from "node:fs";
 import https from "node:https";
 import {
@@ -31,6 +31,7 @@ import {
 
 export const CLAUDE_USAGE_POLL_BASE_MS = 5_000;
 export const CLAUDE_USAGE_POLL_JITTER_RATIO = 0.2;
+const CLAUDE_KEYCHAIN_SERVICE = "Claude Code-credentials";
 export const CLAUDE_USAGE_RATE_LIMIT_BACKOFF_MS = [
   CLAUDE_USAGE_POLL_BASE_MS,
   10_000,
@@ -98,8 +99,7 @@ function getSnapshotSchedule(cache) {
   };
 }
 
-export function readClaudeCredentials() {
-  const data = readJson(CLAUDE_CREDENTIALS_PATH, null);
+function normalizeClaudeCredentials(data, source, supportsUsageApi = true) {
   if (!data) return null;
   const creds = data.claudeAiOauth || data;
   if (!creds.accessToken) return null;
@@ -107,9 +107,51 @@ export function readClaudeCredentials() {
     accessToken: creds.accessToken,
     refreshToken: creds.refreshToken,
     expiresAt: creds.expiresAt,
+    source,
+    supportsUsageApi,
   };
 }
 
+function readClaudeKeychainCredentials(execFileSyncFn = execFileSync) {
+  try {
+    const raw = execFileSyncFn(
+      "security",
+      ["find-generic-password", "-s", CLAUDE_KEYCHAIN_SERVICE, "-w"],
+      { encoding: "utf8" },
+    );
+    return normalizeClaudeCredentials(JSON.parse(raw.trim()), "keychain");
+  } catch {
+    return null;
+  }
+}
+
+export function readClaudeCredentials({
+  readCredentialFile = () => readJson(CLAUDE_CREDENTIALS_PATH, null),
+  platform = process.platform,
+  execFileSyncFn = execFileSync,
+  env = process.env,
+} = {}) {
+  const fileCreds = normalizeClaudeCredentials(readCredentialFile(), "file");
+  if (fileCreds) return fileCreds;
+
+  if (platform === "darwin") {
+    const keychainCreds = readClaudeKeychainCredentials(execFileSyncFn);
+    if (keychainCreds) return keychainCreds;
+  }
+
+  if (env.ANTHROPIC_API_KEY) {
+    return {
+      accessToken: env.ANTHROPIC_API_KEY,
+      refreshToken: null,
+      expiresAt: null,
+      source: "env",
+      supportsUsageApi: false,
+    };
+  }
+
+  return null;
+}
+
 export function refreshClaudeAccessToken(refreshToken) {
   return new Promise((resolve) => {
     const clientId =
@@ -166,17 +208,67 @@ export function refreshClaudeAccessToken(refreshToken) {
   });
 }
 
-export function writeBackClaudeCredentials(creds) {
+function serializeClaudeCredentials(creds) {
+  const oauth = {
+    accessToken: creds.accessToken,
+  };
+  if (creds.expiresAt != null) oauth.expiresAt = creds.expiresAt;
+  if (creds.refreshToken) oauth.refreshToken = creds.refreshToken;
+  return { claudeAiOauth: oauth };
+}
+
+function writeClaudeKeychainCredentials(creds, execFileSyncFn = execFileSync) {
+  execFileSyncFn(
+    "security",
+    [
+      "add-generic-password",
+      "-s",
+      CLAUDE_KEYCHAIN_SERVICE,
+      "-w",
+      JSON.stringify(serializeClaudeCredentials(creds)),
+      "-U",
+    ],
+    { stdio: "ignore" },
+  );
+}
+
+export function writeBackClaudeCredentials(
+  creds,
+  {
+    readCredentialFile = () => readJson(CLAUDE_CREDENTIALS_PATH, null),
+    writeCredentialFile = (data) =>
+      writeFileSync(CLAUDE_CREDENTIALS_PATH, JSON.stringify(data, null, 2)),
+    platform = process.platform,
+    execFileSyncFn = execFileSync,
+  } = {},
+) {
+  if (creds?.source === "env") return;
+
+  let data = null;
   try {
-    const data = readJson(CLAUDE_CREDENTIALS_PATH, null);
-    if (!data) return;
+    data = readCredentialFile();
+  } catch {
+    data = null;
+  }
+
+  if (data) {
     const target = data.claudeAiOauth || data;
     target.accessToken = creds.accessToken;
     if (creds.expiresAt != null) target.expiresAt = creds.expiresAt;
     if (creds.refreshToken) target.refreshToken = creds.refreshToken;
-    writeFileSync(CLAUDE_CREDENTIALS_PATH, JSON.stringify(data, null, 2));
-  } catch {
-    /* 쓰기 실패 무시 */
+    try {
+      writeCredentialFile(data);
+    } catch {
+      /* 파일 쓰기 실패 무시 */
+    }
+  }
+
+  if (platform === "darwin") {
+    try {
+      writeClaudeKeychainCredentials(creds, execFileSyncFn);
+    } catch {
+      /* Keychain 쓰기 실패 무시 */
+    }
   }
 }
 
@@ -399,6 +491,10 @@ export async function fetchClaudeUsage(forceRefresh = false) {
     writeClaudeUsageCache(null, { type: "auth", status: 0 });
     return existingSnapshot.data || null;
   }
+  if (creds.supportsUsageApi === false) {
+    writeClaudeUsageCache(null, { type: "auth", status: 0 });
+    return existingSnapshot.data || null;
+  }
 
   // 토큰 만료 시 리프레시
   if (creds.expiresAt && creds.expiresAt <= Date.now() && creds.refreshToken) {

package/package.json

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

package/scripts/__tests__/release-governance.test.mjs

@@ -191,8 +191,13 @@ describe("release governance scripts", () => {
       });
       assert.equal(executed.skipTests, false);
 
+      // F3 (issue #192): test step 의 command 가 "npm test" 에서 직접 node
+      // test-lock.mjs 호출로 바뀜. legacy npm test 와 F3 후 node test-lock.mjs
+      // 둘 다 인식.
       const testCall = calls.find(
-        (call) => call.command === "npm" && call.args.join(" ") === "test",
+        (call) =>
+          (call.command === "npm" && call.args.join(" ") === "test") ||
+          call.args[0]?.endsWith("test-lock.mjs"),
       );
       assert.ok(testCall);
       assert.deepEqual(testCall.options.stdio, ["ignore", "pipe", "pipe"]);

package/scripts/completions/tfx.bash

@@ -1,47 +1,47 @@
-#!/usr/bin/env bash
-# Installation: source /path/to/tfx.bash 또는 ~/.bashrc에 추가
-
-_tfx_completion() {
-    local cur prev words cword
-    COMPREPLY=()
-    cur="${COMP_WORDS[COMP_CWORD]}"
-    prev="${COMP_WORDS[COMP_CWORD-1]}"
-    words=("${COMP_WORDS[@]}")
-    cword=$COMP_CWORD
-
-    local commands="setup doctor multi hub auto codex gemini"
-    local multi_cmds="status stop kill attach list"
-    local hub_cmds="start stop status restart"
-    local flags="--thorough --quick --tmux --psmux --agents --no-attach --timeout"
-
-    if [[ $cword -eq 1 ]]; then
-        COMPREPLY=( $(compgen -W "${commands}" -- "$cur") )
-        return 0
-    fi
-
-    local cmd="${words[1]}"
-    case "${cmd}" in
-        multi)
-            if [[ $cword -eq 2 && ! "$cur" == -* ]]; then
-                COMPREPLY=( $(compgen -W "${multi_cmds}" -- "$cur") )
-            else
-                COMPREPLY=( $(compgen -W "${flags}" -- "$cur") )
-            fi
-            ;;
-        hub)
-            if [[ $cword -eq 2 ]]; then
-                COMPREPLY=( $(compgen -W "${hub_cmds}" -- "$cur") )
-            fi
-            ;;
-        doctor)
-            COMPREPLY=( $(compgen -W "--fix --reset" -- "$cur") )
-            ;;
-        setup|auto|codex|gemini)
-            if [[ "$cur" == -* ]]; then
-                COMPREPLY=( $(compgen -W "${flags}" -- "$cur") )
-            fi
-            ;;
-    esac
-}
-
-complete -F _tfx_completion tfx
+#!/usr/bin/env bash
+# Installation: source /path/to/tfx.bash 또는 ~/.bashrc에 추가
+
+_tfx_completion() {
+    local cur prev words cword
+    COMPREPLY=()
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+    words=("${COMP_WORDS[@]}")
+    cword=$COMP_CWORD
+
+    local commands="setup doctor multi hub auto codex gemini"
+    local multi_cmds="status stop kill attach list"
+    local hub_cmds="start stop status restart"
+    local flags="--thorough --quick --tmux --psmux --agents --no-attach --timeout"
+
+    if [[ $cword -eq 1 ]]; then
+        COMPREPLY=( $(compgen -W "${commands}" -- "$cur") )
+        return 0
+    fi
+
+    local cmd="${words[1]}"
+    case "${cmd}" in
+        multi)
+            if [[ $cword -eq 2 && ! "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "${multi_cmds}" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -W "${flags}" -- "$cur") )
+            fi
+            ;;
+        hub)
+            if [[ $cword -eq 2 ]]; then
+                COMPREPLY=( $(compgen -W "${hub_cmds}" -- "$cur") )
+            fi
+            ;;
+        doctor)
+            COMPREPLY=( $(compgen -W "--fix --reset" -- "$cur") )
+            ;;
+        setup|auto|codex|gemini)
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "${flags}" -- "$cur") )
+            fi
+            ;;
+    esac
+}
+
+complete -F _tfx_completion tfx

package/scripts/completions/tfx.fish

@@ -1,44 +1,44 @@
-# Installation: ~/.config/fish/completions/에 복사
-# e.g., cp /path/to/tfx.fish ~/.config/fish/completions/tfx.fish
-
-set -l commands setup doctor multi hub auto codex gemini
-set -l multi_cmds status stop kill attach list
-set -l hub_cmds start stop status restart
-
-complete -c tfx -f
-
-# Subcommands
-complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "setup" -d "Setup and sync files"
-complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "doctor" -d "Diagnose CLI and issues"
-complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "multi" -d "Multi-CLI team mode"
-complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "hub" -d "MCP message bus management"
-complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "auto" -d "Auto mode"
-complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "codex" -d "Codex mode"
-complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "gemini" -d "Gemini mode"
-
-# Doctor flags
-complete -c tfx -n "__fish_seen_subcommand_from doctor" -l fix -d "Auto fix issues"
-complete -c tfx -n "__fish_seen_subcommand_from doctor" -l reset -d "Reset all caches"
-
-# Multi subcommands
-complete -c tfx -n "__fish_seen_subcommand_from multi; and not __fish_seen_subcommand_from $multi_cmds" -a "status"
-complete -c tfx -n "__fish_seen_subcommand_from multi; and not __fish_seen_subcommand_from $multi_cmds" -a "stop"
-complete -c tfx -n "__fish_seen_subcommand_from multi; and not __fish_seen_subcommand_from $multi_cmds" -a "kill"
-complete -c tfx -n "__fish_seen_subcommand_from multi; and not __fish_seen_subcommand_from $multi_cmds" -a "attach"
-complete -c tfx -n "__fish_seen_subcommand_from multi; and not __fish_seen_subcommand_from $multi_cmds" -a "list"
-
-# Hub subcommands
-complete -c tfx -n "__fish_seen_subcommand_from hub; and not __fish_seen_subcommand_from $hub_cmds" -a "start"
-complete -c tfx -n "__fish_seen_subcommand_from hub; and not __fish_seen_subcommand_from $hub_cmds" -a "stop"
-complete -c tfx -n "__fish_seen_subcommand_from hub; and not __fish_seen_subcommand_from $hub_cmds" -a "status"
-complete -c tfx -n "__fish_seen_subcommand_from hub; and not __fish_seen_subcommand_from $hub_cmds" -a "restart"
-
-# Global or multi flags
-set -l flags_cond "__fish_seen_subcommand_from setup multi auto codex gemini"
-complete -c tfx -n "$flags_cond" -l thorough -d "Thorough execution"
-complete -c tfx -n "$flags_cond" -l quick -d "Quick execution"
-complete -c tfx -n "$flags_cond" -l tmux -d "Use tmux"
-complete -c tfx -n "$flags_cond" -l psmux -d "Use psmux"
-complete -c tfx -n "$flags_cond" -l agents -d "Specify agents"
-complete -c tfx -n "$flags_cond" -l no-attach -d "Do not attach"
-complete -c tfx -n "$flags_cond" -l timeout -d "Set timeout"
+# Installation: ~/.config/fish/completions/에 복사
+# e.g., cp /path/to/tfx.fish ~/.config/fish/completions/tfx.fish
+
+set -l commands setup doctor multi hub auto codex gemini
+set -l multi_cmds status stop kill attach list
+set -l hub_cmds start stop status restart
+
+complete -c tfx -f
+
+# Subcommands
+complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "setup" -d "Setup and sync files"
+complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "doctor" -d "Diagnose CLI and issues"
+complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "multi" -d "Multi-CLI team mode"
+complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "hub" -d "MCP message bus management"
+complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "auto" -d "Auto mode"
+complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "codex" -d "Codex mode"
+complete -c tfx -n "not __fish_seen_subcommand_from $commands" -a "gemini" -d "Gemini mode"
+
+# Doctor flags
+complete -c tfx -n "__fish_seen_subcommand_from doctor" -l fix -d "Auto fix issues"
+complete -c tfx -n "__fish_seen_subcommand_from doctor" -l reset -d "Reset all caches"
+
+# Multi subcommands
+complete -c tfx -n "__fish_seen_subcommand_from multi; and not __fish_seen_subcommand_from $multi_cmds" -a "status"
+complete -c tfx -n "__fish_seen_subcommand_from multi; and not __fish_seen_subcommand_from $multi_cmds" -a "stop"
+complete -c tfx -n "__fish_seen_subcommand_from multi; and not __fish_seen_subcommand_from $multi_cmds" -a "kill"
+complete -c tfx -n "__fish_seen_subcommand_from multi; and not __fish_seen_subcommand_from $multi_cmds" -a "attach"
+complete -c tfx -n "__fish_seen_subcommand_from multi; and not __fish_seen_subcommand_from $multi_cmds" -a "list"
+
+# Hub subcommands
+complete -c tfx -n "__fish_seen_subcommand_from hub; and not __fish_seen_subcommand_from $hub_cmds" -a "start"
+complete -c tfx -n "__fish_seen_subcommand_from hub; and not __fish_seen_subcommand_from $hub_cmds" -a "stop"
+complete -c tfx -n "__fish_seen_subcommand_from hub; and not __fish_seen_subcommand_from $hub_cmds" -a "status"
+complete -c tfx -n "__fish_seen_subcommand_from hub; and not __fish_seen_subcommand_from $hub_cmds" -a "restart"
+
+# Global or multi flags
+set -l flags_cond "__fish_seen_subcommand_from setup multi auto codex gemini"
+complete -c tfx -n "$flags_cond" -l thorough -d "Thorough execution"
+complete -c tfx -n "$flags_cond" -l quick -d "Quick execution"
+complete -c tfx -n "$flags_cond" -l tmux -d "Use tmux"
+complete -c tfx -n "$flags_cond" -l psmux -d "Use psmux"
+complete -c tfx -n "$flags_cond" -l agents -d "Specify agents"
+complete -c tfx -n "$flags_cond" -l no-attach -d "Do not attach"
+complete -c tfx -n "$flags_cond" -l timeout -d "Set timeout"

package/scripts/completions/tfx.zsh

@@ -1,83 +1,83 @@
-#compdef tfx
-# Installation: fpath에 추가 후 compinit
-# e.g., fpath=(/path/to/dir $fpath) && compinit
-
-_tfx() {
-    local line state
-    local -a commands multi_cmds hub_cmds flags
-
-    commands=(
-        'setup:Setup and sync files'
-        'doctor:Diagnose CLI and issues'
-        'multi:Multi-CLI team mode'
-        'hub:MCP message bus management'
-        'auto:Auto mode'
-        'codex:Codex mode'
-        'gemini:Gemini mode'
-    )
-
-    multi_cmds=(
-        'status:Show status'
-        'stop:Stop multi'
-        'kill:Kill multi'
-        'attach:Attach to multi'
-        'list:List multi sessions'
-    )
-
-    hub_cmds=(
-        'start:Start hub'
-        'stop:Stop hub'
-        'status:Show hub status'
-        'restart:Restart hub'
-    )
-
-    _arguments -C \
-        '1: :->cmds' \
-        '*: :->args'
-
-    case $state in
-        cmds)
-            _describe -t commands 'tfx commands' commands
-            ;;
-        args)
-            case $words[2] in
-                multi)
-                    if (( CURRENT == 3 )) && [[ $words[CURRENT] != -* ]]; then
-                        _describe -t multi_cmds 'multi commands' multi_cmds
-                    else
-                        _arguments \
-                            '--thorough[Thorough execution]' \
-                            '--quick[Quick execution]' \
-                            '--tmux[Use tmux]' \
-                            '--psmux[Use psmux]' \
-                            '--agents[Specify agents]' \
-                            '--no-attach[Do not attach]' \
-                            '--timeout[Set timeout]'
-                    fi
-                    ;;
-                hub)
-                    if (( CURRENT == 3 )); then
-                        _describe -t hub_cmds 'hub commands' hub_cmds
-                    fi
-                    ;;
-                doctor)
-                    _arguments \
-                        '--fix[Auto fix issues]' \
-                        '--reset[Reset all caches]'
-                    ;;
-                *)
-                    _arguments \
-                        '--thorough[Thorough execution]' \
-                        '--quick[Quick execution]' \
-                        '--tmux[Use tmux]' \
-                        '--psmux[Use psmux]' \
-                        '--agents[Specify agents]' \
-                        '--no-attach[Do not attach]' \
-                        '--timeout[Set timeout]'
-                    ;;
-            esac
-            ;;
-    esac
-}
-
-_tfx "$@"
+#compdef tfx
+# Installation: fpath에 추가 후 compinit
+# e.g., fpath=(/path/to/dir $fpath) && compinit
+
+_tfx() {
+    local line state
+    local -a commands multi_cmds hub_cmds flags
+
+    commands=(
+        'setup:Setup and sync files'
+        'doctor:Diagnose CLI and issues'
+        'multi:Multi-CLI team mode'
+        'hub:MCP message bus management'
+        'auto:Auto mode'
+        'codex:Codex mode'
+        'gemini:Gemini mode'
+    )
+
+    multi_cmds=(
+        'status:Show status'
+        'stop:Stop multi'
+        'kill:Kill multi'
+        'attach:Attach to multi'
+        'list:List multi sessions'
+    )
+
+    hub_cmds=(
+        'start:Start hub'
+        'stop:Stop hub'
+        'status:Show hub status'
+        'restart:Restart hub'
+    )
+
+    _arguments -C \
+        '1: :->cmds' \
+        '*: :->args'
+
+    case $state in
+        cmds)
+            _describe -t commands 'tfx commands' commands
+            ;;
+        args)
+            case $words[2] in
+                multi)
+                    if (( CURRENT == 3 )) && [[ $words[CURRENT] != -* ]]; then
+                        _describe -t multi_cmds 'multi commands' multi_cmds
+                    else
+                        _arguments \
+                            '--thorough[Thorough execution]' \
+                            '--quick[Quick execution]' \
+                            '--tmux[Use tmux]' \
+                            '--psmux[Use psmux]' \
+                            '--agents[Specify agents]' \
+                            '--no-attach[Do not attach]' \
+                            '--timeout[Set timeout]'
+                    fi
+                    ;;
+                hub)
+                    if (( CURRENT == 3 )); then
+                        _describe -t hub_cmds 'hub commands' hub_cmds
+                    fi
+                    ;;
+                doctor)
+                    _arguments \
+                        '--fix[Auto fix issues]' \
+                        '--reset[Reset all caches]'
+                    ;;
+                *)
+                    _arguments \
+                        '--thorough[Thorough execution]' \
+                        '--quick[Quick execution]' \
+                        '--tmux[Use tmux]' \
+                        '--psmux[Use psmux]' \
+                        '--agents[Specify agents]' \
+                        '--no-attach[Do not attach]' \
+                        '--timeout[Set timeout]'
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+_tfx "$@"

package/scripts/lib/doctor-env-checks.mjs

@@ -0,0 +1,121 @@
+import { execFileSync } from "node:child_process";
+
+export function commandExists(name) {
+  try {
+    execFileSync("sh", ["-c", 'command -v "$1" >/dev/null 2>&1', "sh", name], {
+      stdio: "ignore",
+      timeout: 2000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function inspectMacTimeoutDependency({
+  platform = process.platform,
+  commandExists: exists = commandExists,
+} = {}) {
+  if (platform !== "darwin") {
+    return { ok: true, status: "skipped", platform };
+  }
+
+  if (exists("gtimeout")) {
+    return { ok: true, status: "ok", platform, provider: "gtimeout" };
+  }
+  if (exists("timeout")) {
+    return { ok: true, status: "ok", platform, provider: "timeout" };
+  }
+
+  return {
+    ok: false,
+    status: "missing",
+    platform,
+    fix: "brew install coreutils",
+  };
+}
+
+export function addPluginRootFallbackToCommand(command, pluginRoot) {
+  if (typeof command !== "string") return command;
+  const fallbackRoot = String(pluginRoot || "").replace(/\\/g, "/");
+  if (!fallbackRoot) return command;
+  return command
+    .replaceAll("${PLUGIN_ROOT}", `\${PLUGIN_ROOT:-${fallbackRoot}}`)
+    .replaceAll(
+      "${CLAUDE_PLUGIN_ROOT}",
+      `\${CLAUDE_PLUGIN_ROOT:-${fallbackRoot}}`,
+    )
+    .replace(
+      /(^|[\s"'])\/(hooks|scripts)\//g,
+      `$1\${PLUGIN_ROOT:-${fallbackRoot}}/$2/`,
+    );
+}
+
+function hasBarePluginRootReference(command) {
+  if (typeof command !== "string") return false;
+  return (
+    command.includes("${PLUGIN_ROOT}/") ||
+    command.includes("${CLAUDE_PLUGIN_ROOT}/")
+  );
+}
+
+function hasCollapsedRootHookPath(command) {
+  if (typeof command !== "string") return false;
+  return /(^|[\s"'])\/(?:hooks|scripts)\//.test(command);
+}
+
+export function findPluginRootHookIssues(settings) {
+  const hooksByEvent =
+    settings?.hooks && typeof settings.hooks === "object" ? settings.hooks : {};
+  const issues = [];
+
+  for (const [event, entries] of Object.entries(hooksByEvent)) {
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      const hooks = Array.isArray(entry?.hooks) ? entry.hooks : [];
+      for (const hook of hooks) {
+        const command = hook?.command;
+        if (
+          !hasBarePluginRootReference(command) &&
+          !hasCollapsedRootHookPath(command)
+        ) {
+          continue;
+        }
+        issues.push({
+          event,
+          matcher: entry?.matcher || "*",
+          command,
+          reason: hasCollapsedRootHookPath(command)
+            ? "collapsed-root-path"
+            : "missing-plugin-root-fallback",
+        });
+      }
+    }
+  }
+
+  return issues;
+}
+
+export function applyPluginRootHookFallbacks(settings, { pluginRoot } = {}) {
+  if (!settings?.hooks || typeof settings.hooks !== "object") {
+    return { changed: false, count: 0, settings };
+  }
+
+  let count = 0;
+  for (const entries of Object.values(settings.hooks)) {
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      const hooks = Array.isArray(entry?.hooks) ? entry.hooks : [];
+      for (const hook of hooks) {
+        if (typeof hook?.command !== "string") continue;
+        const next = addPluginRootFallbackToCommand(hook.command, pluginRoot);
+        if (next !== hook.command) {
+          hook.command = next;
+          count++;
+        }
+      }
+    }
+  }
+
+  return { changed: count > 0, count, settings };
+}

package/scripts/release/prepare.mjs

@@ -64,23 +64,32 @@ export async function prepareRelease({
   const steps = [
     {
       name: "npm-test",
-      command: "npm",
-      args: ["test"],
+      // F3 fix (issue #192 — silent EXIT 0 회귀 우회):
+      // npm wrapper 경유 시 prepare.mjs process 가 native level 에서 hard kill
+      // 됨 (process.on("exit") 핸들러 호출 안 됨, EXIT 0 silent, 후속 lint/pack
+      // step 누락). 2026-04-30 진단 세션에서 5 시나리오 reproduce 결과:
+      //   - npm wrapper 경유 + npm test 실행: silent EXIT 0 재현 (12-24s 비결정)
+      //   - 직접 node 실행 또는 npm test 단독: 정상 진행
+      //   - --skip-tests 우회: 정상 unhandled rejection (lint fail visible)
+      // 따라서 npm wrapper 한 단계 줄여 trigger 약화 (cmd.exe shim → npm-cli.js
+      // → spawn 3 layers 제거). package.json `scripts.test` 와 sync 유지 필수.
+      command: process.execPath,
+      args: [
+        "scripts/test-lock.mjs",
+        "--test",
+        "--test-force-exit",
+        "--test-concurrency=8",
+        "tests/**/*.test.mjs",
+        "scripts/__tests__/**/*.test.mjs",
+      ],
       skip: skipTests,
-      // Windows background execution can stall when `npm test` inherits the
-      // parent's console handles through nested shell/spawn layers. Run the
-      // heavy test step non-interactively and fail fast if it never returns.
-      // maxBuffer raised explicitly: 1 MiB default is too small for piped
-      // npm test --test-concurrency=8 verbose output. This is generic
-      // robustness, NOT a fix for the prepare-only EXIT=1 mismatch — that
-      // root cause is the test-lock.mjs spawn `stdio: "inherit"` cascading
-      // the parent's ignore/pipe/pipe down to grand-child `node --test`,
-      // breaking ConPTY assumptions on Windows. See issue #192 for the
-      // diagnosis and fix candidates (F1 = test-lock stdio split).
+      // maxBuffer: 1 MiB default is too small for piped node --test verbose
+      // output. 128 MiB matches the prior npm-test ceiling.
       options: {
         stdio: ["ignore", "pipe", "pipe"],
         timeoutMs: TEST_TIMEOUT_MS,
         maxBuffer: 128 * 1024 * 1024,
+        shell: false,
       },
     },
     {

package/scripts/setup.mjs

@@ -25,6 +25,7 @@ import {
   ensureTfxSection,
   getLatestRoutingTable,
 } from "./claudemd-sync.mjs";
+import { addPluginRootFallbackToCommand } from "./lib/doctor-env-checks.mjs";
 import { cleanupTmpFiles } from "./tmp-cleanup.mjs";
 
 const PLUGIN_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -141,7 +142,7 @@ function isSetupUserStateFile(fileName) {
 }
 
 /**
- * scripts/lib/*.mjs 자동 스캔.
+ * scripts/lib/*.mjs 및 *.sh 자동 스캔.
  * 수동 리스트 대신 glob으로 탐색하여 lib 파일 추가 시 sync 누락 방지.
  */
 function scanLibFiles(pluginRoot, claudeDir) {
@@ -149,7 +150,7 @@ function scanLibFiles(pluginRoot, claudeDir) {
   if (!existsSync(libDir)) return [];
   return readdirSync(libDir)
     .sort()
-    .filter((f) => f.endsWith(".mjs"))
+    .filter((f) => f.endsWith(".mjs") || f.endsWith(".sh"))
     .map((f) => ({
       src: join(libDir, f),
       dst: join(claudeDir, "scripts", "lib", f),
@@ -563,7 +564,13 @@ function ensureHooksInSettings({ settingsPath, registryPath }) {
 
       entries.push({
         matcher: spec.matcher,
-        hooks: [{ type: "command", command: spec.command, timeout: 5 }],
+        hooks: [
+          {
+            type: "command",
+            command: addPluginRootFallbackToCommand(spec.command, PLUGIN_ROOT),
+            timeout: 5,
+          },
+        ],
       });
       added.push(spec.id || spec.fileName);
     }

package/scripts/tfx-route.sh

@@ -1956,8 +1956,12 @@ _codex_config_swap() {
 
 # codex-recovery.sh 의 recover_codex_stdout 헬퍼 사용. STDOUT_LOG/STDERR_LOG env.
 _TFX_ROUTE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=lib/codex-recovery.sh
-source "$_TFX_ROUTE_DIR/lib/codex-recovery.sh"
+if [[ -f "$_TFX_ROUTE_DIR/lib/codex-recovery.sh" ]]; then
+  # shellcheck source=lib/codex-recovery.sh
+  source "$_TFX_ROUTE_DIR/lib/codex-recovery.sh"
+else
+  echo "[tfx-route] WARNING: optional helper missing: $_TFX_ROUTE_DIR/lib/codex-recovery.sh (run: tfx doctor --fix)" >&2
+fi
 
 run_codex_exec() {
   local prompt="$1"

package/scripts/token-snapshot.mjs

@@ -30,7 +30,7 @@ const REPORTS_DIR = join(STATE_DIR, "reports");
 // ── 가격 모델 ($/MTok, 비캐시 기준, 보수적 추정) ──
 const PRICING = {
   claude_sonnet: { input: 3, output: 15 },
-  claude_opus: { input: 15, output: 75 },
+  claude_opus: { input: 5, output: 25 },
   codex: { input: 0, output: 0 },
   gemini_flash: { input: 0.1, output: 0.4 },
 };
@@ -38,7 +38,7 @@ const PRICING = {
 // Claude 캐시 가격 ($/MTok) — 오케스트레이션 비용 정밀 계산용
 const CLAUDE_CACHE_PRICING = {
   claude_sonnet: { cache_write: 3.75, cache_read: 0.3 },
-  claude_opus: { cache_write: 18.75, cache_read: 1.5 },
+  claude_opus: { cache_write: 6.25, cache_read: 0.5 },
 };
 
 // 에이전트 → Claude 대체 모델
@@ -628,11 +628,13 @@ function generateReport(sessionId) {
 
 // ── Named exports (파이프라인 벤치마크 훅용) ──
 export {
+  CLAUDE_CACHE_PRICING,
   computeDiff,
   DIFFS_DIR,
   estimateSavings,
   formatCost,
   formatTokenCount,
+  PRICING,
   STATE_DIR,
   takeSnapshot,
 };

package/references/hosts.json

@@ -1,46 +0,0 @@
-{
-  "hosts": {
-    "ultra4": {
-      "description": "Windows 데스크탑 (22코어/64GB RAM)",
-      "aliases": ["울트라", "울트라4", "데스크탑"],
-      "default_dir": "~/Desktop/Projects/cli/triflux",
-      "tailscale": {
-        "ip": "100.110.136.64",
-        "dns": "ultra-book-4-1",
-        "ssh_mode": "ssh-over-vpn"
-      },
-      "ssh_user": "SSAFY",
-      "os": "windows",
-      "specs": {
-        "cores": 22,
-        "ram_gb": 64,
-        "codex": "0.118.0",
-        "node": "24.14.0"
-      },
-      "capabilities": ["codex", "claude", "high-memory"]
-    },
-    "m2": {
-      "description": "MacBook Air M2 (8코어/16GB RAM)",
-      "aliases": ["맥", "맥북", "m2"],
-      "default_dir": "~/Desktop/Projects/triflux",
-      "tailscale": {
-        "ip": "100.104.61.126",
-        "dns": "tellang의-macbook-air",
-        "ssh_mode": "ssh-over-vpn"
-      },
-      "ssh_user": "tellang",
-      "os": "darwin",
-      "specs": {
-        "cores": 8,
-        "ram_gb": 16,
-        "claude": "2.1.89",
-        "codex": "0.114.0",
-        "gemini": "0.33.1",
-        "node": "25.9.0"
-      },
-      "capabilities": ["codex", "claude", "gemini"]
-    }
-  },
-  "default_host": "m2",
-  "triggers": ["원격에서", "다른 머신에서", "다른 컴퓨터에서"]
-}

package/skills/.omc/state/agent-replay-8f0e10a9-9693-4410-96f5-a6b07e8ed995.jsonl

@@ -1 +0,0 @@
-{"t":0,"agent":"adb34b0","agent_type":"general-purpose","event":"agent_stop","success":true}

package/skills/.omc/state/idle-notif-cooldown.json

@@ -1,3 +0,0 @@
-{
-  "lastSentAt": "2026-03-29T03:41:07.256Z"
-}

package/skills/.omc/state/last-tool-error.json

@@ -1,7 +0,0 @@
-{
-  "tool_name": "Bash",
-  "tool_input_preview": "{\"command\":\"ls -la \\\"C:/Users/tellang/Desktop/Projects/triflux/skills/tfx-deslop/\\\" 2>/dev/null; echo \\\"===\\\"; ls -la \\\"C:/Users/tellang/Desktop/Projects/triflux/skills/tfx-codebase-search/\\\" 2>/dev/n...",
-  "error": "Exit code 2\n===",
-  "timestamp": "2026-03-29T03:40:35.913Z",
-  "retry_count": 1
-}

package/skills/.omc/state/subagent-tracking.json

@@ -1,7 +0,0 @@
-{
-  "agents": [],
-  "total_spawned": 0,
-  "total_completed": 0,
-  "total_failed": 0,
-  "last_updated": "2026-03-29T03:41:34.338Z"
-}

package/skills/tfx-remote-spawn/references/hosts.json

@@ -1,41 +0,0 @@
-{
-  "hosts": {
-    "m2": {
-      "description": "MacBook Air (tellang M2)",
-      "aliases": ["맥북", "맥"],
-      "default_dir": "~/projects",
-      "os": "darwin",
-      "ssh_user": "tellang",
-      "tailscale": {
-        "ip": "100.104.61.126",
-        "dns": "m2.sole-hexatonic.ts.net",
-        "ssh_mode": "ssh-over-vpn"
-      },
-      "capabilities": {
-        "ssh_active": true,
-        "claude": true,
-        "node": "v25.9.0"
-      },
-      "last_probe": "2026-04-24T19:04:48Z"
-    },
-    "fold7": {
-      "description": "Samsung Z Fold 7 (Termux)",
-      "aliases": ["폴드", "폰", "fold"],
-      "default_dir": "~",
-      "os": "android",
-      "ssh_user": "",
-      "tailscale": {
-        "ip": "100.107.139.115",
-        "dns": "fold7.sole-hexatonic.ts.net",
-        "ssh_mode": "ssh-over-vpn"
-      },
-      "capabilities": {
-        "ssh_active": false,
-        "note": "Termux sshd 미실행 — Fold7에서 'pkg install openssh && sshd -p 8022' 후 probe 재실행"
-      },
-      "last_probe": "2026-04-24T19:04:48Z"
-    }
-  },
-  "default_host": "m2",
-  "triggers": ["원격에서", "다른 머신에서", "다른 컴퓨터에서"]
-}

package/skills/tfx-remote-spawn/references/hosts.json.bak.20260425_040814

@@ -1,16 +0,0 @@
-{
-  "hosts": {
-    "ultra4": {
-      "description": "Windows 데스크탑 (SSAFY)",
-      "aliases": ["울트라", "데스크탑"],
-      "default_dir": "~/Desktop/Projects"
-    },
-    "m2": {
-      "description": "MacBook Pro",
-      "aliases": ["맥북", "맥"],
-      "default_dir": "~/projects"
-    }
-  },
-  "default_host": "ultra4",
-  "triggers": ["원격에서", "다른 머신에서", "다른 컴퓨터에서"]
-}