@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.
- package/LICENSE +22 -0
- package/README.md +377 -0
- package/extensions/distill/README.md +86 -0
- package/extensions/distill/auto-setup.ts +480 -0
- package/extensions/distill/distill-workspace.ts +1344 -0
- package/extensions/distill/index.ts +1808 -0
- package/extensions/distill/scripts/distill-wrapper.sh +692 -0
- package/extensions/distill/scripts/git_retry.sh +65 -0
- package/extensions/distill/scripts/napkin-distill-merge +455 -0
- package/extensions/distill/scripts-paths.ts +30 -0
- package/extensions/distill/session-touched-files.ts +216 -0
- package/extensions/distill/should-distill-on-shutdown.ts +68 -0
- package/extensions/napkin-context/index.ts +259 -0
- package/package.json +68 -0
- package/skills/napkin/SKILL.md +44 -0
|
@@ -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
|
+
}
|