triflux 3.2.0-dev.1 → 3.2.0-dev.11

package/scripts/psmux-steering-prototype.sh

@@ -0,0 +1,368 @@
+#!/usr/bin/env bash
+# psmux-steering-prototype.sh
+# Windows psmux 환경에서 lead/codex-worker/gemini-worker pane을 만들고
+# send-keys + pipe-pane 기반으로 실시간 CLI 스티어링을 실험하는 프로토타입.
+
+set -euo pipefail
+
+PSMUX_BIN="${PSMUX_BIN:-psmux}"
+SESSION_NAME="${PSMUX_SESSION_NAME:-triflux-steering}"
+WINDOW_NAME="${PSMUX_WINDOW_NAME:-control}"
+PANE_LEAD="lead"
+PANE_CODEX="codex-worker"
+PANE_GEMINI="gemini-worker"
+SHELL_COMMAND="${PSMUX_SHELL_COMMAND:-powershell.exe -NoLogo}"
+CAPTURE_ROOT="${PSMUX_CAPTURE_ROOT:-${TMPDIR:-/tmp}/psmux-steering}"
+CAPTURE_DIR="${CAPTURE_ROOT}/${SESSION_NAME}"
+CAPTURE_HELPER_PATH="${CAPTURE_ROOT}/pipe-pane-capture.ps1"
+COMPLETION_PREFIX="__TRIFLUX_DONE__:"
+POLL_INTERVAL_SEC="${PSMUX_POLL_INTERVAL_SEC:-1}"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  scripts/psmux-steering-prototype.sh start
+  scripts/psmux-steering-prototype.sh demo
+  scripts/psmux-steering-prototype.sh attach
+  scripts/psmux-steering-prototype.sh send <pane-name> <command text>
+  scripts/psmux-steering-prototype.sh send-no-enter <pane-name> <text>
+  scripts/psmux-steering-prototype.sh steer-ps <pane-name> <powershell command>
+  scripts/psmux-steering-prototype.sh wait <pane-name> <regex> [timeout-sec]
+  scripts/psmux-steering-prototype.sh logs
+  scripts/psmux-steering-prototype.sh cleanup
+
+Pane names:
+  lead | codex-worker | gemini-worker
+
+Environment overrides:
+  PSMUX_BIN
+  PSMUX_SESSION_NAME
+  PSMUX_WINDOW_NAME
+  PSMUX_SHELL_COMMAND
+  PSMUX_CAPTURE_ROOT
+  PSMUX_POLL_INTERVAL_SEC
+EOF
+}
+
+log() {
+  printf '[psmux-steering] %s\n' "$*"
+}
+
+die() {
+  printf '[psmux-steering] ERROR: %s\n' "$*" >&2
+  exit 1
+}
+
+require_psmux() {
+  command -v "$PSMUX_BIN" >/dev/null 2>&1 || die "Cannot find '$PSMUX_BIN' in PATH."
+}
+
+session_target() {
+  printf '%s:%s' "$SESSION_NAME" "$WINDOW_NAME"
+}
+
+pane_target_from_index() {
+  local pane_index="$1"
+  printf '%s.%s' "$(session_target)" "$pane_index"
+}
+
+log_file_for() {
+  local pane_name="$1"
+  printf '%s/%s.log' "$CAPTURE_DIR" "$pane_name"
+}
+
+to_windows_path() {
+  local path_value="$1"
+
+  if command -v cygpath >/dev/null 2>&1; then
+    cygpath -aw "$path_value"
+    return 0
+  fi
+
+  printf '%s\n' "$path_value"
+}
+
+ensure_capture_helper() {
+  mkdir -p "$CAPTURE_ROOT"
+
+  cat >"$CAPTURE_HELPER_PATH" <<'EOF'
+param(
+  [Parameter(Mandatory = $true)][string]$Path
+)
+
+$parent = Split-Path -Parent $Path
+if ($parent) {
+  New-Item -ItemType Directory -Force -Path $parent | Out-Null
+}
+
+$reader = [Console]::In
+while (($line = $reader.ReadLine()) -ne $null) {
+  Add-Content -LiteralPath $Path -Value $line -Encoding utf8
+}
+EOF
+}
+
+session_exists() {
+  "$PSMUX_BIN" has-session -t "$SESSION_NAME" >/dev/null 2>&1
+}
+
+resolve_pane_target() {
+  local pane_name="$1"
+  local pane_index
+
+  pane_index="$("$PSMUX_BIN" list-panes -t "$(session_target)" -F '#{pane_index} #{pane_title}' \
+    | awk -v wanted="$pane_name" '$2 == wanted { print $1; exit }')"
+
+  [[ -n "$pane_index" ]] || return 1
+  pane_target_from_index "$pane_index"
+}
+
+require_pane_target() {
+  local pane_name="$1"
+  local pane_target
+
+  pane_target="$(resolve_pane_target "$pane_name")"
+  [[ -n "$pane_target" ]] || die "Pane '$pane_name' not found in session '$SESSION_NAME'."
+  printf '%s\n' "$pane_target"
+}
+
+set_pane_title() {
+  local pane_target="$1"
+  local pane_name="$2"
+
+  "$PSMUX_BIN" select-pane -t "$pane_target" -T "$pane_name" >/dev/null
+}
+
+start_capture_for_pane() {
+  local pane_name="$1"
+  local pane_target log_file helper_windows_path log_windows_path
+
+  pane_target="$(require_pane_target "$pane_name")"
+  log_file="$(log_file_for "$pane_name")"
+  ensure_capture_helper
+  helper_windows_path="$(to_windows_path "$CAPTURE_HELPER_PATH")"
+  log_windows_path="$(to_windows_path "$log_file")"
+
+  mkdir -p "$CAPTURE_DIR"
+  : >"$log_file"
+
+  "$PSMUX_BIN" pipe-pane -t "$pane_target" >/dev/null 2>&1 || true
+  "$PSMUX_BIN" pipe-pane -t "$pane_target" powershell.exe -NoLogo -NoProfile -File "$helper_windows_path" "$log_windows_path" >/dev/null
+  refresh_snapshot_for_pane "$pane_name"
+}
+
+start_capture_for_all_panes() {
+  start_capture_for_pane "$PANE_LEAD"
+  start_capture_for_pane "$PANE_CODEX"
+  start_capture_for_pane "$PANE_GEMINI"
+}
+
+stop_capture_for_pane() {
+  local pane_name="$1"
+  local pane_target
+
+  pane_target="$(resolve_pane_target "$pane_name" || true)"
+  [[ -n "$pane_target" ]] || return 0
+  "$PSMUX_BIN" pipe-pane -t "$pane_target" >/dev/null 2>&1 || true
+}
+
+refresh_snapshot_for_pane() {
+  local pane_name="$1"
+  local pane_target log_file
+
+  pane_target="$(require_pane_target "$pane_name")"
+  log_file="$(log_file_for "$pane_name")"
+  mkdir -p "$CAPTURE_DIR"
+
+  # Detached Windows sessions may not flush pipe-pane reliably yet.
+  # Overwriting the log with a fresh capture-pane snapshot keeps
+  # completion detection deterministic for the prototype.
+  "$PSMUX_BIN" capture-pane -t "$pane_target" -p >"$log_file"
+}
+
+send_keys_to_pane() {
+  local pane_name="$1"
+  local text="$2"
+  local submit="${3:-1}"
+  local pane_target
+
+  pane_target="$(require_pane_target "$pane_name")"
+  "$PSMUX_BIN" send-keys -t "$pane_target" -l "$text"
+  if [[ "$submit" != "0" ]]; then
+    "$PSMUX_BIN" send-keys -t "$pane_target" C-m
+  fi
+}
+
+dispatch_powershell_command() {
+  local pane_name="$1"
+  local command_text="$2"
+  local token wrapped
+
+  token="${pane_name}-$(date +%s)-$RANDOM"
+  wrapped="${command_text}; \$trifluxExit = if (\$null -ne \$LASTEXITCODE) { [int]\$LASTEXITCODE } else { 0 }; Write-Output \"${COMPLETION_PREFIX}${token}:\$trifluxExit\""
+
+  send_keys_to_pane "$pane_name" "$wrapped" 1
+  printf '%s\n' "$token"
+}
+
+wait_for_pattern() {
+  local pane_name="$1"
+  local pattern="$2"
+  local timeout_sec="${3:-300}"
+  local log_file deadline
+
+  log_file="$(log_file_for "$pane_name")"
+  [[ -f "$log_file" ]] || die "Log file for pane '$pane_name' does not exist. Start capture first."
+
+  deadline=$((SECONDS + timeout_sec))
+  while (( SECONDS <= deadline )); do
+    refresh_snapshot_for_pane "$pane_name"
+    if grep -Eq -- "$pattern" "$log_file"; then
+      return 0
+    fi
+    sleep "$POLL_INTERVAL_SEC"
+  done
+
+  return 1
+}
+
+wait_for_completion_token() {
+  local pane_name="$1"
+  local token="$2"
+  local timeout_sec="${3:-300}"
+  local pattern
+
+  pattern="${COMPLETION_PREFIX}${token}:[0-9]+"
+  wait_for_pattern "$pane_name" "$pattern" "$timeout_sec"
+}
+
+print_log_locations() {
+  mkdir -p "$CAPTURE_DIR"
+  printf '%s\t%s\n' "$PANE_LEAD" "$(log_file_for "$PANE_LEAD")"
+  printf '%s\t%s\n' "$PANE_CODEX" "$(log_file_for "$PANE_CODEX")"
+  printf '%s\t%s\n' "$PANE_GEMINI" "$(log_file_for "$PANE_GEMINI")"
+}
+
+create_session_layout() {
+  local lead_index codex_index gemini_index
+
+  require_psmux
+
+  if session_exists; then
+    die "Session '$SESSION_NAME' already exists. Run cleanup first or set PSMUX_SESSION_NAME."
+  fi
+
+  mkdir -p "$CAPTURE_DIR"
+
+  lead_index="$("$PSMUX_BIN" new-session -d -P -F '#{pane_index}' -s "$SESSION_NAME" -n "$WINDOW_NAME" -- $SHELL_COMMAND)"
+  codex_index="$("$PSMUX_BIN" split-window -h -P -F '#{pane_index}' -t "$(session_target)" -- $SHELL_COMMAND)"
+  gemini_index="$("$PSMUX_BIN" split-window -v -P -F '#{pane_index}' -t "$(pane_target_from_index "$codex_index")" -- $SHELL_COMMAND)"
+
+  set_pane_title "$(pane_target_from_index "$lead_index")" "$PANE_LEAD"
+  set_pane_title "$(pane_target_from_index "$codex_index")" "$PANE_CODEX"
+  set_pane_title "$(pane_target_from_index "$gemini_index")" "$PANE_GEMINI"
+
+  "$PSMUX_BIN" select-layout -t "$(session_target)" tiled >/dev/null
+  "$PSMUX_BIN" select-pane -t "$(pane_target_from_index "$lead_index")" >/dev/null
+
+  start_capture_for_all_panes
+}
+
+show_start_summary() {
+  log "Session created: $SESSION_NAME"
+  log "Window: $WINDOW_NAME"
+  log "Attach with: $PSMUX_BIN attach -t $SESSION_NAME"
+  print_log_locations
+}
+
+run_demo() {
+  local lead_token codex_token gemini_token
+
+  create_session_layout
+
+  lead_token="$(dispatch_powershell_command "$PANE_LEAD" 'Write-Host "lead pane ready"')"
+  codex_token="$(dispatch_powershell_command "$PANE_CODEX" 'Write-Host "codex-worker pane ready"')"
+  gemini_token="$(dispatch_powershell_command "$PANE_GEMINI" 'Write-Host "gemini-worker pane ready"')"
+
+  wait_for_completion_token "$PANE_LEAD" "$lead_token" 30 || die "Lead pane demo command timed out."
+  wait_for_completion_token "$PANE_CODEX" "$codex_token" 30 || die "Codex pane demo command timed out."
+  wait_for_completion_token "$PANE_GEMINI" "$gemini_token" 30 || die "Gemini pane demo command timed out."
+
+  show_start_summary
+}
+
+cleanup() {
+  stop_capture_for_pane "$PANE_LEAD"
+  stop_capture_for_pane "$PANE_CODEX"
+  stop_capture_for_pane "$PANE_GEMINI"
+
+  if session_exists; then
+    "$PSMUX_BIN" kill-session -t "$SESSION_NAME" >/dev/null 2>&1 || true
+  fi
+}
+
+main() {
+  local action="${1:-demo}"
+
+  case "$action" in
+    start)
+      create_session_layout
+      show_start_summary
+      ;;
+    demo)
+      run_demo
+      ;;
+    attach)
+      require_psmux
+      "$PSMUX_BIN" attach -t "$SESSION_NAME"
+      ;;
+    send)
+      [[ $# -ge 3 ]] || die "Usage: $0 send <pane-name> <command text>"
+      shift
+      local pane_name="$1"
+      shift
+      send_keys_to_pane "$pane_name" "$*" 1
+      ;;
+    send-no-enter)
+      [[ $# -ge 3 ]] || die "Usage: $0 send-no-enter <pane-name> <text>"
+      shift
+      local pane_name="$1"
+      shift
+      send_keys_to_pane "$pane_name" "$*" 0
+      ;;
+    steer-ps)
+      [[ $# -ge 3 ]] || die "Usage: $0 steer-ps <pane-name> <powershell command>"
+      shift
+      local pane_name="$1"
+      shift
+      dispatch_powershell_command "$pane_name" "$*"
+      ;;
+    wait)
+      [[ $# -ge 3 ]] || die "Usage: $0 wait <pane-name> <regex> [timeout-sec]"
+      shift
+      local pane_name="$1"
+      local pattern="$2"
+      local timeout_sec="${3:-300}"
+      if wait_for_pattern "$pane_name" "$pattern" "$timeout_sec"; then
+        log "Matched pattern for pane '$pane_name': $pattern"
+      else
+        die "Timed out waiting for pane '$pane_name' pattern: $pattern"
+      fi
+      ;;
+    logs)
+      print_log_locations
+      ;;
+    cleanup)
+      cleanup
+      ;;
+    -h|--help|help)
+      usage
+      ;;
+    *)
+      usage
+      die "Unknown action: $action"
+      ;;
+  esac
+}
+
+main "$@"

package/scripts/run.cjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execFileSync } = require("child_process");
+const { existsSync, readFileSync } = require("fs");
+const { dirname, isAbsolute, join, resolve } = require("path");
+
+function resolvePluginRoot() {
+  if (process.env.CLAUDE_PLUGIN_ROOT) return process.env.CLAUDE_PLUGIN_ROOT;
+  return dirname(__dirname);
+}
+
+function resolveTargetPath(rawTarget) {
+  if (!rawTarget || typeof rawTarget !== "string") return null;
+
+  const pluginRoot = resolvePluginRoot();
+  const trimmed = rawTarget.trim();
+
+  if (trimmed.startsWith("${CLAUDE_PLUGIN_ROOT}/")) {
+    return join(pluginRoot, trimmed.replace("${CLAUDE_PLUGIN_ROOT}/", ""));
+  }
+
+  if (trimmed.startsWith("/scripts/")) {
+    return join(pluginRoot, trimmed.replace(/^\/+/, ""));
+  }
+
+  if (isAbsolute(trimmed)) return trimmed;
+  return resolve(process.cwd(), trimmed);
+}
+
+const targetArg = process.argv[2];
+if (!targetArg) {
+  process.exit(0);
+}
+
+const targetPath = resolveTargetPath(targetArg);
+if (!targetPath || !existsSync(targetPath)) {
+  process.exit(0);
+}
+
+const stdinBuffer = (() => {
+  try {
+    return readFileSync(0);
+  } catch {
+    return Buffer.alloc(0);
+  }
+})();
+
+try {
+  execFileSync(process.execPath, [targetPath, ...process.argv.slice(3)], {
+    env: process.env,
+    stdio: ["pipe", "inherit", "inherit"],
+    input: stdinBuffer,
+    windowsHide: true
+  });
+  process.exit(0);
+} catch (error) {
+  if (typeof error?.status === "number") {
+    process.exit(error.status);
+  }
+  process.exit(0);
+}

package/scripts/setup.mjs

@@ -7,9 +7,30 @@
 import { copyFileSync, mkdirSync, readFileSync, writeFileSync, readdirSync, existsSync, chmodSync, unlinkSync } from "fs";
 import { join, dirname } from "path";
 import { homedir } from "os";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
 
-const PLUGIN_ROOT = dirname(dirname(new URL(import.meta.url).pathname)).replace(/^\/([A-Z]:)/, "$1");
+const PLUGIN_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const CLAUDE_DIR = join(homedir(), ".claude");
+const CODEX_DIR = join(homedir(), ".codex");
+const CODEX_CONFIG_PATH = join(CODEX_DIR, "config.toml");
+
+const REQUIRED_CODEX_PROFILES = [
+  {
+    name: "xhigh",
+    lines: [
+      'model = "gpt-5.3-codex"',
+      'model_reasoning_effort = "xhigh"',
+    ],
+  },
+  {
+    name: "spark_fast",
+    lines: [
+      'model = "gpt-5.1-codex-mini"',
+      'model_reasoning_effort = "low"',
+    ],
+  },
+];
 
 // ── 파일 동기화 ──
 
@@ -24,6 +45,36 @@ const SYNC_MAP = [
     dst: join(CLAUDE_DIR, "scripts", "tfx-route-post.mjs"),
     label: "tfx-route-post.mjs",
   },
+  {
+    src: join(PLUGIN_ROOT, "scripts", "tfx-route-worker.mjs"),
+    dst: join(CLAUDE_DIR, "scripts", "tfx-route-worker.mjs"),
+    label: "tfx-route-worker.mjs",
+  },
+  {
+    src: join(PLUGIN_ROOT, "hub", "workers", "codex-mcp.mjs"),
+    dst: join(CLAUDE_DIR, "scripts", "hub", "workers", "codex-mcp.mjs"),
+    label: "hub/workers/codex-mcp.mjs",
+  },
+  {
+    src: join(PLUGIN_ROOT, "hub", "workers", "interface.mjs"),
+    dst: join(CLAUDE_DIR, "scripts", "hub", "workers", "interface.mjs"),
+    label: "hub/workers/interface.mjs",
+  },
+  {
+    src: join(PLUGIN_ROOT, "hub", "workers", "gemini-worker.mjs"),
+    dst: join(CLAUDE_DIR, "scripts", "hub", "workers", "gemini-worker.mjs"),
+    label: "hub/workers/gemini-worker.mjs",
+  },
+  {
+    src: join(PLUGIN_ROOT, "hub", "workers", "claude-worker.mjs"),
+    dst: join(CLAUDE_DIR, "scripts", "hub", "workers", "claude-worker.mjs"),
+    label: "hub/workers/claude-worker.mjs",
+  },
+  {
+    src: join(PLUGIN_ROOT, "hub", "workers", "factory.mjs"),
+    dst: join(CLAUDE_DIR, "scripts", "hub", "workers", "factory.mjs"),
+    label: "hub/workers/factory.mjs",
+  },
   {
     src: join(PLUGIN_ROOT, "hud", "hud-qos-status.mjs"),
     dst: join(CLAUDE_DIR, "hud", "hud-qos-status.mjs"),
@@ -41,6 +92,54 @@ function getVersion(filePath) {
   }
 }
 
+function shouldSyncTextFile(src, dst) {
+  if (!existsSync(dst)) return true;
+  try {
+    return readFileSync(src, "utf8") !== readFileSync(dst, "utf8");
+  } catch {
+    return true;
+  }
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function hasProfileSection(tomlContent, profileName) {
+  const section = `^\\[profiles\\.${escapeRegExp(profileName)}\\]\\s*$`;
+  return new RegExp(section, "m").test(tomlContent);
+}
+
+function ensureCodexProfiles() {
+  try {
+    if (!existsSync(CODEX_DIR)) mkdirSync(CODEX_DIR, { recursive: true });
+
+    const original = existsSync(CODEX_CONFIG_PATH)
+      ? readFileSync(CODEX_CONFIG_PATH, "utf8")
+      : "";
+
+    let updated = original;
+    let added = 0;
+
+    for (const profile of REQUIRED_CODEX_PROFILES) {
+      if (hasProfileSection(updated, profile.name)) continue;
+
+      if (updated.length > 0 && !updated.endsWith("\n")) updated += "\n";
+      if (updated.trim().length > 0) updated += "\n";
+      updated += `[profiles.${profile.name}]\n${profile.lines.join("\n")}\n`;
+      added++;
+    }
+
+    if (added > 0) {
+      writeFileSync(CODEX_CONFIG_PATH, updated, "utf8");
+    }
+
+    return added;
+  } catch {
+    return 0;
+  }
+}
+
 let synced = 0;
 
 for (const { src, dst, label } of SYNC_MAP) {
@@ -56,9 +155,7 @@ for (const { src, dst, label } of SYNC_MAP) {
     try { chmodSync(dst, 0o755); } catch {}
     synced++;
   } else {
-    const srcVersion = getVersion(src);
-    const dstVersion = getVersion(dst);
-    if (srcVersion && dstVersion && srcVersion !== dstVersion) {
+    if (shouldSyncTextFile(src, dst)) {
       copyFileSync(src, dst);
       try { chmodSync(dst, 0o755); } catch {}
       synced++;
@@ -66,6 +163,34 @@ for (const { src, dst, label } of SYNC_MAP) {
   }
 }
 
+// ── Worker 의존성 동기화 (MCP SDK + transitive deps) ──
+
+const workerNodeModules = join(CLAUDE_DIR, "scripts", "node_modules");
+const mcpSdkPath = join(workerNodeModules, "@modelcontextprotocol", "sdk");
+const srcNodeModules = join(PLUGIN_ROOT, "node_modules");
+
+// native 모듈은 제외 (플랫폼 의존적, worker에서 불필요)
+const SKIP_PACKAGES = new Set(["better-sqlite3", "prebuild-install", "node-abi", "node-addon-api"]);
+
+if (!existsSync(mcpSdkPath) && existsSync(srcNodeModules)) {
+  try {
+    const { cpSync } = await import("fs");
+    for (const entry of readdirSync(srcNodeModules)) {
+      if (SKIP_PACKAGES.has(entry)) continue;
+
+      const src = join(srcNodeModules, entry);
+      const dst = join(workerNodeModules, entry);
+      if (existsSync(dst)) continue;
+
+      mkdirSync(dirname(dst), { recursive: true });
+      cpSync(src, dst, { recursive: true });
+    }
+    synced++;
+  } catch {
+    // best effort: 의존성 복사 실패 시 exec fallback으로 동작
+  }
+}
+
 // ── 스킬 동기화 ──
 
 const skillsSrc = join(PLUGIN_ROOT, "skills");
@@ -130,6 +255,36 @@ if (existsSync(hudPath)) {
   }
 }
 
+// ── Agent Teams 환경변수 자동 설정 ──
+
+try {
+  let agentSettings = {};
+  if (existsSync(settingsPath)) {
+    agentSettings = JSON.parse(readFileSync(settingsPath, "utf8"));
+  }
+
+  if (!agentSettings.env) agentSettings.env = {};
+  let agentSettingsChanged = false;
+
+  if (agentSettings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS !== "1") {
+    agentSettings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1";
+    agentSettingsChanged = true;
+  }
+
+  // teammateMode: auto (tmux 밖이면 in-process, 안이면 split-pane)
+  if (!agentSettings.teammateMode) {
+    agentSettings.teammateMode = "auto";
+    agentSettingsChanged = true;
+  }
+
+  if (agentSettingsChanged) {
+    writeFileSync(settingsPath, JSON.stringify(agentSettings, null, 2) + "\n", "utf8");
+    synced++;
+  }
+} catch {
+  // settings.json 파싱 실패 시 무시 — 기존 설정 보존
+}
+
 // ── Stale PID 파일 정리 (hub 좀비 방지) ──
 
 const HUB_PID_FILE = join(CLAUDE_DIR, "cache", "tfx-hub", "hub.pid");
@@ -196,9 +351,14 @@ if (process.platform === "win32") {
   }
 }
 
-// ── MCP 인벤토리 백그라운드 갱신 ──
+// ── Codex 프로필 자동 보정 ──
 
-import { spawn } from "child_process";
+const codexProfilesAdded = ensureCodexProfiles();
+if (codexProfilesAdded > 0) {
+  synced++;
+}
+
+// ── MCP 인벤토리 백그라운드 갱신 ──
 
 const mcpCheck = join(PLUGIN_ROOT, "scripts", "mcp-check.mjs");
 if (existsSync(mcpCheck)) {
@@ -209,6 +369,26 @@ if (existsSync(mcpCheck)) {
   child.unref(); // 부모 프로세스와 분리 — 비동기 실행
 }
 
+// ── Hub 헬스체크 + 자동 기동 (세션 시작 백그라운드) ──
+// setup 훅이 포그라운드 지연을 만들지 않도록 별도 detached 프로세스로 처리한다.
+const hubEnsure = join(PLUGIN_ROOT, "scripts", "hub-ensure.mjs");
+const isPostinstall = process.env.npm_lifecycle_event === "postinstall";
+const isCi = /^(1|true)$/i.test(process.env.CI || "");
+const disableHubAutostart = process.env.TFX_DISABLE_HUB_AUTOSTART === "1";
+
+if (!isPostinstall && !isCi && !disableHubAutostart && existsSync(hubEnsure)) {
+  try {
+    const child = spawn(process.execPath, [hubEnsure], {
+      env: process.env,
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+  } catch {
+    // best effort: 실패해도 setup 흐름은 지속
+  }
+}
+
 // ── postinstall 배너 (npm install 시에만 출력) ──
 
 if (process.env.npm_lifecycle_event === "postinstall") {
@@ -239,7 +419,8 @@ ${B}Commands:${R}
   ${C}triflux${R} setup     파일 동기화 + HUD 설정
   ${C}triflux${R} doctor    CLI 진단 (Codex/Gemini 확인)
   ${C}triflux${R} list      설치된 스킬 목록
-  ${C}triflux${R} update    최신 버전으로 업데이트
+  ${C}triflux${R} update    최신 안정 버전으로 업데이트
+  ${C}triflux${R} update --dev  dev 채널로 업데이트 (${D}dev 별칭 지원${R})
 
 ${B}Shortcuts:${R}
   ${C}tfx${R}                 triflux 축약
@@ -248,6 +429,7 @@ ${B}Shortcuts:${R}
 
 ${B}Skills (Claude Code):${R}
   ${C}/tfx-auto${R}   "작업"   자동 분류 + 병렬 실행
+  ${C}/tfx-auto-codex${R} "작업" Codex 리드 + Gemini 유지
   ${C}/tfx-codex${R}  "작업"   Codex 전용 모드
   ${C}/tfx-gemini${R} "작업"   Gemini 전용 모드
   ${C}/tfx-setup${R}           HUD 설정 + 진단