pi-better-subagents 0.26.0 → 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.
@@ -135,7 +135,14 @@ export const OUTPUT_PAGE_DEFAULTS = {
135
135
 
136
136
  export type OutputBudgetSurface = keyof typeof OUTPUT_BUDGET_BYTES;
137
137
 
138
- export type PageReset = "stale-cursor" | "source-replaced" | "compacted";
138
+ /**
139
+ * Why a supplied cursor was not followed. `cursor-corrupt` means the payload
140
+ * itself failed its integrity check — a hand-copied character, not evidence
141
+ * that the source changed or that the cursor belongs to another scope (#617).
142
+ * A corrupt cursor only resumes from an offset a witness recomputed from the
143
+ * current source proves; otherwise the page restarts at byte 0.
144
+ */
145
+ export type PageReset = "stale-cursor" | "source-replaced" | "compacted" | "cursor-corrupt";
139
146
  export type EvidenceGapKind = "capture" | "retention" | "read";
140
147
  export type StatusChange = "none" | "failure" | "content" | "reset";
141
148
  export type EnvelopeSectionName =
@@ -191,6 +198,12 @@ export interface PageResult {
191
198
  appendReady?: boolean;
192
199
  /** Bytes of a trailing, still-incomplete UTF-8 sequence withheld until the writer completes it. */
193
200
  pendingBytes?: number;
201
+ /**
202
+ * `backward` marks an end-anchored page: the text ends at the cursor's upper
203
+ * bound, `omittedBytes` counts earlier bytes not shown, and `nextCursor`
204
+ * continues toward the start of the file.
205
+ */
206
+ direction?: "backward";
194
207
  }
195
208
 
196
209
  export interface FilePageRequest extends PageRequest {
@@ -205,6 +218,14 @@ export interface FilePageRequest extends PageRequest {
205
218
  captureGaps?: Array<{ bytes: number; detail?: string }>;
206
219
  /** Pin pagination to this many leading bytes; defaults to the size at first read. */
207
220
  snapshotBytes?: number;
221
+ /**
222
+ * Start an uncursored read from the newest retained byte instead of byte 0
223
+ * (issue #618). The first page is end-anchored and `nextCursor` then pages
224
+ * toward the oldest byte; reaching the start hands back an append-ready
225
+ * cursor. A backward cursor keeps this direction on its own, so the request
226
+ * flag is only needed to start such a pager.
227
+ */
228
+ direction?: "backward";
208
229
  }
209
230
 
210
231
  export interface VerbatimPage {
@@ -224,6 +245,8 @@ export interface VerbatimPage {
224
245
  endByte?: number;
225
246
  appendReady?: boolean;
226
247
  pendingBytes?: number;
248
+ /** `backward` marks an end-anchored page whose `nextCursor` reads earlier bytes. */
249
+ direction?: "backward";
227
250
  /** Where `nextCursor` is accepted when that is not the tool that returned it. */
228
251
  via?: string;
229
252
  }
@@ -286,10 +309,15 @@ interface CursorPayload {
286
309
  i?: string;
287
310
  h?: string;
288
311
  hl?: number;
312
+ /** Position witness: the byte window before the offset (`k: "f"`), or the source snapshot (`k: "t"`). */
289
313
  w?: string;
290
314
  c?: string;
291
315
  f?: string;
292
316
  a?: 1;
317
+ /** End-anchored page: `o` is the page's upper bound and `nextCursor` reads earlier bytes. */
318
+ b?: 1;
319
+ /** Integrity tag over every other field; see `cursorIntegrityTag`. */
320
+ x?: string;
293
321
  }
294
322
 
295
323
  function positiveInt(value: unknown): number | undefined {
@@ -438,10 +466,44 @@ function resourceTag(resource: string): string {
438
466
  return hashBytes(encoder.encode(resource)).slice(0, 16);
439
467
  }
440
468
 
469
+ /**
470
+ * Cursors that carry an offset are tagged, so a hand-copied cursor can be
471
+ * recognised as damaged. Status cursors are not: they hold no offset, a
472
+ * damaged one already falls back to the current facts, and their payload sits
473
+ * in 1 KiB status responses where every cursor byte competes with decision
474
+ * facts (`remote setup: …` was clipped once the cursor grew).
475
+ */
476
+ function isTaggedCursorKind(kind: CursorPayload["k"]): boolean {
477
+ return kind !== "s";
478
+ }
479
+
441
480
  function encodeCursor(payload: CursorPayload): string {
442
- return CURSOR_PREFIX + Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
481
+ const tagged = isTaggedCursorKind(payload.k) ? { ...payload, x: cursorIntegrityTag(payload) } : payload;
482
+ return CURSOR_PREFIX + Buffer.from(JSON.stringify(tagged), "utf8").toString("base64url");
443
483
  }
444
484
 
485
+ /**
486
+ * Integrity tag over every payload field except the tag itself.
487
+ *
488
+ * Cursors are re-typed by the model. One mistyped base64url character used to
489
+ * decode into a payload that still parsed: when the changed field was the
490
+ * source digest the pager reported `source-replaced`, restarted at byte 0 and
491
+ * minted the same cursor again — the caller could never reach the rest of the
492
+ * text (#617). The tag makes a near-miss detectable as corruption instead of
493
+ * being read as a different source.
494
+ */
495
+ function cursorIntegrityTag(payload: CursorPayload): string {
496
+ const { x: _ignored, ...rest } = payload;
497
+ // 36 bits: enough to catch an accidental edit, and short enough that the
498
+ // cursor stays a small thing to copy.
499
+ return shortHash(encoder.encode(JSON.stringify(rest))).slice(0, 6);
500
+ }
501
+
502
+ /**
503
+ * Structural decode only: a corrupted payload still reports its kind and
504
+ * resource so it can be classified and, where the offset is still meaningful,
505
+ * resumed. `cursorIntegrityOk` is the separate integrity verdict.
506
+ */
445
507
  function decodeCursor(cursor: string | undefined): CursorPayload | undefined {
446
508
  if (!cursor || !cursor.startsWith(CURSOR_PREFIX)) return undefined;
447
509
  try {
@@ -453,6 +515,39 @@ function decodeCursor(cursor: string | undefined): CursorPayload | undefined {
453
515
  return undefined;
454
516
  }
455
517
 
518
+ /** False when any payload field was altered after the cursor was minted. */
519
+ function cursorIntegrityOk(parsed: CursorPayload): boolean {
520
+ if (!isTaggedCursorKind(parsed.k)) return true;
521
+ return typeof parsed.x === "string" && parsed.x === cursorIntegrityTag(parsed);
522
+ }
523
+
524
+ /**
525
+ * Digest of one source snapshot at one offset. A text cursor carries it in `v`
526
+ * and, recomputed against the current text, it answers both questions a
527
+ * continuation needs: is this still the same source, and is this still its
528
+ * offset? A changed source or a shifted offset changes it (#617).
529
+ */
530
+ function textSnapshotDigest(revision: string, offset: number): string {
531
+ return shortHash(encoder.encode(`t\0${revision}\0${offset}`));
532
+ }
533
+
534
+ /**
535
+ * Second, independent witness of the same fact, stored in `w`: the snapshot,
536
+ * its length, and the offset. Both witnesses are recomputed from the current
537
+ * text, so damage to either one alone still leaves a usable cursor — the
538
+ * reported one-character miscopy keeps the page advancing instead of replaying
539
+ * page 1 forever, while a genuinely replaced or shifted source fails both.
540
+ */
541
+ function textOffsetWitness(revision: string, offset: number, length: number): string {
542
+ return shortHash(encoder.encode(`t\0${revision}\0${length}\0${offset}`)).slice(0, 6);
543
+ }
544
+
545
+ /** Decoded page offset, or NaN when the field did not survive decoding. */
546
+ function cursorOffset(parsed: CursorPayload): number {
547
+ const o = parsed.o;
548
+ return typeof o === "number" && Number.isFinite(o) ? Math.floor(o) : Number.NaN;
549
+ }
550
+
456
551
  export function cursorKind(cursor: string | undefined): "t" | "f" | "s" | "l" | undefined {
457
552
  if (cursor?.startsWith(ROW_CURSOR_PREFIX)) return decodeRowCursor(cursor) ? "l" : undefined;
458
553
  return decodeCursor(cursor)?.k;
@@ -491,6 +586,14 @@ function emptyPage(overrides: Partial<PageResult> & Pick<PageResult, "revision"
491
586
  * Page exact UTF-8 text. Consecutive pages concatenate to the original string.
492
587
  * Cursors are caller-owned: the same cursor plus maxBytes always yields the
493
588
  * same page, and two callers do not share consumption.
589
+ *
590
+ * A cursor that fails its integrity check is reported as `cursor-corrupt`,
591
+ * never as a replaced source, and never replays page 1 blindly: it resumes at
592
+ * its decoded offset only when a witness recomputed from the current text
593
+ * proves that offset still belongs to the same snapshot. Otherwise — a
594
+ * replaced, grown, or shifted source, a damaged offset, or a cursor from
595
+ * before the witnesses existed — the page restarts at byte 0, so no unread
596
+ * text is skipped (#617).
494
597
  */
495
598
  export function pageVerbatimText(text: string, request: PageRequest = {}): PageResult {
496
599
  const maxBytes = pagerBudget(request.maxBytes, OUTPUT_BUDGET_BYTES.answer);
@@ -501,20 +604,43 @@ export function pageVerbatimText(text: string, request: PageRequest = {}): PageR
501
604
  let reset: PageReset | undefined;
502
605
  const parsed = decodeCursor(request.cursor);
503
606
  if (request.cursor) {
504
- if (!parsed || parsed.k !== "t" || (parsed.r ?? undefined) !== resource) {
607
+ if (!parsed || parsed.k !== "t") {
608
+ reset = "stale-cursor";
609
+ } else if (!cursorIntegrityOk(parsed) || parsed.w === undefined) {
610
+ // A payload without its position witness (a cursor minted before this
611
+ // format) is treated the same as a damaged one: its offset is unproven.
612
+ reset = "cursor-corrupt";
613
+ if ((parsed.r ?? undefined) === resource) {
614
+ const decoded = cursorOffset(parsed);
615
+ const inside = Number.isFinite(decoded) && decoded >= 0 && decoded <= encoded.length;
616
+ // Two independent witnesses of "this snapshot at this offset": either
617
+ // one surviving a single damaged field keeps a static-source cursor
618
+ // moving instead of looping on page 1.
619
+ const witnessed = inside && (
620
+ parsed.v === textSnapshotDigest(revision, decoded)
621
+ || (parsed.w !== undefined && parsed.w === textOffsetWitness(revision, decoded, encoded.length))
622
+ );
623
+ if (witnessed) offset = decoded;
624
+ }
625
+ } else if ((parsed.r ?? undefined) !== resource) {
505
626
  reset = "stale-cursor";
506
- } else if (parsed.v !== revision) {
507
- reset = "source-replaced";
508
627
  } else {
509
628
  offset = Math.min(encoded.length, Math.max(0, Math.floor(parsed.o ?? 0)));
629
+ if (parsed.v !== textSnapshotDigest(revision, offset)) {
630
+ // Same cursor, different text: restart at byte 0 rather than serving
631
+ // bytes from a position that no longer means what it did.
632
+ reset = "source-replaced";
633
+ offset = 0;
634
+ }
510
635
  }
511
636
  }
512
637
  const mint = (o: number): string => encodeCursor({
513
638
  k: "t",
514
639
  ...(resource !== undefined ? { r: resource } : {}),
515
- v: revision,
640
+ v: textSnapshotDigest(revision, o),
516
641
  o,
517
642
  n: encoded.length,
643
+ w: textOffsetWitness(revision, o, encoded.length),
518
644
  });
519
645
  const make = (start: number, end: number): PageResult => ({
520
646
  text: decoder.decode(encoded.subarray(start, end)),
@@ -598,6 +724,35 @@ function fileReadError(
598
724
  });
599
725
  }
600
726
 
727
+ /**
728
+ * Start byte of an end-anchored page inside `window` (the bytes immediately
729
+ * before its upper bound). A backward page starts just after the first newline
730
+ * that keeps at least half the window, so consecutive pages concatenate; when
731
+ * no such newline exists (one oversized line) it starts on the next whole code
732
+ * point and the page begins mid-line rather than stalling.
733
+ */
734
+ function backwardPageStart(window: Buffer): number {
735
+ let start = 0;
736
+ while (start < window.length && isContinuation(window[start]!)) start += 1;
737
+ const floor = Math.ceil(window.length / 2);
738
+ for (let i = start; i < floor; i += 1) {
739
+ if (window[i] === NEWLINE) return i + 1;
740
+ }
741
+ return start;
742
+ }
743
+
744
+ /**
745
+ * Largest boundary <= `end` that does not split a UTF-8 sequence, looking only
746
+ * at the bytes retained up to `end`. Used for the newest retained byte, which
747
+ * a writer can leave inside a code point it has not finished emitting.
748
+ */
749
+ function completeCodePointEnd(fd: number, end: number): number {
750
+ if (end <= 0) return 0;
751
+ const from = Math.max(0, end - 4);
752
+ const tail = readAt(fd, from, end - from);
753
+ return from + utf8SafeEnd(tail, 0, tail.length);
754
+ }
755
+
601
756
  /**
602
757
  * Page retained file bytes without skipping unread ranges. Snapshot high-water
603
758
  * marks keep a page stable while the file appends. Cursors bind the resource
@@ -640,32 +795,46 @@ export function pageRetainedFile(path: string, request: FilePageRequest = {}): P
640
795
  let appendReady = false;
641
796
 
642
797
  if (request.cursor) {
643
- if (!parsed || parsed.k !== "f" || parsed.r !== resource) {
798
+ if (!parsed || parsed.k !== "f") {
644
799
  reset = "stale-cursor";
645
- } else if (parsed.i !== identity) {
646
- reset = "source-replaced";
647
800
  } else {
648
- const o = Math.max(0, Math.floor(parsed.o ?? 0));
649
- const n = Math.max(0, Math.floor(parsed.n ?? 0));
650
- const headLength = Math.max(0, Math.floor(parsed.hl ?? 0));
651
- const generationChanged = generation !== undefined && parsed.g !== generation;
652
- const bytesIntact = o <= n
653
- && n <= size
654
- && headLength <= size
655
- && (!parsed.h || shortHash(head.subarray(0, headLength)) === parsed.h)
656
- && (o === 0 || windowHash(o) === parsed.w);
657
- if (generationChanged) {
658
- // The consumer declared a compaction/replacement of this file.
659
- reset = "compacted";
660
- } else if (!bytesIntact) {
661
- // Same file object as far as stat can tell, but the bytes behind the
662
- // cursor changed without a declared compaction: rewritten in place,
663
- // or deleted and recreated on a reused inode with coarse timestamps.
664
- reset = "source-replaced";
801
+ // A hand-copied cursor is never reported as a replaced source: that was
802
+ // a false claim, and the restart replayed page 1 forever (#617). A
803
+ // damaged payload is also never resumed: its offset *and* its direction
804
+ // come from a payload that failed its integrity check, so the pass
805
+ // restarts at its own anchor (byte 0 forward, the newest byte backward)
806
+ // instead of continuing somewhere the caller never reached (#617 R1).
807
+ const corrupt = !cursorIntegrityOk(parsed);
808
+ const reason = (clean: PageReset): PageReset => (corrupt ? "cursor-corrupt" : clean);
809
+ if (parsed.r !== resource) {
810
+ reset = reason("stale-cursor");
811
+ } else if (parsed.i !== identity) {
812
+ reset = reason("source-replaced");
813
+ } else if (corrupt) {
814
+ reset = "cursor-corrupt";
665
815
  } else {
666
- offset = o;
667
- snapshot = n;
668
- appendReady = parsed.a === 1;
816
+ const o = Math.max(0, Math.floor(parsed.o ?? 0));
817
+ const n = Math.max(0, Math.floor(parsed.n ?? 0));
818
+ const headLength = Math.max(0, Math.floor(parsed.hl ?? 0));
819
+ const generationChanged = generation !== undefined && parsed.g !== generation;
820
+ const bytesIntact = o <= n
821
+ && n <= size
822
+ && headLength <= size
823
+ && (!parsed.h || shortHash(head.subarray(0, headLength)) === parsed.h)
824
+ && (o === 0 || windowHash(o) === parsed.w);
825
+ if (generationChanged) {
826
+ // The consumer declared a compaction/replacement of this file.
827
+ reset = "compacted";
828
+ } else if (!bytesIntact) {
829
+ // Same file object as far as stat can tell, but the bytes behind the
830
+ // cursor changed without a declared compaction: rewritten in place,
831
+ // or deleted and recreated on a reused inode with coarse timestamps.
832
+ reset = "source-replaced";
833
+ } else {
834
+ offset = o;
835
+ snapshot = n;
836
+ appendReady = parsed.a === 1;
837
+ }
669
838
  }
670
839
  }
671
840
  }
@@ -674,7 +843,7 @@ export function pageRetainedFile(path: string, request: FilePageRequest = {}): P
674
843
  snapshot = Math.max(snapshot, initialSnapshot());
675
844
  }
676
845
 
677
- const mint = (o: number, n: number, append: boolean): string => {
846
+ const mint = (o: number, n: number, append: boolean, back = false): string => {
678
847
  const window = windowHash(o);
679
848
  return encodeCursor({
680
849
  k: "f",
@@ -687,6 +856,7 @@ export function pageRetainedFile(path: string, request: FilePageRequest = {}): P
687
856
  hl: head.length,
688
857
  ...(window ? { w: window } : {}),
689
858
  ...(append ? { a: 1 } : {}),
859
+ ...(back ? { b: 1 as const } : {}),
690
860
  });
691
861
  };
692
862
  const base = {
@@ -694,6 +864,80 @@ export function pageRetainedFile(path: string, request: FilePageRequest = {}): P
694
864
  ...(reset ? { reset } : {}),
695
865
  };
696
866
 
867
+ // A backward cursor keeps its own direction (even after a reset, which
868
+ // restarts at the newest bytes); the request flag starts one.
869
+ const backward = parsed?.k === "f" ? parsed.b === 1 : request.direction === "backward";
870
+ if (backward) {
871
+ if (!request.cursor || reset) offset = snapshot;
872
+ if (offset > snapshot) offset = snapshot;
873
+ const mintBackward = (o: number): string => mint(o, snapshot, false, true);
874
+ const revision = fileRevision(generation, identity, snapshot);
875
+ // The newest retained byte can stop inside a code point the writer has not
876
+ // finished. Withhold that suffix like the forward pager does, and anchor
877
+ // the append cursor at its first byte, so the whole character arrives once
878
+ // the writer completes it. Every other page starts where a previous page
879
+ // already aligned.
880
+ const snapshotEnd = completeCodePointEnd(opened, snapshot);
881
+ if (offset <= 0) {
882
+ // Nothing earlier is retained: hand back the forward append-ready cursor.
883
+ return emptyPage({
884
+ revision,
885
+ cursor: mintBackward(0),
886
+ nextCursor: mint(snapshotEnd, snapshotEnd, true),
887
+ totalBytes: snapshot,
888
+ startByte: 0,
889
+ endByte: 0,
890
+ appendReady: true,
891
+ direction: "backward",
892
+ ...(snapshotEnd < snapshot ? { pendingBytes: snapshot - snapshotEnd } : {}),
893
+ ...base,
894
+ });
895
+ }
896
+ const from = Math.max(0, offset - maxBytes);
897
+ const window = readAt(opened, from, offset - from);
898
+ const withheldFrom = offset === snapshot ? snapshotEnd : offset;
899
+ const pendingBytes = offset - withheldFrom;
900
+ // Byte 0 is always a valid page start; otherwise start at the first line
901
+ // boundary that keeps as much of the window as possible.
902
+ const reachedStart = from === 0;
903
+ const start = reachedStart ? 0 : from + backwardPageStart(window.subarray(0, withheldFrom - from));
904
+ if (!reachedStart && start >= withheldFrom) {
905
+ // Budget is smaller than the next code point behind the cursor: stay put.
906
+ const here = mintBackward(offset);
907
+ return emptyPage({
908
+ revision,
909
+ cursor: here,
910
+ nextCursor: here,
911
+ hasMore: true,
912
+ omittedBytes: offset,
913
+ totalBytes: snapshot,
914
+ startByte: offset,
915
+ endByte: offset,
916
+ direction: "backward",
917
+ ...(pendingBytes > 0 ? { pendingBytes } : {}),
918
+ ...base,
919
+ });
920
+ }
921
+ return {
922
+ text: decoder.decode(window.subarray(start - from, withheldFrom - from)),
923
+ revision,
924
+ cursor: mintBackward(offset),
925
+ // Reaching the oldest byte hands the whole pass back to forward polling:
926
+ // the append cursor sits on the newest complete code point, so a withheld
927
+ // character is returned whole rather than skipped.
928
+ nextCursor: reachedStart ? mint(snapshotEnd, snapshotEnd, true) : mintBackward(start),
929
+ hasMore: !reachedStart,
930
+ omittedBytes: start,
931
+ totalBytes: snapshot,
932
+ startByte: start,
933
+ endByte: withheldFrom,
934
+ ...(reachedStart ? { appendReady: true } : {}),
935
+ ...(pendingBytes > 0 ? { pendingBytes } : {}),
936
+ direction: "backward",
937
+ ...base,
938
+ };
939
+ }
940
+
697
941
  if (offset > snapshot) offset = snapshot;
698
942
  if (offset >= snapshot) {
699
943
  return emptyPage({
@@ -1088,7 +1332,9 @@ function formatContinuation(info: {
1088
1332
  ? `omittedRows=${page.omittedRows}`
1089
1333
  : `omittedBytes=${page.omittedBytes}`;
1090
1334
  const cursor = page.nextCursor ? ` nextCursor=${page.nextCursor}${page.via ? ` (${page.via})` : ""}` : "";
1091
- lines.push(`hasMore=${page.hasMore} ${amount}${cursor}`);
1335
+ // End-anchored pages count earlier bytes and continue toward the start.
1336
+ const direction = page.direction === "backward" ? " (newest-first page; nextCursor reads earlier bytes)" : "";
1337
+ lines.push(`hasMore=${page.hasMore} ${amount}${cursor}${direction}`);
1092
1338
  } else if (page?.appendReady && page.nextCursor) {
1093
1339
  lines.push(`end nextCursor=${page.nextCursor} (reuse to read only bytes appended later)`);
1094
1340
  }
package/stop.ts CHANGED
@@ -16,6 +16,11 @@
16
16
  * process-group evidence remains, reread the child log and finalize from
17
17
  * coherent terminal evidence (`completed` / `failed`) or record `lost`.
18
18
  *
19
+ * Terminal completion (#624): every terminal write here also records the run's
20
+ * pending completion marker, so a stopped, killed, or cleanup-finalized run
21
+ * still produces exactly one completion callback (delivered at the next
22
+ * boundary, or recovered by the next Pi instance after `/reload`).
23
+ *
19
24
  * Process-group-only contract (ADR 0002): related work is the captured
20
25
  * process group (pgid, falling back to pid for old metadata). Escaped /
21
26
  * reparented descendants outside that group are out of contract and are
@@ -26,6 +31,8 @@ import { realProcessProbe, type ProcessProbe } from "./health.ts";
26
31
  import { parseRunForLifecycle } from "./parse.ts";
27
32
  import {
28
33
  effectiveStatus,
34
+ launchAttemptInProgress,
35
+ purgeAbandonedLaunch,
29
36
  readMeta,
30
37
  writeMeta,
31
38
  type RunMeta,
@@ -35,7 +42,13 @@ import { killProcessTree } from "./spawn.ts";
35
42
  export type StopOutcome =
36
43
  | { action: "stopped"; id: string }
37
44
  | { action: "finalized"; id: string; status: "completed" | "failed" | "lost" }
38
- | { action: "not-running"; id: string; status: string };
45
+ | { action: "not-running"; id: string; status: string }
46
+ | { action: "purged"; id: string }
47
+ /**
48
+ * The id is not debris right now: a concurrent launch either published its
49
+ * metadata or is still preparing it. Nothing was removed.
50
+ */
51
+ | { action: "preserved"; id: string; status: string };
39
52
 
40
53
  export interface StopDeps {
41
54
  /** OS process probe; defaults to the real probe. Tests inject fakes. */
@@ -66,10 +79,32 @@ function terminateRelatedWork(meta: Pick<RunMeta, "pid" | "pgid">): number | und
66
79
  return pgid;
67
80
  }
68
81
 
82
+ /**
83
+ * Record the one durable terminal-completion obligation (#624).
84
+ *
85
+ * Every terminal transition owes its caller exactly one completion callback:
86
+ * the callback batcher delivers it once at the next boundary and writes the
87
+ * sent marker, and `/reload` recovers a record that is still marked pending.
88
+ * A stop is a terminal transition like any other, so it must set the marker —
89
+ * otherwise a killed run stays silent now and after `session_start` recovery,
90
+ * which is the case the caller can only notice by polling (or never).
91
+ *
92
+ * `callback:false` runs owe no model message, and an existing marker (sent,
93
+ * suppressed, or already pending) is never moved or reintroduced.
94
+ */
95
+ function oweTerminalCompletion(meta: RunMeta, now: number): void {
96
+ if (meta.callback === false) return;
97
+ if (meta.completionCallbackPendingAt !== undefined
98
+ || meta.completionCallbackSentAt !== undefined
99
+ || meta.completionCallbackSuppressedAt !== undefined) return;
100
+ meta.completionCallbackPendingAt = now;
101
+ }
102
+
69
103
  function recordKilled(meta: RunMeta, now: number): StopOutcome {
70
104
  meta.status = "killed";
71
105
  meta.lifecycleClassification = "killed";
72
106
  meta.endedAt = now;
107
+ oweTerminalCompletion(meta, now);
73
108
  writeMeta(meta);
74
109
  return { action: "stopped", id: meta.id };
75
110
  }
@@ -87,6 +122,7 @@ function finalizeOrphanedWithoutProcess(meta: RunMeta, now: number): StopOutcome
87
122
  meta.lifecycleClassification = "complete";
88
123
  if (meta.exitCode === undefined) meta.exitCode = 0;
89
124
  meta.endedAt = now;
125
+ oweTerminalCompletion(meta, now);
90
126
  writeMeta(meta);
91
127
  return { action: "finalized", id: meta.id, status: "completed" };
92
128
  }
@@ -96,11 +132,15 @@ function finalizeOrphanedWithoutProcess(meta: RunMeta, now: number): StopOutcome
96
132
  meta.lifecycleClassification = "incomplete_open_tools";
97
133
  meta.failureReason = "incomplete-stream";
98
134
  meta.endedAt = now;
135
+ oweTerminalCompletion(meta, now);
99
136
  writeMeta(meta);
100
137
  return { action: "finalized", id: meta.id, status: "failed" };
101
138
  }
102
139
 
103
140
  // No coherent terminal completion evidence and no related process remains.
141
+ // `lost` is the one terminal outcome that does NOT owe a completion callback:
142
+ // its dedicated health callback (subagent-health) is the terminal notice, so
143
+ // marking a completion here would report the same run twice.
104
144
  meta.status = "lost";
105
145
  meta.lifecycleClassification = "lost";
106
146
  meta.lostAt = now;
@@ -131,11 +171,29 @@ function cleanupOrphanedRun(meta: RunMeta, probe: ProcessProbe, now: number): St
131
171
  * otherwise reread logs and finalize completed/failed/lost.
132
172
  * - other statuses → not-running (on-disk record untouched).
133
173
  *
174
+ * An id with no metadata is either unknown or an abandoned launch record (a
175
+ * launch that never wrote `meta.json` and never started a child). The latter is
176
+ * purged, so the operator can clear launch debris (#623) without waiting for the
177
+ * sweep's grace period. A concurrent launch that owns the record — published, or
178
+ * still preparing under its claim — is preserved, never deleted (#623 R1).
179
+ * Anything else stays an unknown id.
180
+ *
134
181
  * Throws on an unknown id (same contract as the stop tool).
135
182
  */
136
183
  export function stopRun(id: string, deps: StopDeps = {}): StopOutcome {
137
184
  const meta = readMeta(id);
138
- if (!meta) throw new Error(`Unknown run id: ${id}`);
185
+ if (!meta) {
186
+ const purge = purgeAbandonedLaunch(id);
187
+ if (purge === "purged") return { action: "purged", id };
188
+ // The purge re-checks under the run's metadata lock, so a launch may have
189
+ // become visible while we waited. Preserve it and say what it is.
190
+ const published = readMeta(id);
191
+ if (published) return { action: "preserved", id, status: effectiveStatus(published) };
192
+ if (purge === "retained" || launchAttemptInProgress(id)) {
193
+ return { action: "preserved", id, status: "launching" };
194
+ }
195
+ throw new Error(`Unknown run id: ${id}`);
196
+ }
139
197
  const probe = deps.probe ?? realProcessProbe;
140
198
  const now = typeof deps.now === "function" ? deps.now() : Date.now();
141
199
  const status = effectiveStatus(meta);
package/timing.ts CHANGED
@@ -26,6 +26,13 @@
26
26
  * tool call does not count toward the stuck window, so a child in the middle
27
27
  * of a 20-minute test run is not stuck. A caller that needs to bound a
28
28
  * possibly hung command can opt into a ceiling.
29
+ *
30
+ * Because silence inside a running call is waiting, not being stuck, the
31
+ * parent also records the call it last saw open in the durable timing record
32
+ * (`inFlight`). A later parent (after `/reload`, or after a log rewrite) that
33
+ * can only read a bounded window may not see the call's start; the record is
34
+ * the still-alive evidence that keeps a silent build from being reported as
35
+ * stuck or stopped mid-call (#620).
29
36
  */
30
37
 
31
38
  import { createHash } from "node:crypto";
@@ -63,6 +70,13 @@ export interface RunTiming {
63
70
  stuckAnchorAt?: number;
64
71
  /** Latest progress seen by the parent (floor for a reload whose log read is bounded). */
65
72
  lastProgressAt?: number;
73
+ /**
74
+ * Tool call the parent last observed open, so a bounded reload read cannot
75
+ * turn a child that is waiting on a command into "no progress" (#620).
76
+ * `since` is when the open set became non-empty, which is also the pause
77
+ * start used once its result arrives.
78
+ */
79
+ inFlight?: { id: string; since: number };
66
80
  /** Set when the harness stopped the run. */
67
81
  stopReason?: TimingStopReason;
68
82
  stoppedAt?: number;
@@ -189,7 +203,7 @@ export interface ProgressState {
189
203
  /** Latest event timestamp seen (message provenance only). */
190
204
  lastEventAt?: number;
191
205
  /** Tool calls started and not yet finished. */
192
- open: Map<string, { name: string; command?: string; novel: boolean }>;
206
+ open: Map<string, { name: string; command?: string; novel: boolean; seeded?: boolean }>;
193
207
  /** Hashes of tool name + normalized arguments already seen in this run (bounded, oldest evicted). */
194
208
  seen: Set<string>;
195
209
  /** When the open set last went from empty to non-empty. */
@@ -199,8 +213,20 @@ export interface ProgressState {
199
213
  lastToolFailed: boolean;
200
214
  }
201
215
 
202
- export function emptyProgress(startedAt: number): ProgressState {
203
- return { startedAt, open: new Map(), seen: new Set(), pausedMs: 0, lastToolFailed: false };
216
+ /**
217
+ * Progress state for a run. `inFlight` seeds the open set from the durable
218
+ * record: the parent knows the child is waiting on that call even when the
219
+ * bounded log read no longer contains its start. A seeded entry carries no
220
+ * arguments, so its result is never mistaken for progress; the call's own
221
+ * result, or a later call's start, supersedes it.
222
+ */
223
+ export function emptyProgress(startedAt: number, inFlight?: { id?: string; since?: number }): ProgressState {
224
+ const state: ProgressState = { startedAt, open: new Map(), seen: new Set(), pausedMs: 0, lastToolFailed: false };
225
+ if (typeof inFlight?.id === "string" && inFlight.id !== "" && typeof inFlight.since === "number" && Number.isFinite(inFlight.since)) {
226
+ state.open.set(inFlight.id, { name: "", novel: false, seeded: true });
227
+ state.inFlightSince = Math.max(startedAt, inFlight.since);
228
+ }
229
+ return state;
204
230
  }
205
231
 
206
232
 
@@ -267,8 +293,23 @@ export function foldProgress(state: ProgressState, event: Record<string, unknown
267
293
  const id = typeof event.toolCallId === "string" ? event.toolCallId : undefined;
268
294
  if (!id) return;
269
295
  const args = event.args as { command?: unknown } | undefined;
270
- if (state.open.size === 0) state.inFlightSince = state.lastEventAt ?? state.startedAt;
271
296
  const name = String(event.toolName ?? "");
297
+ // A different call starting means the seeded call finished while the log window
298
+ // was lost: its wait is a pause, not progress. A seed for this same id is
299
+ // replaced by the real event below.
300
+ const seedSince = state.inFlightSince;
301
+ let supersededSeed = false;
302
+ for (const [openId, call] of state.open) {
303
+ if (call.seeded && openId !== id) {
304
+ state.open.delete(openId);
305
+ supersededSeed = true;
306
+ }
307
+ }
308
+ if (supersededSeed && state.open.size === 0 && seedSince !== undefined) {
309
+ state.pausedMs += Math.max(0, (state.lastEventAt ?? state.startedAt) - seedSince);
310
+ state.inFlightSince = undefined;
311
+ }
312
+ if (state.open.size === 0) state.inFlightSince = state.lastEventAt ?? state.startedAt;
272
313
  state.open.set(id, { name, command: typeof args?.command === "string" ? args.command : undefined, novel: remember(state, callKey(name, event.args)) });
273
314
  return;
274
315
  }