@triflux/remote 10.28.1 → 10.30.0

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 "@triflux/core/hub/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,73 @@ 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;
+  let timeout = null;
+  const timeoutPromise = new Promise((resolve) => {
+    // Keep this timer ref'ed: drainPendingSynapse() is awaited specifically
+    // to hold the process open until either in-flight POSTs settle or the
+    // bounded drain budget expires. An unref'ed timer can let Node's test
+    // runner/process exit before the Promise resolves when no other handles
+    // remain.
+    timeout = setTimeout(resolve, ms);
+  });
+  return Promise.race([settled, timeoutPromise]).finally(() => {
+    if (timeout) clearTimeout(timeout);
+  });
+}
+
 export function registerSynapseSession(meta, opts = {}) {
   return fireAndForgetSynapse("/synapse/register", meta, opts);
 }
@@ -45,11 +147,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,
   );

package/hub/team/synapse-registry.mjs

@@ -5,12 +5,59 @@ const DEFAULT_LOCAL_HEARTBEAT_INTERVAL_MS = 5_000;
 const DEFAULT_LOCAL_TIMEOUT_MS = 30_000;
 const DEFAULT_REMOTE_HEARTBEAT_INTERVAL_MS = 15_000;
 const DEFAULT_REMOTE_TIMEOUT_MS = 90_000;
+// Interactive (Claude/Codex) sessions idle for long stretches; a 30s local
+// timeout produces stale false-positives. 5-minute TTL + an `idle` state
+// distinguishes "alive but inactive" from "presumed dead".
+const DEFAULT_INTERACTIVE_HEARTBEAT_INTERVAL_MS = 60_000;
+const DEFAULT_INTERACTIVE_TIMEOUT_MS = 300_000;
+
+const VALID_SESSION_KINDS = new Set(["interactive", "headless"]);
 
 function normalizeSessionId(sessionId) {
   if (sessionId == null) return "";
   return String(sessionId).trim();
 }
 
+function normalizeSessionKind(raw) {
+  return VALID_SESSION_KINDS.has(raw) ? raw : "headless";
+}
+
+// A session is "live" while active OR idle. Idle is an interactive session that
+// missed its heartbeat interval but is still under the TTL — alive but inactive,
+// not presumed dead. getActive() and querySessions() share this single predicate
+// so the liveness contract can't drift: getActive() feeds git-preflight's
+// dirty-file conflict guard, so dropping idle there would hide a still-live
+// interactive session's claimed paths from that safety check.
+function isLiveStatus(status) {
+  return status === "active" || status === "idle";
+}
+
+// Non-secret co-location fingerprint: a short, stable, non-reversible hash of a
+// path so peers can correlate co-located sessions without leaking the raw
+// filesystem path (cf. AccountBroker redaction). This is NOT a security boundary
+// — the boundary is `cwdLabel` (basename only). Treat the hash as an opaque
+// correlation token, not as a secret.
+function shortHash(value) {
+  const str = String(value ?? "");
+  let h = 5381;
+  for (let i = 0; i < str.length; i++) {
+    h = (h * 33) ^ str.charCodeAt(i);
+  }
+  return (h >>> 0).toString(36);
+}
+
+// Last path segment of a directory, used as a human-readable label in redacted
+// peer projections. Separator-agnostic on purpose: `node:path`.basename() is
+// platform-dependent, so on POSIX a Windows path like `C:\Users\Alice\secret`
+// would NOT be split and the full path would leak as the label. Splitting on
+// either separator redacts both path styles regardless of host platform.
+function pathLabel(value) {
+  const str = String(value ?? "").replace(/[/\\]+$/, "");
+  if (!str) return "";
+  const segments = str.split(/[/\\]+/);
+  return segments[segments.length - 1] || "";
+}
+
 function cloneSession(session) {
   return {
     ...session,
@@ -24,6 +71,13 @@ function sanitizeSession(raw, fallbackSessionId = "") {
   const sessionId = normalizeSessionId(raw?.sessionId ?? fallbackSessionId);
   if (!sessionId) return null;
 
+  const status =
+    raw?.status === "stale" ||
+    raw?.status === "expired" ||
+    raw?.status === "idle"
+      ? raw.status
+      : "active";
+
   return {
     sessionId,
     host: typeof raw?.host === "string" ? raw.host : "local",
@@ -33,11 +87,39 @@ function sanitizeSession(raw, fallbackSessionId = "") {
     taskSummary: typeof raw?.taskSummary === "string" ? raw.taskSummary : "",
     lastHeartbeat:
       typeof raw?.lastHeartbeat === "number" ? raw.lastHeartbeat : Date.now(),
-    status:
-      raw?.status === "stale" || raw?.status === "expired"
-        ? raw.status
-        : "active",
+    status,
     isRemote: Boolean(raw?.isRemote),
+    // Additive fields (peer-discovery). Defaults keep pre-existing persist rows
+    // (no cwd/pid/sessionKind) loading cleanly — no persist version bump needed.
+    cwd: typeof raw?.cwd === "string" ? raw.cwd : "",
+    pid: typeof raw?.pid === "number" ? raw.pid : null,
+    sessionKind: normalizeSessionKind(raw?.sessionKind),
+  };
+}
+
+// Pure redacted projection of a session for the peer-discovery route. Raw
+// `cwd`/`pid` and `dirtyFiles` are NEVER exposed; only label/hash + booleans
+// computed against the caller's query args (cf. AccountBroker.publicSnapshot).
+export function projectPeer(session, query = {}) {
+  const cwd = typeof session?.cwd === "string" ? session.cwd : "";
+  const worktreePath =
+    typeof session?.worktreePath === "string" ? session.worktreePath : "";
+  const queryCwd = typeof query?.cwd === "string" ? query.cwd : "";
+  const queryWorktree =
+    typeof query?.worktree === "string" ? query.worktree : "";
+
+  return {
+    sessionId: typeof session?.sessionId === "string" ? session.sessionId : "",
+    branch: typeof session?.branch === "string" ? session.branch : "",
+    sessionKind: normalizeSessionKind(session?.sessionKind),
+    status: typeof session?.status === "string" ? session.status : "active",
+    host: typeof session?.host === "string" ? session.host : "local",
+    isRemote: Boolean(session?.isRemote),
+    sameCwd: Boolean(queryCwd) && cwd === queryCwd,
+    sameWorktree: Boolean(queryWorktree) && worktreePath === queryWorktree,
+    cwdLabel: pathLabel(cwd),
+    cwdHash: cwd ? shortHash(cwd) : "",
+    worktreeLabel: pathLabel(worktreePath),
   };
 }
 
@@ -49,11 +131,14 @@ export function createSynapseRegistry(opts = {}) {
     localTimeoutMs = DEFAULT_LOCAL_TIMEOUT_MS,
     remoteHeartbeatIntervalMs = DEFAULT_REMOTE_HEARTBEAT_INTERVAL_MS,
     remoteTimeoutMs = DEFAULT_REMOTE_TIMEOUT_MS,
+    interactiveHeartbeatIntervalMs = DEFAULT_INTERACTIVE_HEARTBEAT_INTERVAL_MS,
+    interactiveTimeoutMs = DEFAULT_INTERACTIVE_TIMEOUT_MS,
   } = opts;
 
   const sessions = new Map();
   const monitors = new Map();
   const staleCallbacks = new Set();
+  const idleCallbacks = new Set();
   const removedCallbacks = new Set();
 
   function now() {
@@ -61,12 +146,16 @@ export function createSynapseRegistry(opts = {}) {
   }
 
   function intervalFor(session) {
+    if (session.sessionKind === "interactive") {
+      return interactiveHeartbeatIntervalMs;
+    }
     return session.isRemote
       ? remoteHeartbeatIntervalMs
       : localHeartbeatIntervalMs;
   }
 
   function timeoutFor(session) {
+    if (session.sessionKind === "interactive") return interactiveTimeoutMs;
     return session.isRemote ? remoteTimeoutMs : localTimeoutMs;
   }
 
@@ -130,6 +219,21 @@ export function createSynapseRegistry(opts = {}) {
     }
   }
 
+  function notifyIdle(session) {
+    const clone = cloneSession(session);
+    emitter?.emit("synapse.session.idle", {
+      sessionId: session.sessionId,
+      session: clone,
+    });
+    for (const callback of idleCallbacks) {
+      try {
+        callback(clone);
+      } catch {
+        /* no-op */
+      }
+    }
+  }
+
   function notifyRemoved(session) {
     const clone = cloneSession(session);
     emitter?.emit("synapse.session.removed", {
@@ -156,12 +260,30 @@ export function createSynapseRegistry(opts = {}) {
       if (!current) return;
 
       const elapsedMs = now() - current.lastHeartbeat;
-      if (elapsedMs > timeoutFor(current) && current.status !== "stale") {
-        const staled = { ...current, status: "stale" };
-        sessions.set(sessionId, staled);
+      if (elapsedMs > timeoutFor(current)) {
+        if (current.status !== "stale") {
+          const staled = { ...current, status: "stale" };
+          sessions.set(sessionId, staled);
+          schedulePersist();
+          setImmediate(() => {
+            if (!destroyed) notifyStale(staled);
+          });
+        }
+        return;
+      }
+
+      // Interactive sessions that miss the heartbeat interval but are still
+      // under the TTL are "alive but inactive" (idle), not "presumed dead".
+      if (
+        current.sessionKind === "interactive" &&
+        current.status === "active" &&
+        elapsedMs > intervalFor(current)
+      ) {
+        const idled = { ...current, status: "idle" };
+        sessions.set(sessionId, idled);
         schedulePersist();
         setImmediate(() => {
-          if (!destroyed) notifyStale(staled);
+          if (!destroyed) notifyIdle(idled);
         });
       }
     }, intervalFor(session));
@@ -185,7 +307,14 @@ export function createSynapseRegistry(opts = {}) {
       return { ok: false, sessionId, reason: "invalid_id" };
     }
 
-    if (sessions.has(sessionId)) {
+    // A live row (active/idle) means a concurrent session already holds this id
+    // — reject (LOCKED #5). A stale/expired row is a dead remnant of the SAME
+    // session resuming: Claude Code re-fires SessionStart with the same
+    // session_id on resume/clear/compact, so fall through and re-register
+    // (revive) it. Otherwise the resumed-but-live session stays stale forever
+    // and vanishes from peer-discovery AND git-preflight's dirty-file guard.
+    const existing = sessions.get(sessionId);
+    if (existing && isLiveStatus(existing.status)) {
       console.warn(
         "[synapse-registry] duplicate registration rejected:",
         sessionId,
@@ -252,6 +381,9 @@ export function createSynapseRegistry(opts = {}) {
       if (typeof partialMeta.isRemote === "boolean") {
         updated.isRemote = partialMeta.isRemote;
       }
+      if (typeof partialMeta.cwd === "string") updated.cwd = partialMeta.cwd;
+      if (typeof partialMeta.pid === "number") updated.pid = partialMeta.pid;
+      // sessionKind is set at register time and immutable on heartbeat.
     }
 
     sessions.set(normalized, updated);
@@ -270,8 +402,11 @@ export function createSynapseRegistry(opts = {}) {
   }
 
   function getActive() {
+    // Live = active or idle. git-preflight uses this to detect other live
+    // sessions whose dirty files would conflict; an idle interactive session is
+    // still live (process alive, dirty files on disk) and must stay visible.
     return [...sessions.values()]
-      .filter((session) => session.status === "active")
+      .filter((session) => isLiveStatus(session.status))
       .map((session) => cloneSession(session));
   }
 
@@ -286,11 +421,51 @@ export function createSynapseRegistry(opts = {}) {
     return session ? cloneSession(session) : null;
   }
 
+  // Peer-discovery primitive: returns sessions sharing the caller's cwd OR
+  // worktree, excluding the caller's own session. Only live peers (active/idle)
+  // are returned — stale/expired rows are presumed dead and omitted.
+  //
+  // SECURITY: at least one non-empty locator (cwd or worktree) is REQUIRED. An
+  // empty filter would otherwise return every active/idle session, turning the
+  // redacted peer surface into a full-registry enumeration (session ids/branches/
+  // labels/hashes). With no usable locator we return [] rather than leak.
+  //
+  // Matching is disjunctive (cwd OR worktreePath): a peer in the same worktree
+  // but a different subdirectory shares the worktree locator even though its cwd
+  // differs, and a conjunctive (AND) match would wrongly drop it.
+  function querySessions(filter = {}) {
+    const wantCwd = typeof filter?.cwd === "string" ? filter.cwd : "";
+    const wantWorktree =
+      typeof filter?.worktree === "string" ? filter.worktree : "";
+    const excludeId = normalizeSessionId(filter?.excludeSessionId);
+
+    // Require at least one non-empty locator — never enumerate the whole registry.
+    if (!wantCwd && !wantWorktree) return [];
+
+    return [...sessions.values()]
+      .filter((session) => {
+        if (!isLiveStatus(session.status)) {
+          return false;
+        }
+        if (excludeId && session.sessionId === excludeId) return false;
+        const cwdMatch = Boolean(wantCwd) && session.cwd === wantCwd;
+        const worktreeMatch =
+          Boolean(wantWorktree) && session.worktreePath === wantWorktree;
+        return cwdMatch || worktreeMatch;
+      })
+      .map((session) => cloneSession(session));
+  }
+
   function onStale(callback) {
     if (typeof callback !== "function") return;
     staleCallbacks.add(callback);
   }
 
+  function onIdle(callback) {
+    if (typeof callback !== "function") return;
+    idleCallbacks.add(callback);
+  }
+
   function onRemoved(callback) {
     if (typeof callback !== "function") return;
     removedCallbacks.add(callback);
@@ -321,7 +496,9 @@ export function createSynapseRegistry(opts = {}) {
     getActive,
     getAll,
     getSession,
+    querySessions,
     onStale,
+    onIdle,
     onRemoved,
     snapshot,
     destroy,