@fusengine/harness 0.1.90 → 0.1.92

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

package/src/cli/cursor-event-scanner.ts

@@ -0,0 +1,175 @@
+import { JsonPrimitiveScanner } from "./json-primitive-scanner";
+
+/**
+ * Fixed cardinality bounds used by the incremental Cursor JSON scanner.
+ * `maxDepth` counts simultaneously open containers. Deeper valid JSON remains
+ * indeterminate and the oversized Cursor path fails closed.
+ */
+export const CURSOR_SCANNER_LIMITS = { tokenEntries: 256, maxDepth: 1024 } as const;
+
+type Frame =
+  | { kind: "object"; state: "keyOrEnd" | "key" | "colon" | "value" | "commaOrEnd"; key?: string }
+  | { kind: "array"; state: "valueOrEnd" | "value" | "commaOrEnd" };
+
+/** Incrementally validates JSON and extracts the last top-level Cursor event name. */
+export class CursorEventScanner {
+  private frames: Frame[] = [];
+  private mode: "normal" | "string" | "primitive" = "normal";
+  private token: number[] = [];
+  private tokenOverflow = false;
+  private primitive: JsonPrimitiveScanner | undefined;
+  private escaped = false;
+  private unicode = 0;
+  private rootStarted = false;
+  private rootComplete = false;
+  private invalid = false;
+  private event: string | undefined;
+
+  /** Consume another raw JSON byte chunk without retaining the payload. */
+  write(chunk: Uint8Array): void {
+    for (const byte of chunk) this.consume(byte);
+  }
+
+  /** Return the event only when the complete stream is valid JSON. */
+  finish(): string | undefined {
+    if (this.mode === "primitive") this.endPrimitive();
+    if (this.mode !== "normal" || this.frames.length > 0 || !this.rootComplete) this.invalid = true;
+    return this.invalid ? undefined : this.event;
+  }
+
+  private consume(byte: number): void {
+    if (this.invalid) return;
+    if (this.mode === "string") { this.stringByte(byte); return; }
+    if (this.mode === "primitive") {
+      if (!isDelimiter(byte)) {
+        if (!this.primitive?.write(byte)) this.invalid = true;
+        return;
+      }
+      this.endPrimitive();
+      if (this.invalid) return;
+    }
+    if (isWhitespace(byte)) return;
+    if (byte === 0x22) { this.startString(); return; }
+    if (byte === 0x7b || byte === 0x5b) { this.startContainer(byte === 0x7b ? "object" : "array"); return; }
+    if (byte === 0x7d || byte === 0x5d) { this.endContainer(byte === 0x7d ? "object" : "array"); return; }
+    if (byte === 0x3a) { this.colon(); return; }
+    if (byte === 0x2c) { this.comma(); return; }
+    if (isPrimitiveStart(byte)) { this.startPrimitive(byte); return; }
+    this.invalid = true;
+  }
+
+  private startString(): void {
+    this.mode = "string";
+    this.token = [0x22];
+    this.tokenOverflow = false;
+    this.escaped = false;
+    this.unicode = 0;
+  }
+
+  private startPrimitive(byte: number): void {
+    this.mode = "primitive";
+    this.primitive = new JsonPrimitiveScanner(byte);
+  }
+
+  private stringByte(byte: number): void {
+    this.pushToken(byte);
+    if (this.unicode > 0) {
+      if (!isHex(byte)) { this.invalid = true; return; }
+      this.unicode -= 1;
+      return;
+    }
+    if (this.escaped) {
+      if (byte === 0x75) this.unicode = 4;
+      else if (![0x22, 0x5c, 0x2f, 0x62, 0x66, 0x6e, 0x72, 0x74].includes(byte)) this.invalid = true;
+      this.escaped = false;
+      return;
+    }
+    if (byte === 0x5c) { this.escaped = true; return; }
+    if (byte < 0x20) { this.invalid = true; return; }
+    if (byte !== 0x22) return;
+    this.mode = "normal";
+    const value = this.tokenOverflow ? undefined : decodeString(this.token);
+    if (value === null) { this.invalid = true; return; }
+    this.acceptString(value);
+  }
+
+  private acceptString(value: string | undefined): void {
+    const frame = this.frames.at(-1);
+    if (frame?.kind === "object" && (frame.state === "key" || frame.state === "keyOrEnd")) {
+      frame.key = value;
+      frame.state = "colon";
+      return;
+    }
+    this.acceptValue("string", value);
+  }
+
+  private startContainer(kind: "object" | "array"): void {
+    this.acceptValue(kind);
+    if (this.invalid) return;
+    if (this.frames.length >= CURSOR_SCANNER_LIMITS.maxDepth) { this.invalid = true; return; }
+    this.frames.push(kind === "object" ? { kind, state: "keyOrEnd" } : { kind, state: "valueOrEnd" });
+  }
+
+  private endContainer(kind: "object" | "array"): void {
+    const frame = this.frames.at(-1);
+    const valid = frame?.kind === kind && (kind === "object"
+      ? frame.state === "keyOrEnd" || frame.state === "commaOrEnd"
+      : frame.state === "valueOrEnd" || frame.state === "commaOrEnd");
+    if (!valid) { this.invalid = true; return; }
+    this.frames.pop();
+    if (this.frames.length === 0) this.rootComplete = true;
+  }
+
+  private acceptValue(kind: "string" | "primitive" | "object" | "array", value?: string): void {
+    if (this.rootComplete) { this.invalid = true; return; }
+    const frame = this.frames.at(-1);
+    if (!frame) {
+      if (this.rootStarted) { this.invalid = true; return; }
+      this.rootStarted = true;
+      if (kind === "string" || kind === "primitive") this.rootComplete = true;
+      return;
+    }
+    const expected = frame.kind === "object" ? frame.state === "value" : frame.state === "value" || frame.state === "valueOrEnd";
+    if (!expected) { this.invalid = true; return; }
+    if (frame.kind === "object") {
+      if (this.frames.length === 1 && frame.key === "hook_event_name") this.event = kind === "string" ? value : undefined;
+      frame.key = undefined;
+    }
+    frame.state = "commaOrEnd";
+  }
+
+  private colon(): void {
+    const frame = this.frames.at(-1);
+    if (frame?.kind !== "object" || frame.state !== "colon") { this.invalid = true; return; }
+    frame.state = "value";
+  }
+
+  private comma(): void {
+    const frame = this.frames.at(-1);
+    if (!frame || frame.state !== "commaOrEnd") { this.invalid = true; return; }
+    frame.state = frame.kind === "object" ? "key" : "value";
+  }
+
+  private endPrimitive(): void {
+    const valid = this.primitive?.finish() === true;
+    this.mode = "normal";
+    this.primitive = undefined;
+    if (valid) this.acceptValue("primitive");
+    else this.invalid = true;
+  }
+
+  private pushToken(byte: number): void {
+    if (this.token.length < CURSOR_SCANNER_LIMITS.tokenEntries) this.token.push(byte);
+    else this.tokenOverflow = true;
+  }
+}
+
+function decodeString(bytes: number[]): string | null {
+  try { const value: unknown = JSON.parse(Buffer.from(bytes).toString("utf8")); return typeof value === "string" ? value : null; }
+  catch { return null; }
+}
+
+function isWhitespace(byte: number): boolean { return byte === 0x20 || byte === 0x09 || byte === 0x0a || byte === 0x0d; }
+function isDelimiter(byte: number): boolean { return isWhitespace(byte) || [0x2c, 0x5d, 0x7d].includes(byte); }
+function isPrimitiveStart(byte: number): boolean { return byte === 0x2d || byte === 0x74 || byte === 0x66 || byte === 0x6e || byte >= 0x30 && byte <= 0x39; }
+function isHex(byte: number): boolean { return byte >= 0x30 && byte <= 0x39 || byte >= 0x41 && byte <= 0x46 || byte >= 0x61 && byte <= 0x66; }

package/src/cli/cursor-stdin-reader.ts

@@ -0,0 +1,65 @@
+import { readSync } from "node:fs";
+import { CURSOR_SCANNER_LIMITS, CursorEventScanner } from "./cursor-event-scanner";
+
+const HEAD_BYTES = 4096;
+const CHUNK_BYTES = 64 * 1024;
+
+export type CursorStdinRead =
+  | { kind: "ok"; text: string }
+  | { kind: "oversize"; head: string };
+
+/**
+ * Requested independent Buffer allocation/retention lengths and scanner cardinalities.
+ * Zero-copy aliases such as `subarray`, backing pools/ArrayBuffers, JS objects/strings,
+ * and RSS are excluded; this metric is not a physical or total-memory bound.
+ */
+export function cursorReaderBounds(maxBytes: number): {
+  bufferAllocationRequestBytes: number;
+  scannerTokenEntries: number;
+  scannerFrames: number;
+} {
+  return {
+    bufferAllocationRequestBytes: maxBytes + CHUNK_BYTES + HEAD_BYTES + CURSOR_SCANNER_LIMITS.tokenEntries,
+    scannerTokenEntries: CURSOR_SCANNER_LIMITS.tokenEntries,
+    scannerFrames: CURSOR_SCANNER_LIMITS.maxDepth,
+  };
+}
+
+/**
+ * Read Cursor stdin through EOF for valid top-level event classification.
+ * Cursor's host-configured execution timeout bounds an idle open pipe.
+ */
+export function readCursorBounded(fd: number, maxBytes: number): CursorStdinRead {
+  const chunk = Buffer.alloc(CHUNK_BYTES);
+  const head = Buffer.alloc(HEAD_BYTES);
+  const retained = Buffer.alloc(maxBytes);
+  const scanner = new CursorEventScanner();
+  let headLength = 0;
+  let retainedLength = 0;
+  let total = 0;
+  let oversize = false;
+  for (;;) {
+    const length = readSync(fd, chunk, 0, CHUNK_BYTES, null);
+    if (length === 0) break;
+    const view = chunk.subarray(0, length);
+    scanner.write(view);
+    total += length;
+    if (headLength < HEAD_BYTES) {
+      const copied = Math.min(length, HEAD_BYTES - headLength);
+      view.copy(head, headLength, 0, copied);
+      headLength += copied;
+    }
+    if (!oversize) {
+      const copied = Math.min(length, Math.max(0, maxBytes - retainedLength));
+      if (copied > 0) view.copy(retained, retainedLength, 0, copied);
+      retainedLength += copied;
+      if (total > maxBytes) oversize = true;
+    }
+  }
+  if (!oversize) return { kind: "ok", text: retained.subarray(0, total).toString("utf8") };
+  const event = scanner.finish();
+  return {
+    kind: "oversize",
+    head: event ? JSON.stringify({ hook_event_name: event }) : head.subarray(0, headLength).toString("utf8"),
+  };
+}

package/src/cli/doctor.ts

@@ -0,0 +1,96 @@
+/**
+ * `harness doctor` — diagnose which `@fusengine/harness` is actually running.
+ *
+ * A confirmed, still-open bun bug (oven-sh/bun #5791; scoped-pkg behaviour
+ * reinforced by #32019/#32150) makes `bunx <pkg>` (unpinned) prefer a stale
+ * GLOBAL install over npm-latest, so a consumer can silently run an old harness
+ * after a publish. This command surfaces the truth: the resolved version +
+ * package path of the code executing right now, the runtime binary, and the
+ * latest version published on npm. It queries the registry over HTTP (not
+ * `npm view`, whose exit code is 0 even on an empty result — npm/cli#6408) and
+ * never throws: an offline environment yields `latest: null`, never a crash.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const PKG = "@fusengine/harness";
+
+/** Diagnostic snapshot printed by `harness doctor`. */
+export interface DoctorReport {
+  /** Version from the running `package.json` (`"unknown"` if not resolvable). */
+  running: string;
+  /** Absolute path to the running package root. */
+  packagePath: string;
+  /** Runtime binary executing this code (`process.execPath`). */
+  runtime: string;
+  /** Latest version on npm, or `null` when offline / unreachable. */
+  latest: string | null;
+  /** True when npm advertises a version different from the one running. */
+  stale: boolean;
+}
+
+/** Walk up from `startDir` for the `@fusengine/harness` `package.json`. */
+function findPackage(startDir: string): { version: string; path: string } | null {
+  let dir = startDir;
+  for (let depth = 0; depth < 6; depth++) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as { name?: string; version?: string };
+      if (pkg.name === PKG) return { version: pkg.version ?? "unknown", path: dir };
+    } catch { /* not here — keep walking up */ }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/** Resolve the running version + package path (no network), from a module URL. */
+export function runningVersion(moduleUrl: string): { version: string; path: string } {
+  const found = findPackage(dirname(fileURLToPath(moduleUrl)));
+  return { version: found?.version ?? "unknown", path: found?.path ?? "unknown" };
+}
+
+/** One-line `pkg vX.Y.Z` banner (stderr, only on explicit `--version`/`doctor` commands — never on `hook`, to avoid spamming automated invocations). */
+export function versionBanner(moduleUrl: string): string {
+  return `${PKG} v${runningVersion(moduleUrl).version}`;
+}
+
+/** Latest published version via the npm registry HTTP API. `null` on any failure. */
+export async function npmLatest(): Promise<string | null> {
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${PKG}/latest`, { signal: AbortSignal.timeout(8000) });
+    if (!res.ok) return null;
+    const body = (await res.json()) as { version?: string };
+    return body.version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Build the full diagnostic report for the module at `moduleUrl`. */
+export async function buildDoctorReport(moduleUrl: string): Promise<DoctorReport> {
+  const { version, path } = runningVersion(moduleUrl);
+  const latest = await npmLatest();
+  return { running: version, packagePath: path, runtime: process.execPath, latest, stale: latest !== null && latest !== version };
+}
+
+/** Render a {@link DoctorReport} as human-readable stdout text. */
+export function formatDoctor(r: DoctorReport): string {
+  const lines = [
+    `${PKG} doctor`,
+    `  running:    ${r.running}`,
+    `  package:    ${r.packagePath}`,
+    `  runtime:    ${r.runtime}`,
+    `  npm latest: ${r.latest ?? "(unavailable — offline or unreachable)"}`,
+  ];
+  if (r.stale) lines.push(`  ! stale — npm serves ${r.latest}. Pin "@fusengine/harness@${r.latest}" in hooks.json (see README).`);
+  else if (r.latest !== null) lines.push(`  ok — running the latest published version.`);
+  return lines.join("\n");
+}
+
+/** Run `harness doctor`: print the diagnostic to stdout. Always resolves 0 (pure info). */
+export async function runDoctor(moduleUrl: string): Promise<number> {
+  process.stdout.write(formatDoctor(await buildDoctorReport(moduleUrl)) + "\n");
+  return 0;
+}

package/src/cli/hook-io.ts

@@ -0,0 +1,130 @@
+/**
+ * Hook stdin reading + debug tracing for `harness hook` — extracted from
+ * `bin.ts` so the command dispatcher stays under the SOLID line ceiling.
+ * Tracing is stderr-only and active only when FUSE_HARNESS_DEBUG=1 AND
+ * CI=true (both set by test/sim/exec.ts; never in an interactive session).
+ *
+ * `resolveStdinMaxBytes` (default 16 MiB) caps retained payload content.
+ * The legacy reader may also retain its overflow chunk; Cursor additionally
+ * requests fixed scanner/chunk buffers while reading to EOF. Buffer alias views,
+ * JS objects/strings, and RSS are runtime-dependent, so this is not a physical
+ * memory guarantee. Unclassified oversized Cursor input fails closed.
+ */
+import { readSync } from "node:fs";
+import { resolveStdinMaxBytes } from "../config/limits";
+import { respond } from "../runtime/respond";
+import { cursorEventContract } from "../adapters/cursor/events";
+import { readCursorBounded } from "./cursor-stdin-reader";
+export { cursorReaderBounds, readCursorBounded } from "./cursor-stdin-reader";
+
+const hookDebug = process.env.FUSE_HARNESS_DEBUG === "1" && process.env.CI === "true";
+
+/** stderr-only trace, no-op outside the debug flag combination above. */
+export function traceHook(label: string, data: unknown): void {
+  if (hookDebug) process.stderr.write(`[hook-debug] ${label}: ${typeof data === "string" ? data : JSON.stringify(data)}\n`);
+}
+
+/** Result of the bounded stdin read. */
+export type StdinRead =
+  | { kind: "ok"; text: string }
+  | { kind: "oversize"; head: string };
+
+const MALFORMED_STDIN: unique symbol = Symbol("cursor-malformed-stdin");
+type MalformedStdin = { readonly [MALFORMED_STDIN]: true };
+
+/** Type guard for the oversize variant (narrows the readStdin union). */
+export function isOversize(x: unknown): x is { kind: "oversize"; head: string } {
+  return typeof x === "object" && x !== null && (x as { kind?: unknown }).kind === "oversize";
+}
+
+/** Identify Cursor JSON parse failures without accepting a forgeable payload field. */
+export function isMalformedCursorStdin(x: unknown): x is MalformedStdin {
+  return typeof x === "object" && x !== null && MALFORMED_STDIN in x;
+}
+
+/** First 4 KiB are the fallback diagnostic probe when no event key is found. */
+const HEAD_BYTES = 4096;
+const CHUNK = 64 * 1024;
+const CURSOR_MAX_STDIN_BYTES = 64 * 1024 * 1024;
+
+/** Resolve and clamp Cursor's stdin cap while preserving other harness limits. */
+export function resolveCursorStdinMaxBytes(env: Record<string, string | undefined> = process.env): number {
+  return Math.min(CURSOR_MAX_STDIN_BYTES, resolveStdinMaxBytes(env));
+}
+
+/**
+ * Read a file descriptor to EOF, bounded at `maxBytes` (+1 byte to detect
+ * the overflow). Injectable fd so tests never touch process stdin.
+ * @param fd - The descriptor to read (0 in production).
+ * @param maxBytes - Cap from {@link resolveStdinMaxBytes}.
+ */
+export function readBounded(fd: number, maxBytes: number): StdinRead {
+  const buf = Buffer.alloc(CHUNK);
+  const parts: Buffer[] = [];
+  let total = 0;
+  for (;;) {
+    const n = readSync(fd, buf, 0, CHUNK, null);
+    if (n === 0) break;
+    total += n;
+    parts.push(Buffer.from(buf.subarray(0, n)));
+    if (total > maxBytes) {
+      return { kind: "oversize", head: Buffer.concat(parts).subarray(0, HEAD_BYTES).toString("utf8") };
+    }
+  }
+  traceHook("stdin-text-length", total);
+  return { kind: "ok", text: Buffer.concat(parts).toString("utf8") };
+}
+
+/** Read hook stdin; Cursor distinguishes malformed non-empty JSON from historical empty input. */
+export async function readStdin(id?: string): Promise<Record<string, unknown> | StdinRead | MalformedStdin> {
+  const cap = id === "cursor" ? resolveCursorStdinMaxBytes() : resolveStdinMaxBytes();
+  const read = id === "cursor" ? readCursorBounded(0, cap) : readBounded(0, cap);
+  if (read.kind === "oversize") return read;
+  const text = read.text.trim();
+  if (!text) return {};
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return typeof parsed === "object" && parsed !== null ? (parsed as Record<string, unknown>) : {};
+  } catch (e) {
+    traceHook("stdin-parse-error", e instanceof Error ? e.message : String(e));
+    return id === "cursor" ? { [MALFORMED_STDIN]: true } : {};
+  }
+}
+
+/** Blockable hook events (fail-closed on oversize); others are observation-only. */
+const BLOCKABLE = new Set(["PreToolUse", "UserPromptSubmit", "Stop"]);
+
+/**
+ * Native stdout for an oversize payload: a deny on blockable (or
+ * undeterminable) events — never an uninspected passthrough — and a neutral
+ * empty string on observation-only events (no crash, no noise).
+ * @param id - Harness id (selects the native deny shape via `respond`).
+ * @param head - The first bytes of the payload (event-name sniffing).
+ */
+export function oversizeStdout(id: string, head: string): string {
+  const event = id === "cursor" ? probeEvent(head) : legacyProbeEvent(head);
+  const maxBytes = id === "cursor" ? resolveCursorStdinMaxBytes() : resolveStdinMaxBytes();
+  if (id === "cursor" && event) {
+    const contract = cursorEventContract(event);
+    if (!contract.known || !contract.blockable) return "{}";
+  }
+  if (id !== "cursor" && event && !BLOCKABLE.has(event)) return "";
+  return respond(id, {
+    kind: "block",
+    title: "Oversize hook payload",
+    reason: `stdin payload exceeds ${maxBytes} bytes — denied uninspected`,
+  }, id === "cursor" ? (event || "preToolUse") : "PreToolUse");
+}
+
+function legacyProbeEvent(head: string): string {
+  return /"hook_event_name"\s*:\s*"([^"]+)"/.exec(head)?.[1] ?? "";
+}
+
+function probeEvent(head: string): string {
+  try {
+    const parsed: unknown = JSON.parse(head);
+    if (typeof parsed !== "object" || parsed === null) return "";
+    const event = (parsed as Record<string, unknown>).hook_event_name;
+    return typeof event === "string" ? event : "";
+  } catch { return ""; }
+}

package/src/cli/hook-sound.ts

@@ -0,0 +1,49 @@
+/**
+ * @module hook-sound
+ * CLI short-circuit for `harness hook ... --sound <kind>` — play the embedded
+ * notification sound and exit, bypassing stdin/handleHook entirely. Lets
+ * plugin hooks.json entries call the harness directly instead of a native
+ * `afplay`. Harness-agnostic by design: no gate on harness id here — codex,
+ * cursor, and hermes hooks.json may call this flag exactly the same way.
+ * @packageDocumentation
+ */
+import { notify, type SoundKind } from "../runtime/notifications";
+
+/** Recognised sound kinds — anything else fails closed (returns `null`). */
+const KINDS = new Set<SoundKind>(["stop", "permission", "human"]);
+
+/**
+ * Parse a `--sound <kind>` or `--sound=<kind>` flag anywhere in `argv`.
+ * Returns the kind only when it is a recognised {@link SoundKind}; an absent
+ * flag or an unrecognised value both yield `null` (fail-closed). Pure — no
+ * side effects, so it is directly unit-testable.
+ * @param argv - Full argv array (e.g. `process.argv`).
+ */
+export function soundArg(argv: string[]): SoundKind | null {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--sound") {
+      const val = argv[i + 1];
+      return val !== undefined && KINDS.has(val as SoundKind) ? (val as SoundKind) : null;
+    }
+    if (arg !== undefined && arg.startsWith("--sound=")) {
+      const val = arg.slice("--sound=".length);
+      return KINDS.has(val as SoundKind) ? (val as SoundKind) : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Play the sound requested by a `--sound <kind>` flag in `argv`, if present
+ * and valid. Fire-and-forget via {@link notify} (fail-open, respects
+ * `FUSE_HARNESS_SOUND=0`). Returns whether a sound was triggered, so the
+ * caller can short-circuit (exit 0) without ever reading stdin.
+ * @param argv - Full argv array (e.g. `process.argv`).
+ */
+export function maybePlaySound(argv: string[]): boolean {
+  const kind = soundArg(argv);
+  if (!kind) return false;
+  notify(kind);
+  return true;
+}

package/src/cli/index.ts

@@ -0,0 +1 @@
+export * from "./run";