@cad0p/pi-napkin 0.2.4

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.
@@ -0,0 +1,692 @@
1
+ #!/usr/bin/env bash
2
+ # distill-wrapper — orchestrates a single auto-distill attempt inside a
3
+ # per-distill git worktree.
4
+ #
5
+ # Usage:
6
+ # distill-wrapper.sh <vault> <worktree> <branch> <sessionFork> <prompt> <errorDir> [<model>] [<defaultBranch>] [<parentCwd>]
7
+ #
8
+ # Arguments:
9
+ # <vault> absolute path to the main vault (NOT the worktree)
10
+ # <worktree> absolute path to the distill worktree (lives under
11
+ # `$XDG_CACHE_HOME/napkin-distill/<vault-hash>/<suffix>/`;
12
+ # see `resolveCacheRoot` in extensions/distill/distill-workspace.ts)
13
+ # <branch> distill branch name (`distill/<hex>-<epoch>`)
14
+ # <sessionFork> absolute path to the forked session .jsonl inside the worktree
15
+ # <prompt> prompt passed to `pi -p`
16
+ # <errorDir> absolute path to `<vault.configPath>/distill/errors/`
17
+ # <model> optional "<provider>/<id>" to pass to `pi --model`
18
+ # <defaultBranch> optional name of the vault's mainline branch (e.g. `main`,
19
+ # `master`). When empty/absent, defaults to `main`. The JS
20
+ # side resolves this via `git symbolic-ref refs/remotes/origin/HEAD`
21
+ # or a HEAD-ref lookup so the wrapper doesn't hardcode `main`.
22
+ # <parentCwd> REQUIRED. Absolute path of the parent pi session's cwd.
23
+ # Pi is spawned at this cwd so the system prompt's
24
+ # `Current working directory:` line is byte-identical
25
+ # to the parent's, preserving prompt-cache hits. Vault
26
+ # writes are still routed to the worktree via the
27
+ # napkin shim installed at
28
+ # `<worktree>/.napkin/distill/bin/napkin`. The wrapper
29
+ # hard-fails if this is empty (R7-PERF-7, R7-CI-6) —
30
+ # silently falling back to <worktree> would re-
31
+ # introduce the cache regression POST-R6-CACHE fixed.
32
+ #
33
+ # Lifecycle (happy path):
34
+ # 1. install napkin shim at <worktree>/.napkin/distill/bin/napkin and
35
+ # prepend it to PATH (auto-routes agent napkin calls to the worktree)
36
+ # 2. cd <parentCwd> (cache parity — keeps pi's
37
+ # system prompt cwd line
38
+ # byte-identical to parent's)
39
+ # 3. pi --session <sessionFork> -p <prompt> (with NAPKIN_DISTILL_NO_RECURSE=1)
40
+ # 4. git -C <worktree> add -A
41
+ # 5. git -C <worktree> commit -m "distill: …" (skipped if nothing changed)
42
+ # 6. git_retry git -C <worktree> merge main (LLM merge driver handles *.md
43
+ # conflicts; 3-strike salvage
44
+ # reverts unresolvable files to
45
+ # main's version)
46
+ # 7. cd <vault>
47
+ # 8. git_retry git merge --squash <branch>
48
+ # 9. git_retry git commit -m "<msg>" (skipped if squash produced no change)
49
+ # 10. cleanup (trap): git worktree remove --force, git branch -D
50
+ # (also removes the shim, which lives inside the worktree)
51
+ #
52
+ # Error handling:
53
+ # Any fatal failure writes a log entry to:
54
+ # <errorDir>/<ISO-timestamp>-<pid>-<branch-short-hash>.log
55
+ # and proceeds to cleanup. We never `exit` before the trap so worktrees and
56
+ # branches are always torn down.
57
+ #
58
+ # Environment:
59
+ # NAPKIN_DISTILL_NO_RECURSE=1 exported so the nested `pi` won't auto-distill
60
+ # NAPKIN_GIT_RETRY_MAX forwarded to git_retry
61
+ # NAPKIN_GIT_RETRY_DELAY forwarded to git_retry
62
+ #
63
+ # Testing hooks:
64
+ # NAPKIN_DISTILL_PI_BIN path to a stub `pi` binary (integration tests)
65
+ # NAPKIN_DISTILL_MERGE_MOCK forwarded to the merge driver
66
+ # NAPKIN_DISTILL_SKIP_PI=1 skip the pi invocation entirely; distill
67
+ # wrapper instead expects tests to pre-stage any
68
+ # file changes into the worktree.
69
+ # NAPKIN_DISTILL_HALT_AFTER_META=1
70
+ # halt right after rewriting meta.json's pid to
71
+ # the wrapper's pid — lets tests inspect the
72
+ # updated meta without the cleanup trap
73
+ # wiping the worktree.
74
+ # NAPKIN_DISTILL_HALT_AFTER_SHIM=1
75
+ # halt right after the per-distill napkin shim
76
+ # is installed at <worktree>/.napkin/distill/bin/napkin
77
+ # — lets tests inspect the shim contents and PATH
78
+ # injection without the cleanup trap wiping it.
79
+ # NAPKIN_DISTILL_FORCE_CLEANUP=1
80
+ # trigger the cleanup trap from a controlled
81
+ # exit point post-shim-install. Unlike the
82
+ # HALT_AFTER_* hooks this does NOT clear
83
+ # the EXIT trap — the cleanup function
84
+ # fires and tests assert on its post-state
85
+ # (rm-rf fallback, rmdir parent, etc.).
86
+ # NAPKIN_DISTILL_FORCE_MERGE_HEAD=1
87
+ # force MERGE_HEAD to exist right before the
88
+ # escape-hatch check — lets tests cover the
89
+ # belt-and-braces "merge did not complete"
90
+ # bail-out path, which isn't reliably
91
+ # triggerable via real driver output.
92
+ # NAPKIN_DISTILL_FORCE_MERGE_RC=<n>
93
+ # override the captured merge exit code —
94
+ # lets tests cover the unexpected-exit-code
95
+ # branch (128 etc.) without contriving a
96
+ # real git failure of that shape.
97
+
98
+ set -uo pipefail
99
+
100
+ # Resolve our own script dir so we can source git_retry.sh regardless of cwd.
101
+ HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
102
+ # shellcheck source=./git_retry.sh
103
+ source "$HERE/git_retry.sh"
104
+
105
+ VAULT="${1:-}"
106
+ WORKTREE="${2:-}"
107
+ BRANCH="${3:-}"
108
+ SESSION_FORK="${4:-}"
109
+ PROMPT="${5:-}"
110
+ ERROR_DIR="${6:-}"
111
+ MODEL="${7:-}"
112
+ DEFAULT_BRANCH="${8:-main}"
113
+ PARENT_CWD="${9:-}"
114
+ # Treat empty string as "use fallback", not "literal empty branch name".
115
+ if [ -z "$DEFAULT_BRANCH" ]; then
116
+ DEFAULT_BRANCH="main"
117
+ fi
118
+ # parentCwd (arg 9) is required since POST-R6-CACHE: pi spawns at
119
+ # parentCwd to keep the system prompt's `Current working directory:`
120
+ # line byte-identical to the parent's, preserving prompt-cache hits.
121
+ # Falling back silently to $WORKTREE (pre-R7) re-introduces the cache
122
+ # regression with no observable signal — hard-fail instead so any
123
+ # out-of-tree caller surfaces the contract violation immediately.
124
+ # (R7-PERF-7, R7-CI-6.)
125
+ if [ -z "$PARENT_CWD" ]; then
126
+ echo "distill-wrapper: missing required argument 9 (parentCwd) — cache-preserving spawn requires the parent pi session's cwd" >&2
127
+ exit 2
128
+ fi
129
+
130
+ if [ -z "$VAULT" ] || [ -z "$WORKTREE" ] || [ -z "$BRANCH" ] || \
131
+ [ -z "$SESSION_FORK" ] || [ -z "$PROMPT" ] || [ -z "$ERROR_DIR" ]; then
132
+ echo "distill-wrapper: missing required argument" >&2
133
+ exit 2
134
+ fi
135
+
136
+ # Export so the merge driver subprocess (spawned by `git merge` two layers
137
+ # down) inherits it and co-locates its forensic logs in the wrapper's
138
+ # vault-local errorDir. Without `export`, this stays a wrapper-only local
139
+ # and the driver falls through to the XDG_CACHE_HOME fallback at
140
+ # napkin-distill-merge:124, contradicting the production-doc claim that
141
+ # all per-distill artefacts live under <vault>/.napkin/distill/errors/.
142
+ export NAPKIN_DISTILL_ERROR_DIR="$ERROR_DIR"
143
+
144
+ # Compute error log path. `branch-short-hash` is the portion after `distill/`
145
+ # (already unique per invocation — hex nonce + epoch).
146
+ BRANCH_SHORT="${BRANCH#distill/}"
147
+ TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
148
+ # Two distinct log files per branch:
149
+ # *.log — fatal-error log. Presence of this file is the
150
+ # JS-side signal that the wrapper failed (R7-SC-3 +
151
+ # R8-CC-1). Lazily created on first `log_error` call.
152
+ # *.partial-merge.log — forensic log for partial-merge salvage on the
153
+ # SUCCESS path: each file the LLM driver 3-strike'd
154
+ # and we reverted to the default branch. Presence of
155
+ # this file is informational — the wrapper still
156
+ # exits 0 and the squash commit lands on main.
157
+ # JS-side `findDistillErrorLogForBranch` filters by
158
+ # suffix `-<branchShort>.log` (NOT
159
+ # `-<branchShort>.partial-merge.log`), so a salvage
160
+ # success doesn't surface as a failure.
161
+ ERROR_LOG="$ERROR_DIR/${TIMESTAMP}-$$-${BRANCH_SHORT}.log"
162
+ PARTIAL_MERGE_LOG="$ERROR_DIR/${TIMESTAMP}-$$-${BRANCH_SHORT}.partial-merge.log"
163
+ # Outcome sidecar (POST-CONV-5) — one-line classification of why the
164
+ # wrapper exited 0. The detached wrapper's exit status is unobservable
165
+ # to the parent (`stdio:ignore` + `unref()`); the filesystem is the
166
+ # only signal channel.
167
+ #
168
+ # JS-side runDistillWith poller dispatches UI severity per outcome class.
169
+ # See formatOutcomeNotification in extensions/distill/index.ts for the
170
+ # canonical mapping. Per the locked notification severity contract:
171
+ # merged-content → info; no-content → warning; partial-merge → warning
172
+ # with log path; missing-sidecar AND missing-error-log → warning (abnormal).
173
+ OUTCOME_PATH="$ERROR_DIR/${TIMESTAMP}-$$-${BRANCH_SHORT}.outcome"
174
+
175
+ # Lazy-create error log on first write. Empty file is the "no error" signal.
176
+ ERROR_LOG_TOUCHED=0
177
+ log_error() {
178
+ if [ "$ERROR_LOG_TOUCHED" -eq 0 ]; then
179
+ mkdir -p "$ERROR_DIR"
180
+ {
181
+ echo "# napkin distill error log"
182
+ echo "branch: $BRANCH"
183
+ echo "vault: $VAULT"
184
+ echo "worktree: $WORKTREE"
185
+ echo "started: $TIMESTAMP"
186
+ echo "pid: $$"
187
+ echo
188
+ } >> "$ERROR_LOG"
189
+ ERROR_LOG_TOUCHED=1
190
+ fi
191
+ echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) $*" >> "$ERROR_LOG"
192
+ }
193
+
194
+ # Lazy-create partial-merge log on first write. Forensic-only — distinct
195
+ # filename so the JS-side failure check ignores it. Used by the salvage
196
+ # path on the success branch (each file the LLM driver 3-strike'd is
197
+ # logged here, NOT to the fatal log; the wrapper proceeds to commit and
198
+ # exits 0).
199
+ PARTIAL_MERGE_LOG_TOUCHED=0
200
+ log_partial_merge() {
201
+ if [ "$PARTIAL_MERGE_LOG_TOUCHED" -eq 0 ]; then
202
+ mkdir -p "$ERROR_DIR"
203
+ {
204
+ echo "# napkin distill partial-merge salvage log"
205
+ echo "branch: $BRANCH"
206
+ echo "vault: $VAULT"
207
+ echo "worktree: $WORKTREE"
208
+ echo "started: $TIMESTAMP"
209
+ echo "pid: $$"
210
+ echo ""
211
+ echo "# This log records files the LLM merge driver 3-strike'd and"
212
+ echo "# the wrapper reverted to the default branch's version. The"
213
+ echo "# distill itself succeeded (other files merged cleanly and the"
214
+ echo "# squash commit landed on main); see the corresponding"
215
+ echo "# .log file (if any) for fatal errors."
216
+ echo
217
+ } >> "$PARTIAL_MERGE_LOG"
218
+ PARTIAL_MERGE_LOG_TOUCHED=1
219
+ fi
220
+ echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) $*" >> "$PARTIAL_MERGE_LOG"
221
+ }
222
+
223
+ # Capture the dangling commit SHA for forensic recovery (git gc grace period
224
+ # is 2 weeks by default; `git reflog` holds 90 days). Printed into the error
225
+ # log on any fatal failure path so the user can `git cat-file -p <sha>` to
226
+ # resurrect the distill's work.
227
+ record_dangling_sha() {
228
+ local sha
229
+ sha="$(git -C "$WORKTREE" rev-parse HEAD 2>/dev/null || true)"
230
+ if [ -n "$sha" ]; then
231
+ log_error "dangling distill commit SHA: $sha"
232
+ fi
233
+ }
234
+
235
+ # Write the outcome sidecar (POST-CONV-5). One line, one class string.
236
+ # Caller must invoke this immediately before any successful `exit 0`
237
+ # path. Idempotent: a double call would just rewrite the same file.
238
+ write_outcome() {
239
+ local class="$1"
240
+ mkdir -p "$ERROR_DIR" 2>/dev/null || true
241
+ printf '%s\n' "$class" > "$OUTCOME_PATH" 2>/dev/null || true
242
+ }
243
+
244
+ # Tracks whether the partial-merge salvage path fired during this run.
245
+ # Read at the final `exit 0` to pick the right outcome class
246
+ # (merged-content vs partial-merge). Salvage is on the success path —
247
+ # the squash still lands — but the user must be warned that some
248
+ # files reverted to the default branch.
249
+ PARTIAL_MERGE_OCCURRED=0
250
+
251
+ # Trap-based cleanup: always remove the worktree + branch on exit (success or
252
+ # failure). `git worktree remove --force` also handles partially-initialized
253
+ # worktrees. Errors from cleanup are logged but don't affect our exit status.
254
+ cleanup() {
255
+ local rc=$?
256
+ # cd out of the worktree before removing it, otherwise git refuses.
257
+ cd "$VAULT" 2>/dev/null || cd /
258
+ if [ -d "$WORKTREE" ]; then
259
+ git -C "$VAULT" worktree remove --force "$WORKTREE" 2>/dev/null || true
260
+ fi
261
+ # In production this fires on every exit because the gitignored
262
+ # .napkin/distill/ shim survives `git worktree remove --force`. The
263
+ # `[ -d ]` guard is defensive against future scenarios where the shim
264
+ # is removed before this point. Mirrors cleanupDistillWorkspace's
265
+ # contract at distill-workspace.ts:572.
266
+ if [ -d "$WORKTREE" ]; then
267
+ rm -rf "$WORKTREE" 2>/dev/null || true
268
+ fi
269
+ # Prune in case the worktree entry is stale but the dir is gone.
270
+ git -C "$VAULT" worktree prune 2>/dev/null || true
271
+ # -D (force) because the distill branch is never marked "merged" (we use
272
+ # squash merge on main, which leaves the branch dangling).
273
+ git -C "$VAULT" branch -D "$BRANCH" 2>/dev/null || true
274
+ # Best-effort rmdir of the parent vault-hash dir — succeeds when this
275
+ # was the last distill for the vault. ENOTEMPTY (other concurrent
276
+ # distills) and ENOENT (race) are both expected and benign.
277
+ rmdir "$(dirname "$WORKTREE")" 2>/dev/null || true
278
+ exit "$rc"
279
+ }
280
+ trap cleanup EXIT
281
+
282
+ # --- Update meta.json's pid to OUR pid ($$) -----------------------------------
283
+ #
284
+ # createDistillWorkspace() writes meta.json before this wrapper starts, with
285
+ # `pid` set to the parent pi session's pid — a pre-spawn placeholder. For
286
+ # liveness checks in `getActiveDistills` / `cleanupStaleWorktrees` to be
287
+ # accurate, the recorded pid must track THIS wrapper's lifetime: when this
288
+ # process dies, the worktree is defunct; when it runs, the worktree is live.
289
+ # Rewrite the pid field in place before doing anything else.
290
+ #
291
+ # The JSON is produced by node's JSON.stringify(obj, null, 2), so the `pid`
292
+ # line always has the shape ` "pid": <number>,`. A targeted sed replaces
293
+ # just that line. We use a temp file + mv for atomicity (cheap since it's
294
+ # same-filesystem).
295
+ META_PATH="$WORKTREE/.napkin/distill/meta.json"
296
+ if [ -f "$META_PATH" ]; then
297
+ META_TMP="$META_PATH.tmp.$$"
298
+ if sed -E "s/(\"pid\":[[:space:]]*)[0-9]+/\1$$/" "$META_PATH" > "$META_TMP"; then
299
+ mv "$META_TMP" "$META_PATH"
300
+ else
301
+ rm -f "$META_TMP"
302
+ log_error "failed to rewrite meta.json pid to wrapper pid ($$)"
303
+ fi
304
+ fi
305
+
306
+ # Extract startSha from meta.json — used for the post-pi diff that
307
+ # detects whether pi produced any content (committed by pi itself or
308
+ # staged-but-uncommitted). createDistillWorkspace populates this field
309
+ # with the vault HEAD captured pre-spawn; same JSON.stringify(obj,
310
+ # null, 2) shape as `pid`.
311
+ #
312
+ # Use node for parsing instead of sed: a regex on JSON is fragile
313
+ # against future shape changes (multi-line values, embedded commas,
314
+ # nested objects) and would silently degrade to an empty extraction
315
+ # on shape drift. Node is normally on PATH inside the wrapper because
316
+ # pi-bun spawned us; the same JSON parser the JS side wrote with is
317
+ # the most robust reader.
318
+ #
319
+ # Hard-fail with a clear diagnostic if node is missing or unrunnable
320
+ # rather than letting the meta-missing-startSha hard-fail downstream
321
+ # mislead the user (R13-CI-1 / R13-CC-3). Cron / systemd / launchd /
322
+ # container-init-launched pi may all have stripped PATHs without
323
+ # node's bindir (mise / nvm / asdf install node outside /usr/bin).
324
+ # Mirrors the napkin --version smoke-test pattern below for shape
325
+ # consistency.
326
+ REAL_NODE="$(command -v node || true)"
327
+ if [ -z "$REAL_NODE" ]; then
328
+ log_error "node binary not found on wrapper PATH; required for startSha extraction. Set PATH to include node before launching pi."
329
+ log_error " PATH=$PATH"
330
+ exit 1
331
+ fi
332
+ if ! "$REAL_NODE" --version >/dev/null 2>&1; then
333
+ log_error "node binary not runnable on wrapper PATH (resolved to '$REAL_NODE'); shebang or binary issue."
334
+ log_error " PATH=$PATH"
335
+ exit 1
336
+ fi
337
+
338
+ START_SHA=""
339
+ if [ -f "$META_PATH" ]; then
340
+ START_SHA="$("$REAL_NODE" -e 'try { const d = require(process.argv[1]); process.stdout.write(d.startSha || ""); } catch { /* swallow — empty START_SHA triggers the hard-fail below */ }' "$META_PATH" 2>/dev/null || true)"
341
+ fi
342
+
343
+ # Hard-fail when startSha can't be recovered. The pre-POST-CONV-1
344
+ # wrapper used a `git diff --cached --quiet` no-op check that silently
345
+ # dropped pi-self-committed content (real failure: dropped commit
346
+ # `a13e8b1`). A silent fallback to that path on extraction failure
347
+ # would re-introduce the bug undetectably. createDistillWorkspace has
348
+ # always populated startSha and cleanupStaleWorktrees evicts pre-
349
+ # c5e6fea worktrees within 60min, so reaching here without startSha
350
+ # means an out-of-tree caller or a meta.json contract violation.
351
+ if [ -z "$START_SHA" ]; then
352
+ log_error "meta.json missing startSha; refusing to proceed (worktree from incompatible pi-napkin version?)"
353
+ exit 1
354
+ fi
355
+
356
+ # Testing hook: halt right after the meta-pid rewrite so integration tests
357
+ # can inspect the updated meta.json before the cleanup trap removes the
358
+ # worktree. Clears the EXIT trap so cleanup is skipped.
359
+ if [ "${NAPKIN_DISTILL_HALT_AFTER_META:-}" = "1" ]; then
360
+ trap - EXIT
361
+ exit 0
362
+ fi
363
+
364
+ # --- Install per-distill napkin shim that auto-routes to the worktree -------
365
+ #
366
+ # Pi runs at PARENT_CWD (not the worktree) to keep the system prompt's
367
+ # `Current working directory:` line byte-identical to the parent's,
368
+ # preserving prompt-cache hits across the spawn boundary. That means
369
+ # napkin's cwd-based vault walk-up resolves to the *parent's* vault
370
+ # (typically the same one we want, but the writes need to land in the
371
+ # worktree's checkout for the squash-merge step to see them).
372
+ #
373
+ # The shim transparently injects `--vault $WORKTREE` into every napkin
374
+ # invocation from the agent's bash tool. The real napkin path is
375
+ # resolved here (via `command -v`) and baked in as an absolute path —
376
+ # so the shim, once invoked, doesn't depend on PATH lookup. PATH
377
+ # ordering is still required to ensure the agent's shell resolves
378
+ # `napkin` to THIS shim and not the global one: that's what the
379
+ # `export PATH="$SHIM_DIR:$PATH"` further down handles.
380
+ #
381
+ # Lives at `<worktree>/.napkin/distill/bin/napkin` so it's removed when
382
+ # the worktree is removed (no extra cleanup needed). The directory is
383
+ # already `.gitignore`d via the `.napkin/distill/` exclusion.
384
+ #
385
+ # Platform note: same bash dependency as the rest of this wrapper. The
386
+ # shim itself is a 3-line bash script; works wherever the wrapper does
387
+ # (Linux, macOS, WSL, Git Bash). Doesn't add a new platform constraint.
388
+ #
389
+ # CI / test note: when NAPKIN_DISTILL_SKIP_PI=1 the shim is skipped
390
+ # (no pi run → no napkin invocations to route). Lets the integration
391
+ # tests run in environments where napkin isn't installed (e.g. fresh
392
+ # CI runners). Production never sets SKIP_PI.
393
+ #
394
+ # See POST-R6-CACHE in features/pi-napkin-distill/deferred.md for the
395
+ # full design rationale.
396
+ if [ "${NAPKIN_DISTILL_SKIP_PI:-}" != "1" ]; then
397
+ SHIM_DIR="$WORKTREE/.napkin/distill/bin"
398
+ REAL_NAPKIN="$(command -v napkin || true)"
399
+ if [ -z "$REAL_NAPKIN" ]; then
400
+ # Include $PATH in the error log so the user can diagnose missing
401
+ # PATH entries (e.g. cron / systemd / launchd-launched pi with a
402
+ # stripped PATH) without further trial. The error log is vault-local
403
+ # and never leaves the user's machine.
404
+ log_error "napkin binary not found on wrapper PATH; cache-preserving shim cannot be installed"
405
+ log_error " PATH=$PATH"
406
+ exit 1
407
+ fi
408
+ # Refuse to install on top of another distill shim (recursion footgun:
409
+ # an inherited PATH from an aborted run could leave a stale shim ahead
410
+ # of the real napkin, and the new shim would exec the OLD shim, which
411
+ # exec's the real napkin with a stale --vault — multi-hop indirection
412
+ # at every napkin call). The pattern matches our own shim path layout.
413
+ case "$REAL_NAPKIN" in
414
+ */.napkin/distill/bin/napkin)
415
+ log_error "refusing to install shim — \`command -v napkin\` resolved to another distill shim ($REAL_NAPKIN); check PATH for a stale .napkin/distill/bin/ entry"
416
+ log_error " PATH=$PATH"
417
+ exit 1
418
+ ;;
419
+ esac
420
+ # Smoke-test that the resolved napkin actually executes. `command -v`
421
+ # only verifies PATH resolution; bun installs napkin as a symlink to
422
+ # `dist/main.js` with `#!/usr/bin/env node` shebang, which fails at
423
+ # exec time if `node` isn't on PATH. Catching that here surfaces a
424
+ # clean diagnostic instead of cryptic "node: not found" on every
425
+ # agent napkin call.
426
+ if ! "$REAL_NAPKIN" --version >/dev/null 2>&1; then
427
+ log_error "napkin not runnable on wrapper PATH (resolved to '$REAL_NAPKIN'); cache-preserving shim cannot be installed"
428
+ log_error " PATH=$PATH"
429
+ exit 1
430
+ fi
431
+ if ! mkdir -p "$SHIM_DIR"; then
432
+ log_error "failed to mkdir shim dir: $SHIM_DIR"
433
+ exit 1
434
+ fi
435
+ # Generate the shim with `printf %q` so $REAL_NAPKIN and $WORKTREE are
436
+ # shell-escaped at install time. This is escape-safe: any `"`, `\`,
437
+ # `$`, or backtick in either path is quoted so the resulting shim is
438
+ # always well-formed. Plain heredoc-with-interpolation (used
439
+ # previously) was a latent injection surface — see R7-SC-2 / R7-CI-4
440
+ # in features/pi-napkin-distill/pr-11/reviews/.
441
+ if ! {
442
+ printf '#!/usr/bin/env bash\n'
443
+ printf '# Auto-generated distill napkin shim. Routes every napkin command\n'
444
+ printf '# to the distill worktree so vault writes from the agent'\''s bash\n'
445
+ printf '# tool land inside the worktree even though pi'\''s cwd is the\n'
446
+ printf '# parent session'\''s cwd (set that way to preserve prompt-cache\n'
447
+ printf '# hits). Removed when the worktree is removed.\n'
448
+ printf 'exec %q --vault %q "$@"\n' "$REAL_NAPKIN" "$WORKTREE"
449
+ } > "$SHIM_DIR/napkin"; then
450
+ log_error "failed to write shim to $SHIM_DIR/napkin"
451
+ exit 1
452
+ fi
453
+ if ! chmod +x "$SHIM_DIR/napkin"; then
454
+ log_error "failed to chmod +x shim: $SHIM_DIR/napkin"
455
+ exit 1
456
+ fi
457
+ export PATH="$SHIM_DIR:$PATH"
458
+ fi
459
+
460
+ # Testing hook: halt right after the shim install so tests can inspect the
461
+ # shim file without the cleanup trap wiping the worktree. Clears the EXIT
462
+ # trap so cleanup is skipped — caller is responsible for tearing down the
463
+ # worktree afterward.
464
+ if [ "${NAPKIN_DISTILL_HALT_AFTER_SHIM:-}" = "1" ]; then
465
+ trap - EXIT
466
+ exit 0
467
+ fi
468
+
469
+ # Testing hook: trigger the cleanup trap from a controlled exit point
470
+ # so tests can drive the actual rm-rf fallback (POST-CONV-3) and rmdir
471
+ # parent (POST-CONV-4) paths through the wrapper instead of
472
+ # reproducing them in inline bash. Unlike HALT_AFTER_META and
473
+ # HALT_AFTER_SHIM, this hook does NOT clear the EXIT trap — cleanup
474
+ # fires normally and the test asserts on the post-cleanup state.
475
+ # Placement is post-shim-install so the worktree has gitignored
476
+ # content (.napkin/distill/bin/napkin shim) that survives
477
+ # `git worktree remove --force`, exercising the rm-rf fallback.
478
+ #
479
+ # Emit a distinguishable diagnostic so tests can verify the wrapper
480
+ # exited from THIS hook, not from the napkin-not-found / node-not-found
481
+ # / meta-missing-startSha paths above (R13-CC-1: the previous test
482
+ # was passing for the wrong reason — PATH stripped of napkin made
483
+ # the wrapper exit at the shim-install block before ever reaching
484
+ # this hook).
485
+ if [ "${NAPKIN_DISTILL_FORCE_CLEANUP:-}" = "1" ]; then
486
+ log_error "FORCE_CLEANUP hook fired post-shim-install (test hook); triggering cleanup trap"
487
+ exit 1
488
+ fi
489
+
490
+ # --- Step 1: run pi at PARENT_CWD (cache parity) -----------------------------
491
+ #
492
+ # pi reads its session-fork header to determine cwd for the system
493
+ # prompt and tools. createDistillWorkspace forked the session with
494
+ # `targetCwd = PARENT_CWD` precisely so this matches. Spawning pi here
495
+ # at PARENT_CWD also makes process.cwd() consistent with the header,
496
+ # which avoids `MissingSessionCwdError` if pi ever validates that.
497
+
498
+ cd "$PARENT_CWD" || { log_error "cd parent cwd failed: $PARENT_CWD"; exit 1; }
499
+
500
+ if [ "${NAPKIN_DISTILL_SKIP_PI:-}" != "1" ]; then
501
+ PI_BIN="${NAPKIN_DISTILL_PI_BIN:-pi}"
502
+ pi_args=(--session "$SESSION_FORK")
503
+ if [ -n "$MODEL" ]; then
504
+ pi_args+=(--model "$MODEL")
505
+ fi
506
+ pi_args+=(-p "$PROMPT")
507
+ # Capture pi's stderr into the error log on non-zero exit. stdout is
508
+ # discarded — pi's subagent chatter isn't useful forensically.
509
+ pi_stderr="$(mktemp)"
510
+ if ! NAPKIN_DISTILL_NO_RECURSE=1 "$PI_BIN" "${pi_args[@]}" > /dev/null 2> "$pi_stderr"; then
511
+ log_error "pi subprocess failed (exit $?); stderr follows:"
512
+ cat "$pi_stderr" >> "$ERROR_LOG" 2>/dev/null || true
513
+ rm -f "$pi_stderr"
514
+ record_dangling_sha
515
+ exit 1
516
+ fi
517
+ rm -f "$pi_stderr"
518
+ fi
519
+
520
+ # --- Step 2: commit distill's changes on the distill branch. ---------------
521
+ #
522
+ # The vault's `.gitignore` (installed by extensions/distill/auto-setup.ts)
523
+ # already excludes `.napkin/distill/`, so a plain `git add -A` will not
524
+ # sweep in our per-worktree session fork or meta.json. Worktrees
525
+ # themselves live OUTSIDE the vault (under `$XDG_CACHE_HOME/napkin-distill/`),
526
+ # so there are no sibling worktree paths to exclude.
527
+
528
+ git -C "$WORKTREE" add -A
529
+ # Detect whether pi produced any content. `git diff --quiet $START_SHA`
530
+ # compares the worktree's full state (committed by pi itself + staged)
531
+ # against the branch's starting commit, so it correctly handles BOTH
532
+ # cases: (a) pi staged but did not commit (legacy expected behaviour),
533
+ # and (b) pi's bash tool ran `git commit` itself (the worktree is
534
+ # clean post-`add -A` because pi already advanced HEAD). The previous
535
+ # `git diff --cached --quiet` reported false-no-op for case (b),
536
+ # silently dropping the distill commit when the cleanup trap force-
537
+ # deleted the branch (POST-CONV-1; real failure: dropped commit
538
+ # `a13e8b1`). startSha is now load-bearing — the legacy --cached
539
+ # fallback was deleted to prevent silent regression.
540
+ if git -C "$WORKTREE" diff --quiet "$START_SHA"; then
541
+ # Genuinely no-op — pi explicitly produced nothing. Skip straight
542
+ # to cleanup and signal `no-content` to the JS-side poller.
543
+ write_outcome "no-content"
544
+ exit 0
545
+ fi
546
+
547
+ # Commit any staged changes. If pi already committed itself, there's
548
+ # nothing left staged — skip the commit step and let the squash phase
549
+ # pick up pi's existing commit(s).
550
+ if ! git -C "$WORKTREE" diff --cached --quiet; then
551
+ if ! git_retry git -C "$WORKTREE" commit -m "distill: auto-distill content" > /dev/null 2>&1; then
552
+ log_error "git commit failed on distill branch"
553
+ record_dangling_sha
554
+ exit 1
555
+ fi
556
+ fi
557
+
558
+ # --- Step 3: merge main into distill. LLM driver handles *.md conflicts. ---
559
+
560
+ # Merge may return non-zero when conflicts remain after the driver 3-strikes
561
+ # on some files; exit 1 is the expected "conflicts remain, salvage below".
562
+ # Any other non-zero exit code (128 for corrupt index, 129+ for option
563
+ # errors, etc.) indicates a REAL failure that salvage can't recover from
564
+ # — log forensic info and bail out.
565
+ #
566
+ # We deliberately do NOT wrap this in git_retry: retrying after a partial
567
+ # conflict leaves git with "you have unmerged files" and the second attempt
568
+ # returns 128 (false positive for our unexpected-failure branch).
569
+ # Transient index.lock contention on this single call isn't a real
570
+ # concern — we're the only writer on the distill branch.
571
+ merge_rc=0
572
+ git -C "$WORKTREE" merge --no-edit "$DEFAULT_BRANCH" > /dev/null 2>&1 || merge_rc=$?
573
+ # Testing hook: override the captured merge rc so tests can cover the
574
+ # unexpected-exit-code branch (128 etc.) without having to contrive a
575
+ # real git failure of that shape.
576
+ if [ -n "${NAPKIN_DISTILL_FORCE_MERGE_RC:-}" ]; then
577
+ merge_rc="$NAPKIN_DISTILL_FORCE_MERGE_RC"
578
+ fi
579
+ case "$merge_rc" in
580
+ 0)
581
+ # Clean merge — driver handled every conflict, no salvage needed.
582
+ ;;
583
+ 1)
584
+ # Conflicts remain after driver 3-strike. Proceed to salvage below.
585
+ ;;
586
+ *)
587
+ log_error "git merge $DEFAULT_BRANCH failed unexpectedly (exit $merge_rc) — aborting"
588
+ record_dangling_sha
589
+ # Leave the merge in progress for forensic inspection; cleanup trap
590
+ # will wipe the worktree. Do NOT attempt salvage — the failure mode
591
+ # is unknown.
592
+ exit 1
593
+ ;;
594
+ esac
595
+
596
+ # Partial-merge salvage: any file still marked unmerged (driver gave up) gets
597
+ # reverted to main's version. This preserves the clean distill content while
598
+ # discarding files we couldn't resolve. Each discarded file is logged to the
599
+ # partial-merge log (forensic-only — distinct from the fatal-error log so
600
+ # the JS-side runner doesn't surface a salvage success as a UI failure;
601
+ # R8-CC-1).
602
+ UNMERGED="$(git -C "$WORKTREE" diff --name-only --diff-filter=U 2>/dev/null || true)"
603
+ if [ -n "$UNMERGED" ]; then
604
+ PARTIAL_MERGE_OCCURRED=1
605
+ while IFS= read -r f; do
606
+ [ -z "$f" ] && continue
607
+ log_partial_merge "reverted '$f' to $DEFAULT_BRANCH's version (LLM driver 3-strike)"
608
+ git -C "$WORKTREE" checkout "$DEFAULT_BRANCH" -- "$f" > /dev/null 2>&1 || \
609
+ log_partial_merge " failed to checkout $DEFAULT_BRANCH:$f"
610
+ git -C "$WORKTREE" add -- "$f" > /dev/null 2>&1 || true
611
+ done <<< "$UNMERGED"
612
+ # Complete the merge commit with whatever's now staged. --no-edit reuses
613
+ # the merge message git prepared (even with conflicts it has one drafted).
614
+ if ! git_retry git -C "$WORKTREE" commit --no-edit > /dev/null 2>&1; then
615
+ log_error "failed to complete partial-merge commit"
616
+ record_dangling_sha
617
+ exit 1
618
+ fi
619
+ fi
620
+
621
+ # Testing hook: force a MERGE_HEAD file to exist so the escape-hatch check
622
+ # below fires. Lets tests cover the path without relying on a race between
623
+ # git's merge logic and the driver's output (which real-world tests can't
624
+ # reliably stage — git clears MERGE_HEAD on driver exit 0).
625
+ if [ "${NAPKIN_DISTILL_FORCE_MERGE_HEAD:-}" = "1" ]; then
626
+ _gitdir="$(git -C "$WORKTREE" rev-parse --git-dir 2>/dev/null || true)"
627
+ if [ -n "$_gitdir" ]; then
628
+ echo "deadbeefcafebabe" > "$_gitdir/MERGE_HEAD"
629
+ fi
630
+ fi
631
+
632
+ # Re-check: if MERGE_HEAD is still present the merge never completed
633
+ # (e.g. driver wrote output that still contains markers). Bail — the caller's
634
+ # squash below would silently lose content.
635
+ if [ -f "$WORKTREE/.git/MERGE_HEAD" ] || \
636
+ [ -f "$(git -C "$WORKTREE" rev-parse --git-dir)/MERGE_HEAD" ]; then
637
+ log_error "merge did not complete (MERGE_HEAD still present)"
638
+ record_dangling_sha
639
+ exit 1
640
+ fi
641
+
642
+ # --- Step 4: squash distill into $DEFAULT_BRANCH from the main vault. ------
643
+
644
+ cd "$VAULT" || { log_error "cd vault failed"; exit 1; }
645
+
646
+ # Defensive: refuse to squash if the vault's HEAD isn't on the default branch.
647
+ # `git merge --squash <branch>` stages changes onto whatever is checked out;
648
+ # if the user has a feature branch in the main vault while auto-distill
649
+ # fires, the squash would corrupt that branch's history with distill commits.
650
+ # The spec's "Main history stays linear" invariant assumes HEAD == main.
651
+ VAULT_HEAD="$(git symbolic-ref --short HEAD 2>/dev/null || true)"
652
+ if [ -n "$VAULT_HEAD" ] && [ "$VAULT_HEAD" != "$DEFAULT_BRANCH" ]; then
653
+ log_error "vault HEAD is '$VAULT_HEAD', expected '$DEFAULT_BRANCH' — refusing to squash-merge distill into the wrong branch"
654
+ record_dangling_sha
655
+ exit 1
656
+ fi
657
+
658
+ if ! git_retry git merge --squash "$BRANCH" > /dev/null 2>&1; then
659
+ log_error "git merge --squash failed"
660
+ record_dangling_sha
661
+ exit 1
662
+ fi
663
+
664
+ # Squash may result in no staged changes (e.g. distill's changes were already
665
+ # in main — unlikely in practice but possible with concurrent distills that
666
+ # took the same content). Skip the commit if so.
667
+ if git diff --cached --quiet; then
668
+ # Squash produced nothing for main — user-facing this is no-content
669
+ # (no new lines on main). Salvage state is irrelevant here: even if
670
+ # the inner merge salvaged some files, none of the distill content
671
+ # made it to main this round.
672
+ write_outcome "no-content"
673
+ exit 0
674
+ fi
675
+
676
+ SQUASH_MSG="distill: merge ${BRANCH_SHORT}"
677
+ if ! git_retry git commit -m "$SQUASH_MSG" > /dev/null 2>&1; then
678
+ log_error "git commit failed on main after squash"
679
+ record_dangling_sha
680
+ exit 1
681
+ fi
682
+
683
+ # Success — the trap cleans up on exit 0. Outcome class depends on
684
+ # whether the inner merge had to salvage files: a clean merge is
685
+ # `merged-content`; a salvage that still landed something on main is
686
+ # `partial-merge` (the user must know N files reverted to main).
687
+ if [ "$PARTIAL_MERGE_OCCURRED" -eq 1 ]; then
688
+ write_outcome "partial-merge"
689
+ else
690
+ write_outcome "merged-content"
691
+ fi
692
+ exit 0