triflux 10.20.0 → 10.20.2

package/hub/team/synapse-cli.mjs

@@ -4,7 +4,7 @@
 // so the CLI works even when Hub is offline.
 
 import { execFile } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
@@ -15,6 +15,15 @@ const DEFAULT_REGISTRY_CANDIDATES = [
   ".triflux/synapse/registry.json",
   join(homedir(), ".claude", "cache", "tfx-hub", "synapse-registry.json"),
 ];
+const DEFAULT_SWARM_LOGS_DIR = ".triflux/swarm-logs";
+const STALE_AFTER_MS = 30 * 60 * 1000;
+const STATUS_PRIORITY = {
+  active: 3,
+  running: 3,
+  completed: 2,
+  failed: 2,
+  stale: 1,
+};
 
 function gitExec(args, cwd) {
   return new Promise((res, rej) => {
@@ -55,10 +64,228 @@ function loadRegistrySnapshot(path) {
   }
 }
 
+function parseJsonLines(path) {
+  try {
+    return readFileSync(path, "utf8")
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .flatMap((line) => {
+        try {
+          return [JSON.parse(line)];
+        } catch {
+          return [];
+        }
+      });
+  } catch {
+    return [];
+  }
+}
+
+function normalizeRunId(name) {
+  return String(name || "").replace(/^run-/, "");
+}
+
+function eventTimeMs(event) {
+  const ms = Date.parse(String(event?.ts || ""));
+  return Number.isFinite(ms) ? ms : 0;
+}
+
+function deriveLogStatus(events, lastHeartbeatMs, nowMs) {
+  const stateEvents = events.filter((e) => e.event === "swarm_state");
+  const lastState = stateEvents[stateEvents.length - 1]?.to;
+  if (lastState === "completed" || lastState === "failed") return lastState;
+  if (events.some((e) => e.event === "integration_complete")) {
+    const lastIntegration = [...events]
+      .reverse()
+      .find((e) => e.event === "integration_complete");
+    if (
+      Array.isArray(lastIntegration?.failed) &&
+      lastIntegration.failed.length
+    ) {
+      return "failed";
+    }
+    return "completed";
+  }
+  if (nowMs - lastHeartbeatMs > STALE_AFTER_MS) return "stale";
+  return "active";
+}
+
+function buildLogSession(runDir, nowMs = Date.now()) {
+  const eventPath = join(runDir, "swarm-events.jsonl");
+  if (!existsSync(eventPath)) return null;
+  const events = parseJsonLines(eventPath);
+  if (events.length === 0) return null;
+
+  let statMs = 0;
+  try {
+    statMs = statSync(eventPath).mtimeMs;
+  } catch {}
+
+  const eventMs = events.map(eventTimeMs).filter((ms) => ms > 0);
+  const lastEventMs = eventMs.length ? Math.max(...eventMs) : statMs;
+  const launched = new Set();
+  const completed = new Set();
+  const failed = new Set();
+  for (const event of events) {
+    if (event.event === "shard_launched" && event.shard) {
+      launched.add(event.shard);
+    } else if (event.event === "shard_completed" && event.shard) {
+      completed.add(event.shard);
+    } else if (
+      (event.event === "shard_failed" ||
+        event.event === "shard_launch_failed") &&
+      event.shard
+    ) {
+      failed.add(event.shard);
+    }
+  }
+
+  const runId = normalizeRunId(runDir.split(/[\\/]/).pop());
+  const totalShards = launched.size || completed.size + failed.size;
+  const aliveWorkers = [...launched].filter(
+    (name) => !completed.has(name) && !failed.has(name),
+  ).length;
+
+  return {
+    sessionId: runId,
+    runId,
+    host: "-",
+    branch: "-",
+    dirtyFiles: [],
+    status: deriveLogStatus(events, lastEventMs || nowMs, nowMs),
+    taskSummary: "swarm log run",
+    source: "logs",
+    shards: totalShards ? `${completed.size}/${totalShards}` : "-",
+    workers: totalShards ? `${aliveWorkers} alive` : "-",
+    lastHeartbeat: lastEventMs || null,
+    logDir: runDir,
+  };
+}
+
+export function loadSwarmLogSessions(logsDir, opts = {}) {
+  const nowMs = opts.nowMs ?? Date.now();
+  const root = logsDir || DEFAULT_SWARM_LOGS_DIR;
+  if (!existsSync(root)) return [];
+  try {
+    return readdirSync(root, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && entry.name.startsWith("run-"))
+      .map((entry) => buildLogSession(join(root, entry.name), nowMs))
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function statusPriority(status) {
+  return STATUS_PRIORITY[status] || 0;
+}
+
+function mergeSession(existing, next) {
+  const status =
+    statusPriority(next.status) > statusPriority(existing.status)
+      ? next.status
+      : existing.status;
+  const source =
+    existing.source && next.source && existing.source !== next.source
+      ? "synapse + logs"
+      : existing.source || next.source || "synapse";
+  return {
+    ...next,
+    ...existing,
+    status,
+    source,
+    shards: next.shards || existing.shards,
+    workers: next.workers || existing.workers,
+    lastHeartbeat: Math.max(
+      Number(existing.lastHeartbeat || 0),
+      Number(next.lastHeartbeat || 0),
+    ),
+    logDir: existing.logDir || next.logDir,
+  };
+}
+
+export function mergeRegistryAndLogSessions(registrySessions, logSessions) {
+  const merged = new Map();
+  for (const session of registrySessions) {
+    const key = String(session.runId || session.sessionId || "");
+    if (!key) continue;
+    merged.set(key, {
+      ...session,
+      source: session.source || "synapse",
+      lastHeartbeat: session.lastHeartbeat || null,
+    });
+  }
+  for (const session of logSessions) {
+    const key = String(session.runId || session.sessionId || "");
+    if (!key) continue;
+    const existing = merged.get(key);
+    merged.set(key, existing ? mergeSession(existing, session) : session);
+  }
+  return [...merged.values()].sort((left, right) => {
+    const rightTs = Number(right.lastHeartbeat || 0);
+    const leftTs = Number(left.lastHeartbeat || 0);
+    return rightTs - leftTs;
+  });
+}
+
+function formatAge(ts, nowMs = Date.now()) {
+  if (!Number.isFinite(Number(ts)) || Number(ts) <= 0) return "-";
+  const seconds = Math.max(0, Math.round((nowMs - Number(ts)) / 1000));
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.round(minutes / 60);
+  return `${hours}h ago`;
+}
+
+function hasSwarmLogFields(sessions) {
+  return sessions.some(
+    (s) =>
+      s.source === "logs" ||
+      s.source === "synapse + logs" ||
+      s.runId ||
+      s.shards ||
+      s.workers,
+  );
+}
+
+function formatSwarmStatus(sessions) {
+  const nowMs = Date.now();
+  const rows = [];
+  rows.push(
+    "RUN_ID                 STATUS     SHARDS   WORKERS  LAST_HEARTBEAT  SOURCE",
+  );
+  rows.push(
+    "─────────────────────  ─────────  ───────  ───────  ──────────────  ──────────────",
+  );
+  for (const s of sessions) {
+    const id = String(s.runId || s.sessionId || "?")
+      .padEnd(21)
+      .slice(0, 21);
+    const status = String(s.status || "active")
+      .padEnd(9)
+      .slice(0, 9);
+    const shards = String(s.shards || "-")
+      .padEnd(7)
+      .slice(0, 7);
+    const workers = String(s.workers || "-")
+      .padEnd(7)
+      .slice(0, 7);
+    const heartbeat = formatAge(s.lastHeartbeat, nowMs).padEnd(14).slice(0, 14);
+    const source = String(s.source || "synapse").slice(0, 20);
+    rows.push(
+      `${id}  ${status}  ${shards}  ${workers}  ${heartbeat}  ${source}`,
+    );
+  }
+  return rows.join("\n");
+}
+
 function formatStatus(sessions) {
   if (!sessions.length) {
     return "no active sessions (synapse-registry empty)";
   }
+  if (hasSwarmLogFields(sessions)) return formatSwarmStatus(sessions);
   const rows = [];
   rows.push("SESSION                HOST    BRANCH    DIRTY   STATE    TASK");
   rows.push(
@@ -84,13 +311,22 @@ function formatStatus(sessions) {
 export async function cmdSynapseStatus(args = [], opts = {}) {
   const jsonOut = args.includes("--json") || opts.json;
   const explicit = extractFlag(args, "--registry");
+  const explicitLogsDir = extractFlag(args, "--logs-dir");
   const path = locateRegistryPath(explicit);
-  const sessions = loadRegistrySnapshot(path);
+  const registrySessions = loadRegistrySnapshot(path);
+  const logsDir = explicitLogsDir || DEFAULT_SWARM_LOGS_DIR;
+  const logSessions = loadSwarmLogSessions(logsDir);
+  const sessions = mergeRegistryAndLogSessions(registrySessions, logSessions);
 
   if (jsonOut) {
     process.stdout.write(
       JSON.stringify(
-        { registry: path, count: sessions.length, sessions },
+        {
+          registry: path,
+          logsDir: existsSync(logsDir) ? logsDir : null,
+          count: sessions.length,
+          sessions,
+        },
         null,
         2,
       ) + "\n",
@@ -98,13 +334,14 @@ export async function cmdSynapseStatus(args = [], opts = {}) {
     return;
   }
 
-  if (!path) {
+  if (!path && logSessions.length === 0) {
     process.stdout.write(
-      "no registry file found (looked for .triflux/synapse-registry.json)\n",
+      "no registry or swarm logs found (looked for .triflux/synapse-registry.json and .triflux/swarm-logs)\n",
     );
     return;
   }
-  process.stdout.write(`registry: ${path}\n`);
+  if (path) process.stdout.write(`registry: ${path}\n`);
+  if (logSessions.length > 0) process.stdout.write(`swarm logs: ${logsDir}\n`);
   process.stdout.write(`${formatStatus(sessions)}\n`);
 }
 

package/hub/team/worker-sandbox.mjs

@@ -0,0 +1,93 @@
+// hub/team/worker-sandbox.mjs — local worker HOME/APPDATA isolation helpers
+//
+// Team/swarm workers run untrusted task-specific CLIs. Keep their mutable user
+// state under the worker worktree instead of the operator's real home/appdata,
+// while preserving explicitly brokered auth homes such as CODEX_HOME.
+
+import { mkdirSync } from "node:fs";
+import { join, resolve, win32 } from "node:path";
+
+const SAFE_SEGMENT_RE = /[^a-zA-Z0-9._-]/g;
+
+function safeSegment(value, fallback = "worker") {
+  const raw = String(value ?? "").trim();
+  const cleaned = raw.replace(SAFE_SEGMENT_RE, "_").replace(/^_+|_+$/g, "");
+  return cleaned || fallback;
+}
+
+function isDisabled(env = {}) {
+  return /^(0|false|no|off)$/i.test(String(env.TFX_WORKER_SANDBOX ?? ""));
+}
+
+function windowsHomeParts(home) {
+  const normalized = String(home || "").replace(/\//g, "\\");
+  const match = normalized.match(/^([a-zA-Z]:)(\\.*)$/);
+  if (!match) return null;
+  return { drive: match[1], path: match[2] || "\\" };
+}
+
+function mkdirAll(paths) {
+  for (const path of paths) mkdirSync(path, { recursive: true });
+}
+
+/**
+ * Build a deterministic sandbox home for a local team/swarm worker.
+ *
+ * @param {object} opts
+ * @param {string} [opts.cwd] Worktree/current working directory for the worker.
+ * @param {string} [opts.sessionId] Stable session/member id.
+ * @param {object} [opts.env] Existing env used for opt-out and explicit root.
+ * @param {boolean} [opts.create=true] Create directories eagerly.
+ * @returns {{env: object, root: string|null, home: string|null, disabled: boolean}}
+ */
+export function buildWorkerSandboxEnv(opts = {}) {
+  const env = opts.env && typeof opts.env === "object" ? opts.env : {};
+  if (isDisabled(env)) {
+    return { env: {}, root: null, home: null, disabled: true };
+  }
+
+  const cwd = resolve(opts.cwd || process.cwd());
+  const sessionId = safeSegment(opts.sessionId, "worker");
+  const home = resolve(
+    env.TFX_WORKER_HOME || join(cwd, ".triflux", "worker-home", sessionId),
+  );
+  const appData = join(home, "AppData", "Roaming");
+  const localAppData = join(home, "AppData", "Local");
+  const xdgConfig = join(home, ".config");
+  const xdgCache = join(home, ".cache");
+  const xdgState = join(home, ".local", "state");
+
+  if (opts.create !== false) {
+    mkdirAll([home, appData, localAppData, xdgConfig, xdgCache, xdgState]);
+  }
+
+  const overlay = {
+    TFX_WORKER_HOME: home,
+    HOME: home,
+    USERPROFILE: home,
+    APPDATA: appData,
+    LOCALAPPDATA: localAppData,
+    XDG_CONFIG_HOME: xdgConfig,
+    XDG_CACHE_HOME: xdgCache,
+    XDG_STATE_HOME: xdgState,
+  };
+
+  const winParts =
+    windowsHomeParts(home) ||
+    (process.platform === "win32"
+      ? {
+          drive: win32.parse(home).root.replace(/[\\/]$/, "") || "C:",
+          path:
+            win32
+              .relative(win32.parse(home).root, home)
+              .replace(/\//g, "\\")
+              .replace(/^/, "\\") || "\\",
+        }
+      : null);
+  if (winParts) {
+    overlay.HOMEDRIVE = winParts.drive;
+    overlay.HOMEPATH = winParts.path;
+  }
+
+  return { env: overlay, root: home, home, disabled: false };
+}

package/hub/team/worktree-lifecycle.mjs

@@ -314,7 +314,7 @@ export async function prepareIntegrationBranch({
  * @param {string} [opts.rootDir=process.cwd()]
  * @param {{ checkRebase: Function } | null} [opts.preflight=null] — git-preflight instance
  * @param {{ sessionId: string, workerId?: string } | null} [opts.sessionContext=null]
- * @returns {Promise<{ ok: boolean, headCommit?: string, error?: string, preflight?: object }>}
+ * @returns {Promise<{ ok: boolean, headCommit?: string, strategy?: string, commits?: number, notes?: string, fallbackReason?: string, error?: string, preflight?: object }>}
  */
 export async function rebaseShardOntoIntegration({
   shardBranch,
@@ -355,10 +355,9 @@ export async function rebaseShardOntoIntegration({
   // Backup integration HEAD for rollback
   const backupCommit = await git(["rev-parse", integrationBranch], rootDir);
 
-  // #127: cherry-pick instead of rebase. Rebase fails when shardBranch is
-  // already checked out by a swarm worktree ("branch already used by worktree").
-  // Cherry-pick reads the shard's commits without touching its branch ref,
-  // so worktree contention disappears. Memory: feedback_swarm_cherry_pick.
+  let shaList = [];
+  let ffError = null;
+
   try {
     const log = await git(
       [
@@ -369,19 +368,55 @@ export async function rebaseShardOntoIntegration({
       ],
       rootDir,
     );
-    const shaList = log
+    shaList = log
       .split("\n")
       .map((s) => s.trim())
       .filter(Boolean);
 
     await git(["checkout", integrationBranch], rootDir);
 
+    try {
+      await git(["merge", "--ff-only", shardBranch], rootDir);
+      const headCommit = await git(["rev-parse", "HEAD"], rootDir);
+      return {
+        ok: true,
+        headCommit,
+        strategy: "auto-ff",
+        commits: shaList.length,
+        notes: "linear (merge --ff-only)",
+      };
+    } catch (err) {
+      ffError = err;
+      try {
+        await git(["merge", "--abort"], rootDir);
+      } catch {
+        /* ff-only usually leaves no merge state */
+      }
+      try {
+        await git(["reset", "--hard", backupCommit], rootDir);
+      } catch {
+        /* fallback below will report if cherry-pick also fails */
+      }
+    }
+
+    // #127: cherry-pick fallback instead of branch merge. Rebase/ff paths can
+    // fail when histories diverge or a shard branch is checked out by a swarm
+    // worktree. Cherry-pick reads commits without moving the shard branch ref.
     for (const sha of shaList) {
       await git(["cherry-pick", sha], rootDir);
     }
 
     const headCommit = await git(["rev-parse", "HEAD"], rootDir);
-    return { ok: true, headCommit };
+    return {
+      ok: true,
+      headCommit,
+      strategy: "cherry-pick",
+      commits: shaList.length,
+      fallbackReason: ffError?.message || null,
+      notes: ffError
+        ? `auto-ff failed: ${ffError.message}`
+        : "cherry-pick fallback",
+    };
   } catch (err) {
     try {
       await git(["cherry-pick", "--abort"], rootDir);
@@ -422,7 +457,13 @@ export async function rebaseShardOntoIntegration({
       }
     }
 
-    return { ok: false, error: err.message };
+    return {
+      ok: false,
+      error: err.message,
+      strategy: "failed",
+      commits: shaList.length,
+      fallbackReason: ffError?.message || null,
+    };
   } finally {
     // Always restore caller's branch. Skip if originalBranch is null
     // (detached HEAD case) or already on target.

package/hub/workers/delegator-mcp.mjs

@@ -14,6 +14,7 @@ import * as z from "zod";
 import { resolveBashExecutable } from "../lib/bash-path.mjs";
 import { whichCommand } from "../platform.mjs";
 import { runHeadlessWithCleanup } from "../team/headless.mjs";
+import { buildWorkerSandboxEnv } from "../team/worker-sandbox.mjs";
 import { CodexMcpWorker } from "./codex-mcp.mjs";
 import { GeminiWorker } from "./gemini-worker.mjs";
 
@@ -1182,8 +1183,20 @@ export class DelegatorMcpWorker {
   }
 
   _buildRouteEnv(args) {
-    const env = cloneEnv(this.env);
+    const baseEnv = cloneEnv(this.env);
+    const sandbox = buildWorkerSandboxEnv({
+      cwd: args.cwd || this.cwd,
+      sessionId:
+        args.teamTaskId ||
+        args.teamAgentName ||
+        args.workerIndex ||
+        args.agentType ||
+        "route",
+      env: baseEnv,
+    });
+    const env = { ...baseEnv, ...sandbox.env };
     env.TFX_CLI_MODE = pickRouteMode(args.provider);
+    if (sandbox.root) env.TFX_WORKER_SANDBOX_SCOPE = "delegator-route";
 
     if (args.codexTransport) {
       env.TFX_CODEX_TRANSPORT = args.codexTransport;

package/package.json

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

package/scripts/__tests__/gen-skill-docs.test.mjs

@@ -163,6 +163,8 @@ describe("gen-skill-manifest", () => {
           "  - manifest",
           "argument-hint: <arg>",
           "internal: true",
+          "deprecated: true",
+          "superseded-by: tfx-auto",
           "---",
           "body",
         ].join("\n"),
@@ -180,6 +182,8 @@ describe("gen-skill-manifest", () => {
       assert.deepEqual(manifest.triggers, ["test", "manifest"]);
       assert.equal(manifest.argument_hint, "<arg>");
       assert.equal(manifest.internal, true);
+      assert.equal(manifest.deprecated, true);
+      assert.equal(manifest.superseded_by, "tfx-auto");
     } finally {
       rmSync(root, { recursive: true, force: true });
     }

package/scripts/__tests__/skill-surface.test.mjs

@@ -0,0 +1,61 @@
+import assert from "node:assert/strict";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, it } from "node:test";
+
+import { parseFrontmatter } from "../lib/skill-template.mjs";
+
+const repoRoot = join(import.meta.dirname, "..", "..");
+const skillsDir = join(repoRoot, "skills");
+
+function readSkillFrontmatter(name) {
+  const skillPath = join(skillsDir, name, "SKILL.md");
+  assert.equal(existsSync(skillPath), true, `${name} SKILL.md missing`);
+  return parseFrontmatter(readFileSync(skillPath, "utf8")).data;
+}
+
+function listSkillFrontmatter() {
+  return readdirSync(skillsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .filter((entry) => existsSync(join(skillsDir, entry.name, "SKILL.md")))
+    .map((entry) => readSkillFrontmatter(entry.name))
+    .filter((data) => data.name);
+}
+
+describe("skill surface consolidation (#112)", () => {
+  it("keeps the public core skill surface at or below the target size", () => {
+    const coreSkills = listSkillFrontmatter().filter(
+      (data) => data.internal !== true && data.deprecated !== true,
+    );
+
+    assert.ok(
+      coreSkills.length <= 15,
+      `expected <=15 public core skills, got ${coreSkills.length}: ${coreSkills
+        .map((skill) => skill.name)
+        .sort()
+        .join(", ")}`,
+    );
+  });
+
+  it("marks legacy compatibility aliases as deprecated and superseded", () => {
+    const expectedAliases = [
+      "tfx-autopilot",
+      "tfx-consensus",
+      "tfx-debate",
+      "tfx-fullcycle",
+      "tfx-multi",
+      "tfx-panel",
+      "tfx-persist",
+      "tfx-psmux-rules",
+      "tfx-remote-setup",
+      "tfx-remote-spawn",
+      "tfx-swarm",
+    ];
+
+    for (const name of expectedAliases) {
+      const data = readSkillFrontmatter(name);
+      assert.equal(data.deprecated, true, `${name} must be deprecated`);
+      assert.ok(data["superseded-by"], `${name} must declare superseded-by`);
+    }
+  });
+});

package/scripts/gen-skill-manifest.mjs

@@ -25,6 +25,9 @@ function extractManifest(skillMdContent) {
   if (data["argument-hint"]) manifest.argument_hint = data["argument-hint"];
   if (data.internal === true || data.internal === "true")
     manifest.internal = true;
+  if (data.deprecated === true || data.deprecated === "true")
+    manifest.deprecated = true;
+  if (data["superseded-by"]) manifest.superseded_by = data["superseded-by"];
 
   return manifest;
 }

package/scripts/lib/skill-template.mjs

@@ -360,6 +360,8 @@ export function parseFrontmatterWithManifest(source, skillDir) {
   if (manifest.triggers) merged.triggers = manifest.triggers;
   if (manifest.argument_hint) merged["argument-hint"] = manifest.argument_hint;
   if (manifest.internal != null) merged.internal = manifest.internal;
+  if (manifest.deprecated != null) merged.deprecated = manifest.deprecated;
+  if (manifest.superseded_by) merged["superseded-by"] = manifest.superseded_by;
 
   return { data: merged, body };
 }