thinkpool-pair 0.7.364 → 0.7.366

package/flow-review-gate.mjs

@@ -1,402 +1 @@
-// Thinkpool Flow — S5 adversarial reviewer tool-call gate.
-//
-// Pure decision function: given a reviewer lane's tool call, decide whether to allow or
-// deny it. No fs side-effects except realpathSync (injectable via _realpath for tests).
-//
-// Spec: docs/specs/2026-06-30-flow-build-s5-reviewer-writeblock.md (S5, slice 1).
-//
-// Rules:
-//   READ-ONLY tools (Read, Grep, Glob, LS, …) → ALLOW (always)
-//   Edit / Write / NotebookEdit → structural path check against sliceRoot:
-//     • file_path resolves under sliceRoot AND is NOT verdictFile → DENY
-//     • file_path IS verdictFile (FLOW_REVIEW.json) → ALLOW (unless it symlinks into slice)
-//   Bash → ALLOW by default (reviewer MUST run tests); DENY on write-to-slice heuristics
-//   Unknown tools → DENY (conservative; add to READ_ONLY_TOOLS if truly non-mutating)
-//
-// Path-robustness:
-//   • '..' traversal: caught by path.resolve() normalization.
-//   • Absolute-escape: caught by path.resolve() normalization.
-//   • Symlink escape: caught by realpathSync() (injectable for tests). A write whose REAL
-//     resolved path lands under sliceRoot is denied even through a symlink.
-//   • Symlinked verdictFile pointing into the slice is denied.
-//   • Both canonical (realpathSync) and input (path.resolve) forms of sliceRoot are checked
-//     to handle cases where sliceRoot itself is a symlink (e.g. macOS /tmp → /private/tmp).
-//
-// BASH LIMITATION: Bash write-detection is HEURISTIC (best-effort pattern matching), unlike
-// Edit/Write/NotebookEdit which have a structural file_path field. Shell quoting, variable
-// expansion, heredocs, subshells, and aliases can bypass these patterns. The reviewer prompt
-// already instructs it not to modify the slice; this gate is a structural backstop for the
-// common cases, not a complete shell parser. If precise Bash blocking is required, use a
-// wrapper that translates shell commands into structured tool calls.
-//
-// ACCEPTED LIMITATIONS (do not add fragile parsers for these):
-//   • python3 -c '...' / node -e '...' inline scripts: scripted writes embedded in string
-//     literals are not parsed — detecting them reliably requires a full language parser.
-//   • bare `git commit` / `git add .` with no explicit slice path: the gate detects git
-//     mutations only when sliceRoot appears literally in the command (via -C flag or path
-//     arg). A bare git command that relies on cwd is NOT caught by this heuristic.
-//   REAL MITIGATION: the reviewer lane runs in its OWN git worktree (not the slice's).
-//   Bare cwd-relative git mutations and inline scripted writes therefore affect the
-//   reviewer's worktree, not the slice. The wiring layer that provisions the reviewer lane
-//   MUST guarantee this worktree isolation — this gate cannot substitute for it.
-
-import { realpathSync as nodeRealpathSync, readlinkSync, lstatSync } from 'node:fs'
-import path from 'node:path'
-
-// ── Tool classification ───────────────────────────────────────────────────────
-
-// Tools that cannot mutate files — always allowed for a reviewer.
-const READ_ONLY_TOOLS = new Set([
-  'Read', 'Grep', 'Glob', 'LS',
-  // Other non-mutating Claude Code tools:
-  'WebFetch', 'WebSearch', 'Search', 'TodoRead', 'Explore',
-])
-
-// Tools that write files — must have file_path checked before allowing.
-const FILE_WRITE_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit'])
-
-// Git subcommands that mutate the working tree.
-const GIT_MUTATING_RE = /\b(?:add|commit|apply|checkout|reset|revert|rm|clean|merge|rebase|cherry-pick|stash)\b/
-
-// Shell commands that write to a path positional argument (HEURISTIC — see BASH LIMITATION).
-// cp and mv are handled separately via CP_MV_RE — only their DESTINATION is checked,
-// so that reading FROM the slice (e.g. cp /slice/f /tmp/x) is allowed.
-const BASH_WRITE_CMD_RE = /\b(?:rm|tee|truncate|dd|install)\b/
-
-// cp/mv require destination-aware analysis — see _assessBashCommand.
-const CP_MV_RE = /\b(?:cp|mv)\b/
-
-// sed in-place edit.
-const SED_INPLACE_RE = /\bsed\b[^|;]*-i\b/
-
-// ── reviewGateDecision ────────────────────────────────────────────────────────
-
-/**
- * Decide whether a reviewer lane's tool call is allowed.
- *
- * @param {object} opts
- * @param {string}   opts.toolName     Tool name ('Read', 'Write', 'Bash', …).
- * @param {object}  [opts.input]       Tool input (e.g. { file_path } or { command }).
- * @param {string}   opts.sliceRoot    Absolute path of the directory tree under review.
- * @param {string}  [opts.verdictFile] Absolute path where reviewer writes FLOW_REVIEW.json.
- *                                     Writes to this exact path are ALLOWED unless it
- *                                     symlinks back into sliceRoot.
- * @param {function}[opts._realpath]   Injectable realpathSync (default: node:fs realpathSync).
- * @returns {{ allow: boolean, reason: string }}
- */
-export function reviewGateDecision ({
-  toolName,
-  input = {},
-  sliceRoot,
-  verdictFile,
-  _realpath = nodeRealpathSync,
-}) {
-  if (!sliceRoot) {
-    return { allow: false, reason: 'sliceRoot not provided — gate cannot assess containment; denied' }
-  }
-
-  // Resolve both forms of sliceRoot so comparisons work whether or not sliceRoot is
-  // itself a symlink (e.g. macOS /tmp → /private/tmp).
-  const inputSliceRoot = path.resolve(sliceRoot)
-  let canonicalSliceRoot
-  try {
-    canonicalSliceRoot = _realpath(sliceRoot)
-  } catch {
-    canonicalSliceRoot = inputSliceRoot
-  }
-
-  // ── READ-ONLY TOOLS ───────────────────────────────────────────────────
-  if (READ_ONLY_TOOLS.has(toolName)) {
-    return { allow: true, reason: `${toolName} is a read-only tool — allowed` }
-  }
-
-  // ── FILE WRITE TOOLS ──────────────────────────────────────────────────
-  if (FILE_WRITE_TOOLS.has(toolName)) {
-    const filePath = input.file_path
-    if (!filePath) {
-      return {
-        allow: false,
-        reason: `${toolName} has no file_path — cannot assess containment; denied conservatively`,
-      }
-    }
-    return _assessFilePath({
-      filePath, toolName,
-      inputSliceRoot, canonicalSliceRoot,
-      verdictFile, _realpath,
-    })
-  }
-
-  // ── BASH ──────────────────────────────────────────────────────────────
-  if (toolName === 'Bash') {
-    const cmd = typeof input.command === 'string' ? input.command : ''
-    return _assessBashCommand({ cmd, inputSliceRoot, canonicalSliceRoot })
-  }
-
-  // ── UNKNOWN TOOLS ─────────────────────────────────────────────────────
-  // Conservative default: deny unknown tools — they may be mutating.
-  // To allow a new read-only tool, add it to READ_ONLY_TOOLS above.
-  return {
-    allow: false,
-    reason: `Unknown tool "${toolName}" — denied by default (not in READ_ONLY_TOOLS; add if truly read-only)`,
-  }
-}
-
-// ── _assessFilePath ───────────────────────────────────────────────────────────
-
-function _assessFilePath ({
-  filePath, toolName,
-  inputSliceRoot, canonicalSliceRoot,
-  verdictFile, _realpath,
-}) {
-  const resolved = path.resolve(filePath)
-
-  // Is this a write to the verdictFile (FLOW_REVIEW.json)?
-  if (verdictFile) {
-    const resolvedVerdict = path.resolve(verdictFile)
-    if (resolved === resolvedVerdict) {
-      // B4 fix: check resolved path FIRST — before any symlink/realpath logic.
-      // If verdictFile's resolved path is inside sliceRoot, deny regardless of whether
-      // the file exists yet. The old ENOENT catch path ("no symlink possible; allow")
-      // was the hole: a non-existent verdictFile inside sliceRoot slipped through.
-      if (_isUnder(resolvedVerdict, canonicalSliceRoot) || _isUnder(resolvedVerdict, inputSliceRoot)) {
-        return {
-          allow: false,
-          reason: `verdictFile "${verdictFile}" resolves inside sliceRoot — denied`,
-        }
-      }
-      // Secondary check: deny if an existing verdictFile is a symlink INTO the slice.
-      // (Handles indirect containment via symlinks that point inside sliceRoot.)
-      try {
-        const realVerdict = _realpath(verdictFile)
-        if (_isUnder(realVerdict, canonicalSliceRoot) || _isUnder(realVerdict, inputSliceRoot)) {
-          return {
-            allow: false,
-            reason: `verdictFile "${verdictFile}" is a symlink resolving to "${realVerdict}" inside sliceRoot — denied`,
-          }
-        }
-      } catch {
-        // verdictFile doesn't exist yet — realpathSync(verdictFile) threw ENOENT.
-        // That does NOT prove "no symlink possible": a symlinked ANCESTOR directory (or a
-        // dangling symlink named FLOW_REVIEW.json) can still resolve the write into the slice.
-        // Realpath the nearest EXISTING ancestor and re-check containment of the full target.
-        const realAncestor = _realpathNearestAncestor(resolvedVerdict, _realpath)
-        if (realAncestor && (_isUnder(realAncestor, canonicalSliceRoot) || _isUnder(realAncestor, inputSliceRoot))) {
-          return {
-            allow: false,
-            reason: `verdictFile "${verdictFile}" resolves (via a symlinked path component) to "${realAncestor}" inside sliceRoot — denied`,
-          }
-        }
-      }
-      return { allow: true, reason: `write to verdictFile (${path.basename(verdictFile)}) — allowed` }
-    }
-  }
-
-  // Not the verdictFile. Check whether the write target lands inside the slice.
-
-  // 1. String-level check — catches '..' traversal and absolute paths into sliceRoot.
-  if (_isUnder(resolved, canonicalSliceRoot) || _isUnder(resolved, inputSliceRoot)) {
-    return {
-      allow: false,
-      reason: `${toolName} to "${filePath}" (resolved: "${resolved}") is inside sliceRoot — denied`,
-    }
-  }
-
-  // 2. Realpath check — catches symlinks whose TARGET is inside sliceRoot.
-  try {
-    const real = _realpath(filePath)
-    if (_isUnder(real, canonicalSliceRoot) || _isUnder(real, inputSliceRoot)) {
-      return {
-        allow: false,
-        reason: `${toolName} to "${filePath}" symlinks to "${real}" inside sliceRoot — denied`,
-      }
-    }
-  } catch {
-    // ENOENT — the file (or a component of it) doesn't exist yet, so realpathSync(filePath)
-    // threw before it could follow any symlinked ANCESTOR directory. Step 1 only normalized
-    // '..' — it did NOT resolve a symlinked path component (e.g. scratch/link → sliceRoot,
-    // then Write scratch/link/PWNED.js lands in the slice). Realpath the nearest EXISTING
-    // ancestor, re-join the un-created tail, and re-check containment.
-    const realAncestor = _realpathNearestAncestor(resolved, _realpath)
-    if (realAncestor && (_isUnder(realAncestor, canonicalSliceRoot) || _isUnder(realAncestor, inputSliceRoot))) {
-      return {
-        allow: false,
-        reason: `${toolName} to "${filePath}" resolves (via a symlinked path component) to "${realAncestor}" inside sliceRoot — denied`,
-      }
-    }
-  }
-
-  return { allow: true, reason: `${toolName} to "${filePath}" is outside sliceRoot — allowed` }
-}
-
-// ── _realpathNearestAncestor ────────────────────────────────────────────────────
-// For a target path that does NOT fully exist (realpathSync threw ENOENT), walk UP to the
-// nearest existing ancestor directory, realpath-resolve THAT (following any symlinked
-// component), then re-join the remaining un-created tail. The returned absolute path is what
-// the write would ACTUALLY land on once created — which is what containment must be tested
-// against. Returns null only if even the filesystem root can't be resolved (never expected).
-function _realpathNearestAncestor (resolved, _realpath) {
-  // If the LEAF itself is a symlink (existing but DANGLING — its target doesn't exist, so
-  // realpathSync(resolved) threw), follow the link one hop and resolve from THERE. This is the
-  // dangling-verdict-symlink case: scratch/FLOW_REVIEW.json → <sliceRoot>/evil.js. path.resolve
-  // does NOT follow symlinks, so without this the write's true landing spot is invisible.
-  try {
-    if (lstatSync(resolved).isSymbolicLink()) {
-      const linkTarget = readlinkSync(resolved)
-      const absTarget = path.isAbsolute(linkTarget)
-        ? linkTarget
-        : path.resolve(path.dirname(resolved), linkTarget)
-      // Recurse: the target may itself be non-existent / chained through more symlinks.
-      try {
-        return _realpath(absTarget)
-      } catch {
-        return _realpathNearestAncestor(absTarget, _realpath)
-      }
-    }
-  } catch {
-    // lstat failed — leaf doesn't exist at all; fall through to ancestor walk below.
-  }
-
-  let ancestor = path.dirname(resolved)
-  const tail = [path.basename(resolved)]
-  // Walk up until an ancestor resolves, or we hit the root (dirname is a fixed point).
-  while (true) {
-    try {
-      const realAncestor = _realpath(ancestor)
-      return path.join(realAncestor, ...tail.reverse())
-    } catch {
-      const parent = path.dirname(ancestor)
-      if (parent === ancestor) return null // reached root without resolving — give up
-      tail.push(path.basename(ancestor))
-      ancestor = parent
-    }
-  }
-}
-
-// ── _assessBashCommand ────────────────────────────────────────────────────────
-// HEURISTIC — see BASH LIMITATION comment at top of file.
-
-function _assessBashCommand ({ cmd, inputSliceRoot, canonicalSliceRoot }) {
-  // Returns true if `str` (a path extracted from the command) resolves under sliceRoot.
-  function inSlice (str) {
-    if (!str) return false
-    const abs = path.isAbsolute(str) ? str : path.resolve(str)
-    return _isUnder(abs, canonicalSliceRoot) || _isUnder(abs, inputSliceRoot)
-  }
-
-  // Returns true if either form of sliceRoot appears literally in the command string.
-  // Used for commands that embed the target path as a positional argument.
-  function cmdContainsSlice () {
-    return cmd.includes(canonicalSliceRoot) || cmd.includes(inputSliceRoot)
-  }
-
-  // ── Output redirection (> or >>) into sliceRoot ───────────────────────
-  // HEURISTIC: misses paths with spaces and shell variable expansion.
-  // Negative lookbehind excludes '<' so '<<' (heredoc) and '<>' (r/w) are not
-  // misread as write redirections.
-  // Group 1: optional surrounding quote char; group 2: the path (stripped of quotes).
-  // This catches both `> /slice/f` (unquoted) and `> "/slice/f"` / `> '/slice/f'` (D1/D2).
-  const redirRe = /(?<![<])>+\s*(['"]?)([^\s;|&'"]+)\1/g
-  let m
-  while ((m = redirRe.exec(cmd)) !== null) {
-    if (inSlice(m[2])) {
-      return {
-        allow: false,
-        reason: `Bash output redirection to "${m[2]}" targets sliceRoot — denied`,
-      }
-    }
-  }
-
-  // ── git mutating commands targeting sliceRoot ─────────────────────────
-  if (/\bgit\b/.test(cmd) && GIT_MUTATING_RE.test(cmd)) {
-    // Explicit -C flag: `git -C <dir> <verb>`
-    const cwdMatch = cmd.match(/-C\s+(['"]?)([^\s'"]+)\1/)
-    if (cwdMatch) {
-      const cwdArg = cwdMatch[2]
-      if (inSlice(cwdArg)) {
-        return {
-          allow: false,
-          reason: `Bash "git -C ${cwdArg} ..." targets sliceRoot — denied`,
-        }
-      }
-    }
-    // Fallback: sliceRoot path appears anywhere in a mutating git command.
-    if (cmdContainsSlice()) {
-      return { allow: false, reason: 'Bash git mutating command references sliceRoot — denied' }
-    }
-  }
-
-  // ── cp/mv: only deny when DESTINATION (last positional arg) is inside sliceRoot ──
-  // C5 fix: the old approach (cmdContainsSlice) wrongly denied `cp /slice/f /tmp/x`
-  // because sliceRoot appeared as the SOURCE. Only the destination can cause a write.
-  if (CP_MV_RE.test(cmd)) {
-    const tokens = cmd.trim().split(/\s+/)
-    // Skip the verb (i=0) and option flags; remaining tokens are positional path args.
-    const pathArgs = tokens.filter((t, i) => i > 0 && !t.startsWith('-'))
-    const dest = pathArgs[pathArgs.length - 1]
-    if (dest && inSlice(dest)) {
-      const verb = (cmd.match(CP_MV_RE) || [''])[0]
-      return {
-        allow: false,
-        reason: `Bash "${verb}" destination "${dest}" targets sliceRoot — denied`,
-      }
-    }
-  }
-
-  // ── rm / tee / truncate / dd / install targeting sliceRoot ──
-  if (BASH_WRITE_CMD_RE.test(cmd) && cmdContainsSlice()) {
-    const verb = (cmd.match(BASH_WRITE_CMD_RE) || [''])[0]
-    return {
-      allow: false,
-      reason: `Bash write command "${verb}" references sliceRoot — denied`,
-    }
-  }
-
-  // ── sed -i targeting sliceRoot ────────────────────────────────────────
-  if (SED_INPLACE_RE.test(cmd) && cmdContainsSlice()) {
-    return { allow: false, reason: 'Bash "sed -i" references sliceRoot — denied' }
-  }
-
-  return { allow: true, reason: 'Bash command allowed (no write-to-slice pattern detected)' }
-}
-
-// ── reviewGatePreToolDecision ───────────────────────────────────────────────────
-// S5 (slice 1b) — the LIVE PreToolUse wiring seam. Lives HERE (not in claude-session.mjs)
-// so it stays SDK-free and unit-testable: claude-session.mjs pulls the Claude Agent SDK at
-// module load, which isn't resolvable in the test env. The PreToolUse hook imports and calls
-// this; the integration test imports it directly.
-//
-// `reviewGate` is a per-review-lane closure (bridge.mjs folds reviewGateDecision over the
-// reviewed slices' worktree roots); it is NULL on builder lanes. Returns:
-//   • null       → fall through to the normal permission path (read / run-test / verdict).
-//   • deny payload → a terminal PreToolUse `permissionDecision: 'deny'` the hook returns
-//                    immediately — BEFORE the auto-allow/bypass path, so the block is
-//                    structural even in the lane's bypassPermissions mode.
-// A throwing reviewGate fails CLOSED (deny) — never a silent allow. Builder lanes
-// (reviewGate=null) always return null here → their toolset is UNCHANGED.
-export function reviewGatePreToolDecision ({ reviewGate, toolName, toolInput }) {
-  if (!reviewGate) return null
-  let g = null
-  try {
-    g = reviewGate({ toolName, input: toolInput })
-  } catch (e) {
-    g = { allow: false, reason: `review gate error — denied: ${e?.message || e}` }
-  }
-  if (g && g.allow === false) {
-    return {
-      continue: true,
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        permissionDecision: 'deny',
-        permissionDecisionReason: `Blocked (Flow review lane): ${g.reason} You REVIEW the slice — you do not edit it. Read it, run it to reproduce acceptance, then emit your verdict by Writing FLOW_REVIEW.json.`,
-      },
-    }
-  }
-  return null
-}
-
-// ── helpers ───────────────────────────────────────────────────────────────────
-
-// Returns true if `filePath` equals `dir` OR is strictly inside it.
-function _isUnder (filePath, dir) {
-  return filePath === dir || filePath.startsWith(dir + path.sep)
-}
+import{realpathSync as e,readlinkSync as t,lstatSync as o}from"node:fs";import n from"node:path";const i=new Set(["Read","Grep","Glob","LS","WebFetch","WebSearch","Search","TodoRead","Explore"]),r=new Set(["Edit","Write","NotebookEdit"]),s=/\b(?:add|commit|apply|checkout|reset|revert|rm|clean|merge|rebase|cherry-pick|stash)\b/,a=/\b(?:rm|tee|truncate|dd|install)\b/,l=/\b(?:cp|mv)\b/,c=/\bsed\b[^|;]*-i\b/;export function reviewGateDecision({toolName:t,input:o={},sliceRoot:m,verdictFile:f,_realpath:h=e}){if(!m)return{allow:!1,reason:"sliceRoot not provided — gate cannot assess containment; denied"};const p=n.resolve(m);let w;try{w=h(m)}catch{w=p}if(i.has(t))return{allow:!0,reason:`${t} is a read-only tool — allowed`};if(r.has(t)){const e=o.file_path;return e?function({filePath:e,toolName:t,inputSliceRoot:o,canonicalSliceRoot:i,verdictFile:r,_realpath:s}){const a=n.resolve(e);if(r){const e=n.resolve(r);if(a===e){if(u(e,i)||u(e,o))return{allow:!1,reason:`verdictFile "${r}" resolves inside sliceRoot — denied`};try{const e=s(r);if(u(e,i)||u(e,o))return{allow:!1,reason:`verdictFile "${r}" is a symlink resolving to "${e}" inside sliceRoot — denied`}}catch{const t=d(e,s);if(t&&(u(t,i)||u(t,o)))return{allow:!1,reason:`verdictFile "${r}" resolves (via a symlinked path component) to "${t}" inside sliceRoot — denied`}}return{allow:!0,reason:`write to verdictFile (${n.basename(r)}) — allowed`}}}if(u(a,i)||u(a,o))return{allow:!1,reason:`${t} to "${e}" (resolved: "${a}") is inside sliceRoot — denied`};try{const n=s(e);if(u(n,i)||u(n,o))return{allow:!1,reason:`${t} to "${e}" symlinks to "${n}" inside sliceRoot — denied`}}catch{const n=d(a,s);if(n&&(u(n,i)||u(n,o)))return{allow:!1,reason:`${t} to "${e}" resolves (via a symlinked path component) to "${n}" inside sliceRoot — denied`}}return{allow:!0,reason:`${t} to "${e}" is outside sliceRoot — allowed`}}({filePath:e,toolName:t,inputSliceRoot:p,canonicalSliceRoot:w,verdictFile:f,_realpath:h}):{allow:!1,reason:`${t} has no file_path — cannot assess containment; denied conservatively`}}return"Bash"===t?function({cmd:e,inputSliceRoot:t,canonicalSliceRoot:o}){function i(e){if(!e)return!1;const i=n.isAbsolute(e)?e:n.resolve(e);return u(i,o)||u(i,t)}function r(){return e.includes(o)||e.includes(t)}const d=/(?<![<])>+\s*(['"]?)([^\s;|&'"]+)\1/g;let m;for(;null!==(m=d.exec(e));)if(i(m[2]))return{allow:!1,reason:`Bash output redirection to "${m[2]}" targets sliceRoot — denied`};if(/\bgit\b/.test(e)&&s.test(e)){const t=e.match(/-C\s+(['"]?)([^\s'"]+)\1/);if(t){const e=t[2];if(i(e))return{allow:!1,reason:`Bash "git -C ${e} ..." targets sliceRoot — denied`}}if(r())return{allow:!1,reason:"Bash git mutating command references sliceRoot — denied"}}if(l.test(e)){const t=e.trim().split(/\s+/).filter((e,t)=>t>0&&!e.startsWith("-")),o=t[t.length-1];if(o&&i(o))return{allow:!1,reason:`Bash "${(e.match(l)||[""])[0]}" destination "${o}" targets sliceRoot — denied`}}return a.test(e)&&r()?{allow:!1,reason:`Bash write command "${(e.match(a)||[""])[0]}" references sliceRoot — denied`}:c.test(e)&&r()?{allow:!1,reason:'Bash "sed -i" references sliceRoot — denied'}:{allow:!0,reason:"Bash command allowed (no write-to-slice pattern detected)"}}({cmd:"string"==typeof o.command?o.command:"",inputSliceRoot:p,canonicalSliceRoot:w}):{allow:!1,reason:`Unknown tool "${t}" — denied by default (not in READ_ONLY_TOOLS; add if truly read-only)`}}function d(e,i){try{if(o(e).isSymbolicLink()){const o=t(e),r=n.isAbsolute(o)?o:n.resolve(n.dirname(e),o);try{return i(r)}catch{return d(r,i)}}}catch{}let r=n.dirname(e);const s=[n.basename(e)];for(;;)try{const e=i(r);return n.join(e,...s.reverse())}catch{const e=n.dirname(r);if(e===r)return null;s.push(n.basename(r)),r=e}}export function reviewGatePreToolDecision({reviewGate:e,toolName:t,toolInput:o}){if(!e)return null;let n=null;try{n=e({toolName:t,input:o})}catch(e){n={allow:!1,reason:`review gate error — denied: ${e?.message||e}`}}return n&&!1===n.allow?{continue:!0,hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:`Blocked (Flow review lane): ${n.reason} You REVIEW the slice — you do not edit it. Read it, run it to reproduce acceptance, then emit your verdict by Writing FLOW_REVIEW.json.`}}:null}function u(e,t){return e===t||e.startsWith(t+n.sep)}

package/flow-review-reflect.mjs

@@ -1,115 +1 @@
-/* ─────────────────────────────────────────────────────────────
-   flow-review-reflect.mjs — the BOUNDED reflection governor for the
-   verifying reviewer lane (heist E1 + P3).
-   Spec: docs/specs/2026-07-02-e1p3-verifying-reviewer.md
-   Parents: Emergent steal E1 (self-test loop) + Cursor steal P3 (Bugbot).
-
-   The existing adversarial reviewer (bridge/flow-review.mjs) runs the slice
-   once and emits a verdict. E1 makes that a bounded, budget-capped SELF-TEST
-   loop: the reviewer may dig across several rounds (re-run, hit edge cases,
-   reproduce the acceptance proof harder) — but it MUST stop at a hard ceiling
-   and hand off to the humans, never loop unbounded. That unbounded self-heal
-   loop is exactly Emergent's most-hated wound (billing a runaway fix-loop back
-   to the user); this governor is the structural guarantee we never have it.
-
-   Two independent stop conditions, both enforced here (not prompted):
-     • ROUND ceiling  — never more than maxRounds hunt rounds (anti-Emergent).
-     • BUDGET ceiling — never spend past the room/lane cap (nexos steal #1 /
-       cost-guard; the review lane SPENDS inference, so it inherits N1).
-
-   Pure + deterministic — the whole loop-control decision in one function so it
-   is unit-testable without a live Flow room (the reviewable seam; the live
-   wiring into flow-review.mjs + bridge.mjs is the held integration slice,
-   same split that shipped S5's reviewGateDecision).
-
-   P3 (pair co-adjudication): when the loop stops, the outcome is not the end —
-   `surfaceToPair` says the verdict/findings must go to the ROOM for the two
-   humans + Pool to challenge, rather than silently auto-driving the gate. A
-   solo Bugbot's verdict is final; ours is a prompt for the pair to argue.
-   ───────────────────────────────────────────────────────────── */
-
-export const REVIEW_DEFAULTS = Object.freeze({
-  maxRounds: 3,          // hard hunt ceiling — bounded, never unbounded (anti-Emergent)
-})
-
-/**
- * Decide whether the reviewer's self-test loop continues or stops, and why.
- *
- * @param {object}  s
- * @param {number}  s.round            1-based current hunt round (1 = first pass)
- * @param {number} [s.maxRounds]       hard ceiling (default REVIEW_DEFAULTS.maxRounds)
- * @param {number} [s.spentTokens]     tokens the review lane has spent so far
- * @param {number|null} [s.budgetCap]  the room/lane token cap (null = uncapped)
- * @param {boolean} s.foundFailure     this round produced a CONCRETE, reproduced failure
- * @param {boolean} [s.exhausted]      the reviewer reports it has nothing left to check
- * @returns {{ stop: boolean, action: 'reject'|'pass'|'surface'|'continue',
- *             surfaceToPair: boolean, reason: string }}
- *   action:
- *     'reject'   — a concrete failure was found; stop, verdict = REJECT
- *     'pass'     — checks exhausted with no failure; stop, verdict = PASS
- *     'surface'  — a ceiling (budget or rounds) was hit inconclusively; stop,
- *                  hand the partial findings to the humans (no guess, no loop)
- *     'continue' — keep hunting (still under both ceilings, not yet concluded)
- *   surfaceToPair — true whenever the loop STOPS (P3: every terminal outcome is
- *                   a prompt for the pair, not an automatic gate action).
- */
-export function reviewReflectionDecision ({
-  round,
-  maxRounds = REVIEW_DEFAULTS.maxRounds,
-  spentTokens = 0,
-  budgetCap = null,
-  foundFailure = false,
-  exhausted = false,
-} = {}) {
-  const r = Number.isFinite(round) ? round : 1
-  const cap = Number.isFinite(maxRounds) && maxRounds > 0 ? maxRounds : REVIEW_DEFAULTS.maxRounds
-
-  // 1. A concrete, reproduced failure ends the hunt immediately — default-to-
-  //    reject is the whole point; no value in more rounds once it's broken.
-  if (foundFailure) {
-    return { stop: true, action: 'reject', surfaceToPair: true,
-      reason: 'concrete failure reproduced — verdict REJECT' }
-  }
-
-  // 2. BUDGET ceiling (nexos #1 / cost-guard). Fail-closed: the moment spend
-  //    reaches the cap, STOP and hand off — never spend the next unit. Checked
-  //    before the round ceiling because money is the harder limit.
-  if (budgetCap != null && Number.isFinite(budgetCap) && spentTokens >= budgetCap) {
-    return { stop: true, action: 'surface', surfaceToPair: true,
-      reason: `review budget cap reached (${spentTokens}/${budgetCap} tokens) — surfacing partial findings to the pair` }
-  }
-
-  // 3. Reviewer says it has checked everything and found nothing — verdict PASS.
-  if (exhausted) {
-    return { stop: true, action: 'pass', surfaceToPair: true,
-      reason: 'checks exhausted, no failure reproduced — verdict PASS' }
-  }
-
-  // 4. ROUND ceiling (anti-Emergent). Reached the last allowed round without a
-  //    conclusion → surface to the humans rather than guess or loop forever.
-  if (r >= cap) {
-    return { stop: true, action: 'surface', surfaceToPair: true,
-      reason: `reached the ${cap}-round hunt ceiling without a conclusion — surfacing to the pair (not looping)` }
-  }
-
-  // 5. Under both ceilings, not yet concluded → dig another round.
-  return { stop: false, action: 'continue', surfaceToPair: false,
-    reason: `round ${r}/${cap}, under budget — continue hunting` }
-}
-
-/**
- * Format a stopped review outcome as the room-facing co-adjudication prompt
- * (P3). Not the gate action itself — a message that invites the two humans +
- * Pool to challenge the reviewer before the verdict is treated as final.
- */
-export function pairAdjudicationPrompt ({ action, reason, findings = [], taskKey = '' } = {}) {
-  const head = {
-    reject:  `The reviewer REJECTED ${taskKey || 'this slice'}.`,
-    pass:    `The reviewer PASSED ${taskKey || 'this slice'}.`,
-    surface: `The reviewer could not conclude on ${taskKey || 'this slice'}.`,
-  }[action] || `Review outcome for ${taskKey || 'this slice'}.`
-  const body = findings.length
-    ? '\n' + findings.map((f) => `  • ${f}`).join('\n')
-    : (reason ? `\n  ${reason}` : '')
-  return `${head}${body}\n\nYou two decide — do you agree? Challenge it, or accept.`
-}
+export const REVIEW_DEFAULTS=Object.freeze({maxRounds:3});export function reviewReflectionDecision({round:e,maxRounds:n=REVIEW_DEFAULTS.maxRounds,spentTokens:o=0,budgetCap:i=null,foundFailure:r=!1,exhausted:t=!1}={}){const a=Number.isFinite(e)?e:1,c=Number.isFinite(n)&&n>0?n:REVIEW_DEFAULTS.maxRounds;return r?{stop:!0,action:"reject",surfaceToPair:!0,reason:"concrete failure reproduced — verdict REJECT"}:null!=i&&Number.isFinite(i)&&o>=i?{stop:!0,action:"surface",surfaceToPair:!0,reason:`review budget cap reached (${o}/${i} tokens) — surfacing partial findings to the pair`}:t?{stop:!0,action:"pass",surfaceToPair:!0,reason:"checks exhausted, no failure reproduced — verdict PASS"}:a>=c?{stop:!0,action:"surface",surfaceToPair:!0,reason:`reached the ${c}-round hunt ceiling without a conclusion — surfacing to the pair (not looping)`}:{stop:!1,action:"continue",surfaceToPair:!1,reason:`round ${a}/${c}, under budget — continue hunting`}}export function pairAdjudicationPrompt({action:e,reason:n,findings:o=[],taskKey:i=""}={}){return`${{reject:`The reviewer REJECTED ${i||"this slice"}.`,pass:`The reviewer PASSED ${i||"this slice"}.`,surface:`The reviewer could not conclude on ${i||"this slice"}.`}[e]||`Review outcome for ${i||"this slice"}.`}${o.length?"\n"+o.map(e=>`  • ${e}`).join("\n"):n?`\n  ${n}`:""}\n\nYou two decide — do you agree? Challenge it, or accept.`}