pi-better-subagents 0.25.1 → 0.26.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -12,7 +12,7 @@ Use `pi-better-subagents` when you want Pi to launch independent agent work with
12
12
 
13
13
  ## Core Features
14
14
  - Non-blocking subagent launches, with an optional role and named-agent catalog (`docs/agent-catalog.md`, `docs/agent-catalog-lifecycle.md`).
15
- - Completed-subagent continuation: `subagent_resume` continues a saved single or batch conversation under a new attempt id. Retention is optional cleanup protection: `retain_session` pins artifacts, and `subagent_release` removes that protection without invalidating history that still exists. See [continuing a completed subagent](docs/usage.md#continuing-a-completed-subagent).
15
+ - Continue a saved conversation with `subagent_spawn({ session_id, prompt })`, or use `session_name` for a unique name in the current folder. Sessions persist by default. Lists show session IDs and search locally; `all:true` searches globally. Batch jobs use the same selectors. See [continuing a saved conversation](docs/usage.md#continuing-a-saved-conversation).
16
16
  - Typed foreground `subagent_spawn_batch` launch receipts for native Pi codemode (Pi 0.99.1+), preserving direct tool calls, per-run callbacks, and batch capacity/catalog guarantees. See [codemode batch launches](docs/usage.md#codemode-batch-launches).
17
17
  - Opt-in OS task sandboxing on macOS and Linux.
18
18
  - Explicit tool allowlists for child sessions.
package/batch.mjs CHANGED
@@ -25,7 +25,7 @@ export const batchLaunchOutputSchema = {
25
25
  type: "array",
26
26
  items: {
27
27
  type: "object",
28
- properties: { job: { type: "integer", minimum: 1 }, name: { type: "string" }, id: { type: "string" }, modelNote: { type: "string" } },
28
+ properties: { job: { type: "integer", minimum: 1 }, name: { type: "string" }, id: { type: "string" }, sessionId: { type: "string" }, continuedFrom: { type: "string" }, modelNote: { type: "string" } },
29
29
  required: ["job", "name", "id"],
30
30
  additionalProperties: false,
31
31
  },
@@ -94,6 +94,10 @@ export function mergeJobOptions(shared, job) {
94
94
  git_clone_workspace: job.git_clone_workspace ?? shared?.git_clone_workspace,
95
95
  approve: job.approve ?? shared?.approve,
96
96
  allow_nested: job.allow_nested ?? shared?.allow_nested,
97
+ // Native session id selected for this JOB only. A shared value would make
98
+ // every job contend for the same conversation writer, so it is not inherited.
99
+ session_id: typeof job.session_id === "string" ? job.session_id : undefined,
100
+ session_name: typeof job.session_name === "string" ? job.session_name : undefined,
97
101
  // Harness timing; an explicit null means "not set", so it falls through to shared.
98
102
  deadline_minutes: job.deadline_minutes ?? shared?.deadline_minutes,
99
103
  grace_minutes: job.grace_minutes ?? shared?.grace_minutes,
@@ -149,6 +153,11 @@ export function validateBatchPlan({ shared, jobs, onCapacity, config }) {
149
153
  if (typeof job.prompt !== "string" || job.prompt.trim() === "") {
150
154
  throw new Error(`job ${i + 1} is missing a non-empty prompt.`);
151
155
  }
156
+ if (job.session_id !== undefined && job.session_name !== undefined) throw new Error(`job ${i + 1}: pass either session_id or session_name, not both.`);
157
+ if (job.session_name !== undefined && (typeof job.session_name !== "string" || job.session_name.trim() === "")) throw new Error(`job ${i + 1} session_name must be a non-empty name.`);
158
+ if (job.session_id !== undefined && (typeof job.session_id !== "string" || job.session_id.trim() === "")) {
159
+ throw new Error(`job ${i + 1} session_id must be a non-empty native session id.`);
160
+ }
152
161
  if (seenPrompts.has(job.prompt)) {
153
162
  // Duplicate prompts are allowed, but a batch with every prompt
154
163
  // identical is a common mistake; warn via the error path only when
@@ -273,8 +282,8 @@ export function formatBatchLaunchResponse({ batchId, batchName, launched, skippe
273
282
  lines.push(
274
283
  `Batch ${label} launched ${launched.length} subagent(s):`,
275
284
  );
276
- for (const { name, id, modelNote } of launched) {
277
- lines.push(`• ${name} → ${id}${modelNote ? ` · ${modelNote}` : ""}`);
285
+ for (const { name, id, sessionId, modelNote } of launched) {
286
+ lines.push(`• ${name} → ${id}${sessionId && sessionId !== id ? ` (session ${sessionId})` : ""}${modelNote ? ` · ${modelNote}` : ""}`);
278
287
  }
279
288
  }
280
289
 
@@ -222,12 +222,16 @@ export async function clarifyCatalogRequest(
222
222
  const normalized = jobs.map((job, index) => ({
223
223
  job: { ...job, catalogJobIndex: index },
224
224
  index,
225
- agent: agentIdOf(job),
226
- roles: roleIdsOf(job),
225
+ continuation: job.session_id !== undefined || job.session_name !== undefined,
226
+ agent: job.session_id !== undefined || job.session_name !== undefined ? undefined : agentIdOf(job),
227
+ roles: job.session_id !== undefined || job.session_name !== undefined ? [] : roleIdsOf(job),
227
228
  }));
228
229
  const clean: CatalogJobFields[] = [];
229
230
  const pending: { job: CatalogJobFields; index: number; agent?: string; roles: string[] }[] = [];
230
231
  for (const item of normalized) {
232
+ // Saved conversations keep their launch recipe. Repeated selectors are
233
+ // checked against that recipe at admission, never clarified or expanded.
234
+ if (item.continuation) { clean.push(item.job); continue; }
231
235
  if (item.roles.length > 1 || (item.agent && item.roles.length > 0)) pending.push(item);
232
236
  else clean.push(withSelector(item.job, { agent: item.agent, role: item.roles[0] }));
233
237
  }
package/cleanup.ts CHANGED
@@ -9,11 +9,15 @@ import {
9
9
  } from "node:fs";
10
10
  import { join, relative, sep } from "node:path";
11
11
  import {
12
+ ABANDONED_LAUNCH_GRACE_MS,
13
+ abandonedLaunchRecord,
12
14
  baseDir,
13
15
  listMetas,
16
+ observeArchivePublication,
14
17
  ownedByThisParent,
15
18
  orphanedTaskRuntimeProvenance,
16
19
  processStartToken,
20
+ purgeAbandonedLaunch,
17
21
  readMeta,
18
22
  removeMetaArtifacts,
19
23
  removeRunDirectory,
@@ -35,6 +39,7 @@ import {
35
39
  withConversationMutation,
36
40
  } from "./continuation.ts";
37
41
  import { processExists } from "./spawn.ts";
42
+ import { archiveCompletedAttempt, archivePublicationPending, listArchivedAttempts } from "./session-store.ts";
38
43
 
39
44
  export const DEFAULT_CLEANUP_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
40
45
 
@@ -80,6 +85,14 @@ export interface DailyCleanupResult {
80
85
  dateKey: string;
81
86
  removedRunDirs: number;
82
87
  removedSessionPaths: number;
88
+ /** Launch attempts that never produced a run, reclaimed on this pass. */
89
+ removedAbandonedLaunches: number;
90
+ errors: string[];
91
+ }
92
+
93
+ /** Outcome of the launch-debris sweep alone (unit-testable, no daily marker). */
94
+ export interface AbandonedLaunchSweepResult {
95
+ removed: string[];
83
96
  errors: string[];
84
97
  }
85
98
 
@@ -346,6 +359,70 @@ function planCleanupOccupancy(
346
359
  interface CleanupScope {
347
360
  occupancy: CleanupOccupancy;
348
361
  runIdsBySession: Map<string, string[]>;
362
+ /**
363
+ * Conversations whose saved session and launch recipe live in durable
364
+ * storage. Their history and owned clone workspace never age out; only the
365
+ * volatile log, metadata, and task scratch are reclaimed.
366
+ */
367
+ persistent: ReadonlySet<string>;
368
+ /**
369
+ * Completed attempts whose compact durable record is still unpublished. The
370
+ * volatile run directory holds the only copy of the recipe, so both bounds
371
+ * retain the whole run until a sweep can publish it.
372
+ */
373
+ archivePending: ReadonlySet<string>;
374
+ }
375
+
376
+ /**
377
+ * Conversations with a durable continuation record: a completed attempt saved
378
+ * its compact metadata and frozen recipe under the Pi agent directory. Their
379
+ * saved history and owned clone workspace are kept indefinitely; only the
380
+ * volatile log, metadata, and task scratch are reclaimed.
381
+ *
382
+ * A completed durable-layout attempt whose compact record could not be published
383
+ * belongs here too: it is not resumable yet, but its recipe, saved history, and
384
+ * clone are the only copy of that conversation.
385
+ *
386
+ * Legacy attempts (recipes pointing at the old temporary session directory, or
387
+ * fixtures without a recipe) never publish that record and keep the existing
388
+ * reclaimable behavior. A conversation that only ever failed is not resumable,
389
+ * so its artifacts stay ordinary aged history and do not pin a clone forever.
390
+ */
391
+ function persistentSessionIds(
392
+ metas: readonly RunMeta[],
393
+ archivePending: ReadonlySet<string>,
394
+ ): Set<string> {
395
+ const sessions = new Set(listArchivedAttempts().map((meta) => meta.sessionId));
396
+ for (const meta of metas) {
397
+ if (archivePending.has(meta.id)) sessions.add(meta.sessionId);
398
+ }
399
+ return sessions;
400
+ }
401
+
402
+ /**
403
+ * Retry publication of every completed attempt whose compact durable record is
404
+ * missing, BEFORE either bound decides what to delete.
405
+ *
406
+ * The volatile run directory is the only place a completed attempt's recipe
407
+ * lives until that record is published, so this pass is what makes the age and
408
+ * size bounds safe: while it keeps failing, the runs it names are retained (see
409
+ * `CleanupScope.archivePending`), and once it succeeds they are ordinary
410
+ * persistent conversations whose raw logs may be reclaimed.
411
+ *
412
+ * Returns the run ids still unpublished.
413
+ */
414
+ function retryPendingArchives(metas: readonly RunMeta[]): Set<string> {
415
+ const pending = new Set<string>();
416
+ for (const meta of metas) {
417
+ if (!archivePublicationPending(meta)) continue;
418
+ try {
419
+ if (archiveCompletedAttempt(meta)) observeArchivePublication(meta.id);
420
+ } catch (error) {
421
+ observeArchivePublication(meta.id, error);
422
+ }
423
+ if (archivePublicationPending(meta)) pending.add(meta.id);
424
+ }
425
+ return pending;
349
426
  }
350
427
 
351
428
  function runIdsBySession(metas: readonly RunMeta[]): Map<string, string[]> {
@@ -457,7 +534,7 @@ function cleanRunDirs(cutoff: number, scope: CleanupScope, errors: string[]): nu
457
534
  const dir = runDir(id);
458
535
  const meta = readMeta(id);
459
536
  if (meta) {
460
- if (!ageSweepEligible(meta, cutoff, retained, scope.occupancy)) continue;
537
+ if (!ageSweepEligible(meta, cutoff, retained, scope)) continue;
461
538
  if (removeAgedRunArtifacts(meta, cutoff, retained, scope, errors)) removed += 1;
462
539
  continue;
463
540
  }
@@ -480,13 +557,15 @@ function ageSweepEligible(
480
557
  meta: RunMeta,
481
558
  cutoff: number,
482
559
  retained: ReadonlySet<string>,
483
- occupancy: CleanupOccupancy,
560
+ scope: CleanupScope,
484
561
  ): boolean {
485
562
  if (!TERMINAL_CLEANUP_STATUSES.has(meta.status)) return false;
486
563
  if (retained.has(meta.sessionId)) return false;
564
+ // The run directory still holds the only copy of this conversation's recipe.
565
+ if (scope.archivePending.has(meta.id)) return false;
487
566
  // A released conversation can still be in use: a later attempt may run
488
567
  // inside this root's clone, or a stop/kill may not have landed.
489
- if (occupancy.runIds.has(meta.id)) return false;
568
+ if (scope.occupancy.runIds.has(meta.id)) return false;
490
569
  return terminalTimestamp(meta) < cutoff;
491
570
  }
492
571
 
@@ -515,8 +594,8 @@ function removeAgedRunArtifacts(
515
594
  return withConversationSerialization(meta.sessionId, () => {
516
595
  if (!conversationQuiescentUnderLock(meta.sessionId, runIds)) return false;
517
596
  const fresh = readMeta(meta.id) ?? meta;
518
- if (!ageSweepEligible(fresh, cutoff, retained, scope.occupancy)) return false;
519
- if (removeMetaArtifacts(fresh)) return true;
597
+ if (!ageSweepEligible(fresh, cutoff, retained, scope)) return false;
598
+ if (removeMetaArtifacts(fresh, { keepWorkspace: scope.persistent.has(fresh.sessionId) })) return true;
520
599
  errors.push(`${runDir(meta.id)}: could not remove run artifacts`);
521
600
  return false;
522
601
  }, () => false);
@@ -528,8 +607,8 @@ function removeAgedRunArtifacts(
528
607
  * `<timestamp>_<sessionId>.jsonl` name, or the bare conversation name. History
529
608
  * that resolves to nothing this sweep knows stays on the ordinary path.
530
609
  */
531
- function sessionIdForPath(path: string, serialized: ReadonlySet<string>): string | undefined {
532
- const rel = relative(sessionsDir(), path);
610
+ function sessionIdForPath(root: string, path: string, serialized: ReadonlySet<string>): string | undefined {
611
+ const rel = relative(root, path);
533
612
  if (!rel || rel.startsWith("..")) return undefined;
534
613
  const known = [...new Set(pathNameCandidates(rel.split(sep)))].filter((candidate) => serialized.has(candidate));
535
614
  // Two different tracked conversations in one path is not a layout this
@@ -553,12 +632,13 @@ function* pathNameCandidates(parts: readonly string[]): Generator<string> {
553
632
  * when this sweep tracks that conversation.
554
633
  */
555
634
  function removeSessionPath(
635
+ root: string,
556
636
  path: string,
557
637
  serialized: ReadonlySet<string>,
558
638
  scope: CleanupScope,
559
639
  errors: string[],
560
640
  ): boolean {
561
- const sessionId = sessionIdForPath(path, serialized);
641
+ const sessionId = sessionIdForPath(root, path, serialized);
562
642
  if (!sessionId) return removePath(path, errors);
563
643
  const runIds = scope.runIdsBySession.get(sessionId) ?? [];
564
644
  return withConversationSerialization(sessionId, () => {
@@ -567,7 +647,7 @@ function removeSessionPath(
567
647
  }, () => false);
568
648
  }
569
649
 
570
- function activeSessionIds(metas: RunMeta[], occupancy: CleanupOccupancy): Set<string> {
650
+ function activeSessionIds(metas: RunMeta[], occupancy: CleanupOccupancy, persistent: ReadonlySet<string>): Set<string> {
571
651
  const active = new Set<string>(occupancy.sessions);
572
652
  for (const meta of metas) {
573
653
  if (meta.status === "running" || meta.status === "orphaned") active.add(meta.sessionId);
@@ -575,12 +655,14 @@ function activeSessionIds(metas: RunMeta[], occupancy: CleanupOccupancy): Set<st
575
655
  // A retained completed conversation is not active work, but its saved
576
656
  // session file is the history a continuation reopens.
577
657
  for (const sessionId of retainedSessionIds()) active.add(sessionId);
658
+ // Durable conversations never expire with the volatile sweeps either.
659
+ for (const sessionId of persistent) active.add(sessionId);
578
660
  return active;
579
661
  }
580
662
 
581
- function pathMentionsActiveSession(path: string, active: Set<string>): boolean {
663
+ function pathMentionsActiveSession(root: string, path: string, active: Set<string>): boolean {
582
664
  if (active.size === 0) return false;
583
- const rel = relative(sessionsDir(), path);
665
+ const rel = relative(root, path);
584
666
  for (const sessionId of active) {
585
667
  if (sessionId && rel.includes(sessionId)) return true;
586
668
  }
@@ -588,6 +670,7 @@ function pathMentionsActiveSession(path: string, active: Set<string>): boolean {
588
670
  }
589
671
 
590
672
  function cleanSessionTree(
673
+ root: string,
591
674
  cutoff: number,
592
675
  active: Set<string>,
593
676
  protectedPaths: readonly string[],
@@ -595,7 +678,6 @@ function cleanSessionTree(
595
678
  serialized: ReadonlySet<string>,
596
679
  errors: string[],
597
680
  ): number {
598
- const root = sessionsDir();
599
681
  if (!existsSync(root)) return 0;
600
682
  let removed = 0;
601
683
 
@@ -614,10 +696,10 @@ function cleanSessionTree(
614
696
  if (entry.isDirectory()) {
615
697
  const childEmpty = visit(path);
616
698
  if (childEmpty
617
- && !pathMentionsActiveSession(path, active)
699
+ && !pathMentionsActiveSession(root, path, active)
618
700
  && !pathOverlapsProtected(path, protectedPaths)) {
619
701
  const mtimeMs = safeStatMtime(path);
620
- if (mtimeMs !== undefined && mtimeMs < cutoff && removeSessionPath(path, serialized, scope, errors)) {
702
+ if (mtimeMs !== undefined && mtimeMs < cutoff && removeSessionPath(root, path, serialized, scope, errors)) {
621
703
  removed += 1;
622
704
  continue;
623
705
  }
@@ -626,12 +708,12 @@ function cleanSessionTree(
626
708
  continue;
627
709
  }
628
710
 
629
- if (pathMentionsActiveSession(path, active) || pathOverlapsProtected(path, protectedPaths)) {
711
+ if (pathMentionsActiveSession(root, path, active) || pathOverlapsProtected(path, protectedPaths)) {
630
712
  empty = false;
631
713
  continue;
632
714
  }
633
715
  const mtimeMs = safeStatMtime(path);
634
- if (mtimeMs !== undefined && mtimeMs < cutoff && removeSessionPath(path, serialized, scope, errors)) {
716
+ if (mtimeMs !== undefined && mtimeMs < cutoff && removeSessionPath(root, path, serialized, scope, errors)) {
635
717
  removed += 1;
636
718
  continue;
637
719
  }
@@ -644,31 +726,90 @@ function cleanSessionTree(
644
726
  return removed;
645
727
  }
646
728
 
729
+ /**
730
+ * Reclaim launch attempts that never produced a supervised run (#623).
731
+ *
732
+ * A launch that throws while preparing (or a pi that dies in that window) can
733
+ * leave a run directory with only `prompt.md` and a sandbox `control/` dir: no
734
+ * `meta.json`, no `output.log`. Such a directory is unreadable run evidence
735
+ * forever and skews `subagent_list` counts, so it is reclaimed once it is older
736
+ * than {@link ABANDONED_LAUNCH_GRACE_MS}. The grace is the only guard needed:
737
+ * launch preparation is synchronous and short, and a directory with a log is
738
+ * never debris (the child may have started and its output is real evidence).
739
+ *
740
+ * Age alone is not an ownership proof: `purgeAbandonedLaunch` re-classifies and
741
+ * removes under the run's metadata lock, and a launch claim owned by a live
742
+ * process makes the record not-debris at any age, so a preparer that is paused
743
+ * past the grace is preserved and the sweep never deletes a live attempt's
744
+ * artifacts (#623 R1). A record a writer retained is left for the next sweep
745
+ * with an error so the retention stays visible.
746
+ *
747
+ * Runs before the daily marker in {@link runDailyCleanupOnce}, so every launch
748
+ * reclaims earlier debris instead of waiting for the next day's sweep.
749
+ * Best-effort; never throws into its caller.
750
+ */
751
+ export function sweepAbandonedLaunches(options: { now?: number; graceMs?: number } = {}): AbandonedLaunchSweepResult {
752
+ const now = options.now ?? Date.now();
753
+ const grace = Number.isFinite(options.graceMs) && options.graceMs! >= 0 ? options.graceMs! : ABANDONED_LAUNCH_GRACE_MS;
754
+ const cutoff = now - grace;
755
+ let ids: string[];
756
+ try {
757
+ ids = readdirSync(join(baseDir(), "runs"));
758
+ } catch {
759
+ return { removed: [], errors: [] };
760
+ }
761
+ const removed: string[] = [];
762
+ const errors: string[] = [];
763
+ for (const id of ids) {
764
+ const attempt = abandonedLaunchRecord(id);
765
+ if (!attempt || attempt.mtimeMs >= cutoff) continue;
766
+ const purge = purgeAbandonedLaunch(id);
767
+ if (purge === "purged") removed.push(id);
768
+ else if (purge === "retained") errors.push(`${runDir(id)}: abandoned launch record could not be removed (in use, or its lock is unavailable)`);
769
+ }
770
+ return { removed, errors };
771
+ }
772
+
647
773
  export function runDailyCleanupOnce(options: DailyCleanupOptions = {}): DailyCleanupResult {
648
774
  const now = options.now ?? Date.now();
775
+ const abandoned = sweepAbandonedLaunches({ now });
649
776
  const dateKey = localDateKey(now);
650
777
  const state = readCleanupState();
651
778
  if (state.lastLocalDate === dateKey) {
652
- return { ran: false, dateKey, removedRunDirs: 0, removedSessionPaths: 0, errors: [] };
779
+ return { ran: false, dateKey, removedRunDirs: 0, removedSessionPaths: 0, removedAbandonedLaunches: abandoned.removed.length, errors: [...abandoned.errors] };
653
780
  }
654
781
 
655
782
  const errors: string[] = [];
656
783
  const terminalRetention = retentionMs(options.terminalRunRetentionMs, options.config?.cleanupTerminalRunRetentionMs);
657
784
  const sessionRetention = retentionMs(options.sessionRetentionMs, options.config?.cleanupSessionRetentionMs);
658
785
  const metas = listMetas();
786
+ // Publish any outstanding compact record before this sweep reclaims the only
787
+ // copy of a completed attempt's recipe.
788
+ const archivePending = retryPendingArchives(metas);
789
+ const persistent = persistentSessionIds(metas, archivePending);
659
790
  const scope: CleanupScope = {
660
791
  occupancy: planCleanupOccupancy(metas, options.protect),
661
792
  runIdsBySession: runIdsBySession(metas),
793
+ persistent,
794
+ archivePending,
662
795
  };
663
796
  const removedRunDirs = cleanRunDirs(now - terminalRetention, scope, errors);
664
- const removedSessionPaths = cleanSessionTree(
665
- now - sessionRetention,
666
- activeSessionIds(metas, scope.occupancy),
667
- scope.occupancy.paths,
668
- scope,
669
- serializedConversations(metas),
670
- errors,
671
- );
797
+ // Native saved history is durable regardless of the latest attempt status.
798
+ // Sweep only legacy temporary sessions; eligibility to resume must never
799
+ // determine whether a durable native conversation is kept.
800
+ const sessionRoots = [join(baseDir(), "sessions")];
801
+ let removedSessionPaths = 0;
802
+ for (const root of sessionRoots) {
803
+ removedSessionPaths += cleanSessionTree(
804
+ root,
805
+ now - sessionRetention,
806
+ activeSessionIds(metas, scope.occupancy, persistent),
807
+ scope.occupancy.paths,
808
+ scope,
809
+ serializedConversations(metas),
810
+ errors,
811
+ );
812
+ }
672
813
 
673
814
  try {
674
815
  writeCleanupState({ lastLocalDate: dateKey, lastRunAt: now });
@@ -676,7 +817,7 @@ export function runDailyCleanupOnce(options: DailyCleanupOptions = {}): DailyCle
676
817
  errors.push(`${cleanupStatePath()}: ${err instanceof Error ? err.message : String(err)}`);
677
818
  }
678
819
 
679
- return { ran: true, dateKey, removedRunDirs, removedSessionPaths, errors };
820
+ return { ran: true, dateKey, removedRunDirs, removedSessionPaths, removedAbandonedLaunches: abandoned.removed.length, errors: [...abandoned.errors, ...errors] };
680
821
  }
681
822
 
682
823
  /** Bytes held under one run directory. Best-effort; unreadable entries count 0. */
@@ -767,6 +908,10 @@ export function enforceRegistrySizeCapOnce(options: SizeCapOptions = {}): SizeCa
767
908
  ?? (Number.isFinite(configured) && configured! > 0 ? configured! : DEFAULT_MAX_REGISTRY_BYTES);
768
909
 
769
910
  const errors: string[] = [];
911
+ // Same ordering as the age sweep: retry archival first, so a run whose
912
+ // recipe only exists in its volatile directory is never a removal candidate.
913
+ const metas = listMetas();
914
+ const archivePending = retryPendingArchives(metas);
770
915
  const entries = collectSizeCapEntries();
771
916
  // Retained conversations and their workspaces are exempt from the byte
772
917
  // bound until the owner releases them; a size sweep must not delete the
@@ -776,17 +921,20 @@ export function enforceRegistrySizeCapOnce(options: SizeCapOptions = {}): SizeCa
776
921
  // Occupancy costs a metadata scan and lease reads, so it is only computed
777
922
  // when this sweep would actually remove something.
778
923
  const totalBytes = entries.reduce((sum, entry) => sum + entry.bytes, 0);
779
- const metas = listMetas();
780
924
  const occupancy = totalBytes > maxBytes ? planCleanupOccupancy(metas, options.protect) : undefined;
781
925
  const protectedIds = new Set([
782
926
  ...(options.protectedIds ?? ownRunIds(metas)),
783
927
  ...retainedRunIds(metas),
784
928
  ...(occupancy?.runIds ?? []),
929
+ // An unpublished compact record is the recipe's only copy.
930
+ ...archivePending,
785
931
  ]);
786
932
  const plan = planRegistrySizeCap(entries, { maxBytes, protectedIds });
787
933
  const scope: CleanupScope = {
788
934
  occupancy: occupancy ?? { sessions: new Set(), runIds: new Set(), paths: [] },
789
935
  runIdsBySession: runIdsBySession(metas),
936
+ persistent: persistentSessionIds(metas, archivePending),
937
+ archivePending,
790
938
  };
791
939
  const bytesById = new Map(entries.map((entry) => [entry.id, entry.bytes]));
792
940
  const removed: string[] = [];
@@ -830,7 +978,7 @@ function removeSizeCappedRun(
830
978
  const fresh = readMeta(id) ?? meta;
831
979
  if (!TERMINAL_CLEANUP_STATUSES.has(fresh.status)) return "retained";
832
980
  if (scope.occupancy.runIds.has(fresh.id)) return "retained";
833
- if (removeMetaArtifacts(fresh)) return "removed";
981
+ if (removeMetaArtifacts(fresh, { keepWorkspace: scope.persistent.has(fresh.sessionId) })) return "removed";
834
982
  errors.push(`${runDir(id)}: could not remove run artifacts`);
835
983
  return "failed";
836
984
  }, () => "retained");
package/continuation.ts CHANGED
@@ -1,11 +1,17 @@
1
1
  /**
2
- * Completed-subagent continuation.
2
+ * Subagent continuation.
3
3
  *
4
4
  * A subagent attempt is one detached `pi -p` process; its conversation is a
5
5
  * saved native session JSONL that outlives the process. Continuation keeps the
6
6
  * conversation and allocates a NEW attempt, so old logs, results, callback
7
7
  * markers, and timing records stay intact under their own run id.
8
8
  *
9
+ * A completed attempt and an interrupted attempt stopped by `subagent_stop`
10
+ * (status `killed`) are both continuable: stopping ends an execution, not the
11
+ * saved conversation or the uncommitted workspace it leaves behind. The stopped
12
+ * attempt is never rewritten; the next attempt keeps `rootRunId` and records
13
+ * `resumedFrom`, so the interruption and its recovery stay distinguishable.
14
+ *
9
15
  * This module owns the four seams that decision needs and that the rest of the
10
16
  * package must not duplicate:
11
17
  *
@@ -18,9 +24,19 @@
18
24
  * clean/nesting/approval intent, confinement, model, effort, role identity,
19
25
  * workspace intent) on run metadata.
20
26
  * 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.
27
+ * completed conversation and its workspace stay out of cleanup until a
28
+ * foreground session releases it. Retention lives in the existing runtime
29
+ * storage, so system-temp reaping can still remove it; a missing
30
+ * conversation refuses.
31
+ *
32
+ * Foreground-session ownership is provenance, not an authorization boundary:
33
+ * Pi sessions are ordinary files on disk, so any foreground session that can
34
+ * name a continuable attempt with a verifiable saved conversation, workspace,
35
+ * and launch recipe may continue it (or release its optional retention). The new
36
+ * attempt records the INVOKING foreground as its callback origin and its
37
+ * permission admission is re-resolved from the current profile, so continuing
38
+ * transfers the run to the caller instead of borrowing the original owner's
39
+ * authority.
24
40
  * 4. **Conversation writer lease.** A cross-process token lease held from
25
41
  * admission through child lifetime and finalization. Duplicate continuations
26
42
  * of one conversation admit exactly one writer. Lease-path and retention
@@ -66,6 +82,7 @@ import {
66
82
  type RunStatus,
67
83
  } from "./registry.ts";
68
84
  import { processExists } from "./spawn.ts";
85
+ import { durableSubagentRoot } from "./session-store.ts";
69
86
 
70
87
  const nodeRequire = createRequire(import.meta.url);
71
88
 
@@ -231,7 +248,11 @@ export interface RetentionRecord {
231
248
  ownerRunId: string;
232
249
  /** Canonical workspace kept available for continuation. */
233
250
  workspace: string;
234
- /** Foreground session that may continue or release this conversation. */
251
+ /**
252
+ * Foreground session that first retained this conversation. Provenance for
253
+ * diagnostics only: retention is optional convenience, not a tenancy
254
+ * boundary, so any foreground session may release it.
255
+ */
235
256
  ownerOrigin: RunCallbackOrigin;
236
257
  retainedAt: number;
237
258
  lastAttemptId: string;
@@ -398,7 +419,14 @@ export function markRetentionReleased(
398
419
 
399
420
  // ---- ownership and continuation plan ------------------------------------
400
421
 
401
- /** True when `origin` is the foreground session recorded on the run. */
422
+ /**
423
+ * True when `origin` is the foreground session recorded on the run.
424
+ *
425
+ * This is a provenance/labelling helper, deliberately NOT an admission gate: a
426
+ * different foreground session may continue a continuable attempt (see the
427
+ * module header). Callers that need to route a notification use it to decide
428
+ * which foreground a run belongs to, not to deny an operation.
429
+ */
402
430
  export function ownedByOrigin(meta: RunMeta, origin: RunCallbackOrigin | undefined): boolean {
403
431
  const recorded = meta.callbackOrigin;
404
432
  if (!origin?.sessionId || typeof origin.cwd !== "string") return false;
@@ -429,7 +457,42 @@ function isActiveAttempt(meta: RunMeta): boolean {
429
457
  }
430
458
 
431
459
  /**
432
- * Validate one completed attempt for continuation and return the exact
460
+ * Terminal statuses whose saved conversation may be reopened by a new attempt.
461
+ * A stopped (`killed`) run is an interrupted execution, not a destroyed
462
+ * conversation; other terminal outcomes keep their existing refusal.
463
+ */
464
+ const CONTINUABLE_STATUSES: ReadonlySet<RunStatus> = new Set(["completed", "killed"]);
465
+
466
+ /**
467
+ * A recorded writer that may still be appending to the conversation.
468
+ *
469
+ * A fresh launch opens a brand-new session and takes no lease, so a killed
470
+ * attempt can be recorded terminal while its child is still alive (for example
471
+ * SIGTERM is pending behind SIGSTOP). In that state no lease blocks the next
472
+ * writer. Check the prior attempt explicitly — the active-sibling scan excludes
473
+ * it — plus every same-conversation attempt that is not known to have exited.
474
+ * `completed`/`failed` attempts are omitted because their compact durable
475
+ * records drop the process-start identity, so a recycled pid could otherwise
476
+ * block an unrelated conversation. `recordedWriterLive` applies the same pid
477
+ * and start-token evidence the conversation lease uses.
478
+ */
479
+ function findLiveConversationWriter(
480
+ prior: RunMeta,
481
+ others: readonly RunMeta[],
482
+ probe?: LeaseProbe,
483
+ ): RunMeta | undefined {
484
+ const candidates = [
485
+ prior,
486
+ ...others.filter((meta) => meta.sessionId === prior.sessionId
487
+ && meta.id !== prior.id
488
+ && meta.status !== "completed"
489
+ && meta.status !== "failed"),
490
+ ];
491
+ return candidates.find((meta) => recordedWriterLive(meta, probe));
492
+ }
493
+
494
+ /**
495
+ * Validate one continuable attempt for continuation and return the exact
433
496
  * conversation plus frozen recipe to relaunch. Every refusal is fail-closed:
434
497
  * nothing is spawned and no history is created or replaced.
435
498
  */
@@ -438,13 +501,19 @@ export function planContinuation(options: {
438
501
  prior: RunMeta | undefined;
439
502
  origin: RunCallbackOrigin | undefined;
440
503
  others: readonly RunMeta[];
504
+ /** Process-identity seam for the recorded-writer check. */
505
+ probe?: LeaseProbe;
441
506
  }): ContinuationPlan {
442
507
  const { id, prior, origin, others } = options;
443
508
  if (!prior) throw refusal(id, "no such run id.");
509
+ // The invoking foreground is still required, because the new attempt's
510
+ // completion callback and navigator entry are routed to it. It is not
511
+ // required to be the attempt's original owner: the saved session, workspace,
512
+ // and recipe are the thing being continued, and Pi sessions are shared
513
+ // on-disk state rather than a per-foreground boundary.
444
514
  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.`);
515
+ if (!CONTINUABLE_STATUSES.has(prior.status)) {
516
+ throw refusal(id, `its status is ${prior.status}; only a completed or stopped run can be continued. Stop a running attempt or launch a new run instead.`);
448
517
  }
449
518
  const recipe = prior.recipe;
450
519
  if (!recipe || recipe.version !== 1) throw refusal(id, "it was launched before continuation support, so no launch recipe was saved.");
@@ -454,6 +523,14 @@ export function planContinuation(options: {
454
523
  const active = others.find((meta) => meta.sessionId === prior.sessionId && meta.id !== prior.id && isActiveAttempt(meta));
455
524
  if (active) throw refusal(id, `attempt ${active.id} is still active in the same conversation; stop it first.`);
456
525
 
526
+ // A killed record means stop was requested, not that the writer exited. A
527
+ // fresh launch has no lease, so this check is the only admission barrier
528
+ // while the prior child can still append to the saved conversation.
529
+ const writer = findLiveConversationWriter(prior, others, options.probe);
530
+ if (writer) {
531
+ throw refusal(id, `attempt ${writer.id} is still active and may still be writing the conversation (pid ${writer.pid}); wait for it to exit before continuing.`);
532
+ }
533
+
457
534
  let workspaceIsDir = false;
458
535
  try { workspaceIsDir = statSync(recipe.cwd).isDirectory(); } catch { workspaceIsDir = false; }
459
536
  if (!workspaceIsDir) throw refusal(id, `its workspace ${recipe.cwd} is missing.`);
@@ -490,13 +567,13 @@ export function planRetentionRelease(options: {
490
567
  }): RetentionRecord {
491
568
  const { id, prior, origin, others } = options;
492
569
  if (!prior) throw new ContinuationError(`Cannot release ${id}: no such run id.`);
570
+ // Release is the same on-disk convenience promise as continuation: any
571
+ // foreground that can name the attempt may drop optional retention. The
572
+ // invoking identity is still required, because the record keeps `releasedBy`
573
+ // and the decision must be attributable to a real foreground session.
493
574
  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
575
  const record = readRetention(prior.sessionId);
496
576
  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
577
  if (record.releasedAt !== undefined) {
501
578
  throw new ContinuationError(`Cannot release ${id}: its retention was already released at ${new Date(record.releasedAt).toISOString()}.`);
502
579
  }
@@ -541,8 +618,14 @@ const ADMISSION_LOCK_WAIT_MS = 0;
541
618
  const RELEASE_LOCK_WAIT_MS = 1_000;
542
619
  const RETENTION_LOCK_WAIT_MS = 1_000;
543
620
 
621
+ /**
622
+ * Stable writer-lease root, independent of TMPDIR: a conversation is ordinary
623
+ * on-disk Pi state, so a foreground that restarts under a different temp root
624
+ * must still see the one writer slot. Retention records stay in the volatile
625
+ * registry as before.
626
+ */
544
627
  export function conversationLeaseDir(): string {
545
- return join(baseDir(), "conversation-leases");
628
+ return join(durableSubagentRoot(), "conversation-leases");
546
629
  }
547
630
 
548
631
  function leasePathFor(sessionId: string): string {