After every distill run, the wrapper writes a pair of sidecar files recording what happened. The outcome sidecar atDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/cad0p/pi-napkin/llms.txt
Use this file to discover all available pages before exploring further.
<vault>/.napkin/distill/errors/<ISO-timestamp>-<pid>-<branch-hash>.outcome is the primary signal: its first line is a machine-readable class string that drives the UI severity displayed in the status bar and notification. Subsequent lines, when present, contain a human-readable recovery hint. A companion .log file holds wrapper diagnostics and agent stderr for deeper investigation.
Outcome Classes
| Class | When | UI severity |
|---|---|---|
merged-content | Agent produced content, integrated, squashed, and pushed to origin (or origin not configured). | info ✓ |
merged-local | Agent integrated and squashed, but origin is configured and local <default> is ahead of origin/<default> — push didn’t land. | warning ⚠ |
no-content | Agent produced nothing (genuine no-op — selective filter passed nothing worth capturing), or committed to the distill branch but skipped the squash step (default branch never moved). | warning ⚠ |
failed:<reason> | Wrapper validation rejected the agent’s output, or the agent didn’t complete successfully. | error ✗ |
failed:<reason> Codes
| Reason | Meaning | Recovery |
|---|---|---|
markers-after-agent-exit | Conflict markers (<<<<<<< / ======= / >>>>>>>) found in tracked *.md files after the agent exited — markers that were not present when the distill started. The agent left an unfinished merge. | The squash commit may already be on <default>. Inspect with git show HEAD, then git revert HEAD --no-edit to undo cleanly. The dangling distill branch is recoverable from git reflog for approximately two weeks. |
pre-existing-markers | Markers were present in the same files before the agent ran. The validator refuses to misattribute them to the distill. | Resolve the pre-existing conflict markers in the vault yourself, then re-run distill. |
internal-validator-error | The wrapper’s post-distill marker validator could not run (e.g. mktemp failed because of a full disk or locked-down TMPDIR), so the vault was never scanned after the agent exited. | Inspect the vault manually for unresolved <<<<<<< / ======= / >>>>>>> markers before relying on the squash commit. If clean, the squash is keepable; otherwise run git -C <vault> revert HEAD --no-edit. Distill content is recoverable from git reflog for approximately 90 days. |
head-not-on-default | Vault HEAD is not on the default branch after the agent exited (detached HEAD or a different branch). | Manually run git checkout <default> after confirming no other distill is in flight. The distill branch lives in git reflog if you want to recover its content. |
divergent-history | After the agent’s push, origin/<default> and local <default> diverged in a way that doesn’t look like a fast-forward — an unexpected concurrent push or a defensive force-push by a third party. | Inspect origin/<default> versus local. If a teammate landed a commit during the distill window, run git pull --no-rebase to integrate. |
agent-exit-nonzero | The agent’s pi -p invocation exited non-zero with no other diagnostic. | See the error log next to the sidecar for the agent’s stderr. |
agent-timeout | timeout(1) killed the agent after distill.maxDurationMinutes minutes. | Bump distill.maxDurationMinutes in your vault config if your conversations routinely produce long distills, or check the error log for what the agent was doing when it was killed. |
Sidecar File Location
.outcome file has the machine-readable class on line 1 and optional recovery hints on subsequent lines. The .log file contains wrapper diagnostics and the agent’s stderr — useful when failed:<reason> gives an insufficient signal on its own.
Salvage on Validation Failure
When wrapper validation fails, the salvage path is deliberately narrow. The wrapper janitors only the worktree and distill branch — it never rewrites the main vault’s commit history. On a validation failure, the wrapper:- Force-removes the worktree (
git worktree remove --forcewith a path-safety guard, falling back torm -rfonly when the worktree path is a confirmed descendant of the resolved cache root). - Force-deletes the distill branch (
git branch -D). - Writes a
failed:<reason>sidecar with a recovery hint that names the corrupt squash commit if one landed on<default>. - Exits 1.
git reset --hard or otherwise rewrite the vault’s commit history. If the agent’s squash landed corrupt content, the user’s git revert HEAD --no-edit (a forward-only operation) is preferred over a destructive reset that could clobber concurrent edits made between distill spawn and validation.
What a Missing Sidecar Means
A missing.outcome file and a missing .log file together mean the wrapper itself was killed before it could write either — typically SIGKILL from an OOM event, or a hard system reboot. The JS-side poller surfaces this condition as:
Distillation terminated abnormally — no outcome recordThis is reported at
warning severity. The distill branch (if it was created before the kill) is accessible via git reflog for the standard grace period.