@cad0p/pi-napkin 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1344 @@
1
+ /**
2
+ * Per-distill workspace management.
3
+ *
4
+ * Each auto-distill invocation gets its own isolated git worktree so
5
+ * concurrent distills (interval, shutdown, or multiple pi sessions) don't
6
+ * race on vault files. Napkin resolves the vault from cwd, so a subprocess
7
+ * launched with cwd = worktree operates on the worktree's copy of the vault.
8
+ *
9
+ * Layout per worktree:
10
+ * <worktree-root>/
11
+ * .napkin/
12
+ * distill/
13
+ * session.jsonl # forked session, pi subprocess reads this
14
+ * meta.json # DistillMeta, see below
15
+ *
16
+ * Lifecycle:
17
+ * createDistillWorkspace(vault, sessionFile)
18
+ * \u2192 createDistillWorktree(vault, branch, path) (git worktree add -b ...)
19
+ * \u2192 SessionManager.forkFrom \u2192 session.jsonl
20
+ * \u2192 write meta.json
21
+ * ... distill subprocess runs in worktree ...
22
+ * removeDistillWorktree(vault, worktreePath, branch)
23
+ * \u2192 git worktree remove --force <path>
24
+ * \u2192 git branch -D <branch>
25
+ */
26
+
27
+ import { spawn, spawnSync } from "node:child_process";
28
+ import { createHash, randomBytes } from "node:crypto";
29
+ import * as fs from "node:fs";
30
+ import * as os from "node:os";
31
+ import * as path from "node:path";
32
+
33
+ import { Napkin } from "@cad0p/napkin";
34
+ import { SessionManager } from "@earendil-works/pi-coding-agent";
35
+
36
+ import { DISTILL_WRAPPER_SCRIPT, MERGE_DRIVER_SCRIPT } from "./scripts-paths";
37
+
38
+ /**
39
+ * Error class thrown by distill-workspace operations. Separate class so
40
+ * callers can distinguish workspace-layer failures (worktree / git / fs)
41
+ * from generic Errors raised by the stdlib.
42
+ */
43
+ export class DistillError extends Error {
44
+ constructor(message: string) {
45
+ super(message);
46
+ this.name = "DistillError";
47
+ }
48
+ }
49
+
50
+ /**
51
+ * Metadata written to each distill workspace's `meta.json`. Consumed by the
52
+ * Phase C `/distill-status` command and the forensic error-log path: if a
53
+ * distill crashes, the on-disk meta plus the dangling branch SHA let us
54
+ * recover the work or at least explain it.
55
+ *
56
+ * Schema is append-only. Readers MUST tolerate unknown fields.
57
+ */
58
+ export interface DistillMeta {
59
+ /**
60
+ * PID of the detached wrapper shell. Written first as a pre-spawn
61
+ * placeholder (= `process.pid` of the parent pi session) by
62
+ * `createDistillWorkspace`, then OVERWRITTEN by the wrapper itself
63
+ * (`$$`) immediately after it installs its cleanup trap. Readers see the
64
+ * wrapper's pid for the vast majority of the distill's lifetime; only a
65
+ * brief window (≲ 100ms between JS write and wrapper's rewrite) shows the
66
+ * parent pid. Liveness checks (`/distill-status.alive`,
67
+ * `cleanupStaleWorktrees`) use this field via `process.kill(pid, 0)`.
68
+ */
69
+ pid: number;
70
+ /** Absolute path to the main vault (NOT the worktree). */
71
+ vault: string;
72
+ /** Git branch name created for this distill, e.g. `distill/a1b2c3-1715198400`. */
73
+ branch: string;
74
+ /** ISO-8601 timestamp when the workspace was created. */
75
+ startedAt: string;
76
+ /** Absolute path to the parent session's .jsonl (for traceability). */
77
+ parentSession: string;
78
+ /**
79
+ * HEAD commit SHA (in the main repo) at the moment the worktree was
80
+ * created. Used by per-distill-completion overlap detection to enumerate
81
+ * exactly the files the distill affected (post-squash, from the main
82
+ * vault):
83
+ *
84
+ * git -C <vaultPath> log --name-only <startSha>..HEAD
85
+ *
86
+ * Also useful for the live `diffWorktreeSinceStart` helper while the
87
+ * worktree is still alive (status displays, debugging).
88
+ *
89
+ * Absent on meta.json files written by pre-Phase-C2 code paths — readers
90
+ * MUST tolerate undefined and fall back to scanning the whole worktree.
91
+ */
92
+ startSha?: string;
93
+ }
94
+
95
+ /**
96
+ * Handle returned by `createDistillWorkspace`. All paths are absolute and
97
+ * live inside the worktree root.
98
+ */
99
+ export interface DistillWorkspace {
100
+ /** Worktree root (the `cwd` for the distill subprocess). */
101
+ worktreePath: string;
102
+ /** Branch name created for this distill (unique per invocation). */
103
+ branchName: string;
104
+ /** Path to the forked session .jsonl inside the worktree. */
105
+ sessionForkPath: string;
106
+ /** Path to meta.json inside the worktree. */
107
+ metaPath: string;
108
+ /**
109
+ * Vault HEAD SHA at workspace-creation time — the distill's fork point.
110
+ * Used by per-completion overlap detection (R7-PERF-2): once the distill
111
+ * has squash-merged onto main, `git log --name-only <startSha>..HEAD`
112
+ * from the main vault enumerates exactly the files the distill
113
+ * affected. Undefined if HEAD couldn't be resolved at creation time
114
+ * (e.g. fresh repo with no commits) — callers must tolerate that.
115
+ */
116
+ startSha?: string;
117
+ }
118
+
119
+ /**
120
+ * Generate a unique branch name per distill invocation. Format:
121
+ * distill/<6-hex-nonce>-<epoch-seconds>
122
+ *
123
+ * Nonce prevents collisions when two distills fire in the same second (unlikely
124
+ * but cheap to prevent; relying on timestamp alone is a latent race).
125
+ */
126
+ export function generateDistillBranchName(
127
+ now: Date = new Date(),
128
+ nonceHex?: string,
129
+ ): string {
130
+ const nonce = nonceHex ?? randomBytes(3).toString("hex");
131
+ const epoch = Math.floor(now.getTime() / 1000);
132
+ return `distill/${nonce}-${epoch}`;
133
+ }
134
+
135
+ /**
136
+ * Relative path (from worktree root) of the distill `.napkin/distill/` dir.
137
+ */
138
+ export const DISTILL_SUBDIR = path.join(".napkin", "distill");
139
+
140
+ /**
141
+ * Resolve the root directory where this vault's distill worktrees live.
142
+ * Follows XDG Base Directory Spec: `~/.cache/napkin-distill/<hash>/` by
143
+ * default, `$XDG_CACHE_HOME/napkin-distill/<hash>/` when set.
144
+ *
145
+ * `<hash>` is the first 16 hex chars of sha256(vaultContentPath) — stable
146
+ * per vault, unique across vaults. Prevents worktrees from two different
147
+ * vaults colliding under the same cache dir while keeping the path short
148
+ * and inspectable.
149
+ *
150
+ * Worktree placement outside the vault is deliberate:
151
+ * - Cloud-sync pollution: OneDrive/Dropbox don't respect `.gitignore`;
152
+ * in-vault worktrees would upload tens of MB per distill spawn.
153
+ * - Filesystem-walker pollution: Obsidian plugins and `find` descend
154
+ * into worktrees and would see N full vault copies for N concurrent
155
+ * distills.
156
+ * - Autocommit-cron noise: a vault's autocommit hook can surface
157
+ * in-vault worktrees as gitlinks under some command sequences.
158
+ * - Git convention: git-worktree docs show worktrees as siblings of
159
+ * the main repo, never nested inside it.
160
+ * - Safety escape hatch: `rm -rf ~/.cache/napkin-distill/<hash>/` is
161
+ * always safe — anything valuable is already on main or was never
162
+ * going to commit.
163
+ *
164
+ * @param vaultContentPath Absolute path to the vault's content root
165
+ * (`napkin.vault.contentPath`, NOT configPath — they're distinct in
166
+ * subdir layout and we want one hash per vault, not per config dir).
167
+ *
168
+ * The path is canonicalised through `fs.realpathSync` before hashing so
169
+ * equivalent paths that differ only in symlink presence (e.g.
170
+ * `~/workplace` → `/workplace/pcad`) resolve to the same cache dir. A
171
+ * stale symlink (ENOENT) falls back to the raw path so the caller sees
172
+ * a deterministic hash rather than an unrelated throw.
173
+ */
174
+ export function resolveCacheRoot(vaultContentPath: string): string {
175
+ const cacheHome =
176
+ process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
177
+ let canonical: string;
178
+ try {
179
+ canonical = fs.realpathSync(vaultContentPath);
180
+ } catch {
181
+ // Broken symlink, missing dir, or permission error — fall back to the
182
+ // raw path. Produces a stable hash for the same input even if the
183
+ // realpath machinery is unavailable; worst case is that two different
184
+ // views of the same vault hash to different cache dirs, which is the
185
+ // pre-R4-L-1 behaviour.
186
+ canonical = vaultContentPath;
187
+ }
188
+ const vaultHash = createHash("sha256")
189
+ .update(canonical)
190
+ .digest("hex")
191
+ .slice(0, 16);
192
+ return path.join(cacheHome, "napkin-distill", vaultHash);
193
+ }
194
+
195
+ /**
196
+ * Throws `DistillError` if `vaultPath` is not a git repository. Phase B
197
+ * requires auto-distill to run in a git context; Phase C's auto-init wires
198
+ * session_start so this throw should never fire in practice for
199
+ * distill.enabled vaults.
200
+ */
201
+ function assertVaultIsGitRepo(vaultPath: string): void {
202
+ const gitDir = path.join(vaultPath, ".git");
203
+ if (!fs.existsSync(gitDir)) {
204
+ throw new DistillError(
205
+ `vault not a git repo: ${vaultPath} (auto-distill requires git; Phase C wires auto-init)`,
206
+ );
207
+ }
208
+ }
209
+
210
+ /**
211
+ * Invoke `git` inside a specific cwd. Returns `{status, stdout, stderr}`.
212
+ * Does not throw on non-zero exit \u2014 callers decide how to react (retry,
213
+ * translate to DistillError, ignore, \u2026). 30s timeout per call is a sanity
214
+ * ceiling; normal git invocations complete in milliseconds.
215
+ *
216
+ * `env: process.env` is required for Bun: unlike Node, Bun's spawnSync
217
+ * does NOT propagate mutations to `process.env` to the child unless
218
+ * `env` is passed explicitly (it snapshots env at runtime startup).
219
+ * Without this, tests that manipulate PATH (e.g. to shim `git`) would
220
+ * silently exec the real git. Matches the same fix in `auto-setup.ts`.
221
+ */
222
+ function runGit(
223
+ cwd: string,
224
+ args: string[],
225
+ ): { status: number | null; stdout: string; stderr: string } {
226
+ const r = spawnSync("git", args, {
227
+ cwd,
228
+ encoding: "utf-8",
229
+ timeout: 30_000,
230
+ env: process.env,
231
+ });
232
+ return {
233
+ status: r.status,
234
+ stdout: r.stdout ?? "",
235
+ stderr: r.stderr ?? "",
236
+ };
237
+ }
238
+
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
+ /**
304
+ * 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.
308
+ *
309
+ * Precondition: vault is a git repo with at least one commit (HEAD
310
+ * resolvable). Phase C's auto-init ensures both.
311
+ *
312
+ * @throws DistillError if:
313
+ * - vault has no `.git/` directory
314
+ * - `git worktree add` exits non-zero (branch collision, dirty state, ...)
315
+ * - merge driver registration fails
316
+ *
317
+ * @returns absolute worktree path on success (same as input, for chaining).
318
+ */
319
+ export function createDistillWorktree(
320
+ vaultPath: string,
321
+ branchName: string,
322
+ worktreePath: string,
323
+ ): string {
324
+ assertVaultIsGitRepo(vaultPath);
325
+
326
+ // Verify HEAD resolves to a valid commit. An empty repo (git init
327
+ // without any commit) has .git/HEAD pointing at refs/heads/main but no
328
+ // commits to resolve to. `git worktree add ... HEAD` fails with exit
329
+ // 128: "fatal: invalid reference: HEAD". Surface this as a DistillError
330
+ // the caller can catch and log gracefully rather than a cryptic git
331
+ // exit.
332
+ //
333
+ // auto-setup seeds an empty commit so the happy path never hits this,
334
+ // but the guard stays cheap and catches vaults where .git came from
335
+ // outside auto-setup (user's own `git init`, brazil workspace
336
+ // scaffolding, etc.) and never got a commit.
337
+ const headCheck = runGit(vaultPath, ["rev-parse", "--verify", "HEAD"]);
338
+ if (headCheck.status !== 0) {
339
+ throw new DistillError(
340
+ `vault git repo has no commits yet (HEAD unresolvable); ` +
341
+ `auto-distill can't create a worktree. Make an initial commit in ` +
342
+ `${vaultPath} before using auto-distill, or rerun setup.`,
343
+ );
344
+ }
345
+
346
+ // Ensure the parent of worktreePath exists; `git worktree add` requires a
347
+ // 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
349
+ // `~/.cache/napkin-distill/<hash>/`) only exists after first use.
350
+ fs.mkdirSync(path.dirname(worktreePath), { recursive: true });
351
+
352
+ const res = runGit(vaultPath, [
353
+ "worktree",
354
+ "add",
355
+ "-b",
356
+ branchName,
357
+ worktreePath,
358
+ "HEAD",
359
+ ]);
360
+ if (res.status !== 0) {
361
+ throw new DistillError(
362
+ `git worktree add failed (exit ${res.status}): ${res.stderr.trim() || res.stdout.trim()}`,
363
+ );
364
+ }
365
+
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
+ return worktreePath;
382
+ }
383
+
384
+ /**
385
+ * Remove a distill worktree and delete its branch. Idempotent \u2014 logs and
386
+ * swallows errors because cleanup runs in shutdown / trap contexts where
387
+ * throwing would mask more interesting failures upstream.
388
+ *
389
+ * Order matters: remove the worktree first (which releases the branch), then
390
+ * delete the branch. Calling `git branch -D` while a worktree still holds
391
+ * the branch fails.
392
+ */
393
+ export function removeDistillWorktree(
394
+ vaultPath: string,
395
+ worktreePath: string,
396
+ branchName: string,
397
+ ): void {
398
+ // Guard: vault may have been deleted between spawn and cleanup. Don't
399
+ // throw \u2014 treat as "nothing to clean up".
400
+ if (!fs.existsSync(path.join(vaultPath, ".git"))) return;
401
+
402
+ const rmRes = runGit(vaultPath, [
403
+ "worktree",
404
+ "remove",
405
+ "--force",
406
+ worktreePath,
407
+ ]);
408
+ // If worktree removal fails, try to prune stale entries and continue on to
409
+ // branch deletion; leaving a dangling branch is worse than a stale worktree.
410
+ if (rmRes.status !== 0) {
411
+ runGit(vaultPath, ["worktree", "prune"]);
412
+ }
413
+
414
+ // -D (force) in case the branch has unmerged content (expected: the squash
415
+ // merge to main doesn't mark it as merged).
416
+ runGit(vaultPath, ["branch", "-D", branchName]);
417
+
418
+ // Best-effort rmdir of the parent vault-hash dir. rmdir is non-recursive
419
+ // and only succeeds when the parent is empty (i.e. this was the last
420
+ // distill for this vault).
421
+ try {
422
+ fs.rmdirSync(path.dirname(worktreePath));
423
+ } catch {
424
+ // ENOTEMPTY (other concurrent distills exist for this vault) and
425
+ // ENOENT (race) are expected and benign. Other I/O errors swallowed
426
+ // per this function's idempotent shutdown-context contract.
427
+ }
428
+ }
429
+
430
+ /**
431
+ * Create a distill workspace = a fresh git worktree + session fork + meta.
432
+ *
433
+ * Workflow:
434
+ * 1. Pick a unique branch name (`distill/<hex>-<epoch>`).
435
+ * 2. Compute worktree path: `<cacheRoot>/<branch-suffix>/` where
436
+ * `cacheRoot = resolveCacheRoot(vault)` (XDG cache; outside vault).
437
+ * 3. `git worktree add -b <branch> <path> HEAD`.
438
+ * 4. Make `<wt>/.napkin/distill/`, fork the source session into it, write
439
+ * meta.json.
440
+ * 5. Return handle.
441
+ *
442
+ * On failure at any step after the worktree exists, the worktree + branch are
443
+ * torn down via `removeDistillWorktree` so we never leak on throw.
444
+ *
445
+ * @param vault Absolute path to the vault's content root (NOT a
446
+ * worktree, NOT configPath). Used as the input to
447
+ * the vault-hash so multi-vault setups isolate
448
+ * cleanly.
449
+ * @param sourceSessionFile Absolute path to the parent session .jsonl.
450
+ * @param parentCwd Absolute path of the parent pi session's cwd.
451
+ * Pinned into the fork header so the distill
452
+ * subprocess's system prompt `Current working
453
+ * directory:` line matches the parent's,
454
+ * preserving prompt-cache hits across the spawn.
455
+ * Routing of vault writes to the worktree happens
456
+ * via the wrapper's per-distill `napkin` shim,
457
+ * NOT cwd-based vault resolution. See
458
+ * POST-R6-CACHE in features/pi-napkin-distill/deferred.md.
459
+ *
460
+ * @throws DistillError if vault isn't a git repo, worktree creation fails,
461
+ * or session fork fails.
462
+ */
463
+ export function createDistillWorkspace(
464
+ vault: string,
465
+ sourceSessionFile: string,
466
+ parentCwd: string,
467
+ ): DistillWorkspace {
468
+ assertVaultIsGitRepo(vault);
469
+
470
+ // parentCwd is load-bearing for prompt-cache parity (POST-R6-CACHE):
471
+ // pi is spawned at parentCwd so the session-fork header and the
472
+ // resulting system prompt's `Current working directory:` line stay
473
+ // byte-identical to the parent's. A relative path or a stale path
474
+ // that doesn't exist would silently degrade to the wrapper's
475
+ // `cd $PARENT_CWD || exit 1` graceful failure (UI-silent, error log
476
+ // only). Validate up-front so the caller gets a clear DistillError
477
+ // instead. (R7-SC-12, R7-CC-7.)
478
+ if (!path.isAbsolute(parentCwd)) {
479
+ throw new DistillError(
480
+ `parentCwd must be an absolute path, got: ${parentCwd}`,
481
+ );
482
+ }
483
+ if (!fs.existsSync(parentCwd)) {
484
+ throw new DistillError(`parentCwd does not exist: ${parentCwd}`);
485
+ }
486
+
487
+ const branchName = generateDistillBranchName();
488
+ const branchSuffix = branchName.slice("distill/".length);
489
+ // Worktree lives OUTSIDE the vault, under the user's XDG cache dir. See
490
+ // `resolveCacheRoot` for the full rationale (cloud-sync pollution,
491
+ // autocommit-cron noise, plugin re-indexing). `git worktree list`
492
+ // still enumerates these correctly regardless of placement.
493
+ const worktreePath = path.join(resolveCacheRoot(vault), branchSuffix);
494
+
495
+ // Capture HEAD SHA BEFORE the worktree is created so meta.json records
496
+ // the exact commit the distill started from. Used by per-completion
497
+ // overlap detection (R7-PERF-2): after the wrapper squash-merges onto
498
+ // main, `git log --name-only <startSha>..HEAD` from the main vault
499
+ // enumerates exactly the files the distill affected.
500
+ // Failure to resolve HEAD is not fatal — leave `startSha` undefined.
501
+ let startSha: string | undefined;
502
+ {
503
+ const headRes = runGit(vault, ["rev-parse", "HEAD"]);
504
+ if (headRes.status === 0) {
505
+ const sha = headRes.stdout.trim();
506
+ if (/^[0-9a-f]{7,64}$/.test(sha)) startSha = sha;
507
+ }
508
+ }
509
+
510
+ createDistillWorktree(vault, branchName, worktreePath);
511
+
512
+ try {
513
+ const distillDir = path.join(worktreePath, DISTILL_SUBDIR);
514
+ fs.mkdirSync(distillDir, { recursive: true });
515
+
516
+ // SessionManager.forkFrom writes to <sessionDir>/<uuid>.jsonl. We want a
517
+ // deterministic name (`session.jsonl`) so the wrapper script can reference
518
+ // it without globbing.
519
+ //
520
+ // Target cwd is the PARENT's cwd, not the worktree path — see the
521
+ // `parentCwd` parameter docstring above for the full rationale.
522
+ const forkedSm = SessionManager.forkFrom(
523
+ sourceSessionFile,
524
+ parentCwd,
525
+ distillDir,
526
+ );
527
+ const forkedFile = forkedSm.getSessionFile();
528
+ if (!forkedFile) {
529
+ throw new DistillError(
530
+ "SessionManager.forkFrom did not produce a session file",
531
+ );
532
+ }
533
+
534
+ const sessionForkPath = path.join(distillDir, "session.jsonl");
535
+ if (forkedFile !== sessionForkPath) {
536
+ if (fs.existsSync(sessionForkPath)) {
537
+ fs.rmSync(sessionForkPath, { force: true });
538
+ }
539
+ fs.renameSync(forkedFile, sessionForkPath);
540
+ }
541
+
542
+ const metaPath = path.join(distillDir, "meta.json");
543
+ const meta: DistillMeta = {
544
+ pid: process.pid,
545
+ vault,
546
+ branch: branchName,
547
+ startedAt: new Date().toISOString(),
548
+ parentSession: sourceSessionFile,
549
+ startSha,
550
+ };
551
+ fs.writeFileSync(metaPath, `${JSON.stringify(meta, null, 2)}\n`);
552
+
553
+ return { worktreePath, branchName, sessionForkPath, metaPath, startSha };
554
+ } catch (err) {
555
+ // Roll back worktree + branch so we never leak on failure. The cleanup is
556
+ // itself best-effort; if it fails, the original error is what the caller
557
+ // cares about.
558
+ try {
559
+ removeDistillWorktree(vault, worktreePath, branchName);
560
+ } catch {
561
+ // ignore
562
+ }
563
+ throw err;
564
+ }
565
+ }
566
+
567
+ /**
568
+ * Remove a distill workspace. Idempotent: safe to call on partial state and
569
+ * on a path that doesn't exist. Used by the `sh -c` wrapper's trap.
570
+ *
571
+ * Handles both the worktree + branch AND any leftover files inside the
572
+ * worktree path (e.g., if the worktree was partially torn down by git but the
573
+ * directory lingers).
574
+ */
575
+ export function cleanupDistillWorkspace(
576
+ vault: string,
577
+ workspace: Pick<DistillWorkspace, "worktreePath" | "branchName">,
578
+ ): void {
579
+ removeDistillWorktree(vault, workspace.worktreePath, workspace.branchName);
580
+ // Best-effort remove any leftover directory (git worktree remove normally
581
+ // deletes it, but if the worktree was corrupted it may still exist).
582
+ if (fs.existsSync(workspace.worktreePath)) {
583
+ fs.rmSync(workspace.worktreePath, { recursive: true, force: true });
584
+ }
585
+ }
586
+
587
+ /**
588
+ * Parse `git worktree list --porcelain` output into a list of
589
+ * `{ path, branch }` pairs. Only returns entries that have a branch (skips
590
+ * detached-HEAD worktrees — we never create those for distills).
591
+ *
592
+ * Porcelain format is newline-separated records, each record is a block of
593
+ * `key value` lines terminated by a blank line. We care about `worktree`
594
+ * (absolute path) and `branch` (full ref, e.g. `refs/heads/distill/abc-1`).
595
+ */
596
+ export function parseWorktreeList(
597
+ porcelain: string,
598
+ ): Array<{ path: string; branch: string }> {
599
+ const out: Array<{ path: string; branch: string }> = [];
600
+ let wt: string | null = null;
601
+ let branch: string | null = null;
602
+ const flush = () => {
603
+ if (wt && branch) out.push({ path: wt, branch });
604
+ wt = null;
605
+ branch = null;
606
+ };
607
+ for (const line of porcelain.split("\n")) {
608
+ if (line === "") {
609
+ flush();
610
+ continue;
611
+ }
612
+ if (line.startsWith("worktree ")) wt = line.slice("worktree ".length);
613
+ else if (line.startsWith("branch "))
614
+ branch = line.slice("branch ".length).replace(/^refs\/heads\//, "");
615
+ }
616
+ flush();
617
+ return out;
618
+ }
619
+
620
+ /**
621
+ * Liveness check: returns true if `pid` refers to a running process this
622
+ * user can see. Uses signal 0 (no-op) — throws ESRCH when the pid is dead,
623
+ * EPERM when it exists but is owned by another user (still "alive" from our
624
+ * perspective — don't clean up someone else's worktree).
625
+ */
626
+ function isPidAlive(pid: number): boolean {
627
+ try {
628
+ process.kill(pid, 0);
629
+ return true;
630
+ } catch (err) {
631
+ const e = err as NodeJS.ErrnoException;
632
+ // EPERM = exists but not signalable. Treat as alive (don't clobber).
633
+ return e.code === "EPERM";
634
+ }
635
+ }
636
+
637
+ /**
638
+ * Number of minutes past which a worktree with a stale mtime on its
639
+ * meta.json is considered abandoned — even if its pid is still alive.
640
+ *
641
+ * Covers the `distill.maxDurationMinutes` config (10 minutes by
642
+ * default; read in the extension factory via `getMaxDistillDurationMs`)
643
+ * with a 6× margin, so a worktree older than this either crashed
644
+ * silently, lost its pid (e.g. kernel reboot), or somehow outlived its
645
+ * shutdown timeout. The window is deliberately generous: a false-positive
646
+ * here would clobber a slow-but-live distill, whereas waiting an extra
647
+ * 50 minutes to sweep a dead one is harmless.
648
+ */
649
+ export const STALE_WORKTREE_MINUTES = 60;
650
+
651
+ /**
652
+ * Same threshold expressed in milliseconds for the mtime comparison site.
653
+ * Kept as a separate export because existing callers (and tests) already
654
+ * import `STALE_META_AGE_MS` directly.
655
+ */
656
+ export const STALE_META_AGE_MS = STALE_WORKTREE_MINUTES * 60 * 1000;
657
+
658
+ /**
659
+ * VaultInfo-shaped handle this module accepts. We rely only on `contentPath`
660
+ * (the vault root = the git main worktree root) — kept minimal so tests and
661
+ * callers don't have to construct a full Napkin instance.
662
+ */
663
+ export interface StaleCleanupVault {
664
+ contentPath: string;
665
+ }
666
+
667
+ /**
668
+ * Remove distill worktrees that belong to dead sessions. Intended to run
669
+ * once per `session_start` so long-lived vaults don't accumulate debris
670
+ * from crashed pi instances.
671
+ *
672
+ * A worktree (branch matches `^distill/.*`) is removed if ANY of:
673
+ * 1. `<wt>/.napkin/distill/meta.json` is missing
674
+ * 2. meta.json's `pid` is not a running process
675
+ * 3. meta.json's mtime is older than STALE_META_AGE_MS
676
+ *
677
+ * Removal is best-effort: failures on one worktree don't abort the sweep.
678
+ *
679
+ * @returns number of worktrees removed.
680
+ */
681
+ export function cleanupStaleWorktrees(vault: StaleCleanupVault): number {
682
+ const vaultPath = vault.contentPath;
683
+ // No git in the vault → nothing to clean up. session_start may call us
684
+ // before auto-init runs on first launch.
685
+ if (!fs.existsSync(path.join(vaultPath, ".git"))) return 0;
686
+
687
+ const listRes = runGit(vaultPath, ["worktree", "list", "--porcelain"]);
688
+ if (listRes.status !== 0) return 0;
689
+
690
+ const entries = parseWorktreeList(listRes.stdout).filter((e) =>
691
+ e.branch.startsWith("distill/"),
692
+ );
693
+
694
+ let removed = 0;
695
+ for (const entry of entries) {
696
+ try {
697
+ const metaPath = path.join(entry.path, DISTILL_SUBDIR, "meta.json");
698
+ let shouldRemove = false;
699
+
700
+ if (!fs.existsSync(metaPath)) {
701
+ shouldRemove = true;
702
+ } else {
703
+ let mtime = 0;
704
+ try {
705
+ mtime = fs.statSync(metaPath).mtimeMs;
706
+ } catch {
707
+ shouldRemove = true;
708
+ }
709
+ if (!shouldRemove) {
710
+ const meta = readDistillMeta(entry.path);
711
+ if (!meta) {
712
+ shouldRemove = true;
713
+ } else if (!isPidAlive(meta.pid)) {
714
+ shouldRemove = true;
715
+ } else if (Date.now() - mtime > STALE_META_AGE_MS) {
716
+ shouldRemove = true;
717
+ }
718
+ }
719
+ }
720
+
721
+ if (shouldRemove) {
722
+ removeDistillWorktree(vaultPath, entry.path, entry.branch);
723
+ removed += 1;
724
+ }
725
+ } catch {
726
+ // Per-worktree failure is non-fatal; keep sweeping.
727
+ }
728
+ }
729
+
730
+ return removed;
731
+ }
732
+
733
+ /**
734
+ * Read a workspace's meta.json. Returns null if the file doesn't exist or
735
+ * can't be parsed \u2014 callers treat this as "workspace is gone or stale".
736
+ *
737
+ * Never throws on missing files; throws only on unexpected I/O errors
738
+ * (permissions, disk failure) that indicate a deeper problem.
739
+ */
740
+ export function readDistillMeta(worktreePath: string): DistillMeta | null {
741
+ const metaPath = path.join(worktreePath, DISTILL_SUBDIR, "meta.json");
742
+ if (!fs.existsSync(metaPath)) return null;
743
+ try {
744
+ const raw = fs.readFileSync(metaPath, "utf-8");
745
+ const parsed = JSON.parse(raw) as DistillMeta;
746
+ // Light schema check: these fields are required by all consumers.
747
+ if (
748
+ typeof parsed.pid !== "number" ||
749
+ typeof parsed.vault !== "string" ||
750
+ typeof parsed.branch !== "string" ||
751
+ typeof parsed.startedAt !== "string" ||
752
+ typeof parsed.parentSession !== "string"
753
+ ) {
754
+ return null;
755
+ }
756
+ return parsed;
757
+ } catch {
758
+ return null;
759
+ }
760
+ }
761
+
762
+ /**
763
+ * Result of `spawnDistillInWorktree` — returned for bookkeeping and tests.
764
+ * The caller typically stores nothing beyond `workspace.branchName` so
765
+ * `/distill-status` can later discover active workspaces by enumerating
766
+ * `git worktree list` and reading their `meta.json`.
767
+ */
768
+ export interface SpawnDistillResult {
769
+ workspace: DistillWorkspace;
770
+ /** PID of the detached wrapper. The parent process MUST NOT wait on it. */
771
+ pid: number;
772
+ }
773
+
774
+ /**
775
+ * Resolve the absolute path to the distill error log directory for a
776
+ * given vault. Mirrors the logic the wrapper uses internally so the
777
+ * JS-side completion check can find error logs the wrapper produced.
778
+ *
779
+ * Falls back to `<vault>/.napkin/distill/errors/` if napkin's vault
780
+ * resolution throws (defensive — the upstream caller has typically
781
+ * already resolved the vault successfully). The returned path may not
782
+ * exist on disk; callers should check before reading.
783
+ */
784
+ export function resolveDistillErrorDir(vault: string): string {
785
+ try {
786
+ return path.join(new Napkin(vault).vault.configPath, "distill", "errors");
787
+ } catch {
788
+ return path.join(vault, ".napkin", "distill", "errors");
789
+ }
790
+ }
791
+
792
+ /**
793
+ * Find the wrapper-emitted error log for a specific distill branch, if
794
+ * any. The wrapper writes ‘forensic’ logs to
795
+ * `<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.
799
+ *
800
+ * `branchShort` is the part after `distill/`, e.g. for
801
+ * `distill/abc1234-1715198400` pass `abc1234-1715198400`.
802
+ *
803
+ * Used by `runDistillWith`'s success path to detect wrapper failures
804
+ * that don't surface as a timeout (e.g. wrapper exited 1 quickly).
805
+ * Mirrors the timeout-surfacing pattern: target gone + error log
806
+ * present → paint failure in UI; target gone + no error log → success.
807
+ */
808
+ export function findDistillErrorLogForBranch(
809
+ errorDir: string,
810
+ branchShort: string,
811
+ ): string | null {
812
+ if (!fs.existsSync(errorDir)) return null;
813
+ if (branchShort.length === 0) return null;
814
+ let entries: string[];
815
+ try {
816
+ entries = fs.readdirSync(errorDir);
817
+ } catch {
818
+ return null;
819
+ }
820
+ const suffix = `-${branchShort}.log`;
821
+ // Pick the most recent matching file (lexicographic order is
822
+ // chronologically meaningful because the prefix is an ISO
823
+ // timestamp). Multiple logs for the same branch shouldn't happen in
824
+ // practice, but if they do, returning the latest is the right call.
825
+ const matches = entries.filter((f) => f.endsWith(suffix)).sort();
826
+ if (matches.length === 0) return null;
827
+ return path.join(errorDir, matches[matches.length - 1]);
828
+ }
829
+
830
+ /**
831
+ * 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.
834
+ *
835
+ * The outcome sidecar (POST-CONV-5) is written by the wrapper as the
836
+ * 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.
841
+ *
842
+ * Missing outcome AND missing fatal error log = abnormal termination
843
+ * (SIGKILL / `set -e` / disk full / race) — caller must surface this
844
+ * as a warn since the wrapper is detached and we have no other signal
845
+ * channel.
846
+ *
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.
851
+ */
852
+ export function findDistillOutcomeForBranch(
853
+ errorDir: string,
854
+ branchShort: string,
855
+ ): {
856
+ outcomeClass: string;
857
+ outcomePath: string;
858
+ partialMergeLogPath: string | null;
859
+ } | null {
860
+ if (!fs.existsSync(errorDir)) return null;
861
+ if (branchShort.length === 0) return null;
862
+ let entries: string[];
863
+ try {
864
+ entries = fs.readdirSync(errorDir);
865
+ } catch {
866
+ return null;
867
+ }
868
+ const outcomeSuffix = `-${branchShort}.outcome`;
869
+ const outcomes = entries.filter((f) => f.endsWith(outcomeSuffix)).sort();
870
+ if (outcomes.length === 0) return null;
871
+ const outcomePath = path.join(errorDir, outcomes[outcomes.length - 1]);
872
+ let outcomeClass = "";
873
+ try {
874
+ outcomeClass = fs.readFileSync(outcomePath, "utf-8").trim();
875
+ } catch {
876
+ // Treat unreadable outcome as missing — caller will fall through to
877
+ // abnormal-termination handling.
878
+ return null;
879
+ }
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}`;
917
+ }
918
+
919
+ /**
920
+ * Arguments to `spawnDistillInWorktree`. Separated as an interface so callers
921
+ * don't have to remember positional arg order — and so tests can supply the
922
+ * `spawn` override without pulling in the full function signature.
923
+ */
924
+ export interface SpawnDistillOptions {
925
+ /** Absolute path to the main vault (NOT a worktree). */
926
+ vault: string;
927
+ /** Absolute path to the current session .jsonl to fork from. */
928
+ sessionFile: string;
929
+ /**
930
+ * Parent pi session's cwd. Pinned into the fork header and used as the
931
+ * spawn cwd so the distill subprocess's system prompt cwd line matches
932
+ * the parent's, preserving prompt-cache hits. Vault-write routing to the
933
+ * worktree is handled by the wrapper's napkin shim, NOT cwd resolution.
934
+ */
935
+ parentCwd: string;
936
+ /** Prompt passed to `pi -p`. */
937
+ prompt: string;
938
+ /** Optional model override, `<provider>/<id>`. Undefined → pi's default. */
939
+ model?: string;
940
+ /**
941
+ * Override for the `spawn` function — wired by unit tests to capture calls
942
+ * without actually starting processes. Defaults to the node:child_process
943
+ * export at module load time.
944
+ */
945
+ spawnFn?: typeof spawn;
946
+ }
947
+
948
+ /**
949
+ * Detect the vault's default mainline branch. Strategy (first hit wins):
950
+ * 1. `git symbolic-ref refs/remotes/origin/HEAD` — when the vault has a
951
+ * remote `origin`, its HEAD points at the conventional default.
952
+ * 2. Current branch via `git symbolic-ref --short HEAD` — for local-only
953
+ * vaults (fresh `git init` on a user's machine, no remote), the
954
+ * currently checked-out branch IS the default.
955
+ * 3. Fall back to `main` — matches our `git init -b main` in auto-setup.
956
+ *
957
+ * Never throws. Returns a plain short branch name (e.g. `main`, `master`,
958
+ * `trunk`) with no `refs/heads/` prefix.
959
+ *
960
+ * The return value is passed to the wrapper so the `git merge <default>`
961
+ * step inside the worktree targets the vault's actual mainline —
962
+ * hardcoding `main` silently corrupts vaults that use `master` or any
963
+ * other default-branch convention.
964
+ */
965
+ export function detectDefaultBranch(vaultPath: string): string {
966
+ // origin/HEAD gives `refs/remotes/origin/<branch>` when set.
967
+ const originRes = runGit(vaultPath, [
968
+ "symbolic-ref",
969
+ "refs/remotes/origin/HEAD",
970
+ ]);
971
+ if (originRes.status === 0) {
972
+ const ref = originRes.stdout.trim();
973
+ const match = ref.match(/^refs\/remotes\/origin\/(.+)$/);
974
+ if (match && match[1].length > 0) return match[1];
975
+ }
976
+ // HEAD gives `<branch>` directly when --short is used.
977
+ const headRes = runGit(vaultPath, ["symbolic-ref", "--short", "HEAD"]);
978
+ if (headRes.status === 0) {
979
+ const branch = headRes.stdout.trim();
980
+ if (branch.length > 0) return branch;
981
+ }
982
+ return "main";
983
+ }
984
+
985
+ /**
986
+ * Spawn a detached wrapper that performs the full auto-distill lifecycle
987
+ * (pi → commit → merge → squash → cleanup) inside a per-distill worktree.
988
+ *
989
+ * Parent returns synchronously after the child is `unref`'d; the wrapper
990
+ * survives parent exit (this is critical for shutdown distill — the parent
991
+ * pi session is exiting, and the wrapper keeps running). All error paths
992
+ * write to `<vault>/.napkin/distill/errors/` and do NOT block the parent.
993
+ *
994
+ * @throws DistillError if the workspace can't be created (git not a repo,
995
+ * branch collision, fork failure, …). Errors at this layer are
996
+ * unrecoverable by the caller beyond logging — no child to clean up
997
+ * (workspace creation rolled back on throw).
998
+ */
999
+ export function spawnDistillInWorktree(
1000
+ opts: SpawnDistillOptions,
1001
+ ): SpawnDistillResult {
1002
+ const { vault, sessionFile, parentCwd, prompt, model } = opts;
1003
+ const spawnFn = opts.spawnFn ?? spawn;
1004
+
1005
+ const workspace = createDistillWorkspace(vault, sessionFile, parentCwd);
1006
+
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
+ );
1016
+
1017
+ // Error dir lives on the MAIN vault (not in the worktree — worktrees are
1018
+ // removed on cleanup, which would lose the logs). Resolve via Napkin's
1019
+ // configPath so legacy (~/.napkin) and new (<content>/.napkin) layouts
1020
+ // both work.
1021
+ const errorDir = resolveDistillErrorDir(vault);
1022
+ fs.mkdirSync(errorDir, { recursive: true });
1023
+
1024
+ const wrapperArgs = [
1025
+ DISTILL_WRAPPER_SCRIPT,
1026
+ vault,
1027
+ workspace.worktreePath,
1028
+ workspace.branchName,
1029
+ workspace.sessionForkPath,
1030
+ finalPrompt,
1031
+ errorDir,
1032
+ model ?? "",
1033
+ detectDefaultBranch(vault),
1034
+ parentCwd,
1035
+ ];
1036
+
1037
+ // Detached spawn: stdio "ignore" + unref() so the parent can exit cleanly
1038
+ // while the wrapper continues. cwd is the PARENT's cwd — not the worktree
1039
+ // — so pi's process.cwd() at startup matches the session-fork header's
1040
+ // cwd, keeping the system prompt's `Current working directory:` line
1041
+ // byte-identical to the parent's. The wrapper handles git ops in the
1042
+ // worktree and installs a napkin shim that auto-routes vault writes to
1043
+ // the worktree.
1044
+ //
1045
+ // Invoke via `bash` (not `sh`): the wrapper's shebang is `#!/usr/bin/env
1046
+ // bash` and it relies on bash-specific syntax (arrays `pi_args=(...)`,
1047
+ // `set -o pipefail`). On Ubuntu/Debian, `/bin/sh` is `dash` which
1048
+ // parse-errors on bash syntax and exits 2 before the wrapper runs.
1049
+ const proc = spawnFn("bash", wrapperArgs, {
1050
+ cwd: parentCwd,
1051
+ detached: true,
1052
+ stdio: "ignore",
1053
+ env: {
1054
+ ...process.env,
1055
+ NAPKIN_DISTILL_NO_RECURSE: "1",
1056
+ },
1057
+ });
1058
+ proc.unref();
1059
+
1060
+ return {
1061
+ workspace,
1062
+ pid: proc.pid ?? -1,
1063
+ };
1064
+ }
1065
+
1066
+ // ============================================================================
1067
+ // Status helpers (/distill-status + napkin_distill_status tool, Phase C2)
1068
+ // ============================================================================
1069
+
1070
+ /**
1071
+ * Shape returned by `getActiveDistills`. Each entry represents a worktree
1072
+ * currently linked to the vault's git repo on a `distill/*` branch
1073
+ * (placement is under the XDG cache dir, not inside the vault).
1074
+ * Liveness (`alive`) is decided at read time via `process.kill(pid, 0)`,
1075
+ * so a freshly crashed wrapper is reported with `alive: false` (and
1076
+ * `/distill-status` renders it as stale).
1077
+ *
1078
+ * Fields are kept flat + JSON-friendly so the pi tool can serialize the
1079
+ * array directly.
1080
+ */
1081
+ export interface ActiveDistill {
1082
+ pid: number;
1083
+ branch: string;
1084
+ worktreePath: string;
1085
+ /** ISO-8601 timestamp from meta.json. Null if meta.json is unparseable. */
1086
+ startedAt: string | null;
1087
+ /** Milliseconds since `startedAt`. 0 when `startedAt` is null. */
1088
+ elapsedMs: number;
1089
+ /** Absolute path to the parent session's .jsonl. Null if unavailable. */
1090
+ sessionPath: string | null;
1091
+ /** `process.kill(pid, 0)` result — true if the pid is signalable. */
1092
+ alive: boolean;
1093
+ /**
1094
+ * HEAD SHA from meta.json when the worktree was created. Undefined for
1095
+ * pre-Phase-C2 meta files. Used by the overlap injector to diff only
1096
+ * files this distill has written.
1097
+ */
1098
+ startSha?: string;
1099
+ }
1100
+
1101
+ /**
1102
+ * Enumerate active distill worktrees for a vault.
1103
+ *
1104
+ * An "active distill" is a git worktree whose branch is named `distill/*`.
1105
+ * We do NOT filter by pid liveness here — dead entries are still reported
1106
+ * so the UI can distinguish "in flight" from "crashed, needs cleanup". The
1107
+ * caller decides how to render them.
1108
+ *
1109
+ * Returns an empty array on any error (missing .git, `git worktree list`
1110
+ * failure, etc.). Never throws: this is called from UI paths that must not
1111
+ * block on git hiccups.
1112
+ *
1113
+ * Invokes `git worktree list --porcelain` exactly once and does NOT touch
1114
+ * the branch list — so callers that only need the active set (e.g. the
1115
+ * `/distill-status` slash command and `napkin_distill_status` agent tool)
1116
+ * don't pay for a `git branch` invocation they don't need.
1117
+ * (R2-4: restored a pre-CLN-3 fast path.)
1118
+ */
1119
+ export function getActiveDistills(vault: StaleCleanupVault): ActiveDistill[] {
1120
+ return toActiveDistills(listDistillWorktrees(vault.contentPath));
1121
+ }
1122
+
1123
+ /**
1124
+ * Enumerate `distill/*` branches that exist in the vault repo but are NOT
1125
+ * currently checked out in any worktree. These are usually leftover from a
1126
+ * crashed distill whose worktree was removed but whose branch (or, more
1127
+ * often, its squash-merge-candidate commits) lingers pending GC.
1128
+ *
1129
+ * The output is intended for human triage via `/distill-status` — the user
1130
+ * can inspect and `git branch -D` them manually. We do NOT auto-prune
1131
+ * here: that's `cleanupStaleWorktrees`' job, and a lingering branch is
1132
+ * forensic breadcrumb, not debt.
1133
+ *
1134
+ * Returns empty on no-git / git-error. Never throws.
1135
+ *
1136
+ * Calls `git worktree list` + `git branch --list` (both are needed: a
1137
+ * branch can exist without a worktree). Skips the per-entry
1138
+ * meta.json/liveness hydration that `getActiveDistills` does.
1139
+ */
1140
+ export function getUnmergedDistillBranches(vault: StaleCleanupVault): string[] {
1141
+ const vaultPath = vault.contentPath;
1142
+ const worktrees = listDistillWorktrees(vaultPath);
1143
+ const branches = listDistillBranches(vaultPath);
1144
+ const inWorktrees = new Set(worktrees.map((e) => e.branch));
1145
+ return branches.filter((b) => !inWorktrees.has(b));
1146
+ }
1147
+
1148
+ /**
1149
+ * Combined snapshot of distill state for a vault, returned in a single
1150
+ * pass over git plumbing. Used by `/distill-status` — the user wants
1151
+ * "what's running" *and* "what's pending cleanup" at the same time.
1152
+ *
1153
+ * Behavior is equivalent to calling `getActiveDistills` + `getUnmergedDistillBranches`
1154
+ * back-to-back, but we invoke `git worktree list --porcelain` exactly once
1155
+ * instead of twice. `git branch --list 'distill/*'` is still needed to
1156
+ * enumerate orphan branches (a branch can exist without a worktree).
1157
+ *
1158
+ * Returns `{ active: [], unmerged: [] }` on any error — never throws.
1159
+ */
1160
+ export function getDistillState(vault: StaleCleanupVault): {
1161
+ active: ActiveDistill[];
1162
+ unmerged: string[];
1163
+ } {
1164
+ const vaultPath = vault.contentPath;
1165
+ const worktrees = listDistillWorktrees(vaultPath);
1166
+ const active = toActiveDistills(worktrees);
1167
+ const branches = listDistillBranches(vaultPath);
1168
+ const inWorktrees = new Set(worktrees.map((e) => e.branch));
1169
+ const unmerged = branches.filter((b) => !inWorktrees.has(b));
1170
+ return { active, unmerged };
1171
+ }
1172
+
1173
+ /**
1174
+ * Primitive: enumerate `distill/*` worktree entries for a vault.
1175
+ *
1176
+ * Returns the subset of `git worktree list --porcelain` entries whose
1177
+ * branch is under `distill/*`. Empty on no-git / git-error. Cheap: one
1178
+ * `spawnSync` call plus a string split.
1179
+ *
1180
+ * Used by:
1181
+ * - {@link getActiveDistills} directly (no branch listing needed).
1182
+ * - {@link getUnmergedDistillBranches} (combined with branch list).
1183
+ * - {@link getDistillState} (combined).
1184
+ */
1185
+ function listDistillWorktrees(
1186
+ vaultPath: string,
1187
+ ): { path: string; branch: string }[] {
1188
+ if (!fs.existsSync(path.join(vaultPath, ".git"))) return [];
1189
+ const listRes = runGit(vaultPath, ["worktree", "list", "--porcelain"]);
1190
+ if (listRes.status !== 0) return [];
1191
+ return parseWorktreeList(listRes.stdout).filter((e) =>
1192
+ e.branch.startsWith("distill/"),
1193
+ );
1194
+ }
1195
+
1196
+ /**
1197
+ * Primitive: enumerate `distill/*` branches (irrespective of worktrees).
1198
+ *
1199
+ * Empty on no-git / git-error. One `git branch --list` invocation.
1200
+ */
1201
+ function listDistillBranches(vaultPath: string): string[] {
1202
+ if (!fs.existsSync(path.join(vaultPath, ".git"))) return [];
1203
+ const branchesRes = runGit(vaultPath, [
1204
+ "branch",
1205
+ "--list",
1206
+ "distill/*",
1207
+ "--format=%(refname:short)",
1208
+ ]);
1209
+ if (branchesRes.status !== 0) return [];
1210
+ return branchesRes.stdout
1211
+ .split("\n")
1212
+ .map((l) => l.trim())
1213
+ .filter((l) => l.length > 0);
1214
+ }
1215
+
1216
+ /**
1217
+ * Primitive: hydrate worktree entries into `ActiveDistill[]` with
1218
+ * meta.json + pid-liveness.
1219
+ *
1220
+ * Per entry: one `readDistillMeta` (bounded FS read) + one
1221
+ * `isPidAlive` call (`process.kill(pid, 0)`). No git invocation.
1222
+ */
1223
+ function toActiveDistills(
1224
+ entries: { path: string; branch: string }[],
1225
+ ): ActiveDistill[] {
1226
+ const active: ActiveDistill[] = [];
1227
+ for (const entry of entries) {
1228
+ const meta = readDistillMeta(entry.path);
1229
+ const pid = meta?.pid ?? -1;
1230
+ const startedAt = meta?.startedAt ?? null;
1231
+ const elapsedMs =
1232
+ startedAt !== null ? Date.now() - new Date(startedAt).getTime() : 0;
1233
+ const sessionPath = meta?.parentSession ?? null;
1234
+ const alive = pid > 0 ? isPidAlive(pid) : false;
1235
+ active.push({
1236
+ pid,
1237
+ branch: entry.branch,
1238
+ worktreePath: entry.path,
1239
+ startedAt,
1240
+ elapsedMs: Math.max(0, elapsedMs),
1241
+ sessionPath,
1242
+ alive,
1243
+ startSha: meta?.startSha,
1244
+ });
1245
+ }
1246
+ return active;
1247
+ }
1248
+
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
+ /**
1299
+ * Return the list of files affected by commits in the main vault between
1300
+ * `startSha` (the distill's fork point) and HEAD (post-squash, after the
1301
+ * wrapper's squash-merge has landed). Used by per-completion overlap
1302
+ * detection (R7-PERF-2) to compare against the parent session's writes.
1303
+ *
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.
1308
+ *
1309
+ * If `startSha` is missing (legacy distill meta) we cannot reliably
1310
+ * compute the post-squash file set without scanning the now-removed
1311
+ * worktree, so we return `[]`. Overlap detection is best-effort.
1312
+ *
1313
+ * Paths are returned relative to the vault root (matching
1314
+ * `getSessionTouchedFiles` output for the intersection step).
1315
+ *
1316
+ * Downstream `intersectFiles` matches paths in three layers — exact /
1317
+ * symmetric-suffix / basename-fallback. The basename-fallback's known
1318
+ * false-positive shape (two unrelated `README.md`s in different
1319
+ * subtrees match) flows through here too; accepted because the overlap
1320
+ * notice is non-destructive (advisory message, doesn't modify files).
1321
+ * Concurrent-distill log noise is a separate accepted false-positive
1322
+ * class (when two pi sessions on the same vault complete in close
1323
+ * succession, the second's `<startSha>..HEAD` includes the first's
1324
+ * squash commit). See `deferred.md` R8-CC-5.
1325
+ */
1326
+ export function getDistillTouchedFilesPostSquash(
1327
+ vaultPath: string,
1328
+ startSha: string | undefined,
1329
+ ): string[] {
1330
+ if (!startSha) return [];
1331
+ const r = runGit(vaultPath, [
1332
+ "log",
1333
+ `${startSha}..HEAD`,
1334
+ "--name-only",
1335
+ "--format=",
1336
+ ]);
1337
+ if (r.status !== 0) return [];
1338
+ const files = new Set<string>();
1339
+ for (const line of r.stdout.split("\n")) {
1340
+ const f = line.trim();
1341
+ if (f.length > 0) files.add(f);
1342
+ }
1343
+ return Array.from(files);
1344
+ }