@sriinnu/omit 0.3.0 → 0.4.0

package/hooks/command-sentinel.mjs

@@ -7,6 +7,21 @@ import { assessCommand } from '../lib/danger.mjs'
 
 if (process.env.OMIT_OFF === '1') process.exit(0)
 
+// Claude Code's hook contract: exit 2 blocks the tool call, and every other
+// non-zero code is a NON-BLOCKING error — the model sees it and can carry on.
+// So the only safe exit for a hook that did not finish its job is 2. A crash at
+// exit 1 is this hook silently not running, which is the one outcome it exists
+// to prevent; a non-string `command` used to throw out of assessCommand and let
+// the command through.
+const block = (message) => {
+  console.error(message)
+  process.exit(2)
+}
+
+// The payload comes from the harness, not the agent, so a payload we cannot even
+// parse is not evidence about anything the agent did — and harnesses do not agree
+// on shape (Codex's apply_patch sends different fields). Skip, do not block the
+// session on it.
 let data
 try {
   data = JSON.parse(readFileSync(0, 'utf8'))
@@ -14,16 +29,29 @@ try {
   process.exit(0)
 }
 
-const command = data.tool_input?.command
-if (!command) process.exit(0)
+try {
+  const command = data.tool_input?.command
+  if (command === undefined || command === null || command === '') process.exit(0) // not a shell tool call
+  if (typeof command !== 'string') {
+    block(
+      'omit blocks this command: its text was not a string, so nothing about it could be assessed.\n' +
+        'Send the command as a string, or set OMIT_OFF=1 to run without the sentinel.'
+    )
+  }
 
-const findings = assessCommand(command)
-if (findings.length === 0) process.exit(0)
+  const findings = assessCommand(command)
+  if (findings.length === 0) process.exit(0)
 
-console.error(
-  'omit blocks this command: the machine is load-bearing.\n' +
-    findings.map((f) => `  [${f.rule}] ${f.reason}`).join('\n') +
-    '\nUse a narrower target inside the workspace, guard variables with ${VAR:?}, ' +
-    'or, only after genuine review with the user, append: # omit-allow: <reason>'
-)
-process.exit(2)
+  console.error(
+    'omit blocks this command: the machine is load-bearing.\n' +
+      findings.map((f) => `  [${f.rule}] ${f.reason}`).join('\n') +
+      '\nUse a narrower target inside the workspace, guard variables with ${VAR:?}, ' +
+      'or, only after genuine review with the user, append: # omit-allow: <reason>'
+  )
+  process.exit(2)
+} catch (e) {
+  block(
+    `omit could not assess this command (${e?.message ?? e}).\n` +
+      'Blocking the command rather than waving it through: a check that did not run is not a check that passed.'
+  )
+}

package/hooks/dep-sentinel.mjs

@@ -1,45 +1,199 @@
 #!/usr/bin/env node
-// PostToolUse hook: raises a blocking objection when a new dependency lands
-// in a manifest without a receipt in .omit/receipts.jsonl.
-import { readFileSync, existsSync } from 'node:fs'
-import { execSync } from 'node:child_process'
-import { basename, join } from 'node:path'
-import { isManifest, addedDeps } from '../lib/deps.mjs'
+// PostToolUse hook: raises a blocking objection when a new dependency lands in
+// a manifest without a receipt in .omit/receipts.jsonl.
+//
+// Fires on file edits (Edit|Write|MultiEdit|NotebookEdit) and on Bash: a
+// manifest is also rewritten by `npm pkg set`, a redirect, `tee` or `sed -i`,
+// and the same change through a different tool is the same change.
+import { readFileSync, realpathSync } from 'node:fs'
+import { basename, resolve } from 'node:path'
+import { isManifest, addedDeps, MANIFESTS } from '../lib/deps.mjs'
+import { probe, fileAtRevision, repoRelPath } from '../lib/git.mjs'
+import { execDisabled, flagOn } from '../lib/exec.mjs'
+import { newDepCitations } from '../lib/receipts.mjs'
 
 if (process.env.OMIT_OFF === '1') process.exit(0)
 
+// Exit 2 blocks the tool call; any other non-zero code is a non-blocking error
+// the model can shrug off. This hook's whole value is the objection, so nothing
+// here is allowed to end in an uncaught throw.
+const block = (message) => {
+  console.error(message)
+  process.exit(2)
+}
+
+// The ledger is executable in the Makefile sense, and `.omit/receipts.jsonl` is
+// a file the agent under check can Write. Confirmed: a Write of the manifest plus
+// a Write of the ledger ran the receipt's `run` argv as the developer from this
+// PostToolUse hook — no Bash call, no permission prompt, exit 0. So the hook
+// declines to execute ledger snippets by default and the operator opts in per
+// project. OMIT_NO_EXEC is not set here but in the environment of this process,
+// which is the same flag lib/receipts.mjs `execDisabled()` reads; the off-values
+// are kept identical on purpose ( '', '0', 'false' mean "the flag is off" ), so
+// OMIT_HOOK_EXEC=0 really does mean no execution.
+const mayExec = flagOn(process.env.OMIT_HOOK_EXEC)
+if (!mayExec) process.env.OMIT_NO_EXEC = '1'
+
+// repoRoot() answers null both for "not a repository" and for "git could not
+// answer", and those want opposite exits: no repository means there is no HEAD
+// to compare against, while a git that cannot run at all (missing binary, dubious
+// ownership, unreadable object store) means the check never happened. git's own
+// message is the only thing that separates the two, so match on it and fail
+// closed on everything else.
+function repoRootOrNull(cwd) {
+  const r = probe(cwd, ['rev-parse', '--show-toplevel'])
+  if (r.ok) return r.out.trim()
+  if (/not a git repository|must be run in a work tree/i.test(String(r.reason))) return null
+  throw new Error(`git could not report the repository root (${r.reason})`)
+}
+
+// The manifests a shell command plausibly rewrote, decided by pure string work:
+// this runs on every Bash call, so nothing may spawn a process until a manifest
+// is actually in play. Two signals — a package manager whose subcommand writes a
+// manifest, and a watched manifest filename anywhere in the command (which is
+// what `cat > package.json`, `tee`, `sed -i` and `cp` look like).
+const MANAGER_WRITES = [
+  [/\b(?:npm|pnpm|yarn|bun)\s+(?:i|install|add|remove|rm|uninstall|upgrade|update|pkg|link)\b/, 'package.json'],
+  [/\b(?:poetry|uv|pipenv)\s+(?:add|remove|install)\b/, 'pyproject.toml'],
+  [/\bcargo\s+(?:add|remove|install)\b/, 'Cargo.toml'],
+  [/\bgo\s+(?:get|mod\s+(?:tidy|edit))\b/, 'go.mod'],
+  [/\b(?:bundle|bundler)\s+(?:add|install|update)\b/, 'Gemfile'],
+  [/\bcomposer\s+(?:require|remove|update|install)\b/, 'composer.json'],
+]
+
+function manifestsTouched(command) {
+  const out = new Set()
+  for (const [re, name] of MANAGER_WRITES) if (re.test(command)) out.add(name)
+  for (const name of MANIFESTS) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    const m = command.match(new RegExp(`(?:^|[\\s'"=<>|(])([\\w./\\\\-]*${escaped})`, 'i'))
+    if (m) out.add(m[1])
+  }
+  return [...out]
+}
+
+// repoRelPath is lexical, and the path the harness sends and the root git
+// reports do not always agree on symlinks: on macOS `/tmp` and `/var` are links
+// into `/private`, and git answers with the resolved root. A mismatch reads as
+// "outside the repo" — which exits 0, a manifest edit silently unaudited. So
+// resolve the file and ask again before giving up on it.
+function relInRoot(root, abs) {
+  const lexical = repoRelPath(root, abs)
+  if (lexical !== null) return lexical
+  try {
+    return repoRelPath(root, realpathSync(abs))
+  } catch {
+    return null // no such file: nothing to compare, nothing added
+  }
+}
+
+// A manifest we cannot read as text declares nothing, so nothing was added to it.
+// Deleting or replacing it with a directory is not a dependency landing.
+function readManifest(abs) {
+  try {
+    return readFileSync(abs, 'utf8')
+  } catch (e) {
+    if (e.code === 'ENOENT' || e.code === 'EISDIR') return null
+    throw e
+  }
+}
+
 let data
 try {
   data = JSON.parse(readFileSync(0, 'utf8'))
 } catch {
-  process.exit(0)
+  process.exit(0) // harness-authored payload we cannot read: not evidence about a file
 }
 
-const file = data.tool_input?.file_path
-if (!file || !isManifest(file)) process.exit(0)
-
-const cwd = data.cwd ?? process.cwd()
-let diff = ''
 try {
-  diff = execSync(`git diff HEAD -- "${file}"`, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
-} catch {
-  process.exit(0) // not a git repo: nothing to compare against
-}
+  const ti = data.tool_input ?? {}
+  for (const f of ['file_path', 'notebook_path', 'command']) {
+    if (ti[f] !== undefined && typeof ti[f] !== 'string') {
+      block(
+        `omit blocks this edit: the hook was handed a \`${f}\` that is not a path or a command, so no manifest behind it could be checked.\n` +
+          'Send the tool input as a string, or set OMIT_OFF=1 to run without the sentinel.'
+      )
+    }
+  }
+
+  const cwd = data.cwd ?? process.cwd()
+  const targets =
+    typeof ti.file_path === 'string' ? (isManifest(ti.file_path) ? [ti.file_path] : []) : typeof ti.command === 'string' ? manifestsTouched(ti.command) : []
+  if (targets.length === 0) process.exit(0) // an edit that cannot be a manifest edit
 
-const deps = addedDeps(basename(file), diff)
-if (deps.length === 0) process.exit(0)
+  const root = repoRootOrNull(cwd)
+  if (root === null) process.exit(0) // not a repository: no history to compare against
 
-let receipts = ''
-const ledger = join(cwd, '.omit', 'receipts.jsonl')
-if (existsSync(ledger)) receipts = readFileSync(ledger, 'utf8')
+  const citations = newDepCitations(root)
+  const uncited = new Map()
+  for (const target of targets) {
+    const abs = resolve(cwd, target)
+    const rel = relInRoot(root, abs)
+    if (rel === null) continue // outside the repo: not ours to audit
+    const after = readManifest(abs)
+    if (after === null) continue
+    const before = fileAtRevision(root, 'HEAD', rel)
+    // `{failed:true}` is not an empty file. Rendering it as one would turn every
+    // dependency in the manifest into a "new" one, or hide the added one
+    // entirely: either way the hook would be reporting on a comparison it never
+    // made. Throw, and let the wrapper object.
+    if (before.failed) throw new Error(`git could not read ${rel} at HEAD (${before.reason})`)
 
-const uncited = deps.filter((d) => !receipts.includes(d))
-if (uncited.length === 0) process.exit(0)
+    // Compare declared dependency SETS across the two revisions rather than
+    // parsing the diff: a brand-new manifest has no earlier revision, so
+    // everything in it is new, and a minified manifest declares the same set as
+    // a pretty-printed one.
+    for (const dep of addedDeps(basename(rel), before.present ? before.text : '', after)) {
+      const status = citations.get(dep)?.status
+      // Only a VERIFIED new-dep receipt cites a dependency — a ledger line that
+      // merely names it is an assertion, which is what this hook exists to stop
+      // accepting.
+      if (status !== 'verified' && !uncited.has(dep)) uncited.set(dep, status ?? null)
+    }
+  }
+  if (uncited.size === 0) process.exit(0)
 
-console.error(
-  `omit objects: new dependenc${uncited.length > 1 ? 'ies' : 'y'} with no receipt: ${uncited.join(', ')}.\n` +
-    `Omissions 2-5 come first: show the codebase, stdlib, platform, and installed deps cannot cover this.\n` +
-    `If they truly cannot, append the citation to .omit/receipts.jsonl ` +
-    `({"claim":"new dep ${uncited[0]} required","receipt":"<what you verified>","rung":7}) and re-apply. Otherwise revert the manifest change.`
-)
-process.exit(2)
+  const deps = [...uncited]
+  const why = deps
+    .map(([dep, status]) =>
+      status === 'failed'
+        ? `  ${dep}: its receipt was refuted by its own check`
+        : status === 'unverifiable'
+          ? `  ${dep}: its receipt could not be verified`
+          : `  ${dep}: no receipt names it`
+    )
+    .join('\n')
+
+  const decl = deps.length > 1 ? 'ies' : 'y'
+  console.error(
+    `omit objects: new dependenc${decl} without a verified receipt: ${deps.map(([d]) => d).join(', ')}.\n` +
+      why +
+      '\n' +
+      // Honest when it declines to execute: a receipt whose only evidence is a
+      // `run` snippet was not checked, and saying it is unverified is true where
+      // "verified" or silence would not be. It names which switch did the
+      // declining, so the reader is not told to set a flag they already set.
+      (execDisabled()
+        ? 'Ledger snippets were NOT executed here: ' +
+          (mayExec
+            ? 'OMIT_NO_EXEC is set in this environment.\n'
+            : 'a hook does not run `run` argv by default, because a Write of .omit/receipts.jsonl would\n' +
+              'otherwise execute as you, with no approval prompt. Set OMIT_HOOK_EXEC=1 to let this hook run one.\n') +
+          'A receipt whose evidence is a `run` snippet is unverified here, not refuted — check it with `omit verify`.\n'
+        : '') +
+      `Omissions 2-5 come first: show the codebase, stdlib, platform, and installed deps cannot cover this.\n` +
+      `If they truly cannot, append one line to .omit/receipts.jsonl — the entries under "tried" are re-checked, and must NOT hold:\n` +
+      // The printed line has to be a receipt that verifies. `absent` names a
+      // symbol the checker searches the whole tracked tree for, so replace it
+      // with the one you actually looked for; the claim survives only if that
+      // search comes back empty.
+      `  {"claim":"new-dep","rung":7,"dep":"${deps[0][0]}","tried":[{"rung":2,"absent":"<symbol you searched for>"}]}\n` +
+      `\`omit verify\` checks it before you commit. Otherwise revert the manifest change.`
+  )
+  process.exit(2)
+} catch (e) {
+  block(
+    `omit could not complete the new-dependency check (${e?.message ?? e}).\n` +
+      'Blocking the edit rather than accepting a manifest change nothing audited: a check that did not run is not a check that passed.'
+  )
+}

package/hooks/final-draft-gate.mjs

@@ -1,52 +1,246 @@
 #!/usr/bin/env node
 // Stop hook: the turn may not end with an edited working tree and no Final Draft.
 // The deletion pass is a gate, not a suggestion.
-import { readFileSync, statSync, existsSync } from 'node:fs'
-import { execSync } from 'node:child_process'
-import { join } from 'node:path'
+//
+// The draft has to be a REPORT, not a file. Existence and mtime alone let a
+// 0-byte .omit/final-draft.md satisfy a gate whose promise is that a session
+// cannot end with an edited tree and no net report, so the counts the skill asks
+// for — files touched, lines added/removed, new dependencies — are read out of
+// the draft and cross-checked against the tree.
+import { readFileSync, lstatSync, statSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { probe, git, fileAtRevision } from '../lib/git.mjs'
+import { isManifest, addedDeps } from '../lib/deps.mjs'
 
 if (process.env.OMIT_OFF === '1') process.exit(0)
 
+// Exit 2 blocks the stop (the model gets another turn); anything else non-zero is
+// a non-blocking error and the session ends on an unchecked report.
+const block = (message) => {
+  console.error(message)
+  process.exit(2)
+}
+
 let data = {}
 try {
   data = JSON.parse(readFileSync(0, 'utf8'))
 } catch {}
 if (data.stop_hook_active) process.exit(0) // never loop the gate
 
-const cwd = data.cwd ?? process.cwd()
-let changed = []
-try {
-  changed = execSync('git status --porcelain', { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
-    .split('\n')
-    .filter(Boolean)
-    .map((l) => l.slice(3).replace(/^.*-> /, ''))
-    .filter((p) => !p.startsWith('.omit/'))
-} catch {
-  process.exit(0)
-}
-// omitted: distinguishing this session's edits from pre-existing dirt: git has no
-// session concept; set OMIT_OFF=1 in dirty-tree workflows until a marker file lands.
-if (changed.length === 0) process.exit(0)
-
-const draft = join(cwd, '.omit', 'final-draft.md')
-if (existsSync(draft)) {
-  const draftTime = statSync(draft).mtimeMs
-  const newestEdit = Math.max(
-    ...changed.map((p) => {
-      try {
-        return statSync(join(cwd, p)).mtimeMs
-      } catch {
-        return 0 // deleted file: cannot be newer than the draft
-      }
-    })
+const DRAFT_MAX = 1 << 20
+
+// repoRoot() answers null for "not a repository" and for "git could not answer",
+// which want opposite exits — see dep-sentinel for the full note.
+function repoRootOrNull(cwd) {
+  const r = probe(cwd, ['rev-parse', '--show-toplevel'])
+  if (r.ok) return r.out.trim()
+  if (/not a git repository|must be run in a work tree/i.test(String(r.reason))) return null
+  throw new Error(`git could not report the repository root (${r.reason})`)
+}
+
+// Text, or null when there is nothing to count (binary, unreadable, gone).
+function readText(path) {
+  try {
+    const text = readFileSync(path, 'utf8')
+    return text.includes('\0') ? null : text
+  } catch {
+    return null
+  }
+}
+
+// omit counts a file's lines the way an editor does: a trailing newline ends the
+// last line rather than starting an empty one.
+const lineCount = (text) => {
+  const lines = text.split('\n')
+  if (lines[lines.length - 1] === '') lines.pop()
+  return lines.length
+}
+
+// Everything `omit audit` counts, per file: tracked changes (staged or not —
+// `git diff HEAD` sees both) plus untracked files, which `git diff` cannot see
+// and which are most of a working tree mid-session. Binary and unreadable files
+// carry no line counts and are left out, which is the same choice audit makes —
+// that is what lets a draft pasting audit's verdict match unchanged.
+function changeSet(root) {
+  const rows = []
+  let binaries = 0
+  for (const line of git(root, ['diff', 'HEAD', '--numstat']).split('\n').filter(Boolean)) {
+    const [a, d, rel] = line.split('\t')
+    if (a === '-') {
+      binaries++
+      continue
+    }
+    rows.push({ rel, added: +a, deleted: +d, untracked: false })
+  }
+  for (const rel of git(root, ['ls-files', '--others', '--exclude-standard']).split('\n').filter(Boolean)) {
+    // omit's own bookkeeping is not the change, and audit skips it the same way —
+    // that is what lets a draft pasting audit's verdict match this count.
+    // omitted: the same for a tracked .omit/ change, which audit does count; the
+    // caller excludes it from `changed` and keeps this set for that comparison.
+    if (rel.startsWith('.omit/')) continue
+    const text = readText(join(root, rel))
+    if (text === null) continue
+    rows.push({ rel, added: lineCount(text), deleted: 0, untracked: true })
+  }
+  return { rows, binaries }
+}
+
+// The counts the report is checked against. `files` is the size of the set, so
+// every call here passes the set it wants counted.
+function counts(root, rows) {
+  let added = 0
+  let deleted = 0
+  let deps = 0
+  for (const r of rows) {
+    added += r.added
+    deleted += r.deleted
+    if (!isManifest(r.rel)) continue
+    const after = readText(join(root, r.rel)) ?? '' // deleted or unreadable: declares nothing
+    const before = fileAtRevision(root, 'HEAD', r.rel)
+    // `{failed:true}` is not an empty manifest: reading it as one would turn
+    // every dependency it declares into a "new" one.
+    if (before.failed) throw new Error(`git could not read ${r.rel} at HEAD (${before.reason}) — the new-dependency count would be a guess`)
+    deps += addedDeps(basename(r.rel), before.present ? before.text : '', after).length
+  }
+  return { files: rows.length, added, deleted, deps }
+}
+
+// The draft is untrusted input like the ledger: a symlink to /dev/zero (or any
+// pipe) would hang the Stop hook forever. lstat, not stat, so nothing is
+// followed, and the size is capped rather than read into memory.
+function readDraft(path) {
+  const st = lstatSync(path)
+  if (!st.isFile()) throw new Error(`${path} is not a regular file`)
+  if (st.size > DRAFT_MAX) throw new Error(`${path} is ${st.size} bytes, over the ${DRAFT_MAX}-byte cap`)
+  return { text: readFileSync(path, 'utf8'), mtimeMs: st.mtimeMs }
+}
+
+// Form is read leniently — audit's own verdict line parses, and so does prose like
+// "files touched: 2" — content strictly: all three counts must be stated, because
+// a report that cannot be checked is not a net report.
+const firstInt = (text, patterns) => {
+  for (const re of patterns) {
+    const m = text.match(re)
+    if (m) return +m[1]
+  }
+  return null
+}
+
+const firstPair = (text, patterns) => {
+  for (const re of patterns) {
+    const m = text.match(re)
+    if (m) return [+m[1], +m[2]]
+  }
+  return null
+}
+
+function parseReport(text) {
+  const files = firstInt(text, [
+    /across\s+(\d+)\s+files?\b/i, // audit's line: "net: +3 −0 lines across 1 file"
+    /\bfiles?\s+(?:touched|changed|edited)\s*[:=]\s*\**(\d+)/i,
+    /\bfiles?\s*[:=]\s*\**(\d+)/i,
+    /(\d+)\s+files?\b/i,
+  ])
+  const lines = firstPair(text, [
+    /net\s*[:=]?\s*\+\s*(\d+)\s*[−–-]\s*(\d+)/i, // audit's line
+    /\+\s*(\d+)\s*[−–/-]\s*(\d+)/, // "+12 −3", "+12/-3"
+    /\blines?\b[^\n]{0,32}?(\d+)\s*[−–/-]\s*(\d+)/i,
+  ])
+  const none = /\bno\s+new\s+(?:deps?|dependencies)\b|\bnew\s+(?:deps?|dependencies)\s*[:=]\s*\**\s*(?:none|zero|nil|n\/a)\b/i
+  const deps = none.test(text)
+    ? 0
+    : firstInt(text, [/\bnew\s+(?:deps?|dependencies)\s*[:=]\s*\**(\d+)/i, /\bnew\s+dependenc\w*\s*[:=]\s*\**(\d+)/i, /\bdependenc\w*\s+(?:added|introduced)\s*[:=]?\s*(\d+)/i])
+  return { files, lines, deps }
+}
+
+function main() {
+  const cwd = data.cwd ?? process.cwd()
+  const root = repoRootOrNull(cwd)
+  if (root === null) process.exit(0) // not a repository: there is no diff to gate
+
+  const { rows, binaries } = changeSet(root)
+  const changed = rows.filter((r) => !r.rel.startsWith('.omit/'))
+  // omitted: distinguishing this session's edits from pre-existing dirt: git has no
+  // session concept; set OMIT_OFF=1 in dirty-tree workflows until a marker file lands.
+  if (changed.length === 0) process.exit(0)
+
+  const draftPath = join(root, '.omit', 'final-draft.md')
+  let draft
+  try {
+    draft = readDraft(draftPath)
+  } catch (e) {
+    block(
+      `omit: the working tree changed but there is no readable .omit/final-draft.md${e.code === 'ENOENT' ? '' : ` (${e.message})`}.\n` +
+        'Working code is a first draft. Edit your own diff once (dead branches, unused params/imports, ' +
+        'speculative options, restating comments, single-caller indirection), then write the net report to ' +
+        '.omit/final-draft.md: files touched, lines +/-, new dependencies, footnotes recorded. Then finish.'
+    )
+  }
+
+  // A draft older than the newest edit describes a tree that no longer exists.
+  const newestEdit = Math.max(...changed.map((r) => statSync(join(root, r.rel), { throwIfNoEntry: false })?.mtimeMs ?? 0))
+  if (draft.mtimeMs < newestEdit) {
+    block(
+      'omit: the Final Draft is older than the newest edit — it reports a tree that no longer exists.\n' +
+        'Re-run `omit audit`, update the counts in .omit/final-draft.md, then finish.'
+    )
+  }
+
+  const actual = counts(root, changed)
+  const report = parseReport(draft.text)
+  const missing = []
+  if (report.files === null) missing.push('"files touched: <n>"')
+  if (report.lines === null) missing.push('"lines +<added> −<removed>"')
+  if (report.deps === null) missing.push('"new dependencies: <n>"')
+  if (missing.length) {
+    block(
+      `omit: .omit/final-draft.md does not state ${missing.join(', ')}.\n` +
+        `The gate is on the report, not on the file existing. This tree right now: ${actual.files} file(s), ` +
+        `+${actual.added} −${actual.deleted} lines, ${actual.deps} new dependenc${actual.deps === 1 ? 'y' : 'ies'}.\n` +
+        'Those are the numbers `omit audit` prints. Write them down, say what you cut, then finish.'
+    )
+  }
+
+  const wrong = []
+  if (report.files !== actual.files) wrong.push(`  files touched: draft says ${report.files}, the tree has ${actual.files}`)
+  if (report.lines[0] !== actual.added || report.lines[1] !== actual.deleted) {
+    wrong.push(`  lines: draft says +${report.lines[0]} −${report.lines[1]}, the tree has +${actual.added} −${actual.deleted}`)
+  }
+  if (report.deps !== actual.deps) wrong.push(`  new dependencies: draft says ${report.deps}, the tree has ${actual.deps}`)
+  if (wrong.length === 0) {
+    if (binaries > 0) console.error(`omit: note — ${binaries} changed file(s) are binary; no line counts describe them.`)
+    process.exit(0)
+  }
+
+  // One honest mismatch passes with a note. `omit audit` counts omit's own ledger
+  // files when they are tracked, and this gate counts the change itself: a draft
+  // that pasted audit's verdict is reporting the tree accurately, and the only
+  // thing it includes that the gate excludes is omit's bookkeeping. Nothing a
+  // developer did is hidden by letting that through — which is not true of any
+  // other mismatch, where the draft is simply stating a number the tree
+  // contradicts.
+  const audited = counts(root, rows)
+  if (report.files === audited.files && report.lines[0] === audited.added && report.lines[1] === audited.deleted && report.deps === audited.deps) {
+    console.error(
+      "omit: note — the Final Draft matches `omit audit`'s counts, which include omit's own tracked files under .omit/.\n" +
+        'The gate counts the change itself; the difference is omit\'s bookkeeping, not your work.'
+    )
+    process.exit(0)
+  }
+
+  block(
+    `omit: the Final Draft reports numbers the tree contradicts:\n${wrong.join('\n')}\n` +
+      `This tree right now: ${actual.files} file(s), +${actual.added} −${actual.deleted} lines, ${actual.deps} new dependenc${actual.deps === 1 ? 'y' : 'ies'}.\n` +
+      'Fix the numbers in .omit/final-draft.md (untracked files count — `git diff --stat` cannot see them), then finish.'
   )
-  if (draftTime >= newestEdit) process.exit(0)
 }
 
-console.error(
-  'omit: the working tree changed but there is no current Final Draft.\n' +
-    'Working code is a first draft. Edit your own diff once (dead branches, unused params/imports, ' +
-    'speculative options, restating comments, single-caller indirection), then write the net report to ' +
-    '.omit/final-draft.md: files touched, lines +/-, new dependencies, footnotes recorded. Then finish.'
-)
-process.exit(2)
+try {
+  main()
+} catch (e) {
+  block(
+    `omit could not complete the Final Draft check (${e?.message ?? e}).\n` +
+      'Blocking the stop rather than ending the session on a report nothing was compared against. ' +
+      'Fix the error, or set OMIT_OFF=1 if this is not a working session to gate.'
+  )
+}