@cad0p/pi-napkin 0.2.4 → 0.3.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.
@@ -2,52 +2,103 @@
2
2
  # distill-wrapper — orchestrates a single auto-distill attempt inside a
3
3
  # per-distill git worktree.
4
4
  #
5
+ # PR #12 architecture: the distill AGENT owns distill content production
6
+ # AND the integration phases (merge, squash, push, cleanup). The wrapper
7
+ # is a thin shell:
8
+ # 1. Worktree setup is already done by createDistillWorkspace before
9
+ # this script runs (git worktree add, session fork, meta.json).
10
+ # 2. Wrapper installs the napkin shim (POST-R6-CACHE), cds to PARENT_CWD
11
+ # for cache parity, then invokes `pi --session ... -p $PROMPT` ONCE
12
+ # under a hard `timeout(1)` budget.
13
+ # 3. Agent executes the full agent-driven prompt (extensions/distill/
14
+ # distill-prompt.md): distill content + git merge + git merge --squash
15
+ # + git push + git worktree remove + git branch -D.
16
+ # 4. Post-agent-exit, wrapper validates the agent's output (markers
17
+ # absent, HEAD on default, commit count) and salvages on failure.
18
+ # 5. Wrapper writes the outcome sidecar and exits.
19
+ #
20
+ # Implementation history: validation (A3) and salvage (A4) landed in
21
+ # commits afed6ae and 0d0a262 respectively. The numbered lifecycle
22
+ # below reflects the current shape; see git log for the staged
23
+ # rollout.
24
+ #
5
25
  # Usage:
6
- # distill-wrapper.sh <vault> <worktree> <branch> <sessionFork> <prompt> <errorDir> [<model>] [<defaultBranch>] [<parentCwd>]
26
+ # distill-wrapper.sh <vault> <worktree> <branch> <sessionFork> <prompt> <errorDir> [<model>] [<defaultBranch>] [<parentCwd>] [<maxDurationSecs>] [<expectedCacheRoot>]
7
27
  #
8
28
  # 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):
29
+ # <vault> absolute path to the main vault (NOT the worktree)
30
+ # <worktree> absolute path to the distill worktree (lives under
31
+ # `$XDG_CACHE_HOME/napkin-distill/<vault-hash>/<suffix>/`;
32
+ # see `resolveCacheRoot` in extensions/distill/distill-workspace.ts)
33
+ # <branch> distill branch name (`distill/<hex>-<epoch>`)
34
+ # <sessionFork> absolute path to the forked session .jsonl inside the worktree
35
+ # <prompt> resolved agent-driven distill prompt (steps 1–10 with
36
+ # placeholders already substituted by `buildDistillPrompt`)
37
+ # <errorDir> absolute path to `<vault.configPath>/distill/errors/`
38
+ # <model> optional "<provider>/<id>" to pass to `pi --model`
39
+ # <defaultBranch> optional name of the vault's mainline branch (e.g. `main`,
40
+ # `master`). When empty/absent, defaults to `main`. The JS
41
+ # side resolves this via `git symbolic-ref refs/remotes/origin/HEAD`
42
+ # or a HEAD-ref lookup so the wrapper doesn't hardcode `main`.
43
+ # <parentCwd> REQUIRED. Absolute path of the parent pi session's cwd.
44
+ # Pi is spawned at this cwd so the system prompt's
45
+ # `Current working directory:` line is byte-identical
46
+ # to the parent's, preserving prompt-cache hits. Vault
47
+ # writes are still routed to the worktree via the
48
+ # napkin shim installed at
49
+ # `<worktree>/.napkin/distill/bin/napkin`. The wrapper
50
+ # hard-fails if this is empty (R7-PERF-7, R7-CI-6) —
51
+ # silently falling back to <worktree> would re-
52
+ # introduce the cache regression POST-R6-CACHE fixed.
53
+ # <maxDurationSecs> hard wall-clock budget for the agent task, in
54
+ # seconds. Wired into `timeout(1)` so the agent is
55
+ # SIGTERMed (then SIGKILLed after grace) on overrun.
56
+ # Required: the wrapper hard-fails at startup if
57
+ # absent or empty. Derived from
58
+ # `distill.maxDurationMinutes` config; the JS side's
59
+ # `getMaxDistillDurationMs` (extensions/distill/index.ts)
60
+ # is the single source of truth for the production default.
61
+ # <expectedCacheRoot> Absolute path to the resolved XDG cache root
62
+ # (`<XDG_CACHE_HOME or ~/.cache>/napkin-distill/<vault-hash>`)
63
+ # that contains <worktree>. Used by safe_rm_worktree
64
+ # to require any path it `rm -rf`s to be a descendant
65
+ # of THIS root, not just any path containing a
66
+ # `/napkin-distill/<x>/<y>/` segment (SEC-2 / CORR-3).
67
+ # Computed JS-side by `resolveCacheRoot()` in
68
+ # `extensions/distill/distill-workspace.ts` (the same
69
+ # function that built <worktree>'s parent dir), so the
70
+ # two sides stay in sync. Required: the wrapper hard-fails
71
+ # at startup if absent or empty.
72
+ #
73
+ # Lifecycle (happy path, PR #12):
34
74
  # 1. install napkin shim at <worktree>/.napkin/distill/bin/napkin and
35
75
  # prepend it to PATH (auto-routes agent napkin calls to the worktree)
36
76
  # 2. cd <parentCwd> (cache parity — keeps pi's
37
77
  # system prompt cwd line
38
78
  # 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)
79
+ # 3. timeout <maxDurationSecs> pi --session <sessionFork> -p <prompt>
80
+ # (single agent task: produces
81
+ # content, runs git merge into
82
+ # distill branch, squashes to
83
+ # main, pushes if origin, cleans
84
+ # up worktree+branch — see
85
+ # extensions/distill/distill-prompt.md)
86
+ # 4. validate agent output (markers, HEAD on default,
87
+ # commit count; see
88
+ # validate_no_markers /
89
+ # validate_head_on_default /
90
+ # validate_commit_count below)
91
+ # 5. salvage if validation fails (force-cleanup worktree+
92
+ # branch + write
93
+ # `failed:<reason>` outcome
94
+ # with recovery hint; see
95
+ # salvage() below)
96
+ # 6. write outcome sidecar (`merged-content` on happy path;
97
+ # `merged-local` when local diverges
98
+ # from origin; `no-content` on 0
99
+ # commits since startSha; `failed:<reason>`
100
+ # on validation failure)
101
+ # 7. cleanup (trap): force-remove worktree, prune, force-delete branch
51
102
  #
52
103
  # Error handling:
53
104
  # Any fatal failure writes a log entry to:
@@ -57,15 +108,21 @@
57
108
  #
58
109
  # Environment:
59
110
  # 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
111
  #
63
112
  # 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.
113
+ # NAPKIN_DISTILL_PI_BIN path to a stub `pi` binary (integration tests).
114
+ # The agent-driven design means tests that want
115
+ # to simulate specific outcomes (clean-distill,
116
+ # conflict-leave-markers, agent-timeout, …) do
117
+ # so via a stub pi that produces the right
118
+ # filesystem effects on each invocation.
119
+ # NAPKIN_DISTILL_SKIP_PI=1 skip the agent invocation entirely. Tests
120
+ # that pre-stage filesystem state directly use
121
+ # this hook; the wrapper proceeds straight to
122
+ # outcome write. NOTE: at A2 the wrapper still
123
+ # writes `merged-content` unconditionally on
124
+ # this path — A3 wires real validation that
125
+ # fires on the SKIP_PI path too.
69
126
  # NAPKIN_DISTILL_HALT_AFTER_META=1
70
127
  # halt right after rewriting meta.json's pid to
71
128
  # the wrapper's pid — lets tests inspect the
@@ -83,24 +140,46 @@
83
140
  # the EXIT trap — the cleanup function
84
141
  # fires and tests assert on its post-state
85
142
  # (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.
143
+ # NAPKIN_DISTILL_TIMEOUT_KILL_GRACE_SECS=<n>
144
+ # override TIMEOUT_KILL_GRACE_SECS (the
145
+ # seconds the SIGTERM→SIGKILL escalation
146
+ # waits before killing a stuck agent).
147
+ # Production default is 30s; tests assert
148
+ # escalation against SIGTERM-ignoring stubs
149
+ # with a short grace so the assertion
150
+ # completes within the outer test timeout.
97
151
 
98
152
  set -uo pipefail
99
153
 
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"
154
+ # coreutils timeout(1) is required for the agent task's hard wall-clock
155
+ # budget. macOS without `brew install coreutils` doesn't ship `timeout`
156
+ # at all; Homebrew installs it as `gtimeout` by default. Detect both
157
+ # names and prefer whichever is present so the wrapper works on Linux
158
+ # (`timeout`) and stock macOS-with-Homebrew-coreutils (`gtimeout`)
159
+ # without further configuration. Fail fast with an actionable error if
160
+ # neither is on PATH — silently routing through the no-timeout path
161
+ # would let a misbehaving agent leak the wrapper indefinitely
162
+ # (CI-A-1, CLEAN-A-1, SEC-A-3).
163
+ TIMEOUT_BIN="$(command -v timeout || command -v gtimeout || true)"
164
+ if [ -z "$TIMEOUT_BIN" ]; then
165
+ echo "distill-wrapper: GNU coreutils timeout(1) not found on PATH (looked for 'timeout' and 'gtimeout'). Install coreutils (e.g. \`brew install coreutils\` on macOS) and re-run." >&2
166
+ exit 2
167
+ fi
168
+
169
+ # SIGKILL escalation grace period: after timeout(1) sends SIGTERM at
170
+ # the budget boundary, wait this many seconds before escalating to
171
+ # SIGKILL. Without `-k` on the timeout invocation, escalation never
172
+ # happens — a SIGTERM-ignoring agent (a stuck-in-libc-syscall pi
173
+ # process, a tool subprocess that traps SIGTERM, OOM-killing-deadlock)
174
+ # would hang the wrapper indefinitely. 30s is comfortably longer than
175
+ # typical SIGTERM-handler shutdown paths and short enough that a
176
+ # stuck distill clears within ~30s+budget total. Per the methodology
177
+ # guide's never-deferrable magic-number rule.
178
+ #
179
+ # Tests can override via NAPKIN_DISTILL_TIMEOUT_KILL_GRACE_SECS so a
180
+ # SIGTERM-ignoring stub assertion completes within the test timeout
181
+ # budget without waiting the full 30s grace.
182
+ TIMEOUT_KILL_GRACE_SECS="${NAPKIN_DISTILL_TIMEOUT_KILL_GRACE_SECS:-30}"
104
183
 
105
184
  VAULT="${1:-}"
106
185
  WORKTREE="${2:-}"
@@ -111,6 +190,15 @@ ERROR_DIR="${6:-}"
111
190
  MODEL="${7:-}"
112
191
  DEFAULT_BRANCH="${8:-main}"
113
192
  PARENT_CWD="${9:-}"
193
+ # Required: the wrapper hard-fails at startup if absent or empty. The
194
+ # production default (10 minutes) lives JS-side in
195
+ # `getMaxDistillDurationMs` (extensions/distill/index.ts) so there's a
196
+ # single source of truth for the default; duplicating it here would be
197
+ # drift waiting to happen.
198
+ MAX_DURATION_SECS="${10:-}"
199
+ # SEC-2 / CORR-3: explicit cache root the worktree must live under.
200
+ # Required: validated below after the lower-numbered positional args.
201
+ EXPECTED_CACHE_ROOT="${11:-}"
114
202
  # Treat empty string as "use fallback", not "literal empty branch name".
115
203
  if [ -z "$DEFAULT_BRANCH" ]; then
116
204
  DEFAULT_BRANCH="main"
@@ -126,6 +214,23 @@ if [ -z "$PARENT_CWD" ]; then
126
214
  echo "distill-wrapper: missing required argument 9 (parentCwd) — cache-preserving spawn requires the parent pi session's cwd" >&2
127
215
  exit 2
128
216
  fi
217
+ # maxDurationSecs (arg 10) required: timeout(1) needs an explicit
218
+ # wall-clock budget. The JS side always passes
219
+ # Math.round(getMaxDistillDurationMs(config) / 1000); silently falling
220
+ # back to a hardcoded default would let two sources of truth drift.
221
+ if [ -z "$MAX_DURATION_SECS" ]; then
222
+ echo "distill-wrapper: missing required argument 10 (maxDurationSecs) — timeout(1) wall-clock budget is mandatory; JS side derives it from distill.maxDurationMinutes config" >&2
223
+ exit 2
224
+ fi
225
+ # expectedCacheRoot (arg 11) required: safe_rm_worktree's descendant
226
+ # check requires it; the JS side always passes resolveCacheRoot(vault)
227
+ # (the same function that built <worktree>'s parent dir). Validated
228
+ # AFTER parentCwd so positional-order error reporting matches arg
229
+ # numbering.
230
+ if [ -z "$EXPECTED_CACHE_ROOT" ]; then
231
+ echo "distill-wrapper: missing required argument 11 (expectedCacheRoot) — safe_rm_worktree's descendant check requires the resolved XDG cache root" >&2
232
+ exit 2
233
+ fi
129
234
 
130
235
  if [ -z "$VAULT" ] || [ -z "$WORKTREE" ] || [ -z "$BRANCH" ] || \
131
236
  [ -z "$SESSION_FORK" ] || [ -z "$PROMPT" ] || [ -z "$ERROR_DIR" ]; then
@@ -133,33 +238,50 @@ if [ -z "$VAULT" ] || [ -z "$WORKTREE" ] || [ -z "$BRANCH" ] || \
133
238
  exit 2
134
239
  fi
135
240
 
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/.
241
+ # Validate maxDurationSecs is a positive integer. timeout(1) accepts
242
+ # decimal seconds and unit suffixes (`30s`, `5m`, `1h`); we restrict
243
+ # to integer seconds for predictability and to surface contract drift
244
+ # loud and early.
245
+ case "$MAX_DURATION_SECS" in
246
+ ''|*[!0-9]*)
247
+ echo "distill-wrapper: maxDurationSecs (arg 10) must be a positive integer (got '$MAX_DURATION_SECS')" >&2
248
+ exit 2
249
+ ;;
250
+ esac
251
+ if [ "$MAX_DURATION_SECS" -le 0 ]; then
252
+ echo "distill-wrapper: maxDurationSecs (arg 10) must be > 0 (got '$MAX_DURATION_SECS')" >&2
253
+ exit 2
254
+ fi
255
+
256
+ # Export so any subprocess (the agent's bash tool, downstream pi
257
+ # subprocesses) inherits the error dir for forensic logging.
142
258
  export NAPKIN_DISTILL_ERROR_DIR="$ERROR_DIR"
143
259
 
260
+ # Defense-in-depth for CLEAN-11: the agent's `git -C {{worktreePath}}
261
+ # merge --no-edit {{defaultBranch}}` step would, without `--no-edit`,
262
+ # open `core.editor` on a clean auto-merge — the agent's bash tool
263
+ # has no TTY, so the editor would hang or fail. The prompt now passes
264
+ # `--no-edit`, but a future prompt revision (or an agent that crafts
265
+ # a `git pull` / `git revert` / `git commit -a` of its own) could
266
+ # still trip the same trap. `GIT_TERMINAL_PROMPT=0` makes git fail
267
+ # fast on credential prompts (push to a private origin without
268
+ # cached creds, etc.) instead of waiting for tty input. `GIT_EDITOR=true`
269
+ # substitutes a no-op for any editor invocation — git proceeds with
270
+ # whatever default message it composed instead of blocking on user
271
+ # input. Both apply to the wrapper, the agent's pi process, and any
272
+ # git subprocess launched from the agent's bash tool.
273
+ export GIT_TERMINAL_PROMPT=0
274
+ export GIT_EDITOR=true
275
+
144
276
  # Compute error log path. `branch-short-hash` is the portion after `distill/`
145
277
  # (already unique per invocation — hex nonce + epoch).
146
278
  BRANCH_SHORT="${BRANCH#distill/}"
147
279
  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.
280
+ # Single fatal-error log per branch. The agent owns merge resolution
281
+ # end-to-end so there's no per-attempt 3-strike forensic to capture.
282
+ # The presence of *.log is the JS-side signal that the wrapper failed
283
+ # (R7-SC-3 + R8-CC-1). Lazily created on first `log_error` call.
161
284
  ERROR_LOG="$ERROR_DIR/${TIMESTAMP}-$$-${BRANCH_SHORT}.log"
162
- PARTIAL_MERGE_LOG="$ERROR_DIR/${TIMESTAMP}-$$-${BRANCH_SHORT}.partial-merge.log"
163
285
  # Outcome sidecar (POST-CONV-5) — one-line classification of why the
164
286
  # wrapper exited 0. The detached wrapper's exit status is unobservable
165
287
  # to the parent (`stdio:ignore` + `unref()`); the filesystem is the
@@ -168,10 +290,17 @@ PARTIAL_MERGE_LOG="$ERROR_DIR/${TIMESTAMP}-$$-${BRANCH_SHORT}.partial-merge.log"
168
290
  # JS-side runDistillWith poller dispatches UI severity per outcome class.
169
291
  # See formatOutcomeNotification in extensions/distill/index.ts for the
170
292
  # 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).
293
+ # merged-content → info; no-content → warning; merged-local → warning;
294
+ # failed:<reason> → error.
173
295
  OUTCOME_PATH="$ERROR_DIR/${TIMESTAMP}-$$-${BRANCH_SHORT}.outcome"
174
296
 
297
+ # Pre-distill marker snapshot tmp file (CORR-1). Captured right before
298
+ # the agent runs (after START_SHA is recovered from meta.json) so the
299
+ # post-agent validate_no_markers can distinguish agent-induced markers
300
+ # from pre-existing ones. Empty string until the snapshot is
301
+ # captured. Cleaned up in the EXIT trap.
302
+ PRE_DISTILL_MARKER_FILES_FILE=""
303
+
175
304
  # Lazy-create error log on first write. Empty file is the "no error" signal.
176
305
  ERROR_LOG_TOUCHED=0
177
306
  log_error() {
@@ -191,33 +320,37 @@ log_error() {
191
320
  echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) $*" >> "$ERROR_LOG"
192
321
  }
193
322
 
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
323
+ # Soft-warning entries are written to a separate `.warning.log` file
324
+ # (distinct from `.log` which is the fatal-error signal the JS-side
325
+ # `findDistillErrorLogForBranch` picks up). Used for observed-but-
326
+ # accepted invariant breaches the wrapper does NOT escalate to a
327
+ # `failed:*` outcome (e.g. agent committed multiple times to default
328
+ # without squashing — design.md "Mocked-pi behaviors" #6: accepted
329
+ # as `merged-content` but the squash-invariant is documented and
330
+ # worth logging for forensic clarity).
331
+ #
332
+ # Naming convention follows `<base>.warning.log`:
333
+ # `findDistillErrorLogForBranch` matches only the suffix
334
+ # `-<branchShort>.log`, so any sibling forensic file with a longer
335
+ # pre-`.log` suffix (e.g. `<base>.warning.log`) is naturally excluded
336
+ # from the JS-side fatal-failure poller.
337
+ WARNING_LOG="$ERROR_DIR/${TIMESTAMP}-$$-${BRANCH_SHORT}.warning.log"
338
+ WARNING_LOG_TOUCHED=0
339
+ log_warning() {
340
+ if [ "$WARNING_LOG_TOUCHED" -eq 0 ]; then
202
341
  mkdir -p "$ERROR_DIR"
203
342
  {
204
- echo "# napkin distill partial-merge salvage log"
343
+ echo "# napkin distill warning log"
205
344
  echo "branch: $BRANCH"
206
345
  echo "vault: $VAULT"
207
346
  echo "worktree: $WORKTREE"
208
347
  echo "started: $TIMESTAMP"
209
348
  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
349
  echo
217
- } >> "$PARTIAL_MERGE_LOG"
218
- PARTIAL_MERGE_LOG_TOUCHED=1
350
+ } >> "$WARNING_LOG"
351
+ WARNING_LOG_TOUCHED=1
219
352
  fi
220
- echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) $*" >> "$PARTIAL_MERGE_LOG"
353
+ echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) WARNING: $*" >> "$WARNING_LOG"
221
354
  }
222
355
 
223
356
  # Capture the dangling commit SHA for forensic recovery (git gc grace period
@@ -232,25 +365,599 @@ record_dangling_sha() {
232
365
  fi
233
366
  }
234
367
 
235
- # Write the outcome sidecar (POST-CONV-5). One line, one class string.
368
+ # Write the outcome sidecar (POST-CONV-5). The first line is the
369
+ # outcome class (one-token, machine-readable); subsequent lines
370
+ # (optional) are a human-readable recovery hint.
371
+ #
236
372
  # Caller must invoke this immediately before any successful `exit 0`
237
- # path. Idempotent: a double call would just rewrite the same file.
373
+ # OR `exit 1` path. Idempotent: a double call rewrites the same file.
374
+ #
375
+ # JS-side parser (`findDistillOutcomeForBranch`) reads the first line
376
+ # as the outcome class for severity dispatch and exposes the remaining
377
+ # lines as a `recoveryHint?: string` for inclusion in the failure
378
+ # notification.
379
+ #
380
+ # Recovery hint is OPTIONAL because the happy-path classes
381
+ # (`merged-content`, `merged-local`, `no-content`) need no recovery
382
+ # action — only the `failed:<reason>` classes do.
383
+ #
384
+ # Atomicity (SEC-A-4): write to `<sidecar>.tmp` then `mv` to the final
385
+ # path. POSIX `rename(2)` is atomic on the same filesystem, so the
386
+ # JS-side poller (`findDistillOutcomeForBranch`) either sees the file
387
+ # absent or sees the complete contents — never a partial write where
388
+ # line 1 is present but line 2 (recovery hint) hasn't landed yet.
389
+ # Without this guard, the multi-line write path (two `printf`s into
390
+ # the same redirect) could race a poller that opens between the
391
+ # kernel's write of line 1 and line 2 and misclassify a failed
392
+ # distill as having no recovery hint.
238
393
  write_outcome() {
239
394
  local class="$1"
395
+ local recovery_hint="${2:-}"
240
396
  mkdir -p "$ERROR_DIR" 2>/dev/null || true
241
- printf '%s\n' "$class" > "$OUTCOME_PATH" 2>/dev/null || true
397
+ local tmp="$OUTCOME_PATH.tmp"
398
+ if [ -n "$recovery_hint" ]; then
399
+ printf '%s\n%s\n' "$class" "$recovery_hint" > "$tmp" 2>/dev/null || {
400
+ rm -f "$tmp" 2>/dev/null || true
401
+ return 0
402
+ }
403
+ else
404
+ printf '%s\n' "$class" > "$tmp" 2>/dev/null || {
405
+ rm -f "$tmp" 2>/dev/null || true
406
+ return 0
407
+ }
408
+ fi
409
+ mv "$tmp" "$OUTCOME_PATH" 2>/dev/null || {
410
+ rm -f "$tmp" 2>/dev/null || true
411
+ return 0
412
+ }
413
+ }
414
+
415
+ # safe_rm_worktree <worktree_path> <expected_cache_root>
416
+ #
417
+ # Defense-in-depth path-safety guard before `rm -rf <worktree>`. The
418
+ # wrapper's primary defense is JS-side construction: `resolveCacheRoot`
419
+ # in distill-workspace.ts always builds worktrees under
420
+ # `<XDG_CACHE_HOME or ~/.cache>/napkin-distill/<vault-hash>/<branch-suffix>/`,
421
+ # and `git worktree remove --force <path>` refuses paths not registered
422
+ # as worktrees of the vault. But if either control failed (upstream
423
+ # refactor bug, malformed test fixture, future code path that passes
424
+ # a different path through), the bare `rm -rf "$worktree"` after
425
+ # `worktree remove` would run on whatever path was passed in —
426
+ # `rm -rf /etc` if the upstream was that broken (SEC-A-2).
427
+ #
428
+ # This guard adds the wrapper-side check: the worktree's canonical
429
+ # path must be a descendant of `<expected_cache_root>` (SEC-2 / CORR-3).
430
+ # A bug elsewhere that constructed a path like
431
+ # `/some/random/dir/napkin-distill/foo/bar` cannot bypass this check —
432
+ # even though it contains the napkin-distill segment, it isn't under
433
+ # the resolved root.
434
+ #
435
+ # `pwd -P` resolves symlinks (and is portable across BSD/GNU,
436
+ # unlike `readlink -f` which is GNU-only).
437
+ #
438
+ # Returns 0 on successful removal (or already-removed). Returns 1
439
+ # when the path didn't pass the safety guard — caller must log and
440
+ # proceed, never abort: salvage's contract is best-effort cleanup,
441
+ # and the outcome-write path matters more than perfectly cleaning up
442
+ # a malformed worktree path.
443
+ safe_rm_worktree() {
444
+ local worktree="$1"
445
+ local expected_cache_root="$2"
446
+ if [ -z "$worktree" ]; then
447
+ log_error "safe_rm_worktree: empty worktree path; refusing to rm-rf"
448
+ return 1
449
+ fi
450
+ if [ ! -d "$worktree" ]; then
451
+ # Already gone — nothing to do.
452
+ return 0
453
+ fi
454
+ # Canonicalise to defeat symlink/relative-path tricks. `pwd -P`
455
+ # yields the absolute physical path of the cwd; cd'ing into the
456
+ # worktree first means we get its physical path even if the input
457
+ # was a symlink.
458
+ local resolved
459
+ resolved="$(cd "$worktree" 2>/dev/null && pwd -P)" || resolved=""
460
+ if [ -z "$resolved" ]; then
461
+ log_error "safe_rm_worktree: could not resolve canonical path for '$worktree'; refusing to rm-rf"
462
+ return 1
463
+ fi
464
+ # Resolve the cache root canonically too — if it's a symlink the
465
+ # JS side might have given us the symlink's target via
466
+ # `fs.realpathSync`, but defending against the case where it
467
+ # didn't is cheap and removes a footgun.
468
+ local resolved_root
469
+ if [ -d "$expected_cache_root" ]; then
470
+ resolved_root="$(cd "$expected_cache_root" 2>/dev/null && pwd -P)" || resolved_root=""
471
+ else
472
+ # Cache root may not exist yet (e.g. test scaffold that built
473
+ # the worktree but never instantiated the parent vault-hash
474
+ # dir). Fall back to the literal value — the prefix match
475
+ # below still works on logically-equivalent absolute paths.
476
+ resolved_root="$expected_cache_root"
477
+ fi
478
+ if [ -z "$resolved_root" ]; then
479
+ log_error "safe_rm_worktree: could not resolve canonical path for cache root '$expected_cache_root'; refusing to rm-rf '$worktree'"
480
+ return 1
481
+ fi
482
+ # Require `$resolved` to start with `$resolved_root/`. Trailing
483
+ # slash on the prefix prevents a sibling-directory false-accept
484
+ # like `/cache/napkin-distill/abc` matching `/cache/napkin-distill/abc-evil`.
485
+ case "$resolved" in
486
+ "$resolved_root"/*)
487
+ rm -rf "$resolved" 2>/dev/null || true
488
+ return 0
489
+ ;;
490
+ *)
491
+ log_error "safe_rm_worktree: refusing to rm-rf '$resolved' (resolved from '$worktree') — not a descendant of expected cache root '$resolved_root'"
492
+ return 1
493
+ ;;
494
+ esac
495
+ }
496
+
497
+ # salvage <vault> <worktree_path> <branch_name> <reason>
498
+ #
499
+ # Force-cleans the per-distill worktree and branch, validates the
500
+ # vault is back on its default branch, and writes a `failed:<reason>`
501
+ # outcome sidecar with a recovery hint. Per V3 verification
502
+ # (research/v2-v3-verification.md) the salvage path NEVER touches the
503
+ # main vault's commit history — the agent's mutations on main are
504
+ # trusted, and `git reset --hard $START_SHA` would silently destroy
505
+ # concurrent user commits in the autosave-while-editing scenario.
506
+ #
507
+ # Reason codes (must match the JS-side dispatch table):
508
+ # markers-after-agent-exit
509
+ # pre-existing-markers
510
+ # internal-validator-error
511
+ # head-not-on-default
512
+ # agent-exit-nonzero
513
+ # agent-timeout
514
+ # divergent-history
515
+ #
516
+ # Cleanup operations are best-effort: a failed `worktree remove` or
517
+ # `branch -D` does NOT prevent the outcome write — the JS-side
518
+ # UI dispatch on the outcome class is the user-facing signal that
519
+ # matters.
520
+ #
521
+ # INVARIANT: write_outcome ALWAYS runs before any worktree-removal
522
+ # step in this function, mirroring the EXIT trap's ordering. The
523
+ # JS-side poller in runDistillWith watches the worktree path and
524
+ # calls findDistillOutcomeForBranch as soon as fs.existsSync returns
525
+ # false. If any worktree-removal step ran before write_outcome, the
526
+ # JS dispatch would surface a spurious 'terminated abnormally
527
+ # — no outcome record' warning instead of the correct
528
+ # 'failed:<reason>' notification. wrapper-invariant.test.ts pins
529
+ # this invariant for both the happy path (EXIT trap) and the
530
+ # salvage path (this function).
531
+ salvage() {
532
+ local vault="$1"
533
+ local worktree="$2"
534
+ local branch="$3"
535
+ local reason="$4"
536
+
537
+ # cd out of the worktree so `git worktree remove --force` doesn't
538
+ # refuse on "cwd inside worktree".
539
+ cd "$vault" 2>/dev/null || cd /
540
+
541
+ # Compose recovery hint per reason. Each hint points the user at the
542
+ # specific recovery action that fits the failure mode — the design
543
+ # spec calls out `git revert HEAD --no-edit` and `git reflog` as the
544
+ # primary recovery levers ("the dangling distill branch is
545
+ # recoverable from `git reflog` for ~2 weeks").
546
+ local hint
547
+ case "$reason" in
548
+ markers-after-agent-exit)
549
+ hint="Conflict markers landed in the vault. Inspect '$vault', then 'git -C $vault revert HEAD --no-edit' to undo the corrupt commit. Distill content is recoverable from 'git -C $vault reflog' for ~90 days."
550
+ ;;
551
+ pre-existing-markers)
552
+ hint="Conflict markers were already present in the vault before this distill ran (likely from a prior failed merge or a hand-edit). The agent did NOT introduce them, so this distill was rejected to avoid compounding the corruption. Inspect '$vault' (the error log lists the affected files) and resolve manually — delete the marker lines, keep the desired content, and commit. Once clean, re-run distill."
553
+ ;;
554
+ internal-validator-error)
555
+ hint="The post-distill conflict-marker validator could NOT run (mktemp failed to allocate a tempfile — likely a full disk or locked-down TMPDIR). The vault was NOT scanned for markers after the agent exited, so the wrapper cannot say whether the squash commit introduced corruption. Inspect '$vault' manually for unresolved '<<<<<<< / ======= / >>>>>>>' markers; if clean, the squash is keepable, otherwise 'git -C $vault revert HEAD --no-edit'. Distill content is recoverable from 'git -C $vault reflog' for ~90 days."
556
+ ;;
557
+ head-not-on-default)
558
+ hint="Vault HEAD is not on '$DEFAULT_BRANCH'. Run 'git -C $vault checkout $DEFAULT_BRANCH' before the next distill. Distill content is recoverable from 'git -C $vault reflog'."
559
+ ;;
560
+ agent-exit-nonzero)
561
+ hint="Agent crashed before completing the distill. See the error log alongside this outcome for stderr. Distill content (if any) is recoverable from 'git -C $vault reflog'."
562
+ ;;
563
+ agent-timeout)
564
+ hint="Agent task exceeded the maxDurationMinutes budget and was killed. Bump 'distill.maxDurationMinutes' in vault config.json if this happens repeatedly. Distill content (if any) is recoverable from 'git -C $vault reflog'."
565
+ ;;
566
+ divergent-history)
567
+ hint="origin/$DEFAULT_BRANCH and local $DEFAULT_BRANCH have diverged — typically because someone (you or a teammate) pushed to origin from another clone before this distill ran. Less commonly, someone force-pushed there. Inspect with 'git -C $vault log origin/$DEFAULT_BRANCH..$DEFAULT_BRANCH' (your local commits not on origin) and 'git -C $vault log $DEFAULT_BRANCH..origin/$DEFAULT_BRANCH' (origin commits not local), then resolve by pulling-and-merging or by inspecting the divergence and choosing the right recovery (revert, manual merge, etc.). Distill content is recoverable from 'git -C $vault reflog' for ~90 days."
568
+ ;;
569
+ *)
570
+ hint="Distill failed with an unrecognised reason. See the error log for diagnostics. Distill content (if any) is recoverable from 'git -C $vault reflog'."
571
+ ;;
572
+ esac
573
+
574
+ # Write the outcome BEFORE any worktree-removal step. Pins the
575
+ # function-level invariant noted above.
576
+ write_outcome "failed:$reason" "$hint"
577
+
578
+ # Verify HEAD is on default. Per V3, the salvage path NEVER moves
579
+ # HEAD on the user's behalf — if the user manually checked out a
580
+ # different branch mid-distill, that's their state, not ours to
581
+ # rewrite. Log a critical-error so it surfaces in the failure
582
+ # notification, but don't `git checkout`.
583
+ local vault_head
584
+ vault_head="$(git -C "$vault" symbolic-ref --short HEAD 2>/dev/null || true)"
585
+ if [ -z "$vault_head" ]; then
586
+ log_error "salvage: vault HEAD is detached after agent exit; user must checkout '$DEFAULT_BRANCH' manually before next distill"
587
+ elif [ "$vault_head" != "$DEFAULT_BRANCH" ]; then
588
+ log_error "salvage: vault HEAD is '$vault_head' after agent exit (expected '$DEFAULT_BRANCH'); not rewriting per never-touch-main lockdown"
589
+ fi
590
+
591
+ # Force-remove worktree. Ignore errors (already gone, never created,
592
+ # other concurrent salvage racing).
593
+ if [ -d "$worktree" ]; then
594
+ git -C "$vault" worktree remove --force "$worktree" 2>/dev/null || true
595
+ fi
596
+ # Belt-and-braces: gitignored shim survives `worktree remove --force`.
597
+ # rm -rf the leaf if anything's left (POST-CONV-3 pattern). Routed
598
+ # through safe_rm_worktree so an upstream bug that passed a non-
599
+ # napkin-distill path can't escalate to `rm -rf /etc`-class damage
600
+ # via this code path (SEC-A-2 defense-in-depth). Pass
601
+ # EXPECTED_CACHE_ROOT so safe_rm_worktree's descendant check
602
+ # (SEC-2 / CORR-3) verifies the worktree is under the cache root.
603
+ if [ -d "$worktree" ]; then
604
+ safe_rm_worktree "$worktree" "$EXPECTED_CACHE_ROOT" || true
605
+ fi
606
+ # Prune any stale worktree entry whose dir is gone.
607
+ git -C "$vault" worktree prune 2>/dev/null || true
608
+ # Force-delete branch. -D because squash-merge leaves the branch
609
+ # marked as unmerged.
610
+ git -C "$vault" branch -D "$branch" 2>/dev/null || true
611
+ # Best-effort rmdir of the parent vault-hash dir — succeeds when
612
+ # this was the last distill (POST-CONV-4 pattern).
613
+ rmdir "$(dirname "$worktree")" 2>/dev/null || true
614
+ }
615
+
616
+
617
+ # --- Post-agent-exit validation helpers (PR #12 A3) -------------------------
618
+ #
619
+ # Each helper inspects the vault's post-agent state and returns 0 (pass) or
620
+ # 1 (fail). Diagnostics go to the error log on failure so the user can see
621
+ # what tripped the validator. Helpers are intentionally side-effect-free
622
+ # beyond logging — the salvage path (A4) is the only thing that mutates
623
+ # the worktree/branch on validation failure.
624
+
625
+ # list_marker_files <vault> <output_file>
626
+ #
627
+ # Scan the vault's tracked `*.md` files and write the relative path of
628
+ # every file that contains a complete conflict-marker triple to
629
+ # <output_file>, one per line. Empty output file = no conflict-marked
630
+ # files in the vault. Idempotent: caller is responsible for
631
+ # truncating <output_file> first.
632
+ #
633
+ # Marker triple definition (CORR-A-1, SEC-A-7): a real merge conflict
634
+ # always emits ALL THREE marker types (`<<<<<<< `, `======= `, `>>>>>>> `)
635
+ # in the same file. The any-of-three rule false-positives on Setext
636
+ # H1 underlines and on documentation prose that quotes one or two
637
+ # markers; co-presence eliminates those classes. The acknowledged
638
+ # tradeoff (a vault that genuinely documents the full triple inside
639
+ # a single file) is documented at validate_no_markers below.
640
+ #
641
+ # Restricted to `*.md` because that's the only file class the agent
642
+ # touches; scanning the entire vault would false-positive on user
643
+ # scripts that legitimately discuss markers.
644
+ #
645
+ # Why a `git ls-files` enumeration: gitignored content (e.g. the
646
+ # per-distill `.napkin/distill/` shim dir) is skipped automatically.
647
+ # Per-file `grep -q` invocations are O(N) in tracked .md files; the
648
+ # prior single-pass `xargs grep` was O(1) but couldn't express the
649
+ # per-file all-three-co-present predicate. For vaults with thousands
650
+ # of .md files this is slower but still well under wall-clock
651
+ # budget. CLEAN-A-15 tracks the optimisation opportunity.
652
+ #
653
+ # bash 3.2 portability (macOS default): `while read -d ''` with array
654
+ # `+=` is supported. Process substitution `< <(...)` is also bash 3.2.
655
+ #
656
+ # Used by:
657
+ # - The pre-distill snapshot capture (right before the agent runs)
658
+ # to record which files already had markers, so post-distill
659
+ # validation can distinguish agent-induced markers from
660
+ # pre-existing ones (CORR-1).
661
+ # - validate_no_markers (post-distill), which calls this helper
662
+ # against the same vault and diffs the two snapshots.
663
+ list_marker_files() {
664
+ local vault="$1"
665
+ local output_file="$2"
666
+ local file
667
+ while IFS= read -r -d '' file; do
668
+ # All three markers must appear in the same file. `grep -q`
669
+ # short-circuits on first match, and the `&&` chain stops as
670
+ # soon as one marker type is absent — minimising work in the
671
+ # common no-conflict case.
672
+ if grep -qE '^<{7} ' -- "$vault/$file" 2>/dev/null \
673
+ && grep -qE '^={7}$' -- "$vault/$file" 2>/dev/null \
674
+ && grep -qE '^>{7} ' -- "$vault/$file" 2>/dev/null; then
675
+ printf '%s\n' "$file" >> "$output_file"
676
+ fi
677
+ done < <(git -C "$vault" ls-files -z -- '*.md' 2>/dev/null)
678
+ }
679
+
680
+ # validate_no_markers <vault> <pre_distill_marker_files>
681
+ #
682
+ # Searches the vault's tracked `*.md` files for unresolved git conflict
683
+ # markers and classifies any matches against the pre-distill snapshot
684
+ # captured just before the agent ran:
685
+ #
686
+ # pass (rc 0) — no marker-bearing files post-distill
687
+ # fail rc 1 — at least one NEW marker-bearing file (agent-induced)
688
+ # fail rc 2 — only pre-existing marker-bearing files (NOT
689
+ # agent-induced — the user's vault was already in this
690
+ # state; the agent didn't make it worse)
691
+ #
692
+ # rc 1 takes priority when both new and pre-existing markers are
693
+ # present: the agent's run made things worse, which is the dominant
694
+ # signal even if it didn't touch the pre-existing files. Only rc 2
695
+ # fires when EVERY marker-bearing file post-distill was already
696
+ # marker-bearing pre-distill.
697
+ #
698
+ # Caller dispatches on the rc to choose the right salvage reason
699
+ # code:
700
+ # rc 1 → markers-after-agent-exit (agent-induced; existing reason)
701
+ # rc 2 → pre-existing-markers (NOT agent-induced; new reason
702
+ # code with a recovery hint that
703
+ # points the user at fixing the
704
+ # listed files manually)
705
+ # rc 3 → internal-validator-error (validator could NOT run because
706
+ # its post-distill mktemp failed;
707
+ # surfaced as its own reason so the
708
+ # user is NOT told markers were
709
+ # found post-agent-exit when the
710
+ # validator never observed the
711
+ # vault state — CORR-1 R3 / SEC-1 R3)
712
+ #
713
+ # CORR-1: pre-existing markers (from a prior failed run, user error,
714
+ # leftover state from a botched manual merge) used to classify as
715
+ # `markers-after-agent-exit` because the wrapper had no
716
+ # pre-distill marker snapshot. That misled the user into blaming the
717
+ # agent for state it didn't create. Capturing the snapshot at
718
+ # wrapper start lets us differentiate.
719
+ #
720
+ # Marker triple definition (CORR-A-1, SEC-A-7): a real merge conflict
721
+ # always emits ALL THREE marker types in the same file. See
722
+ # list_marker_files for the per-file predicate.
723
+ #
724
+ # Acknowledged tradeoff: a vault that genuinely documents a complete
725
+ # `<<<<<<<` / `=======` / `>>>>>>>` example INSIDE A SINGLE FILE will
726
+ # trip the validator post-distill — but if it ALSO tripped
727
+ # pre-distill, this code path classifies it as `pre-existing-markers`
728
+ # (rc 2) instead of as agent-induced. Users who hit this can escape
729
+ # the markers in their docs (leading space, HTML comments) once and
730
+ # subsequent distills see no markers either pre or post.
731
+ #
732
+ # Why scan post-squash on the vault: the agent merges into its branch
733
+ # inside the worktree, then squashes onto the default branch in the
734
+ # vault. Markers in the agent's branch get squashed into the vault's
735
+ # default branch — they become committed corruption in the vault. The
736
+ # vault working tree is the canonical post-condition.
737
+ validate_no_markers() {
738
+ local vault="$1"
739
+ local pre_file="$2"
740
+ if [ -z "$vault" ] || [ -z "$pre_file" ]; then
741
+ log_error "validate_no_markers: both <vault> and <pre_distill_marker_files> are required (caller passes /dev/null when no pre-distill snapshot is available)"
742
+ return 3
743
+ fi
744
+
745
+ local post_file
746
+ post_file="$(mktemp -t napkin-distill-post-marker.XXXXXX 2>/dev/null || true)"
747
+ if [ -z "$post_file" ]; then
748
+ # CORR-1 R3 / SEC-1 R3: post-distill mktemp failure (full disk,
749
+ # locked-down TMPDIR, etc.) USED to return 1 — which the caller
750
+ # mapped to `failed:markers-after-agent-exit`. That misled the
751
+ # user into reverting a possibly-correct squash commit on the
752
+ # claim that markers had landed in the vault, even though the
753
+ # validator never actually scanned the vault. Return a distinct
754
+ # rc 3 so the caller routes to `failed:internal-validator-error`
755
+ # whose recovery hint truthfully tells the user the validator
756
+ # couldn't run — inspect the vault before relying on the squash.
757
+ log_error "validate_no_markers: mktemp failed for post-distill snapshot — cannot scan vault for conflict markers; routing to internal-validator-error (NOT markers-after-agent-exit) to avoid misattributing unobserved state to the agent"
758
+ return 3
759
+ fi
760
+ list_marker_files "$vault" "$post_file"
761
+
762
+ # Empty post-distill snapshot = no marker-bearing files = pass.
763
+ if [ ! -s "$post_file" ]; then
764
+ rm -f "$post_file" 2>/dev/null || true
765
+ return 0
766
+ fi
767
+
768
+ # Compute set difference: files in post but NOT in pre = NEW (agent-induced).
769
+ # `comm` requires sorted input. The caller passes /dev/null as pre_file
770
+ # when no pre-distill snapshot is available (mktemp failed at startup),
771
+ # which collapses to "every post-marker file is NEW" and routes to
772
+ # failed:markers-after-agent-exit.
773
+ local new_marker_files pre_existing_marker_files
774
+ new_marker_files="$(comm -23 <(sort -u "$post_file") <(sort -u "$pre_file" 2>/dev/null) 2>/dev/null || cat "$post_file")"
775
+ pre_existing_marker_files="$(comm -12 <(sort -u "$post_file") <(sort -u "$pre_file" 2>/dev/null) 2>/dev/null || true)"
776
+
777
+ rm -f "$post_file" 2>/dev/null || true
778
+
779
+ if [ -n "$new_marker_files" ]; then
780
+ # Agent-induced markers present (alone or alongside pre-existing).
781
+ # Dominant signal: the run made things worse.
782
+ log_error "validate_no_markers: NEW conflict markers (agent-induced) in vault \`$vault\`:"
783
+ while IFS= read -r file; do
784
+ [ -n "$file" ] && log_error " $vault/$file"
785
+ done <<< "$new_marker_files"
786
+ if [ -n "$pre_existing_marker_files" ]; then
787
+ log_error "validate_no_markers: also pre-existing conflict markers (present before agent ran) in:"
788
+ while IFS= read -r file; do
789
+ [ -n "$file" ] && log_error " $vault/$file"
790
+ done <<< "$pre_existing_marker_files"
791
+ fi
792
+ return 1
793
+ fi
794
+
795
+ # Only pre-existing markers post-distill — the agent didn't touch
796
+ # those files (or touched them but didn't make things worse). Not
797
+ # agent-induced; route to a different reason code so the user can
798
+ # fix the underlying files manually.
799
+ log_error "validate_no_markers: pre-existing conflict markers (NOT agent-induced) in vault \`$vault\`:"
800
+ while IFS= read -r file; do
801
+ [ -n "$file" ] && log_error " $vault/$file"
802
+ done <<< "$pre_existing_marker_files"
803
+ return 2
804
+ }
805
+
806
+ # validate_head_on_default <vault> <default_branch>
807
+ #
808
+ # Confirms the vault's HEAD is the symbolic ref `refs/heads/<default>`.
809
+ # Per V3 verification (research/v2-v3-verification.md), use
810
+ # `git symbolic-ref --short HEAD` — it returns the short branch name on
811
+ # a normal checkout and exits non-zero on detached HEAD. The other two
812
+ # options (`branch --show-current` returns empty on detached;
813
+ # `rev-parse --abbrev-ref HEAD` returns literal `HEAD` on detached)
814
+ # silently false-positive.
815
+ #
816
+ # Returns 0 (pass) when HEAD == default. Returns 1 (fail) on any other
817
+ # state, including detached HEAD. Refusing to act on detached HEAD is
818
+ # correct: the agent should have exited with HEAD on default after
819
+ # step 8, and the wrapper must not silently accept a vault in the
820
+ # wrong state.
821
+ validate_head_on_default() {
822
+ local vault="$1"
823
+ local default="$2"
824
+ local head
825
+ head="$(git -C "$vault" symbolic-ref --short HEAD 2>/dev/null || true)"
826
+ if [ -z "$head" ]; then
827
+ log_error "validate_head_on_default: vault HEAD is detached (not on a branch); expected '$default'"
828
+ return 1
829
+ fi
830
+ if [ "$head" != "$default" ]; then
831
+ log_error "validate_head_on_default: vault HEAD is '$head', expected '$default'"
832
+ return 1
833
+ fi
834
+ return 0
835
+ }
836
+
837
+ # validate_commit_count <vault> <start_sha>
838
+ #
839
+ # Prints (to stdout) the number of commits on the vault's current HEAD
840
+ # since `<start_sha>` (exclusive). Returns 0 unless the rev-list call
841
+ # itself fails (which would be a hard error — startSha must be reachable
842
+ # from HEAD or the wrapper's invariants are broken).
843
+ #
844
+ # Used by the wrapper to dispatch among:
845
+ # - 0 commits -> no-content (agent ran but produced nothing)
846
+ # - 1+ commits -> merged-content / merged-local (agent landed work)
847
+ #
848
+ # This is intentionally a count, not a boolean: future telemetry
849
+ # (POST-CONV-7-TELEM) wants the number for outcome distribution
850
+ # analysis. The wrapper's own dispatch only needs `>= 1`.
851
+ #
852
+ # Rev-list semantics: `<start_sha>..HEAD` includes commits reachable
853
+ # from HEAD that are NOT reachable from start_sha. If main moved since
854
+ # distill spawn (concurrent user commit + agent's squash), both are
855
+ # counted — acceptable looseness for the no-content vs has-content
856
+ # dispatch (we err on the side of "has content").
857
+ validate_commit_count() {
858
+ local vault="$1"
859
+ local start_sha="$2"
860
+ local count
861
+ count="$(git -C "$vault" rev-list --count "$start_sha..HEAD" 2>/dev/null || true)"
862
+ if [ -z "$count" ]; then
863
+ log_error "validate_commit_count: git rev-list failed for $start_sha..HEAD in $vault"
864
+ return 1
865
+ fi
866
+ printf '%s\n' "$count"
867
+ return 0
868
+ }
869
+
870
+ # detect_local_only <vault> <default_branch>
871
+ #
872
+ # Determines whether the vault has commits on `<default_branch>` that
873
+ # haven't reached `origin/<default_branch>`. Distinguishes legitimate
874
+ # fast-forward state (local ahead of remote, remote is ancestor of
875
+ # local — the agent didn't push but origin's history is intact) from
876
+ # divergent state (remote is NOT an ancestor of local — origin and
877
+ # local share no linear ancestry, e.g. because a teammate pushed from
878
+ # another clone or, less commonly, someone force-pushed origin).
879
+ #
880
+ # Per the spec at "Push behavior: never force":
881
+ # "Spec the prohibition in the prompt; the wrapper post-validates by
882
+ # checking that origin/<default> only fast-forwarded (its tip is an
883
+ # ancestor of the new tip after push)."
884
+ #
885
+ # Equality-check (the pre-fix behavior) couldn't tell those two states
886
+ # apart — in either case local != remote post-agent. The prompt's
887
+ # prohibition was the only enforcement of the no-force-push invariant
888
+ # (a soft control). This helper now adds the wrapper-side hard control
889
+ # the spec requires (SEC-A-1).
890
+ #
891
+ # Return codes:
892
+ # 0 — local-only (`merged-local` outcome): origin configured AND
893
+ # (no remote-tracking ref yet OR remote is ancestor of local).
894
+ # Either case is legitimate “distilled but not pushed” state.
895
+ # 1 — in sync OR no origin configured: proceed to `merged-content`.
896
+ # 2 — divergent histories (`failed:divergent-history` outcome):
897
+ # remote is NOT an ancestor of local. The wrapper surfaces this
898
+ # as a failure because the agent's safe-recovery flow
899
+ # (pull --no-rebase + push) did not run or did not converge,
900
+ # and the user must inspect/resolve before the next distill.
901
+ # The naming is neutral on cause: a benign third-party push
902
+ # from another clone is the common case, force-push the rare
903
+ # one (and SEC-1/CORR-2 round-2 review elevated this to a
904
+ # cross-reviewer-consensus rename from `force-push-detected`).
905
+ detect_local_only() {
906
+ local vault="$1"
907
+ local default="$2"
908
+ # No origin configured at all → push was never expected; not local-only.
909
+ if ! git -C "$vault" remote get-url origin >/dev/null 2>&1; then
910
+ return 1
911
+ fi
912
+ local local_sha remote_sha
913
+ local_sha="$(git -C "$vault" rev-parse "$default" 2>/dev/null || true)"
914
+ remote_sha="$(git -C "$vault" rev-parse "origin/$default" 2>/dev/null || true)"
915
+ # Origin configured but no remote-tracking ref yet (e.g. never fetched)
916
+ # → treat as local-only because origin is the user's intent and the
917
+ # agent's push didn't materialise.
918
+ if [ -z "$remote_sha" ]; then
919
+ log_error "detect_local_only: origin configured but origin/$default unreachable; treating as merged-local"
920
+ return 0
921
+ fi
922
+ if [ -z "$local_sha" ]; then
923
+ # Default branch doesn't exist locally — unexpected; surface as
924
+ # not-local-only and let the markers / commit-count validators
925
+ # decide the outcome.
926
+ return 1
927
+ fi
928
+ if [ "$local_sha" = "$remote_sha" ]; then
929
+ # In sync — push happened (or nothing changed). Not local-only.
930
+ return 1
931
+ fi
932
+ # Local differs from remote. Ancestry decides whether the divergence
933
+ # is legitimate (fast-forward pending) or non-linear (`divergent-history`).
934
+ if git -C "$vault" merge-base --is-ancestor "$remote_sha" "$local_sha"; then
935
+ # Remote is ancestor of local — fast-forward pending. Either the
936
+ # agent didn't push, or the push failed and the agent fell back
937
+ # to local-only. Legitimate `merged-local`.
938
+ return 0
939
+ fi
940
+ # Remote is NOT an ancestor of local — origin and local share no
941
+ # linear ancestry. The common case is a teammate (or the user from
942
+ # another clone) pushing to origin while this distill ran; the rare
943
+ # case is a force-push that rewrote origin's history. Either way
944
+ # the agent's safe-recovery path (pull --no-rebase + push) did not
945
+ # converge, so the wrapper surfaces a `divergent-history` failure
946
+ # for the user to inspect and resolve.
947
+ log_error "detect_local_only: origin/$default at $remote_sha is not an ancestor of local $default at $local_sha (divergent histories)"
948
+ return 2
242
949
  }
243
950
 
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
951
 
251
952
  # Trap-based cleanup: always remove the worktree + branch on exit (success or
252
953
  # failure). `git worktree remove --force` also handles partially-initialized
253
954
  # worktrees. Errors from cleanup are logged but don't affect our exit status.
955
+ #
956
+ # PR #12 cleanup is unchanged from PR #11: agent SHOULD do its own cleanup
957
+ # in step 10 of the prompt, but the wrapper's trap is the safety net for
958
+ # any path the agent didn't reach (timeout, crash, error, salvage). Idempotent
959
+ # against the agent having already removed the worktree (`git worktree
960
+ # remove` errors on a missing path; we discard the error).
254
961
  cleanup() {
255
962
  local rc=$?
256
963
  # cd out of the worktree before removing it, otherwise git refuses.
@@ -262,9 +969,14 @@ cleanup() {
262
969
  # .napkin/distill/ shim survives `git worktree remove --force`. The
263
970
  # `[ -d ]` guard is defensive against future scenarios where the shim
264
971
  # is removed before this point. Mirrors cleanupDistillWorkspace's
265
- # contract at distill-workspace.ts:572.
972
+ # contract in distill-workspace.ts. Routed through
973
+ # safe_rm_worktree so an upstream bug that passed a non-napkin-distill
974
+ # path can't escalate to `rm -rf /etc`-class damage via this code
975
+ # path (SEC-A-2 defense-in-depth). Pass EXPECTED_CACHE_ROOT so
976
+ # safe_rm_worktree's descendant check (SEC-2 / CORR-3) verifies the
977
+ # worktree is under the cache root.
266
978
  if [ -d "$WORKTREE" ]; then
267
- rm -rf "$WORKTREE" 2>/dev/null || true
979
+ safe_rm_worktree "$WORKTREE" "$EXPECTED_CACHE_ROOT" || true
268
980
  fi
269
981
  # Prune in case the worktree entry is stale but the dir is gone.
270
982
  git -C "$VAULT" worktree prune 2>/dev/null || true
@@ -275,6 +987,24 @@ cleanup() {
275
987
  # was the last distill for the vault. ENOTEMPTY (other concurrent
276
988
  # distills) and ENOENT (race) are both expected and benign.
277
989
  rmdir "$(dirname "$WORKTREE")" 2>/dev/null || true
990
+ # CORR-1: the pre-distill marker snapshot tmp file is the wrapper's
991
+ # internal scratch state. Empty string when the snapshot was never
992
+ # captured (NAPKIN_DISTILL_SKIP_PI=1, early-exit before snapshot,
993
+ # mktemp failed). `rm -f` is idempotent on missing paths.
994
+ if [ -n "${PRE_DISTILL_MARKER_FILES_FILE:-}" ]; then
995
+ rm -f "$PRE_DISTILL_MARKER_FILES_FILE" 2>/dev/null || true
996
+ fi
997
+ # SEC-2 R3: pi_stderr is the agent's stderr capture file (allocated
998
+ # via mktemp before invoking pi). Normal-path cleanup happens inline
999
+ # at the post-agent block, but a SIGTERM-on-grace, OOM kill, or any
1000
+ # crash before that block leaves the file orphaned in $TMPDIR. The
1001
+ # EXIT trap doesn't fire on SIGKILL (kernel-enforced) but DOES fire
1002
+ # on SIGTERM grace and on every normal exit — register the cleanup
1003
+ # here for defense-in-depth. Empty string when pi was skipped
1004
+ # (NAPKIN_DISTILL_SKIP_PI=1) or we crashed before the mktemp.
1005
+ if [ -n "${pi_stderr:-}" ]; then
1006
+ rm -f "$pi_stderr" 2>/dev/null || true
1007
+ fi
278
1008
  exit "$rc"
279
1009
  }
280
1010
  trap cleanup EXIT
@@ -303,11 +1033,9 @@ if [ -f "$META_PATH" ]; then
303
1033
  fi
304
1034
  fi
305
1035
 
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`.
1036
+ # Extract startSha from meta.json — used by record_dangling_sha and
1037
+ # (in A3) by validate_commit_count to confirm the agent landed at
1038
+ # least one commit beyond pre-distill HEAD.
311
1039
  #
312
1040
  # Use node for parsing instead of sed: a regex on JSON is fragile
313
1041
  # against future shape changes (multi-line values, embedded commas,
@@ -318,11 +1046,7 @@ fi
318
1046
  #
319
1047
  # Hard-fail with a clear diagnostic if node is missing or unrunnable
320
1048
  # 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.
1049
+ # mislead the user (R13-CI-1 / R13-CC-3).
326
1050
  REAL_NODE="$(command -v node || true)"
327
1051
  if [ -z "$REAL_NODE" ]; then
328
1052
  log_error "node binary not found on wrapper PATH; required for startSha extraction. Set PATH to include node before launching pi."
@@ -340,14 +1064,7 @@ if [ -f "$META_PATH" ]; then
340
1064
  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
1065
  fi
342
1066
 
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.
1067
+ # Hard-fail when startSha can't be recovered (consistent with PR #11).
351
1068
  if [ -z "$START_SHA" ]; then
352
1069
  log_error "meta.json missing startSha; refusing to proceed (worktree from incompatible pi-napkin version?)"
353
1070
  exit 1
@@ -368,7 +1085,7 @@ fi
368
1085
  # preserving prompt-cache hits across the spawn boundary. That means
369
1086
  # napkin's cwd-based vault walk-up resolves to the *parent's* vault
370
1087
  # (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).
1088
+ # worktree's checkout for the subsequent merge/squash/push to see them).
372
1089
  #
373
1090
  # The shim transparently injects `--vault $WORKTREE` into every napkin
374
1091
  # invocation from the agent's bash tool. The real napkin path is
@@ -382,12 +1099,8 @@ fi
382
1099
  # the worktree is removed (no extra cleanup needed). The directory is
383
1100
  # already `.gitignore`d via the `.napkin/distill/` exclusion.
384
1101
  #
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
1102
  # 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
1103
+ # (no agent run → no napkin invocations to route). Lets the integration
391
1104
  # tests run in environments where napkin isn't installed (e.g. fresh
392
1105
  # CI runners). Production never sets SKIP_PI.
393
1106
  #
@@ -475,28 +1188,66 @@ fi
475
1188
  # Placement is post-shim-install so the worktree has gitignored
476
1189
  # content (.napkin/distill/bin/napkin shim) that survives
477
1190
  # `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
1191
  if [ "${NAPKIN_DISTILL_FORCE_CLEANUP:-}" = "1" ]; then
486
1192
  log_error "FORCE_CLEANUP hook fired post-shim-install (test hook); triggering cleanup trap"
487
1193
  exit 1
488
1194
  fi
489
1195
 
490
- # --- Step 1: run pi at PARENT_CWD (cache parity) -----------------------------
1196
+ # --- Pre-distill marker snapshot (CORR-1) -----------------------------------
1197
+ #
1198
+ # Capture which tracked `*.md` files in the vault already contain a
1199
+ # complete conflict-marker triple BEFORE the agent runs. Used by
1200
+ # validate_no_markers post-agent to differentiate:
1201
+ #
1202
+ # - Files marker-bearing post-distill but NOT pre-distill
1203
+ # → NEW (agent-induced) → failed:markers-after-agent-exit
1204
+ # - Files marker-bearing pre-distill AND post-distill
1205
+ # → pre-existing (NOT agent-induced) → failed:pre-existing-markers
1206
+ #
1207
+ # Without this snapshot, every post-agent marker classified as
1208
+ # agent-induced — misleading users when the markers came from a prior
1209
+ # failed run, a botched manual merge, or user editing.
1210
+ #
1211
+ # Best-effort: if mktemp fails (very rare), set PRE_DISTILL_MARKER_FILES_FILE
1212
+ # to /dev/null so the call site always passes a concrete pre-snapshot
1213
+ # path. validate_no_markers treats /dev/null as "no pre-existing markers
1214
+ # observed", collapsing every post-agent marker to NEW (agent-induced)
1215
+ # and routing to failed:markers-after-agent-exit. The wrapper does NOT
1216
+ # hard-fail on snapshot failure — the worst-case is the pre-PR-12-Pass-2B
1217
+ # behaviour.
1218
+ PRE_DISTILL_MARKER_FILES_FILE="$(mktemp -t napkin-distill-pre-marker.XXXXXX 2>/dev/null || true)"
1219
+ if [ -n "$PRE_DISTILL_MARKER_FILES_FILE" ]; then
1220
+ list_marker_files "$VAULT" "$PRE_DISTILL_MARKER_FILES_FILE"
1221
+ else
1222
+ log_error "pre-distill marker snapshot: mktemp failed; passing /dev/null to validate_no_markers (any post-agent markers will route to failed:markers-after-agent-exit)"
1223
+ PRE_DISTILL_MARKER_FILES_FILE="/dev/null"
1224
+ fi
1225
+
1226
+ # --- Step: run the agent under a hard timeout (PR #12 architecture) --------
491
1227
  #
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.
1228
+ # A single bounded `pi -p` call. The agent's prompt (already resolved by
1229
+ # `buildDistillPrompt` on the JS side) instructs it to:
1230
+ # - distill conversation content into the worktree (steps 1–6)
1231
+ # - git merge $DEFAULT_BRANCH into the distill branch from the worktree
1232
+ # - git merge --squash $BRANCH onto $DEFAULT_BRANCH from the main vault
1233
+ # - git push if origin exists (no force, pull-merge on contention)
1234
+ # - git worktree remove + git branch -D
1235
+ #
1236
+ # Wrapper guarantees: cwd = PARENT_CWD (cache parity), napkin shim on PATH,
1237
+ # session is the parent's fork (so the agent has full conversation context),
1238
+ # `timeout(1)` enforces a hard wall-clock bound, NAPKIN_DISTILL_NO_RECURSE=1
1239
+ # inhibits the inner pi from auto-distilling.
1240
+ #
1241
+ # Agent responsibilities: everything between distill and cleanup. The
1242
+ # wrapper validates the agent's output post-exit and salvages on
1243
+ # validation failure (validate_* helpers + salvage() below).
497
1244
 
498
1245
  cd "$PARENT_CWD" || { log_error "cd parent cwd failed: $PARENT_CWD"; exit 1; }
499
1246
 
1247
+ # Capture agent exit code so post-validation can dispatch on it. Default
1248
+ # to 0 when the agent step is skipped (NAPKIN_DISTILL_SKIP_PI=1).
1249
+ AGENT_RC=0
1250
+
500
1251
  if [ "${NAPKIN_DISTILL_SKIP_PI:-}" != "1" ]; then
501
1252
  PI_BIN="${NAPKIN_DISTILL_PI_BIN:-pi}"
502
1253
  pi_args=(--session "$SESSION_FORK")
@@ -505,188 +1256,217 @@ if [ "${NAPKIN_DISTILL_SKIP_PI:-}" != "1" ]; then
505
1256
  fi
506
1257
  pi_args+=(-p "$PROMPT")
507
1258
  # 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:"
1259
+ # discarded — the agent's chatter isn't useful forensically; what
1260
+ # matters is the post-exit filesystem state.
1261
+ #
1262
+ # SEC-2 R3: use the napkin-distill- prefix so abandoned tmpfiles
1263
+ # (post-SIGKILL, OOM, etc.) are attributable to this wrapper instead
1264
+ # of orphaning as anonymous `tmp.XXXXXX` files in $TMPDIR. The
1265
+ # EXIT trap registers an rm -f for $pi_stderr as defense-in-depth
1266
+ # against the SIGTERM-grace path (kernel doesn't fire EXIT on
1267
+ # SIGKILL, but does on SIGTERM and normal exit).
1268
+ pi_stderr="$(mktemp -t napkin-distill-pi_stderr.XXXXXX)"
1269
+ # `timeout(1) --foreground -k <secs> <budget>` sends SIGTERM at the
1270
+ # budget boundary, then escalates to SIGKILL after the grace period
1271
+ # (TIMEOUT_KILL_GRACE_SECS) if the target hasn't exited. `--foreground`
1272
+ # ensures TTY-attached signals propagate even when invoked without a
1273
+ # controlling terminal (which is our case — detached + stdio:ignore).
1274
+ #
1275
+ # When timeout fires SIGTERM, exit code = 124. SIGKILL escalation
1276
+ # exit code = 137. The wrapper distinguishes these from a regular
1277
+ # agent crash via case below.
1278
+ #
1279
+ # TIMEOUT_BIN is detected at wrapper start (resolves to either
1280
+ # `timeout` on Linux or `gtimeout` on macOS-with-Homebrew-coreutils).
1281
+ NAPKIN_DISTILL_NO_RECURSE=1 \
1282
+ "$TIMEOUT_BIN" --foreground -k "$TIMEOUT_KILL_GRACE_SECS" "$MAX_DURATION_SECS" \
1283
+ "$PI_BIN" "${pi_args[@]}" > /dev/null 2> "$pi_stderr" || AGENT_RC=$?
1284
+ # Write stderr to error log on non-zero exit so post-mortem inspection
1285
+ # is possible even when the wrapper went on to write a success
1286
+ # outcome (defensive: unexpected stderr on exit-0 is informational).
1287
+ if [ "$AGENT_RC" -ne 0 ]; then
1288
+ log_error "agent subprocess exited $AGENT_RC; stderr follows:"
512
1289
  cat "$pi_stderr" >> "$ERROR_LOG" 2>/dev/null || true
513
- rm -f "$pi_stderr"
514
- record_dangling_sha
515
- exit 1
516
1290
  fi
517
1291
  rm -f "$pi_stderr"
518
1292
  fi
519
1293
 
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
1294
+ # --- Post-agent-exit dispatch (PR #12 A3) -----------------------------------
1295
+ #
1296
+ # Validates the agent's output and writes the appropriate outcome class.
1297
+ # A3 wires:
1298
+ # - validate_no_markers (markers-after-agent-exit when NEW markers
1299
+ # post-agent; pre-existing-markers when
1300
+ # only pre-existing markers — CORR-1;
1301
+ # internal-validator-error when post-
1302
+ # distill mktemp fails — CORR-1 R3 /
1303
+ # SEC-1 R3)
1304
+ # - validate_head_on_default (head-not-on-default on fail)
1305
+ # - validate_commit_count (no-content when 0 commits since startSha)
1306
+ # - detect_local_only (merged-local when origin diverges)
1307
+ #
1308
+ # Salvage at A3 is minimal: write `failed:<reason>` outcome + record
1309
+ # dangling SHA + exit 1. The cleanup trap still runs (worktree+branch
1310
+ # best-effort removal). A4 will replace this with the explicit salvage
1311
+ # helper that force-cleans pre-exit and emits a recovery hint into the
1312
+ # outcome sidecar.
1313
+ #
1314
+ # Reason codes (from the V3 verification report):
1315
+ # markers-after-agent-exit — V1 fail, NEW conflict markers in vault
1316
+ # *.md introduced by the agent's run
1317
+ # pre-existing-markers — V1 fail, ONLY pre-existing markers in
1318
+ # vault *.md (present before agent ran;
1319
+ # not the agent's fault — CORR-1)
1320
+ # internal-validator-error — V1 fail, post-distill mktemp failed so
1321
+ # the marker validator could NOT scan
1322
+ # the vault. Distinct from
1323
+ # markers-after-agent-exit so the user
1324
+ # isn't blamed-via-agent for state
1325
+ # nobody observed (CORR-1 R3 / SEC-1 R3)
1326
+ # head-not-on-default — V2 fail, vault HEAD not on default branch
1327
+ # agent-exit-nonzero — pi exited non-zero with no other diagnostic
1328
+ # agent-timeout — timeout(1) killed the agent (rc 124 or 137)
1329
+ # divergent-history — origin/<default> diverges from local <default>
1330
+ # (typically a teammate's push from another
1331
+ # clone; rarely a force-push). Spec at
1332
+ # "Push behavior: never force" mandates this
1333
+ # wrapper-side ancestry validation — SEC-A-1)
1334
+ #
1335
+ # These four codes match the JS-side dispatch table in
1336
+ # formatOutcomeNotification (extensions/distill/index.ts).
546
1337
 
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
1338
+ # `timeout(1)` exit codes per coreutils:
1339
+ # 124 = timeout fired and target exited within grace period
1340
+ # 137 = timeout sent SIGKILL after grace period (128 + 9)
1341
+ # Other non-zero codes are agent crashes proper.
1342
+ #
1343
+ # Magic-number rationale (per the methodology guide's never-deferrable
1344
+ # magic-number rule): 124 and 137 are coreutils-defined exit codes,
1345
+ # not arbitrary thresholds. Naming them as constants here keeps the
1346
+ # case statement readable.
1347
+ TIMEOUT_TERM_RC=124
1348
+ TIMEOUT_KILL_RC=137
557
1349
 
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"
1350
+ if [ "$AGENT_RC" -eq "$TIMEOUT_TERM_RC" ] || [ "$AGENT_RC" -eq "$TIMEOUT_KILL_RC" ]; then
1351
+ log_error "agent task exceeded ${MAX_DURATION_SECS}s budget; SIGTERM/SIGKILL fired (rc $AGENT_RC)"
1352
+ record_dangling_sha
1353
+ salvage "$VAULT" "$WORKTREE" "$BRANCH" "agent-timeout"
1354
+ exit 1
578
1355
  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
1356
 
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
1357
+ if [ "$AGENT_RC" -ne 0 ]; then
1358
+ log_error "agent subprocess exited non-zero (rc $AGENT_RC); see stderr above"
1359
+ record_dangling_sha
1360
+ salvage "$VAULT" "$WORKTREE" "$BRANCH" "agent-exit-nonzero"
1361
+ exit 1
619
1362
  fi
620
1363
 
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
1364
+ # Agent exit-0 path. Run validators in order: head-on-default first
1365
+ # (cheap; fails loud on detached HEAD or wrong branch), then markers
1366
+ # (slightly more expensive scan), then commit count + local-only
1367
+ # dispatch.
1368
+ if ! validate_head_on_default "$VAULT" "$DEFAULT_BRANCH"; then
1369
+ record_dangling_sha
1370
+ salvage "$VAULT" "$WORKTREE" "$BRANCH" "head-not-on-default"
1371
+ exit 1
630
1372
  fi
631
1373
 
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)"
1374
+ # Marker validation (CORR-A-1, SEC-A-7, CORR-1, CORR-1 R3 / SEC-1 R3).
1375
+ # Four rc paths:
1376
+ # 0 → no markers post-distill, pass
1377
+ # 1 → NEW marker-bearing files (agent-induced) → markers-after-agent-exit
1378
+ # 2 → only pre-existing marker files → pre-existing-markers (NOT
1379
+ # agent-induced; user must fix manually before next distill)
1380
+ # 3 → post-distill mktemp failed; validator could not scan →
1381
+ # internal-validator-error (graceful degradation; do NOT
1382
+ # blame the agent for state nobody observed — CORR-1 R3 /
1383
+ # SEC-1 R3)
1384
+ #
1385
+ # Pass the pre-distill snapshot file so validate_no_markers can do the
1386
+ # diff. PRE_DISTILL_MARKER_FILES_FILE is set to /dev/null upstream when
1387
+ # mktemp failed; validate_no_markers treats /dev/null as "no pre-existing
1388
+ # markers observed" and routes every post-agent marker to
1389
+ # failed:markers-after-agent-exit.
1390
+ validate_no_markers "$VAULT" "$PRE_DISTILL_MARKER_FILES_FILE"
1391
+ MARKER_RC=$?
1392
+ if [ "$MARKER_RC" -eq 1 ]; then
638
1393
  record_dangling_sha
1394
+ salvage "$VAULT" "$WORKTREE" "$BRANCH" "markers-after-agent-exit"
639
1395
  exit 1
640
1396
  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"
1397
+ if [ "$MARKER_RC" -eq 2 ]; then
654
1398
  record_dangling_sha
1399
+ salvage "$VAULT" "$WORKTREE" "$BRANCH" "pre-existing-markers"
1400
+ exit 1
1401
+ fi
1402
+ if [ "$MARKER_RC" -eq 3 ]; then
1403
+ record_dangling_sha
1404
+ salvage "$VAULT" "$WORKTREE" "$BRANCH" "internal-validator-error"
655
1405
  exit 1
656
1406
  fi
657
1407
 
658
- if ! git_retry git merge --squash "$BRANCH" > /dev/null 2>&1; then
659
- log_error "git merge --squash failed"
1408
+ VAULT_COMMIT_COUNT="$(validate_commit_count "$VAULT" "$START_SHA" 2>/dev/null || echo "")"
1409
+ if [ -z "$VAULT_COMMIT_COUNT" ]; then
1410
+ log_error "validate_commit_count returned empty; refusing to classify outcome"
660
1411
  record_dangling_sha
1412
+ salvage "$VAULT" "$WORKTREE" "$BRANCH" "agent-exit-nonzero"
661
1413
  exit 1
662
1414
  fi
663
1415
 
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.
1416
+ if [ "$VAULT_COMMIT_COUNT" -eq 0 ]; then
1417
+ # Genuine no-op — agent ran but produced nothing for main. Outcome
1418
+ # surfaces as a `warning` notification per the locked notification
1419
+ # severity contract.
672
1420
  write_outcome "no-content"
673
1421
  exit 0
674
1422
  fi
675
1423
 
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"
1424
+ # CORR-2 (Phase C Round 1): design.md "Mocked-pi behaviors" #6 — agent
1425
+ # committed 2+ times to default directly (rather than to its branch +
1426
+ # squash-merge). The wrapper accepts the outcome as `merged-content`
1427
+ # (the dispatch is no-content vs has-content; the squash invariant is
1428
+ # a soft suggestion baked into the prompt, not a hard wrapper-side
1429
+ # constraint), but logs a warning so the forensic record reflects
1430
+ # that the squash didn't collapse to one commit. Keeps the design's
1431
+ # spec literally implemented.
1432
+ if [ "$VAULT_COMMIT_COUNT" -gt 1 ]; then
1433
+ log_warning "validate_commit_count: agent landed $VAULT_COMMIT_COUNT commits on $DEFAULT_BRANCH since startSha (squash-invariant violation; expected 1). Outcome accepted as merged-content but the squash didn't collapse to a single commit."
1434
+ fi
1435
+
1436
+ # Run merged-local / divergent-history detection. detect_local_only returns:
1437
+ # 0 — local-only (`merged-local` outcome): origin configured AND
1438
+ # local is ahead of remote in a fast-forwardable way.
1439
+ # 1 — in sync OR no origin configured: proceed to `merged-content`.
1440
+ # 2 — divergent histories (`failed:divergent-history` outcome):
1441
+ # remote is NOT an ancestor of local. Either a teammate's push
1442
+ # to origin from another clone or, more rarely, a force-push
1443
+ # that rewrote origin's history. The agent's safe-recovery
1444
+ # path (pull --no-rebase + push) did not converge, so the
1445
+ # wrapper surfaces it for user inspection (SEC-A-1: spec at
1446
+ # "Push behavior: never force" mandates wrapper-side ancestry
1447
+ # validation; SEC-1/CORR-2 round-2 renamed the reason code
1448
+ # from `force-push-detected` to neutral-on-cause naming).
1449
+ #
1450
+ # Capture rc explicitly because `if detect_local_only … ; then` would
1451
+ # only branch on rc=0 vs rc!=0, collapsing the rc=1 (in sync) and
1452
+ # rc=2 (divergent) cases into the same arm.
1453
+ detect_local_only "$VAULT" "$DEFAULT_BRANCH"
1454
+ LOCAL_ONLY_RC=$?
1455
+ if [ "$LOCAL_ONLY_RC" -eq 0 ]; then
1456
+ # Origin configured but local main is ahead — agent's push didn't
1457
+ # land. Outcome surfaces as `warning` ("distilled but not pushed").
1458
+ write_outcome "merged-local"
1459
+ exit 0
1460
+ fi
1461
+ if [ "$LOCAL_ONLY_RC" -eq 2 ]; then
1462
+ log_error "detect_local_only signaled divergent histories (rc 2) — origin/$DEFAULT_BRANCH and local $DEFAULT_BRANCH share no linear ancestry; agent's pull-merge-push recovery did not converge"
679
1463
  record_dangling_sha
1464
+ salvage "$VAULT" "$WORKTREE" "$BRANCH" "divergent-history"
680
1465
  exit 1
681
1466
  fi
682
1467
 
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
1468
+ # Happy path: vault HEAD on default, no markers, at least one commit
1469
+ # since startSha, and either (a) origin is in sync OR (b) origin not
1470
+ # configured. Surface as `info` ("Distillation complete").
1471
+ write_outcome "merged-content"
692
1472
  exit 0