@fusengine/harness 0.1.90 → 0.1.91

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

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