@fusengine/harness 0.1.90 → 0.1.91

package/src/runtime/lifecycle/snapshot/git.ts

@@ -0,0 +1,71 @@
+import { execSync } from "node:child_process";
+
+/**
+ * Run a git subcommand at `root` with a short timeout, returning trimmed stdout.
+ * Uses `node:child_process` (the Bun shell can hang on some git plumbing) and
+ * swallows every failure — a non-repo, missing git, or timeout yields `""` so
+ * the caller omits the section instead of throwing inside the hook.
+ * @param root - Directory to run git in.
+ * @param args - The git args (e.g. `"log --oneline -3"`).
+ * @returns Trimmed stdout, or `""` on any error.
+ */
+function git(root: string, args: string): string {
+  try {
+    return execSync(`git ${args}`, {
+      cwd: root,
+      encoding: "utf8",
+      timeout: 150,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/** Working-tree file counts parsed from `git status --porcelain`. */
+interface Wip {
+  staged: number;
+  unstaged: number;
+  untracked: number;
+}
+
+/** Count staged/unstaged/untracked files from porcelain v1 output (skips the `##` branch line). */
+function countWip(porcelain: string): Wip {
+  const w: Wip = { staged: 0, unstaged: 0, untracked: 0 };
+  for (const line of porcelain.split("\n")) {
+    if (!line || line.startsWith("#")) continue;
+    if (line.startsWith("??")) { w.untracked++; continue; }
+    const x = line[0], y = line[1];
+    if (x && x !== " " && x !== "?") w.staged++;
+    if (y === "M" || y === "D") w.unstaged++;
+  }
+  return w;
+}
+
+/** Parse the current branch from the leading `## branch...upstream` porcelain line. */
+function parseBranch(porcelain: string): string {
+  const head = porcelain.split("\n")[0] ?? "";
+  if (!head.startsWith("## ")) return "";
+  const rest = head.slice(3);
+  const dots = rest.indexOf("...");
+  return (dots >= 0 ? rest.slice(0, dots) : rest).split(" ")[0] ?? "";
+}
+
+/**
+ * Collect a compact git reconciliation section for `root`: current branch, the
+ * last three commits (oneline), and staged/unstaged/untracked WIP counts. When
+ * `root` is not a git repo (status fails) the whole section is omitted (`""`).
+ * @param root - The project/repo root.
+ * @returns The rendered git section body, or `""` when not a repo.
+ */
+export function collectGit(root: string): string {
+  const status = git(root, "status --porcelain=v1 --branch");
+  if (!status) return "";
+  const branch = parseBranch(status) || "(unknown)";
+  const w = countWip(status);
+  const log = git(root, "log --oneline -3");
+  const lines = [`- branch: ${branch}`];
+  if (log) lines.push("- recent:", ...log.split("\n").map((l) => `    ${l}`));
+  lines.push(`- WIP: ${w.staged} staged, ${w.unstaged} unstaged, ${w.untracked} untracked`);
+  return lines.join("\n");
+}

package/src/runtime/lifecycle/snapshot/index.ts

@@ -0,0 +1,52 @@
+import { projectRootOrNull } from "../../../util/project-root";
+import { oneShotSummary } from "../../../tracking/one-shot";
+import { collectGit } from "./git";
+import { collectVersion } from "./version";
+import { collectBoard } from "./board";
+import { renderSections, attachSnapshot, type Section } from "./format";
+
+/** Run `fn`, swallowing any throw into `""` so no single collector can break the hook. */
+function safe(fn: () => string): string {
+  try {
+    return fn();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Build the reconciliation snapshot markdown for `cwd`: git state, running
+ * harness version + drift, the persistent board, and one-shot gate status. Each
+ * collector is isolated by {@link safe}; an all-empty result yields `""`.
+ * @param cwd - The session working directory.
+ * @param moduleUrl - `import.meta.url` of the caller (locates the running package).
+ * @returns The snapshot markdown, or `""` when nothing to report.
+ */
+export function renderSnapshot(cwd: string, moduleUrl: string): string {
+  const root = projectRootOrNull(cwd) ?? cwd;
+  const sections: Section[] = [
+    { title: "Git", body: safe(() => collectGit(root)) },
+    { title: "Version", body: safe(() => collectVersion(root, moduleUrl)) },
+    { title: "Board", body: safe(() => collectBoard(root)) },
+    // raw `cwd` (not `root`): oneShotSummary derives the state dir via defaultStateDir(cwd),
+    // keyed on the same raw hook cwd the runtime writes gate counters under (handle.ts).
+    { title: "One-shot gates", body: safe(() => oneShotSummary(cwd)) },
+  ];
+  return renderSections(sections);
+}
+
+/**
+ * Concatenate the reconciliation snapshot onto a core SessionStart stdout. Fully
+ * fail-safe: any error returns `stdout` unchanged so the hook never breaks.
+ * @param stdout - The core SessionStart JSON stdout (may be `""`).
+ * @param cwd - The session working directory.
+ * @param moduleUrl - `import.meta.url` of the caller.
+ * @returns The merged hook stdout.
+ */
+export function withSnapshot(stdout: string, cwd: string, moduleUrl: string): string {
+  try {
+    return attachSnapshot(stdout, renderSnapshot(cwd, moduleUrl));
+  } catch {
+    return stdout;
+  }
+}

package/src/runtime/lifecycle/snapshot/version.ts

@@ -0,0 +1,34 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { runningVersion } from "../../../cli/doctor";
+
+/** Read the `version` field of `<root>/package.json`, or `""` if absent/unreadable. */
+function pkgVersion(root: string): string {
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as { version?: string };
+    return pkg.version ?? "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Collect the version reconciliation section: the harness version actually
+ * running (resolved from {@link runningVersion}, no network) and, when `root`
+ * carries its own `package.json`, whether that project's version has drifted
+ * from the running harness.
+ * @param root - The project root (cwd repo).
+ * @param moduleUrl - `import.meta.url` of the calling module (locates the running package.json).
+ * @returns The rendered version section body (never `""`).
+ */
+export function collectVersion(root: string, moduleUrl: string): string {
+  const running = runningVersion(moduleUrl).version;
+  const lines = [`- harness running: v${running}`];
+  const project = pkgVersion(root);
+  if (project && project !== running) {
+    lines.push(`- project package.json: v${project} (DRIFT — running harness differs)`);
+  } else if (project) {
+    lines.push(`- project package.json: v${project} (in sync)`);
+  }
+  return lines.join("\n");
+}

package/src/runtime/lifecycle/solid-detect.ts

@@ -0,0 +1,56 @@
+import { appendFileSync, existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** A SOLID project profile: type label, per-file line limit, interface dir. */
+export interface SolidProfile {
+  type: string;
+  limit: number;
+  ifaceDir: string;
+}
+
+/** Ordered detection table (mirrors solid/scripts/detect-project.py). */
+const CHECKS: { file: string; grep: string | null; profile: SolidProfile }[] = [
+  { file: "package.json", grep: "next", profile: { type: "nextjs", limit: 150, ifaceDir: "modules/cores/interfaces" } },
+  { file: "composer.json", grep: "laravel", profile: { type: "laravel", limit: 100, ifaceDir: "app/Contracts" } },
+  { file: "go.mod", grep: null, profile: { type: "go", limit: 100, ifaceDir: "internal/interfaces" } },
+  { file: "Cargo.toml", grep: null, profile: { type: "rust", limit: 100, ifaceDir: "src/traits" } },
+  { file: "pyproject.toml", grep: null, profile: { type: "python", limit: 100, ifaceDir: "src/interfaces" } },
+  { file: "requirements.txt", grep: null, profile: { type: "python", limit: 100, ifaceDir: "src/interfaces" } },
+];
+
+/** Detect the SOLID profile for `projectDir`, defaulting to `unknown`. */
+export function detectSolidProfile(projectDir: string): SolidProfile {
+  for (const { file, grep, profile } of CHECKS) {
+    const path = join(projectDir, file);
+    if (!existsSync(path)) continue;
+    if (grep !== null) {
+      try { if (!readFileSync(path, "utf-8").includes(grep)) continue; } catch { continue; }
+    }
+    return profile;
+  }
+  if (existsSync(join(projectDir, "Package.swift"))) return { type: "swift", limit: 150, ifaceDir: "Protocols" };
+  try {
+    if (readdirSync(projectDir).some((e) => e.endsWith(".xcodeproj") || e.endsWith(".xcworkspace"))) {
+      return { type: "swift", limit: 150, ifaceDir: "Protocols" };
+    }
+  } catch { /* unreadable dir */ }
+  return { type: "unknown", limit: 100, ifaceDir: "" };
+}
+
+/**
+ * Handle solid SessionStart: detect the profile, append SOLID_* exports to
+ * `CLAUDE_ENV_FILE`, and return the `SOLID: …` stdout line (or "" for unknown).
+ * Ports `solid/scripts/detect-project.py`.
+ * @param env - Environment (defaults to `process.env`).
+ * @returns The plain-text stdout line (possibly empty).
+ */
+export function solidDetectStart(env: Record<string, string | undefined> = process.env): string {
+  const profile = detectSolidProfile(env.CLAUDE_PROJECT_DIR ?? ".");
+  const envFile = env.CLAUDE_ENV_FILE ?? "";
+  if (envFile) {
+    try {
+      appendFileSync(envFile, `export SOLID_PROJECT_TYPE=${profile.type}\nexport SOLID_FILE_LIMIT=${profile.limit}\nexport SOLID_INTERFACE_DIR=${profile.ifaceDir}\n`, "utf-8");
+    } catch { /* best effort */ }
+  }
+  return profile.type !== "unknown" ? `SOLID: ${profile.type} project (max ${profile.limit} lines)` : "";
+}

package/src/runtime/lifecycle/stop-core.ts

@@ -0,0 +1,35 @@
+import { homedir } from "node:os";
+import { cleanupSession } from "./session-end";
+import { validateTaskSolid } from "./task-completed";
+import { defaultStateDir } from "../paths";
+import { notify } from "../notifications";
+
+/**
+ * Handle the core scope's `Stop` event — Codex parity. Codex never emits
+ * `SessionEnd`/`TaskCompleted` (codex-plugins/docs/reference/hooks.md,
+ * "Harness Runtime Limits": "lifecycle dispatch includes Claude-only names
+ * such as TaskCompleted, PostToolUseFailure, and SessionEnd; Codex does not
+ * emit those events") but its own hooks.json wires `Stop` to `hook codex
+ * core`, and its own docs table defines `Stop` as "turn finishes — cleanup
+ * and completion notification". Both ported behaviors collapse onto it here
+ * rather than being invented anew: {@link cleanupSession} (normally
+ * SessionEnd-only) for cleanup, {@link validateTaskSolid} (normally
+ * TaskCompleted-only) for the SOLID/receipt completion check.
+ *
+ * Claude-side, this branch is unreachable: core-guards' Claude `Stop` hooks
+ * are a native `afplay` sound + an LLM `type:"prompt"` check, neither of
+ * which invokes the harness binary (see `hooks/hooks.json` in claude-plugins
+ * vs codex-plugins) — `dispatchLifecycle`'s `case "Stop"` for scope `"core"`
+ * only ever receives a real payload from Codex.
+ * @param payload - The raw Stop hook payload.
+ * @param cwd - Project root (drives the state dir).
+ * @param now - Clock.
+ * @returns The native hook stdout ("" when the session is clean).
+ */
+export function stopCore(payload: Record<string, unknown>, cwd: string, now: number): string {
+  cleanupSession(undefined, now);
+  // Turn finished — voice the "stop" sound (fire-and-forget, fail-open: never
+  // throws, never blocks; a silent no-op when opted out or no sound resolves).
+  notify("stop");
+  return validateTaskSolid(payload, homedir(), now, defaultStateDir(cwd), "Stop");
+}

package/src/runtime/lifecycle/subagent-cache.ts

@@ -0,0 +1,61 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { loadIndex } from "../../cache/io";
+import { contextResponse } from "../../adapters/claude";
+import { sanitizeSessionId, sessionsDir } from "../home-state";
+
+const DEFAULT_TTL_MIN = 30;
+
+/** Resolve cache TTL (minutes) from `FUSENGINE_CACHE_TTL_MIN` or default. */
+function ttlMinutes(env: Record<string, string | undefined>): number {
+  const raw = (env.FUSENGINE_CACHE_TTL_MIN ?? "").trim();
+  const val = Number.parseInt(raw, 10);
+  return Number.isFinite(val) && val > 0 ? val : DEFAULT_TTL_MIN;
+}
+
+/** True when ISO ts `YYYY-MM-DDTHH:MM:SSZ` is within `ttlMin` minutes of now. */
+function isFresh(ts: string, ttlMin: number, now: number): boolean {
+  const parsed = Date.parse(ts);
+  if (Number.isNaN(parsed)) return false;
+  const ageSec = (now - parsed) / 1000;
+  return ageSec >= 0 && ageSec <= ttlMin * 60;
+}
+
+/** Sanitize + truncate a cell value (replace `|`/newline, ellipsize). */
+function trunc(text: unknown, limit: number): string {
+  const t = String(text ?? "").replace(/\|/g, "/").replace(/\n/g, " ");
+  return t.length <= limit ? t : t.slice(0, limit - 3) + "...";
+}
+
+/** Render fresh cache entries as the markdown injection block. */
+function render(entries: Record<string, unknown>[]): string {
+  const lines = [
+    "# MCP cache available this session",
+    "Before calling mcp__context7/exa, check if the result is already cached.",
+    "Read the .md file via Read to retrieve the result.",
+    "APEX: reading the MCP cache via Read satisfies the research-expert step.",
+    "",
+    "| Tool | Query | File |",
+    "| --- | --- | --- |",
+  ];
+  for (const e of entries) lines.push(`| ${trunc(e.tool, 40)} | ${trunc(e.query, 60)} | ${trunc(e.file, 50)} |`);
+  return lines.join("\n");
+}
+
+/**
+ * Handle SubagentStart: surface fresh MCP cache entries for the session as
+ * `additionalContext`. Ports `subagent-start/inject-context-cache.py`.
+ * @param sessionIdRaw - Raw session id from the payload.
+ * @param home - Home dir (defaults to `~`).
+ * @param env - Environment (defaults to `process.env`).
+ * @param now - Clock (defaults to `Date.now()`).
+ * @returns The native hook stdout (possibly empty).
+ */
+export function subagentCacheContext(sessionIdRaw: unknown, home: string = homedir(), env: Record<string, string | undefined> = process.env, now: number = Date.now()): string {
+  const sid = sanitizeSessionId(sessionIdRaw === "" || sessionIdRaw == null ? "unknown" : sessionIdRaw);
+  if (!sid) return "";
+  const index = loadIndex(join(sessionsDir(home), sid, "context", "index.json")) as Record<string, unknown>[];
+  if (index.length === 0) return "";
+  const fresh = index.filter((e) => isFresh(String(e.ts ?? ""), ttlMinutes(env), now));
+  return fresh.length ? contextResponse("SubagentStart", render(fresh)) : "";
+}

package/src/runtime/lifecycle/task-completed.ts

@@ -0,0 +1,94 @@
+import { basename, extname } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { contextResponse, systemMessage } from "../../adapters/claude";
+import { resolveMaxLines } from "../../config/limits";
+import { resolveTtlSec } from "../../config/ttl";
+import { countLines } from "../../policy/file-size";
+import { loadSessionState, sanitizeSessionId } from "../home-state";
+import { defaultStateDir, trackFile } from "../paths";
+import { freshReceiptFromFile } from "../../tracking/receipts";
+
+/** Code-file extensions audited on task completion (mirrors validate-task-solid.py). */
+const CODE_EXTENSIONS = new Set([
+  ".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs", ".java", ".php",
+  ".cpp", ".c", ".rb", ".swift", ".kt", ".dart", ".vue", ".svelte", ".astro",
+]);
+
+/** Freshness multiple on `FUSE_ENFORCE_TTL_SEC` for receipts (no new env var); a tsc+test run precedes the "done" by more than one edit window. */
+const RECEIPT_TTL_MULTIPLIER = 5;
+
+/** Files modified during the session, persisted by {@link trackSessionChanges}. */
+interface Changes {
+  modifiedFiles?: string[];
+}
+
+/** The modified files that are code (by extension) — the receipt gate's trigger set. */
+function codeFiles(files: string[]): string[] {
+  return files.filter((fp) => CODE_EXTENSIONS.has(extname(fp)));
+}
+
+/**
+ * Refuse completion when code files changed but no fresh, passing verification
+ * receipt (`tsc`/test, exit 0, zero failures, within TTL×{@link RECEIPT_TTL_MULTIPLIER})
+ * exists in the signed track. TaskCompleted does NOT honor `decision:"block"`
+ * (verified against the official hooks docs — `TeammateIdle/TaskCreated/
+ * TaskCompleted` are excluded from that list); the documented stdout refusal is
+ * `{"continue":false,"stopReason":…}`, which halts the teammate with the reason
+ * shown to the user. Returns that JSON, or `null` when the session is clear.
+ */
+function receiptGate(sid: string, files: string[], now: number, stateDir: string): string | null {
+  if (codeFiles(files).length === 0) return null;
+  const windowMs = resolveTtlSec(process.env) * 1000 * RECEIPT_TTL_MULTIPLIER;
+  if (freshReceiptFromFile(trackFile(sid, stateDir), windowMs, now)) return null;
+  const stopReason =
+    "VERIFICATION RECEIPT REQUIRED: code files changed but no fresh passing tsc/test receipt " +
+    "exists. Run `bun test` + `tsc --noEmit` (exit 0, 0 failures) and re-complete.";
+  return JSON.stringify({ continue: false, stopReason });
+}
+
+/**
+ * Re-count physical lines of every modified code file and collect SOLID
+ * violations (`<basename>: <n> lines (max <max>)`) for those exceeding `max`.
+ * @param files - Candidate modified file paths.
+ * @param max - The SOLID line ceiling.
+ * @returns The list of violation strings (empty when all files comply).
+ */
+function collectViolations(files: string[], max: number): string[] {
+  const violations: string[] = [];
+  for (const fp of files) {
+    if (!CODE_EXTENSIONS.has(extname(fp)) || !existsSync(fp)) continue;
+    try {
+      const lines = countLines(readFileSync(fp, "utf-8"));
+      if (lines > max) violations.push(`${basename(fp)}: ${lines} lines (max ${max})`);
+    } catch { /* unreadable file — skip, matches Python's OSError pass */ }
+  }
+  return violations;
+}
+
+/**
+ * Handle TaskCompleted (ports `task-completed/validate-task-solid.py` + the
+ * receipt gate); also reused verbatim for Codex's `Stop` via {@link stopCore}
+ * (Codex never emits `TaskCompleted`) — `event` stamps the real hook name.
+ * @param payload - The TaskCompleted/Stop payload (`task_id`, `task_subject`, `session_id`).
+ * @param event - The hook event name to stamp on the SOLID-violation response (default `TaskCompleted`).
+ * @returns The native hook stdout, or `""` when the session is clean.
+ */
+export function validateTaskSolid(payload: Record<string, unknown>, home: string = homedir(), now: number = Date.now(), stateDir: string = defaultStateDir(process.cwd()), event: string = "TaskCompleted"): string {
+  const sid = sanitizeSessionId(payload.session_id ?? "unknown");
+  if (!sid) return "";
+  const changes = loadSessionState(sid, home).changes as Changes | undefined;
+  const files = changes?.modifiedFiles ?? [];
+  if (files.length === 0) return "";
+  const max = resolveMaxLines();
+  const violations = collectViolations(files, max);
+  if (violations.length === 0) return receiptGate(sid, files, now, stateDir) ?? "";
+  const taskId = String(payload.task_id ?? "");
+  const subject = String(payload.task_subject ?? "");
+  const msg =
+    `SOLID VIOLATION in task '${subject}' (${taskId}): ` +
+    `${violations.length} file(s) exceed ${max} lines: ` +
+    violations.slice(0, 5).join("; ");
+  // TaskCompleted rejects `hookSpecificOutput` (same gap as TeammateIdle) — ride `systemMessage`; `Stop` keeps `additionalContext`, which it DOES accept.
+  return event === "TaskCompleted" ? systemMessage(msg) : contextResponse(event, msg);
+}

package/src/runtime/lifecycle/teammate-idle-check.ts

@@ -0,0 +1,63 @@
+/**
+ * @module teammate-idle-check
+ * TeammateIdle anti-"false done": alongside the existing sniper suggestion
+ * ({@link validateTeammateOutput}), verify that the files this teammate ANNOUNCED
+ * (session-changes `modifiedFiles`) actually exist on disk. A claimed deliverable
+ * missing on disk is a mechanically-verifiable false-done signal → warn the lead.
+ * Deduped across the fan-out; silent when nothing is verifiable. Fail-open.
+ *
+ * Claude-Code-only: no equivalent `TeammateIdle` hook exists on Codex or Hermes,
+ * so this handler is never reached through those adapters.
+ * @packageDocumentation
+ */
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { systemMessage } from "../../adapters/claude";
+import { loadSessionState, sanitizeSessionId } from "../home-state";
+import { oncePerWindow } from "../inject-dedup";
+import { defaultStateDir } from "../paths";
+import { notify } from "../notifications";
+import { validateTeammateOutput } from "./teammate-idle";
+
+/** Re-warn about the same idle teammate at most once per 30s (fan-out + retries). */
+const IDLE_DEDUP_MS = 30_000;
+
+/** The `changes` block written by `track-changes.ts` into unified session state. */
+interface Changes { modifiedFiles?: string[]; }
+
+/** Announced files (session changes) that are ABSENT on disk (the false-done set). */
+function missingDeliverables(sessionId: string, home: string): string[] {
+  const changes = loadSessionState(sessionId, home).changes as Changes | undefined;
+  return (changes?.modifiedFiles ?? []).filter((f) => typeof f === "string" && f !== "" && !existsSync(f));
+}
+
+/**
+ * Handle TeammateIdle: merge the existing sniper suggestion with a missing-
+ * deliverable warning (deduped) into one advisory `systemMessage`, or "" when
+ * neither fires. TeammateIdle rejects `hookSpecificOutput` (no `additionalContext`
+ * channel) — `systemMessage` is the only user-visible, non-blocking channel it
+ * accepts.
+ * @param data - The raw TeammateIdle payload (`teammate_name`, `session_id`).
+ * @param cwd - Project root (state dir for the dedup sidecar).
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ * @returns The native hook stdout, or "".
+ */
+export function teammateIdleContext(data: Record<string, unknown>, cwd: string, home: string = homedir(), now: number = Date.now()): string {
+  const sniper = validateTeammateOutput(data, home);
+  const sessionId = sanitizeSessionId(data.session_id);
+  const teammate = String(data.teammate_name ?? data.team_name ?? "unknown");
+  let notice = "";
+  if (sessionId) {
+    const missing = missingDeliverables(sessionId, home);
+    if (missing.length > 0 && oncePerWindow(`idle:${sessionId}:${teammate}`, IDLE_DEDUP_MS, { now, dir: defaultStateDir(cwd) })) {
+      notice = `Teammate '${teammate}' idle but expected deliverable(s) not found on disk: ${missing.slice(0, 5).join(", ")} — verify before treating as done.`;
+    }
+  }
+  const merged = [sniper, notice].filter(Boolean).join("\n\n");
+  if (!merged) return "";
+  // An actionable idle signal (false-done or sniper suggestion) warrants human
+  // attention — voice the "human" sound (fire-and-forget, fail-open no-op).
+  notify("human");
+  return systemMessage(merged);
+}

package/src/runtime/lifecycle/teammate-idle.ts

@@ -0,0 +1,28 @@
+import { homedir } from "node:os";
+import { loadSessionState, sanitizeSessionId } from "../home-state";
+
+/** The `changes` block written by `track-changes.ts` into unified session state. */
+interface Changes {
+  cumulativeCodeFiles?: number;
+  modifiedFiles?: string[];
+}
+
+/**
+ * Handle TeammateIdle: when the teammate's session-changes file shows code was
+ * modified, suggest sniper validation as plain text — TeammateIdle has no
+ * `additionalContext` channel (rejects `hookSpecificOutput`), so the caller
+ * ({@link module:teammate-idle-check.teammateIdleContext}) rides this text on
+ * the `systemMessage` channel instead. Ports `teammate-idle/validate-teammate-output.py`.
+ * @param data - The raw hook payload.
+ * @param home - Home dir (defaults to `~`).
+ * @returns The plain notice text, or "" when no code file was modified.
+ */
+export function validateTeammateOutput(data: Record<string, unknown>, home: string = homedir()): string {
+  const teammate = String(data.teammate_name ?? "unknown");
+  const sessionId = sanitizeSessionId(data.session_id) ?? "unknown";
+  const changes = loadSessionState(sessionId, home).changes as Changes | undefined;
+  const count = changes?.cumulativeCodeFiles ?? 0;
+  if (count === 0) return "";
+  const files = (changes?.modifiedFiles ?? []).slice(0, 5).join(", ");
+  return `Teammate '${teammate}' going idle after modifying ${count} code file(s): ${files}. Consider running sniper validation.`;
+}

package/src/runtime/lifecycle/tool-failure.ts

@@ -0,0 +1,24 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Handle PostToolUseFailure: append a `TOOL_FAILURE` line to
+ * `~/.claude/logs/tool-failures.log`, skipping user interrupts. Ports
+ * `post-tool-use/log-tool-failure.py`. No stdout (logging only).
+ * @param data - The raw hook payload.
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ */
+export function logToolFailure(data: Record<string, unknown>, home: string = homedir(), now: number = Date.now()): void {
+  if (data.is_interrupt === true) return;
+  const tool = String(data.tool_name ?? "unknown");
+  const error = String(data.error ?? "unknown error");
+  const sessionId = String(data.session_id ?? "unknown");
+  const ts = new Date(now).toISOString().replace(/\.\d{3}Z$/, "Z");
+  const dir = join(home, ".claude", "logs");
+  try {
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, "tool-failures.log"), `[${ts}] TOOL_FAILURE session=${sessionId} tool=${tool} error=${error}\n`, "utf-8");
+  } catch { /* best effort */ }
+}

package/src/runtime/lifecycle/track-changes.ts

@@ -0,0 +1,61 @@
+import { basename } from "node:path";
+import { homedir } from "node:os";
+import { attachSystemMessage, contextResponse } from "../../adapters/claude";
+import { loadSessionState, sanitizeSessionId, saveSessionState, sessionsDir } from "../home-state";
+import { onceExclusive } from "../inject-dedup";
+import { BURST_DEDUP_MS } from "../burst-window";
+import { sniperRequiredNotice } from "../notices";
+
+/** Code-file extensions tracked for sniper (mirrors track-session-changes.py). */
+const CODE_EXT = /\.(ts|tsx|js|jsx|py|go|rs|java|php|cpp|c|rb|swift|kt|vue|svelte|astro)$/;
+
+/** Shape of the `changes` block persisted in per-session state. */
+interface Changes {
+  cumulativeCodeFiles: number;
+  modifiedFiles: string[];
+  lastModifiedFile?: string;
+  lastCheck?: string;
+}
+
+/**
+ * Handle PostToolUse Write/Edit: track the cumulative set of modified code
+ * files per session and emit the mandatory "SNIPER VALIDATION REQUIRED"
+ * additionalContext. Ports `post-tool-use/track-session-changes.py`.
+ * @param sessionIdRaw - Raw session id from the payload.
+ * @param filePath - The edited file path.
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ * @returns The native hook stdout (possibly empty when not a code file).
+ */
+export function trackSessionChanges(sessionIdRaw: unknown, filePath: string, home: string = homedir(), now: number = Date.now()): string {
+  if (!filePath || !CODE_EXT.test(filePath)) return "";
+  const sid = sanitizeSessionId(sessionIdRaw) ?? "unknown";
+  const state = loadSessionState(sid, home);
+  const prev = (state.changes as Changes | undefined) ?? { cumulativeCodeFiles: 0, modifiedFiles: [] };
+  const files = [...prev.modifiedFiles];
+  let count = prev.cumulativeCodeFiles;
+  if (!files.includes(filePath)) { count += 1; files.push(filePath); }
+  state.changes = {
+    cumulativeCodeFiles: count,
+    modifiedFiles: files,
+    lastModifiedFile: filePath,
+    lastCheck: new Date(now).toISOString().replace(/\.\d{3}Z$/, "Z"),
+  } satisfies Changes;
+  saveSessionState(sid, state, home);
+  // Emit the mandatory reminder ONCE per (file+session) burst: the ~11 sibling
+  // plugin hooks of one PostToolUse event would otherwise inject it ~11× (token
+  // noise). A real re-edit past the window reminds again. See burst-window.
+  // Exclusive mode (not the JSON oncePerWindow): this call is exactly the
+  // high-concurrency shape that mode is best-effort against under the real
+  // ~11-process fan-out (lesson 2026-07-05 16:00).
+  if (!onceExclusive(`sniper:${sid}:${filePath}`, BURST_DEDUP_MS, { now, dir: sessionsDir(home) })) return "";
+  const fname = basename(filePath);
+  const stdout = contextResponse(
+    "PostToolUse",
+    `SNIPER VALIDATION REQUIRED: Code file '${fname}' was modified. You MUST now run the sniper agent (fuse-ai-pilot:sniper) to validate this modification before continuing. This is mandatory per CLAUDE.md rules.`,
+  );
+  // User-visible companion to the additionalContext reminder above (which only
+  // reaches the agent, never the human) — rides the SAME oncePerWindow gate above,
+  // so the ×11 hook fan-out never duplicates it.
+  return attachSystemMessage(stdout, sniperRequiredNotice(fname));
+}

package/src/runtime/lifecycle/validate-solid.ts

@@ -0,0 +1,70 @@
+/**
+ * PreToolUse (matcher "Write|Edit") for the solid scope: deny a Go top-level
+ * interface or a Python `ABC` subclass defined outside its language's
+ * `/interfaces/` directory. Ports `solid/scripts/validate-solid.py`'s
+ * `check_go`/`check_python` only — its `check_nextjs`/`check_laravel`/
+ * `check_swift` siblings are NOT ported here: they are a strict subset of the
+ * already-ported `framework-solid-gates.ts` (react/nextjs/laravel/swift),
+ * which fire unconditionally on file extension/content rather than being
+ * gated behind `SOLID_PROJECT_TYPE`. Inert when `SOLID_PROJECT_TYPE` is
+ * absent/"unknown"/nextjs/laravel/swift/rust (parity: the Python hook only
+ * has a `go`/`python` validator).
+ *
+ * Detection rides the conventions module (MASKED content, column-0 anchored
+ * for Go): the old naive regexes matched inside comments/strings and
+ * indented locals — all killed. LEGACY-level detections keep the exact hard
+ * deny (byte-parity); EXTENDED-level ones (Go `interface{` without the
+ * space, Python `Protocol`) follow `FUSE_CONVENTIONS_MODE` — advisory
+ * (non-blocking additionalContext) by default, deny only on `"deny"`
+ * (owner Amendment 5, external audit D0.2).
+ */
+import { contextResponse, denyResponse } from "../../adapters/claude";
+import { interfaceDeclLevel } from "../../policy/conventions/interfaces";
+import { conventionsMode } from "../../policy/conventions/verdict";
+
+/** Go: deny a top-level interface declared outside `/interfaces/`. */
+function checkGo(filePath: string, content: string, env: Record<string, string | undefined>): string | null {
+  if (!filePath.endsWith(".go") || filePath.includes("/interfaces/")) return null;
+  const level = interfaceDeclLevel(filePath, content);
+  if (level === null) return null;
+  const msg = "SOLID: Interfaces must be in internal/interfaces/";
+  if (level === "legacy" || conventionsMode(env) === "deny") return denyResponse("PreToolUse", msg);
+  return contextResponse("PreToolUse", msg);
+}
+
+/** Python: deny an ABC subclass declared outside `/interfaces/`. */
+function checkPython(filePath: string, content: string, env: Record<string, string | undefined>): string | null {
+  if (!filePath.endsWith(".py") || filePath.includes("/interfaces/")) return null;
+  const level = interfaceDeclLevel(filePath, content);
+  if (level === null) return null;
+  const msg = "SOLID: Abstract classes must be in src/interfaces/";
+  if (level === "legacy" || conventionsMode(env) === "deny") return denyResponse("PreToolUse", msg);
+  return contextResponse("PreToolUse", msg);
+}
+
+/** `SOLID_PROJECT_TYPE` values this gate validates (parity subset — see module doc). */
+const VALIDATORS: Record<string, (filePath: string, content: string, env: Record<string, string | undefined>) => string | null> = {
+  go: checkGo,
+  python: checkPython,
+};
+
+/**
+ * Deny (or advise on) a Write/Edit that violates the Go/Python interface-location SOLID rule.
+ * @param tool - The tool name (only "Write"/"Edit" are checked).
+ * @param filePath - The written file's absolute path.
+ * @param content - The written/edited content (`new_string` snippet on Edit).
+ * @param env - Environment (defaults to `process.env`).
+ * @returns The PreToolUse response, or `""` when clean/inert.
+ */
+export function validateSolidGate(
+  tool: string,
+  filePath: string,
+  content: string,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  const ptype = env.SOLID_PROJECT_TYPE ?? "";
+  if (!ptype || ptype === "unknown") return "";
+  if (tool !== "Write" && tool !== "Edit") return "";
+  if (!filePath) return "";
+  return VALIDATORS[ptype]?.(filePath, content, env) ?? "";
+}