@cad0p/pi-napkin 0.2.4 → 0.3.0-20260525.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -19,6 +19,13 @@ Then install the pi-napkin extension:
19
19
  pi install npm:@cad0p/pi-napkin
20
20
  ```
21
21
 
22
+ ### Requirements
23
+
24
+ - **bash 4+** — the auto-distill wrapper uses bash arrays, `local -n`, and other bash-4 features. macOS ships bash 3.2 by default; install a newer one via `brew install bash` (the wrapper resolves bash via its `#!/usr/bin/env bash` shebang, so it picks up homebrew's bash if `brew` is on `PATH`).
25
+ - **`timeout(1)` from coreutils** — used to bound the agent's wall-clock budget (`distill.maxDurationMinutes`). Linux distros ship it as `timeout`; macOS ships it as `gtimeout` after `brew install coreutils`. The wrapper detects either binary and falls back fast with a helpful error if neither is present.
26
+ - **git 2.20+** — needed for `git worktree`, `merge-base --is-ancestor`, and `symbolic-ref --short HEAD`.
27
+ - **A `pi` configured with at least one model provider** — auto-distill spawns `pi -p` against the model in `distill.model.{provider,id}`. Manual `/distill` reuses the parent session's provider.
28
+
22
29
  <details>
23
30
  <summary>Pre-release / dev installs</summary>
24
31
 
@@ -206,7 +213,7 @@ Or edit `<vault>/.napkin/config.json` directly:
206
213
 
207
214
  When enabled, on session start the extension:
208
215
 
209
- 1. Runs `ensureVaultReadyForAutoDistill` on the vault (see below) — git-inits if needed and scaffolds `.gitignore` / `.gitattributes`.
216
+ 1. Runs `ensureVaultReadyForDistill` on the vault (see below) — git-inits if needed and scaffolds `.gitignore`.
210
217
  2. Sweeps stale distill worktrees left by crashed pi instances (`cleanupStaleWorktrees`).
211
218
  3. Arms a timer (`intervalMinutes`) that spawns a detached `pi -p` subprocess on tick.
212
219
  4. On shutdown (unless `distill.onShutdown` is false or the session file is already captured), spawns one final distill.
@@ -226,7 +233,7 @@ The distill subprocess runs a prompt that asks the model to:
226
233
  When you enable `distill.enabled: true` on a vault that isn't a git repo, pi-napkin auto-initializes it on the next session start:
227
234
 
228
235
  1. Runs `git init`.
229
- 2. Scaffolds `.gitignore` (excludes `.napkin/distill/` — the per-worktree session fork) and `.gitattributes` (routes `*.md` through the LLM merge driver). Distill worktrees themselves live outside the vault (see [Where worktrees live](#where-worktrees-live)), so `.gitignore` doesn't need to exclude them.
236
+ 2. Installs the [managed `.gitignore` block](#auto-distill-setup) (excludes `.napkin/distill/` — the per-worktree session fork). Distill worktrees themselves live outside the vault (see [Where worktrees live](#where-worktrees-live)), so `.gitignore` doesn't need to exclude them. No `.gitattributes` is written — the agent-driven merge architecture has no driver to register.
230
237
  3. Commits everything as `napkin: initial vault commit (auto-distill setup)`.
231
238
  4. Notifies you once, with instructions to undo (`rm -rf <vault>/.git`) or opt out (`distill.enabled: false`).
232
239
 
@@ -250,23 +257,61 @@ Running multiple pi sessions against the same vault (for example, autonomous age
250
257
 
251
258
  ### Worktree per distill
252
259
 
253
- Each auto-distill invocation (interval fire or shutdown) creates its own temporary branch and worktree under `$XDG_CACHE_HOME/napkin-distill/<vault-hash>/<branch-suffix>/` (typically `~/.cache/napkin-distill/…`). pi runs at the **parent session's cwd** (not the worktree) so the system prompt's `Current working directory:` line stays byte-identical to the parent's, preserving prompt-cache hits. Vault writes from the agent's bash tool are routed back to the worktree by a per-distill napkin shim at `<worktree>/.napkin/distill/bin/napkin` that injects `--vault <worktree>` into every napkin invocation. The wrapper's own git operations (`git add` / `commit` / `merge --squash`) all run with `git -C <worktree>` against the isolated checkout. See [Where worktrees live](#where-worktrees-live) for why the worktree dir is external to the vault.
260
+ Each auto-distill invocation (interval fire or shutdown) creates its own temporary branch and worktree under `$XDG_CACHE_HOME/napkin-distill/<vault-hash>/<branch-suffix>/` (typically `~/.cache/napkin-distill/…`). pi runs at the **parent session's cwd** (not the worktree) so the system prompt's `Current working directory:` line stays byte-identical to the parent's, preserving prompt-cache hits. Vault writes from the agent's bash tool are routed back to the worktree by a per-distill napkin shim at `<worktree>/.napkin/distill/bin/napkin` that injects `--vault <worktree>` into every napkin invocation. See [Where worktrees live](#where-worktrees-live) for why the worktree dir is external to the vault.
261
+
262
+ ### How distill resolves conflicts
263
+
264
+ The distill agent owns the full lifecycle: produce content → merge default branch into the distill branch → squash to default → push to origin (if configured) → clean up. The wrapper does NOT invoke a per-file merge driver; the model that wrote the content also resolves any conflicts that surface when the worktree is reconciled with main.
265
+
266
+ Flow:
267
+
268
+ 1. **Wrapper** sets up the worktree, installs the per-distill napkin shim, and spawns one `pi -p $PROMPT` invocation under `timeout ${maxDurationMinutes}m`. The prompt instructs the agent to walk steps 1–10 (distill → merge → squash → push → cleanup).
269
+ 2. **Agent** distills content into the worktree, then runs `git -C <worktree> merge --no-edit <default>`. If conflicts surface, it edits each file in place using the conversation history as context.
270
+ 3. **Agent** squash-merges into the vault's default branch (`git -C <vault> merge --squash <distill-branch>` then `git commit`).
271
+ 4. **Agent** pushes to `origin/<default>` if origin is configured. On non-fast-forward failures it recovers via `git pull --no-rebase origin <default>` then re-pushes. It NEVER uses `--force` or `--force-with-lease`.
272
+ 5. **Wrapper** post-validates: no conflict markers in tracked `*.md`, vault HEAD on default branch, push (if attempted) didn't rewrite shared history. Writes an outcome sidecar and force-cleans the worktree + distill branch.
273
+
274
+ The full prompt template lives at `extensions/distill/distill-prompt.md`. The wrapper bounds the agent's wall-clock with `timeout(1)`; everything else (retry policy, network handling, conflict-resolution shape) is the agent's call.
254
275
 
255
- ### LLM merge driver
276
+ ### Outcome classes
256
277
 
257
- When the distill commits its changes and merges back to main, conflicts are resolved by a custom git merge driver (`.napkin-distill-merge`) that calls the same model as the distill itself. The driver is registered per-worktree via `git config --local` and routed at the file level by an `*.md merge=napkin-distill-merge` entry in `.gitattributes`.
278
+ Each distill produces a sidecar at `<vault>/.napkin/distill/errors/<timestamp>-<pid>-<branch>.outcome` whose first line is a machine-readable class:
258
279
 
259
- The driver makes three attempts per conflict. After three strikes, the driver exits 1 and git leaves conflict markers — handled by the next step.
280
+ | Class | When | UI severity |
281
+ |---|---|---|
282
+ | `merged-content` | Agent produced content, integrated, squashed, and pushed to origin (or origin not configured). | info ✓ |
283
+ | `merged-local` | Agent integrated + squashed, but origin/`<default>` is configured AND local `<default>` is ahead of `origin/<default>` (push didn't land). | warning ⚠ — "distilled but not pushed" |
284
+ | `no-content` | Agent produced nothing (genuine no-op — selective filter), or committed to the distill branch but skipped squash (default branch never moved). | warning ⚠ |
285
+ | `failed:<reason>` | Wrapper validation rejected the agent's output, or the agent didn't complete. | error ✗ |
286
+
287
+ Known `failed:<reason>` codes:
288
+
289
+ | Reason | Meaning | Recovery |
290
+ |---|---|---|
291
+ | `markers-after-agent-exit` | Conflict markers (`<<<<<<<` / `=======` / `>>>>>>>`) found in tracked `*.md` files that the agent did not have at distill start. 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 ~2 weeks. |
292
+ | `pre-existing-markers` | Markers were present in the same files BEFORE the agent ran. Validation refuses to misattribute them. | Resolve the pre-existing markers in the vault yourself, then re-run distill. |
293
+ | `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 `git -C <vault> revert HEAD --no-edit`. Distill content is recoverable from `git reflog` for ~90 days. |
294
+ | `head-not-on-default` | Vault HEAD is not on the default branch after the agent exited (detached HEAD or different branch). | Manually `git checkout <default>` after confirming nothing is in flight. The distill branch lives in `git reflog` if you want to recover its content. |
295
+ | `divergent-history` | After the agent's push, `origin/<default>` and local `<default>` diverged in a way that doesn't look like a fast-forward (unexpected; benign third-party push or — defensively — a force-push). | Inspect `origin/<default>` vs local. If a teammate landed a commit during distill, `git pull --no-rebase` to integrate. |
296
+ | `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. |
297
+ | `agent-timeout` | `timeout(1)` killed the agent after `distill.maxDurationMinutes` minutes. | Bump `distill.maxDurationMinutes` if your conversations routinely produce long distills, or check the error log for what the agent was doing when it timed out. |
260
298
 
261
- ### Partial-merge salvage
299
+ A missing sidecar AND missing error log means the wrapper itself was killed before writing either (SIGKILL, OOM). The JS-side poller surfaces this as "distill terminated abnormally".
262
300
 
263
- If the LLM merge driver fails on some files, we don't abort the whole merge. Files that merged cleanly keep the distill's content; files that failed fall back to main's version via `git checkout main -- <file>`.
301
+ ### Salvage when validation fails
264
302
 
265
- Think of it as: "save what you can, log what you lost." A per-failure entry is written to `<vault>/.napkin/distill/errors/` so you can inspect what was discarded, and the dangling distill commit SHA is kept for ~2 weeks of git gc grace in case you want to recover it manually.
303
+ The salvage path is deliberately narrow: the wrapper janitors the **worktree and distill branch**, never the main vault's commit history. If validation fails:
304
+
305
+ - Force-remove the worktree (`git worktree remove --force` + path-safety guard, falling back to `rm -rf` only if the worktree path is a descendant of the resolved cache root).
306
+ - Force-delete the distill branch (`git branch -D`).
307
+ - Write a `failed:<reason>` sidecar with a recovery hint that points at the corrupt squash commit if one landed on `<default>`.
308
+ - Exit 1.
309
+
310
+ The wrapper deliberately does NOT `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` (forward-only) is preferred over a destructive reset that could clobber concurrent edits the user made between distill spawn and validation. The recovery hint in the failed sidecar names the exact command.
266
311
 
267
312
  ### Linear history
268
313
 
269
- Successful distill lifecycles produce exactly one squash commit on `main`, with an LLM-generated summary message. This keeps history clean and makes it easy to revert a bad distill with `git revert <sha>`.
314
+ Successful distill lifecycles produce exactly one squash commit on `main`, with a one-line summary the agent generates from the distill content. This keeps history clean and makes it easy to revert a bad distill with `git revert <sha>`.
270
315
 
271
316
  ## Agent visibility
272
317
 
@@ -308,7 +353,71 @@ If you want auto-distill on an existing Obsidian vault:
308
353
  2. Start a pi session in the vault.
309
354
  3. On session start, pi-napkin prompts to auto-init git if the vault isn't already one.
310
355
 
311
- If your vault IS already a git repo (common for "vault as project"), pi-napkin just adds the `.gitignore` / `.gitattributes` scaffolds and moves on.
356
+ If your vault IS already a git repo (common for "vault as project"), pi-napkin just installs the [managed `.gitignore` block](#auto-distill-setup) and moves on.
357
+
358
+ ## Auto-distill setup
359
+
360
+ Every time pi starts a session in an auto-distill-enabled vault, pi-napkin runs a **health check** that confirms the vault is in a state the worktree-based distill can actually run against. The check is layered into two cadences so the cost of routine checks stays near-zero while the rare expensive checks only fire on the manual `/distill` path.
361
+
362
+ ### The managed `.gitignore` block
363
+
364
+ pi-napkin owns a single contiguous block in the vault's `.gitignore`, delimited by these exact marker lines:
365
+
366
+ ```gitignore
367
+ # BEGIN NAPKIN-DISTILL MANAGED
368
+ # napkin-distill ephemeral state
369
+ .napkin/distill/
370
+
371
+ # Obsidian workspace-local state
372
+ .obsidian/workspace*.json
373
+ .obsidian/cache
374
+ .obsidian/.trash/
375
+
376
+ # Local tmp/cache + common secrets (belt-and-braces; auto-init's
377
+ # `git add .` would otherwise capture them in the initial commit
378
+ # even on vaults that happen to contain dev work).
379
+ # (full canonical body in extensions/distill/auto-setup.ts:BLOCK_CONTENT)
380
+ # END NAPKIN-DISTILL MANAGED
381
+ ```
382
+
383
+ **Inside the markers:** pi-napkin owns the content. Hand-edits between the markers are reset on the next session start — the auto-init / health-check pass rewrites the block to its canonical content if it has drifted.
384
+
385
+ **Outside the markers:** user territory. pi-napkin's only edit outside the block is removing lines that match canonical block content (a one-time migration cleanup from the 0.3.0 line-by-line format, kept on every run as a self-heal). User-written lines that don't match canonical content are never touched. You can add, remove, or reorder anything else in `.gitignore` and pi-napkin will leave it alone.
386
+
387
+ The block style is the same Ansible-style sentinel pattern Ansible's `blockinfile` module uses (and Homebrew, oh-my-zsh, etc.) so the boundary between managed and unmanaged content is visually obvious.
388
+
389
+ ### Fast-level vs full-level checks
390
+
391
+ | Cadence | When | What it covers | Typical cost |
392
+ |---|---|---|---|
393
+ | Fast-level | Every `session_start` (every pi launch in the vault) | Subdir vs legacy-embedded layout, managed gitignore block matches canonical (auto-recover if drift), auto-init `git init` + initial commit if `.git/` is missing | Sub-second (a handful of git probes) |
394
+ | Full-level | On `/distill` (manual) and at each interval-driven auto-distill spawn | Everything fast-level covers, plus: `.napkin/config.json` is git-tracked, vault HEAD resolves to a commit (seed an empty initial commit if a hand-`git init`-ed vault has no commits yet), `.napkin/config.json` not gitignored outside the managed block, `.napkin/distill/` not tracked, cache root writable, no orphaned distill worktree registry entries, no stale `distill/*` branches past the grace period | A few extra git probes; runs only when a worktree is about to be spawned anyway |
395
+
396
+ Fast-level findings surface as one-shot notifications at session start; the session continues regardless. Full-level findings are gated separately depending on category (below).
397
+
398
+ ### Auto-recover findings (info; distill proceeds)
399
+
400
+ These are recoverable drift the health check fixes in place. Each emits a single info notification of the form `Auto-distill recovered: <message>` and `/distill` proceeds normally afterward:
401
+
402
+ - **Managed-block drift** — markers got reordered, content drifted, or canonical lines leaked outside the block. Resolution: rewrite the bracketed region back to canonical and strip any leaked lines from user territory.
403
+ - **Untracked `.napkin/config.json`** (full-level only) — config file exists but isn't yet in git's index. Resolution: stage and commit it (so worktrees can see it).
404
+ - **Vault HEAD resolves to a commit** (full-level only) — the vault is a `git init`-ed repo with zero commits, so `git rev-parse --verify HEAD` fails and `git worktree add HEAD` would have no ref to pin to. Resolution: `git commit --allow-empty` to seed an empty initial commit. (Detached-HEAD-after-distill is a separate post-distill concern surfaced as the `head-not-on-default` outcome reason in the wrapper-side table above; it requires manual recovery.)
405
+ - **Orphaned distill worktrees** (full-level only) — a previous distill crashed and left a `git worktree list` registry entry pointing at a directory that no longer exists. Resolution: `git worktree prune --expire=now`.
406
+ - **Stale `distill/*` branches** (full-level only) — a `distill/*` branch with a committerdate older than the grace period (24h) AND no live worktree pointing at it. Resolution: `git branch -D <branch>`. The reflog grace gives you a recovery window for content from a failed distill.
407
+
408
+ ### Loud-error findings (error; distill aborts)
409
+
410
+ These are conditions where auto-distill cannot safely proceed. Each emits an error notification of the form `Auto-distill cannot proceed: <message>` and `/distill` aborts before spawning a wrapper:
411
+
412
+ - **Subdir-layout violation** — vault uses napkin's legacy embedded layout (config at `<vault>/config.json`, no `.napkin/` subdir). Auto-distill needs the subdir layout for worktree-based concurrency to work; see [Migration from legacy layout](#migration-from-legacy-layout).
413
+ - **Malformed `.napkin/config.json`** — file exists but doesn't parse as JSON. Detected by `loadVaultConfig` upstream of the health check itself; auto-distill refuses to guess; fix the file and reload.
414
+ - **`.napkin/config.json` gitignored outside the managed block** (full-level only) — a user-territory rule in `.gitignore` (or a parent `.gitignore` / global ignore) excludes the config file. Worktrees would have no config to read; remove the rule or move it inside the managed block.
415
+ - **`.napkin/distill/` tracked in git** (full-level only) — the per-worktree session fork directory got committed at some point. Untrack it (`git rm --cached -r .napkin/distill/`) before re-running.
416
+ - **Cache root unwritable** (full-level only) — `$XDG_CACHE_HOME/napkin-distill/<hash>/` can't be created or written. Check disk space and permissions on the cache root.
417
+
418
+ ### Opt out
419
+
420
+ Set `distill.enabled = false` in `.napkin/config.json` (or run `napkin --vault <path> config set --key distill.enabled --value false`). With auto-distill disabled, pi-napkin runs no health checks, installs no managed block, and never touches `.gitignore`. Manual `/distill` still works — it has no concurrency-safety prerequisites.
312
421
 
313
422
  ## Troubleshooting
314
423
 
@@ -331,15 +440,18 @@ rm -rf ~/.cache/napkin-distill/
331
440
 
332
441
  Safe — anything valuable is either already committed to main or was never going to commit.
333
442
 
334
- ### Merge driver fails repeatedly
443
+ ### Distill keeps failing (`failed:<reason>`)
444
+
445
+ Outcome sidecar: `<vault>/.napkin/distill/errors/<ISO-timestamp>-<pid>-<branch-hash>.outcome`. First line is the class string (`failed:<reason>`); remaining lines are a human-readable recovery hint.
335
446
 
336
- Error log: `<vault>/.napkin/distill/errors/<ISO-timestamp>-<pid>-<branch-hash>.log`.
447
+ Companion error log (if produced): `<ISO-timestamp>-<pid>-<branch-hash>.log` — wrapper diagnostics + the agent's stderr.
337
448
 
338
- Each log has the conflicted files, the last LLM response, and an optional one-liner describing the failure. Common causes:
449
+ See the [Outcome classes](#outcome-classes) table for what each `<reason>` means and the recommended recovery action. Common patterns:
339
450
 
340
- - Model is rate-limited → retry later.
341
- - LLM returned empty / tiny / huge output → driver sanity-check rejects it. Usually a transient provider issue.
342
- - Conflicted content is genuinely unmergeable (same line added with different content) → the partial-merge salvage falls back to main's version; the distill commit SHA is kept in reflog for ~2 weeks if you want to recover it.
451
+ - `agent-timeout` recurring → bump `distill.maxDurationMinutes` (default 10) or investigate what's taking the agent so long. Log shows the last tool calls before SIGTERM.
452
+ - `markers-after-agent-exit` → the agent's squash commit may already be on `<default>` with literal `<<<<<<<` markers in tracked files. The recovery hint in the sidecar names the exact `git revert HEAD --no-edit` command.
453
+ - `agent-exit-nonzero` → check the model provider (rate limits, auth refresh, network). The agent's stderr is in the `.log` file.
454
+ - `divergent-history` → a teammate likely landed a commit on `origin/<default>` while the agent's distill ran. `git pull --no-rebase` to integrate.
343
455
 
344
456
  ### "vault not a git repo" / "legacy embedded layout"
345
457
 
@@ -356,21 +468,51 @@ The distill wrapper (`extensions/distill/scripts/distill-wrapper.sh`) reads seve
356
468
 
357
469
  | Variable | Purpose |
358
470
  |---|---|
359
- | `NAPKIN_DISTILL_PI_BIN` | Override the `pi` binary path. Tests point this at `/usr/bin/true` (exits 0 quickly) or a stub script so the wrapper completes its lifecycle without contacting a real LLM. |
360
- | `NAPKIN_DISTILL_MERGE_MOCK` | Forwarded to `napkin-distill-merge` (the LLM driver). Set to `fail` to force every conflict to 3-strike, or `ok-after-N` to succeed after N attempts. Used to exercise the partial-merge salvage path. |
361
- | `NAPKIN_DISTILL_SKIP_PI=1` | Skip BOTH the napkin shim install AND the `pi` invocation. Used by tests that pre-stage file changes manually and only want to exercise the wrapper's git lifecycle (commit/merge/squash). |
471
+ | `NAPKIN_DISTILL_PI_BIN` | Override the `pi` binary path. Integration tests under `extensions/distill/test-fixtures/agent-stubs/` point this at a bash stub that simulates a specific agent behavior class (clean-distill, conflict-resolve-clean, agent-timeout, etc.) so the wrapper completes its lifecycle without contacting a real LLM. |
472
+ | `NAPKIN_DISTILL_SKIP_PI=1` | Skip BOTH the napkin shim install AND the `pi` invocation. Used by tests that pre-stage file changes manually and only want to exercise the wrapper's lifecycle (validation, salvage, sidecar emission). |
473
+ | `NAPKIN_DISTILL_NO_RECURSE=1` | Exported by the wrapper into the agent's environment so a nested `pi` won't auto-distill recursively. Tests sometimes set it directly to suppress recursion when invoking the wrapper from inside another distill. |
362
474
  | `NAPKIN_DISTILL_HALT_AFTER_META=1` | Halt right after rewriting `meta.json`'s pid to the wrapper's pid. Lets tests inspect the updated meta without the cleanup trap wiping the worktree. Clears the `EXIT` trap so cleanup is skipped — caller is responsible for tearing down the worktree afterwards. |
363
475
  | `NAPKIN_DISTILL_HALT_AFTER_SHIM=1` | Halt right after the per-distill napkin shim is installed at `<worktree>/.napkin/distill/bin/napkin`. Lets tests inspect the shim contents and PATH injection without the cleanup trap firing. |
364
- | `NAPKIN_DISTILL_FORCE_MERGE_HEAD=1` | Force `MERGE_HEAD` to exist right before the escape-hatch check. Lets tests cover the belt-and-braces "merge did not complete" bail-out path, which isn't reliably triggerable via real driver output (git clears `MERGE_HEAD` on driver exit 0). |
365
- | `NAPKIN_DISTILL_FORCE_MERGE_RC=<n>` | Override the captured merge exit code. Lets tests cover the unexpected-exit-code branch (128 etc.) without contriving a real git failure of that shape. |
476
+ | `NAPKIN_DISTILL_FORCE_CLEANUP=1` | Force the salvage / cleanup path to run unconditionally (even on success). Used to test salvage idempotency. |
477
+ | `NAPKIN_DISTILL_TIMEOUT_KILL_GRACE_SECS=<n>` | Override the `timeout(1) -k` grace window (default 30s) — the delay between SIGTERM and SIGKILL when the agent exceeds `distill.maxDurationMinutes`. Used to keep timeout tests fast. |
366
478
 
367
479
  Production never sets any of these. If you find one in your environment by accident, `unset` it and re-run — the wrapper falls back to its normal behaviour automatically.
368
480
 
369
- ## Future: builder-deleter
481
+ ## Migration from PR #11
482
+
483
+ pi-napkin v0.1.x shipped an LLM-backed git merge driver (`.napkin-distill-merge`). PR #12 (v0.2.x) deleted the driver entirely; the agent now resolves its own conflicts as part of the distill task. New vaults set up by v0.2+ never see the driver. Existing v0.1.x vaults retain inert fragments that are safe to leave in place but cleaner to remove:
370
484
 
371
- Next major feature: a "builder-deleter" janitor that acts on the `supersedes:` frontmatter convention that auto-distill already writes. When a note lists `supersedes: ["old/note.md"]`, the janitor archives the superseded file. Threshold-triggered to avoid running on every distill, git gc as the safety net.
485
+ ```bash
486
+ # In each existing vault that ran v0.1.x distill:
487
+ git config --local --remove-section merge.napkin-distill-merge 2>/dev/null || true
488
+
489
+ # Edit <vault>/.gitattributes and remove this line if present:
490
+ # *.md merge=napkin-distill-merge
491
+ ```
492
+
493
+ Why manual: PR #12 deliberately avoids automatic migration. The orphaned `.gitattributes` rule falls back to git's built-in merge driver once the script is gone (the rule becomes inert, not harmful), so the cost of automating cleanup outweighs the benefit for a project with a small user base. New vaults aren't affected.
494
+
495
+ ## Maintenance
496
+
497
+ ### Verifying the distill flow end-to-end against a real LLM
498
+
499
+ CI uses bash-stub fixtures (`extensions/distill/test-fixtures/agent-stubs/`) to cover the agent-behavior space without burning tokens. For ad-hoc re-validation that the full runtime — wrapper subprocess + agent + JS-side polling — still walks cleanly through a real model, run:
500
+
501
+ ```bash
502
+ bun run verify:e2e
503
+ ```
504
+
505
+ The script (`scripts/verify-e2e.ts`) creates a tmpdir vault by invoking the real `napkin init` CLI, then drives the production session_start handler so auto-init's `git init` + managed `.gitignore` block + initial commit run end-to-end, then triggers the `/distill` command handler so the production `runDistillWith` path runs (real wrapper subprocess, real 2-second `setInterval` poller). It asserts on the dispatched UI notification's severity + message together with filesystem post-conditions: no conflict markers, HEAD on default branch, agent's squash commit landed, distill branch removed, worktree removed, outcome sidecar with class `merged-content`, and origin advanced.
506
+
507
+ The gate also accepts `--variant <name>` (or `--all`) to exercise the full-level health-check decision points end-to-end — a loud-error path (`config-outside-block`, which aborts before LLM dispatch and costs $0) and an auto-recover path (`orphaned-worktree`, which prunes the orphan and then runs the full distill). The default `healthy` variant is the original gate.
508
+
509
+ Exits 0 on PASS, 1 on FAIL. Manual-only — not in CI; cost is roughly $0.50 per LLM-driven variant.
510
+
511
+ This replaces the earlier prompt-only gate. The strict superset matters because the wrapper↔JS-poller seam — where worktree-teardown and outcome-write race — is invisible to a prompt-only harness.
512
+
513
+ ## Future: builder-deleter
372
514
 
373
- See [features/pi-napkin-distill/builder-deleter](https://github.com/cad0p/pi-napkin/blob/main/features/) (design pending) for the full design.
515
+ Next major feature: a "builder-deleter" janitor that acts on the `supersedes:` frontmatter convention that auto-distill already writes. When a note lists `supersedes: ["old/note.md"]`, the janitor archives the superseded file. Threshold-triggered to avoid running on every distill, git gc as the safety net. Design pending.
374
516
 
375
517
  ## License
376
518