Troubleshooting

omit wiki at ac68124 · checked against v0.9.0Updated for v0.9.0: the "new comment on every push" entry.

What the gates, sentinels and the Action say, and what to do about it.

In the verdict

receipts: 1/5 verified · 4 unverifiable ⚠
The unverifiable ones need their run snippet executed and execution is off. In the Action that is the default (exec: false); locally it is OMIT_NO_EXEC=1. Run npx @sriinnu/omit verify yourself to settle them, or set with: { exec: true } on a repo whose PRs you trust. A receipt written before 0.4.0 (a prose receipt string, or a tried entry citing a file) also reads as unverifiable.

receipts: … FAILED ⛔
The tree refutes a claim. npx @sriinnu/omit verify names the line and says why. A refuted new-dep receipt means one of the omissions it says it tried actually holds, so the dependency is not needed.

lint: eslint not run (…) ⚠
The linter is configured but could not run: no node_modules, nothing on PATH, or exec: false in CI. It is reported as not run, never as a pass.

new deps: 0 (1 dependency-shaped file not parsed)
A setup.py, build.gradle, Package.swift or *.csproj changed. omit does not parse those, so read that file's diff yourself.

hooks: core.hooksPath=… — the pre-commit gate installed here is NOT the hook git runs ⛔
Git is configured to run hooks from another directory, so the gate in .git/hooks is shadowed. Re-run npx @sriinnu/omit hook install: it writes to the directory git actually runs hooks from.

The file count is one too high (Action, v0.4.1 and earlier)
Known bug: the verdict file counted itself. Line counts are right. Fixed in v0.5.0: pin sriinnu/omit@v0.5.0 or later.

From `omit audit`

<ref> is not a revision this repo can resolve
The base does not exist here: a typo, a shallow clone, or rewritten history. omit refuses to measure a change against nothing rather than report an empty diff as a pass. Fetch the base, or check out with fetch-depth: 0.

--base a..b: expected a single revision
--base takes one revision, not a range.

From the hooks

Not sure which hooks a session actually loads
omit doctor reads the Codex and Claude Code hook files a session would pick up and reports missing scripts, duplicate registrations and bad matchers. It never runs a hook it finds. (omit 0.6.0 and later.)

The session will not end: the working tree changed but there is no readable .omit/final-draft.md
That is the Final Draft gate. Do the deletion pass, run npx @sriinnu/omit audit, and write .omit/final-draft.md with the counts it prints, in the shape the gate parses: files touched: <n>, lines +<added> −<removed>, new dependencies: <n>. Untracked files count, and git diff --stat cannot see them, so take the numbers from omit audit.

The gate says the numbers in .omit/final-draft.md are wrong
The report is read and cross-checked against the real diff, and a draft older than the newest edit describes a tree that no longer exists. Re-run omit audit and update the counts.

A sentinel blocked a command you have reviewed
Append a trailing comment with a real reason: # omit-allow: <reason>. The bare token, a token inside a string, and a marker with no reason are ignored. Secrets have no override.

A new dependency was objected to
It needs a verified new-dep receipt in .omit/receipts.jsonl naming the omissions that were tried. See README: Receipts.

You are a human and want it out of the way
OMIT_OFF=1.

From codemode

omit codemode needs its sandbox, which is not installed
The sandbox is an optional peer. Run npm install -g @earendil-works/pi-codemode next to omit. It needs Node 22.19 or newer. A Homebrew install already includes it.

omit codemode prints the usage line
That omit predates codemode (v0.4.1 or earlier). Upgrade to 0.5.0 or later: npm install -g @sriinnu/omit.

omit: output withheld, it carries aws-access-key (output line 3)
The script returned something that matches a secret rule, so the whole result was held back. Filter it out in the script and return only what you need.

[omit: 30008 characters cut here. …]
The result was past 20,000 characters and lost its middle. Count, aggregate or filter in the script.

<path> is outside the workspace
Paths are relative to the directory the server started in and cannot leave it: no .., no absolute path, no symlink pointing out.

fatal: not a git repository from files or grep
Those two read the tree through git. read still works there.

Script error (timeout)
A script has 60 seconds.

omit codemode run exits 1
The script failed or its result was withheld. What it printed says which.

The sandbox disappears from a checkout of omit
In the repo, npm install --no-save @earendil-works/pi-codemode toggles: a second run removes it. Run plain npm install there instead; the sandbox is a dev dependency.

From the Action

Checkout fails on a private repo
The workflow names pull-requests: write and nothing else, which drops contents to none. Use permissions: { contents: read, pull-requests: write }.

The comment step fails on a pull request from a fork
A fork's token is read-only. Add the if: guard from GitHub Action.