pi-better-subagents 0.24.0 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,944 @@
1
+ /**
2
+ * Completed-subagent continuation.
3
+ *
4
+ * A subagent attempt is one detached `pi -p` process; its conversation is a
5
+ * saved native session JSONL that outlives the process. Continuation keeps the
6
+ * conversation and allocates a NEW attempt, so old logs, results, callback
7
+ * markers, and timing records stay intact under their own run id.
8
+ *
9
+ * This module owns the four seams that decision needs and that the rest of the
10
+ * package must not duplicate:
11
+ *
12
+ * 1. **Saved-conversation identity.** Find the exact JSONL for a session id and
13
+ * prove its header still names that id and the expected workspace. Pi's
14
+ * `--session` opens a missing path by creating a fresh conversation, so a
15
+ * continuation validates first and refuses instead of silently replacing
16
+ * history.
17
+ * 2. **Launch recipe.** Capture the effective launch (tools, exclusions,
18
+ * clean/nesting/approval intent, confinement, model, effort, role identity,
19
+ * workspace intent) on run metadata.
20
+ * 3. **Explicit retention.** `retain_session` records a bounded promise that a
21
+ * completed conversation and its workspace stay out of cleanup until the
22
+ * owner releases it. Retention lives in the existing runtime storage, so
23
+ * system-temp reaping can still remove it; a missing conversation refuses.
24
+ * 4. **Conversation writer lease.** A cross-process token lease held from
25
+ * admission through child lifetime and finalization. Duplicate continuations
26
+ * of one conversation admit exactly one writer. Lease-path and retention
27
+ * mutations run inside a short kernel-owned per-conversation transaction, so
28
+ * stale recovery cannot expose an empty path to a competing admission.
29
+ * Stale leases are recovered only with process-identity or terminal-attempt
30
+ * evidence, and never while the attempt's own detached child is still alive:
31
+ * the lease holder and the writer are different processes, so the holder
32
+ * dying is not quiescence. Missing attempt metadata is also not quiescence —
33
+ * the launch path spawns before publishing it — so that state needs an
34
+ * explicit operator recovery.
35
+ *
36
+ * No worker, RPC daemon, or new poller exists between attempts: the next
37
+ * attempt is an ordinary detached launch, and a parked owner occupies no
38
+ * capacity slot.
39
+ */
40
+
41
+ import { randomBytes } from "node:crypto";
42
+ import {
43
+ closeSync,
44
+ linkSync,
45
+ mkdirSync,
46
+ openSync,
47
+ readFileSync,
48
+ readSync,
49
+ readdirSync,
50
+ realpathSync,
51
+ renameSync,
52
+ statSync,
53
+ unlinkSync,
54
+ writeFileSync,
55
+ } from "node:fs";
56
+ import { dirname, join } from "node:path";
57
+ import { createRequire } from "node:module";
58
+ import {
59
+ baseDir,
60
+ listMetas,
61
+ processStartToken,
62
+ readMeta,
63
+ type LaunchRecipe,
64
+ type RunCallbackOrigin,
65
+ type RunMeta,
66
+ type RunStatus,
67
+ } from "./registry.ts";
68
+ import { processExists } from "./spawn.ts";
69
+
70
+ const nodeRequire = createRequire(import.meta.url);
71
+
72
+ /** A continuation that cannot proceed. The message is the model-facing refusal. */
73
+ export class ContinuationError extends Error {
74
+ constructor(message: string) {
75
+ super(message);
76
+ this.name = "ContinuationError";
77
+ }
78
+ }
79
+
80
+ // ---- saved conversation identity -----------------------------------------
81
+
82
+ /** Native conversation that a continuation reopens. */
83
+ export interface SavedConversation {
84
+ sessionId: string;
85
+ /** Exact session JSONL path handed to `--session`. */
86
+ path: string;
87
+ /** Canonical workspace recorded in the session header. */
88
+ cwd: string;
89
+ }
90
+
91
+ export type ConversationLookup =
92
+ | { kind: "ok"; conversation: SavedConversation }
93
+ | { kind: "missing" }
94
+ | { kind: "ambiguous"; paths: string[] }
95
+ | { kind: "mismatch"; detail: string }
96
+ | { kind: "invalid"; detail: string };
97
+
98
+ /** Header lines are small; this bound only prevents reading a whole session. */
99
+ const SESSION_HEADER_BYTES = 256 * 1024;
100
+
101
+ function canonicalPath(path: string): string {
102
+ try {
103
+ return realpathSync.native(path);
104
+ } catch {
105
+ return path;
106
+ }
107
+ }
108
+
109
+ /** First JSON line of a session file, or undefined when it is not a session header. */
110
+ export function readSessionHeader(path: string): Record<string, unknown> | undefined {
111
+ let fd: number | undefined;
112
+ try {
113
+ fd = openSync(path, "r");
114
+ const buffer = Buffer.alloc(SESSION_HEADER_BYTES);
115
+ const read = readSync(fd, buffer, 0, buffer.length, 0);
116
+ if (read <= 0) return undefined;
117
+ const text = buffer.subarray(0, read).toString("utf-8");
118
+ const newline = text.indexOf("\n");
119
+ const line = (newline === -1 ? text : text.slice(0, newline)).trim();
120
+ if (!line) return undefined;
121
+ const parsed = JSON.parse(line) as unknown;
122
+ return parsed && typeof parsed === "object" && !Array.isArray(parsed)
123
+ ? parsed as Record<string, unknown>
124
+ : undefined;
125
+ } catch {
126
+ return undefined;
127
+ } finally {
128
+ if (fd !== undefined) {
129
+ try { closeSync(fd); } catch { /* read-only handle */ }
130
+ }
131
+ }
132
+ }
133
+
134
+ /**
135
+ * Find the saved conversation for `sessionId` and prove it still belongs to
136
+ * this attempt's workspace. Ambiguity is refused, never guessed: a wrong file
137
+ * would silently continue someone else's history.
138
+ */
139
+ export function findSavedConversation(options: {
140
+ sessionDir: string;
141
+ sessionId: string;
142
+ expectedCwd: string;
143
+ }): ConversationLookup {
144
+ const { sessionDir, sessionId, expectedCwd } = options;
145
+ if (!isSafeRunId(sessionId)) return { kind: "invalid", detail: `session id ${JSON.stringify(sessionId)} is not a valid run id` };
146
+ let names: string[];
147
+ try {
148
+ names = readdirSync(sessionDir);
149
+ } catch {
150
+ return { kind: "missing" };
151
+ }
152
+ const matches: string[] = [];
153
+ let headerCwd: string | undefined;
154
+ // Pi names session files `<timestamp>_<sessionId>.jsonl`. Try that exact
155
+ // suffix first so a resume does not read the header prefix of every
156
+ // conversation in a busy session directory; fall back to a header scan for
157
+ // renamed or foreign layouts instead of guessing.
158
+ const direct = names.filter((name) => name.endsWith(`_${sessionId}.jsonl`));
159
+ if (direct.length > 1) return { kind: "ambiguous", paths: direct.map((name) => join(sessionDir, name)).sort() };
160
+ const candidates = direct.length === 1 ? direct : names.filter((name) => name.endsWith(".jsonl"));
161
+ for (const name of candidates) {
162
+ const path = join(sessionDir, name);
163
+ const header = readSessionHeader(path);
164
+ if (!header || header.type !== "session") {
165
+ if (direct.length === 1) return { kind: "invalid", detail: `${path} is not a saved Pi session` };
166
+ continue;
167
+ }
168
+ if (header.id !== sessionId) {
169
+ if (direct.length === 1) return { kind: "invalid", detail: `${path} names session ${JSON.stringify(header.id)}` };
170
+ continue;
171
+ }
172
+ matches.push(path);
173
+ if (headerCwd === undefined && typeof header.cwd === "string") headerCwd = header.cwd;
174
+ }
175
+ if (matches.length === 0) return { kind: "missing" };
176
+ if (matches.length > 1) return { kind: "ambiguous", paths: matches.sort() };
177
+ const path = matches[0]!;
178
+ const expected = canonicalPath(expectedCwd);
179
+ if (headerCwd === undefined || headerCwd.trim() === "") {
180
+ return { kind: "mismatch", detail: `saved conversation ${path} records no workspace` };
181
+ }
182
+ const recorded = canonicalPath(headerCwd);
183
+ if (recorded !== expected) {
184
+ return { kind: "mismatch", detail: `saved conversation ${path} belongs to workspace ${recorded}, not ${expected}` };
185
+ }
186
+ return { kind: "ok", conversation: { sessionId, path, cwd: recorded } };
187
+ }
188
+
189
+ // ---- launch recipe -------------------------------------------------------
190
+
191
+ /** Freeze the effective launch of one attempt for later continuation. */
192
+ export function buildLaunchRecipe(input: Omit<LaunchRecipe, "version">): LaunchRecipe {
193
+ const recipe: LaunchRecipe = { version: 1, ...input };
194
+ if (input.excludeTools === "") delete recipe.excludeTools;
195
+ if (input.sandboxDir === "") delete recipe.sandboxDir;
196
+ return recipe;
197
+ }
198
+
199
+ /** Compare implementation identity separately from current permission admission. */
200
+ export function assertContinuationExtensions(
201
+ priorId: string,
202
+ recipe: LaunchRecipe,
203
+ baseArgs: readonly string[],
204
+ trusted: readonly { name: string; package: string; loadPath: string }[],
205
+ ): void {
206
+ const expected = recipe.baseExtensionArgs ?? recipe.extensionArgs;
207
+ if (expected && JSON.stringify(baseArgs) !== JSON.stringify(expected)) {
208
+ throw new ContinuationError(`Cannot continue ${priorId}: resolved extension implementations changed; launch a new run rather than changing this conversation's runtime silently.`);
209
+ }
210
+ if (!recipe.trustedExtensions) return;
211
+ for (const current of trusted) {
212
+ const original = recipe.trustedExtensions.find((tool) => tool.name === current.name);
213
+ if (!original || original.package !== current.package
214
+ || canonicalPath(original.loadPath) !== canonicalPath(current.loadPath)) {
215
+ throw new ContinuationError(`Cannot continue ${priorId}: resolved extension implementation changed for ${current.name}; launch a new run instead.`);
216
+ }
217
+ }
218
+ }
219
+
220
+ // ---- explicit retention --------------------------------------------------
221
+
222
+ /**
223
+ * Durable retention for one conversation. `retainedAt` is the first request;
224
+ * later attempts refresh `lastAttemptId` without extending the promise, which
225
+ * stays bounded by the existing runtime-storage cleanup rules.
226
+ */
227
+ export interface RetentionRecord {
228
+ version: 1;
229
+ sessionId: string;
230
+ /** First attempt of the conversation's lineage. */
231
+ ownerRunId: string;
232
+ /** Canonical workspace kept available for continuation. */
233
+ workspace: string;
234
+ /** Foreground session that may continue or release this conversation. */
235
+ ownerOrigin: RunCallbackOrigin;
236
+ retainedAt: number;
237
+ lastAttemptId: string;
238
+ releasedAt?: number;
239
+ releasedBy?: RunCallbackOrigin;
240
+ }
241
+
242
+ export function retentionDir(): string {
243
+ return join(baseDir(), "retained");
244
+ }
245
+
246
+ function retentionPath(sessionId: string): string {
247
+ if (!isSafeRunId(sessionId)) throw new Error("Invalid session id.");
248
+ return join(retentionDir(), `${sessionId}.json`);
249
+ }
250
+
251
+ function isSafeRunId(id: unknown): id is string {
252
+ return typeof id === "string" && /^[A-Za-z0-9_-]+$/.test(id);
253
+ }
254
+
255
+ function parseRetention(raw: string, sessionId: string): RetentionRecord | undefined {
256
+ let parsed: unknown;
257
+ try {
258
+ parsed = JSON.parse(raw);
259
+ } catch {
260
+ return undefined;
261
+ }
262
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
263
+ const record = parsed as Partial<RetentionRecord>;
264
+ if (record.version !== 1 || record.sessionId !== sessionId) return undefined;
265
+ if (typeof record.ownerRunId !== "string" || typeof record.workspace !== "string") return undefined;
266
+ if (typeof record.retainedAt !== "number" || typeof record.lastAttemptId !== "string") return undefined;
267
+ const origin = record.ownerOrigin;
268
+ if (!origin || typeof origin.cwd !== "string") return undefined;
269
+ return record as RetentionRecord;
270
+ }
271
+
272
+ export function readRetention(sessionId: string): RetentionRecord | undefined {
273
+ if (!isSafeRunId(sessionId)) return undefined;
274
+ try {
275
+ return parseRetention(readFileSync(retentionPath(sessionId), "utf-8"), sessionId);
276
+ } catch {
277
+ return undefined;
278
+ }
279
+ }
280
+
281
+ function writeRetention(record: RetentionRecord): void {
282
+ const path = retentionPath(record.sessionId);
283
+ mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
284
+ const temp = join(dirname(path), `.${randomBytes(8).toString("hex")}.tmp`);
285
+ try {
286
+ writeFileSync(temp, JSON.stringify(record, null, 2), { mode: 0o600, flag: "wx" });
287
+ renameSync(temp, path);
288
+ } catch (error) {
289
+ try { unlinkSync(temp); } catch { /* best effort */ }
290
+ throw error;
291
+ }
292
+ }
293
+
294
+ /** Every parseable retention record, including released ones. */
295
+ export function listRetentionRecords(): RetentionRecord[] {
296
+ let names: string[];
297
+ try {
298
+ names = readdirSync(retentionDir());
299
+ } catch {
300
+ return [];
301
+ }
302
+ const records: RetentionRecord[] = [];
303
+ for (const name of names) {
304
+ if (!name.endsWith(".json")) continue;
305
+ const sessionId = name.slice(0, -5);
306
+ if (!isSafeRunId(sessionId)) continue;
307
+ const record = readRetention(sessionId);
308
+ if (record) records.push(record);
309
+ }
310
+ return records;
311
+ }
312
+
313
+ /** Session ids whose conversation and workspace must survive cleanup. */
314
+ export function retainedSessionIds(): Set<string> {
315
+ const ids = new Set<string>();
316
+ for (const record of listRetentionRecords()) {
317
+ if (record.releasedAt === undefined) ids.add(record.sessionId);
318
+ }
319
+ return ids;
320
+ }
321
+
322
+ /** Run ids belonging to a retained conversation (every attempt, not just the root). */
323
+ export function retainedRunIds(metas: readonly RunMeta[] = listMetas()): Set<string> {
324
+ const sessions = retainedSessionIds();
325
+ const ids = new Set<string>();
326
+ if (sessions.size === 0) return ids;
327
+ for (const meta of metas) {
328
+ if (sessions.has(meta.sessionId)) ids.add(meta.id);
329
+ }
330
+ return ids;
331
+ }
332
+
333
+ /** Record an explicit retention request. An existing record keeps its first timestamp. */
334
+ export function retainConversation(options: {
335
+ sessionId: string;
336
+ ownerRunId: string;
337
+ workspace: string;
338
+ ownerOrigin: RunCallbackOrigin;
339
+ attemptId: string;
340
+ now?: number;
341
+ }): RetentionRecord {
342
+ return withConversationMutation(options.sessionId, () => {
343
+ const existing = readRetention(options.sessionId);
344
+ const record: RetentionRecord = existing
345
+ ? { ...existing, lastAttemptId: options.attemptId }
346
+ : {
347
+ version: 1,
348
+ sessionId: options.sessionId,
349
+ ownerRunId: options.ownerRunId,
350
+ workspace: canonicalPath(options.workspace),
351
+ ownerOrigin: { cwd: options.ownerOrigin.cwd, sessionId: options.ownerOrigin.sessionId },
352
+ retainedAt: options.now ?? Date.now(),
353
+ lastAttemptId: options.attemptId,
354
+ };
355
+ writeRetention(record);
356
+ return record;
357
+ }, { waitMs: RETENTION_LOCK_WAIT_MS });
358
+ }
359
+
360
+ /** Extend retention to a continuation attempt, but never revive a released one. */
361
+ export function refreshRetentionForAttempt(options: {
362
+ sessionId: string;
363
+ attemptId: string;
364
+ }): RetentionRecord | undefined {
365
+ return withConversationMutation(options.sessionId, () => {
366
+ // Read and write inside one critical section: a release acknowledged by
367
+ // another process before this section began is visible to the re-read
368
+ // and is never overwritten by an attempt refresh.
369
+ const existing = readRetention(options.sessionId);
370
+ if (!existing || existing.releasedAt !== undefined) return undefined;
371
+ const record: RetentionRecord = { ...existing, lastAttemptId: options.attemptId };
372
+ writeRetention(record);
373
+ return record;
374
+ }, { waitMs: RETENTION_LOCK_WAIT_MS });
375
+ }
376
+
377
+ /** Mark a validated retention record released. Deletion is left to normal cleanup. */
378
+ export function markRetentionReleased(
379
+ record: RetentionRecord,
380
+ origin: RunCallbackOrigin,
381
+ now: number = Date.now(),
382
+ ): RetentionRecord {
383
+ return withConversationMutation(record.sessionId, () => {
384
+ // Re-read under the same lock the refresh path uses. An acknowledged
385
+ // release is monotonic: it is never revived by a stale attempt refresh
386
+ // that was planned before this section.
387
+ const current = readRetention(record.sessionId) ?? record;
388
+ if (current.releasedAt !== undefined) return current;
389
+ const released: RetentionRecord = {
390
+ ...current,
391
+ releasedAt: now,
392
+ releasedBy: { cwd: origin.cwd, sessionId: origin.sessionId },
393
+ };
394
+ writeRetention(released);
395
+ return released;
396
+ }, { waitMs: RETENTION_LOCK_WAIT_MS });
397
+ }
398
+
399
+ // ---- ownership and continuation plan ------------------------------------
400
+
401
+ /** True when `origin` is the foreground session recorded on the run. */
402
+ export function ownedByOrigin(meta: RunMeta, origin: RunCallbackOrigin | undefined): boolean {
403
+ const recorded = meta.callbackOrigin;
404
+ if (!origin?.sessionId || typeof origin.cwd !== "string") return false;
405
+ if (!recorded?.sessionId) return false;
406
+ return recorded.cwd === origin.cwd && recorded.sessionId === origin.sessionId;
407
+ }
408
+
409
+ export interface ContinuationPlan {
410
+ prior: RunMeta;
411
+ recipe: LaunchRecipe;
412
+ conversation: SavedConversation;
413
+ /** First attempt of the conversation's lineage. */
414
+ rootRunId: string;
415
+ }
416
+
417
+ function refusal(id: string, reason: string): ContinuationError {
418
+ return new ContinuationError(`Cannot continue ${id}: ${reason}`);
419
+ }
420
+
421
+ function effectiveAttemptStatus(meta: RunMeta): RunStatus | "exited" {
422
+ if (meta.status !== "running") return meta.status;
423
+ return processExists(meta.pid) ? "running" : "exited";
424
+ }
425
+
426
+ function isActiveAttempt(meta: RunMeta): boolean {
427
+ const status = effectiveAttemptStatus(meta);
428
+ return status === "running" || status === "orphaned";
429
+ }
430
+
431
+ /**
432
+ * Validate one completed attempt for continuation and return the exact
433
+ * conversation plus frozen recipe to relaunch. Every refusal is fail-closed:
434
+ * nothing is spawned and no history is created or replaced.
435
+ */
436
+ export function planContinuation(options: {
437
+ id: string;
438
+ prior: RunMeta | undefined;
439
+ origin: RunCallbackOrigin | undefined;
440
+ others: readonly RunMeta[];
441
+ }): ContinuationPlan {
442
+ const { id, prior, origin, others } = options;
443
+ if (!prior) throw refusal(id, "no such run id.");
444
+ if (!origin?.sessionId) throw refusal(id, "the active foreground session identity is unavailable.");
445
+ if (!ownedByOrigin(prior, origin)) throw refusal(id, "only its owning foreground session may continue it.");
446
+ if (prior.status !== "completed") {
447
+ throw refusal(id, `its status is ${prior.status}; only a completed run can be continued. Stop or launch a new run instead.`);
448
+ }
449
+ const recipe = prior.recipe;
450
+ if (!recipe || recipe.version !== 1) throw refusal(id, "it was launched before continuation support, so no launch recipe was saved.");
451
+ if (recipe.sessionId !== prior.sessionId) throw refusal(id, "its launch recipe and metadata disagree about the conversation identity.");
452
+ if (canonicalPath(recipe.cwd) !== canonicalPath(prior.cwd)) throw refusal(id, "its launch recipe and metadata disagree about the workspace.");
453
+
454
+ const active = others.find((meta) => meta.sessionId === prior.sessionId && meta.id !== prior.id && isActiveAttempt(meta));
455
+ if (active) throw refusal(id, `attempt ${active.id} is still active in the same conversation; stop it first.`);
456
+
457
+ let workspaceIsDir = false;
458
+ try { workspaceIsDir = statSync(recipe.cwd).isDirectory(); } catch { workspaceIsDir = false; }
459
+ if (!workspaceIsDir) throw refusal(id, `its workspace ${recipe.cwd} is missing.`);
460
+ if (recipe.sandboxDir !== undefined) {
461
+ let sandboxIsDir = false;
462
+ try { sandboxIsDir = statSync(recipe.sandboxDir).isDirectory(); } catch { sandboxIsDir = false; }
463
+ if (!sandboxIsDir) throw refusal(id, `its sandbox workspace ${recipe.sandboxDir} is missing.`);
464
+ }
465
+
466
+ const lookup: ConversationLookup = findSavedConversation({
467
+ sessionDir: recipe.sessionDir,
468
+ sessionId: recipe.sessionId,
469
+ expectedCwd: recipe.cwd,
470
+ });
471
+ switch (lookup.kind) {
472
+ case "ok":
473
+ return { prior, recipe, conversation: lookup.conversation, rootRunId: prior.rootRunId ?? prior.id };
474
+ case "missing":
475
+ throw refusal(id, `its saved conversation is gone (session ${recipe.sessionId} under ${recipe.sessionDir}). Retained history lives in temporary storage and can be removed; launch a new run instead.`);
476
+ case "ambiguous":
477
+ throw refusal(id, `its saved conversation is ambiguous (${lookup.paths.length} files name session ${recipe.sessionId}); refusing to guess which history to continue.`);
478
+ case "invalid":
479
+ case "mismatch":
480
+ throw refusal(id, `its saved conversation cannot be verified: ${lookup.detail}.`);
481
+ }
482
+ }
483
+
484
+ /** Validate an explicit retention release. Returns the record to mark released. */
485
+ export function planRetentionRelease(options: {
486
+ id: string;
487
+ prior: RunMeta | undefined;
488
+ origin: RunCallbackOrigin | undefined;
489
+ others: readonly RunMeta[];
490
+ }): RetentionRecord {
491
+ const { id, prior, origin, others } = options;
492
+ if (!prior) throw new ContinuationError(`Cannot release ${id}: no such run id.`);
493
+ if (!origin?.sessionId) throw new ContinuationError(`Cannot release ${id}: the active foreground session identity is unavailable.`);
494
+ if (!ownedByOrigin(prior, origin)) throw new ContinuationError(`Cannot release ${id}: only its owning foreground session may change retention.`);
495
+ const record = readRetention(prior.sessionId);
496
+ if (!record) throw new ContinuationError(`Cannot release ${id}: it was not launched with retain_session, so it has no retained conversation.`);
497
+ if (!record.ownerOrigin.sessionId || record.ownerOrigin.sessionId !== origin.sessionId || record.ownerOrigin.cwd !== origin.cwd) {
498
+ throw new ContinuationError(`Cannot release ${id}: only the foreground session that retained this conversation may release it.`);
499
+ }
500
+ if (record.releasedAt !== undefined) {
501
+ throw new ContinuationError(`Cannot release ${id}: its retention was already released at ${new Date(record.releasedAt).toISOString()}.`);
502
+ }
503
+ const active = others.find((meta) => meta.sessionId === prior.sessionId && isActiveAttempt(meta));
504
+ if (active) throw new ContinuationError(`Cannot release ${id}: attempt ${active.id} is still active in the same conversation. Stop it first.`);
505
+ return record;
506
+ }
507
+
508
+ // ---- cross-process conversation writer lease -----------------------------
509
+
510
+ export class ConversationBusyError extends Error {
511
+ constructor(message: string) {
512
+ super(message);
513
+ this.name = "ConversationBusyError";
514
+ }
515
+ }
516
+
517
+ export interface ConversationLease {
518
+ sessionId: string;
519
+ attemptId: string;
520
+ token: string;
521
+ path: string;
522
+ /** Idempotent; only removes the lease this holder published. */
523
+ release(): void;
524
+ }
525
+
526
+ interface LeasePayload {
527
+ pid: number;
528
+ start?: string;
529
+ token: string;
530
+ sessionId: string;
531
+ attemptId: string;
532
+ at: number;
533
+ }
534
+
535
+ /** A live holder must be visible for this long before its terminal attempt frees the lease. */
536
+ const TERMINAL_ATTEMPT_RECLAIM_MS = 5_000;
537
+ const UNPARSABLE_LEASE_GRACE_MS = 1_000;
538
+ /** Admission is fail-fast: another foreground mutation is a refusal, not a wait. */
539
+ const ADMISSION_LOCK_WAIT_MS = 0;
540
+ /** Release and retention are short cleanup decisions; wait briefly for their lock. */
541
+ const RELEASE_LOCK_WAIT_MS = 1_000;
542
+ const RETENTION_LOCK_WAIT_MS = 1_000;
543
+
544
+ export function conversationLeaseDir(): string {
545
+ return join(baseDir(), "conversation-leases");
546
+ }
547
+
548
+ function leasePathFor(sessionId: string): string {
549
+ return join(conversationLeaseDir(), `${sessionId}.lock`);
550
+ }
551
+
552
+ function errnoOf(error: unknown): string | undefined {
553
+ return (error as NodeJS.ErrnoException).code;
554
+ }
555
+
556
+ // ---- per-conversation mutation lock --------------------------------------
557
+
558
+ /**
559
+ * Refuse rather than proceed when the kernel lock that makes lease and
560
+ * retention mutations serial cannot be created. Node 24 ships `node:sqlite`;
561
+ * on a runtime without it the one-writer guarantee is unavailable, so every
562
+ * admission, release, and retention write fails closed instead of racing.
563
+ */
564
+ export class ConversationLockUnavailableError extends Error {
565
+ constructor(message: string) {
566
+ super(message);
567
+ this.name = "ConversationLockUnavailableError";
568
+ }
569
+ }
570
+
571
+ interface MutationDb {
572
+ exec(sql: string): void;
573
+ close(): void;
574
+ }
575
+
576
+ const sqliteWarningFilter = Symbol.for("pi-better-subagents.continuation-sqlite-warning-filter");
577
+
578
+ function installSqliteWarningFilter(): void {
579
+ const marked = process as typeof process & { [sqliteWarningFilter]?: boolean };
580
+ if (marked[sqliteWarningFilter]) return;
581
+ marked[sqliteWarningFilter] = true;
582
+ const emit = process.emitWarning.bind(process);
583
+ process.emitWarning = ((warning: unknown, ...args: unknown[]) => {
584
+ const message = typeof warning === "string"
585
+ ? warning
586
+ : (warning as { message?: unknown } | undefined)?.message;
587
+ if (typeof message === "string" && message.includes("SQLite is an experimental feature")) return;
588
+ return (emit as (warning: unknown, ...args: unknown[]) => void)(warning, ...args);
589
+ }) as typeof process.emitWarning;
590
+ }
591
+
592
+ let databaseSyncCtor: (new (path: string) => MutationDb) | null | undefined;
593
+
594
+ function databaseSync(): (new (path: string) => MutationDb) | null {
595
+ if (databaseSyncCtor !== undefined) return databaseSyncCtor;
596
+ installSqliteWarningFilter();
597
+ try {
598
+ const loaded = nodeRequire("node:sqlite") as { DatabaseSync?: new (path: string) => MutationDb };
599
+ databaseSyncCtor = loaded.DatabaseSync ?? null;
600
+ } catch (error) {
601
+ const code = errnoOf(error);
602
+ const message = error instanceof Error ? error.message : String(error);
603
+ const missing = code === "ERR_UNKNOWN_BUILTIN_MODULE"
604
+ || message.includes("Cannot find package")
605
+ || message.includes("Cannot find module")
606
+ || message.includes("No such built-in module");
607
+ if (!missing) throw error;
608
+ databaseSyncCtor = null;
609
+ }
610
+ return databaseSyncCtor;
611
+ }
612
+
613
+ function isSqliteBusy(error: unknown): boolean {
614
+ const message = error instanceof Error ? error.message : String(error);
615
+ return /database is locked|SQLITE_BUSY/i.test(message);
616
+ }
617
+
618
+ /**
619
+ * Stable transaction file for one conversation. It is never renamed or deleted
620
+ * while the conversation is in use: SQLite's reserved lock lives in this file,
621
+ * and the kernel drops that lock when its holder exits.
622
+ */
623
+ function conversationMutationPath(sessionId: string): string {
624
+ return join(conversationLeaseDir(), `${sessionId}.mutations.sqlite`);
625
+ }
626
+
627
+ export interface ConversationMutationOptions {
628
+ /** How long SQLite may wait for a concurrent holder. Default 0 (fail fast). */
629
+ waitMs?: number;
630
+ }
631
+
632
+ /**
633
+ * Serialize one conversation's lease-path and retention mutations across
634
+ * processes with a short kernel-owned critical section.
635
+ *
636
+ * The body runs while SQLite holds `BEGIN IMMEDIATE` on the conversation's
637
+ * stable transaction file. No other process can enter a conversation mutation
638
+ * at the same time, so a reclaim cannot expose an empty lease path to an
639
+ * admission, and a retention refresh cannot publish a stale unreleased record
640
+ * over an acknowledged release. The transaction is released immediately after
641
+ * the body returns: it covers the mutation, never the detached child's lifetime.
642
+ *
643
+ * `waitMs` defaults to 0 so admission fails fast. Callers that own cleanup may
644
+ * pass a small budget. A body must not call another public conversation
645
+ * mutation for the same conversation; private `*Unlocked` helpers exist for
646
+ * that reason and keep the lock non-reentrant.
647
+ */
648
+ export function withConversationMutation<T>(
649
+ sessionId: string,
650
+ body: () => T,
651
+ options: ConversationMutationOptions = {},
652
+ ): T {
653
+ if (!isSafeRunId(sessionId)) throw new Error("Invalid session id for a conversation mutation.");
654
+ const Ctor = databaseSync();
655
+ if (!Ctor) {
656
+ throw new ConversationLockUnavailableError(
657
+ `Cannot update conversation ${sessionId}: this Pi runtime does not provide node:sqlite, so the cross-process conversation lock required for one-writer continuation is unavailable. Upgrade to Node 24 or newer.`,
658
+ );
659
+ }
660
+ const directory = conversationLeaseDir();
661
+ mkdirSync(directory, { recursive: true, mode: 0o700 });
662
+ const db = new Ctor(conversationMutationPath(sessionId));
663
+ const requestedWait = options.waitMs ?? 0;
664
+ const waitMs = Number.isFinite(requestedWait)
665
+ ? Math.min(60_000, Math.max(0, Math.floor(requestedWait)))
666
+ : 0;
667
+ try {
668
+ db.exec(`PRAGMA busy_timeout = ${waitMs}`);
669
+ try {
670
+ db.exec("BEGIN IMMEDIATE");
671
+ } catch (error) {
672
+ if (isSqliteBusy(error)) {
673
+ throw new ConversationBusyError(
674
+ `Cannot update conversation ${sessionId}: another foreground process is inside a conversation mutation.`,
675
+ );
676
+ }
677
+ throw error;
678
+ }
679
+ } catch (error) {
680
+ try { db.close(); } catch { /* preserve the lock error */ }
681
+ throw error;
682
+ }
683
+ let result: T;
684
+ try {
685
+ result = body();
686
+ } catch (error) {
687
+ try { db.exec("ROLLBACK"); } catch { /* closing rolls back too */ }
688
+ try { db.close(); } catch { /* preserve the body error */ }
689
+ throw error;
690
+ }
691
+ try {
692
+ db.exec("ROLLBACK");
693
+ } finally {
694
+ db.close();
695
+ }
696
+ return result;
697
+ }
698
+
699
+ function parseLeasePayload(raw: string): LeasePayload | undefined {
700
+ let parsed: unknown;
701
+ try {
702
+ parsed = JSON.parse(raw);
703
+ } catch {
704
+ return undefined;
705
+ }
706
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
707
+ const payload = parsed as Partial<LeasePayload>;
708
+ if (typeof payload.pid !== "number" || !Number.isInteger(payload.pid) || payload.pid <= 0) return undefined;
709
+ if (typeof payload.token !== "string" || typeof payload.sessionId !== "string") return undefined;
710
+ if (typeof payload.attemptId !== "string" || typeof payload.at !== "number") return undefined;
711
+ return payload as LeasePayload;
712
+ }
713
+
714
+ /** Process-identity seam for the lease. Production uses the OS probe. */
715
+ export interface LeaseProbe {
716
+ startToken?(pid: number): string | undefined;
717
+ }
718
+
719
+ /** Metadata of the attempt a lease names, when that id is a real run id. */
720
+ function readAttemptMeta(attemptId: string): RunMeta | undefined {
721
+ if (!isSafeRunId(attemptId)) return undefined;
722
+ try {
723
+ return readMeta(attemptId);
724
+ } catch {
725
+ return undefined;
726
+ }
727
+ }
728
+
729
+ /**
730
+ * Whether the attempt's recorded child may still be writing the conversation.
731
+ *
732
+ * The lease is taken by the supervising pi process, but the writer is the
733
+ * detached child it spawned: a supervisor can exit — normally, by crash, or as a
734
+ * `killed`/`lost` record whose kill has not landed — while its child keeps
735
+ * appending to the saved session. Recorded process-start identity is compared so
736
+ * a recycled pid cannot stand in for the old writer; an unavailable token proves
737
+ * nothing and counts as alive.
738
+ *
739
+ * The process group is deliberately not writer evidence: only the child pi writes
740
+ * the session, and treating a surviving tool descendant as a writer would strand
741
+ * the conversation until that descendant exits.
742
+ */
743
+ function recordedWriterLive(meta: RunMeta, probe?: LeaseProbe): boolean {
744
+ const pid = meta.pid;
745
+ if (typeof pid !== "number" || pid <= 0 || !processExists(pid)) return false;
746
+ if (meta.pidStartTime === undefined) return true;
747
+ const current = (probe?.startToken ?? processStartToken)(pid);
748
+ if (current === undefined) return true;
749
+ return current === meta.pidStartTime;
750
+ }
751
+
752
+ /** True when the held pid now belongs to an unrelated process. */
753
+ function holderRecycled(payload: LeasePayload, probe?: LeaseProbe): boolean {
754
+ if (payload.start === undefined) return false;
755
+ const current = (probe?.startToken ?? processStartToken)(payload.pid);
756
+ return current !== undefined && current !== payload.start;
757
+ }
758
+
759
+ /**
760
+ * Whether an existing lease may be recovered. Conservative by design: a live
761
+ * holder keeps its lease unless its recorded start identity proves pid
762
+ * recycling, and a dead or recycled holder is still not quiescence while the
763
+ * attempt's own child is alive. That child outlives the process that took the
764
+ * lease, so it is checked before any creator-death or terminal-status
765
+ * conclusion, including `killed`/`lost` whose kill may not have landed yet.
766
+ *
767
+ * A missing attempt record proves nothing about the child: the launch sequence
768
+ * acquires the lease, spawns the detached child, and only then publishes
769
+ * metadata. A dead holder with no record can therefore be a live writer whose
770
+ * supervisor crashed in that window. Such a lease is refused until an operator
771
+ * explicitly recovers the conversation or starts a new one.
772
+ */
773
+ function leaseReclaimable(
774
+ leasePath: string,
775
+ raw: string,
776
+ now: number,
777
+ probe?: LeaseProbe,
778
+ explicitRecovery = false,
779
+ ): boolean {
780
+ const payload = parseLeasePayload(raw);
781
+ if (!payload) {
782
+ try {
783
+ return now - statSync(leasePath).mtimeMs > UNPARSABLE_LEASE_GRACE_MS;
784
+ } catch (error) {
785
+ if (errnoOf(error) === "ENOENT") return true;
786
+ return false;
787
+ }
788
+ }
789
+ const own = payload.pid === process.pid;
790
+ if (!own && processExists(payload.pid) && !holderRecycled(payload, probe)) return false;
791
+ const meta = readAttemptMeta(payload.attemptId);
792
+ if (!meta) {
793
+ if (!explicitRecovery) return false;
794
+ // Even an explicit recovery keeps the same grace for this process's own
795
+ // just-published lease, so an in-flight admission is not stolen from.
796
+ if (own && now - payload.at < TERMINAL_ATTEMPT_RECLAIM_MS) return false;
797
+ return true;
798
+ }
799
+ if (recordedWriterLive(meta, probe)) return false;
800
+ if (!own) return true;
801
+ if (now - payload.at < TERMINAL_ATTEMPT_RECLAIM_MS) return false;
802
+ return isTerminalStatus(meta.status);
803
+ }
804
+
805
+ function isTerminalStatus(status: RunStatus): boolean {
806
+ return status === "completed" || status === "failed" || status === "killed" || status === "lost";
807
+ }
808
+
809
+ function conversationBusy(sessionId: string, attemptId: string): ConversationBusyError {
810
+ return new ConversationBusyError(
811
+ `Cannot continue ${attemptId}: conversation ${sessionId} is already being written by another attempt.`,
812
+ );
813
+ }
814
+
815
+ function readLeaseRaw(leasePath: string): string | undefined {
816
+ try {
817
+ return readFileSync(leasePath, "utf-8");
818
+ } catch (error) {
819
+ if (errnoOf(error) === "ENOENT") return undefined;
820
+ throw error;
821
+ }
822
+ }
823
+
824
+ /**
825
+ * Publish one complete lease at its path. The caller holds the conversation
826
+ * mutation lock, so an existing lease was either judged recoverable or
827
+ * admission already refused.
828
+ *
829
+ * A fresh path is published with a hard link (never overwriting an unknown
830
+ * holder). Reclaiming an existing path atomically renames the new complete
831
+ * lease over it, so no reader — including cleanup, which does not take this
832
+ * lock — can observe an empty path while a stale holder is being replaced.
833
+ */
834
+ function publishLeaseUnlocked(leasePath: string, serialized: string, replace: boolean): void {
835
+ const creating = join(dirname(leasePath), `.${randomBytes(8).toString("hex")}.creating`);
836
+ writeFileSync(creating, serialized, { mode: 0o600, flag: "wx" });
837
+ try {
838
+ if (replace) renameSync(creating, leasePath);
839
+ else linkSync(creating, leasePath);
840
+ } catch (error) {
841
+ try { unlinkSync(creating); } catch { /* best effort */ }
842
+ if (errnoOf(error) === "EEXIST") {
843
+ throw new ConversationBusyError("Conversation lease changed during a serialized admission.");
844
+ }
845
+ throw error;
846
+ }
847
+ if (!replace) {
848
+ try { unlinkSync(creating); } catch { /* best effort */ }
849
+ }
850
+ }
851
+
852
+ /** Remove only the exact lease this holder published. Caller holds the lock. */
853
+ function releaseLeaseUnlocked(leasePath: string, serialized: string): void {
854
+ const observed = readLeaseRaw(leasePath);
855
+ if (observed === undefined || observed !== serialized) return;
856
+ try {
857
+ unlinkSync(leasePath);
858
+ } catch (error) {
859
+ if (errnoOf(error) !== "ENOENT") throw error;
860
+ }
861
+ }
862
+
863
+ /**
864
+ * Acquire the conversation writer lease.
865
+ *
866
+ * Admission is one serialized critical section: existing bytes are inspected
867
+ * and a recoverable lease is replaced atomically with this holder's complete
868
+ * lease before the transaction ends. No other admission can enter the section,
869
+ * and the path is never empty during replacement, which is what makes stale
870
+ * recovery unable to displace a newer holder or admit a second writer.
871
+ *
872
+ * `waitMs` defaults to 0 so duplicate admission fails fast instead of stalling
873
+ * the foreground event loop. `explicitRecovery` is an operator escape for a
874
+ * conversation whose writer evidence is permanently unavailable (for example a
875
+ * supervisor killed between spawning its child and publishing metadata); it is
876
+ * never used by ordinary continuation.
877
+ */
878
+ export function acquireConversationLease(options: {
879
+ sessionId: string;
880
+ attemptId: string;
881
+ waitMs?: number;
882
+ now?: () => number;
883
+ probe?: LeaseProbe;
884
+ explicitRecovery?: boolean;
885
+ }): ConversationLease {
886
+ const { sessionId, attemptId } = options;
887
+ if (!isSafeRunId(sessionId)) throw new Error("Invalid session id for a conversation lease.");
888
+ const now = options.now ?? Date.now;
889
+ try {
890
+ return withConversationMutation(sessionId, () => {
891
+ const leasePath = leasePathFor(sessionId);
892
+ const payload: LeasePayload = {
893
+ pid: process.pid,
894
+ start: processStartToken(process.pid),
895
+ token: randomBytes(16).toString("hex"),
896
+ sessionId,
897
+ attemptId,
898
+ at: now(),
899
+ };
900
+ if (payload.start === undefined) delete (payload as { start?: string }).start;
901
+ const serialized = JSON.stringify(payload);
902
+ const existing = readLeaseRaw(leasePath);
903
+ let replace = false;
904
+ if (existing !== undefined) {
905
+ if (!leaseReclaimable(leasePath, existing, now(), options.probe, options.explicitRecovery)) {
906
+ throw conversationBusy(sessionId, attemptId);
907
+ }
908
+ replace = true;
909
+ }
910
+ publishLeaseUnlocked(leasePath, serialized, replace);
911
+ let released = false;
912
+ return {
913
+ sessionId,
914
+ attemptId,
915
+ token: payload.token,
916
+ path: leasePath,
917
+ release() {
918
+ if (released) return;
919
+ withConversationMutation(
920
+ sessionId,
921
+ () => releaseLeaseUnlocked(leasePath, serialized),
922
+ { waitMs: RELEASE_LOCK_WAIT_MS },
923
+ );
924
+ released = true;
925
+ },
926
+ };
927
+ }, { waitMs: Math.max(0, options.waitMs ?? ADMISSION_LOCK_WAIT_MS) });
928
+ } catch (error) {
929
+ if (error instanceof ConversationBusyError) throw conversationBusy(sessionId, attemptId);
930
+ throw error;
931
+ }
932
+ }
933
+
934
+ /** Test/diagnostic seam: the lease currently published for a conversation. */
935
+ export function readConversationLease(sessionId: string): (LeasePayload & { raw: string }) | undefined {
936
+ if (!isSafeRunId(sessionId)) return undefined;
937
+ try {
938
+ const raw = readFileSync(leasePathFor(sessionId), "utf-8");
939
+ const payload = parseLeasePayload(raw);
940
+ return payload ? { ...payload, raw } : undefined;
941
+ } catch {
942
+ return undefined;
943
+ }
944
+ }