triflux 10.41.1 → 10.43.0

package/cto/hygiene.mjs

@@ -11,8 +11,9 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
-
+import { getCtoHygieneApplyMode } from "../hub/lib/cto-env.mjs";
 import { appendCtoEvent } from "./events.mjs";
+import { applyHygieneArchiveActions } from "./hygiene-actions.mjs";
 import { resolveLakeRootDir } from "./lake-root.mjs";
 
 const COUNT_KEYS = [
@@ -178,6 +179,18 @@ function rowFrom(kind, id, status, entry, ref, action) {
   if (entry?.summary) row.summary = String(entry.summary);
   if (action) row.action = action;
   if (action && !hasKnownOwner(ref)) row.owner = "unknown";
+  if (typeof ref?.artifact_path === "string" && ref.artifact_path.trim()) {
+    row.artifact_path = ref.artifact_path.trim();
+  }
+  if (
+    typeof ref?.project_root_hash === "string" &&
+    ref.project_root_hash.trim()
+  ) {
+    row.project_root_hash = ref.project_root_hash.trim();
+  }
+  if (typeof ref?.session_id === "string" && ref.session_id.trim()) {
+    row.session_id = ref.session_id.trim();
+  }
   return row;
 }
 
@@ -517,17 +530,52 @@ function isApplicableRow(row) {
   return Boolean(row?.action) || APPLICABLE_STATUSES.has(row?.status);
 }
 
+const ARCHIVE_ACK_STATUSES = new Set(["archived", "already_archived"]);
+
+function hygieneApplyActor(opts = {}) {
+  const actor = { cli: "tfx cto hygiene --apply" };
+  if (typeof opts.actorSessionId === "string" && opts.actorSessionId.trim()) {
+    actor.session_id = opts.actorSessionId.trim();
+  }
+  return actor;
+}
+
 async function applyHygieneRows({
   rootDir,
   lakeRoot,
   projection,
   steward,
+  active,
+  approvals,
   opts,
 }) {
   const rows = projection.rows.filter(isApplicableRow);
   const appended = [];
   const now = opts.now || new Date().toISOString();
+  const actions = await applyHygieneArchiveActions({
+    rootDir,
+    lakeRoot,
+    projection: { ...projection, rows },
+    dryRun: false,
+    now,
+    applyMode: opts.applyMode || getCtoHygieneApplyMode(),
+    active,
+    humanAck: opts.humanAck,
+    humanGate: opts.humanGate,
+    actorSessionId: opts.actorSessionId,
+    approvals,
+    fsOps: opts.fsOps,
+  });
+  const operationByKey = new Map(
+    (actions.operations || []).map((operation) => [
+      operation.hygiene_key,
+      operation,
+    ]),
+  );
   for (const row of rows) {
+    const hygieneKey = hygieneKeyForRow(row);
+    const operation = operationByKey.get(hygieneKey);
+    if (operation && !ARCHIVE_ACK_STATUSES.has(operation.status)) continue;
     const result = await appendCtoEvent(
       lakeRoot,
       {
@@ -536,12 +584,12 @@ async function applyHygieneRows({
         source: "tfx_cto_hygiene_apply",
         project_root: rootDir,
         status: row.status,
-        hygiene_key: hygieneKeyForRow(row),
+        hygiene_key: hygieneKey,
         hygiene_kind: row.kind,
         hygiene_id: row.id,
         hygiene_action: row.action || `acknowledge_${row.status}`,
         summary: `hygiene apply ${row.kind}:${row.id} ${row.status}`,
-        actor: { cli: "tfx cto hygiene --apply" },
+        actor: hygieneApplyActor(opts),
       },
       {
         stderr: opts.stderr,
@@ -559,6 +607,7 @@ async function applyHygieneRows({
     },
     applicable_count: rows.length,
     applied_count: appended.length,
+    actions,
     events: appended,
   };
 }
@@ -582,15 +631,21 @@ export async function runHygiene(args = [], opts = {}) {
     const current = existsSync(currentPath) ? readJson(currentPath) : {};
     const ledger = readJsonLines(join(lakeRoot, "ledger.jsonl"));
     const overlay = await readLiveOverlay({ ...opts, rootDir, lakeRoot });
-    return projectCtoHygiene({
-      current,
-      ledger: ledger.length > 0 ? ledger : null,
+    return {
+      ledger,
       overlay,
-    });
+      projection: projectCtoHygiene({
+        current,
+        ledger: ledger.length > 0 ? ledger : null,
+        overlay,
+      }),
+    };
   };
 
   let steward = null;
   let projection;
+  let overlay = { live_sessions: [] };
+  let ledger = [];
   let applyResult = null;
   if (apply) {
     steward = await acquireCtoHygieneStewardLock(rootDir, lakeRoot, {
@@ -600,12 +655,14 @@ export async function runHygiene(args = [], opts = {}) {
       lockPath: opts.stewardLockPath,
     });
     try {
-      projection = await buildProjection();
+      ({ projection, overlay, ledger } = await buildProjection());
       applyResult = await applyHygieneRows({
         rootDir,
         lakeRoot,
         projection,
         steward,
+        active: overlay,
+        approvals: ledger.filter((entry) => entry?.event === "hygiene_applied"),
         opts,
       });
       projection = { ...projection, dry_run: false, apply: applyResult };
@@ -613,7 +670,20 @@ export async function runHygiene(args = [], opts = {}) {
       steward.release();
     }
   } else {
-    projection = await buildProjection();
+    ({ projection, overlay } = await buildProjection());
+    projection = {
+      ...projection,
+      actions: await applyHygieneArchiveActions({
+        rootDir,
+        lakeRoot,
+        projection,
+        dryRun: true,
+        now: opts.now || new Date().toISOString(),
+        applyMode: opts.applyMode || getCtoHygieneApplyMode(),
+        active: overlay,
+        fsOps: opts.fsOps,
+      }),
+    };
   }
 
   if (jsonOut) writeJson(stdout, projection);

package/cto/index.mjs

@@ -1,4 +1,11 @@
-const SUBCOMMANDS = ["collect", "status", "dashboard", "hygiene", "event"];
+const SUBCOMMANDS = [
+  "collect",
+  "status",
+  "dashboard",
+  "hygiene",
+  "steward",
+  "event",
+];
 
 function printUsage(subcommand) {
   if (subcommand) {
@@ -6,13 +13,14 @@ function printUsage(subcommand) {
   }
   console.log(`
 Usage
-  tfx cto <collect|status|dashboard|hygiene|event> [options]
+  tfx cto <collect|status|dashboard|hygiene|steward|event> [options]
 
 Subcommands
   collect     Refresh .triflux/lake/current.json from repo-local 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
+  steward     Periodically collect and run one-shot CTO hygiene (TFX_CTO=0 disables)
   event       Append normalized wrapper lifecycle events to the CTO ledger
 `);
 }
@@ -37,6 +45,10 @@ export async function cmdCto(cmdArgs, opts = {}) {
       const { runHygiene } = await import("./hygiene.mjs");
       return runHygiene(rest, opts);
     }
+    case "steward": {
+      const { runSteward } = await import("./steward.mjs");
+      return runSteward(rest, opts);
+    }
     case "event": {
       const { runEvent } = await import("./events.mjs");
       return runEvent(rest, opts);

package/cto/steward.mjs

@@ -0,0 +1,362 @@
+// cto/steward.mjs — collect + hygiene 주기 루프 (resident-cto-manager PRD T2 선행 슬라이스)
+// 가드레일: TFX_CTO kill-switch 매 cycle 확인 + watch 루프는 lake당 단일 인스턴스 락.
+import { utimesSync } from "node:fs";
+import { join } from "node:path";
+
+import { isCtoDisabled } from "../hub/lib/cto-env.mjs";
+import { runCollect } from "./collect.mjs";
+import { acquireCtoHygieneStewardLock, runHygiene } from "./hygiene.mjs";
+import { resolveLakeRootDir } from "./lake-root.mjs";
+
+const SCHEMA_VERSION = "cto-steward.v1";
+const DEFAULT_INTERVAL_MS = 60_000;
+const LOOP_LOCK_STALE_MS = 10 * 60_000;
+const KNOWN_FLAGS_WITH_VALUES = new Set(["--max-runs", "--interval-ms"]);
+const KNOWN_BOOLEAN_FLAGS = new Set([
+  "--watch",
+  "--apply",
+  "--dry-run",
+  "--json",
+  "--no-collect",
+]);
+
+function writeJson(stdout, payload) {
+  stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function parsePositiveInteger(name, value) {
+  if (value === undefined || String(value).startsWith("--")) {
+    throw new Error(`tfx cto steward ${name} requires a value`);
+  }
+  if (!/^\d+$/u.test(String(value))) {
+    throw new Error(`tfx cto steward ${name} must be a positive integer`);
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new Error(`tfx cto steward ${name} must be a positive integer`);
+  }
+  return parsed;
+}
+
+function parseNonNegativeInteger(name, value) {
+  if (value === undefined || String(value).startsWith("--")) {
+    throw new Error(`tfx cto steward ${name} requires a value`);
+  }
+  if (!/^\d+$/u.test(String(value))) {
+    throw new Error(`tfx cto steward ${name} must be a non-negative integer`);
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 0) {
+    throw new Error(`tfx cto steward ${name} must be a non-negative integer`);
+  }
+  return parsed;
+}
+
+export function parseStewardArgs(args = []) {
+  const parsed = {
+    watch: false,
+    maxRuns: null,
+    intervalMs: DEFAULT_INTERVAL_MS,
+    apply: false,
+    dryRun: false,
+    json: false,
+    collectEnabled: true,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (KNOWN_FLAGS_WITH_VALUES.has(arg)) {
+      const value = args[index + 1];
+      if (arg === "--max-runs")
+        parsed.maxRuns = parsePositiveInteger(arg, value);
+      else parsed.intervalMs = parseNonNegativeInteger(arg, value);
+      index += 1;
+      continue;
+    }
+    if (KNOWN_BOOLEAN_FLAGS.has(arg)) {
+      if (arg === "--watch") parsed.watch = true;
+      else if (arg === "--apply") parsed.apply = true;
+      else if (arg === "--dry-run") parsed.dryRun = true;
+      else if (arg === "--json") parsed.json = true;
+      else if (arg === "--no-collect") parsed.collectEnabled = false;
+      continue;
+    }
+    throw new Error(`unknown tfx cto steward flag: ${arg}`);
+  }
+
+  if (parsed.apply && parsed.dryRun) {
+    throw new Error("tfx cto steward accepts only one of --apply or --dry-run");
+  }
+  return parsed;
+}
+
+function createSilentStdout() {
+  return {
+    write() {
+      return true;
+    },
+  };
+}
+
+function compactRun(index, collectResult, hygieneResult) {
+  return {
+    index,
+    collected: collectResult !== null,
+    collect: collectResult,
+    hygiene: hygieneResult,
+  };
+}
+
+function isAbortError(error) {
+  return error?.name === "AbortError" || error?.code === "ABORT_ERR";
+}
+
+export function stewardLoopLockPath(lakeRoot) {
+  return join(lakeRoot, "stewards", "steward-loop.lock");
+}
+
+export async function runSteward(args = [], opts = {}) {
+  const parsed = parseStewardArgs(args);
+  const jsonRequested = parsed.json || opts.json === true;
+  if (parsed.watch && parsed.maxRuns === null && jsonRequested) {
+    throw new Error(
+      "tfx cto steward --watch --json requires --max-runs for a finite JSON summary",
+    );
+  }
+  if (!parsed.watch && parsed.maxRuns !== null) {
+    (opts.stderr || process.stderr).write(
+      "tfx cto steward: --max-runs is ignored without --watch\n",
+    );
+  }
+
+  // steward 전용 opts 는 여기서 걸러내고, 나머지(overlay, synapseReader 등)만
+  // collect/hygiene 로 전달한다.
+  const {
+    collectFn: injectedCollectFn,
+    hygieneFn: injectedHygieneFn,
+    sleepFn: injectedSleepFn,
+    onRun,
+    json: _jsonOpt,
+    stdout: injectedStdout,
+    stderr: _stderrOpt,
+    signal: externalSignal,
+    isCtoDisabledFn: injectedGate,
+    acquireLoopLockFn: injectedAcquireLoopLock,
+    installSignalHandler,
+    rootDir: _rootDirOpt,
+    lakeRoot: _lakeRootOpt,
+    ...innerOpts
+  } = opts;
+
+  const rootDir = opts.rootDir || resolveLakeRootDir(process.cwd());
+  const lakeRoot = opts.lakeRoot || join(rootDir, ".triflux", "lake");
+  const stdout = injectedStdout || process.stdout;
+  const collectFn = injectedCollectFn || runCollect;
+  const hygieneFn = injectedHygieneFn || runHygiene;
+  const ctoDisabled = injectedGate || isCtoDisabled;
+
+  const controller = new AbortController();
+  const signal = controller.signal;
+  if (externalSignal) {
+    if (externalSignal.aborted) controller.abort();
+    else
+      externalSignal.addEventListener("abort", () => controller.abort(), {
+        once: true,
+      });
+  }
+
+  const sleepFn =
+    injectedSleepFn ||
+    ((ms) =>
+      new Promise((resolve) => {
+        if (signal.aborted) {
+          resolve();
+          return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal.addEventListener(
+          "abort",
+          () => {
+            clearTimeout(timer);
+            resolve();
+          },
+          { once: true },
+        );
+      }));
+
+  const mode = parsed.apply ? "apply" : "dry-run";
+  const silentStdout = createSilentStdout();
+  const runLimit = parsed.watch ? parsed.maxRuns : 1;
+  const retainRuns = runLimit !== null;
+  const runs = [];
+  let latestRun = null;
+  let lastCollect = null;
+  let lastHygiene = null;
+  let runCount = 0;
+  let stoppedReason = null;
+
+  // 가드레일 1 (PRD kill-switch): 루프 진입 전에도, 매 cycle에도 확인한다.
+  if (ctoDisabled()) stoppedReason = "disabled";
+
+  // 가드레일 2 (PRD single-instance): watch 루프는 lake당 하나만 돈다.
+  const loopLockPath = stewardLoopLockPath(lakeRoot);
+  const loopLockStaleMs = Math.max(LOOP_LOCK_STALE_MS, parsed.intervalMs * 3);
+  let loopLock = null;
+  let loopLockHeartbeat = null;
+  if (!stoppedReason && parsed.watch) {
+    const acquireLock =
+      injectedAcquireLoopLock ||
+      ((lockPath) =>
+        acquireCtoHygieneStewardLock(rootDir, lakeRoot, {
+          lockPath,
+          timeoutMs: 0,
+          staleMs: loopLockStaleMs,
+        }));
+    loopLock = await acquireLock(loopLockPath);
+    // 한 cycle이 staleMs보다 길어져도 다른 인스턴스가 락을 stale로 오판해
+    // 훔치지 못하도록, 작업 진행 중에도 주기적으로 mtime을 갱신한다.
+    if (loopLock?.path) {
+      const heartbeatMs = Math.max(30_000, Math.floor(loopLockStaleMs / 3));
+      loopLockHeartbeat = setInterval(() => {
+        try {
+          const touch = new Date();
+          utimesSync(loopLock.path, touch, touch);
+        } catch {}
+      }, heartbeatMs);
+      loopLockHeartbeat.unref?.();
+    }
+  }
+
+  let sigintHandler = null;
+  if (!stoppedReason && parsed.watch && installSignalHandler !== false) {
+    sigintHandler = () => controller.abort();
+    process.once("SIGINT", sigintHandler);
+  }
+
+  try {
+    while (!stoppedReason && (runLimit === null || runCount < runLimit)) {
+      if (ctoDisabled()) {
+        stoppedReason = "disabled";
+        break;
+      }
+      if (signal.aborted) {
+        stoppedReason = "signal";
+        break;
+      }
+
+      const runIndex = runCount + 1;
+      let collectResult = null;
+
+      if (parsed.collectEnabled) {
+        collectResult = await collectFn([], {
+          ...innerOpts,
+          rootDir,
+          lakeRoot,
+          stdout: silentStdout,
+        });
+        lastCollect = collectResult;
+      }
+
+      // collect 도중 중단/kill-switch가 들어왔으면 이번 cycle의 hygiene(특히
+      // apply)을 시작하지 않는다 — 중단 요청 이후의 fs-mutation 금지.
+      if (ctoDisabled()) {
+        stoppedReason = "disabled";
+        break;
+      }
+      if (signal.aborted) {
+        stoppedReason = "signal";
+        break;
+      }
+
+      const hygieneArgs = parsed.apply
+        ? ["--apply", "--json"]
+        : ["--dry-run", "--json"];
+      const hygieneResult = await hygieneFn(hygieneArgs, {
+        ...innerOpts,
+        rootDir,
+        lakeRoot,
+        stdout: silentStdout,
+        apply: parsed.apply,
+        dryRun: !parsed.apply,
+        json: true,
+      });
+      lastHygiene = hygieneResult;
+
+      const run = compactRun(runIndex, collectResult, hygieneResult);
+      latestRun = run;
+      if (retainRuns) runs.push(run);
+      runCount += 1;
+
+      if (parsed.watch && !jsonRequested) {
+        stdout.write(
+          `cto steward run ${runIndex} (${mode}): collect=${
+            collectResult !== null ? "ok" : "skipped"
+          } hygiene=ok\n`,
+        );
+      }
+      if (typeof onRun === "function") {
+        await onRun(run, {
+          run_count: runCount,
+          rootDir,
+          lakeRoot,
+          mode,
+        });
+      }
+
+      if (!parsed.watch) break;
+      if (runLimit !== null && runCount >= runLimit) break;
+      try {
+        await sleepFn(parsed.intervalMs);
+      } catch (error) {
+        if (isAbortError(error)) {
+          stoppedReason = "signal";
+          break;
+        }
+        throw error;
+      }
+      if (signal.aborted) {
+        stoppedReason = "signal";
+        break;
+      }
+    }
+  } finally {
+    if (sigintHandler) process.off("SIGINT", sigintHandler);
+    if (loopLockHeartbeat) clearInterval(loopLockHeartbeat);
+    loopLock?.release?.();
+  }
+
+  if (!stoppedReason) stoppedReason = parsed.watch ? "max-runs" : "single-run";
+
+  const summary = {
+    schema_version: SCHEMA_VERSION,
+    mode,
+    watch: parsed.watch,
+    interval_ms: parsed.intervalMs,
+    max_runs: parsed.maxRuns,
+    collect_enabled: parsed.collectEnabled,
+    disabled: stoppedReason === "disabled",
+    stopped_reason: stoppedReason,
+    loop_lock_path: parsed.watch ? loopLockPath : null,
+    run_count: runCount,
+    retained_run_count: runs.length,
+    runs,
+    latest_run: latestRun,
+    last_collect: lastCollect,
+    last_hygiene: lastHygiene,
+  };
+
+  if (jsonRequested) writeJson(stdout, summary);
+  else if (stoppedReason === "disabled") {
+    stdout.write(
+      `cto steward disabled by TFX_CTO kill-switch after ${runCount} run(s)\n`,
+    );
+  } else {
+    stdout.write(
+      `cto steward ${mode}: ${runCount} run(s), collect ${
+        parsed.collectEnabled ? "enabled" : "disabled"
+      }, stopped=${stoppedReason}\n`,
+    );
+  }
+
+  return summary;
+}

package/hooks/keyword-rules.json

@@ -62,6 +62,40 @@
       "state": null,
       "mcp_route": null
     },
+    {
+      "id": "tfx-harness",
+      "patterns": [
+        {
+          "source": "\\btfx[\\s-]?harness\\b",
+          "flags": "i"
+        }
+      ],
+      "skill": "tfx-harness",
+      "priority": 1,
+      "supersedes": ["tfx-unified"],
+      "exclusive": false,
+      "state": null,
+      "mcp_route": null
+    },
+    {
+      "id": "tfx-harness-meta",
+      "patterns": [
+        {
+          "source": "(?:어떤\\s*스킬|스킬\\s*추천|스킬\\s*라우팅|작업\\s*라우팅|메타\\s*라우팅)",
+          "flags": "i"
+        },
+        {
+          "source": "\\bwhich\\s+skill\\b",
+          "flags": "i"
+        }
+      ],
+      "skill": "tfx-harness",
+      "priority": 2,
+      "supersedes": ["tfx-unified"],
+      "exclusive": false,
+      "state": null,
+      "mcp_route": null
+    },
     {
       "id": "tfx-unified",
       "patterns": [
@@ -160,7 +194,7 @@
         }
       ],
       "skill": "tfx-hub",
-      "priority": 2,
+      "priority": 1,
       "supersedes": [],
       "exclusive": false,
       "state": null,
@@ -175,7 +209,7 @@
         }
       ],
       "skill": "tfx-doctor",
-      "priority": 2,
+      "priority": 1,
       "supersedes": [],
       "exclusive": false,
       "state": null,
@@ -190,7 +224,7 @@
         }
       ],
       "skill": "tfx-setup",
-      "priority": 2,
+      "priority": 1,
       "supersedes": [],
       "exclusive": false,
       "state": null,
@@ -205,7 +239,7 @@
         }
       ],
       "skill": "tfx-research",
-      "priority": 2,
+      "priority": 1,
       "supersedes": [],
       "exclusive": false,
       "state": null,
@@ -220,7 +254,7 @@
         }
       ],
       "skill": "tfx-interview",
-      "priority": 2,
+      "priority": 1,
       "supersedes": [],
       "exclusive": false,
       "state": null,

package/hooks/pipeline-stop.mjs

@@ -152,7 +152,7 @@ function contextPercentsFromObject(value) {
     value.total_tokens ??
     value.totalTokens;
   // Fall back to a 1M context window when the payload omits one — Opus 4.x
-  // [1M] and Codex gpt-5.5 both run on a 1M window, and assuming 200K there
+  // [1M] and Codex GPT-5.6 family run on a 1M window, and assuming 200K there
   // false-positives at ~15% real usage. Override via
   // TFX_CONTEXT_DEFAULT_MAX_TOKENS for narrower setups.
   const envFallback = Number(process.env.TFX_CONTEXT_DEFAULT_MAX_TOKENS);