triflux 10.36.0 → 10.37.0

package/bin/tfx-live.mjs

@@ -5,6 +5,9 @@ import { homedir, tmpdir } from "node:os";
 import { join as pathJoin, resolve as pathResolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+import { runHygiene } from "../cto/hygiene.mjs";
+import { notifyCtoHygieneOnce } from "../cto/hygiene-notify.mjs";
+import { createNotifier } from "../hub/team/notify.mjs";
 import {
   escapePwshSingleQuoted as escapeRemotePwshSingleQuoted,
   probeRemoteEnv as probeRemoteHostEnv,
@@ -51,6 +54,8 @@ function usage() {
     "  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.",
+    "  tfx-live cto-hygiene-notify --root DIR --state-file PATH [--json]",
+    "    One-shot CTO hygiene dry-run notification: sends only when actionable hygiene state changes; no polling or apply/steward lock.",
   ].join("\n");
 }
 
@@ -1113,7 +1118,20 @@ async function hasTmuxSession(adapter, opts) {
 
 function daemonProbeUnavailableReason(probe, targetAttachable) {
   if (targetAttachable) return null;
-  if (!probe?.ok) return probe?.reason ?? "probe-failed";
+  if (!probe?.ok) {
+    const candidateCodes = Array.isArray(probe?.raw?.candidateResults)
+      ? probe.raw.candidateResults
+          .map((entry) => entry?.errorCode)
+          .filter(Boolean)
+      : [];
+    if (candidateCodes.includes("stale-control-socket")) {
+      return "stale-control-socket";
+    }
+    if (candidateCodes.includes("daemon-dir-missing")) {
+      return "daemon-dir-missing";
+    }
+    return probe?.reason ?? "probe-failed";
+  }
   return "target-not-found";
 }
 
@@ -2194,6 +2212,45 @@ function printJson(value) {
   process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 
+async function ctoHygieneNotify(flags) {
+  const rootDir = flags.root ? pathResolve(flags.root) : process.cwd();
+  const stateFile = flags["state-file"]
+    ? pathResolve(flags["state-file"])
+    : pathJoin(rootDir, ".triflux", "cto-hygiene-notify-state.json");
+
+  const projection = await runHygiene(["--dry-run", "--json"], {
+    rootDir,
+    dryRun: true,
+    json: false,
+    stdout: {
+      write() {
+        return true;
+      },
+    },
+  });
+
+  const notifier = createNotifier({ stdout: process.stderr });
+  const result = await notifyCtoHygieneOnce(projection, {
+    notifier,
+    stateFile,
+  });
+  const payload = {
+    ok: true,
+    stateFile,
+    counts: projection.counts,
+    ...result,
+  };
+
+  if (flags.json) {
+    printJson(payload);
+    return;
+  }
+
+  process.stdout.write(
+    `cto hygiene notify: ${payload.reason} (${payload.hash})\n`,
+  );
+}
+
 async function main() {
   const { command, flags } = parseCli(process.argv.slice(2));
 
@@ -2220,6 +2277,8 @@ async function main() {
     await peer(flags);
   } else if (command === "orchestrate") {
     await orchestrate(flags);
+  } else if (command === "cto-hygiene-notify") {
+    await ctoHygieneNotify(flags);
   } else {
     throw new Error(`Unknown subcommand: ${command}\n${usage()}`);
   }
@@ -2229,6 +2288,7 @@ export {
   ADAPTERS,
   buildRemoteLiveCommand,
   callRemoteLive,
+  ctoHygieneNotify,
   extractAssistantResponse,
   extractClaudeCompletedTaskListResponse,
   hasClaudeCompletedTaskListResponse,

package/bin/triflux.mjs

@@ -499,12 +499,13 @@ const CLI_COMMAND_SCHEMAS = Object.freeze({
     },
   },
   cto: {
-    usage: "tfx cto <collect|status|dashboard> [options]",
+    usage: "tfx cto <collect|status|dashboard|hygiene> [options]",
     description: "repo-local authority layer console",
     subcommands: {
       collect: "refresh .triflux/lake/current.json from authority sources",
       status: "print the current authority summary",
       dashboard: "render the CTO console dashboard, optionally with --watch",
+      hygiene: "project CTO hygiene counts and actionable dry-run rows",
     },
   },
   multi: {
@@ -2708,6 +2709,7 @@ function statusBadge(status) {
     case "missing":
     case "missing-file":
     case "warning":
+    case "skipped":
       return `${YELLOW}${status}${RESET}`;
     case "mismatch":
     case "invalid":
@@ -2730,6 +2732,7 @@ function buildMcpStatusRows(statusInfo) {
       else if (row.status === "mismatch")
         detail = `expected ${row.expectedUrl || row.expectedCommand}`;
       else if (row.status === "invalid-config") detail = "parse error";
+      else if (row.status === "skipped") detail = row.message || "skipped";
       else if (row.status === "stdio") detail = "configured as stdio";
       return [
         row.name,

package/cto/dashboard.mjs

@@ -196,6 +196,65 @@ function renderLedger(entries) {
   `;
 }
 
+const HYGIENE_METRICS = Object.freeze([
+  ["active_tasks", "Active tasks"],
+  ["stale_sessions", "Stale sessions"],
+  ["orphan_worktrees", "Orphan worktrees"],
+  ["superseded_checkpoints", "Superseded checkpoints"],
+  ["unknown_owner", "Unknown owners"],
+]);
+
+function hygieneCount(hygiene, key) {
+  const value = Number(hygiene?.[key] || 0);
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+function renderHygiene(hygiene) {
+  if (!hygiene || typeof hygiene !== "object") return "";
+  const actions = Array.isArray(hygiene.actions)
+    ? hygiene.actions.slice(0, 5)
+    : [];
+  const actionCount = hygieneCount(hygiene, "action_count") || actions.length;
+  return `
+    <section class="panel">
+      <h2>Hygiene</h2>
+      <table>
+        <tbody>
+          ${HYGIENE_METRICS.map(
+            ([key, label]) => `
+              <tr>
+                <th>${escapeHtml(label)}</th>
+                <td>${hygieneCount(hygiene, key)}</td>
+              </tr>
+            `,
+          ).join("")}
+          <tr>
+            <th>Actions</th>
+            <td>${actionCount}</td>
+          </tr>
+        </tbody>
+      </table>
+      ${
+        actions.length
+          ? `<ul class="items">
+              ${actions
+                .map(
+                  (action) => `
+                    <li>
+                      <strong>${escapeHtml(formatValue(action?.id || action?.kind, "item"))}</strong>
+                      <span>${escapeHtml(formatValue(action?.action || action?.kind, "review"))}</span>
+                      <em>${escapeHtml(formatValue(action?.status, "action"))}</em>
+                    </li>
+                  `,
+                )
+                .join("")}
+            </ul>`
+          : `<p class="empty">No hygiene actions reported.</p>`
+      }
+    </section>
+  `;
+}
+
 function pageShell(title, body) {
   return `<!doctype html>
 <html lang="en">
@@ -326,6 +385,7 @@ function renderCurrentHtml(current) {
           <h2>Swarm Shards</h2>
           ${renderShards(shards)}
         </section>
+        ${renderHygiene(current.hygiene || current.summary?.hygiene)}
         <section class="panel">
           <h2>Recent Ledger</h2>
           ${renderLedger(Array.isArray(current.ledger_tail) ? current.ledger_tail : [])}

package/cto/events.mjs

@@ -0,0 +1,222 @@
+import {
+  appendFileSync,
+  closeSync,
+  mkdirSync,
+  openSync,
+  unlinkSync,
+} from "node:fs";
+import { basename, join } from "node:path";
+
+export const CTO_EVENT_SCHEMA_VERSION = "cto-event.v1";
+export const DEFAULT_CTO_EVENT_SOURCE = "tfx_cto_event";
+
+export const CTO_EVENT_TYPES = Object.freeze([
+  "session_started",
+  "session_heartbeat",
+  "session_stale",
+  "checkpoint_saved",
+  "checkpoint_restored",
+  "task_claimed",
+  "task_completed",
+  "pr_created",
+  "pr_merged_or_closed",
+  "worktree_created",
+  "worktree_removed",
+  "hygiene_applied",
+]);
+
+export const CTO_HYGIENE_STATUSES = Object.freeze([
+  "active",
+  "idle",
+  "stale",
+  "superseded",
+  "orphaned",
+  "completed",
+  "blocked",
+  "unknown_owner",
+  "hidden",
+  "needs_attention",
+]);
+
+const EVENT_TYPE_SET = new Set(CTO_EVENT_TYPES);
+const STATUS_SET = new Set(CTO_HYGIENE_STATUSES);
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function maybeString(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+
+function toIsoTime(value) {
+  if (typeof value === "string" && value.trim()) return value;
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return new Date(value).toISOString();
+  }
+  return new Date().toISOString();
+}
+
+function shortHash(value) {
+  const str = String(value ?? "");
+  let h = 5381;
+  for (let i = 0; i < str.length; i += 1) {
+    h = (h * 33) ^ str.charCodeAt(i);
+  }
+  return (h >>> 0).toString(36);
+}
+
+function pathLabel(value) {
+  const str = String(value ?? "").replace(/[/\\]+$/u, "");
+  if (!str) return null;
+  const segments = str.split(/[/\\]+/u);
+  return segments[segments.length - 1] || null;
+}
+
+function normalizeNumericRefs(values) {
+  const rawValues = Array.isArray(values)
+    ? values
+    : values == null
+      ? []
+      : [values];
+  const refs = [];
+  for (const value of rawValues) {
+    const parsed =
+      typeof value === "number" && Number.isInteger(value)
+        ? value
+        : typeof value === "string"
+          ? Number(value.trim().replace(/^#/u, ""))
+          : NaN;
+    if (Number.isInteger(parsed) && parsed > 0 && !refs.includes(parsed)) {
+      refs.push(parsed);
+    }
+  }
+  return refs;
+}
+
+function normalizeActor(actor) {
+  if (!actor || typeof actor !== "object" || Array.isArray(actor)) return null;
+  const normalized = {};
+  for (const key of ["cli", "session_id", "agent_id", "host"]) {
+    const value = maybeString(actor[key]);
+    if (value) normalized[key] = value;
+  }
+  return Object.keys(normalized).length > 0 ? normalized : null;
+}
+
+function putString(target, key, value) {
+  const normalized = maybeString(value);
+  if (normalized) target[key] = normalized;
+}
+
+function defaultSummary(eventType, ref) {
+  if (ref.task_id) return `${eventType} ${ref.task_id}`;
+  if (ref.checkpoint_id) return `${eventType} ${ref.checkpoint_id}`;
+  if (ref.session_id) return `${eventType} ${ref.session_id}`;
+  return eventType;
+}
+
+export function normalizeCtoEvent(input = {}) {
+  const eventType = maybeString(input.event ?? input.event_type);
+  if (!eventType || !EVENT_TYPE_SET.has(eventType)) {
+    throw new Error(`unknown CTO event: ${eventType || "<empty>"}`);
+  }
+
+  const status = maybeString(input.status);
+  if (status && !STATUS_SET.has(status)) {
+    throw new Error(`invalid CTO status: ${status}`);
+  }
+
+  const ts = toIsoTime(input.now ?? input.ts);
+  const ref = {
+    schema_version: CTO_EVENT_SCHEMA_VERSION,
+    event_type: eventType,
+  };
+
+  putString(ref, "session_id", input.session_id);
+  putString(ref, "parent_session_id", input.parent_session_id);
+  putString(ref, "restored_from_session_id", input.restored_from_session_id);
+  putString(ref, "checkpoint_id", input.checkpoint_id);
+  putString(ref, "artifact_path", input.artifact_path);
+  putString(ref, "task_id", input.task_id);
+  putString(ref, "branch", input.branch);
+  putString(ref, "last_seen_at", input.last_seen_at);
+  putString(ref, "stale_reason", input.stale_reason);
+  putString(ref, "hygiene_key", input.hygiene_key);
+  putString(ref, "hygiene_kind", input.hygiene_kind);
+  putString(ref, "hygiene_id", input.hygiene_id);
+  putString(ref, "hygiene_action", input.hygiene_action);
+  if (status) ref.status = status;
+
+  const projectRoot = maybeString(input.project_root);
+  if (projectRoot) {
+    ref.project_root_hash = shortHash(projectRoot);
+    ref.project_root_label = pathLabel(projectRoot) || basename(projectRoot);
+  }
+
+  const worktreePath = maybeString(input.worktree_path ?? input.worktreePath);
+  if (worktreePath) {
+    ref.worktree_path_hash = shortHash(worktreePath);
+    ref.worktree_label = pathLabel(worktreePath) || basename(worktreePath);
+  }
+
+  const issueRefs = normalizeNumericRefs(input.issue_refs ?? input.issueRefs);
+  if (issueRefs.length > 0) ref.issue_refs = issueRefs;
+  const prRefs = normalizeNumericRefs(input.pr_refs ?? input.prRefs);
+  if (prRefs.length > 0) ref.pr_refs = prRefs;
+
+  const actor = normalizeActor(input.actor);
+  if (actor) ref.actor = actor;
+
+  return {
+    ts,
+    event: eventType,
+    source: maybeString(input.source) || DEFAULT_CTO_EVENT_SOURCE,
+    summary: maybeString(input.summary) || defaultSummary(eventType, ref),
+    ref,
+  };
+}
+
+export async function appendCtoEvent(lakeRoot, input, opts = {}) {
+  const event = normalizeCtoEvent(input);
+  const stderr = opts.stderr || process.stderr;
+  const lockRetries = Number.isInteger(opts.lockRetries) ? opts.lockRetries : 3;
+  const lockRetryDelayMs = Number.isFinite(opts.lockRetryDelayMs)
+    ? opts.lockRetryDelayMs
+    : 100;
+
+  mkdirSync(lakeRoot, { recursive: true });
+  const ledgerPath = join(lakeRoot, "ledger.jsonl");
+  const lockPath = join(lakeRoot, "ledger.jsonl.lock");
+  let fd = null;
+
+  for (let attempt = 0; attempt < lockRetries; attempt += 1) {
+    try {
+      fd = openSync(lockPath, "wx", 0o600);
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      if (attempt < lockRetries - 1) await sleep(lockRetryDelayMs);
+    }
+  }
+
+  if (fd === null) {
+    stderr.write(
+      "[tfx cto event] warning: ledger lock timeout; skipped ledger append\n",
+    );
+    return { appended: false, event };
+  }
+
+  try {
+    appendFileSync(ledgerPath, `${JSON.stringify(event)}\n`, "utf8");
+    return { appended: true, event };
+  } finally {
+    closeSync(fd);
+    try {
+      unlinkSync(lockPath);
+    } catch {}
+  }
+}

package/cto/hygiene-notify.mjs

@@ -0,0 +1,170 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+const ACTIONABLE_COUNT_KEYS = Object.freeze([
+  "active_tasks",
+  "stale_sessions",
+  "orphan_worktrees",
+  "superseded_checkpoints",
+  "unknown_owner",
+]);
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, stableValue(value[key])]),
+    );
+  }
+  return value;
+}
+
+function stableJson(value) {
+  return JSON.stringify(stableValue(value));
+}
+
+function normalizeCount(value) {
+  return Number.isFinite(Number(value)) ? Number(value) : 0;
+}
+
+function actionableCounts(projection = {}) {
+  const counts = projection?.counts || {};
+  return Object.fromEntries(
+    ACTIONABLE_COUNT_KEYS.map((key) => [key, normalizeCount(counts[key])]),
+  );
+}
+
+function normalizeRows(rows) {
+  return (Array.isArray(rows) ? rows : [])
+    .map((row) => ({
+      kind: String(row?.kind || ""),
+      id: String(row?.id || ""),
+      status: String(row?.status || ""),
+      action: row?.action == null ? "" : String(row.action),
+      owner: row?.owner == null ? "" : String(row.owner),
+    }))
+    .sort((a, b) =>
+      [a.kind, a.id, a.status, a.action, a.owner]
+        .join("\u0000")
+        .localeCompare(
+          [b.kind, b.id, b.status, b.action, b.owner].join("\u0000"),
+        ),
+    );
+}
+
+export function ctoHygieneStateHash(projection = {}) {
+  const canonical = {
+    counts: actionableCounts(projection),
+    rows: normalizeRows(projection.rows),
+  };
+  return createHash("sha256").update(stableJson(canonical)).digest("hex");
+}
+
+function plural(count, singular, pluralWord = `${singular}s`) {
+  return `${count} ${count === 1 ? singular : pluralWord}`;
+}
+
+function summarizeCounts(counts) {
+  const parts = [];
+  if (counts.active_tasks)
+    parts.push(plural(counts.active_tasks, "active task"));
+  if (counts.stale_sessions)
+    parts.push(plural(counts.stale_sessions, "stale session"));
+  if (counts.orphan_worktrees)
+    parts.push(plural(counts.orphan_worktrees, "orphan worktree"));
+  if (counts.superseded_checkpoints)
+    parts.push(plural(counts.superseded_checkpoints, "superseded checkpoint"));
+  if (counts.unknown_owner)
+    parts.push(plural(counts.unknown_owner, "unknown owner"));
+  return parts;
+}
+
+export function buildCtoHygieneNotification(projection = {}, opts = {}) {
+  const counts = actionableCounts(projection);
+  const actionable = ACTIONABLE_COUNT_KEYS.some((key) => counts[key] > 0);
+  const hash = ctoHygieneStateHash(projection);
+  if (!actionable) {
+    return { actionable, hash, event: null, counts };
+  }
+
+  const summary = `CTO hygiene needs action: ${summarizeCounts(counts).join(", ")}`;
+  return {
+    actionable,
+    hash,
+    counts,
+    event: {
+      type: "ctoHygiene",
+      sessionId: opts.sessionId || "cto-hygiene",
+      summary,
+      timestamp:
+        typeof opts.now === "function"
+          ? opts.now()
+          : (opts.timestamp ?? new Date().toISOString()),
+    },
+  };
+}
+
+async function readState(stateFile) {
+  if (!stateFile) return null;
+  try {
+    return JSON.parse(await readFile(stateFile, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+async function writeState(stateFile, state) {
+  if (!stateFile) return;
+  await mkdir(dirname(stateFile), { recursive: true });
+  await writeFile(stateFile, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+export async function notifyCtoHygieneOnce(projection = {}, opts = {}) {
+  const notification = buildCtoHygieneNotification(projection, opts);
+  const previous = await readState(opts.stateFile);
+  const unchanged = previous?.hash === notification.hash;
+  const checkedAt =
+    typeof opts.now === "function" ? opts.now() : new Date().toISOString();
+
+  if (!notification.actionable) {
+    await writeState(opts.stateFile, {
+      hash: notification.hash,
+      actionable: false,
+      checkedAt,
+    });
+    return {
+      actionable: false,
+      notified: false,
+      reason: "not-actionable",
+      hash: notification.hash,
+    };
+  }
+
+  if (unchanged) {
+    return {
+      actionable: true,
+      notified: false,
+      reason: "unchanged-state",
+      hash: notification.hash,
+    };
+  }
+
+  const notifierResult = await opts.notifier.notify(notification.event);
+  await writeState(opts.stateFile, {
+    hash: notification.hash,
+    actionable: true,
+    notifiedAt: notification.event.timestamp,
+  });
+
+  return {
+    actionable: true,
+    notified: true,
+    reason: "changed-actionable-state",
+    hash: notification.hash,
+    event: notification.event,
+    notify: notifierResult,
+  };
+}