@fusengine/harness 0.1.89 → 0.1.91

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";

package/src/cli/json-primitive-scanner.ts

@@ -0,0 +1,83 @@
+type NumberState = "minus" | "zero" | "integer" | "dot" | "fraction" | "exponentMark" | "exponentSign" | "exponent";
+
+/** Validate one JSON literal or number incrementally with constant state. */
+export class JsonPrimitiveScanner {
+  private literal: "true" | "false" | "null" | undefined;
+  private literalIndex = 0;
+  private number: NumberState | undefined;
+  private valid = true;
+
+  constructor(firstByte: number) {
+    if (firstByte === 0x74) { this.literal = "true"; this.literalIndex = 1; }
+    else if (firstByte === 0x66) { this.literal = "false"; this.literalIndex = 1; }
+    else if (firstByte === 0x6e) { this.literal = "null"; this.literalIndex = 1; }
+    else if (firstByte === 0x2d) this.number = "minus";
+    else if (firstByte === 0x30) this.number = "zero";
+    else if (isOneToNine(firstByte)) this.number = "integer";
+    else this.valid = false;
+  }
+
+  /** Consume one non-delimiter byte and report whether the prefix stays valid. */
+  write(byte: number): boolean {
+    if (!this.valid) return false;
+    if (this.literal) {
+      this.valid = this.literal.charCodeAt(this.literalIndex) === byte;
+      this.literalIndex += 1;
+      return this.valid && this.literalIndex <= this.literal.length;
+    }
+    this.valid = this.writeNumber(byte);
+    return this.valid;
+  }
+
+  /** Return whether the accumulated primitive is complete JSON grammar. */
+  finish(): boolean {
+    if (!this.valid) return false;
+    if (this.literal) return this.literalIndex === this.literal.length;
+    return this.number === "zero" || this.number === "integer" || this.number === "fraction" || this.number === "exponent";
+  }
+
+  private writeNumber(byte: number): boolean {
+    if (this.number === "minus") return this.digitAfter(byte, "zero", "integer");
+    if (this.number === "zero") return this.afterInteger(byte, false);
+    if (this.number === "integer") {
+      if (isDigit(byte)) return true;
+      return this.afterInteger(byte, true);
+    }
+    if (this.number === "dot") {
+      if (!isDigit(byte)) return false;
+      this.number = "fraction";
+      return true;
+    }
+    if (this.number === "fraction") {
+      if (isDigit(byte)) return true;
+      return this.startExponent(byte);
+    }
+    if (this.number === "exponentMark") {
+      if (byte === 0x2b || byte === 0x2d) { this.number = "exponentSign"; return true; }
+      return this.digitAfter(byte, "exponent", "exponent");
+    }
+    if (this.number === "exponentSign") return this.digitAfter(byte, "exponent", "exponent");
+    return this.number === "exponent" && isDigit(byte);
+  }
+
+  private afterInteger(byte: number, digitAllowed: boolean): boolean {
+    if (digitAllowed && isDigit(byte)) return true;
+    if (byte === 0x2e) { this.number = "dot"; return true; }
+    return this.startExponent(byte);
+  }
+
+  private startExponent(byte: number): boolean {
+    if (byte !== 0x65 && byte !== 0x45) return false;
+    this.number = "exponentMark";
+    return true;
+  }
+
+  private digitAfter(byte: number, zero: NumberState, nonzero: NumberState): boolean {
+    if (byte === 0x30) { this.number = zero; return true; }
+    if (isOneToNine(byte)) { this.number = nonzero; return true; }
+    return false;
+  }
+}
+
+function isDigit(byte: number): boolean { return byte >= 0x30 && byte <= 0x39; }
+function isOneToNine(byte: number): boolean { return byte >= 0x31 && byte <= 0x39; }

package/src/cli/run.ts

@@ -0,0 +1,36 @@
+import { execFileSync } from "node:child_process";
+import { evaluate } from "../policy/evaluate";
+import { formatPrompt } from "../prompt/types";
+import { isCodeFile } from "../util/project-root";
+
+/** Staged files (Added/Copied/Modified/Renamed). Uses `node:child_process` (Bun shell can hang on `git show`). */
+export function stagedFiles(): string[] {
+  const out = execFileSync("git", ["diff", "--cached", "--name-only", "--diff-filter=ACMR"], {
+    encoding: "utf8",
+  });
+  return out.trim().split("\n").filter(Boolean);
+}
+
+/**
+ * Read a file's staged (index) content — not the working-tree version.
+ * Uses `execFileSync` with an argv array (never a shell), so a staged
+ * filename containing shell metacharacters (backticks, `$(...)`, quotes)
+ * reaches `git show` as a single literal argument — see issue #87.
+ */
+export function stagedContent(path: string): string {
+  return execFileSync("git", ["show", `:${path}`], { encoding: "utf8" });
+}
+
+/**
+ * Evaluate staged code files against the policy core; return violation blocks.
+ * `read` is injected (the real impl is {@link stagedContent}) so this is pure + testable.
+ */
+export function checkStaged(files: string[], read: (path: string) => string): string[] {
+  const violations: string[] = [];
+  for (const file of files) {
+    if (!isCodeFile(file)) continue;
+    const r = evaluate({ tool: "Write", filePath: file, content: read(file) });
+    if (r.decision === "deny" && r.prompt) violations.push(`${file}\n${formatPrompt(r.prompt)}`);
+  }
+  return violations;
+}

package/src/cli/scope.ts

@@ -0,0 +1,31 @@
+/**
+ * CLI scope argument parsing for `harness hook <id> [scope]`. The scope set is
+ * closed (plugin-scoped lifecycle behaviors); an unknown value historically
+ * fell back to `"core"` SILENTLY, which made a typo'd plugin name apply the
+ * core guards with no sign of the mistake. The fallback stays (wiring
+ * compatibility) but now warns on stderr — harnesses never parse stderr, so
+ * the wire contract is untouched.
+ */
+import type { PluginScope } from "../runtime/lifecycle";
+
+/** Closed set of plugin scopes accepted after `harness hook <id>`. */
+const VALID_SCOPES = new Set<string>([
+  "solid", "rules", "carto", "security", "changelog",
+  "aipilot", "lessons", "seo", "memory", "tailwindcss",
+]);
+
+/**
+ * Parse the optional scope argument.
+ * @param scopeArg - `process.argv[4]`, when present.
+ * @param err - Warning sink (defaults to stderr; injectable for tests).
+ * @returns The valid scope, or `"core"` (with a warning) otherwise.
+ */
+export function parseScope(
+  scopeArg: string | undefined,
+  err: (msg: string) => void = (m) => process.stderr.write(m),
+): PluginScope {
+  if (scopeArg !== undefined && scopeArg !== "core" && !VALID_SCOPES.has(scopeArg)) {
+    err(`harness: unknown scope "${scopeArg}", falling back to "core"\n`);
+  }
+  return scopeArg !== undefined && VALID_SCOPES.has(scopeArg) ? (scopeArg as PluginScope) : "core";
+}