@fusengine/harness 0.1.90 → 0.1.92

package/src/runtime/lifecycle/seo/post-tool-use.ts

@@ -0,0 +1,45 @@
+/**
+ * SEO PostToolUse handler (fs effects). Ports `seo/hooks/validate-seo.ts`: on an
+ * edited HTML-like file under a `.fuse-seo` marker, deny when SEO elements are
+ * missing. Opt-in only — silent when no marker / non-HTML / file unreadable.
+ */
+import { readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { isHtmlLike, missingSeoElements } from "../../../policy/seo/validate";
+import { blockResponse } from "../../../adapters/claude";
+import { walkUpFor } from "../../../util/project-root";
+
+/**
+ * Validate the edited file's SEO completeness. Returns a block message (for a
+ * top-level `decision: block` response) when HTML-like, opted-in, and missing
+ * elements; otherwise `null` (allow).
+ * @param payload - The raw PostToolUse payload.
+ * @returns The block reason string, or `null` to allow.
+ */
+export function seoPostToolUse(payload: Record<string, unknown>): string | null {
+  const input = payload.tool_input as { file_path?: string } | undefined;
+  const path = input?.file_path;
+  if (!path || !isHtmlLike(path)) return null;
+  const cwd = typeof payload.cwd === "string" ? payload.cwd : dirname(path);
+  if (!walkUpFor(cwd, ".fuse-seo")) return null;
+  try {
+    const missing = missingSeoElements(readFileSync(path, "utf-8"));
+    if (missing.length === 0) return null;
+    return `fuse-seo: missing SEO elements in ${path}:\n  - ${missing.join("\n  - ")}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * SEO PostToolUse as a ready native response: a top-level `decision: block`
+ * string when the edited file is missing SEO elements, else `null` (allow).
+ * PostToolUse ignores `permissionDecision` (PreToolUse-only), so this must use
+ * the `decision`/`reason` keys to actually feed the failure back to Claude.
+ * @param payload - The raw PostToolUse payload.
+ * @returns The block response string, or `null` to allow.
+ */
+export function seoPostToolUseResponse(payload: Record<string, unknown>): string | null {
+  const block = seoPostToolUse(payload);
+  return block ? blockResponse(block) : null;
+}

package/src/runtime/lifecycle/session-end.ts

@@ -0,0 +1,17 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { fusengineCache } from "../home-state";
+import { removeOldFiles } from "../fs-cleanup";
+
+/**
+ * Handle SessionEnd: remove stale `*.tmp` (>1h) under `session-tmp/` and stale
+ * legacy `claude_solid_reads_*` / `claude_session_changes_*` files (>2h) under
+ * `cache`. Ports `session-end/cleanup-session.py`. No stdout.
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock (defaults to `Date.now()`).
+ */
+export function cleanupSession(home: string = homedir(), now: number = Date.now()): void {
+  const base = fusengineCache(home);
+  removeOldFiles(join(base, "session-tmp"), (n) => n.endsWith(".tmp"), 3600, now);
+  removeOldFiles(base, (n) => n.startsWith("claude_solid_reads_") || n.startsWith("claude_session_changes_"), 7200, now);
+}

package/src/runtime/lifecycle/session-start.ts

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { attachSystemMessage, contextResponse } from "../../adapters/claude";
+import { claudeHome, fusengineCache, sessionsDir } from "../home-state";
+import { devContext } from "../dev-context";
+import { pruneEmptyDirs, purgeTtlTree, removeOldFiles, trimLogFile } from "../fs-cleanup";
+import { apexDocName, harnessHomeSegment } from "../../policy/apex-target";
+
+/** TTLs (seconds) for purgeable cache subtrees (cleanup-old-caches.py). */
+const PURGEABLE: Record<string, number> = { sessions: 48 * 3600, webfetch: 24 * 3600, doc: 48 * 3600, explore: 48 * 3600 };
+
+/**
+ * Read the target's root instructions doc (`~/.claude/CLAUDE.md`,
+ * `~/.codex/AGENTS.md`, `~/.kimi-code/AGENTS.md`, ...), or "" when
+ * missing/unreadable.
+ * @param home - Home dir.
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ */
+function claudeMd(home: string, id: string = "claude-code"): string {
+  const path = join(home, harnessHomeSegment(id), apexDocName(id));
+  try {
+    return existsSync(path) ? readFileSync(path, "utf-8") : "";
+  } catch {
+    return "";
+  }
+}
+
+/** Run the legacy SessionStart cleanups (stale states, caches, log trim). */
+export function runSessionStartCleanups(home: string = homedir(), now: number = Date.now()): void {
+  const base = fusengineCache(home);
+  removeOldFiles(sessionsDir(home), (n) => n.startsWith("session-") && n.endsWith(".json"), 86400, now);
+  const user = process.env.USER ?? "unknown";
+  removeOldFiles(base, (n) => n === `changes-${user}.json`, 21600, now);
+  trimLogFile(join(claudeHome(home), "logs", "hooks.log"), 10485760, 5000);
+  removeOldFiles(join(claudeHome(home), "logs", "00-apex"), (n) => n.startsWith("ref-cache-") && n.endsWith(".json"), 86400, now);
+  purgeTtlTree(base, PURGEABLE, now);
+  pruneEmptyDirs(base, Object.keys(PURGEABLE));
+}
+
+/**
+ * Handle core-guards SessionStart: inject CLAUDE.md + dev context as
+ * `additionalContext`, then run the cache/state cleanups. Ports the four
+ * `session-start/*.py` scripts into one harness call.
+ * @param cwd - Project root for dev-context detection.
+ * @param home - Home dir (defaults to `~`).
+ * @param now - Clock for TTL cleanup (defaults to `Date.now()`).
+ * @param id - Harness target id (defaults to "claude-code" — zero-regression default).
+ * @returns The native hook stdout (possibly empty).
+ */
+export function sessionStartCore(cwd: string, home: string = homedir(), now: number = Date.now(), id: string = "claude-code"): string {
+  const md = claudeMd(home, id);
+  const dev = devContext(cwd);
+  runSessionStartCleanups(home, now);
+  const ctx = [md, dev].filter(Boolean).join("\n");
+  return ctx ? attachSystemMessage(contextResponse("SessionStart", ctx), `${apexDocName(id)} injected`) : "";
+}

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

@@ -0,0 +1,27 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Max board characters injected — a persistent board should stay small; over-long boards are truncated. */
+const MAX_BOARD = 4000;
+
+/**
+ * Collect the persistent task board: the contents of `<root>/.claude/BOARD.md`
+ * (truncated to {@link MAX_BOARD}) plus an instruction to keep it current. The
+ * board lives on disk so it survives context purges — rehydrated every session.
+ * Missing/empty/unreadable board → `""` (section omitted).
+ * @param root - The project root.
+ * @returns The rendered board section body, or `""` when there is no board.
+ */
+export function collectBoard(root: string): string {
+  const path = join(root, ".claude", "BOARD.md");
+  try {
+    if (!existsSync(path)) return "";
+    let body = readFileSync(path, "utf8").trim();
+    if (!body) return "";
+    if (body.length > MAX_BOARD) body = `${body.slice(0, MAX_BOARD)}\n… (truncated)`;
+    const note = "- .claude/BOARD.md (keep current — Write to it as tasks start/finish):";
+    return `${note}\n\n${body}`;
+  } catch {
+    return "";
+  }
+}

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

@@ -0,0 +1,60 @@
+import { contextResponse } from "../../../adapters/claude";
+import { capFragment, budgetReport } from "../../inject-budget";
+
+/** A titled snapshot section — dropped from the render when its `body` is empty. */
+export interface Section {
+  title: string;
+  body: string;
+}
+
+/**
+ * Render the non-empty `sections` under one reconciliation heading. Empty
+ * sections are dropped; when every section is empty the whole snapshot is `""`.
+ * Each surviving section is passed through {@link capFragment} (harness-produced
+ * content, not owner CLAUDE.md), and a trailing {@link budgetReport} line gives
+ * the owner-requested numeric visibility into what was actually injected.
+ * @param sections - The collected sections in display order.
+ * @returns The assembled markdown block, or `""` when nothing to report.
+ */
+export function renderSections(sections: Section[]): string {
+  const kept = sections
+    .filter((s) => s.body.trim())
+    .map((s) => ({ title: s.title, body: capFragment(s.title, s.body.trim()) }));
+  if (!kept.length) return "";
+  const header =
+    "# Reconciliation snapshot\nReal state of the world at session start — reconcile against this instead of re-discovering it.";
+  const parts = kept.map((s) => `### ${s.title}\n${s.body}`);
+  const report = budgetReport(kept.map((s) => ({ label: s.title, chars: s.body.length })));
+  return `${header}\n\n${parts.join("\n\n")}\n\n_${report}_`;
+}
+
+/**
+ * Concatenate `snapshot` onto an existing SessionStart stdout's
+ * `additionalContext` — it never replaces prior injected context (CLAUDE.md,
+ * dev-context). When `stdout` is empty a fresh {@link contextResponse} is made;
+ * a non-empty but unparseable `stdout` is returned UNCHANGED (the snapshot is
+ * dropped) — fabricating a fresh response there would discard the very CLAUDE.md
+ * injection the invariant protects, so preserving prior context always wins.
+ * @param stdout - The core SessionStart JSON stdout (may be `""`).
+ * @param snapshot - The snapshot markdown to append (no-op when `""`).
+ * @returns The merged hook stdout JSON.
+ */
+export function attachSnapshot(stdout: string, snapshot: string): string {
+  if (!snapshot) return stdout;
+  if (!stdout) return contextResponse("SessionStart", snapshot);
+  try {
+    const parsed = JSON.parse(stdout) as {
+      hookSpecificOutput?: { additionalContext?: string };
+    };
+    const prev = parsed.hookSpecificOutput?.additionalContext ?? "";
+    const merged = prev ? `${prev}\n\n${snapshot}` : snapshot;
+    return JSON.stringify({
+      ...parsed,
+      hookSpecificOutput: { ...parsed.hookSpecificOutput, hookEventName: "SessionStart", additionalContext: merged },
+    });
+  } catch {
+    // Unparseable non-empty stdout: keep it verbatim so prior injected context
+    // (CLAUDE.md) is never discarded — the snapshot is sacrificed, not the invariant.
+    return stdout;
+  }
+}

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);
+}