@fusengine/harness 0.1.89 → 0.1.91

package/src/adapters/hermes/interfaces/types.ts

@@ -0,0 +1,26 @@
+/**
+ * Hermes Agent (NousResearch/hermes-agent) shell-hook wire types. Verified 2026
+ * against hermes-agent.nousresearch.com/docs/user-guide/features/hooks: hooks
+ * are configured in `~/.hermes/config.yaml` under `hooks:`, receive a JSON
+ * payload on stdin, and answer with JSON on stdout.
+ */
+
+/** `pre_tool_call` stdin payload (subset). Same wire shape as Claude Code. */
+export interface HermesHookInput {
+  hook_event_name?: string;
+  tool_name?: string;
+  tool_input?: { path?: string; file_path?: string; content?: string; command?: string | string[] };
+  session_id?: string;
+  cwd?: string;
+}
+
+/**
+ * Hook stdout response. `{}` allows; `{ decision: "block", reason }` cancels
+ * the tool call; `{ context }` injects LLM context (honored on `pre_llm_call`).
+ * Hermes has NO Claude-style `permissionDecision` and no interactive "ask".
+ */
+export interface HermesResponse {
+  decision?: "block";
+  reason?: string;
+  context?: string;
+}

package/src/adapters/kimi/index.ts

@@ -0,0 +1,96 @@
+/**
+ * Kimi Code CLI adapter (hook-mode). Moonshot AI's Kimi Code CLI (v0.27.0,
+ * 2026) configures hooks in `~/.kimi-code/config.toml` (`[[hooks]]`: event,
+ * matcher, command, timeout — exactly 4 fields, any extra breaks config
+ * loading) and pipes a JSON payload to `command` on stdin, reading JSON back
+ * on stdout. Verified against kimi.com/code/docs/en/kimi-code-cli/
+ * customization/hooks.html (2026): the INPUT base shape
+ * (`hook_event_name`/`session_id`/`cwd`, `PreToolUse`/`Bash` carrying
+ * `tool_name` + `tool_input.command`) matches Claude Code's snake_case wire
+ * shape, so the Claude reader is reused — verified live against kimi-code
+ * v0.27.0 for both `PreToolUse`/`Bash` and `PreToolUse`/`Write`. Tool fields
+ * verified: `Bash` takes `command`; `Write` takes `path` + `content`; `Edit`
+ * takes `path` + `old_string`/`new_string` (per `docs/en/reference/tools.md`,
+ * moonshotai/kimi-code). The path key is `path`, NOT Claude's `file_path`
+ * (see interfaces/types.ts).
+ *
+ * OUTPUT does not match Claude: only `UserPromptSubmit`, `PreToolUse`, `Stop`
+ * are blockable, and the only documented decision is
+ * `{"hookSpecificOutput":{"permissionDecision":"deny","permissionDecisionReason"}}`
+ * (camelCase, despite the snake_case input — a real Kimi inconsistency). No
+ * `"ask"`/`"allow"`/`additionalContext` is documented. Verified live against
+ * kimi-code v0.27.0: that deny envelope on stdout at exit 0 blocks the call
+ * (exit 2 is NOT required) and `permissionDecisionReason` is re-injected to
+ * the model; empty stdout at exit 0 lets the call run. Exit 2 = block, stderr
+ * = reason; any other exit/timeout/crash fails open (allow). Whether raw-text
+ * stdout at exit 0 (the `inform` case) reaches the context is documented only
+ * as "may be" — unverified, needs live test.
+ */
+import { evaluate } from "../../policy/evaluate";
+import { formatPrompt, type Prompt } from "../../prompt/types";
+import { readClaudeInput } from "../claude";
+import { commandToString } from "../../runtime/command-string";
+import type { KimiHookInput, KimiResponse } from "./interfaces/types";
+
+export type { KimiHookInput, KimiResponse } from "./interfaces/types";
+
+/**
+ * Downgrade prefix for `ask` — Kimi has no interactive approval channel
+ * reachable from a hook. Kimi DOES have an `ask` decision, but only via
+ * `[[permission.rules]] decision = "ask"` in config.toml, a separate system
+ * a hook's return value cannot invoke.
+ */
+const ASK_PREFIX = "[downgraded from ask — Kimi Code has no interactive approval]";
+
+/** Read & parse the Kimi hook stdin payload (same wire shape as Claude for the fields we consume). */
+export async function readKimiInput(): Promise<KimiHookInput> {
+  return await readClaudeInput();
+}
+
+/**
+ * Render a portable {@link Prompt} as a Kimi hook response string:
+ * `block`/`ask` -> `{hookSpecificOutput:{permissionDecision:"deny",...}}`
+ * (only `"deny"` is documented; `ask` is downgraded with {@link ASK_PREFIX});
+ * `inform` -> raw text (Kimi appends stdout to context on exit 0 — no
+ * documented JSON envelope for non-blocking context injection).
+ * @param prompt - The portable policy prompt.
+ * @returns The native Kimi response string.
+ */
+export function toKimiResponse(prompt: Prompt): string {
+  const msg = formatPrompt(prompt);
+  if (prompt.kind === "inform") return msg;
+  const reason = prompt.kind === "ask" ? `${ASK_PREFIX}\n${msg}` : msg;
+  const res: KimiResponse = { hookSpecificOutput: { permissionDecision: "deny", permissionDecisionReason: reason } };
+  return JSON.stringify(res);
+}
+
+/**
+ * Render a raw deny reason as a Kimi hook response — for callers that already
+ * hold a fully-formatted message (e.g. the MCP cache-hit notice) rather than a
+ * portable {@link Prompt}. Same envelope as {@link toKimiResponse}, minus the
+ * `[BLOCKED]` prompt framing and without `hookEventName` (undocumented upstream).
+ * @param reason - The fully-formatted deny message.
+ * @returns The native Kimi response string.
+ */
+export function kimiDenyResponse(reason: string): string {
+  const res: KimiResponse = { hookSpecificOutput: { permissionDecision: "deny", permissionDecisionReason: reason } };
+  return JSON.stringify(res);
+}
+
+/**
+ * Run the bundled policy over a Kimi hook payload and return the native
+ * response string, or null to allow (the hook then exits 0 with empty stdout).
+ * @param input - Parsed hook stdin payload.
+ * @returns Native response string, or null when the tool use is allowed.
+ */
+export function guard(input: KimiHookInput): string | null {
+  const t = input.tool_input;
+  const r = evaluate({
+    tool: input.tool_name ?? "Write",
+    filePath: t?.path ?? t?.file_path,
+    content: t?.content ?? t?.new_string,
+    command: commandToString(t?.command),
+  });
+  if (r.decision === "allow" || !r.prompt) return null;
+  return toKimiResponse(r.prompt);
+}

package/src/adapters/kimi/interfaces/types.ts

@@ -0,0 +1,55 @@
+/**
+ * Kimi Code CLI shell-hook wire types. Verified 2026 against
+ * kimi.com/code/docs/en/kimi-code-cli/customization/hooks.html (v0.27.0):
+ * hooks are configured in `~/.kimi-code/config.toml` under `[[hooks]]`,
+ * receive a snake_case JSON payload on stdin, and answer with a camelCase
+ * JSON envelope on stdout (a real, documented casing inconsistency).
+ */
+
+/**
+ * `PreToolUse`/`UserPromptSubmit`/`Stop` stdin payload (subset). Same base
+ * wire shape as Claude Code (`hook_event_name`/`tool_name`/`tool_input`/
+ * `cwd`); `tool_input.command` is confirmed for `Bash` by the docs' example
+ * script (`payload.tool_input?.command`). Verified live against kimi-code
+ * v0.27.0 on `PreToolUse`/`Bash`: `tool_name` is present at top level (the
+ * docs never name it as a stdin key) and `tool_input.command` carries the
+ * shell string. The live payload also carries an UNDOCUMENTED `tool_call_id`
+ * (e.g. `"tool_LsTnl0gBxM62XuWvKw0GFGHs"`); the harness does not consume it,
+ * so it is deliberately absent from this interface. `cwd` is the
+ * symlink-resolved path (macOS: `/private/tmp/…` for a shell in `/tmp/…`).
+ */
+export interface KimiHookInput {
+  hook_event_name?: string;
+  tool_name?: string;
+  /**
+   * Verified against the official tool reference (`docs/en/reference/tools.md`,
+   * moonshotai/kimi-code) AND live against kimi-code v0.27.0: `Write` sends
+   * `{ path, content, mode? }`, `Edit` sends
+   * `{ path, old_string, new_string, replace_all? }` — the path key is `path`,
+   * NOT Claude's `file_path`. `file_path` is kept as a tolerated alias (read
+   * second) for Claude-shaped replay payloads, mirroring
+   * `runtime/normalize.ts` which resolves both on the CLI path.
+   */
+  tool_input?: {
+    path?: string;
+    file_path?: string;
+    content?: string;
+    new_string?: string;
+    command?: string | string[];
+  };
+  session_id?: string;
+  cwd?: string;
+}
+
+/**
+ * Hook stdout response. Only `"deny"` is documented for `permissionDecision`
+ * — no `"ask"`/`"allow"` value, and no `additionalContext` field exists on
+ * this envelope. Blocking events are `UserPromptSubmit`, `PreToolUse`, and
+ * `Stop` only; every other event's return value is ignored.
+ */
+export interface KimiResponse {
+  hookSpecificOutput?: {
+    permissionDecision?: "deny";
+    permissionDecisionReason?: string;
+  };
+}

package/src/cache/compact.ts

@@ -0,0 +1,55 @@
+import { createHash } from "node:crypto";
+
+const HTML_ENTITIES: Record<string, string> = {
+  "&amp;": "&", "&lt;": "<", "&gt;": ">", "&quot;": '"',
+  "&#x27;": "'", "&#39;": "'", "&nbsp;": " ", "&apos;": "'",
+};
+
+const BOILERPLATE: RegExp[] = [
+  /^.*cookie.*(accept|consent|banner).*$/gim,
+  /^.*was this (helpful|page helpful|article helpful).*$/gim,
+  /^.*©\s*\d{4}.*all rights reserved.*$/gim,
+  /^\s*(home|about|contact|privacy|terms)\s*\|\s*.*$/gim,
+  /^.*subscribe to (our )?newsletter.*$/gim,
+  /^.*follow us on (twitter|facebook|linkedin).*$/gim,
+];
+
+const MAX_BYTES = 5 * 1024;
+
+function decodeEntities(text: string): string {
+  let out = text;
+  for (const [ent, ch] of Object.entries(HTML_ENTITIES)) out = out.split(ent).join(ch);
+  out = out.replace(/&#x([0-9a-fA-F]+);/g, (_m, h: string) => String.fromCodePoint(parseInt(h, 16)));
+  out = out.replace(/&#(\d+);/g, (_m, d: string) => String.fromCodePoint(parseInt(d, 10)));
+  return out;
+}
+
+/** Strip HTML entities + boilerplate, normalize blank lines, truncate to ~5KB. */
+export function compactMarkdown(content: string): string {
+  let text = decodeEntities(content);
+  for (const re of BOILERPLATE) text = text.replace(re, "");
+  text = text.replace(/\n{3,}/g, "\n\n").trim();
+  const enc = new TextEncoder().encode(text);
+  if (enc.length > MAX_BYTES) {
+    const truncated = new TextDecoder().decode(enc.slice(0, MAX_BYTES));
+    const remaining = text.slice(truncated.length).split("\n").length - 1;
+    text = `${truncated}\n\n[... truncated, ${remaining} lines]`;
+  }
+  return text;
+}
+
+/** 8-char MD5 of `${toolName}::${query}`. */
+export function queryHash(toolName: string, query: string): string {
+  return createHash("md5").update(`${toolName}::${query}`).digest("hex").slice(0, 8);
+}
+
+/** Bag-of-words Jaccard similarity strictly greater than `threshold`. */
+export function jaccardSimilar(a: string, b: string, threshold = 0.8): boolean {
+  const ta = new Set(a.toLowerCase().split(/\s+/).filter(Boolean));
+  const tb = new Set(b.toLowerCase().split(/\s+/).filter(Boolean));
+  if (ta.size === 0 || tb.size === 0) return false;
+  let inter = 0;
+  for (const t of ta) if (tb.has(t)) inter++;
+  const union = ta.size + tb.size - inter;
+  return inter / union > threshold;
+}

package/src/cache/index.ts

@@ -0,0 +1,5 @@
+export * from "./compact";
+export * from "./io";
+export * from "./mcp-response";
+export * from "./mcp-store";
+export * from "./store";

package/src/cache/io.ts

@@ -0,0 +1,38 @@
+import { existsSync, readFileSync } from "node:fs";
+
+/** Read a JSON array from `path`; [] on missing/corrupt/non-array. */
+export function loadIndex(path: string): unknown[] {
+  try {
+    if (!existsSync(path)) return [];
+    const data: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return Array.isArray(data) ? data : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Summary of a cache index. */
+export interface IndexSummary {
+  total: number;
+  byTool: Record<string, number>;
+  oldestTs: string | null;
+  newestTs: string | null;
+}
+
+/** Summarize an index of `{ tool?, ts? }` entries. */
+export function summarizeIndex(index: unknown[]): IndexSummary {
+  const byTool: Record<string, number> = {};
+  const timestamps: string[] = [];
+  for (const entry of index) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const e = entry as { tool?: unknown; ts?: unknown };
+    if (typeof e.tool === "string") byTool[e.tool] = (byTool[e.tool] ?? 0) + 1;
+    if (typeof e.ts === "string") timestamps.push(e.ts);
+  }
+  return {
+    total: index.length,
+    byTool,
+    oldestTs: timestamps.length ? timestamps.reduce((a, b) => (a < b ? a : b)) : null,
+    newestTs: timestamps.length ? timestamps.reduce((a, b) => (a > b ? a : b)) : null,
+  };
+}

package/src/cache/mcp-response.ts

@@ -0,0 +1,39 @@
+const MAX_DEPTH = 5;
+
+interface TextBlock {
+  type?: string;
+  text?: string;
+}
+
+/**
+ * Extract usable markdown from an MCP `tool_response`: a string, a list of
+ * content blocks (non-text blocks skipped), or any JSON structure (fallback).
+ * Recurses up to depth 5 to guard against pathological/cyclic structures.
+ */
+export function extractText(resp: unknown, depth = 0): string {
+  if (depth >= MAX_DEPTH) return "";
+  if (typeof resp === "string") return resp;
+  if (Array.isArray(resp)) {
+    const parts = resp
+      .filter((b): b is TextBlock => typeof b === "object" && b !== null)
+      .filter((b) => b.type === "text")
+      .map((b) => b.text ?? "");
+    if (parts.length) return parts.join("\n\n");
+    const nested = resp
+      .filter((b) => Array.isArray(b) || (typeof b === "object" && b !== null))
+      .map((b) => extractText(b, depth + 1));
+    const joined = nested.filter(Boolean).join("\n\n");
+    if (joined) return joined;
+  }
+  if (!resp) return "";
+  try {
+    // Stable key order (mirrors Python `json.dumps(sort_keys=True)`) so cache
+    // keys derived from this fallback text are deterministic across key orders.
+    return JSON.stringify(resp, (_k, v) =>
+      v !== null && typeof v === "object" && !Array.isArray(v)
+        ? Object.fromEntries(Object.entries(v as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)))
+        : v);
+  } catch {
+    return "";
+  }
+}

package/src/cache/mcp-store.ts

@@ -0,0 +1,70 @@
+import { join } from "node:path";
+import { atomicWrite } from "../util/json-io";
+import { compactMarkdown, jaccardSimilar, queryHash } from "./compact";
+import { loadIndex } from "./io";
+import { cacheStore } from "./store";
+
+/** A persisted MCP cache index entry. */
+interface IndexEntry {
+  tool: string;
+  query: string;
+  hash: string;
+  ts: string;
+}
+
+/** UTC timestamp `YYYY-MM-DDTHH:MM:SSZ` (no millis), mirroring the Python store. */
+function stamp(now: number): string {
+  return new Date(now).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+/** True when a Jaccard-similar query already exists for `tool` in `index`. */
+function isDuplicate(index: unknown[], tool: string, query: string): boolean {
+  return index.some((e) => {
+    if (typeof e !== "object" || e === null) return false;
+    const r = e as { tool?: unknown; query?: unknown };
+    return r.tool === tool && typeof r.query === "string" && jaccardSimilar(r.query, query);
+  });
+}
+
+/**
+ * Persist an MCP doc result the way `cache-mcp-result.py` does: compact the body,
+ * skip Jaccard-duplicate queries, write a front-matter `.md` (exact FNV key, so
+ * {@link cacheLookup} still hits) carrying the query for substring lookups, and
+ * append the entry to `index.json`. No-op on empty body or duplicate query.
+ * @param dir - Cache directory (also holds `index.json`).
+ * @param tool - MCP tool id.
+ * @param query - Doc query that keys the entry.
+ * @param body - Raw response text (compacted before write).
+ * @param now - Current epoch ms (timestamp source).
+ */
+export function mcpCacheWrite(dir: string, tool: string, query: string, body: string, now: number): void {
+  const compacted = compactMarkdown(body);
+  if (!compacted) return;
+  const indexPath = join(dir, "index.json");
+  const index = loadIndex(indexPath);
+  if (isDuplicate(index, tool, query)) return;
+  const hash = queryHash(tool, query);
+  const ts = stamp(now);
+  const front = `---\ntool: ${tool}\nquery: ${JSON.stringify(query)}\nts: ${ts}\nhash: ${hash}\n---\n\n`;
+  cacheStore(dir, tool, query, front + compacted);
+  index.push({ tool, query, hash, ts } satisfies IndexEntry);
+  atomicWrite(indexPath, JSON.stringify(index, null, 2));
+}
+
+/**
+ * Persist a WebFetch result the way `webfetch-cache-store.py` does: compact the
+ * body, write a front-matter `.md` keyed by `key` (url + prompt[:500]). No index
+ * and no dedup — WebFetch entries are exact-key only. No-op on empty body.
+ * @param dir - Cache directory.
+ * @param tool - Always `WebFetch`.
+ * @param key - The url+prompt cache key string.
+ * @param body - Raw response text (compacted before write).
+ * @param now - Current epoch ms (timestamp source).
+ */
+export function webfetchCacheWrite(dir: string, tool: string, key: string, body: string, now: number): void {
+  const compacted = compactMarkdown(body);
+  if (!compacted) return;
+  const hash = queryHash(tool, key);
+  const front = `---\ntool: ${tool}\nkey: ${JSON.stringify(key)}\nts: ${stamp(now)}\nhash: ${hash}\n---\n\n`;
+  cacheStore(dir, tool, key, front + compacted);
+}

package/src/cache/store.ts

@@ -0,0 +1,93 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Max body bytes read on a substring lookup (parity with mcp-cache-lookup.py MAX_BODY). */
+const MAX_BODY = 8 * 1024;
+/** Needle length scanned on a substring lookup (first 80 query chars, ripgrep-aligned). */
+const NEEDLE_LEN = 80;
+
+/** Stable 16-char key from a tool name + query (FNV-1a, non-crypto). */
+export function mcpCacheKey(tool: string, query: string): string {
+  const s = `${tool}\n${query}`;
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0") + (s.length >>> 0).toString(16).padStart(8, "0");
+}
+
+/** Path of a cache entry under `dir`. */
+export function cachePath(dir: string, tool: string, query: string): string {
+  return join(dir, `${mcpCacheKey(tool, query)}.md`);
+}
+
+/** A cache hit's body plus its age in ms (now − mtime), for caller-side reporting. */
+export interface CacheHit {
+  body: string;
+  ageMs: number;
+}
+
+/** Read a cached entry if it exists and is fresh (mtime within `ttlMs`), else null. */
+export function cacheLookup(dir: string, tool: string, query: string, ttlMs: number, now: number): string | null {
+  return cacheLookupMeta(dir, tool, query, ttlMs, now)?.body ?? null;
+}
+
+/** Like {@link cacheLookup}, but also reports the entry's age (for `CACHE HIT` wrapper text). */
+export function cacheLookupMeta(dir: string, tool: string, query: string, ttlMs: number, now: number): CacheHit | null {
+  const path = cachePath(dir, tool, query);
+  try {
+    if (!existsSync(path)) return null;
+    const ageMs = now - statSync(path).mtimeMs;
+    if (ageMs > ttlMs) return null;
+    return { body: readFileSync(path, "utf8").slice(0, MAX_BODY), ageMs };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * First fresh cache file whose body contains the (normalized, case-insensitive)
+ * query substring, else null. Relaxes the exact-key match to lift the hit-rate —
+ * parity with `mcp-cache-lookup.py` (`rg -i -F` over the first 80 query chars).
+ * @param dir - Cache directory to scan.
+ * @param query - Raw query; newlines folded to spaces, truncated to 80 chars.
+ * @param ttlMs - Freshness window (mtime-based).
+ * @param now - Current epoch ms.
+ */
+export function cacheLookupSubstring(dir: string, query: string, ttlMs: number, now: number): string | null {
+  return cacheLookupSubstringMeta(dir, query, ttlMs, now)?.body ?? null;
+}
+
+/** Like {@link cacheLookupSubstring}, but also reports the matched entry's age. */
+export function cacheLookupSubstringMeta(dir: string, query: string, ttlMs: number, now: number): CacheHit | null {
+  const needle = query.replace(/[\r\n]+/g, " ").slice(0, NEEDLE_LEN).trim().toLowerCase();
+  if (!needle) return null;
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return null;
+  }
+  for (const name of names) {
+    if (!name.endsWith(".md")) continue;
+    const path = join(dir, name);
+    try {
+      const ageMs = now - statSync(path).mtimeMs;
+      if (ageMs > ttlMs) continue;
+      const body = readFileSync(path, "utf8").slice(0, MAX_BODY);
+      if (body.toLowerCase().includes(needle)) return { body, ageMs };
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/** Store a cache entry (creates the dir; no-op on empty content). */
+export function cacheStore(dir: string, tool: string, query: string, content: string): void {
+  if (!content) return;
+  const path = cachePath(dir, tool, query);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content);
+}

package/src/changelog/fetch.ts

@@ -0,0 +1,79 @@
+/**
+ * Changelog scanner — ports the changelog-watcher plugin's `fetch-changelog`
+ * into the harness (exposed as the `harness changelog` CLI verb). Fetches the
+ * official Claude Code changelog, detects how many versions are new since the
+ * last check, persists per-day state, and returns a JSON summary. Dual-runtime:
+ * global `fetch` + `node:fs` (works under Node 20+ and Bun, no imports needed).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { claudeHome } from "../runtime/home-state";
+import { todayUtc } from "../runtime/lifecycle/security/skill-state";
+
+const CHANGELOG_URL = "https://code.claude.com/docs/en/changelog.md";
+
+/** Summary printed by the CLI (and consumed by the changelog-scan skill). */
+export interface ChangelogScan {
+  latest: string;
+  new_since_last_check: number;
+  recent_versions: string[];
+}
+
+/** Persisted per-day state under `~/.claude/logs/00-changelog/`. */
+interface ChangelogState { last_version: string; previous: string; new_versions: number; checked: string }
+
+/**
+ * Parse up to 10 semver versions from the changelog, newest first. Matches the
+ * current docs format (`<Update label="X.Y.Z" …>` MDX blocks) AND the legacy
+ * markdown headers (`## vX.Y.Z` / `## X.Y.Z`) so it survives a format rollback.
+ */
+export function parseVersions(md: string): string[] {
+  const re = /<Update\s+label="v?(\d+\.\d+\.\d+)"|^##\s+v?(\d+\.\d+\.\d+)/gm;
+  return [...md.matchAll(re)].map((m) => m[1] ?? m[2] ?? "").filter(Boolean).slice(0, 10);
+}
+
+/** Count versions newer than `lastKnown` (stops at the first match). */
+export function countNew(versions: string[], lastKnown: string): number {
+  if (!lastKnown) return 0;
+  let n = 0;
+  for (const v of versions) { if (v === lastKnown) break; n++; }
+  return n;
+}
+
+/** Read the saved `last_version` for today's state file ("" when absent/corrupt). */
+function lastKnownVersion(stateFile: string): string {
+  if (!existsSync(stateFile)) return "";
+  try {
+    return (JSON.parse(readFileSync(stateFile, "utf8")) as ChangelogState).last_version ?? "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Fetch + parse the changelog, diff against the saved state, persist, and return
+ * the scan summary. Throws on network failure (the CLI maps it to exit 1).
+ * @param now - Clock (ms).
+ * @param home - Home dir.
+ */
+export async function scanChangelog(now: number = Date.now(), home: string = homedir()): Promise<ChangelogScan> {
+  const res = await fetch(CHANGELOG_URL, { signal: AbortSignal.timeout(10_000) });
+  if (!res.ok) throw new Error(`changelog fetch failed: ${res.status}`);
+  const versions = parseVersions(await res.text());
+  const latest = versions[0] ?? "";
+
+  const dir = join(claudeHome(home), "logs", "00-changelog");
+  const today = todayUtc(now);
+  const stateFile = join(dir, `${today}-state.json`);
+  const lastKnown = lastKnownVersion(stateFile);
+  const newCount = countNew(versions, lastKnown);
+
+  try {
+    mkdirSync(dir, { recursive: true });
+    const state: ChangelogState = { last_version: latest, previous: lastKnown, new_versions: newCount, checked: today };
+    writeFileSync(stateFile, JSON.stringify(state, null, 2));
+  } catch { /* best effort — the summary is still returned */ }
+
+  return { latest, new_since_last_check: newCount, recent_versions: versions };
+}

package/src/cli/bin.ts

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * harness — CLI for @fusengine/harness.
+ *   harness check          cli-mode: check staged files (pre-commit), exit non-zero on a violation
+ *   harness init [id]      write the wiring file for a harness (defaults to the detected one)
+ *   harness hook <id>      runtime: read a hook payload on stdin, route to the adapter, print the response
+ *   harness changelog      fetch + diff the Claude Code changelog, print a JSON summary (changelog-watcher)
+ *   harness codex-rules    generate a Codex execpolicy .rules (Starlark) file from security.ts; stdout or --out <path>
+ */
+import { detectHarness, type HarnessId } from "../detect/harness";
+import { initFor, writeInitFile } from "../init/run";
+import { scanChangelog } from "../changelog/fetch";
+import { runSecurityScan } from "../runtime/lifecycle/security/scan";
+import { buildCodexRules } from "../codex-rules";
+import { writeFileSync } from "node:fs";
+import { handleHook } from "../runtime/handle";
+import { resolveTtlSec } from "../config/ttl";
+import { loadDotenv } from "../config/dotenv";
+import { discoverRefs } from "../refs/discover";
+import { homedir } from "node:os";
+import { checkStaged, stagedContent, stagedFiles } from "./run";
+import { runDoctor, runningVersion, versionBanner } from "./doctor";
+import { parseScope } from "./scope";
+import { isMalformedCursorStdin, isOversize, oversizeStdout, readStdin, traceHook } from "./hook-io";
+import { maybePlaySound } from "./hook-sound";
+
+const cmd = process.argv[2];
+
+if (cmd === "--version" || cmd === "-v") {
+  process.stderr.write(versionBanner(import.meta.url) + "\n");
+  process.stdout.write(runningVersion(import.meta.url).version + "\n");
+  process.exit(0);
+} else if (cmd === "doctor") {
+  process.stderr.write(versionBanner(import.meta.url) + "\n");
+  process.exit(await runDoctor(import.meta.url));
+} else if (cmd === "hook") {
+  const id = process.argv[3] ?? detectHarness().id;
+  loadDotenv(id as HarnessId);
+  const scope = parseScope(process.argv[4]);
+  if (maybePlaySound(process.argv)) process.exit(0);
+  const marketplaces = (process.env.FUSE_HARNESS_MARKETPLACES ?? "fusengine-plugins").split(",").map((s) => s.trim()).filter(Boolean);
+  const refsDir = process.env.FUSE_HARNESS_REFS || discoverRefs(homedir(), process.cwd(), marketplaces) || undefined;
+  traceHook("args", { id, scope });
+  let outcome: Awaited<ReturnType<typeof handleHook>>;
+  try {
+    const stdin = await readStdin(id);
+    if (isOversize(stdin)) {
+      const stdout = oversizeStdout(id, stdin.head);
+      if (stdout) process.stdout.write(stdout);
+      process.exit(0);
+    }
+    if (isMalformedCursorStdin(stdin)) process.exit(1);
+    outcome = await handleHook(id, stdin, { now: Date.now(), cwd: process.cwd(), refsDir, windowMs: resolveTtlSec(process.env) * 1000, scope });
+  } catch (e) { traceHook("handleHook-threw", e instanceof Error ? `${e.message}\n${e.stack}` : String(e)); throw e; }
+  traceHook("outcome", { stdoutLength: outcome.stdout.length, exit: outcome.exit });
+  if (outcome.stdout) process.stdout.write(outcome.stdout);
+  process.exit(outcome.exit);
+} else if (cmd === "init") {
+  const id = (process.argv[3] as HarnessId | undefined) ?? detectHarness().id;
+  const files = initFor(id);
+  if (!files) {
+    process.stderr.write(`harness: no hook integration for "${id}" — use \`harness check\` in a pre-commit step\n`);
+    process.exit(1);
+  }
+  const written = files.map((f) => writeInitFile(process.cwd(), f));
+  process.stdout.write(`harness: wired ${id} -> ${written.join(", ")}\n`);
+  process.exit(0);
+} else if (cmd === "changelog") {
+  try {
+    process.stdout.write(JSON.stringify(await scanChangelog()) + "\n");
+    process.exit(0);
+  } catch (e) {
+    process.stdout.write(JSON.stringify({ status: "error", message: e instanceof Error ? e.message : "changelog fetch failed" }) + "\n");
+    process.exit(1);
+  }
+} else if (cmd === "scan") {
+  const dir = process.argv[3] ?? process.cwd();
+  process.stdout.write(JSON.stringify(runSecurityScan(dir), null, 2) + "\n");
+  process.exit(0);
+} else if (cmd === "codex-rules") {
+  const outIdx = process.argv.indexOf("--out");
+  const outPath = outIdx !== -1 ? process.argv[outIdx + 1] : undefined;
+  const rules = buildCodexRules();
+  if (outPath) {
+    writeFileSync(outPath, rules);
+    process.stderr.write(`harness: wrote Codex execpolicy rules -> ${outPath}\n`);
+  } else {
+    process.stdout.write(rules);
+  }
+  process.exit(0);
+} else {
+  const files = stagedFiles();
+  if (files.length === 0) process.exit(0);
+  const violations = checkStaged(files, stagedContent);
+  if (violations.length > 0) {
+    process.stderr.write(`harness check: policy violations\n\n${violations.join("\n\n")}\n`);
+    process.exit(1);
+  }
+  process.exit(0);
+}