@triflux/remote 10.31.0 → 10.33.0

package/cto/current.schema.json

@@ -0,0 +1,181 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://triflux.local/schemas/cto/current.schema.json",
+  "title": "Triflux CTO Lake Current Authority State",
+  "description": "Contract for .triflux/lake/current.json. .triflux/lake is a triflux-owned, namespace-neutral cross-agent rollup for durable artifacts across Claude, Codex/OMX, OMC, AGY, gstack, gbrain, and Triflux state. It reads and aggregates .omx/ultragoal and .omc/ultragoal execution ledgers without replacing or duplicating their authority. ledger.jsonl and sources.json companion contracts are documented in $defs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "generated_at",
+    "repo",
+    "sources",
+    "summary",
+    "ledger_tail"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "cto-lake.v1"
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "repo": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["root", "branch", "head", "dirty"],
+      "properties": {
+        "root": {
+          "type": "string",
+          "minLength": 1
+        },
+        "branch": {
+          "type": ["string", "null"]
+        },
+        "head": {
+          "type": ["string", "null"]
+        },
+        "dirty": {
+          "type": "boolean"
+        }
+      }
+    },
+    "sources": {
+      "type": "object",
+      "description": "Durable artifact source states only. Live Claude /goal state and AGY internal state are not shell-collectable; a source reports available:false when no shell-readable durable artifact exists.",
+      "additionalProperties": false,
+      "required": [
+        "git",
+        "tfx_hub",
+        "tfx_swarm",
+        "tfx_team",
+        "tfx_synapse",
+        "ultragoal_omx",
+        "ultragoal_omc",
+        "handoffs",
+        "session_vault",
+        "agy",
+        "gbrain"
+      ],
+      "properties": {
+        "git": {
+          "$ref": "#/$defs/sourceState"
+        },
+        "tfx_hub": {
+          "$ref": "#/$defs/sourceState"
+        },
+        "tfx_swarm": {
+          "$ref": "#/$defs/sourceState"
+        },
+        "tfx_team": {
+          "$ref": "#/$defs/sourceState"
+        },
+        "tfx_synapse": {
+          "$ref": "#/$defs/sourceState"
+        },
+        "ultragoal_omx": {
+          "$ref": "#/$defs/sourceState"
+        },
+        "ultragoal_omc": {
+          "$ref": "#/$defs/sourceState"
+        },
+        "handoffs": {
+          "$ref": "#/$defs/sourceState"
+        },
+        "session_vault": {
+          "$ref": "#/$defs/sourceState"
+        },
+        "agy": {
+          "$ref": "#/$defs/sourceState"
+        },
+        "gbrain": {
+          "$ref": "#/$defs/sourceState"
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "description": "Human- and dashboard-oriented synthesized authority summary derived from durable artifacts and live Triflux synapse session status. Phase 1 may add source-derived fields here without changing the top-level contract.",
+      "additionalProperties": true
+    },
+    "ledger_tail": {
+      "type": "array",
+      "description": "Recent append-only .triflux/lake/ledger.jsonl entries copied into current.json for quick status rendering.",
+      "items": {
+        "$ref": "#/$defs/ledgerEntry"
+      }
+    }
+  },
+  "$defs": {
+    "sourceState": {
+      "description": "Every collected durable source reports { available, status, detail, collected_at }. available:false means the surface exposes no shell-readable artifact for this collection pass.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["available", "status", "detail", "collected_at"],
+      "properties": {
+        "available": {
+          "type": "boolean"
+        },
+        "status": {
+          "type": "string"
+        },
+        "detail": {
+          "type": ["string", "object", "array", "null"]
+        },
+        "collected_at": {
+          "type": ["string", "null"],
+          "format": "date-time"
+        }
+      }
+    },
+    "ledgerEntry": {
+      "description": ".triflux/lake/ledger.jsonl is append-only and single-writer. The collector must acquire .triflux/lake/ledger.jsonl.lock before appending so concurrent collectors cannot interleave or corrupt JSONL lines. Each line is one JSON object with this shape.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ts", "event", "source", "summary", "ref"],
+      "properties": {
+        "ts": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "event": {
+          "type": "string"
+        },
+        "source": {
+          "type": "string"
+        },
+        "summary": {
+          "type": "string"
+        },
+        "ref": {
+          "type": ["string", "object", "null"]
+        }
+      }
+    },
+    "sourceRegistry": {
+      "$comment": ".triflux/lake/sources.json is an array of durable source probe registrations.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "kind", "probe", "enabled"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "kind": {
+            "type": "string"
+          },
+          "probe": {
+            "type": ["string", "object"]
+          },
+          "enabled": {
+            "type": "boolean"
+          }
+        }
+      }
+    }
+  }
+}

package/cto/status.mjs

@@ -0,0 +1,260 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const SCHEMA_VERSION = "cto-lake.v1";
+const SYNAPSE_TIMEOUT_MS = 1500;
+
+function hasFlag(args, flag) {
+  return Array.isArray(args) && args.includes(flag);
+}
+
+function writeJson(stdout, payload) {
+  stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function readJson(filePath) {
+  return JSON.parse(readFileSync(filePath, "utf8"));
+}
+
+function firstExisting(paths) {
+  return paths.filter(Boolean).find((path) => existsSync(path)) || null;
+}
+
+function toIsoTime(value) {
+  if (typeof value === "string" && value.trim()) return value;
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return new Date(value).toISOString();
+  }
+  return null;
+}
+
+function normalizeLiveSession(session) {
+  return {
+    sessionId: String(session?.sessionId || ""),
+    host: typeof session?.host === "string" ? session.host : "local",
+    agent_id:
+      typeof session?.agent_id === "string"
+        ? session.agent_id
+        : typeof session?.agentId === "string"
+          ? session.agentId
+          : null,
+    phase:
+      typeof session?.phase === "string"
+        ? session.phase
+        : typeof session?.status === "string"
+          ? session.status
+          : "active",
+    started_at: toIsoTime(
+      session?.started_at ?? session?.startedAt ?? session?.lastHeartbeat,
+    ),
+  };
+}
+
+function normalizeActiveShard(shard) {
+  return {
+    shard_name:
+      typeof shard?.shard_name === "string"
+        ? shard.shard_name
+        : typeof shard?.shardName === "string"
+          ? shard.shardName
+          : typeof shard?.name === "string"
+            ? shard.name
+            : typeof shard?.id === "string"
+              ? shard.id
+              : null,
+    phase:
+      typeof shard?.phase === "string"
+        ? shard.phase
+        : typeof shard?.status === "string"
+          ? shard.status
+          : "active",
+    members: Array.isArray(shard?.members)
+      ? shard.members.map((member) => String(member))
+      : [],
+  };
+}
+
+function normalizeSynapseOverlay(value) {
+  const sessions = Array.isArray(value)
+    ? value
+    : Array.isArray(value?.sessions)
+      ? value.sessions
+      : Array.isArray(value?.live_sessions)
+        ? value.live_sessions
+        : [];
+  const activeShards = Array.isArray(value?.active_shards)
+    ? value.active_shards
+    : Array.isArray(value?.activeShards)
+      ? value.activeShards
+      : [];
+
+  return {
+    live_sessions: sessions
+      .map(normalizeLiveSession)
+      .filter((session) => session.sessionId),
+    active_shards: activeShards.map(normalizeActiveShard),
+  };
+}
+
+function withTimeout(promise, timeoutMs = SYNAPSE_TIMEOUT_MS) {
+  let timer = null;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(
+      () => reject(new Error("synapse read timeout")),
+      timeoutMs,
+    );
+    if (typeof timer.unref === "function") timer.unref();
+  });
+  return Promise.race([Promise.resolve(promise), timeout]).finally(() => {
+    if (timer) clearTimeout(timer);
+  });
+}
+
+async function readSynapseWithRegistry(opts = {}) {
+  const rootDir = opts.rootDir || process.cwd();
+  const persistPath = firstExisting([
+    opts.synapsePersistPath,
+    join(rootDir, ".triflux", "synapse-registry.json"),
+    join(rootDir, ".triflux", "synapse", "registry.json"),
+    join(homedir(), ".claude", "cache", "tfx-hub", "synapse-sessions.json"),
+    join(homedir(), ".claude", "cache", "tfx-hub", "synapse-registry.json"),
+  ]);
+  if (!persistPath) return { sessions: [], active_shards: [] };
+
+  const { createSynapseRegistry } = await import(
+    "../hub/team/synapse-registry.mjs"
+  );
+  const registry = createSynapseRegistry({ persistPath });
+  return { sessions: registry.getActive(), active_shards: [] };
+}
+
+async function readSynapseOverlay(opts) {
+  try {
+    const reader = opts.synapseReader || readSynapseWithRegistry;
+    const raw = await withTimeout(
+      reader({
+        rootDir: opts.rootDir,
+        lakeRoot: opts.lakeRoot,
+        synapsePersistPath: opts.synapsePersistPath,
+      }),
+      opts.synapseTimeoutMs || SYNAPSE_TIMEOUT_MS,
+    );
+    return normalizeSynapseOverlay(raw);
+  } catch {
+    return { live_sessions: [], active_shards: [] };
+  }
+}
+
+// active_shards 의 source 는 live_sessions 와 다르다: live_sessions 는 synapse
+// overlay(실시간 세션)에서, active_shards 는 collect 가 .triflux/swarm-locks.json 을
+// snapshot 한 current.json(sources.tfx_swarm.detail.shards)에서 온다. synapse
+// overlay 가 shard 를 채우는 경로가 생기면 그쪽을 우선하고, 없으면 snapshot 으로
+// fallback 한다(현재 overlay 의 active_shards 는 항상 비어 snapshot 을 쓴다).
+function deriveActiveShards(current, overlay) {
+  // overlay(synapse)가 채운 shard 중 식별 가능한 것만 authoritative 로 본다.
+  // normalizeSynapseOverlay 가 shard_name 을 null 로 정규화한 무효 행이 snapshot
+  // fallback 을 가로채지 않도록 먼저 거른다.
+  const overlayShards = Array.isArray(overlay?.active_shards)
+    ? overlay.active_shards.filter((shard) => shard?.shard_name)
+    : [];
+  if (overlayShards.length > 0) return overlayShards;
+  const shards = current?.sources?.tfx_swarm?.detail?.shards;
+  if (!Array.isArray(shards)) return [];
+  return shards.map(normalizeActiveShard).filter((shard) => shard.shard_name);
+}
+
+function projectStatus(current, overlay) {
+  return {
+    schema_version: current?.schema_version || SCHEMA_VERSION,
+    generated_at: current?.generated_at || null,
+    repo: current?.repo || {},
+    sources: current?.sources || {},
+    summary: current?.summary || {},
+    ledger_tail: Array.isArray(current?.ledger_tail) ? current.ledger_tail : [],
+    live_sessions: overlay.live_sessions,
+    active_shards: deriveActiveShards(current, overlay),
+  };
+}
+
+function countAvailableSources(sources) {
+  const values = Object.values(sources || {});
+  return {
+    available: values.filter((source) => source?.available === true).length,
+    total: values.length,
+  };
+}
+
+function countActiveGoals(current) {
+  const sources = current?.sources || {};
+  return Object.values(sources).reduce((count, source) => {
+    const goals = source?.detail?.active_goals;
+    return count + (Array.isArray(goals) ? goals.length : 0);
+  }, 0);
+}
+
+function formatRepo(repo) {
+  const branch = repo?.branch || "unknown";
+  const head = repo?.head ? String(repo.head).slice(0, 12) : "unknown";
+  const dirty = repo?.dirty ? "dirty" : "clean";
+  return `${repo?.root || "unknown"} (${branch}@${head}, ${dirty})`;
+}
+
+function formatLedgerEntry(entry) {
+  const ts = entry?.ts || "?";
+  const event = entry?.event || "event";
+  const summary = entry?.summary ? ` - ${entry.summary}` : "";
+  return `${ts} ${event}${summary}`;
+}
+
+function renderHumanStatus(status) {
+  const { available, total } = countAvailableSources(status.sources);
+  const activeGoals = countActiveGoals(status);
+  const recent = Array.isArray(status.ledger_tail)
+    ? status.ledger_tail.slice(-2)
+    : [];
+  const lines = [
+    `repo: ${formatRepo(status.repo)}`,
+    `sources: ${available}/${total} available`,
+    `active: ${status.live_sessions.length} sessions, ${status.active_shards.length} shards, ${activeGoals} goals`,
+  ];
+  if (recent.length) {
+    lines.push("ledger:");
+    for (const entry of recent) lines.push(`- ${formatLedgerEntry(entry)}`);
+  } else {
+    lines.push("ledger: no recent events");
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export async function runStatus(args = [], opts = {}) {
+  const rootDir = opts.rootDir || process.cwd();
+  const lakeRoot = opts.lakeRoot || join(rootDir, ".triflux", "lake");
+  const stdout = opts.stdout || process.stdout;
+  const jsonOut = opts.json === true || hasFlag(args, "--json");
+  const currentPath = join(lakeRoot, "current.json");
+
+  if (!existsSync(currentPath)) {
+    const missing = {
+      schema_version: SCHEMA_VERSION,
+      available: false,
+      hint: "run tfx cto collect",
+    };
+    if (jsonOut) writeJson(stdout, missing);
+    else stdout.write("cto status unavailable: run tfx cto collect\n");
+    return missing;
+  }
+
+  const current = readJson(currentPath);
+  const overlay = await readSynapseOverlay({
+    ...opts,
+    rootDir,
+    lakeRoot,
+  });
+  const status = projectStatus(current, overlay);
+
+  if (jsonOut) writeJson(stdout, status);
+  else stdout.write(renderHumanStatus(status));
+
+  return status;
+}

package/hub/hub-lifecycle.mjs

@@ -0,0 +1,242 @@
+// hub/hub-lifecycle.mjs — Hub process lifecycle helpers
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const HUB_DEFAULT_PORT = 27888;
+
+const HUB_PID_FILE = join(homedir(), ".claude", "cache", "tfx-hub", "hub.pid");
+const EPHEMERAL_ENV_KEYS = [
+  "TFX_WORKER_SANDBOX_SCOPE",
+  "TFX_WORKER_INDEX",
+  "TFX_TEAM_TASK_ID",
+  "TFX_TEAM_AGENT_NAME",
+  "TFX_EPHEMERAL",
+];
+
+function parsePositiveInt(value) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+function parsePortFromUrl(value) {
+  try {
+    return parsePositiveInt(new URL(String(value)).port);
+  } catch {
+    return null;
+  }
+}
+
+export function isHubServerCommand(command) {
+  return /(^|[\\/,\s])hub[\\/]server\.mjs(?=$|[\s"'`])/i.test(
+    String(command || ""),
+  );
+}
+
+export function isWorktreeOrEphemeralHubContext({
+  cwd = process.cwd(),
+  env = process.env,
+} = {}) {
+  const normalizedCwd = String(cwd || "").replace(/\\/g, "/");
+  if (
+    normalizedCwd.includes("/.claude/worktrees/") ||
+    normalizedCwd.includes("/.worktrees/") ||
+    normalizedCwd.includes("/.codex-swarm/wt-") ||
+    /(^|\/)wt-[^/]+(?:\/|$)/u.test(normalizedCwd)
+  ) {
+    return true;
+  }
+  return EPHEMERAL_ENV_KEYS.some((key) => String(env?.[key] || "").length > 0);
+}
+
+export function resolveHubPortForContext({
+  port,
+  env = process.env,
+  cwd = process.cwd(),
+  defaultPort = HUB_DEFAULT_PORT,
+} = {}) {
+  const envPort = parsePositiveInt(port) ?? parsePositiveInt(env?.TFX_HUB_PORT);
+  const urlPort = parsePortFromUrl(env?.TFX_HUB_URL);
+  const resolvedPort = envPort ?? urlPort ?? defaultPort;
+  if (
+    resolvedPort !== defaultPort &&
+    isWorktreeOrEphemeralHubContext({ cwd, env })
+  ) {
+    return defaultPort;
+  }
+  return resolvedPort;
+}
+
+export function collectHubProcesses(
+  psOutput = "",
+  { currentPid = process.pid } = {},
+) {
+  const ownPid = Number(currentPid);
+  return String(psOutput)
+    .split(/\r?\n/u)
+    .flatMap((line) => {
+      const match = line.match(/^\s*(\d+)\s+(\d+)\s+(.+)$/u);
+      if (!match) return [];
+      const pid = Number.parseInt(match[1], 10);
+      const ppid = Number.parseInt(match[2], 10);
+      const command = match[3].trim();
+      if (!Number.isFinite(pid) || pid === ownPid) return [];
+      if (!/\bnode(?:\s|$)|\/node(?:\s|$)/u.test(command)) return [];
+      if (!isHubServerCommand(command)) return [];
+      return [{ pid, ppid, command }];
+    });
+}
+
+function readPidFilePid({
+  pidFilePath = HUB_PID_FILE,
+  readFile = readFileSync,
+} = {}) {
+  try {
+    const info = JSON.parse(readFile(pidFilePath, "utf8"));
+    const pid = Number(info?.pid);
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+function findListeningPidsForPort(
+  port = HUB_DEFAULT_PORT,
+  { execFileSyncFn = execFileSync } = {},
+) {
+  try {
+    const output = execFileSyncFn(
+      "lsof",
+      ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"],
+      {
+        encoding: "utf8",
+        timeout: 1000,
+        maxBuffer: 1024 * 1024,
+      },
+    );
+    return String(output)
+      .split(/\r?\n/u)
+      .map((line) => Number.parseInt(line.trim(), 10))
+      .filter((pid) => Number.isFinite(pid) && pid > 0);
+  } catch {
+    return [];
+  }
+}
+
+async function waitForExit(
+  pid,
+  { killFn = process.kill, graceMs = 5000, pollMs = 100 } = {},
+) {
+  const deadline = Date.now() + Math.max(0, graceMs);
+  while (Date.now() <= deadline) {
+    try {
+      killFn(pid, 0);
+    } catch {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+  try {
+    killFn(pid, 0);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+export async function reapExistingHubProcesses({
+  currentPid = process.pid,
+  pidFilePath = HUB_PID_FILE,
+  execFileSyncFn = execFileSync,
+  killFn = process.kill,
+  readPidFileFn,
+  findListeningPidsForPortFn,
+  waitForExitFn,
+  graceMs = 5000,
+  pollMs = 100,
+} = {}) {
+  let output = "";
+  try {
+    output = execFileSyncFn("ps", ["-axo", "pid,ppid,command"], {
+      encoding: "utf8",
+      timeout: 1000,
+      maxBuffer: 1024 * 1024,
+    });
+  } catch {
+    return {
+      candidates: [],
+      reaped: [],
+      preserved: {
+        currentPid: Number(currentPid),
+        pidFilePid: null,
+        defaultPortPids: [],
+      },
+    };
+  }
+
+  const current = Number(currentPid);
+  const pidFileInfo =
+    typeof readPidFileFn === "function"
+      ? readPidFileFn()
+      : { pid: readPidFilePid({ pidFilePath }) };
+  const pidFilePid = parsePositiveInt(pidFileInfo?.pid);
+  const defaultPortPids = [
+    ...new Set(
+      (typeof findListeningPidsForPortFn === "function"
+        ? findListeningPidsForPortFn(HUB_DEFAULT_PORT)
+        : findListeningPidsForPort(HUB_DEFAULT_PORT, { execFileSyncFn })
+      ).map(Number),
+    ),
+  ].filter((pid) => Number.isFinite(pid) && pid > 0);
+
+  const preservedPids = new Set(
+    [current, pidFilePid, ...defaultPortPids].filter(
+      (pid) => Number.isFinite(pid) && pid > 0,
+    ),
+  );
+  const candidates = collectHubProcesses(output, { currentPid: current });
+  const reaped = [];
+  const failed = [];
+
+  for (const processInfo of candidates) {
+    if (preservedPids.has(processInfo.pid)) continue;
+    try {
+      killFn(processInfo.pid, "SIGTERM");
+      const exited =
+        typeof waitForExitFn === "function"
+          ? await waitForExitFn(processInfo.pid, { killFn, graceMs, pollMs })
+          : await waitForExit(processInfo.pid, { killFn, graceMs, pollMs });
+      if (!exited) {
+        try {
+          killFn(processInfo.pid, "SIGKILL");
+        } catch (error) {
+          failed.push({
+            pid: processInfo.pid,
+            signal: "SIGKILL",
+            error: String(error?.message || error),
+          });
+        }
+      }
+      reaped.push(processInfo);
+    } catch (error) {
+      failed.push({
+        pid: processInfo.pid,
+        signal: "SIGTERM",
+        error: String(error?.message || error),
+      });
+    }
+  }
+
+  return {
+    candidates,
+    reaped,
+    failed,
+    preserved: {
+      currentPid: current,
+      pidFilePid,
+      defaultPortPids,
+    },
+  };
+}