@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.
@@ -0,0 +1,212 @@
1
+ /**
2
+ * Distill prompt loader.
3
+ *
4
+ * The agent-driven distill prompt lives as markdown at
5
+ * `extensions/distill/distill-prompt.md`, with template placeholders the
6
+ * wrapper resolves at spawn time. This module reads that .md at runtime,
7
+ * substitutes the placeholders, and returns the resolved string for the
8
+ * wrapper to pass to `pi -p`.
9
+ *
10
+ * Why markdown + a loader (PR #12 design — "DISTILL_PROMPT location"):
11
+ * - Easier to edit / iterate the prompt without touching code
12
+ * - Markdown rendering in editors makes the prompt readable as prose
13
+ * - Snapshot tests assert prompt content directly against the .md
14
+ * - Bundled with npm publish via `package.json` `files` entry
15
+ *
16
+ * The loader is strict on placeholder coverage: every required placeholder
17
+ * MUST be present in the .md OR the loader throws. This protects against
18
+ * silent drift where a refactor renames a placeholder in the .md but
19
+ * leaves the TS-side input shape intact, sending an unresolved
20
+ * `{{worktreePath}}` literal to the agent. Per the methodology guide's
21
+ * never-deferrable categories, "stale references to renamed concepts" are
22
+ * a fix-now class — failing fast at load time keeps them out of agent
23
+ * prompts entirely.
24
+ */
25
+
26
+ import * as fs from "node:fs";
27
+ import * as path from "node:path";
28
+ import { fileURLToPath } from "node:url";
29
+
30
+ const _here = path.dirname(fileURLToPath(import.meta.url));
31
+
32
+ /** Absolute path to the distill prompt markdown file. */
33
+ export const DISTILL_PROMPT_PATH: string = path.join(
34
+ _here,
35
+ "distill-prompt.md",
36
+ );
37
+
38
+ /**
39
+ * Inputs to {@link buildDistillPrompt}. All four placeholders MUST be
40
+ * provided; passing an empty string is disallowed because that would
41
+ * produce an agent prompt with `git merge ` (empty branch name) or
42
+ * `cd ` (empty path) — silent corruption rather than fail-fast.
43
+ */
44
+ export interface DistillPromptInputs {
45
+ /** Absolute path to the per-distill git worktree. Substituted for `{{worktreePath}}`. */
46
+ worktreePath: string;
47
+ /** Absolute path to the main vault (the worktree's parent repo). Substituted for `{{vaultPath}}`. */
48
+ vaultPath: string;
49
+ /** Distill branch name, e.g. `distill/abc123-1700000000000`. Substituted for `{{branchName}}`. */
50
+ branchName: string;
51
+ /** Vault's default mainline branch (`main`, `master`, ...). Substituted for `{{defaultBranch}}`. */
52
+ defaultBranch: string;
53
+ }
54
+
55
+ /**
56
+ * Required placeholders the .md template must contain. Order matches the
57
+ * order they appear in the template; the validator below iterates this
58
+ * list to surface a precise diagnostic when one is missing.
59
+ */
60
+ const REQUIRED_PLACEHOLDERS = [
61
+ "{{worktreePath}}",
62
+ "{{vaultPath}}",
63
+ "{{branchName}}",
64
+ "{{defaultBranch}}",
65
+ ] as const;
66
+
67
+ /**
68
+ * Validate a single substitution input. Used for every field of
69
+ * {@link DistillPromptInputs}. Hard rejects:
70
+ *
71
+ * 1. Non-string / empty string — silent prompt corruption (e.g.
72
+ * `git merge ` with empty branch name) is worse than a loud
73
+ * validation throw.
74
+ * 2. ASCII control characters (NUL, BEL, BS, TAB, LF, CR, ESC, DEL,
75
+ * …; the `\x00–\x1F` and `\x7F` ranges). A `\n` in
76
+ * `worktreePath` would inject a newline into the agent's prompt,
77
+ * letting an attacker who controls a single field break out of
78
+ * one prompt-step and inject prose into another (prompt-
79
+ * injection class). NUL bytes truncate strings on most C-side
80
+ * consumers (the wrapper's `printf`, `git`'s argv parsing). TAB
81
+ * isn't strictly malicious but its inclusion in agent prompts
82
+ * breaks the `git -C "<tab>worktree"` quoting we rely on.
83
+ * 3. Mustache-style `{{` or `}}` runs — collide with the
84
+ * placeholder syntax this loader uses. A vault path that
85
+ * contained `{{worktreePath}}` would silently re-substitute
86
+ * itself on a second pass; even though we don't multi-pass
87
+ * today, defending the input shape lets future refactors of
88
+ * the substitution loop stay safe.
89
+ *
90
+ * Defense-in-depth (SEC-A-5): the JS-side caller already controls
91
+ * three of the four inputs (`worktreePath`, `branchName`,
92
+ * `defaultBranch` come from `createDistillWorkspace` /
93
+ * `detectDefaultBranch` which produce well-formed strings).
94
+ * `vaultPath` originates from the user's config but is
95
+ * `path.resolve`d before reaching here. So the realistic threat
96
+ * surface is narrow — but the validator is cheap, the failure mode
97
+ * is "throw with a clear message", and a future caller that bypasses
98
+ * the helpers (or a malformed config) would otherwise let bad input
99
+ * reach the agent prompt.
100
+ *
101
+ * Slashes (`/`), spaces, hyphens, dots, and underscores are all
102
+ * allowed: `feat/foo` branch names and `~/My Vault/notes` paths must
103
+ * pass.
104
+ */
105
+ function validateInput(name: string, value: unknown): asserts value is string {
106
+ if (typeof value !== "string" || value.length === 0) {
107
+ throw new Error(
108
+ `buildDistillPrompt: input '${name}' must be a non-empty string (got ${JSON.stringify(value)})`,
109
+ );
110
+ }
111
+ // Reject ASCII control chars (\x00–\x1F and \x7F). A literal `\n`
112
+ // in any input would break out of the prompt step it's embedded
113
+ // in — classic prompt-injection. JSON.stringify the value in the
114
+ // error so the offending char is visible (escaped) in the message.
115
+ // biome-ignore lint/suspicious/noControlCharactersInRegex: rejecting control chars IS the validator's job
116
+ if (/[\x00-\x1F\x7F]/.test(value)) {
117
+ throw new Error(
118
+ `buildDistillPrompt: input '${name}' contains control characters; reject (got ${JSON.stringify(value)})`,
119
+ );
120
+ }
121
+ // Reject placeholder-syntax collisions. A vault path that contained
122
+ // `{{worktreePath}}` would silently re-substitute on a second pass
123
+ // — defense-in-depth for future refactors of the substitution loop.
124
+ if (value.includes("{{") || value.includes("}}")) {
125
+ throw new Error(
126
+ `buildDistillPrompt: input '${name}' contains placeholder-syntax characters '{{' or '}}' (got ${JSON.stringify(value)})`,
127
+ );
128
+ }
129
+ }
130
+
131
+ /**
132
+ * Read a distill prompt markdown template from `promptPath` and
133
+ * substitute placeholders. The path-injected core of the loader.
134
+ *
135
+ * Test seam (CI-A-5): production callers should use
136
+ * {@link buildDistillPrompt}, which delegates to this helper with
137
+ * {@link DISTILL_PROMPT_PATH}. Tests that need to exercise template
138
+ * error paths (missing placeholder, empty template) point this at a
139
+ * tmpdir copy of the .md so the shipped artifact is never mutated.
140
+ *
141
+ * @throws Error if the .md file is missing, empty, or omits any required
142
+ * placeholder. Throws if any input value is empty (per the
143
+ * {@link DistillPromptInputs} contract).
144
+ *
145
+ * Pure function aside from the .md read: the loader does not cache, so
146
+ * tests that mutate the file (or replace it via mocked fs) see the
147
+ * fresh contents on each call. The .md is small (a few KB); re-reading
148
+ * it on each spawn is cheap relative to the agent task itself (60s+).
149
+ */
150
+ export function buildDistillPromptFromFile(
151
+ promptPath: string,
152
+ inputs: DistillPromptInputs,
153
+ ): string {
154
+ for (const [key, value] of Object.entries(inputs)) {
155
+ validateInput(key, value);
156
+ }
157
+
158
+ let template: string;
159
+ try {
160
+ template = fs.readFileSync(promptPath, "utf-8");
161
+ } catch (err) {
162
+ throw new Error(
163
+ `buildDistillPrompt: failed to read prompt template at ${promptPath}: ${(err as Error).message}`,
164
+ );
165
+ }
166
+ if (template.length === 0) {
167
+ throw new Error(
168
+ `buildDistillPrompt: prompt template at ${promptPath} is empty`,
169
+ );
170
+ }
171
+
172
+ for (const placeholder of REQUIRED_PLACEHOLDERS) {
173
+ if (!template.includes(placeholder)) {
174
+ throw new Error(
175
+ `buildDistillPrompt: prompt template at ${promptPath} is missing required placeholder '${placeholder}'`,
176
+ );
177
+ }
178
+ }
179
+
180
+ // Map placeholder → input key. Keep this aligned with REQUIRED_PLACEHOLDERS
181
+ // so the missing-placeholder error and the substitution loop never drift.
182
+ const substitutions: Array<[string, string]> = [
183
+ ["{{worktreePath}}", inputs.worktreePath],
184
+ ["{{vaultPath}}", inputs.vaultPath],
185
+ ["{{branchName}}", inputs.branchName],
186
+ ["{{defaultBranch}}", inputs.defaultBranch],
187
+ ];
188
+
189
+ let result = template;
190
+ for (const [placeholder, value] of substitutions) {
191
+ // String#replaceAll on each placeholder; values are not regex-special
192
+ // because they're filesystem paths or branch names. Even if a path
193
+ // contained a `$` or `\`, replaceAll on a literal string (not regex)
194
+ // is escape-safe.
195
+ result = result.replaceAll(placeholder, value);
196
+ }
197
+
198
+ return result;
199
+ }
200
+
201
+ /**
202
+ * Read the shipped distill prompt markdown and substitute placeholders.
203
+ * Public API — production callers should use this. Delegates to
204
+ * {@link buildDistillPromptFromFile} with the bundled .md path.
205
+ *
206
+ * @throws Error if the .md file is missing, empty, or omits any required
207
+ * placeholder. Throws if any input value is empty (per the
208
+ * {@link DistillPromptInputs} contract).
209
+ */
210
+ export function buildDistillPrompt(inputs: DistillPromptInputs): string {
211
+ return buildDistillPromptFromFile(DISTILL_PROMPT_PATH, inputs);
212
+ }
@@ -32,8 +32,22 @@ import * as path from "node:path";
32
32
 
33
33
  import { Napkin } from "@cad0p/napkin";
34
34
  import { SessionManager } from "@earendil-works/pi-coding-agent";
35
+ import { buildDistillPrompt } from "./distill-prompt";
36
+ import { DISTILL_WRAPPER_SCRIPT } from "./scripts-paths";
35
37
 
36
- import { DISTILL_WRAPPER_SCRIPT, MERGE_DRIVER_SCRIPT } from "./scripts-paths";
38
+ /**
39
+ * Per-subcommand wall-clock ceiling for `git` invocations from the
40
+ * JS-side. Typical git plumbing returns in milliseconds; this is a
41
+ * generous upper bound that catches truly stuck operations (network
42
+ * hangs, lock contention, fsmonitor wedges) without slowing the happy
43
+ * path. Tuned alongside the distill cleanup-trap budget so a single
44
+ * hung subcommand can't keep the wrapper alive past its overall
45
+ * `timeout(1)` wall-clock budget.
46
+ *
47
+ * Re-exported and consumed by `auto-setup.ts`'s sibling `runGit` so
48
+ * both call sites share a single source of truth.
49
+ */
50
+ export const GIT_SUBCOMMAND_TIMEOUT_MS = 30_000;
37
51
 
38
52
  /**
39
53
  * Error class thrown by distill-workspace operations. Separate class so
@@ -83,9 +97,6 @@ export interface DistillMeta {
83
97
  *
84
98
  * git -C <vaultPath> log --name-only <startSha>..HEAD
85
99
  *
86
- * Also useful for the live `diffWorktreeSinceStart` helper while the
87
- * worktree is still alive (status displays, debugging).
88
- *
89
100
  * Absent on meta.json files written by pre-Phase-C2 code paths — readers
90
101
  * MUST tolerate undefined and fall back to scanning the whole worktree.
91
102
  */
@@ -226,7 +237,7 @@ function runGit(
226
237
  const r = spawnSync("git", args, {
227
238
  cwd,
228
239
  encoding: "utf-8",
229
- timeout: 30_000,
240
+ timeout: GIT_SUBCOMMAND_TIMEOUT_MS,
230
241
  env: process.env,
231
242
  });
232
243
  return {
@@ -236,75 +247,9 @@ function runGit(
236
247
  };
237
248
  }
238
249
 
239
- /**
240
- * Ensure the worktree's local git config has the napkin-distill-merge
241
- * driver registered, and that `.gitattributes` routes `*.md` through it.
242
- *
243
- * Registration is per-worktree (`--local`, stays in the worktree's git config
244
- * dir, never propagates to the main repo or gets committed). The
245
- * `.gitattributes` line is per-file though \u2014 if the vault doesn't already
246
- * have one routing `*.md` through the driver, we append one. The appended
247
- * line gets committed along with the distill's content changes, which is
248
- * fine: committing the merge-driver rule to the vault is what lets the
249
- * driver actually fire during the merge back to main.
250
- *
251
- * Phase C's auto-init will pre-scaffold `.gitattributes` so this append
252
- * becomes a no-op; until then, we self-heal.
253
- */
254
- function registerMergeDriver(worktreePath: string): void {
255
- // Register the driver in local git config. Local config lives in the
256
- // worktree's `.git` file (actually in the main repo's .git/config, since
257
- // worktrees share config by default \u2014 the config applies during all git
258
- // operations from this worktree's perspective).
259
- const nameRes = runGit(worktreePath, [
260
- "config",
261
- "--local",
262
- "merge.napkin-distill-merge.name",
263
- "napkin distill LLM merge driver",
264
- ]);
265
- if (nameRes.status !== 0) {
266
- throw new DistillError(
267
- `failed to configure merge driver name: ${nameRes.stderr.trim()}`,
268
- );
269
- }
270
- // Quote the driver path so spaces / shell metacharacters in the path
271
- // don't break git's sh -c invocation of the driver command, and so a
272
- // malicious path prefix (unlikely locally, possible in CI with a
273
- // runner-controlled workspace path) can't inject arguments.
274
- // Single-quote the path and escape any literal ' as '\''.
275
- const quotedDriverPath = `'${MERGE_DRIVER_SCRIPT.replace(/'/g, "'\\''")}'`;
276
- const driverRes = runGit(worktreePath, [
277
- "config",
278
- "--local",
279
- "merge.napkin-distill-merge.driver",
280
- `${quotedDriverPath} %O %A %B %P`,
281
- ]);
282
- if (driverRes.status !== 0) {
283
- throw new DistillError(
284
- `failed to configure merge driver command: ${driverRes.stderr.trim()}`,
285
- );
286
- }
287
-
288
- // Ensure `*.md merge=napkin-distill-merge` is in .gitattributes. This is
289
- // the bit git consults during `git merge` to pick the driver. If
290
- // .gitattributes is missing or the line isn't present, append it.
291
- const attrsPath = path.join(worktreePath, ".gitattributes");
292
- const attrLine = "*.md merge=napkin-distill-merge";
293
- let existing = "";
294
- if (fs.existsSync(attrsPath)) {
295
- existing = fs.readFileSync(attrsPath, "utf-8");
296
- }
297
- if (!existing.split("\n").some((line) => line.trim() === attrLine)) {
298
- const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
299
- fs.writeFileSync(attrsPath, `${existing}${sep}${attrLine}\n`);
300
- }
301
- }
302
-
303
250
  /**
304
251
  * Create a git worktree at `worktreePath` checked out to a fresh branch
305
- * `branchName` rooted at the vault's HEAD. Registers the napkin-distill-merge
306
- * driver in the worktree's local git config so subsequent `git merge`
307
- * invocations can resolve conflicts via the LLM.
252
+ * `branchName` rooted at the vault's HEAD.
308
253
  *
309
254
  * Precondition: vault is a git repo with at least one commit (HEAD
310
255
  * resolvable). Phase C's auto-init ensures both.
@@ -312,7 +257,6 @@ function registerMergeDriver(worktreePath: string): void {
312
257
  * @throws DistillError if:
313
258
  * - vault has no `.git/` directory
314
259
  * - `git worktree add` exits non-zero (branch collision, dirty state, ...)
315
- * - merge driver registration fails
316
260
  *
317
261
  * @returns absolute worktree path on success (same as input, for chaining).
318
262
  */
@@ -345,7 +289,7 @@ export function createDistillWorktree(
345
289
 
346
290
  // Ensure the parent of worktreePath exists; `git worktree add` requires a
347
291
  // non-existent target directory but will happily create intermediate dirs
348
- // for us \u2014 except when the parent (e.g. the vault's XDG cache root
292
+ // for us — except when the parent (e.g. the vault's XDG cache root
349
293
  // `~/.cache/napkin-distill/<hash>/`) only exists after first use.
350
294
  fs.mkdirSync(path.dirname(worktreePath), { recursive: true });
351
295
 
@@ -363,21 +307,6 @@ export function createDistillWorktree(
363
307
  );
364
308
  }
365
309
 
366
- try {
367
- registerMergeDriver(worktreePath);
368
- } catch (err) {
369
- // Roll back the worktree if driver registration fails \u2014 an unregistered
370
- // worktree would merge with plain conflict markers instead of going
371
- // through the LLM, defeating the point.
372
- try {
373
- runGit(vaultPath, ["worktree", "remove", "--force", worktreePath]);
374
- runGit(vaultPath, ["branch", "-D", branchName]);
375
- } catch {
376
- // ignore
377
- }
378
- throw err;
379
- }
380
-
381
310
  return worktreePath;
382
311
  }
383
312
 
@@ -793,9 +722,9 @@ export function resolveDistillErrorDir(vault: string): string {
793
722
  * Find the wrapper-emitted error log for a specific distill branch, if
794
723
  * any. The wrapper writes ‘forensic’ logs to
795
724
  * `<errorDir>/<ISO-timestamp>-<pid>-<branch-short>.log` whenever it
796
- * fails (missing napkin, pi subprocess error, merge driver 3-strike,
797
- * cd parent_cwd failure, …). Returns the absolute path to the first
798
- * matching log file, or null when no log exists.
725
+ * fails (missing napkin, pi subprocess error, agent timeout, post-call
726
+ * validation failure, cd parent_cwd failure, …). Returns the absolute
727
+ * path to the first matching log file, or null when no log exists.
799
728
  *
800
729
  * `branchShort` is the part after `distill/`, e.g. for
801
730
  * `distill/abc1234-1715198400` pass `abc1234-1715198400`.
@@ -829,34 +758,56 @@ export function findDistillErrorLogForBranch(
829
758
 
830
759
  /**
831
760
  * Find the most recent outcome sidecar for a distill branch. Returns
832
- * `{ class, outcomePath, partialMergeLogPath }` when a `*.outcome` file
833
- * exists for `branchShort`, else null.
761
+ * `{ class, outcomePath }` when a `*.outcome` file exists for
762
+ * `branchShort`, else null.
834
763
  *
835
764
  * The outcome sidecar (POST-CONV-5) is written by the wrapper as the
836
765
  * LAST action before any successful exit-0 path. One-line content is
837
- * the class string: `merged-content` / `no-content` / `partial-merge`.
838
- * Used by the JS-side `runDistillWith` poller to dispatch the right UI
839
- * severity (info vs warn) since multiple `exit 0` wrapper paths
840
- * previously produced the same notification.
766
+ * the class string: `merged-content` / `merged-local` / `no-content` /
767
+ * `failed:<reason>`. Used by the JS-side `runDistillWith` poller to
768
+ * dispatch the right UI severity (info vs warn vs error) since multiple
769
+ * `exit 0` wrapper paths previously produced the same notification.
841
770
  *
842
771
  * Missing outcome AND missing fatal error log = abnormal termination
843
772
  * (SIGKILL / `set -e` / disk full / race) — caller must surface this
844
773
  * as a warn since the wrapper is detached and we have no other signal
845
774
  * channel.
775
+ */
776
+ /**
777
+ * Parsed outcome sidecar shape (POST-CONV-5 / PR #12 A4).
778
+ *
779
+ * One canonical type for the wrapper-emitted outcome record so callers
780
+ * (the `findDistillOutcomeForBranch` reader, the strategy `checkOutcome`
781
+ * callbacks in `index.ts`, the `formatOutcomeNotification` dispatcher)
782
+ * stay in sync as the shape evolves. Hand-redeclaring this shape at
783
+ * each call site causes drift on the next field addition / removal
784
+ * (CLEAN-7); pinning it here makes future changes single-edit.
846
785
  *
847
- * `partialMergeLogPath` is populated when the class is `partial-merge`
848
- * AND a matching `.partial-merge.log` (R8-CC-1) exists in the same
849
- * directory; null otherwise. Caller can read the log to count
850
- * reverted files for the user-facing message.
786
+ * Field semantics:
787
+ * - `outcomeClass`: machine-readable class string (line 1 of the
788
+ * sidecar). Drives UI severity in `formatOutcomeNotification` per
789
+ * the locked notification severity contract
790
+ * (`merged-content`/`merged-local`/`no-content`/`failed:<reason>`).
791
+ * - `outcomePath`: absolute path to the sidecar file on disk. Used
792
+ * by tests (and ad-hoc forensic tooling) that need to inspect the
793
+ * raw bytes; consumers that only want the class/hint can ignore
794
+ * it.
795
+ * - `recoveryHint`: lines 2+ of the sidecar concatenated, or `null`
796
+ * when the wrapper wrote no hint (happy-path classes don't need
797
+ * one; legacy single-line sidecars have none either). Surfaced
798
+ * in the failure notification message so the user sees the
799
+ * recommended recovery action without opening the error log.
851
800
  */
801
+ export interface DistillOutcome {
802
+ outcomeClass: string;
803
+ outcomePath: string;
804
+ recoveryHint: string | null;
805
+ }
806
+
852
807
  export function findDistillOutcomeForBranch(
853
808
  errorDir: string,
854
809
  branchShort: string,
855
- ): {
856
- outcomeClass: string;
857
- outcomePath: string;
858
- partialMergeLogPath: string | null;
859
- } | null {
810
+ ): DistillOutcome | null {
860
811
  if (!fs.existsSync(errorDir)) return null;
861
812
  if (branchShort.length === 0) return null;
862
813
  let entries: string[];
@@ -869,51 +820,26 @@ export function findDistillOutcomeForBranch(
869
820
  const outcomes = entries.filter((f) => f.endsWith(outcomeSuffix)).sort();
870
821
  if (outcomes.length === 0) return null;
871
822
  const outcomePath = path.join(errorDir, outcomes[outcomes.length - 1]);
823
+ // PR #12 A4: outcome sidecar format is multi-line
824
+ // line 1 = outcome class (machine-readable, drives JS-side dispatch)
825
+ // lines 2+ = optional human-readable recovery hint (failed:* only)
826
+ // Pre-PR-12 sidecars are single-line; the split below handles both
827
+ // shapes: `lines[0]` is always the class, `lines.slice(1).join('\n')`
828
+ // is empty for legacy single-line sidecars.
872
829
  let outcomeClass = "";
830
+ let recoveryHint: string | null = null;
873
831
  try {
874
- outcomeClass = fs.readFileSync(outcomePath, "utf-8").trim();
832
+ const raw = fs.readFileSync(outcomePath, "utf-8");
833
+ const lines = raw.split("\n");
834
+ outcomeClass = (lines[0] ?? "").trim();
835
+ const restRaw = lines.slice(1).join("\n").trim();
836
+ recoveryHint = restRaw.length > 0 ? restRaw : null;
875
837
  } catch {
876
838
  // Treat unreadable outcome as missing — caller will fall through to
877
839
  // abnormal-termination handling.
878
840
  return null;
879
841
  }
880
- let partialMergeLogPath: string | null = null;
881
- if (outcomeClass === "partial-merge") {
882
- const pmSuffix = `-${branchShort}.partial-merge.log`;
883
- const pmMatches = entries.filter((f) => f.endsWith(pmSuffix)).sort();
884
- if (pmMatches.length > 0) {
885
- partialMergeLogPath = path.join(
886
- errorDir,
887
- pmMatches[pmMatches.length - 1],
888
- );
889
- }
890
- }
891
- return { outcomeClass, outcomePath, partialMergeLogPath };
892
- }
893
-
894
- /**
895
- * Prefix prepended to the distill prompt only when running through the
896
- * worktree spawn path. Tells the agent its writes must stay inside the
897
- * per-distill worktree — critical because the agent inherits the parent
898
- * session's full message history (which contains absolute paths to the
899
- * MAIN vault) and would otherwise route writes there via `edit`/`write`
900
- * with absolute paths, silently bypassing worktree isolation.
901
- *
902
- * The prefix is added inside `spawnDistillInWorktree` (not at call sites)
903
- * so every worktree-mode caller gets it automatically. Legacy spawn
904
- * (manual /distill on git-less or disabled vaults) does NOT prepend
905
- * this — there's no isolation to preserve there.
906
- *
907
- * Exported for tests; production callers should rely on the implicit
908
- * application inside `spawnDistillInWorktree`.
909
- *
910
- * See POST-R6-CACHE in features/pi-napkin-distill/deferred.md for context.
911
- */
912
- export function buildWorktreeDistillPrompt(
913
- worktreePath: string,
914
- basePrompt: string,
915
- ): string {
916
- return `You are running in an isolated git worktree at ${worktreePath}. Only modify files within the worktree. Do NOT use absolute paths from the conversation history — those refer to the main vault and bypass isolation, causing the distill to silently merge nothing.\n\n${basePrompt}`;
842
+ return { outcomeClass, outcomePath, recoveryHint };
917
843
  }
918
844
 
919
845
  /**
@@ -933,10 +859,20 @@ export interface SpawnDistillOptions {
933
859
  * worktree is handled by the wrapper's napkin shim, NOT cwd resolution.
934
860
  */
935
861
  parentCwd: string;
936
- /** Prompt passed to `pi -p`. */
937
- prompt: string;
938
862
  /** Optional model override, `<provider>/<id>`. Undefined → pi's default. */
939
863
  model?: string;
864
+ /**
865
+ * Hard wall-clock budget (seconds) for the agent's distill+merge+squash+
866
+ * push+cleanup task. Wired into the wrapper's `timeout(1)` invocation so
867
+ * the agent is SIGTERMed (then SIGKILLed after grace) on overrun. Derived
868
+ * from `distill.maxDurationMinutes` (default 10 min = 600s). Must be a
869
+ * positive integer.
870
+ *
871
+ * PR #12 collapses the old per-phase timeouts (distill / per-file merge /
872
+ * squash) into this single agent-task budget — there are no per-phase
873
+ * subprocesses anymore for the wrapper to time-bound separately.
874
+ */
875
+ maxDurationSecs: number;
940
876
  /**
941
877
  * Override for the `spawn` function — wired by unit tests to capture calls
942
878
  * without actually starting processes. Defaults to the node:child_process
@@ -999,20 +935,26 @@ export function detectDefaultBranch(vaultPath: string): string {
999
935
  export function spawnDistillInWorktree(
1000
936
  opts: SpawnDistillOptions,
1001
937
  ): SpawnDistillResult {
1002
- const { vault, sessionFile, parentCwd, prompt, model } = opts;
938
+ const { vault, sessionFile, parentCwd, model, maxDurationSecs } = opts;
1003
939
  const spawnFn = opts.spawnFn ?? spawn;
1004
940
 
1005
941
  const workspace = createDistillWorkspace(vault, sessionFile, parentCwd);
1006
942
 
1007
- // Prepend the worktree-isolation prefix so the agent (which inherits the
1008
- // parent's full conversation context, including absolute paths to the
1009
- // MAIN vault) understands its writes must land in the worktree. This is
1010
- // applied centrally here — every worktree-mode caller benefits without
1011
- // having to remember to opt in.
1012
- const finalPrompt = buildWorktreeDistillPrompt(
1013
- workspace.worktreePath,
1014
- prompt,
1015
- );
943
+ const defaultBranch = detectDefaultBranch(vault);
944
+
945
+ // Build the agent-driven distill prompt by substituting the four
946
+ // placeholders into `extensions/distill/distill-prompt.md`. The .md
947
+ // contains the full agent contract (steps 1–6 distill content + steps
948
+ // 7–10 merge/squash/push/cleanup) plus the worktree-isolation prefix
949
+ // from POST-R6-CACHE — see PR #12 design "Agent contract". The wrapper
950
+ // hands this directly to `pi -p` as the agent's task; PR #12 deletes the
951
+ // per-file merge driver entirely.
952
+ const finalPrompt = buildDistillPrompt({
953
+ worktreePath: workspace.worktreePath,
954
+ vaultPath: vault,
955
+ branchName: workspace.branchName,
956
+ defaultBranch,
957
+ });
1016
958
 
1017
959
  // Error dir lives on the MAIN vault (not in the worktree — worktrees are
1018
960
  // removed on cleanup, which would lose the logs). Resolve via Napkin's
@@ -1030,8 +972,20 @@ export function spawnDistillInWorktree(
1030
972
  finalPrompt,
1031
973
  errorDir,
1032
974
  model ?? "",
1033
- detectDefaultBranch(vault),
975
+ defaultBranch,
1034
976
  parentCwd,
977
+ String(maxDurationSecs),
978
+ // SEC-2 / CORR-3: pass the resolved cache root as an explicit
979
+ // positional arg so the wrapper's safe_rm_worktree path-safety
980
+ // guard can require worktrees to be descendants of THIS cache
981
+ // root (not just any path containing `/napkin-distill/<x>/<y>/`).
982
+ // The JS side is the source of truth — `resolveCacheRoot()` here
983
+ // is the same function that built `workspace.worktreePath`, so
984
+ // a future refactor that changes the cache layout updates both
985
+ // sides at once. Without this arg, the wrapper had to fall back
986
+ // on a glob pattern that any path containing the napkin-distill
987
+ // segment would satisfy.
988
+ resolveCacheRoot(vault),
1035
989
  ];
1036
990
 
1037
991
  // Detached spawn: stdio "ignore" + unref() so the parent can exit cleanly
@@ -1246,65 +1200,15 @@ function toActiveDistills(
1246
1200
  return active;
1247
1201
  }
1248
1202
 
1249
- /**
1250
- * Return the list of files an active distill worktree has changed since
1251
- * it forked from the vault's HEAD. Used by live diagnostic surfaces
1252
- * (status, debugging) while the worktree exists.
1253
- *
1254
- * For the per-distill-completion overlap notice (R7-PERF-2) the worktree
1255
- * is already gone by the time we look — use
1256
- * `getDistillTouchedFilesPostSquash(vault, startSha)` instead, which
1257
- * runs against the main vault's commit log.
1258
- *
1259
- * Strategy:
1260
- * - When `startSha` is recorded in meta.json (Phase C2+), diff
1261
- * `<startSha>..HEAD` inside the worktree. That gives exactly the set
1262
- * of files the distill has committed.
1263
- * - When `startSha` is absent (legacy meta.json), fall back to
1264
- * `git status --porcelain` inside the worktree — captures both
1265
- * committed-and-not-merged AND uncommitted changes. Less precise but
1266
- * still useful for overlap detection.
1267
- *
1268
- * All paths are returned relative to the worktree root (which is the same
1269
- * as the vault root from a tracking perspective). Returns `[]` on any
1270
- * error — overlap detection is best-effort and must not throw.
1271
- */
1272
- export function diffWorktreeSinceStart(
1273
- active: Pick<ActiveDistill, "worktreePath" | "startSha">,
1274
- ): string[] {
1275
- if (!fs.existsSync(active.worktreePath)) return [];
1276
- if (active.startSha) {
1277
- const r = runGit(active.worktreePath, [
1278
- "diff",
1279
- "--name-only",
1280
- `${active.startSha}..HEAD`,
1281
- ]);
1282
- if (r.status !== 0) return [];
1283
- return r.stdout
1284
- .split("\n")
1285
- .map((l) => l.trim())
1286
- .filter((l) => l.length > 0);
1287
- }
1288
- // Legacy fallback: uncommitted + committed changes (porcelain lists both).
1289
- // Format: `XY path` where XY is the 2-char status code.
1290
- const r = runGit(active.worktreePath, ["status", "--porcelain"]);
1291
- if (r.status !== 0) return [];
1292
- return r.stdout
1293
- .split("\n")
1294
- .map((l) => l.slice(3).trim())
1295
- .filter((l) => l.length > 0);
1296
- }
1297
-
1298
1203
  /**
1299
1204
  * Return the list of files affected by commits in the main vault between
1300
1205
  * `startSha` (the distill's fork point) and HEAD (post-squash, after the
1301
1206
  * wrapper's squash-merge has landed). Used by per-completion overlap
1302
1207
  * detection (R7-PERF-2) to compare against the parent session's writes.
1303
1208
  *
1304
- * Unlike `diffWorktreeSinceStart`, this runs against the MAIN vault —
1305
- * the distill worktree has been removed by the time we're called. The
1306
- * squash commit on main brings every file the distill affected into
1307
- * `<startSha>..HEAD`'s name range.
1209
+ * Runs against the MAIN vault — the distill worktree has been removed by
1210
+ * the time we're called. The squash commit on main brings every file the
1211
+ * distill affected into `<startSha>..HEAD`'s name range.
1308
1212
  *
1309
1213
  * If `startSha` is missing (legacy distill meta) we cannot reliably
1310
1214
  * compute the post-squash file set without scanning the now-removed