triflux 10.28.0 → 10.29.0

package/bin/tfx-live.mjs

@@ -42,6 +42,8 @@ function usage() {
     "  tfx-live converse --session NAME --prompts-file PATH [--cli codex|claude] [--remote HOST] [--cwd DIR] [--timeout 60] [--settle 1500]",
     "  tfx-live goal-driven --session NAME --goal TEXT [--cli codex|claude] [--remote HOST] [--cwd DIR] [--timeout 60] [--settle 1500] [--max-rounds 8] [--done-token DONE]",
     "  tfx-live peer [--cli-a codex] [--cli-b claude] [--session-a peerA] [--session-b peerB] [--transport-a tmux|uds|auto] [--transport-b tmux|uds|auto] [--short-a SHORT] [--short-b SHORT] [--session-id-a ID] [--session-id-b ID] [--bridge ABS] [--remote HOST] [--cwd DIR] [--rounds 4] [--mode counting|freeform] [--seed TEXT] [--timeout 60]",
+    "  tfx-live orchestrate --task TEXT [--mode peer|codex-led|claude-led] [--codex-transport exec|app-server-uds] [--cwd DIR] [--timeout 120]",
+    "    Runs the Claude(UDS)+Codex orchestration engine. --codex-transport app-server-uds drives a real `codex app-server` over WebSocket-over-UDS (experimental); default exec keeps the codex stdio one-shot path.",
   ].join("\n");
 }
 
@@ -1690,6 +1692,47 @@ async function peer(flags) {
   printJson(output);
 }
 
+const ORCHESTRATION_MODES = ["peer", "codex-led", "claude-led"];
+const CODEX_ORCH_TRANSPORTS = ["exec", "app-server-uds"];
+
+async function orchestrate(flags) {
+  const mode = flags.mode ?? "peer";
+  if (!ORCHESTRATION_MODES.includes(mode)) {
+    throw new Error(`--mode must be one of: ${ORCHESTRATION_MODES.join(", ")}`);
+  }
+  const task = requireFlag(flags, "task");
+  const codexTransport = flags["codex-transport"] ?? "exec";
+  if (!CODEX_ORCH_TRANSPORTS.includes(codexTransport)) {
+    throw new Error(
+      `--codex-transport must be one of: ${CODEX_ORCH_TRANSPORTS.join(", ")}`,
+    );
+  }
+  const cwd = flags.cwd ?? process.cwd();
+  const timeoutMs = secondsFlag(flags, "timeout", 120_000);
+
+  // Lazy import keeps the orchestration engine (and its hub/team deps) off the
+  // hot path for every other thin-CLI verb; only `orchestrate` pays the cost.
+  const orchestratorUrl = new URL(
+    "../hub/team/uds-orchestrator.mjs",
+    import.meta.url,
+  ).href;
+  const {
+    runUdsOrchestration,
+    createClaudeUdsEndpoint,
+    createCodexExecEndpoint,
+    createCodexAppServerUdsEndpoint,
+  } = await import(orchestratorUrl);
+
+  const claude = createClaudeUdsEndpoint({ cwd, timeoutMs });
+  const codex =
+    codexTransport === "app-server-uds"
+      ? createCodexAppServerUdsEndpoint({ cwd, timeoutMs })
+      : createCodexExecEndpoint({ workdir: cwd, timeout: timeoutMs });
+
+  const result = await runUdsOrchestration({ mode, task, claude, codex });
+  printJson({ codexTransport, ...result });
+}
+
 function printJson(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
@@ -1718,6 +1761,8 @@ async function main() {
     await goalDriven(flags);
   } else if (command === "peer") {
     await peer(flags);
+  } else if (command === "orchestrate") {
+    await orchestrate(flags);
   } else {
     throw new Error(`Unknown subcommand: ${command}\n${usage()}`);
   }

package/hooks/pipeline-stop.mjs

@@ -142,7 +142,7 @@ function contextPercentsFromObject(value) {
   ];
 
   const currentUsage = value.current_usage ?? value.currentUsage ?? {};
-  const maxTokens =
+  const explicitMaxTokens =
     value.context_window_size ??
     value.contextWindowSize ??
     value.max_context_tokens ??
@@ -151,6 +151,18 @@ function contextPercentsFromObject(value) {
     value.maxTokens ??
     value.total_tokens ??
     value.totalTokens;
+  // Fall back to a 1M context window when the payload omits one — Opus 4.x
+  // [1M] and Codex gpt-5.5 both run on a 1M window, and assuming 200K there
+  // false-positives at ~15% real usage. Override via
+  // TFX_CONTEXT_DEFAULT_MAX_TOKENS for narrower setups.
+  const envFallback = Number(process.env.TFX_CONTEXT_DEFAULT_MAX_TOKENS);
+  const fallbackMaxTokens =
+    Number.isFinite(envFallback) && envFallback > 0 ? envFallback : 1_000_000;
+  const explicitNumeric = Number(explicitMaxTokens);
+  const maxTokens =
+    Number.isFinite(explicitNumeric) && explicitNumeric > 0
+      ? explicitNumeric
+      : fallbackMaxTokens;
   candidates.push(
     tokenPercent(value.used_tokens ?? value.usedTokens, maxTokens),
     tokenPercent(

package/hooks/session-end-cleanup.mjs

@@ -9,6 +9,7 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { unregisterSynapseSession } from "../hub/team/synapse-http.mjs";
 
 const MARKER = "[session-end-cleanup]";
 const STALE_MS = 30 * 60 * 1000;
@@ -292,6 +293,20 @@ function buildOutput(summary, cleanup, tmuxReport) {
 export function run(input, env = process.env) {
   if (input?.hook_event_name !== "SessionEnd") return "";
 
+  // Best-effort Synapse unregister (fire-and-forget). Crash-safe: if this hook
+  // never fires, the 5-min interactive TTL eventually marks the row stale, so
+  // unregister is an optimization, not a correctness dependency. Never throws,
+  // never changes the report-only stdout contract below.
+  //
+  // Bounded timeout (unref AbortController inside synapse-http) so a stalled hub
+  // cannot keep this short-lived SessionEnd hook process alive past its budget.
+  try {
+    const sessionId = String(input?.session_id || "").trim();
+    if (sessionId) unregisterSynapseSession(sessionId, { timeoutMs: 1500 });
+  } catch {
+    /* swallow — report-only charter preserved */
+  }
+
   const root = env.CLAUDE_CWD || process.cwd();
   const statePath = join(root, ".triflux", "subagents", "subagents.json");
   if (!existsSync(statePath)) return "";

package/hooks/session-start-fast.mjs

@@ -10,8 +10,14 @@
 //
 // external source 훅 (session-vault 등)은 여전히 execFile로 실행된다.
 
+import { execFile } from "node:child_process";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  drainPendingSynapse,
+  heartbeatSynapseSession,
+  registerSynapseSession,
+} from "../hub/team/synapse-http.mjs";
 import { createModuleLogger } from "../scripts/lib/logger.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -20,6 +26,111 @@ const importMod = (p) => import(pathToFileURL(p).href);
 
 const log = createModuleLogger("session-start-fast");
 
+/**
+ * SessionStart 페이로드(JSON 문자열)에서 session_id / cwd 를 추출한다.
+ * 파싱 실패는 빈 객체로 흡수한다 (BLOCKING path 에 절대 영향 없음).
+ */
+function parseStartPayload(stdinData) {
+  try {
+    const raw = typeof stdinData === "string" ? stdinData : "";
+    return raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * cwd 기준 git 컨텍스트(worktree root / branch)를 best-effort, 비동기로 수집.
+ * execFileSync 와 달리 호출자(BACKGROUND)를 블로킹하지 않는다. 각 git 호출은
+ * tight timeout(1.5s) + 강제 kill 로 묶여 hub/디스크 stall 시에도 잔류하지 않는다.
+ * @param {string} cwd
+ * @param {(args:string[], cb:(out:string)=>void)=>void} [gitRunner] 테스트용 seam
+ * @returns {Promise<{ worktreePath: string, branch: string }>}
+ */
+function gitContextAsync(cwd, gitRunner = defaultGitRunner) {
+  const run = (args) =>
+    new Promise((resolve) => {
+      try {
+        gitRunner(cwd, args, (out) => resolve(out));
+      } catch {
+        resolve("");
+      }
+    });
+  return Promise.all([
+    run(["rev-parse", "--show-toplevel"]),
+    run(["rev-parse", "--abbrev-ref", "HEAD"]),
+  ]).then(([toplevel, branch]) => ({
+    worktreePath: toplevel || cwd,
+    branch,
+  }));
+}
+
+/** 기본 git runner: execFile(async) + tight timeout + kill. 실패는 빈 문자열. */
+function defaultGitRunner(cwd, args, cb) {
+  execFile(
+    "git",
+    args,
+    {
+      cwd,
+      encoding: "utf8",
+      timeout: 1500,
+      killSignal: "SIGKILL",
+      windowsHide: true,
+    },
+    (err, stdout) => {
+      cb(err ? "" : String(stdout || "").trim());
+    },
+  );
+}
+
+/**
+ * 인터랙티브 세션을 Synapse 레지스트리에 self-register (fire-and-forget).
+ * hub 미응답이면 silent no-op. BLOCKING path 에 latency 0 — git 컨텍스트는
+ * 블로킹 경로 밖에서 비동기로 enrich 한다 (cwd 만으로 즉시 minimal register).
+ *
+ * pid 는 의도적으로 보내지 않는다: 이 훅 프로세스의 process.pid 는 short-lived
+ * 훅 PID 일 뿐 세션 PID 가 아니므로 오기재가 된다. liveness 는 TTL 이 담당한다.
+ *
+ * @param {string} stdinData
+ * @param {object} [seams] 테스트용 injectable seam
+ * @param {Function} [seams.register]  registerSynapseSession 대체
+ * @param {Function} [seams.heartbeat] heartbeatSynapseSession 대체
+ * @param {Function} [seams.gitRunner] git runner 대체
+ * @returns {void} (enrich 는 백그라운드에서 완료)
+ */
+export function registerInteractiveSession(stdinData, seams = {}) {
+  const register = seams.register || registerSynapseSession;
+  const heartbeat = seams.heartbeat || heartbeatSynapseSession;
+  const gitRunner = seams.gitRunner || defaultGitRunner;
+  try {
+    const payload = parseStartPayload(stdinData);
+    const sessionId = String(payload?.session_id || "").trim();
+    if (!sessionId) return;
+    const cwd = typeof payload?.cwd === "string" ? payload.cwd : process.cwd();
+
+    // 1) cwd 만으로 즉시 minimal register (블로킹 git 없음, latency 0).
+    register({
+      sessionId,
+      cwd,
+      worktreePath: cwd,
+      branch: "",
+      host: "local",
+      sessionKind: "interactive",
+      isRemote: false,
+    });
+
+    // 2) worktree/branch 는 블로킹 경로 밖에서 비동기 enrich → heartbeat partial.
+    gitContextAsync(cwd, gitRunner)
+      .then(({ worktreePath, branch }) => {
+        if (worktreePath === cwd && !branch) return; // 추가 정보 없음
+        heartbeat(sessionId, { worktreePath, branch });
+      })
+      .catch(() => {});
+  } catch {
+    /* best-effort — never affects session start */
+  }
+}
+
 /**
  * BLOCKING 훅을 순차 실행. 하나라도 throw하면 로그만 남기고 계속.
  * @param {string} stdinData
@@ -174,6 +285,9 @@ function runBackground(stdinData) {
     .then((mod) => mod.run(stdinData))
     .catch(() => {}); // 완전 무시
 
+  // Synapse: 인터랙티브 세션 self-register (fire-and-forget, hub 미응답 무시)
+  registerInteractiveSession(stdinData);
+
   // session-vault은 external source — hook-orchestrator가 execFile로 실행
 }
 
@@ -195,6 +309,15 @@ export async function execute(stdinData, externalHooks = []) {
   runDeferred(stdinData);
   runBackground(stdinData);
 
+  // hook-orchestrator process.exit(0)s immediately after we return, which would
+  // drop the just-fired Synapse register POST before it flushes to the loopback
+  // socket (Node's exit abandons pending I/O). Drain it with a tight bound: the
+  // register is a fast localhost POST (hub was ensured up in the BLOCKING phase)
+  // and the ceiling caps a hub stall so SessionStart never hangs. The async
+  // git-enrich heartbeat stays best-effort (it may not have fired yet) — losing
+  // it only drops worktree/branch enrichment, not the core registration.
+  await drainPendingSynapse(1000);
+
   const totalDur = performance.now() - totalStart;
   log.info(
     {

package/hub/server.mjs

@@ -56,7 +56,10 @@ import { createStoreAdapter } from "./store-adapter.mjs";
 import { createGitPreflight } from "./team/git-preflight.mjs";
 import { nativeProxy } from "./team/nativeProxy.mjs";
 import { createSwarmLocks } from "./team/swarm-locks.mjs";
-import { createSynapseRegistry } from "./team/synapse-registry.mjs";
+import {
+  createSynapseRegistry,
+  projectPeer,
+} from "./team/synapse-registry.mjs";
 import { registerTeamBridge } from "./team-bridge.mjs";
 import { createTools } from "./tools.mjs";
 import { createDelegatorMcpWorker } from "./workers/delegator-mcp.mjs";
@@ -1299,7 +1302,20 @@ export async function startHub({
       }
 
       // ── Synapse Layer 5: session registry + locks + preflight routes ──
+      // Admin/raw snapshot (loopback-only). Returns raw cwd/pid for local
+      // admin/HUD use; the redacted peer surface is GET /synapse/peers.
       if (path === "/synapse/sessions" && req.method === "GET") {
+        // Enforce the loopback boundary independent of token mode: the global
+        // token gate admits any token-bearing remote client, but this raw
+        // snapshot leaks absolute cwd/pid/worktreePath/dirtyFiles for every
+        // session, so it must never be reachable off 127.0.0.1 (LOCKED #3: raw
+        // cwd is admin-only via loopback). Off-loopback peers use /synapse/peers.
+        if (!isLoopbackRemoteAddress(req.socket.remoteAddress)) {
+          return writeJson(res, 403, {
+            ok: false,
+            error: "Forbidden: /synapse/sessions is loopback-only",
+          });
+        }
         return writeJson(res, 200, {
           ok: true,
           ...synapseRegistry.snapshot(),
@@ -1307,6 +1323,33 @@ export async function startHub({
         });
       }
 
+      // Redacted peer-discovery surface. Returns co-located live peers (same
+      // cwd / worktree) with raw cwd/pid stripped — only label/hash + booleans.
+      if (path === "/synapse/peers" && req.method === "GET") {
+        // formatHostForUrl wraps IPv6 hosts in [...]; a bare `::1` would make
+        // `new URL(req.url, "http://::1")` throw (invalid authority).
+        const query = new URL(req.url, `http://${formatHostForUrl(host)}`)
+          .searchParams;
+        const cwd = query.get("cwd") || "";
+        const worktree = query.get("worktree") || "";
+        const excludeSessionId = query.get("excludeSessionId") || "";
+        // Require at least one non-empty locator. Without it querySessions
+        // already returns [], but short-circuiting keeps the contract explicit
+        // and avoids ever enumerating the registry over the redacted surface.
+        if (!cwd && !worktree) {
+          return writeJson(res, 200, { ok: true, peers: [], ts: Date.now() });
+        }
+        const matches = synapseRegistry.querySessions({
+          cwd,
+          worktree,
+          excludeSessionId,
+        });
+        const peers = matches.map((session) =>
+          projectPeer(session, { cwd, worktree }),
+        );
+        return writeJson(res, 200, { ok: true, peers, ts: Date.now() });
+      }
+
       if (path === "/synapse/register" && req.method === "POST") {
         try {
           const body = await parseBody(req);

package/hub/team/synapse-http.mjs

@@ -1,4 +1,56 @@
-const DEFAULT_SYNAPSE_BASE_URL = "http://127.0.0.1:27888";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const HUB_DEFAULT_PORT = 27888;
+// Same token file as hub/bridge.mjs (HUB_TOKEN_FILE). Kept inline rather than
+// imported so this helper stays dependency-free and byte-identical across the
+// packages/core mirror (which cannot carry relative cross-package imports).
+const HUB_TOKEN_FILE = join(homedir(), ".claude", ".tfx-hub-token");
+
+// In-flight fire-and-forget POSTs. A short-lived caller (the SessionStart hook,
+// which process.exit(0)s immediately after firing register) must be able to
+// flush these before the process dies: Node's process.exit() abandons pending
+// socket I/O, so an un-awaited loopback POST is created but never written.
+// Callers on an exit budget drain this set via drainPendingSynapse() first.
+const inFlightSynapse = new Set();
+
+function normalizeToken(raw) {
+  if (raw == null) return null;
+  const token = String(raw).trim();
+  return token || null;
+}
+
+// Mirrors hub/bridge.mjs:readHubToken — env override first, then the token file.
+// Missing token → null (backward-compatible with token-less hubs).
+function readHubToken() {
+  const envToken = normalizeToken(process.env.TFX_HUB_TOKEN);
+  if (envToken) return envToken;
+  try {
+    return normalizeToken(readFileSync(HUB_TOKEN_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// Wrap IPv6 hosts in [...] so they form a valid URL authority (cf. bridge.mjs).
+function formatHostForUrl(host) {
+  return String(host).includes(":") ? `[${host}]` : host;
+}
+
+// Resolve the hub base URL from env (TFX_HUB_URL / TFX_HUB_PORT) before falling
+// back to the loopback default, so a cascaded / non-default hub port is hit
+// instead of silently posting to 127.0.0.1:27888 and missing the live hub.
+function resolveSynapseBaseUrl() {
+  const envUrl = normalizeToken(process.env.TFX_HUB_URL);
+  if (envUrl) return envUrl.replace(/\/mcp$/, "");
+
+  const envPort = Number.parseInt(String(process.env.TFX_HUB_PORT ?? ""), 10);
+  if (Number.isFinite(envPort) && envPort > 0) {
+    return `http://${formatHostForUrl("127.0.0.1")}:${envPort}`;
+  }
+  return `http://${formatHostForUrl("127.0.0.1")}:${HUB_DEFAULT_PORT}`;
+}
 
 function resolveSynapseFetch(fetchImpl) {
   if (fetchImpl === null) return null;
@@ -19,23 +71,68 @@ export function fireAndForgetSynapse(path, payload, opts = {}) {
   if (!fetchImpl) return false;
 
   try {
-    const url = new URL(
-      path,
-      opts.baseUrl || DEFAULT_SYNAPSE_BASE_URL,
-    ).toString();
-    Promise.resolve(
-      fetchImpl(url, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify(payload),
-      }),
-    ).catch(() => {});
+    const baseUrl = opts.baseUrl || resolveSynapseBaseUrl();
+    const url = new URL(path, baseUrl).toString();
+    const headers = { "content-type": "application/json" };
+    // token: false explicitly skips auth; otherwise reuse the hub token so a
+    // token-required hub does not 401 (the failure would be swallowed silently).
+    if (opts.token !== false) {
+      const token =
+        typeof opts.token === "string" && opts.token.trim()
+          ? opts.token.trim()
+          : readHubToken();
+      if (token) headers.Authorization = `Bearer ${token}`;
+    }
+    const init = {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload),
+    };
+    // Optional bounded timeout so callers on a teardown budget (e.g. SessionEnd)
+    // cannot hang the host process if the hub stalls. The timer is unref'd so it
+    // never keeps the event loop (and thus the hook process) alive on its own.
+    let timer = null;
+    const timeoutMs = Number(opts.timeoutMs);
+    if (
+      Number.isFinite(timeoutMs) &&
+      timeoutMs > 0 &&
+      typeof AbortController === "function"
+    ) {
+      const controller = new AbortController();
+      init.signal = controller.signal;
+      timer = setTimeout(() => controller.abort(), timeoutMs);
+      if (typeof timer.unref === "function") timer.unref();
+    }
+    const tracked = Promise.resolve(fetchImpl(url, init))
+      .catch(() => {})
+      .finally(() => {
+        if (timer) clearTimeout(timer);
+        inFlightSynapse.delete(tracked);
+      });
+    inFlightSynapse.add(tracked);
     return true;
   } catch {
     return false;
   }
 }
 
+// Await any in-flight fire-and-forget Synapse POSTs, bounded by timeoutMs so a
+// stalled hub can never hang the caller. The SessionStart hook calls this right
+// before process.exit(0) so the register POST actually flushes to the socket.
+export function drainPendingSynapse(timeoutMs = 1000) {
+  if (inFlightSynapse.size === 0) return Promise.resolve();
+  const settled = Promise.allSettled([...inFlightSynapse]);
+  const ms = Number(timeoutMs);
+  if (!Number.isFinite(ms) || ms <= 0) return settled;
+  return Promise.race([
+    settled,
+    new Promise((resolve) => {
+      const t = setTimeout(resolve, ms);
+      if (typeof t.unref === "function") t.unref();
+    }),
+  ]);
+}
+
 export function registerSynapseSession(meta, opts = {}) {
   return fireAndForgetSynapse("/synapse/register", meta, opts);
 }
@@ -45,11 +142,15 @@ export function heartbeatSynapseSession(
   partialMeta = {},
   opts = {},
 ) {
+  // The live route reads `{ sessionId, partial }` (hub/server.mjs
+  // /synapse/heartbeat → synapseRegistry.heartbeat(sessionId, partial)), so the
+  // helper must nest the meta under `partial` rather than spreading it top-level.
   return fireAndForgetSynapse(
     "/synapse/heartbeat",
     {
       sessionId,
-      ...(partialMeta && typeof partialMeta === "object" ? partialMeta : {}),
+      partial:
+        partialMeta && typeof partialMeta === "object" ? partialMeta : {},
     },
     opts,
   );