triflux 10.20.0 → 10.20.2

package/hooks/post-tool-tips.mjs

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+
+// hooks/post-tool-tips.mjs — opt-in targeted PostToolUse rules reminders (#245)
+//
+// This hook is intentionally quiet by default. Set TFX_POST_TOOL_TIPS=1 to emit
+// bounded reminders after Bash/Edit/Write touches high-impact triflux paths.
+
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import {
+  dirname,
+  isAbsolute,
+  join,
+  normalize,
+  relative,
+  resolve,
+} from "node:path";
+
+const MAX_MESSAGE_CHARS = 1200;
+const MAX_STATE_ENTRIES = 80;
+const DEDUPE_TTL_MS = 60 * 60 * 1000;
+const STATE_DIR =
+  process.env.TRIFLUX_POST_TOOL_TIPS_STATE_DIR ||
+  join(tmpdir(), "tfx-post-tool-tips");
+const STATE_FILE = join(STATE_DIR, "seen.json");
+
+const RULES = [
+  {
+    id: "hook-lifecycle",
+    label: "hook lifecycle",
+    patterns: [
+      /^hooks\/(hook-registry\.json|hooks\.json|hook-orchestrator\.mjs)$/,
+      /^hooks\/.*\.(mjs|json)$/,
+    ],
+    message:
+      "hook lifecycle change: keep registry/settings narrow, mirror package hooks, run the focused hook test and npm run release:check-mirror before commit.",
+  },
+  {
+    id: "package-hook-mirror",
+    label: "package hook mirror",
+    patterns: [/^packages\/(triflux|core)\/hooks\//],
+    message:
+      "package hook mirror change: keep root, packages/triflux, and packages/core lifecycle hook behavior aligned; do not leave core partially mirrored.",
+  },
+  {
+    id: "team-runtime",
+    label: "team runtime",
+    patterns: [/^hub\/team\//, /^mesh\//, /^hooks\/pipeline-stop\.mjs$/],
+    message:
+      "team runtime change: verify swarm/retry/pipeline state transitions and avoid blocking user abort or cleanup paths.",
+  },
+  {
+    id: "mcp-surface",
+    label: "MCP surface",
+    patterns: [
+      /^scripts\/mcp/,
+      /^scripts\/lib\/mcp-/,
+      /^hooks\/mcp-config-watcher\.mjs$/,
+      /^\.mcp\.json$/,
+    ],
+    message:
+      "MCP surface change: preserve stdio MCP remediation, gateway fallback, and transport degradation behavior across macOS/Linux/Windows.",
+  },
+  {
+    id: "instruction-source",
+    label: "instruction source",
+    patterns: [/^AGENTS\.md$/, /^CLAUDE\.md$/, /^\.claude\/rules\//],
+    message:
+      "instruction source change: do not mix policy edits with unrelated implementation; preserve exact psmux/WT/Codex routing constraints.",
+  },
+];
+
+function readStdin() {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function isEnabled() {
+  return process.env.TFX_POST_TOOL_TIPS === "1";
+}
+
+function safeJsonParse(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function normalizeSlash(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function cwdFromInput(input) {
+  return resolve(input.cwd || process.env.CLAUDE_CWD || process.cwd());
+}
+
+function toRepoRelative(candidate, cwd) {
+  if (!candidate || typeof candidate !== "string") return null;
+  const stripped = candidate.trim().replace(/^["']|["']$/g, "");
+  if (!stripped) return null;
+  if (/^[a-z]+:\/\//i.test(stripped)) return null;
+
+  const absolute = isAbsolute(stripped) ? stripped : resolve(cwd, stripped);
+  const normalizedAbs = normalize(absolute);
+  const normalizedCwd = normalize(cwd);
+  const rel = normalizeSlash(relative(normalizedCwd, normalizedAbs));
+
+  if (!rel || rel === ".") return null;
+  if (rel.startsWith("../") || rel === "..") return null;
+  return rel;
+}
+
+function extractEditWritePath(input, cwd) {
+  const filePath = input.tool_input?.file_path || input.tool_input?.path;
+  const rel = toRepoRelative(filePath, cwd);
+  return rel ? [rel] : [];
+}
+
+function tokenizeCommand(command) {
+  const tokens = [];
+  let current = "";
+  let quote = null;
+
+  for (const ch of String(command || "")) {
+    if (quote) {
+      if (ch === quote) quote = null;
+      else current += ch;
+    } else if (ch === "'" || ch === '"') {
+      quote = ch;
+    } else if (/\s/.test(ch)) {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+    } else {
+      current += ch;
+    }
+  }
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+function looksLikePathToken(token) {
+  if (!token || token.startsWith("-")) return false;
+  if (
+    /^(node|npm|pnpm|bun|npx|git|cat|sed|awk|rg|grep|bash|sh|zsh)$/.test(token)
+  )
+    return false;
+  return /^(hooks|packages|hub|mesh|scripts|\.claude|AGENTS\.md|CLAUDE\.md|\.mcp\.json)(\/|$)/.test(
+    normalizeSlash(token),
+  );
+}
+
+function extractBashPaths(input, cwd) {
+  const command = input.tool_input?.command || "";
+  const paths = [];
+  for (const token of tokenizeCommand(command)) {
+    const cleaned = token.replace(/[,:;]+$/g, "");
+    if (!cleaned || cleaned.startsWith("-")) continue;
+
+    const rel = toRepoRelative(cleaned, cwd);
+    if (!rel) continue;
+    if (!isAbsolute(cleaned) && !looksLikePathToken(cleaned)) continue;
+    paths.push(rel);
+  }
+  return paths;
+}
+
+function extractTouchedPaths(input) {
+  const toolName = input.tool_name || "";
+  const cwd = cwdFromInput(input);
+
+  if (toolName === "Edit" || toolName === "Write")
+    return extractEditWritePath(input, cwd);
+  if (toolName === "Bash") return extractBashPaths(input, cwd);
+  return [];
+}
+
+function canonicalPathKey(relPath, cwd) {
+  const absolute = resolve(cwd, relPath);
+  try {
+    return normalizeSlash(realpathSync(absolute));
+  } catch {
+    return normalizeSlash(absolute);
+  }
+}
+
+function matchRules(relPaths, cwd) {
+  const matched = [];
+  const seen = new Set();
+
+  for (const relPath of relPaths) {
+    const normalizedRel = normalizeSlash(relPath);
+    for (const rule of RULES) {
+      if (!rule.patterns.some((pattern) => pattern.test(normalizedRel)))
+        continue;
+      const key = `${rule.id}:${canonicalPathKey(normalizedRel, cwd)}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      matched.push({ rule, relPath: normalizedRel, key });
+    }
+  }
+
+  return matched;
+}
+
+function loadState() {
+  if (!existsSync(STATE_FILE)) return { entries: {} };
+  try {
+    const parsed = JSON.parse(readFileSync(STATE_FILE, "utf8"));
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      typeof parsed.entries !== "object"
+    )
+      return { entries: {} };
+    return parsed;
+  } catch {
+    return { entries: {} };
+  }
+}
+
+function saveState(state) {
+  mkdirSync(dirname(STATE_FILE), { recursive: true });
+  writeFileSync(STATE_FILE, JSON.stringify(state, null, 2), "utf8");
+}
+
+function hashKey(value) {
+  return createHash("sha1").update(value).digest("hex").slice(0, 16);
+}
+
+function filterUnseen(matches) {
+  if (matches.length === 0) return [];
+
+  const now = Date.now();
+  const state = loadState();
+  const entries = Object.fromEntries(
+    Object.entries(state.entries || {}).filter(
+      ([, ts]) => now - Number(ts || 0) <= DEDUPE_TTL_MS,
+    ),
+  );
+
+  const unseen = [];
+  for (const match of matches) {
+    const key = hashKey(match.key);
+    if (entries[key]) continue;
+    entries[key] = now;
+    unseen.push(match);
+  }
+
+  const trimmed = Object.entries(entries)
+    .sort((a, b) => Number(b[1]) - Number(a[1]))
+    .slice(0, MAX_STATE_ENTRIES);
+  saveState({ entries: Object.fromEntries(trimmed) });
+
+  return unseen;
+}
+
+function buildMessage(matches) {
+  if (matches.length === 0) return "";
+
+  const lines = ["[post-tool-tips] targeted triflux reminder:"];
+  for (const { rule, relPath } of matches) {
+    lines.push(`- ${rule.label} (${relPath}): ${rule.message}`);
+  }
+
+  let message = lines.join("\n");
+  if (message.length > MAX_MESSAGE_CHARS) {
+    message = `${message.slice(0, MAX_MESSAGE_CHARS - 40).trimEnd()}\n[post-tool-tips] truncated`;
+  }
+  return message;
+}
+
+function main() {
+  if (!isEnabled()) process.exit(0);
+
+  const input = safeJsonParse(readStdin());
+  if (!input || input.hook_event_name !== "PostToolUse") process.exit(0);
+
+  const cwd = cwdFromInput(input);
+  const paths = extractTouchedPaths(input);
+  if (paths.length === 0) process.exit(0);
+
+  const matches = matchRules(paths, cwd);
+  const unseen = filterUnseen(matches);
+  const message = buildMessage(unseen);
+
+  if (message) process.stdout.write(JSON.stringify({ systemMessage: message }));
+}
+
+try {
+  main();
+} catch {
+  process.exit(0);
+}

package/hooks/pre-compact-snapshot.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+// hooks/pre-compact-snapshot.mjs — PreCompact hook
+//
+// Compaction 직전에 짧은 상태 스냅샷을 주입한다. 민감 데이터는 읽지 않고,
+// repo-local 상태와 git 요약만 3KB 이하로 제한한다.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const MAX_CONTEXT_BYTES = 3000;
+const STALE_RUN_MS = 30 * 60 * 1000;
+const PROJECT_ROOT = process.env.CLAUDE_CWD || process.cwd();
+
+function readStdinJson() {
+  try {
+    const raw = readFileSync(0, "utf8");
+    return raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function git(args) {
+  try {
+    return execFileSync("git", args, {
+      cwd: PROJECT_ROOT,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 3000,
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function summarizeGit() {
+  const branch =
+    git(["branch", "--show-current"]) || git(["rev-parse", "--short", "HEAD"]);
+  const status = git(["status", "--short"]);
+  const rows = status ? status.split(/\r?\n/).filter(Boolean) : [];
+  return {
+    branch: branch || "unknown",
+    dirty: rows.length,
+    sample: rows.slice(0, 8),
+  };
+}
+
+function readJsonIfSmall(path, maxBytes = 24_000) {
+  try {
+    if (!existsSync(path)) return null;
+    if (statSync(path).size > maxBytes) return null;
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function summarizeModeState(root) {
+  const stateDir = join(root, ".omx", "state");
+  if (!existsSync(stateDir)) return [];
+  try {
+    return readdirSync(stateDir)
+      .filter((name) => name.endsWith("-state.json"))
+      .flatMap((name) => {
+        const state = readJsonIfSmall(join(stateDir, name));
+        if (!state || state.active === false) return [];
+        return [
+          {
+            mode: state.mode || name.replace(/-state\.json$/, ""),
+            phase: state.current_phase || state.phase || null,
+            active: state.active !== false,
+          },
+        ];
+      })
+      .slice(0, 8);
+  } catch {
+    return [];
+  }
+}
+
+function summarizeRetryState(input) {
+  const sessionId = input.session_id || input.sessionId || "";
+  if (!sessionId) return null;
+  const candidates = [
+    join(PROJECT_ROOT, ".omc", "state", `retry-${sessionId}.json`),
+    join(homedir(), ".omc", "state", `retry-${sessionId}.json`),
+  ];
+  for (const path of candidates) {
+    const state = readJsonIfSmall(path);
+    if (!state) continue;
+    return {
+      phase: state.phase || state.current_phase || null,
+      iteration: state.iteration ?? state.retry_count ?? null,
+      max: state.max_iterations ?? state.max ?? null,
+    };
+  }
+  return null;
+}
+
+function countStaleSwarmRuns(nowMs = Date.now()) {
+  const logsRoot = join(PROJECT_ROOT, ".triflux", "swarm-logs");
+  if (!existsSync(logsRoot)) return 0;
+  try {
+    return readdirSync(logsRoot, { withFileTypes: true }).filter((entry) => {
+      if (!entry.isDirectory() || !entry.name.startsWith("run-")) return false;
+      const eventPath = join(logsRoot, entry.name, "swarm-events.jsonl");
+      if (!existsSync(eventPath)) return false;
+      try {
+        return nowMs - statSync(eventPath).mtimeMs > STALE_RUN_MS;
+      } catch {
+        return false;
+      }
+    }).length;
+  } catch {
+    return 0;
+  }
+}
+
+function truncateUtf8(text, maxBytes) {
+  let output = text;
+  while (Buffer.byteLength(output, "utf8") > maxBytes) {
+    output = output.slice(0, Math.max(0, output.length - 200));
+  }
+  return output;
+}
+
+export function buildSnapshot(input = readStdinJson()) {
+  const gitState = summarizeGit();
+  const activeModes = summarizeModeState(PROJECT_ROOT);
+  const retry = summarizeRetryState(input);
+  const staleSwarmRuns = countStaleSwarmRuns();
+
+  const lines = [
+    "[triflux pre-compact snapshot]",
+    `cwd: ${PROJECT_ROOT}`,
+    `git: ${gitState.branch}; dirty=${gitState.dirty}`,
+  ];
+  if (gitState.sample.length) {
+    lines.push(`dirty_sample: ${gitState.sample.join(" | ")}`);
+  }
+  if (activeModes.length) {
+    lines.push(
+      `active_modes: ${activeModes
+        .map((m) => `${m.mode}${m.phase ? `:${m.phase}` : ""}`)
+        .join(", ")}`,
+    );
+  }
+  if (retry) {
+    lines.push(
+      `retry: phase=${retry.phase || "-"} iteration=${retry.iteration ?? "-"}/${retry.max ?? "-"}`,
+    );
+  }
+  if (staleSwarmRuns > 0) {
+    lines.push(`stale_swarm_runs: ${staleSwarmRuns}`);
+  }
+
+  return truncateUtf8(lines.join("\n"), MAX_CONTEXT_BYTES);
+}
+
+function main() {
+  const snapshot = buildSnapshot();
+  if (!snapshot.trim()) return;
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreCompact",
+        additionalContext: snapshot,
+      },
+    }),
+  );
+}
+
+try {
+  if (import.meta.url.endsWith(process.argv[1]?.split(/[\\/]/).pop() || "")) {
+    main();
+  }
+} catch {
+  process.exit(0);
+}

package/hooks/session-end-cleanup.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// hooks/session-end-cleanup.mjs — SessionEnd lifecycle state reporter
+//
+// Report-only by default. Opt-in cleanup only removes the repo-local
+// .triflux/subagents/subagents.json file when stale running lifecycle state is
+// present. It never kills processes or touches external HOME/MCP configs.
+
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const MARKER = "[session-end-cleanup]";
+const STALE_MS = 30 * 60 * 1000;
+const MAX_OUTPUT_BYTES = 2 * 1024;
+
+function readStdin() {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function parseJson(raw) {
+  if (!raw?.trim()) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function timestampMs(agent) {
+  const value =
+    agent?.startedAt ??
+    agent?.started_at ??
+    agent?.createdAt ??
+    agent?.created_at ??
+    agent?.timestamp;
+  const parsed = Date.parse(String(value ?? ""));
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function isCompleted(agent) {
+  return (
+    Boolean(
+      agent?.stoppedAt ??
+        agent?.stopped_at ??
+        agent?.completedAt ??
+        agent?.completed_at ??
+        agent?.endedAt ??
+        agent?.ended_at ??
+        agent?.durationMs ??
+        agent?.duration_ms ??
+        agent?.result,
+    ) ||
+    agent?.status === "completed" ||
+    agent?.status === "stopped"
+  );
+}
+
+function agentEntries(state) {
+  const agents = state?.agents;
+  if (Array.isArray(agents)) return agents;
+  if (agents && typeof agents === "object") return Object.values(agents);
+  return [];
+}
+
+export function summarizeLifecycleState(state, now = Date.now()) {
+  const completedEntries = Array.isArray(state?.completed)
+    ? state.completed
+    : [];
+  const summary = {
+    running: 0,
+    completed: completedEntries.length,
+    stale: 0,
+    total: completedEntries.length,
+  };
+
+  for (const agent of agentEntries(state)) {
+    if (!agent || typeof agent !== "object") continue;
+    summary.total += 1;
+
+    if (isCompleted(agent)) {
+      summary.completed += 1;
+      continue;
+    }
+
+    const started = timestampMs(agent);
+    if (started !== null && now - started >= STALE_MS) {
+      summary.stale += 1;
+    } else {
+      summary.running += 1;
+    }
+  }
+
+  return summary;
+}
+
+function pruneStaleRunningAgents(state, now = Date.now()) {
+  const agents = state?.agents;
+  if (!agents || typeof agents !== "object" || Array.isArray(agents)) {
+    return { nextState: state, removed: 0 };
+  }
+
+  let removed = 0;
+  const nextAgents = {};
+  for (const [key, agent] of Object.entries(agents)) {
+    const started = timestampMs(agent);
+    const stale =
+      !isCompleted(agent) && started !== null && now - started >= STALE_MS;
+    if (stale) {
+      removed += 1;
+    } else {
+      nextAgents[key] = agent;
+    }
+  }
+
+  return {
+    nextState: { ...state, agents: nextAgents },
+    removed,
+  };
+}
+
+function buildOutput(summary, cleanup) {
+  const context =
+    `${MARKER} subagent lifecycle: ` +
+    `running=${summary.running} completed=${summary.completed} ` +
+    `stale=${summary.stale} total=${summary.total} cleanup=${cleanup}`;
+  const output = {
+    systemMessage: context,
+    hookSpecificOutput: {
+      hookEventName: "SessionEnd",
+      additionalContext: context,
+    },
+  };
+
+  let json = JSON.stringify(output);
+  if (Buffer.byteLength(json, "utf8") >= MAX_OUTPUT_BYTES) {
+    const bounded = `${MARKER} subagent lifecycle: running=${summary.running} completed=${summary.completed} stale=${summary.stale} cleanup=${cleanup}`;
+    json = JSON.stringify({
+      systemMessage: bounded,
+      hookSpecificOutput: {
+        hookEventName: "SessionEnd",
+        additionalContext: bounded,
+      },
+    });
+  }
+  return json;
+}
+
+export function run(input, env = process.env) {
+  if (input?.hook_event_name !== "SessionEnd") return "";
+
+  const root = env.CLAUDE_CWD || process.cwd();
+  const statePath = join(root, ".triflux", "subagents", "subagents.json");
+  if (!existsSync(statePath)) return "";
+
+  const state = parseJson(readFileSync(statePath, "utf8"));
+  if (!state) return "";
+
+  const summary = summarizeLifecycleState(state);
+  let cleanup = "report-only";
+
+  if (env.TFX_SESSION_END_CLEANUP === "1" && summary.stale > 0) {
+    try {
+      const { nextState, removed } = pruneStaleRunningAgents(state);
+      const remainingAgents = Object.keys(nextState?.agents || {}).length;
+      const remainingCompleted = Array.isArray(nextState?.completed)
+        ? nextState.completed.length
+        : 0;
+      if (remainingAgents === 0 && remainingCompleted === 0) {
+        unlinkSync(statePath);
+        cleanup = "removed";
+      } else {
+        writeFileSync(
+          statePath,
+          `${JSON.stringify({ ...nextState, updatedAt: new Date().toISOString() }, null, 2)}\n`,
+          "utf8",
+        );
+        cleanup = `pruned-${removed}`;
+      }
+    } catch {
+      cleanup = "failed";
+    }
+  }
+
+  return buildOutput(summary, cleanup);
+}
+
+function main() {
+  const input = parseJson(readStdin());
+  if (!input) return;
+  const output = run(input);
+  if (output) process.stdout.write(output);
+}
+
+try {
+  main();
+} catch {
+  process.exit(0);
+}