@triflux/remote 10.1.0 → 10.26.0

package/hub/team/worker-completion-validator.mjs

@@ -0,0 +1,84 @@
+// hub/team/worker-completion-validator.mjs — Enforce worker completion schema.
+// Issue #115 Lane 1 / F7_worker_did_not_commit.
+//
+// A shard worker MUST emit a completion JSON with `status: "ok"` + a non-empty
+// `commits_made` array. Reporting without committing is the #1 cause of lost
+// swarm work — guarded here before integration trusts the worker.
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import Ajv from "ajv";
+
+const schemaPath = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "schemas",
+  "worker-completion.json",
+);
+const schema = JSON.parse(readFileSync(schemaPath, "utf8"));
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+const compiled = ajv.compile(schema);
+
+/**
+ * Validate a worker completion payload against worker-completion.json.
+ * Returns `{ ok: true }` when the payload satisfies the schema, otherwise
+ * `{ ok: false, reason }` with a short human-readable reason string.
+ *
+ * @param {unknown} payload
+ * @returns {{ ok: boolean, reason?: string }}
+ */
+export function validateWorkerCompletion(payload) {
+  if (payload === null || typeof payload !== "object") {
+    return { ok: false, reason: "payload_not_object" };
+  }
+
+  const valid = compiled(payload);
+  if (!valid) {
+    const firstError = compiled.errors?.[0];
+    const reason = formatError(firstError, payload);
+    return { ok: false, reason };
+  }
+
+  // BUG-G (#130): the schema's if-then only constrains commits_made when
+  // status='ok', so status='failed' payloads pass AJV vacuously. Without
+  // this guard the hypervisor F7 path treats a worker self-reported failure
+  // as a successful completion and integrates phantom shards.
+  if (payload.status === "failed") {
+    const detail =
+      typeof payload.reason === "string" && payload.reason.length > 0
+        ? payload.reason
+        : "unspecified";
+    return { ok: false, reason: `worker_self_reported_failure:${detail}` };
+  }
+
+  return { ok: true };
+}
+
+function formatError(err, payload) {
+  if (!err) return "schema_validation_failed";
+
+  // Map Ajv keywords to short, actionable reasons.
+  if (
+    err.keyword === "required" &&
+    err.params?.missingProperty === "commits_made"
+  ) {
+    return "missing_commits_made";
+  }
+  if (err.keyword === "minItems" && err.instancePath === "/commits_made") {
+    return "empty_commits_made";
+  }
+  if (err.keyword === "enum" && err.instancePath === "/status") {
+    return `invalid_status:${payload?.status ?? "undefined"}`;
+  }
+  if (err.keyword === "type" && err.instancePath === "/commits_made") {
+    return "commits_made_not_array";
+  }
+  if (err.keyword === "required" && err.params?.missingProperty === "status") {
+    return "missing_status";
+  }
+
+  const path = err.instancePath || "(root)";
+  return `${err.keyword}@${path}:${err.message}`;
+}

package/hub/team/worker-sandbox.mjs

@@ -0,0 +1,97 @@
+// 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 hostHome = env.HOME || env.USERPROFILE;
+  if (!env.CODEX_HOME && hostHome) {
+    overlay.CODEX_HOME = join(hostHome, ".codex");
+  }
+
+  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/worker-signal.mjs

@@ -0,0 +1,263 @@
+import { randomUUID } from "node:crypto";
+import * as nodeFs from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+const DEFAULT_TIMEOUT_MS = 600_000;
+const DEFAULT_POLL_MS = 1_000;
+const FALLBACK_RENAME_CODES = new Set(["EACCES", "EEXIST", "EPERM"]);
+const TERMINAL_TYPES = new Set(["done", "error"]);
+
+function assertSignalDir(signalDir) {
+  if (typeof signalDir !== "string" || !signalDir.trim()) {
+    throw new Error("WorkerSignalChannel requires a non-empty signalDir");
+  }
+}
+
+function assertShardId(shardId) {
+  if (typeof shardId !== "string" || !shardId.trim()) {
+    throw new Error("WorkerSignalChannel requires a non-empty shardId");
+  }
+  if (basename(shardId) !== shardId || shardId.includes("\\")) {
+    throw new Error(`Invalid shardId for signal file: ${shardId}`);
+  }
+}
+
+function objectValue(value, field) {
+  if (value == null) return {};
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${field} must be an object`);
+  }
+  return value;
+}
+
+async function readText(filePath, fs) {
+  try {
+    return await fs.readFile(filePath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return "";
+    throw error;
+  }
+}
+
+async function unlinkQuiet(filePath, fs) {
+  try {
+    await fs.unlink(filePath);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+}
+
+async function renameWithRollback(tempPath, targetPath, backupPath, fs) {
+  try {
+    await fs.rename(tempPath, targetPath);
+    return;
+  } catch (error) {
+    if (!FALLBACK_RENAME_CODES.has(error?.code)) throw error;
+  }
+
+  let backup = false;
+  try {
+    await fs.rename(targetPath, backupPath);
+    backup = true;
+    await fs.rename(tempPath, targetPath);
+  } catch (error) {
+    if (backup) {
+      try {
+        await fs.rename(backupPath, targetPath);
+        backup = false;
+      } catch (rollbackError) {
+        error.backupPath = backupPath;
+        error.rollbackError = rollbackError;
+      }
+    } else if (error?.code === "ENOENT") {
+      await fs.rename(tempPath, targetPath);
+      return;
+    }
+    throw error;
+  } finally {
+    if (backup) await unlinkQuiet(backupPath, fs);
+  }
+}
+
+/**
+ * @param {string} filePath
+ * @param {string} line
+ * @param {{fs?: typeof import("node:fs/promises")}} [options]
+ */
+export async function appendSignalLineAtomic(filePath, line, options = {}) {
+  const fs = options.fs ?? nodeFs;
+  const dir = dirname(filePath);
+  const suffix = `${process.pid}.${Date.now()}.${randomUUID()}`;
+  const tempPath = join(dir, `.${basename(filePath)}.${suffix}.tmp`);
+  const backupPath = join(dir, `.${basename(filePath)}.${suffix}.bak`);
+
+  await fs.mkdir(dir, { recursive: true });
+  const current = await readText(filePath, fs);
+
+  try {
+    await fs.writeFile(tempPath, `${current}${line}`, {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+    await renameWithRollback(tempPath, filePath, backupPath, fs);
+  } finally {
+    await unlinkQuiet(tempPath, fs);
+  }
+}
+
+export class WorkerSignalChannel {
+  #pendingWrite = Promise.resolve();
+
+  constructor({
+    shardId,
+    signalDir,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    now,
+  } = {}) {
+    assertShardId(shardId);
+    assertSignalDir(signalDir);
+    this.shardId = shardId;
+    this.signalDir = signalDir;
+    this.timeoutMs = timeoutMs;
+    this.now = now ?? Date.now;
+    this.filePath = join(signalDir, `${shardId}.jsonl`);
+  }
+
+  start() {
+    return this.#write({ type: "start", shardId: this.shardId });
+  }
+
+  heartbeat(meta = {}) {
+    return this.#write({
+      type: "heartbeat",
+      shardId: this.shardId,
+      meta: objectValue(meta, "meta"),
+    });
+  }
+
+  done(payload) {
+    return this.#write({
+      type: "done",
+      shardId: this.shardId,
+      payload: objectValue(payload, "payload"),
+    });
+  }
+
+  error(reason, meta = {}) {
+    if (typeof reason !== "string" || !reason.trim()) {
+      throw new Error("error reason must be a non-empty string");
+    }
+    return this.#write({
+      type: "error",
+      shardId: this.shardId,
+      reason,
+      meta: objectValue(meta, "meta"),
+    });
+  }
+
+  async #write(signal) {
+    const payload = { ...signal, ts: new Date(this.now()).toISOString() };
+    const write = this.#pendingWrite.then(() =>
+      appendSignalLineAtomic(this.filePath, `${JSON.stringify(payload)}\n`),
+    );
+    this.#pendingWrite = write.catch(() => {});
+    return write;
+  }
+
+  static async listen({
+    signalDir,
+    onSignal,
+    abortSignal,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    pollMs = DEFAULT_POLL_MS,
+    now = Date.now,
+  } = {}) {
+    assertSignalDir(signalDir);
+    if (typeof onSignal !== "function") {
+      throw new Error("WorkerSignalChannel.listen requires onSignal callback");
+    }
+
+    const state = {
+      lineCounts: new Map(),
+      lastLiveAt: new Map(),
+      staleShards: new Set(),
+      terminalShards: new Set(),
+    };
+
+    while (!abortSignal?.aborted) {
+      await scanSignalDir(signalDir, state, onSignal);
+      emitStaleSignals(state, timeoutMs, now, onSignal);
+      if (abortSignal?.aborted) break;
+      try {
+        await delay(pollMs, undefined, { signal: abortSignal });
+      } catch (error) {
+        if (error?.name !== "AbortError") throw error;
+      }
+    }
+  }
+}
+
+async function scanSignalDir(signalDir, state, onSignal) {
+  let entries;
+  try {
+    entries = await nodeFs.readdir(signalDir, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+
+  const files = entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+    .map((entry) => join(signalDir, entry.name))
+    .sort();
+  for (const filePath of files) await scanSignalFile(filePath, state, onSignal);
+}
+
+async function scanSignalFile(filePath, state, onSignal) {
+  const raw = await readText(filePath, nodeFs);
+  const lines = raw.split(/\r?\n/).filter(Boolean);
+  const previous = state.lineCounts.get(filePath) ?? 0;
+  for (const line of lines.slice(previous > lines.length ? 0 : previous)) {
+    const signal = JSON.parse(line);
+    onSignal(signal);
+    recordSignal(signal, state);
+  }
+  state.lineCounts.set(filePath, lines.length);
+}
+
+function recordSignal(signal, state) {
+  if (!signal?.shardId || !signal?.ts) return;
+  if (TERMINAL_TYPES.has(signal.type)) {
+    state.terminalShards.add(signal.shardId);
+    return;
+  }
+  if (signal.type === "start" || signal.type === "heartbeat") {
+    const ts = Date.parse(signal.ts);
+    if (Number.isFinite(ts)) {
+      state.lastLiveAt.set(signal.shardId, ts);
+      state.staleShards.delete(signal.shardId);
+    }
+  }
+}
+
+function emitStaleSignals(state, timeoutMs, now, onSignal) {
+  const current = now();
+  for (const [shardId, lastTs] of state.lastLiveAt.entries()) {
+    if (
+      state.terminalShards.has(shardId) ||
+      state.staleShards.has(shardId) ||
+      current - lastTs <= timeoutMs
+    ) {
+      continue;
+    }
+    state.staleShards.add(shardId);
+    onSignal({
+      type: "stale",
+      shardId,
+      ts: new Date(current).toISOString(),
+      lastTs: new Date(lastTs).toISOString(),
+      timeoutMs,
+    });
+  }
+}

package/hub/team/worker-signal.types.d.ts

@@ -0,0 +1,52 @@
+export type WorkerSignal =
+  | { type: "start"; shardId: string; ts: string }
+  | {
+      type: "heartbeat";
+      shardId: string;
+      ts: string;
+      meta?: Record<string, unknown>;
+    }
+  | {
+      type: "done";
+      shardId: string;
+      ts: string;
+      payload: Record<string, unknown>;
+    }
+  | {
+      type: "error";
+      shardId: string;
+      ts: string;
+      reason: string;
+      meta?: Record<string, unknown>;
+    };
+
+export type WorkerSignalEvent =
+  | WorkerSignal
+  | {
+      type: "stale";
+      shardId: string;
+      ts: string;
+      lastTs: string;
+      timeoutMs: number;
+    };
+
+export class WorkerSignalChannel {
+  constructor(options: {
+    shardId: string;
+    signalDir: string;
+    timeoutMs?: number;
+    now?: () => number;
+  });
+  start(): Promise<void>;
+  heartbeat(meta?: Record<string, unknown>): Promise<void>;
+  done(payload: Record<string, unknown>): Promise<void>;
+  error(reason: string, meta?: Record<string, unknown>): Promise<void>;
+  static listen(options: {
+    signalDir: string;
+    onSignal: (signal: WorkerSignalEvent) => void;
+    abortSignal?: AbortSignal;
+    timeoutMs?: number;
+    pollMs?: number;
+    now?: () => number;
+  }): Promise<void>;
+}