@fusengine/harness 0.1.89 → 0.1.91

package/src/policy/gemini-mcp-gate.ts

@@ -0,0 +1,83 @@
+/**
+ * @module gemini-mcp-gate
+ * OPT-IN gate porting core-guards `enforce-gemini-mcp.py`: when enabled via
+ * `FUSE_ENFORCE_GEMINI_MCP`, blocks a UI write (`.tsx/.jsx/.vue/.svelte`) that
+ * hand-writes >= 3 Tailwind utility classes unless a `mcp__gemini-design__*`
+ * call was made this session. DISABLED BY DEFAULT — the flag is read fresh on
+ * every call, so nothing is gated unless the owner explicitly turns it on (a
+ * gate blocking a common dev action must never be always-on).
+ * @packageDocumentation
+ */
+import type { Prompt } from "../prompt/types";
+import type { AuthEntry } from "../freshness/doc-helpers";
+
+/** UI file extensions the gate polices (parity enforce-gemini-mcp.py UI_EXT). */
+const UI_EXT_RE = /\.(tsx|jsx|vue|svelte)$/;
+/** Paths exempt from the gate (parity EXEMPT_DIRS). */
+const GEMINI_EXEMPT_RE = /(node_modules|dist|build|\.next|\.claude)\//;
+/** A live `mcp__gemini-design__*` call recorded this session proves consultation. */
+const GEMINI_MCP_SOURCE_RE = /gemini-mcp/i;
+/** Tailwind utility patterns (parity TAILWIND_PATTERNS). */
+const TW_PATTERNS: readonly RegExp[] = [
+  /\bflex\b/, /\bgrid\b/, /\bp-\d/, /\bpx-\d/, /\bpy-\d/,
+  /\bm-\d/, /\bmx-\d/, /\bmy-\d/, /\bmt-\d/, /\bmb-\d/,
+  /\bbg-\w+/, /\btext-\w+/, /\brounded/, /\bshadow/,
+  /\bborder\b/, /\bgap-\d/, /\bw-\w+/, /\bh-\w+/,
+  /\bjustify-\w+/, /\bitems-\w+/, /\bspace-\w+-\d/,
+];
+/** Min distinct Tailwind patterns before the gate fires (parity MIN_TAILWIND_CLASSES). */
+const MIN_TW = 3;
+/** Min newlines an Edit's new_string must have to be gated (parity MIN_LINES_FOR_EDIT). */
+const MIN_LINES_EDIT = 2;
+
+/** OPT-IN: off unless `FUSE_ENFORCE_GEMINI_MCP` is `1`/`true`. Read fresh each call (dynamic). */
+export function geminiMcpEnforced(): boolean {
+  const v = process.env.FUSE_ENFORCE_GEMINI_MCP;
+  return v === "1" || v === "true";
+}
+
+/** Count distinct Tailwind utility patterns present in `content` (parity count_tailwind_classes). */
+function countTailwindClasses(content: string): number {
+  return TW_PATTERNS.reduce((n, re) => (re.test(content) ? n + 1 : n), 0);
+}
+
+/** Session evidence the gate consumes. */
+export interface GeminiEvidence {
+  authorizations?: Record<string, AuthEntry>;
+  sessionId: string;
+}
+
+/** True when a `mcp__gemini-design__*` call was recorded this session (parity gemini_was_called). */
+export function geminiMcpConsulted(authorizations: Record<string, AuthEntry> | undefined, sessionId: string): boolean {
+  if (!authorizations) return false;
+  return Object.values(authorizations).some(
+    (a) => a.doc_sessions?.includes(sessionId) && (a.sources ?? (a.source ? [a.source] : [])).some((s) => GEMINI_MCP_SOURCE_RE.test(s)),
+  );
+}
+
+/**
+ * Gate a UI write when `FUSE_ENFORCE_GEMINI_MCP` is on: block hand-written
+ * Tailwind (>= 3 classes) in a `.tsx/.jsx/.vue/.svelte` file unless a Gemini
+ * Design MCP call was made this session. Returns `null` when disabled (default),
+ * out of scope, or already satisfied.
+ * @param tool - the tool name.
+ * @param filePath - the file being written.
+ * @param content - the written content (new_string on Edit).
+ * @param ev - session evidence (authorizations + sessionId).
+ */
+export function geminiMcpGate(tool: string, filePath: string, content: string, ev: GeminiEvidence): Prompt | null {
+  if (!geminiMcpEnforced()) return null;
+  if (tool !== "Write" && tool !== "Edit") return null;
+  if (!filePath || !UI_EXT_RE.test(filePath) || GEMINI_EXEMPT_RE.test(filePath)) return null;
+  if (!content) return null;
+  if (tool === "Edit" && (content.match(/\n/g)?.length ?? 0) < MIN_LINES_EDIT) return null;
+  if (countTailwindClasses(content) < MIN_TW) return null;
+  if (geminiMcpConsulted(ev.authorizations, ev.sessionId)) return null;
+  return {
+    kind: "block",
+    title: "Gemini Design MCP",
+    reason:
+      "BLOCKED: UI code with Tailwind detected but Gemini Design MCP not used. Use mcp__gemini-design__create_frontend, modify_frontend, or snippet_frontend BEFORE writing UI code manually.",
+    actions: ["Call mcp__gemini-design__create_frontend / modify_frontend / snippet_frontend, then retry"],
+  };
+}

package/src/policy/git-gates.ts

@@ -0,0 +1,40 @@
+import { matchPatterns, GIT_BLOCKED, GIT_ASK } from "./patterns";
+import type { PolicyResult } from "./interfaces/types";
+
+/**
+ * Evaluate the two git confirmation gates — destructive block ({@link
+ * GIT_BLOCKED}) and confirmation ask ({@link GIT_ASK}) — against `command`.
+ * Skipped entirely when `ralphSafe` is true: Ralph mode already silent-
+ * allowed the command upstream (parity with evaluate.ts's pre-existing
+ * `!ralphSafe &&` guards). Returns the matching gate's {@link PolicyResult},
+ * or `null` when neither gate matches.
+ */
+export function evaluateGitGates(command: string | undefined, ralphSafe: boolean): PolicyResult | null {
+  if (ralphSafe || !command) return null;
+  if (matchPatterns(command, GIT_BLOCKED)) {
+    const reason = `Destructive git command: ${command}`;
+    return {
+      decision: "deny",
+      message: reason,
+      prompt: {
+        kind: "block",
+        title: "Destructive git command",
+        reason,
+        actions: ["Use a non-destructive alternative (e.g. --force-with-lease; avoid --hard / -D)"],
+      },
+    };
+  }
+  if (matchPatterns(command, GIT_ASK)) {
+    return {
+      decision: "deny",
+      message: `Git operation requires confirmation: ${command}`,
+      prompt: {
+        kind: "ask",
+        title: "Confirm git operation",
+        reason: `Authorize: ${command.trim()}`,
+        actions: ["Approve if this git operation is intended"],
+      },
+    };
+  }
+  return null;
+}

package/src/policy/guards/bash-command-anchor.ts

@@ -0,0 +1,40 @@
+/**
+ * Command-position anchoring for the Bash write guard — the regex prefix that
+ * tells a real mutator invocation apart from a quoted/argument mention of the
+ * same token. Consumed by bash-write-patterns.ts (CODE_MUTATORS, CODE_COMMAND_WRITE).
+ */
+
+/**
+ * Transparent exec wrappers that run another command as their argument
+ * (`env sed -i …`, `timeout 5 patch …`, `sudo -n tee …`, `xargs sed -i`). A code
+ * mutator behind one is still a code mutator — the wrapper is not a shield.
+ */
+const WRAP = "(?:env|timeout|nice|nohup|sudo|command|stdbuf|time|ionice|exec|xargs)";
+
+/**
+ * A wrapper's own leading arg tokens: `VAR=val` assignments, `-f`/`--flag`
+ * options, or a bare duration/number (`timeout 5`, `nice -n 10`). The flag form
+ * is `--?[^\s-]\S*` (not `-{1,2}\S+`) so a dash-run has ONE decomposition — the
+ * `-`/`--` ambiguity under the outer `*` is a ReDoS vector (OWASP ReDoS). Every
+ * alternative consumes ≥1 char and is followed by a mandatory `\s+`, so the
+ * repeated group is never zero-width (no `(X*)*` catastrophic shape).
+ */
+const WRAP_ARG = "(?:\\w+=\\S+|--?[^\\s-]\\S*|\\d+[smhd]?)";
+
+/**
+ * Command-position anchor: line/segment start or a `;&|(` separator, then any
+ * chain of {@link WRAP} wrappers (each with its own {@link WRAP_ARG} tokens).
+ * Anchoring a write motif here makes it fire on a real invocation
+ * (`env sed -i x src/a.ts`) while ignoring a quoted/argument MENTION of the same
+ * text (`git commit -m "fix sed -i doc"`, `npm run t -- --grep "sed -i"`), which
+ * is never at a command position.
+ *
+ * Defense-in-depth first pass, NOT the sole control: regex-on-raw-string is
+ * lossy vs a real shell lexer. Known residual gaps (enumerated, not silently
+ * assumed away): command substitution `$(…)`/backticks, indirect exec via
+ * `bash -c`/`eval`/`find -exec`, process substitution `<(…)`, shell-quoting
+ * tricks (`s''ed`, `${x}ed`), and variable-indirection targets (`tee $F`). Those
+ * need a tokenizer, out of scope here; the Write/Edit tool gate stays the
+ * backstop for what slips through.
+ */
+export const CMD: string = `(?:^|[\\n;&|(])\\s*(?:${WRAP}\\s+(?:${WRAP_ARG}\\s+)*)*`;

package/src/policy/guards/bash-write-patterns.ts

@@ -0,0 +1,140 @@
+import { CMD } from "./bash-command-anchor";
+
+/** Code-file extensions the write guards police (shared by CODE_REDIRECT and
+ *  CODE_COMMAND_WRITE). Case-sensitive, parity with the Python guard's list. */
+const CODE_EXT = "ts|tsx|js|jsx|py|go|rb|rs|java|kt|php|swift|vue|svelte|astro|css|c|cpp|h";
+
+/** Redirect (`>`/`>>`) targeting a code-file extension. */
+export const CODE_REDIRECT: RegExp = new RegExp(`(?:>>?)\\s*[^\\s|;&]*\\.(?:${CODE_EXT})\\b`);
+
+/**
+ * Interpreters / tools that mutate source in place, plus heredoc-into-file —
+ * split into labeled sub-patterns (parity bash-write-guard.py `DENY_PATTERNS`,
+ * each with its own `desc`) so the deny reason names which motif matched
+ * instead of a single generic message. Every command-named motif is
+ * {@link CMD}-anchored (start/separator + optional wrapper chain); only the
+ * structural heredoc-into-file motif is position-free.
+ */
+export const CODE_MUTATORS: readonly { re: RegExp; desc: string }[] = [
+  { re: new RegExp(`${CMD}python3?\\s+-\\s*<<`), desc: "Python heredoc input" },
+  { re: new RegExp(`${CMD}sed\\b[^|]*\\s-i`), desc: "sed in-place edit" },
+  { re: new RegExp(`${CMD}perl\\b[^|]*\\s-[pi]i?\\b`), desc: "perl in-place edit" },
+  { re: new RegExp(`${CMD}awk\\b[^|]*-i\\s*inplace`), desc: "awk in-place edit" },
+  // `patch` as a command token (start/separator + optional wrapper chain), then a
+  // metachar/space/EOL. Never the bare word merely NAMING a path in a read-only
+  // command (`jq . apply-patch.json`, `grep patch src/`). Prefix-wrapped forms
+  // (`env patch`, `timeout 5 patch`) are now DENIED — the previously accepted gap
+  // was closed (owner decision 2026-07-06): the wrapper chain folds into CMD.
+  { re: new RegExp(`${CMD}patch(?=\\s|<|[;&|)>]|$)`), desc: "patch file modification" },
+  { re: /<<[-~]?\s*['"]?\w+['"]?[\s\S]*?>/, desc: "heredoc redirected into a file" },
+];
+
+/**
+ * `tee`/`dd of=` whose TARGET is a code file — the command-form parallel to
+ * CODE_REDIRECT. {@link CMD}-anchored so `env`/`timeout` wrappers don't shield
+ * it; the `tee` branch scans ALL args up to the next `;&|` separator so a
+ * decoy-first-target (`tee log.txt src/x.ts`) can't hide the code write. A tee
+ * to a NON-code target (`cmd | tee results.txt`) does not match — it stays a
+ * plain ASK_WRITERS ask, never a hard block, so ordinary logging is untouched.
+ */
+export const CODE_COMMAND_WRITE: RegExp = new RegExp(
+  `${CMD}(?:tee\\s+[^;&|\\n]*?|dd\\b[^|]*\\bof=\\S*)\\.(?:${CODE_EXT})\\b`,
+);
+
+/** File-mutating one-liners via `node -e` / `ruby -e` (parity NODE_WRITES/RUBY_WRITES). */
+export const NODE_WRITES: RegExp =
+  /writeFile|appendFile|createWriteStream|fs\.(?:write|rename|unlink|mkdir|rmdir|copyFile)|execSync|spawnSync|child_process/;
+export const RUBY_WRITES: RegExp =
+  /File\.(?:write|open|delete|rename)|IO\.write|FileUtils|\bsystem\b|\bexec\b|`[^`]/;
+
+/**
+ * Command-position anchor for `python3 -c` (same anchored-token shape as the
+ * removed unconditional CODE_MUTATORS entry) — used ONLY to gate {@link PYTHON_WRITES}
+ * below, never as a standalone block. `python3 - <<EOF` (heredoc) stays
+ * unconditionally blocked in CODE_MUTATORS — a heredoc body can't be inspected
+ * reliably with a single-line regex, so it is never widened.
+ */
+export const PYTHON_C_ANCHOR: RegExp = new RegExp(`${CMD}python3?\\s+-c\\b`);
+
+/**
+ * File/process-mutating constructs inside a `python3 -c` inline script (parity
+ * NODE_WRITES/RUBY_WRITES: content-gated, not name-gated). `python3 -c` is
+ * blocked ONLY when this matches — a read-only one-liner (`print(...)`,
+ * `json.load`/`json.dumps`) passes. Doc-verified against docs.python.org
+ * (functions/pathlib/shutil/subprocess/os/pickle) before writing this pattern.
+ *
+ * Families, each independently sufficient to mutate state or run arbitrary code:
+ *  - `open(...)` / `Path(...).open(...)` in a write/append/exclusive/read-write
+ *    mode — positional (`'w'`,`'x'`,`'a'`,`'r+'`,`'w+'`, …) or `mode=` kwarg, any
+ *    `b`/`t` suffix. Plain `open(f)` / `open(f, 'r')` (read-only, the default)
+ *    does NOT match.
+ *  - `pathlib.Path` mutators: `write_text`, `write_bytes`, `unlink`, `rename`,
+ *    `replace`, `mkdir`, `rmdir`, `touch`, `chmod`, `symlink_to`, `hardlink_to`,
+ *    plus 3.14+ `move`, `move_into`, `copy`, `copy_into`.
+ *  - `shutil.*` EXCLUDING the confirmed read-only members `which`,
+ *    `disk_usage`, `get_terminal_size`, `get_archive_formats`,
+ *    `get_unpack_formats` — every other shutil function copies/moves/deletes.
+ *  - `os.*` mutators/exec: `remove`, `unlink`, `rename`, `replace`, `makedirs`,
+ *    `mkdir`, `rmdir`, `removedirs`, `chmod`, `chown`, `symlink`, `link`,
+ *    `truncate`, `chdir`, `fchdir`, `putenv`, `write`, `ftruncate`, `fchmod`,
+ *    `fchown`, `fork`, `system`, `popen`, plus the `exec*`/`spawn*`/
+ *    `posix_spawn` families.
+ *  - `subprocess.run|call|check_call|check_output|Popen|getoutput|getstatusoutput`
+ *    — the actual spawn surface. Non-spawning members (`PIPE`, `DEVNULL`,
+ *    `STDOUT`, `CompletedProcess`, `CalledProcessError`, …) are deliberately
+ *    excluded — a bare `subprocess\.\w+` would false-positive on those.
+ *  - `pickle.dump` / `json.dump` (the file-writing form — `\b` after `dump`
+ *    excludes `dumps`, which only serializes to a string/bytes in memory).
+ *  - `csv.writer`, `tempfile.*` (temp-file/dir creation is still a write).
+ *  - generic `.write(`/`.writelines(` — covers any file-like object, including
+ *    one opened via a variable this static check can't trace back to `open()`.
+ *  - `exec(`/`eval(` — arbitrary code execution, not merely file I/O.
+ *
+ * Deliberately NOT included: bare `import` statements, arithmetic/string
+ * formatting, `print`, `json.load`/`json.loads`, `sys.argv`/`os.environ` reads,
+ * `os.getcwd`/`os.listdir`/`os.path.*` — none of these mutate disk or spawn.
+ */
+export const PYTHON_WRITES: RegExp = new RegExp(
+  "\\bopen\\s*\\([^)]*(?:(['\"])(?:[wax]|r\\+|\\+r)[bt]?\\1|mode\\s*=\\s*(['\"])(?:[wax]|r\\+|\\+r)[bt]?\\2)"
+    + "|\\.(?:write_text|write_bytes|unlink|rename|replace|mkdir|rmdir|touch|chmod|symlink_to|hardlink_to"
+    + "|move_into|copy_into|move|copy|write|writelines)\\s*\\("
+    + "|\\bshutil\\.(?!which\\b|disk_usage\\b|get_terminal_size\\b|get_archive_formats\\b|get_unpack_formats\\b)\\w+"
+    + "|\\bos\\.(?:remove|unlink|rename|replace|makedirs|mkdir|rmdir|removedirs|system|popen|chmod|chown|symlink"
+    + "|link|truncate|chdir|fchdir|putenv|write|ftruncate|fchmod|fchown|fork)\\b"
+    + "|\\bos\\.(?:exec|spawn|posix_spawn)\\w*\\b"
+    + "|\\bsubprocess\\.(?:run|call|check_call|check_output|Popen|getoutput|getstatusoutput)\\b"
+    + "|\\bpickle\\.dump\\b"
+    + "|\\bjson\\.dump\\b"
+    + "|\\bcsv\\.writer\\b"
+    + "|\\btempfile\\.\\w+"
+    + "|\\b(?:exec|eval)\\s*\\(",
+);
+
+/** Redirect to a non-code file. Excludes `/dev/null`, `2>`/`N>` and `>&N` fd
+ * redirects via the `(?<![0-9&])` lookbehind + `(?!…|&)` (parity has_file_redirect). */
+export const FILE_REDIRECT: RegExp =
+  /(?<![0-9&])\s*>>?\s*(?!\/dev\/null|&)[a-zA-Z./~$]/;
+
+/** Other ambiguous file writers (ASK): `tee <file>` (not `tee -a`/path) and `dd … of=` —
+ * labeled sub-patterns (parity bash-write-guard.py `ASK_PATTERNS`). */
+export const ASK_WRITERS: readonly { re: RegExp; desc: string }[] = [
+  { re: /\btee\s+[^-/\s]/, desc: "tee to file" },
+  { re: /\bdd\b[^|]*\bof=/, desc: "dd output to file" },
+];
+
+/** Commands whose first token never writes, skipped when a real redirect is
+ * present (parity bash-write-guard.py `SAFE_PREFIXES`). */
+export const SAFE_PREFIXES: readonly string[] = [
+  "ls", "pwd", "which", "cat ", "head ", "tail ", "wc ", "file ", "stat ", "tree", "du ", "df ",
+  "find ", "grep ", "rg ", "git ", "cd ", "source ", "export ", "unset ", "env ", "printenv",
+  "bun test", "bun run", "bunx ", "npm test", "npm run", "npx ", "biome ", "eslint ",
+  "prettier ", "ruff ", "pyright ", "tsc ", "mkdir ", "mv ", "cp ",
+];
+
+/**
+ * Session-state directory the freshness/APEX gates rely on. Any Bash command
+ * touching it is a hook-bypass vector, so it is blocked outright — a blunt
+ * substring match (read OR write), parity with bash-write-guard.py DENY_PATTERNS
+ * `fusengine-cache/sessions` (rebranded to the harness cache path).
+ */
+export const SESSION_STATE_FRAGMENT = ".fuse-harness/cache/sessions";

package/src/policy/guards/bash-write-redirects.ts

@@ -0,0 +1,201 @@
+/** One active shell output-redirection operator and its parsed target. */
+export type ShellRedirect = Readonly<{ start: number; operator: string; target: string }>;
+
+function closingParen(input: string, start: number): number {
+  let depth = 1;
+  let quote: "'" | '"' | null = null;
+  for (let i = start; i < input.length; i++) {
+    const ch = input[i];
+    if (ch === "\\" && quote !== "'") { i++; continue; }
+    if (quote) { if (ch === quote) quote = null; continue; }
+    if (ch === "'" || ch === '"') { quote = ch; continue; }
+    if (ch === "(") { depth++; continue; }
+    if (ch === ")" && --depth === 0) return i;
+  }
+  return input.length;
+}
+
+function closingBacktick(input: string, start: number): number {
+  for (let i = start; i < input.length; i++) {
+    if (input[i] === "\\") { i++; continue; }
+    if (input[i] === "`") return i;
+  }
+  return input.length;
+}
+
+function closingArithmetic(input: string, start: number): number {
+  let depth = 1;
+  let quote: "'" | '"' | null = null;
+  for (let i = start; i < input.length; i++) {
+    const ch = input[i];
+    if (ch === "\\" && quote !== "'") { i++; continue; }
+    if (quote) { if (ch === quote) quote = null; continue; }
+    if (ch === "'" || ch === '"') { quote = ch; continue; }
+    if (ch === "(") { depth++; continue; }
+    if (ch !== ")") continue;
+    if (depth === 1 && input[i + 1] === ")") return i + 1;
+    depth--;
+  }
+  return input.length;
+}
+
+function closingConditional(input: string, start: number): number {
+  let quote: "'" | '"' | null = null;
+  for (let i = start; i < input.length - 1; i++) {
+    const ch = input[i];
+    if (ch === "\\" && quote !== "'") { i++; continue; }
+    if (quote) { if (ch === quote) quote = null; continue; }
+    if (ch === "'" || ch === '"') { quote = ch; continue; }
+    if (ch === "]" && input[i + 1] === "]") return i;
+  }
+  return input.length;
+}
+
+function commentStart(input: string, index: number, start: number): boolean {
+  return input[index] === "#" && (index === start || /[\s;|&()]/.test(input[index - 1] ?? ""));
+}
+
+function commandPosition(input: string, index: number, start: number): boolean {
+  const prefix = input.slice(start, index);
+  const segment = prefix.slice(Math.max(prefix.lastIndexOf(";"), prefix.lastIndexOf("|"), prefix.lastIndexOf("&"), prefix.lastIndexOf("\n")) + 1).trim();
+  return segment === "" || /^(?:if|elif|while|until|then|do|!)$/.test(segment);
+}
+
+function readTarget(input: string, start: number, end: number): string {
+  let out = "";
+  let quote: "'" | '"' | null = null;
+  for (let i = start; i < end; i++) {
+    const ch = input[i] ?? "";
+    if (ch === "\\" && quote !== "'") {
+      if (i + 1 < end) out += input[++i] ?? "";
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) quote = null;
+      else out += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') { quote = ch; continue; }
+    if (/\s|[;&|<>]/.test(ch)) break;
+    out += ch;
+  }
+  return out;
+}
+
+function scanDoubleQuote(input: string, start: number, end: number, out: ShellRedirect[]): number {
+  for (let i = start; i < end; i++) {
+    if (input[i] === "\\") { i++; continue; }
+    if (input[i] === '"') return i;
+    if (input[i] === "$" && input[i + 1] === "(" && input[i + 2] === "(") {
+      const close = closingArithmetic(input, i + 3);
+      scanExpansions(input, i + 3, close - 1, out);
+      i = close;
+    } else if (input[i] === "$" && input[i + 1] === "(") {
+      const close = closingParen(input, i + 2);
+      scanRange(input, i + 2, close, out);
+      i = close;
+    } else if (input[i] === "`") {
+      const close = closingBacktick(input, i + 1);
+      scanRange(input, i + 1, close, out);
+      i = close;
+    }
+  }
+  return end;
+}
+
+function scanExpansions(input: string, start: number, end: number, out: ShellRedirect[]): void {
+  for (let i = start; i < end; i++) {
+    if (input[i] === "\\") { i++; continue; }
+    if (commentStart(input, i, start)) {
+      const newline = input.indexOf("\n", i + 1);
+      i = newline < 0 || newline >= end ? end : newline;
+      continue;
+    }
+    if (input[i] === "'") {
+      const close = input.indexOf("'", i + 1);
+      i = close < 0 || close >= end ? end : close;
+      continue;
+    }
+    if (input[i] === '"') { i = scanDoubleQuote(input, i + 1, end, out); continue; }
+    if (input[i] === "$" && input[i + 1] === "(" && input[i + 2] === "(") {
+      const close = closingArithmetic(input, i + 3);
+      scanExpansions(input, i + 3, close - 1, out);
+      i = close;
+    } else if (input[i] === "$" && input[i + 1] === "(") {
+      const close = closingParen(input, i + 2);
+      scanRange(input, i + 2, close, out);
+      i = close;
+    } else if (input[i] === "`") {
+      const close = closingBacktick(input, i + 1);
+      scanRange(input, i + 1, close, out);
+      i = close;
+    }
+  }
+}
+
+function scanRange(input: string, start: number, end: number, out: ShellRedirect[]): void {
+  for (let i = start; i < end; i++) {
+    const ch = input[i];
+    if (ch === "\\") { i++; continue; }
+    if (commentStart(input, i, start)) {
+      const newline = input.indexOf("\n", i + 1);
+      i = newline < 0 || newline >= end ? end : newline;
+      continue;
+    }
+    if (ch === "'") {
+      const close = input.indexOf("'", i + 1);
+      i = close < 0 || close >= end ? end : close;
+      continue;
+    }
+    if (ch === '"') { i = scanDoubleQuote(input, i + 1, end, out); continue; }
+    if (ch === "[" && input[i + 1] === "[" && commandPosition(input, i, start)) {
+      const close = closingConditional(input, i + 2);
+      scanExpansions(input, i + 2, close, out);
+      i = close + 1;
+      continue;
+    }
+    if (ch === "(" && input[i + 1] === "(" && commandPosition(input, i, start)) {
+      const close = closingArithmetic(input, i + 2);
+      scanExpansions(input, i + 2, close - 1, out);
+      i = close;
+      continue;
+    }
+    if (ch === "$" && input[i + 1] === "(" && input[i + 2] === "(") {
+      const close = closingArithmetic(input, i + 3);
+      scanExpansions(input, i + 3, close - 1, out);
+      i = close;
+      continue;
+    }
+    if (ch === "$" && input[i + 1] === "(") {
+      const close = closingParen(input, i + 2);
+      scanRange(input, i + 2, close, out);
+      i = close;
+      continue;
+    }
+    if (ch === "`") {
+      const close = closingBacktick(input, i + 1);
+      scanRange(input, i + 1, close, out);
+      i = close;
+      continue;
+    }
+    if (ch !== ">") continue;
+    if (input[i + 1] === "(") continue;
+    if (input[i - 1] === "&") { if (input[i + 1] === ">") i++; continue; }
+    let opStart = i;
+    while (opStart > start && /\d/.test(input[opStart - 1] ?? "")) opStart--;
+    if (input[opStart - 1] === "&") opStart--;
+    let cursor = i + (input[i + 1] === ">" || input[i + 1] === "|" ? 2 : 1);
+    const operator = input.slice(opStart, cursor);
+    while (/\s/.test(input[cursor] ?? "")) cursor++;
+    if (input[cursor] === "&") continue;
+    const target = readTarget(input, cursor, end);
+    if (target) out.push({ start: opStart, operator, target });
+  }
+}
+
+/** Return active output redirects, excluding quoted/escaped `>` characters. */
+export function shellOutputRedirects(command: string): ShellRedirect[] {
+  const out: ShellRedirect[] = [];
+  scanRange(command, 0, command.length, out);
+  return out;
+}

package/src/policy/guards/bash-write-safe-paths.ts

@@ -0,0 +1,62 @@
+import { join, normalize } from "node:path";
+import { homedir } from "node:os";
+import { claudeHome, fusengineCache } from "../../runtime/home-state";
+import { shellOutputRedirects } from "./bash-write-redirects";
+
+/**
+ * Writable paths the harness owns — writes here never need Write/Edit's APEX
+ * gates. Parity safe_paths.py `SAFE_WRITE_PATHS`; `~/.claude/fusengine-cache`
+ * is rebranded to `~/.fuse-harness/cache`, `~/.claude/logs` is unchanged.
+ */
+export const SAFE_WRITE_PATHS: readonly string[] = [fusengineCache(), join(claudeHome(), "logs")];
+
+/** Raw, un-expanded forms of {@link SAFE_WRITE_PATHS} for substring matching
+ * when a shell didn't expand `~` (parity safe_paths.py `_SAFE_RAW`). */
+const SAFE_WRITE_RAW: readonly string[] = ["~/.fuse-harness/cache", "~/.claude/logs"];
+
+/** Strip quotes, expand `~`/`$HOME`, normalize (parity safe_paths.resolve_path). */
+function resolvePath(raw: string): string {
+  const stripped = raw.trim().replace(/^['"]|['"]$/g, "");
+  // POSIX tilde-prefix: only `~` alone or a `~/` prefix is `$HOME`-relative.
+  // `~user`, `~2xyz`, `~+`, `~N` are login-name/dir-stack forms — leave unexpanded.
+  const expanded = stripped === "~" || stripped.startsWith("~/") ? homedir() + stripped.slice(1) : stripped;
+  return normalize(expanded.replace(/\$HOME/g, homedir()));
+}
+
+/** True when a `>`/`>>` redirect targets a harness-owned safe path (parity is_safe_write_path). */
+export function isSafeWritePath(cmd: string): boolean {
+  const targets = shellOutputRedirects(cmd)
+    .map((redirect) => resolvePath(redirect.target))
+    .filter((target) => target !== "/dev/null");
+  return targets.length > 0 && targets.every((target) => SAFE_WRITE_PATHS.some((safe) => target === safe || target.startsWith(safe + "/")));
+}
+
+/** Extract the file argument of `tee`/`dd of=` (parity extract_command_target). */
+function extractCommandTarget(cmd: string): string | null {
+  const tee = cmd.match(/\btee\s+(?:-[a-z]\s+)*(\S+)/);
+  if (tee?.[1]) return resolvePath(tee[1]);
+  const dd = cmd.match(/\bdd\b[^|]*\bof=(\S+)/);
+  return dd?.[1] ? resolvePath(dd[1]) : null;
+}
+
+/** True when a `tee`/`dd` target is a harness-owned safe path (parity is_safe_command_target). */
+export function isSafeCommandTarget(cmd: string): boolean {
+  const target = extractCommandTarget(cmd);
+  return target !== null && SAFE_WRITE_PATHS.some((safe) => target === safe || target.startsWith(safe + "/"));
+}
+
+/**
+ * True when the command quotes a safe path as a string literal (parity
+ * has_safe_write_target, hardened: the Python original — and this function
+ * before this fix — does an unanchored substring match, which fail-opens any
+ * `node -e` containing the safe path text anywhere, including inside an inert
+ * comment. Requiring it to appear as a quoted literal still covers the real
+ * use case (`fs.appendFileSync('~/.fuse-harness/cache/x.json', ...)`).
+ */
+export function hasSafeWriteTarget(cmd: string): boolean {
+  // Quote-anchored segment boundary: exact quoted literal OR quoted sub-path
+  // (e.g. 'fusengineCache()/x.json' — a real file under the safe dir).
+  const quoted = (p: string): boolean =>
+    cmd.includes(`'${p}'`) || cmd.includes(`"${p}"`) || cmd.includes(`'${p}/`) || cmd.includes(`"${p}/`);
+  return SAFE_WRITE_PATHS.some(quoted) || SAFE_WRITE_RAW.some(quoted);
+}

package/src/policy/guards/bash-write.ts

@@ -0,0 +1,76 @@
+import type { Prompt } from "../../prompt/types";
+import type { GuardContext } from "./context";
+import { hasSafeWriteTarget, isSafeCommandTarget, isSafeWritePath } from "./bash-write-safe-paths";
+import { shellOutputRedirects } from "./bash-write-redirects";
+import {
+  ASK_WRITERS, CODE_COMMAND_WRITE, CODE_MUTATORS, NODE_WRITES,
+  PYTHON_C_ANCHOR, PYTHON_WRITES, RUBY_WRITES, SAFE_PREFIXES, SESSION_STATE_FRAGMENT,
+} from "./bash-write-patterns";
+
+export { ASK_WRITERS, CODE_MUTATORS, CODE_REDIRECT, FILE_REDIRECT, SAFE_PREFIXES, SESSION_STATE_FRAGMENT } from "./bash-write-patterns";
+
+function blockCodeWrite(reason: string): Prompt {
+  return { kind: "block", title: "Bash write to code file", reason, actions: ["Use the Write/Edit tool instead"] };
+}
+function askFileWrite(reason: string, ruleId = "bash-write:file-write"): Prompt {
+  return { kind: "ask", ruleId, title: "Bash file write", reason, actions: ["Use the Write/Edit tool instead"] };
+}
+
+/**
+ * Blocks shell commands that mutate code files in place (and heredocs/redirects
+ * to source files); asks before other file-writing shell commands unless the
+ * target is a harness-owned safe path. Forces use of the Write/Edit tool so
+ * APEX/SOLID checks are not bypassed.
+ *
+ * The code-write detectors (CODE_MUTATORS, CODE_COMMAND_WRITE) run BEFORE the
+ * SAFE_PREFIXES short-circuit: they are command-position anchored
+ * (bash-command-anchor.ts), so a transparent wrapper (`env sed -i src/x.ts`,
+ * `timeout 5 patch`, `cp a b; tee src/y.ts`) can no longer smuggle a code write
+ * past its safe first token, while a quoted mention (`git commit -m "fix sed -i"`)
+ * still falls through. The short-circuit becomes the terminal allow — "first
+ * token never writes, nothing above matched".
+ */
+export function bashWriteGuard(ctx: GuardContext): Prompt | null {
+  if (ctx.tool !== "Bash" || !ctx.command) return null;
+  const cmd: string = ctx.command;
+  const stripped = cmd.trim();
+  const redirects = shellOutputRedirects(cmd).filter((redirect) => redirect.target !== "/dev/null");
+
+  const mutator = CODE_MUTATORS.find((m) => m.re.test(cmd));
+  if (mutator) return blockCodeWrite(`${mutator.desc} — Use Edit/Write tools instead`);
+  if (CODE_COMMAND_WRITE.test(cmd)) return blockCodeWrite("tee/dd into a code file — Use Edit/Write tools instead");
+  if (PYTHON_C_ANCHOR.test(cmd) && PYTHON_WRITES.test(cmd)) {
+    return blockCodeWrite("Python inline script mutates files/spawns a process — Use Edit/Write tools instead");
+  }
+
+  if (SAFE_PREFIXES.some((p) => stripped.startsWith(p)) && redirects.length === 0) {
+    return null;
+  }
+
+  if (cmd.includes(SESSION_STATE_FRAGMENT)) {
+    return {
+      kind: "block",
+      title: "Session-state tampering",
+      reason: "Bash access to the harness session-state directory is a hook-bypass vector — the freshness/APEX enforcement reads it to decide block/allow.",
+      actions: ["Never read or write session state from the shell"],
+    };
+  }
+
+  if (redirects.length > 0) {
+    if (isSafeWritePath(cmd)) return null;
+    return redirects.some((redirect) => /\.(?:ts|tsx|js|jsx|py|go|rb|rs|java|kt|php|swift|vue|svelte|astro|css|c|cpp|h)\b/.test(redirect.target))
+      ? blockCodeWrite("Bash redirect to code file — Use Write/Edit tools (enforces APEX + SOLID specs)")
+      : askFileWrite("Shell redirect to file detected. Authorize?", "bash-write:file-redirect");
+  }
+
+  if (/\bnode\s+-e\b/.test(cmd) && NODE_WRITES.test(cmd)) {
+    return hasSafeWriteTarget(cmd) ? null : askFileWrite("Node.js write operation detected. Authorize?");
+  }
+  if (/\bruby\s+-e\b/.test(cmd) && RUBY_WRITES.test(cmd)) return askFileWrite("Ruby write operation detected. Authorize?");
+
+  const asker = ASK_WRITERS.find((a) => a.re.test(cmd));
+  if (asker) {
+    return isSafeCommandTarget(cmd) ? null : askFileWrite(`${asker.desc} detected. Authorize?`);
+  }
+  return null;
+}

package/src/policy/guards/context.ts

@@ -0,0 +1,12 @@
+import type { Prompt } from "../../prompt/types";
+
+/** Context handed to every guard in the chain. */
+export interface GuardContext {
+  tool: string;
+  filePath?: string;
+  content?: string;
+  command?: string;
+}
+
+/** A single guard: returns a blocking/asking Prompt, or null to continue. */
+export type Guard = (ctx: GuardContext) => Prompt | null;