@cad0p/pi-napkin 0.3.0 β†’ 0.3.1

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
@@ -1,6 +1,6 @@
1
1
  # pi-napkin
2
2
 
3
- 🧻 [Napkin](https://github.com/cad0p/napkin) integration for [pi](https://github.com/badlogic/pi-mono).
3
+ πŸ“œ [Napkin](https://github.com/cad0p/napkin) integration for [pi](https://github.com/badlogic/pi-mono).
4
4
 
5
5
  Gives a pi agent first-class access to an Obsidian-compatible knowledge vault, with automatic knowledge distillation that safely captures conversation context into notes as you work.
6
6
 
@@ -213,7 +213,7 @@ Or edit `<vault>/.napkin/config.json` directly:
213
213
 
214
214
  When enabled, on session start the extension:
215
215
 
216
- 1. Runs `ensureVaultReadyForAutoDistill` on the vault (see below) β€” git-inits if needed and scaffolds `.gitignore`.
216
+ 1. Runs `ensureVaultReadyForDistill` on the vault (see below) β€” git-inits if needed and scaffolds `.gitignore`.
217
217
  2. Sweeps stale distill worktrees left by crashed pi instances (`cleanupStaleWorktrees`).
218
218
  3. Arms a timer (`intervalMinutes`) that spawns a detached `pi -p` subprocess on tick.
219
219
  4. On shutdown (unless `distill.onShutdown` is false or the session file is already captured), spawns one final distill.
@@ -233,7 +233,7 @@ The distill subprocess runs a prompt that asks the model to:
233
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:
234
234
 
235
235
  1. Runs `git init`.
236
- 2. Scaffolds `.gitignore` (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.
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.
237
237
  3. Commits everything as `napkin: initial vault commit (auto-distill setup)`.
238
238
  4. Notifies you once, with instructions to undo (`rm -rf <vault>/.git`) or opt out (`distill.enabled: false`).
239
239
 
@@ -353,7 +353,71 @@ If you want auto-distill on an existing Obsidian vault:
353
353
  2. Start a pi session in the vault.
354
354
  3. On session start, pi-napkin prompts to auto-init git if the vault isn't already one.
355
355
 
356
- If your vault IS already a git repo (common for "vault as project"), pi-napkin just adds the `.gitignore` scaffold 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.
357
421
 
358
422
  ## Troubleshooting
359
423
 
@@ -438,7 +502,11 @@ CI uses bash-stub fixtures (`extensions/distill/test-fixtures/agent-stubs/`) to
438
502
  bun run verify:e2e
439
503
  ```
440
504
 
441
- The script (`scripts/verify-e2e.ts`) creates a tmpdir vault with a bare-repo origin, registers the distill extension against a captured mock `ExtensionAPI`, triggers the `/distill` command handler so the production `runDistillWith` path runs (real wrapper subprocess, real 2-second `setInterval` poller), and 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. Exits 0 on PASS, 1 on FAIL. Manual-only β€” not in CI; cost is roughly $0.50 per run.
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.
442
510
 
443
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.
444
512