@triflux/core 10.0.3 → 10.25.1

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/lib/dynamic-route-cli.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// scripts/lib/dynamic-route-cli.mjs
+//
+// Phase 1 Wire-up 3 helper — tfx-route.sh 등 sh 경로에서 dynamic routing
+// decision 을 받아 단일 CLI 문자열 (또는 JSON) 으로 출력한다.
+//
+// 사용:
+//   node scripts/lib/dynamic-route-cli.mjs --agent-hint codex
+//   → "codex"
+//   node scripts/lib/dynamic-route-cli.mjs --agent-hint codex --json
+//   → {"scenario":"fallback","mode":"codex-default","shards":[{"cli":"codex",...}]}
+//   node scripts/lib/dynamic-route-cli.mjs --agent-hint codex --field scenario
+//   → "fallback"
+//
+// 정책:
+//   - opt-in env TRIFLUX_DYNAMIC_ROUTING=1|true 미설정 시 즉시 silent exit 0
+//     (override 없음 = stdout empty, sh caller 가 graceful no-op).
+//   - error 발생 시 stderr 에 한 줄 + exit 0 (sh caller 가 fallback path 진행).
+
+import { createDynamicRouter } from "../../hub/dynamic-routing-engine.mjs";
+
+function parseArgs(argv) {
+  const args = {
+    taskId: `tfx-route-${process.pid}-${Date.now()}`,
+    agentHint: "codex",
+    teamSize: 1,
+    json: false,
+    field: null,
+  };
+  for (let i = 2; i < argv.length; i++) {
+    const v = argv[i];
+    switch (v) {
+      case "--task-id":
+        args.taskId = argv[++i] || args.taskId;
+        break;
+      case "--agent-hint":
+        args.agentHint = argv[++i] || args.agentHint;
+        break;
+      case "--team-size":
+        args.teamSize = Number(argv[++i]) || args.teamSize;
+        break;
+      case "--json":
+        args.json = true;
+        break;
+      case "--field":
+        args.field = argv[++i] || null;
+        break;
+      case "--help":
+      case "-h":
+        process.stdout.write(
+          "Usage: dynamic-route-cli.mjs [--task-id ID] [--agent-hint CLI] [--team-size N] [--json|--field FIELD]\n",
+        );
+        process.exit(0);
+        break;
+    }
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+
+  // opt-in env 미설정 시 silent no-op (sh caller graceful path)
+  const flag = process.env.TRIFLUX_DYNAMIC_ROUTING;
+  if (flag !== "1" && flag !== "true") return;
+
+  let decision;
+  try {
+    const router = createDynamicRouter();
+    decision = await router.routeRequest({
+      task_id: args.taskId,
+      team_size: args.teamSize,
+      agent_hint: args.agentHint,
+    });
+  } catch (err) {
+    process.stderr.write(
+      `[dynamic-route-cli] error: ${err?.message || String(err)}\n`,
+    );
+    return;
+  }
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify(decision));
+    return;
+  }
+
+  if (args.field) {
+    const value = decision?.[args.field];
+    if (value !== undefined && value !== null) {
+      process.stdout.write(String(value));
+    }
+    return;
+  }
+
+  // 기본 — shards[0].cli 만 stdout 으로 (sh caller 가 즉시 비교)
+  const cli = decision?.shards?.[0]?.cli;
+  if (cli) {
+    process.stdout.write(String(cli));
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(
+    `[dynamic-route-cli] fatal: ${err?.message || String(err)}\n`,
+  );
+  process.exit(0); // sh caller 가 정상 fallback 하도록 always 0
+});

package/scripts/lib/env-probe.mjs

@@ -1,11 +1,12 @@
+import { execSync, spawn } from "node:child_process";
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
 import { homedir } from "node:os";
-import { execSync, spawn } from "node:child_process";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createHash } from "node:crypto";
 import { whichCommand, whichCommandAsync } from "../../hub/platform.mjs";
 
+const HUB_DEFAULT_PORT = 27888;
 const DEFAULT_STATUS_URL = "http://127.0.0.1:27888/status";
 const _sab = new Int32Array(new SharedArrayBuffer(4));
 const CLI_PROBE_CACHE = new Map();
@@ -20,7 +21,7 @@ function sleepSync(ms) {
 
 function fetchHubStatus({
   execSyncFn = execSync,
-  statusUrl = DEFAULT_STATUS_URL,
+  statusUrl = resolveDefaultStatusUrl(),
   timeout = 3000,
 } = {}) {
   const response = execSyncFn(`curl -sf ${statusUrl}`, {
@@ -36,6 +37,13 @@ function fetchHubStatus({
   };
 }
 
+export function resolveDefaultStatusUrl(env = process.env) {
+  const envPort = Number.parseInt(String(env?.TFX_HUB_PORT ?? ""), 10);
+  const port =
+    Number.isFinite(envPort) && envPort > 0 ? envPort : HUB_DEFAULT_PORT;
+  return `http://127.0.0.1:${port}/status`;
+}
+
 function normalizeCliName(name) {
   return String(name ?? "").trim() || null;
 }
@@ -73,10 +81,13 @@ function normalizeCliNames(names) {
 }
 
 function mapCliResults(names, results) {
-  return names.reduce((acc, name, index) => ({
-    ...acc,
-    [name]: results[index],
-  }), {});
+  return names.reduce(
+    (acc, name, index) => ({
+      ...acc,
+      [name]: results[index],
+    }),
+    {},
+  );
 }
 
 async function resolveCliProbe(name, options = {}) {
@@ -115,13 +126,18 @@ export function checkCliSync(name, options = {}) {
   const cached = readCachedCliResult(cliName);
   if (cached) return cached;
 
-  const path = (options.whichCommandFn || whichCommand)(cliName, buildCliProbeOptions(options));
+  const path = (options.whichCommandFn || whichCommand)(
+    cliName,
+    buildCliProbeOptions(options),
+  );
   return storeCliResult(cliName, toCliResult(path));
 }
 
 export async function probeClis(names, options = {}) {
   const cliNames = normalizeCliNames(names);
-  const results = await Promise.all(cliNames.map((name) => checkCli(name, options)));
+  const results = await Promise.all(
+    cliNames.map((name) => checkCli(name, options)),
+  );
   return mapCliResults(cliNames, results);
 }
 
@@ -137,15 +153,18 @@ export function detectCodexAuthState({
 } = {}) {
   try {
     const authPath = join(homeDir, ".codex", "auth.json");
-    if (!existsSyncFn(authPath)) return { plan: "unknown", source: "no_auth", fingerprint: "no_auth" };
+    if (!existsSyncFn(authPath))
+      return { plan: "unknown", source: "no_auth", fingerprint: "no_auth" };
 
     const auth = JSON.parse(readFileSyncFn(authPath, "utf8"));
     if (auth.auth_mode !== "chatgpt") {
       const fingerprint = createHash("sha256")
-        .update(JSON.stringify({
-          auth_mode: auth.auth_mode || "api_key",
-          has_api_key: Boolean(auth.api_key || auth.apiKey),
-        }))
+        .update(
+          JSON.stringify({
+            auth_mode: auth.auth_mode || "api_key",
+            has_api_key: Boolean(auth.api_key || auth.apiKey),
+          }),
+        )
         .digest("hex");
       return { plan: "api", source: "api_key", fingerprint };
     }
@@ -156,20 +175,30 @@ export function detectCodexAuthState({
         plan: "unknown",
         source: "no_token",
         fingerprint: createHash("sha256")
-          .update(JSON.stringify({ auth_mode: auth.auth_mode || "chatgpt", token: null }))
+          .update(
+            JSON.stringify({
+              auth_mode: auth.auth_mode || "chatgpt",
+              token: null,
+            }),
+          )
           .digest("hex"),
       };
     }
 
-    const payload = JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString());
-    const plan = payload?.["https://api.openai.com/auth"]?.chatgpt_plan_type || "unknown";
+    const payload = JSON.parse(
+      Buffer.from(token.split(".")[1], "base64url").toString(),
+    );
+    const plan =
+      payload?.["https://api.openai.com/auth"]?.chatgpt_plan_type || "unknown";
     const fingerprint = createHash("sha256")
-      .update(JSON.stringify({
-        auth_mode: auth.auth_mode || "chatgpt",
-        plan,
-        sub: payload?.sub || null,
-        exp: payload?.exp || null,
-      }))
+      .update(
+        JSON.stringify({
+          auth_mode: auth.auth_mode || "chatgpt",
+          plan,
+          sub: payload?.sub || null,
+          exp: payload?.exp || null,
+        }),
+      )
       .digest("hex");
     return { plan, source: "jwt", fingerprint };
   } catch {
@@ -184,7 +213,7 @@ export function detectCodexPlan(options = {}) {
 
 export function checkHub({
   pkgRoot = DEFAULT_PKG_ROOT,
-  statusUrl = DEFAULT_STATUS_URL,
+  statusUrl = resolveDefaultStatusUrl(),
   restart = true,
   requestTimeoutMs = 3000,
   pollAttempts = 8,
@@ -205,10 +234,12 @@ export function checkHub({
   if (!restart) return { ok: false, state: "unreachable", restart: "disabled" };
 
   const serverPath = join(pkgRoot, "hub", "server.mjs");
-  if (!existsSyncFn(serverPath)) return { ok: false, state: "unreachable", restart: "no_server" };
+  if (!existsSyncFn(serverPath))
+    return { ok: false, state: "unreachable", restart: "no_server" };
 
   try {
     const child = spawnFn(process.execPath, [serverPath], {
+      env: { ...process.env, TFX_HUB_PORT: String(new URL(statusUrl).port) },
       detached: true,
       stdio: "ignore",
       windowsHide: true,
@@ -235,7 +266,4 @@ export function checkHub({
   return { ok: false, state: "unreachable", restart: "timeout" };
 }
 
-export {
-  DEFAULT_PKG_ROOT,
-  DEFAULT_STATUS_URL,
-};
+export { DEFAULT_PKG_ROOT, DEFAULT_STATUS_URL };

package/scripts/lib/env.mjs

@@ -0,0 +1,14 @@
+export function buildPreflightEnv(env = process.env) {
+  return {
+    ...env,
+    GIT_TERMINAL_PROMPT: env.GIT_TERMINAL_PROMPT ?? "0",
+    GIT_ASKPASS: env.GIT_ASKPASS ?? "false",
+    npm_config_yes: env.npm_config_yes ?? "true",
+  };
+}
+
+export function shouldWarnGhAuth(env = process.env, checks = {}) {
+  if (!checks.ghExists) return false;
+  if (env.GH_TOKEN || env.GITHUB_TOKEN) return false;
+  return checks.ghAuthenticated === false;
+}

package/scripts/lib/gemini-profiles.mjs

@@ -1,19 +1,33 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
 const DEFAULT_GEMINI_PROFILES = {
   model: "gemini-3.1-pro-preview",
   profiles: {
-    pro31: { model: "gemini-3.1-pro-preview", hint: "3.1 Pro — 플래그십 (1M ctx, 멀티모달)" },
-    flash3: { model: "gemini-3-flash-preview", hint: "3.0 Flash — 빠른 응답, 비용 효율" },
+    pro31: {
+      model: "gemini-3.1-pro-preview",
+      hint: "3.1 Pro — 플래그십 (1M ctx, 멀티모달)",
+    },
+    flash3: {
+      model: "gemini-3-flash-preview",
+      hint: "3.0 Flash — 빠른 응답, 비용 효율",
+    },
     pro25: { model: "gemini-2.5-pro", hint: "2.5 Pro — 안정 (추론 강화)" },
     flash25: { model: "gemini-2.5-flash", hint: "2.5 Flash — 경량 범용" },
     lite25: { model: "gemini-2.5-flash-lite", hint: "2.5 Flash Lite — 최경량" },
   },
 };
 
-const DEFAULT_PROFILE_COUNT = Object.keys(DEFAULT_GEMINI_PROFILES.profiles).length;
+const DEFAULT_PROFILE_COUNT = Object.keys(
+  DEFAULT_GEMINI_PROFILES.profiles,
+).length;
 
 function ensureGeminiProfiles({
   geminiDir = join(homedir(), ".gemini"),
@@ -23,7 +37,11 @@ function ensureGeminiProfiles({
     if (!existsSync(geminiDir)) mkdirSync(geminiDir, { recursive: true });
 
     if (!existsSync(profilesPath)) {
-      writeFileSync(profilesPath, JSON.stringify(DEFAULT_GEMINI_PROFILES, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+      writeFileSync(
+        profilesPath,
+        JSON.stringify(DEFAULT_GEMINI_PROFILES, null, 2) + "\n",
+        { encoding: "utf8", mode: 0o600 },
+      );
       return {
         ok: true,
         created: true,
@@ -37,8 +55,14 @@ function ensureGeminiProfiles({
     try {
       cfg = JSON.parse(readFileSync(profilesPath, "utf8"));
     } catch {
-      try { copyFileSync(profilesPath, profilesPath + `.bak.${Date.now()}`); } catch {}
-      writeFileSync(profilesPath, JSON.stringify(DEFAULT_GEMINI_PROFILES, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+      try {
+        copyFileSync(profilesPath, profilesPath + `.bak.${Date.now()}`);
+      } catch {}
+      writeFileSync(
+        profilesPath,
+        JSON.stringify(DEFAULT_GEMINI_PROFILES, null, 2) + "\n",
+        { encoding: "utf8", mode: 0o600 },
+      );
       return {
         ok: true,
         created: true,
@@ -49,10 +73,17 @@ function ensureGeminiProfiles({
     }
 
     if (!cfg || typeof cfg !== "object" || Array.isArray(cfg)) cfg = {};
-    if (!cfg.profiles || typeof cfg.profiles !== "object" || Array.isArray(cfg.profiles)) cfg.profiles = {};
+    if (
+      !cfg.profiles ||
+      typeof cfg.profiles !== "object" ||
+      Array.isArray(cfg.profiles)
+    )
+      cfg.profiles = {};
 
     let added = 0;
-    for (const [name, value] of Object.entries(DEFAULT_GEMINI_PROFILES.profiles)) {
+    for (const [name, value] of Object.entries(
+      DEFAULT_GEMINI_PROFILES.profiles,
+    )) {
       if (!cfg.profiles[name]) {
         cfg.profiles[name] = value;
         added++;
@@ -61,7 +92,10 @@ function ensureGeminiProfiles({
     if (!cfg.model) cfg.model = DEFAULT_GEMINI_PROFILES.model;
 
     if (added > 0) {
-      writeFileSync(profilesPath, JSON.stringify(cfg, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+      writeFileSync(profilesPath, JSON.stringify(cfg, null, 2) + "\n", {
+        encoding: "utf8",
+        mode: 0o600,
+      });
     }
 
     return {

package/scripts/lib/handoff.mjs

@@ -18,7 +18,9 @@ function runCommand(command, cwd, executor = execSync) {
 }
 
 function parseStatusLines(statusText) {
-  const lines = String(statusText || "").split(/\r?\n/u).filter(Boolean);
+  const lines = String(statusText || "")
+    .split(/\r?\n/u)
+    .filter(Boolean);
   const changedFiles = [];
   const status = [];
 
@@ -28,7 +30,9 @@ function parseStatusLines(statusText) {
 
     const rawStatus = normalized.slice(0, 2).trim() || "??";
     const rawPath = normalized.slice(3).trim();
-    const filePath = rawPath.includes(" -> ") ? rawPath.split(" -> ").at(-1)?.trim() : rawPath;
+    const filePath = rawPath.includes(" -> ")
+      ? rawPath.split(" -> ").at(-1)?.trim()
+      : rawPath;
     if (!filePath) continue;
 
     changedFiles.push(filePath);
@@ -82,22 +86,30 @@ function formatAheadBehind(value) {
 
 export function collectHandoffContext(options = {}) {
   const cwd = resolve(options.cwd || process.cwd());
-  const executor = typeof options.commandRunner === "function" ? options.commandRunner : execSync;
+  const executor =
+    typeof options.commandRunner === "function"
+      ? options.commandRunner
+      : execSync;
   const target = options.target === "local" ? "local" : "remote";
   const decisions = normalizeDecisions(options.decisions, options.decisionFile);
   const generatedAt = options.generatedAt || new Date().toISOString();
   const claudeMdPaths = Array.isArray(options.claudeMdPaths)
     ? options.claudeMdPaths
     : findAllClaudeMdPaths({
-      cwd,
-      homeDir: options.homeDir,
-    });
+        cwd,
+        homeDir: options.homeDir,
+      });
 
   const gitRoot = runCommand("git rev-parse --show-toplevel", cwd, executor);
-  const branch = runCommand("git rev-parse --abbrev-ref HEAD", cwd, executor) || null;
+  const branch =
+    runCommand("git rev-parse --abbrev-ref HEAD", cwd, executor) || null;
   const shortStatus = runCommand("git status --short", cwd, executor);
   const diffStat = runCommand("git diff --stat --no-color", cwd, executor);
-  const upstreamRaw = runCommand("git rev-list --left-right --count @{upstream}...HEAD", cwd, executor);
+  const upstreamRaw = runCommand(
+    "git rev-list --left-right --count @{upstream}...HEAD",
+    cwd,
+    executor,
+  );
   const parsedStatus = parseStatusLines(shortStatus);
 
   return {
@@ -122,15 +134,19 @@ export function buildHandoffPrompt(context) {
   const upstream = safeContext.upstream
     ? `ahead ${safeContext.upstream.ahead}, behind ${safeContext.upstream.behind}`
     : "unknown";
-  const changedFiles = safeContext.changedFiles.length > 0
-    ? safeContext.changedFiles.map((file) => `- ${file}`).join("\n")
-    : "- 변경 파일 없음";
-  const decisions = safeContext.decisions.length > 0
-    ? safeContext.decisions.map((decision) => `- ${decision}`).join("\n")
-    : "- 명시된 결정사항 없음";
-  const claudeMdList = Array.isArray(safeContext.claudeMdPaths) && safeContext.claudeMdPaths.length > 0
-    ? safeContext.claudeMdPaths.map((path) => `- ${path}`).join("\n")
-    : "- 자동 탐지된 CLAUDE.md 없음";
+  const changedFiles =
+    safeContext.changedFiles.length > 0
+      ? safeContext.changedFiles.map((file) => `- ${file}`).join("\n")
+      : "- 변경 파일 없음";
+  const decisions =
+    safeContext.decisions.length > 0
+      ? safeContext.decisions.map((decision) => `- ${decision}`).join("\n")
+      : "- 명시된 결정사항 없음";
+  const claudeMdList =
+    Array.isArray(safeContext.claudeMdPaths) &&
+    safeContext.claudeMdPaths.length > 0
+      ? safeContext.claudeMdPaths.map((path) => `- ${path}`).join("\n")
+      : "- 자동 탐지된 CLAUDE.md 없음";
   const diffStat = safeContext.diffStat || "(diff stat 없음)";
 
   return [

package/scripts/lib/hook-utils.mjs

@@ -1,10 +1,12 @@
 export function nudge(message) {
-  process.stdout.write(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: "PreToolUse",
-      additionalContext: message,
-    },
-  }));
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext: message,
+      },
+    }),
+  );
   process.exit(0);
 }
 

package/scripts/lib/hub.mjs

@@ -0,0 +1,48 @@
+import { spawn } from "node:child_process";
+
+export function parseHubPort(hubUrl = "") {
+  try {
+    const parsed = new URL(hubUrl);
+    return parsed.port || "27888";
+  } catch {
+    return "27888";
+  }
+}
+
+export async function restartHub({
+  hubUrl = process.env.TFX_HUB_URL || "http://127.0.0.1:27888",
+  hubServer,
+  nodeBin = process.execPath,
+  spawnFn = spawn,
+  fetchFn = globalThis.fetch,
+  sleepMs = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  attempts = 8,
+} = {}) {
+  if (!hubServer) return { ok: false, error: "hub_server_missing" };
+  const port = parseHubPort(hubUrl);
+  const child = spawnFn(nodeBin, [hubServer], {
+    env: { ...process.env, TFX_HUB_PORT: port },
+    stdio: "ignore",
+    detached: true,
+  });
+  child.unref?.();
+
+  for (let i = 0; i < attempts; i += 1) {
+    await sleepMs(500);
+    try {
+      const response = await fetchFn(`${hubUrl.replace(/\/$/, "")}/status`);
+      if (response?.ok) return { ok: true, pid: child.pid };
+    } catch {
+      // Keep polling until attempts are exhausted.
+    }
+  }
+  return { ok: false, pid: child.pid };
+}
+
+export async function withHubRestart({ action, restart }) {
+  const first = await action();
+  if (first?.ok) return first;
+  const restarted = await restart();
+  if (!restarted?.ok) return first;
+  return action();
+}