@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.
- package/README.md +99 -25
- package/extensions/distill/auto-setup.ts +29 -117
- package/extensions/distill/distill-prompt.md +58 -0
- package/extensions/distill/distill-prompt.ts +212 -0
- package/extensions/distill/distill-workspace.ts +115 -211
- package/extensions/distill/index.ts +116 -96
- package/extensions/distill/scripts/distill-wrapper.sh +1080 -300
- package/extensions/distill/scripts-paths.ts +0 -9
- package/package.json +5 -2
- package/extensions/distill/scripts/git_retry.sh +0 -65
- package/extensions/distill/scripts/napkin-distill-merge +0 -455
|
@@ -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>
|
|
10
|
-
# <worktree>
|
|
11
|
-
#
|
|
12
|
-
#
|
|
13
|
-
# <branch>
|
|
14
|
-
# <sessionFork>
|
|
15
|
-
# <prompt>
|
|
16
|
-
#
|
|
17
|
-
# <
|
|
18
|
-
# <
|
|
19
|
-
#
|
|
20
|
-
#
|
|
21
|
-
#
|
|
22
|
-
#
|
|
23
|
-
#
|
|
24
|
-
#
|
|
25
|
-
#
|
|
26
|
-
#
|
|
27
|
-
#
|
|
28
|
-
#
|
|
29
|
-
#
|
|
30
|
-
#
|
|
31
|
-
#
|
|
32
|
-
#
|
|
33
|
-
#
|
|
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>
|
|
40
|
-
#
|
|
41
|
-
#
|
|
42
|
-
#
|
|
43
|
-
#
|
|
44
|
-
#
|
|
45
|
-
#
|
|
46
|
-
#
|
|
47
|
-
#
|
|
48
|
-
#
|
|
49
|
-
#
|
|
50
|
-
#
|
|
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
|
-
#
|
|
66
|
-
#
|
|
67
|
-
#
|
|
68
|
-
#
|
|
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
|
-
#
|
|
87
|
-
#
|
|
88
|
-
#
|
|
89
|
-
#
|
|
90
|
-
#
|
|
91
|
-
#
|
|
92
|
-
#
|
|
93
|
-
#
|
|
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
|
-
#
|
|
101
|
-
|
|
102
|
-
#
|
|
103
|
-
|
|
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
|
-
#
|
|
137
|
-
#
|
|
138
|
-
#
|
|
139
|
-
# and
|
|
140
|
-
|
|
141
|
-
|
|
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
|
-
#
|
|
149
|
-
#
|
|
150
|
-
#
|
|
151
|
-
#
|
|
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;
|
|
172
|
-
#
|
|
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
|
-
#
|
|
195
|
-
#
|
|
196
|
-
#
|
|
197
|
-
#
|
|
198
|
-
#
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
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
|
|
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
|
-
} >> "$
|
|
218
|
-
|
|
350
|
+
} >> "$WARNING_LOG"
|
|
351
|
+
WARNING_LOG_TOUCHED=1
|
|
219
352
|
fi
|
|
220
|
-
echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) $*" >> "$
|
|
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).
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
307
|
-
#
|
|
308
|
-
#
|
|
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).
|
|
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
|
|
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
|
|
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
|
|
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
|
-
# ---
|
|
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
|
-
#
|
|
493
|
-
#
|
|
494
|
-
#
|
|
495
|
-
#
|
|
496
|
-
#
|
|
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 —
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
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
|
-
# ---
|
|
521
|
-
#
|
|
522
|
-
#
|
|
523
|
-
#
|
|
524
|
-
#
|
|
525
|
-
#
|
|
526
|
-
#
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
#
|
|
530
|
-
#
|
|
531
|
-
#
|
|
532
|
-
#
|
|
533
|
-
#
|
|
534
|
-
#
|
|
535
|
-
#
|
|
536
|
-
#
|
|
537
|
-
#
|
|
538
|
-
#
|
|
539
|
-
#
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
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
|
-
#
|
|
548
|
-
#
|
|
549
|
-
#
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
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
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
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
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
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
|
-
#
|
|
622
|
-
#
|
|
623
|
-
#
|
|
624
|
-
#
|
|
625
|
-
if
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
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
|
-
#
|
|
633
|
-
#
|
|
634
|
-
#
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
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
|
-
|
|
659
|
-
|
|
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
|
-
|
|
665
|
-
#
|
|
666
|
-
#
|
|
667
|
-
|
|
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
|
-
|
|
677
|
-
|
|
678
|
-
|
|
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
|
-
#
|
|
684
|
-
#
|
|
685
|
-
#
|
|
686
|
-
|
|
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
|