@fusengine/harness 0.1.90 → 0.1.91

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

package/src/codex-rules/build.ts

@@ -0,0 +1,63 @@
+import { ALL_RULES, SKIP_LIST } from "./mapping";
+import { renderPrefixRules, sanitizeComment } from "./starlark";
+
+const HEADER =
+  '# Codex execpolicy rules — generated from @fusengine/harness src/policy/guards/security.ts\n' +
+  "# DO NOT hand-edit: regenerate via `harness codex-rules`.\n" +
+  "#\n" +
+  "# security.ts is the source of truth for dangerous-command detection; every\n" +
+  '# CRITICAL_PATTERNS label maps to decision = "forbidden", every ASK_PATTERNS\n' +
+  '# label maps to decision = "prompt". Strictest decision wins across matches.\n' +
+  "# The harness remains the AUTHORITATIVE enforcement layer — this file is a\n" +
+  "# complementary defense layer on the Codex side, not a replacement.\n" +
+  "#\n" +
+  "# IRREDUCIBLE gaps (shell syntax, invisible to argv-prefix matching, no\n" +
+  "# prefix_rule can express them) — compensated by sandbox_mode +\n" +
+  "# approval_policy.granular.sandbox_approval, not by this file:\n" +
+  "#   - fork bomb: `:(){ :|:& };:`\n" +
+  "#   - redirect to a raw disk device: `> /dev/sda`\n" +
+  "#   - write to /etc via redirection: `> /etc/...`\n" +
+  "#\n" +
+  "# ASSUMED over-width (intentionally broader than security.ts, chosen to\n" +
+  "# avoid a silent gap rather than an exact-but-brittle translation):\n" +
+  "#   - dd: prompts on every dd invocation; security.ts only fires on of=/dev/*\n" +
+  "#   - rm: prompts even on paths security.ts exempts via a 'trash' substring\n" +
+  "#   - rm/eval/unlink: prompts even on a bare token with no trailing argument;\n" +
+  "#     security.ts requires a space (i.e. an argument) after the command\n" +
+  "#   - chmod 777: prompts on relative paths too, not only absolute ones\n" +
+  "#   - sudo (/usr/bin/sudo alias): forbids the absolute-path form too;\n" +
+  "#     security.ts's word-boundary regex does not match a preceding '/'\n" +
+  "#   - curl/wget: prompts on EVERY curl/wget invocation, not only when piped\n" +
+  '#     into a shell; security.ts\'s "remote script piped to a shell" label\n' +
+  "#     only fires on `curl|wget ... | sh`. A simple plain-word pipe IS split\n" +
+  "#     by Codex into separate argv commands (a bare-shell rule would also\n" +
+  "#     catch that case), but this rule additionally targets the download\n" +
+  "#     half for compound chains and non-shell payload execution where\n" +
+  "#     sh/bash never appears as argv[0] (curl -o x && chmod +x x && ./x,\n" +
+  "#     curl ... | python3); it replaces a former bare sh/bash/zsh heuristic\n" +
+  '#     that prompted on ~50% of Codex\'s own `bash -lc "..."` command\n' +
+  "#     wrapping and rarely caught the actual download\n" +
+  "#\n" +
+  "# NOT covered (out of scope, not an over-width — a purely local pipe with no\n" +
+  "# network fetch is invisible to this rule AND to security.ts, which only\n" +
+  "# matches curl/wget as the left-hand side of the pipe):\n" +
+  "#   - `cat file | sh`: local pipe, no curl/wget involved\n" +
+  "#   - quoted-variable/redirection installer one-liners, e.g.\n" +
+  '#     `curl -fsSL "$URL" | sh`: variable substitution disables Codex\'s\n' +
+  "#     pipe-splitting, collapsing the whole invocation to a single\n" +
+  "#     ['bash', '-lc', '<script>'] where curl is not argv[0] — this exact\n" +
+  "#     form was covered by the removed bare sh/bash heuristic and is no\n" +
+  "#     longer covered by any rule here\n" +
+  "#\n" +
+  "# The following labels have NO argv-prefix equivalent at all (shell syntax\n" +
+  "# not visible to execpolicy's argv matching) and are intentionally NOT\n" +
+  "# expressed as prefix_rule() below — covered instead by sandbox_mode/approval_policy:";
+
+/** Render the full Codex execpolicy `.rules` Starlark file as a string. */
+export function buildCodexRules(): string {
+  const skipComment: string = SKIP_LIST.map(
+    (s) => `#   - ${sanitizeComment(s.sourceLabel)}: ${sanitizeComment(s.reason)}`,
+  ).join("\n");
+  const body: string = renderPrefixRules(ALL_RULES);
+  return `${HEADER}\n${skipComment}\n\n${body}\n`;
+}

package/src/codex-rules/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Codex execpolicy `.rules` (Starlark) generator, derived from the harness's
+ * own `security.ts` dangerous-command patterns. Pure, no I/O — see
+ * `../cli/bin.ts`'s `codex-rules` subcommand for stdout/`--out` wiring.
+ */
+export { buildCodexRules } from "./build";
+export { ALL_RULES, CRITICAL_RULES, ASK_RULES, SKIP_LIST } from "./mapping";
+export type { CodexDecision, CodexPrefixRule, CodexSkipEntry } from "./types";

package/src/codex-rules/mapping.ts

@@ -0,0 +1,42 @@
+import type { CodexPrefixRule } from "./types";
+import { RM_VARIANT_RULES } from "./rules/rm-variants";
+import { MKFS_RULES } from "./rules/mkfs";
+import { DISKUTIL_RULES } from "./rules/diskutil";
+import { DD_RULES } from "./rules/dd";
+import { SINGLE_COMMAND_RULES } from "./rules/single-commands";
+import { PRIVILEGE_RULES } from "./rules/privilege";
+import { ASK_RULES as BASE_ASK_RULES } from "./rules/ask";
+import { CHMOD_ASK_RULES } from "./rules/chmod-ask";
+import { REMOTE_FETCH_RULES } from "./rules/remote-fetch";
+import { withAbsolutePathAliases } from "./rules/absolute-paths";
+import { SKIP_LIST } from "./skip-list";
+
+/** Every `decision = "forbidden"` rule, hand-mapped from CRITICAL_PATTERNS. */
+const CRITICAL_BASE: CodexPrefixRule[] = [
+  ...RM_VARIANT_RULES,
+  ...MKFS_RULES,
+  ...DISKUTIL_RULES,
+  ...SINGLE_COMMAND_RULES,
+  ...PRIVILEGE_RULES,
+];
+
+/** Every `decision = "prompt"` rule, hand-mapped from ASK_PATTERNS (+ dd, downgraded). */
+const ASK_BASE: CodexPrefixRule[] = [...BASE_ASK_RULES, ...CHMOD_ASK_RULES, ...DD_RULES, ...REMOTE_FETCH_RULES];
+
+/** Absolute-path mirrors of the bare-name rules above (see `rules/absolute-paths.ts`). */
+const ABSOLUTE_ALIASES: CodexPrefixRule[] = withAbsolutePathAliases([...CRITICAL_BASE, ...ASK_BASE]);
+
+export const CRITICAL_RULES: CodexPrefixRule[] = [
+  ...CRITICAL_BASE,
+  ...ABSOLUTE_ALIASES.filter((r) => r.decision === "forbidden"),
+];
+
+export const ASK_RULES: CodexPrefixRule[] = [
+  ...ASK_BASE,
+  ...ABSOLUTE_ALIASES.filter((r) => r.decision === "prompt"),
+];
+
+export { SKIP_LIST };
+
+/** Every generated `prefix_rule`, critical (`forbidden`) + ask (`prompt`). */
+export const ALL_RULES: CodexPrefixRule[] = [...CRITICAL_RULES, ...ASK_RULES];

package/src/codex-rules/rules/absolute-paths.ts

@@ -0,0 +1,52 @@
+import type { CodexPrefixRule } from "../types";
+
+/**
+ * Absolute-path executable aliases — Codex only resolves an absolute path
+ * to its basename rule when the CLI is run with `--resolve-host-executables`
+ * (opt-in, off by default; this generated `.rules` file cannot assume it).
+ * `/bin/rm -rf /` and a bare `rm -rf /` are two DIFFERENT argv prefixes to
+ * execpolicy, so every rule keyed on one of these bare names is mirrored
+ * onto its common absolute-path forms.
+ */
+const ABSOLUTE_PATH_ALIASES: Record<string, string[]> = {
+  rm: ["/bin/rm", "/usr/bin/rm"],
+  chmod: ["/bin/chmod", "/usr/bin/chmod"],
+  diskutil: ["/usr/sbin/diskutil"],
+  dd: ["/bin/dd", "/usr/bin/dd"],
+  sudo: ["/usr/bin/sudo"],
+};
+
+/** Escape regex metacharacters so a dynamic token can be safely embedded in a `RegExp` literal. */
+function escapeRegExp(token: string): string {
+  return token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Replace a match/notMatch example's leading token with an absolute-path alias. */
+function aliasExample(example: string, from: string, to: string): string {
+  return example.replace(new RegExp(`^${escapeRegExp(from)}\\b`), to);
+}
+
+/**
+ * Clone every rule in `rules` whose first pattern token has a known
+ * absolute-path alias, producing one variant per alias (same decision,
+ * same sourceLabel — traced back to the same `security.ts` label).
+ */
+export function withAbsolutePathAliases(rules: CodexPrefixRule[]): CodexPrefixRule[] {
+  const out: CodexPrefixRule[] = [];
+  for (const rule of rules) {
+    const first = rule.pattern[0];
+    if (typeof first !== "string") continue;
+    const aliases = ABSOLUTE_PATH_ALIASES[first];
+    if (!aliases) continue;
+    for (const alias of aliases) {
+      out.push({
+        ...rule,
+        pattern: [alias, ...rule.pattern.slice(1)],
+        match: rule.match.map((m) => aliasExample(m, first, alias)),
+        notMatch: rule.notMatch?.map((m) => aliasExample(m, first, alias)),
+        justification: `${rule.justification} (absolute-path form; Codex does not resolve executable basenames by default).`,
+      });
+    }
+  }
+  return out;
+}