Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

fix(progress): reconcile live and saved parent updates (#1596)

Michael D'Angelo5befcdfdd75e
diff --git a/sdk/typescript/src/api.ts b/sdk/typescript/src/api.ts
index 3fd15df41..d0543ec77 100644
--- a/sdk/typescript/src/api.ts
+++ b/sdk/typescript/src/api.ts
@@ -100,6 +100,7 @@ import {
estimateScanCost,
ScanCostTracker,
type ScanCost,
+ type ParentProgressSource,
type ScanSessionEvent,
type ScanUsageObservation,
type ScanWorkerEvent,
@@ -1979,7 +1980,9 @@ export class CodexSecurity {
let scanProgressTracker: ScanProgressTracker | null = null;
let savedProviderProfile: ProviderProfile | undefined;
let artifactRestorationFailure: OutputDirectoryError | null = null;
- let customValidationComplete = false;
+ const customValidation = {
+ status: "pending" as "pending" | "running" | "complete",
+ };
let completionCost: ScanCost | null = null;
let scanTurnStatus: "in_progress" | "completed" | "failed" | null = null;
let budgetRecovery: {
@@ -2317,31 +2320,63 @@ export class CodexSecurity {
let reviewedFileCount = 0;
let latestPhase: ScanProgress["phase"] = "preflight";
let reviewItems: ScanProgress["reviewItems"];
- const reportProgress = (progress: ScanProgress): void => {
+ let lastProgress: string | null = null;
+ const progressKey = (progress: ScanProgress): string =>
+ `${progress.phase}:${progress.filesCompleted}:${progress.filesTotal}:${progress.reviewItems?.completed}:${progress.reviewItems?.total}`;
+ const reportProgress = (
+ progress: ScanProgress,
+ source?: ParentProgressSource,
+ ): void => {
+ const liveEvent =
+ source?.reconciled === true ? undefined : source?.event;
if (
- scopeFileCount === null ||
- progress.filesTotal > scopeFileCount ||
- progress.filesCompleted < reviewedFileCount
+ liveEvent !== undefined &&
+ !tracker.recordParentProgress(progress, liveEvent)
+ )
+ return;
+ const inventory =
+ source?.inventory === true ||
+ (progress.phase === "discovery" &&
+ reviewedFileCount === 0 &&
+ progress.filesCompleted === 0);
+ const filesTotal = inventory ? progress.filesTotal : scopeFileCount;
+ if (
+ filesTotal === null ||
+ progress.filesTotal > filesTotal ||
+ (source?.inventory !== true &&
+ progress.filesCompleted < reviewedFileCount)
) {
+ if (liveEvent !== undefined) tracker.deferParentInventory(liveEvent);
return;
}
+ if (inventory) {
+ scopeFileCount = filesTotal;
+ tracker.setExpectedFilesTotal(filesTotal);
+ }
reviewedFileCount = progress.filesCompleted;
+ if (liveEvent !== undefined)
+ tracker.acceptParentProgress(progress, liveEvent);
if (
+ source !== undefined ||
mode === "deep" ||
scanPhaseSchema.options.indexOf(progress.phase) >
scanPhaseSchema.options.indexOf(latestPhase)
) {
latestPhase = progress.phase;
}
- notifyObserver(
- options,
- "onProgress",
- )({
+ const update = {
...progress,
- phase: latestPhase,
- filesTotal: scopeFileCount,
+ phase:
+ customValidation.status === "running"
+ ? ("validation" as const)
+ : latestPhase,
+ filesTotal,
...(reviewItems === undefined ? {} : { reviewItems }),
- });
+ };
+ const key = progressKey(update);
+ if (lastProgress === key) return;
+ lastProgress = key;
+ notifyObserver(options, "onProgress")(update);
};
const reportWorkerStatus = (status: ScanWorkerStatus): void => {
if (mode !== "deep") {
@@ -2408,12 +2443,20 @@ export class CodexSecurity {
onProgress:
options.onProgress === undefined
? undefined
- : (progress) =>
- reportProgress({
- ...progress,
- // Worker counts belong to the parent scan's current phase.
- phase: mode === "deep" ? progress.phase : latestPhase,
- }),
+ : (progress, source) =>
+ reportProgress(
+ {
+ ...progress,
+ // Only worker counts use the last accepted parent phase.
+ phase:
+ mode === "deep" ||
+ (source !== undefined &&
+ (source.reconciled !== true || !source.worker))
+ ? progress.phase
+ : latestPhase,
+ },
+ source,
+ ),
onCost:
options.onCost === undefined && options.maxCostUsd === undefined
? undefined
@@ -3038,6 +3081,7 @@ export class CodexSecurity {
),
)}`;
}
+ tracker.beginParentTurn(resumeThreadId !== undefined);
const events = directDeepScan
? (this.#dependencies.runDeepScan ?? runDeepScan)({
codexOptions,
@@ -3125,6 +3169,7 @@ export class CodexSecurity {
// This turn follows the primary scan's reporting phase.
scanProgressTracker?.stop();
latestPhase = "validation";
+ customValidation.status = "running";
if (scopeFileCount !== null)
reportProgress({
phase: "validation",
@@ -3164,7 +3209,7 @@ export class CodexSecurity {
return turn.finalResponse;
},
});
- customValidationComplete = true;
+ customValidation.status = "complete";
}
budgetAbortController.abort();
const snapshot = await tracker.stop(usage).catch((error: unknown) => {
@@ -3221,18 +3266,11 @@ export class CodexSecurity {
onTrustedAccessStatus: options.onTrustedAccessStatus,
onReconnect: options.onReconnect,
onActivity: options.onActivity,
- onProgress: (progress) => {
- if (
- progress.phase === "discovery" &&
- progress.filesCompleted === 0 &&
- reviewedFileCount === 0 &&
- progress.filesTotal !== scopeFileCount
- ) {
- scopeFileCount = progress.filesTotal;
- tracker.setExpectedFilesTotal(scopeFileCount);
- }
- reportProgress(progress);
- },
+ onProgressItem:
+ options.onProgress === undefined
+ ? undefined
+ : (event) => tracker.recordParentItem(event),
+ onProgress: reportProgress,
onWorkerStatus: reportWorkerStatus,
onWarning: options.onWarning,
onObserverError: options.onObserverError,
@@ -3599,7 +3637,7 @@ export class CodexSecurity {
if (activeScan !== null && options.resumeScanId === undefined) {
if (
options.validationPrompt !== undefined &&
- !customValidationComplete
+ customValidation.status !== "complete"
) {
await writeCustomValidationStatus(scanDir, {
scanId: activeScan.id,
@@ -5068,7 +5106,8 @@ interface ScanEventRunOptions extends Pick<ScanOptions, "onReconnect"> {
onScanStarted?: () => void;
onTrustedAccessStatus?: (status: ScanTrustedAccessStatus) => void;
onActivity?: (activity: ScanActivity) => void;
- onProgress?: (progress: ScanProgress) => void;
+ onProgressItem?: (event: Readonly<Record<string, unknown>>) => void;
+ onProgress?: (progress: ScanProgress, source: ParentProgressSource) => void;
onWorkerStatus?: (status: ScanWorkerStatus) => void;
onWarning?: (warning: string) => void;
onObserverError?: (observer: ScanObserverName, error: unknown) => void;
@@ -5112,8 +5151,15 @@ export async function runScanEvents(
)) {
notifyObserver(options, "onActivity")(activity);
}
+ options.onProgressItem?.(event);
for (const progress of scanProgressUpdatesFromEvent(event)) {
- notifyObserver(options, "onProgress")(progress);
+ notifyObserver(
+ {
+ onProgress: (update) => options.onProgress?.(update, { event }),
+ onObserverError: options.onObserverError,
+ },
+ "onProgress",
+ )(progress);
}
const workerStatus = workerStatusFromEvent(event);
if (workerStatus !== null) {
diff --git a/sdk/typescript/src/cost.ts b/sdk/typescript/src/cost.ts
index 23300da9f..db03c6180 100644
--- a/sdk/typescript/src/cost.ts
+++ b/sdk/typescript/src/cost.ts
@@ -1,4 +1,5 @@
import { parseJson } from "./value.js";
+import { createHash } from "node:crypto";
import { open, readdir, stat } from "node:fs/promises";
import { join } from "node:path";
import { StringDecoder } from "node:string_decoder";
@@ -86,6 +87,153 @@ function createSessionReasoning(id: string, text = "") {
return { id, text, raw: false, activity: null as ScanActivity | null };
}
+interface SessionProgress {
+ update: ScanProgress;
+ order?: number;
+ position: number;
+ completion: boolean;
+ markerIndex: number;
+ receipt: boolean;
+ duplicate: boolean;
+ // This saved occurrence already supplied scope before a delayed live copy.
+ inventoryAdmitted?: true;
+ scopeFilesTotal?: number;
+ projection?: StreamedProgressItem;
+}
+
+interface ProgressItem {
+ kind: "message" | "command";
+ outputDigest: string;
+ persistedOutputDigest: string;
+ commandDigest?: string;
+}
+
+type ProgressOccurrenceQueues = Map<
+ string,
+ { indexes: number[]; next: number }
+>;
+
+interface SessionCompletion {
+ position: number;
+ item: ProgressItem | null;
+ kind?: ProgressItem["kind"];
+ lastCommandProgress?: SessionProgress;
+ // An exact completion, or a complete projection bounded by an exact anchor.
+ // The latter does not identify the live command's occurrence.
+ projection?: StreamedProgressItem;
+}
+
+interface UnresolvedParentCommand {
+ live: StreamedProgressItem;
+ after: number;
+}
+
+export type ParentProgressSource =
+ | {
+ event: Readonly<Record<string, unknown>>;
+ reconciled?: false;
+ inventory?: never;
+ }
+ | { reconciled: true; inventory?: true; worker?: true };
+
+interface ParentProgressMarker {
+ progress: ScanProgress;
+ index: number;
+ order: number;
+ accepted: boolean;
+ scopeFilesTotal?: number;
+ // Source coordinates of a complete saved projection, not a live occurrence.
+ projection?: { position: number; markerIndex: number };
+}
+
+interface ProgressOrder {
+ order: number;
+ position?: number;
+ markerIndex?: number;
+ live?: StreamedProgressItem;
+ source?: SessionProgress;
+}
+
+interface OrderedProgress extends ProgressOrder {
+ progress: ScanProgress;
+}
+
+interface LiveInventory extends OrderedProgress {
+ marker: ParentProgressMarker;
+ live: StreamedProgressItem;
+}
+
+interface InventoryEvidence extends OrderedProgress {
+ position: number;
+ markerIndex: number;
+ afterLive?: StreamedProgressItem;
+}
+
+function savedProgress(source: SessionProgress) {
+ return {
+ progress: source.update,
+ position: source.position,
+ markerIndex: source.markerIndex,
+ order: source.order ?? 0,
+ source,
+ };
+}
+
+// A live parent keeps authority over an unresolved saved prefix. Once an exact
+// anchor bounds that prefix, source order also governs admission and display.
+// Independent workers and legacy projections still use observation order.
+function compareProgressOrder(
+ left: ProgressOrder,
+ right: ProgressOrder,
+): number {
+ const source = compareSourceOrder(left, right);
+ if (source !== undefined) return source;
+ // A display preference is not source proof. Keep current live authority over
+ // an unresolved prefix, while retaining that prefix for later reconciliation.
+ if (left.live?.after !== undefined && right.position !== undefined) return 1;
+ if (right.live?.after !== undefined && left.position !== undefined) return -1;
+ const observedOrder = (candidate: ProgressOrder) => {
+ const marker =
+ candidate.source?.projection?.markers[candidate.markerIndex ?? 0];
+ // A complete source projection retains its originating live order even
+ // when polling observes that copy after a newer unpositioned phase.
+ return marker !== undefined &&
+ progressKey(marker.progress) === progressKey(candidate.source!.update)
+ ? marker.order
+ : candidate.order;
+ };
+ return observedOrder(left) - observedOrder(right);
+}
+
+function compareSourceOrder(
+ left: ProgressOrder,
+ right: ProgressOrder,
+): number | undefined {
+ const leftPosition = left.position ?? left.live?.position ?? undefined;
+ const rightPosition = right.position ?? right.live?.position ?? undefined;
+ if (leftPosition !== undefined && rightPosition !== undefined)
+ return (
+ leftPosition - rightPosition ||
+ (left.markerIndex ?? 0) - (right.markerIndex ?? 0)
+ );
+ if (leftPosition !== undefined && right.live?.after !== undefined)
+ return leftPosition >= right.live.after ? 1 : undefined;
+ if (rightPosition !== undefined && left.live?.after !== undefined)
+ return rightPosition >= left.live.after ? -1 : undefined;
+ return undefined;
+}
+
+interface StreamedProgressItem {
+ markers: ParentProgressMarker[];
+ // Live review admission rejects later zero inventories in this same item,
+ // even if recovered scope subsequently invalidates that review's cutoff.
+ reviewMarker?: number;
+ item: ProgressItem | null;
+ position: number | null;
+ // First saved position proved to follow an otherwise unpositioned live item.
+ after?: number;
+}
+
type SessionUsage = ReturnType<typeof createSessionUsage> & {
events?: Record<string, unknown>[];
};
@@ -102,7 +250,7 @@ interface ScanCostTrackerOptions {
onUsage?: (usage: Readonly<ScanTokenUsage>) => void;
onUsageObservation?: (observation: ScanUsageObservation) => void;
onActivity?: (activity: ScanActivity) => void;
- onProgress?: (progress: ScanProgress) => void;
+ onProgress?: (progress: ScanProgress, source?: ParentProgressSource) => void;
onSessionEvent?: (event: ScanSessionEvent) => void;
onWorkerEvent?: (event: ScanWorkerEvent) => void;
onError?: (error: unknown) => void;
@@ -137,7 +285,27 @@ function createSessionUsage(observeUsage: boolean) {
responseIds: new Set<string>(),
calls: new Map<string, ScanActivity>(),
activities: [] as ScanActivity[],
- progress: [] as ScanProgress[],
+ progress: [] as SessionProgress[],
+ position: 0,
+ completions: [] as SessionCompletion[],
+ latestWorkerProgress: null as OrderedProgress | null,
+ pendingWorkerProgress: new Map<
+ number,
+ { progress: ScanProgress; order: number }
+ >(),
+ messageProjections: new Map<
+ string,
+ { native: number; event: number; response: number }
+ >(),
+ messageProgressOrder: 0,
+ messageProgressFrontiers: { native: 0, event: 0, response: 0 },
+ messageProgressProjections: new Map<
+ string,
+ {
+ occurrences: number[];
+ next: { native: number; event: number; response: number };
+ }
+ >(),
filesCompleted: 0,
filesTotal: null as number | null,
prose: new Set<string>(),
@@ -152,7 +320,56 @@ export class ScanCostTracker {
readonly #receipts = new Map<string, ScanTokenUsage | null>();
readonly #workers = new Map<string, number>();
readonly #workerProgress = new Map<string, number>();
- readonly #reportedProgress = new Set<string>();
+ readonly #liveParentProgress = new Set<string>();
+ readonly #liveParentItems: StreamedProgressItem[] = [];
+ #liveParentEvents = new WeakMap<
+ Readonly<Record<string, unknown>>,
+ StreamedProgressItem
+ >();
+ #acceptedParent: StreamedProgressItem | null = null;
+ // Global coverage admitted from either the live or saved parent projection.
+ #parentProgress: OrderedProgress | null = null;
+ readonly #parentFacts = new Map<number, OrderedProgress>();
+ #parentInventory: ParentProgressMarker | null = null;
+ #parentInventoryBoundary: {
+ position: number;
+ markerIndex: number;
+ reviewed: boolean;
+ projection?: ProgressOrder & { live: StreamedProgressItem };
+ } | null = null;
+ // A bound excludes inventories at or after it without locating the review.
+ #parentReviewBefore: (ProgressOrder & { live: StreamedProgressItem }) | null =
+ null;
+ readonly #readyParentMarkers = new Map<
+ ParentProgressMarker,
+ StreamedProgressItem
+ >();
+ #inventoryFrontier: Omit<InventoryEvidence, "progress"> & {
+ progress?: ScanProgress;
+ } = {
+ position: 0,
+ markerIndex: -1,
+ order: 0,
+ progress: undefined as ScanProgress | undefined,
+ };
+ #progressOrder = 0;
+ #displayedProgress:
+ | (ProgressOrder & {
+ update: ScanProgress;
+ owner: "live" | "parent" | "worker";
+ })
+ | null = null;
+ #matchedParentItems = 0;
+ #parentCompletionCursor = 0;
+ #indexedParentCompletions = 0;
+ #indexedParentItems = 0;
+ readonly #parentCompletionKeys: ProgressOccurrenceQueues = new Map();
+ readonly #parentItemKeys: ProgressOccurrenceQueues = new Map();
+ readonly #parentMatches: number[] = [];
+ readonly #pendingParentMatches = new Set<number>();
+ #parentSession: SessionUsage | null = null;
+ #parentTurnStartKnown = true;
+ #parentFrontier = { position: 0, markerIndex: -1 };
#threadId: string | null = null;
#observingWorkers = true;
#timer: NodeJS.Timeout | null = null;
@@ -163,16 +380,1815 @@ export class ScanCostTracker {
#lastObservation: ScanUsageObservation | null = null;
#highestFilesCompleted = 0;
#expectedFilesTotal: number | undefined;
+ #parentTurnFilesTotal: number | undefined;
+ #inventoryNeedsReconciliation = false;
public constructor(options: ScanCostTrackerOptions) {
this.#options = options;
- this.#expectedFilesTotal = options.expectedFilesTotal;
+ if (options.expectedFilesTotal !== undefined)
+ this.setExpectedFilesTotal(options.expectedFilesTotal);
}
public setExpectedFilesTotal(filesTotal: number): void {
+ this.#parentTurnFilesTotal ??= filesTotal;
+ if (
+ this.#expectedFilesTotal !== undefined &&
+ this.#expectedFilesTotal !== filesTotal
+ )
+ this.#inventoryNeedsReconciliation = true;
this.#expectedFilesTotal = filesTotal;
}
+ /** Called before launching a turn, after loading any resumed history. */
+ public beginParentTurn(resumed = false): void {
+ this.#parentTurnFilesTotal = this.#expectedFilesTotal;
+ this.#parentTurnStartKnown = this.#parentSession !== null || !resumed;
+ for (const live of this.#liveParentItems) {
+ delete live.after;
+ }
+ this.#liveParentItems.length = 0;
+ this.#liveParentEvents = new WeakMap();
+ this.#acceptedParent = null;
+ this.#parentInventory = null;
+ this.#parentReviewBefore = null;
+ // Historical logs may omit projection kinds emitted by the new turn.
+ this.#parentSession?.messageProjections.clear();
+ if (this.#parentSession !== null) {
+ this.#parentSession.messageProgressProjections.clear();
+ this.#parentSession.messageProgressOrder = 0;
+ this.#parentSession.messageProgressFrontiers = {
+ native: 0,
+ event: 0,
+ response: 0,
+ };
+ }
+ // A new turn retires unresolved hypotheses from the previous turn; admitted
+ // coverage and source summaries remain available for resumed scans.
+ if (this.#parentSession !== null) this.#parentSession.progress.length = 0;
+ for (const completion of this.#parentSession?.completions ?? []) {
+ completion.item = null;
+ delete completion.kind;
+ delete completion.lastCommandProgress;
+ delete completion.projection;
+ }
+ this.#readyParentMarkers.clear();
+ this.#matchedParentItems = 0;
+ this.#parentCompletionCursor = this.#parentSession?.completions.length ?? 0;
+ this.#indexedParentCompletions = this.#parentCompletionCursor;
+ this.#indexedParentItems = 0;
+ this.#parentCompletionKeys.clear();
+ this.#parentItemKeys.clear();
+ this.#parentMatches.length = 0;
+ this.#pendingParentMatches.clear();
+ this.#liveParentProgress.clear();
+ }
+
+ /** Observe every supported completion so repeated output keeps its occurrence. */
+ public recordParentItem(event: Readonly<Record<string, unknown>>): void {
+ const item = event["item"];
+ if (
+ event["type"] !== "item.completed" ||
+ !isRecord(item) ||
+ (item["type"] !== "command_execution" &&
+ item["type"] !== "agent_message") ||
+ this.#liveParentEvents.has(event)
+ )
+ return;
+ const live: StreamedProgressItem = {
+ markers: [],
+ item: streamedProgressItem(event),
+ position: null,
+ };
+ this.#liveParentItems.push(live);
+ this.#liveParentEvents.set(event, live);
+ this.#matchParentCompletions();
+ }
+
+ /** Observe source identity before applying display/count guards. */
+ public recordParentProgress(
+ progress: ScanProgress,
+ event: Readonly<Record<string, unknown>>,
+ ): boolean {
+ this.recordParentItem(event);
+ const live = this.#liveParentEvents.get(event);
+ if (live === undefined) return true;
+ // Parsed rows were observed before this live marker even when their
+ // file.close is still pending. Do not give that old snapshot a later order.
+ for (const session of this.#sessions.values())
+ if (session.threadId === this.#threadId)
+ for (const saved of session.progress)
+ saved.order ??= ++this.#progressOrder;
+ const marker = {
+ progress,
+ index: live.markers.length,
+ order: ++this.#progressOrder,
+ accepted: false,
+ };
+ live.markers.push(marker);
+ if (isInventoryProgress(progress)) this.#parentInventory = marker;
+ if (live.position !== null) this.#readyParentMarkers.set(marker, live);
+ const current = isInventoryProgress(progress)
+ ? this.#retainedInventory()
+ : this.#parentFacts.get(progress.filesTotal);
+ return (
+ live.position === null ||
+ this.#afterParentFrontier(live.position, marker.index) ||
+ // Polling can admit this completion before live delivery. Its live copy
+ // restores progress after worker output or an unmatched live completion;
+ // older proved positions and earlier markers remain stale.
+ ((this.#displayedProgress?.owner === "worker" ||
+ (this.#displayedProgress?.owner === "live" &&
+ this.#displayedProgress.position === undefined)) &&
+ ((live.position === this.#parentFrontier.position &&
+ marker.index === this.#parentFrontier.markerIndex) ||
+ (current?.position === this.#parentFrontier.position &&
+ current.markerIndex === this.#parentFrontier.markerIndex &&
+ progressKey(current.progress) === progressKey(progress))))
+ );
+ }
+
+ /** Source acceptance is independent of duplicate observer notifications. */
+ public deferParentInventory(event: Readonly<Record<string, unknown>>): void {
+ const marker = this.#liveParentEvents.get(event)?.markers.at(-1);
+ // Parent inventory can invalidate provisional worker coverage. Reconcile
+ // it before displaying anything, so still-eligible coverage never drops.
+ if (
+ marker !== undefined &&
+ marker === this.#parentInventory &&
+ (!this.#parentIsEligible(this.#parentProgress) ||
+ this.#parentProgress.progress.filesCompleted === 0)
+ )
+ marker.accepted = true;
+ }
+
+ public acceptParentProgress(
+ progress: ScanProgress,
+ event: Readonly<Record<string, unknown>>,
+ ): void {
+ const live = this.#liveParentEvents.get(event);
+ if (live === undefined) return;
+ const marker = live.markers.at(-1);
+ if (marker === undefined) return;
+ marker.accepted = true;
+ if (progress.filesCompleted > 0) live.reviewMarker ??= marker.index;
+ this.#acceptedParent = live;
+ const provenance = {
+ order: marker.order,
+ live,
+ markerIndex: marker.index,
+ ...(live.position === null ? {} : { position: live.position }),
+ };
+ this.#parentProgress = { progress, ...provenance };
+ this.#rememberParentFact(this.#parentProgress);
+ const update = {
+ ...progress,
+ filesTotal: this.#expectedFilesTotal ?? progress.filesTotal,
+ };
+ this.#displayedProgress = { update, owner: "live", ...provenance };
+ this.#highestFilesCompleted = Math.max(
+ this.#highestFilesCompleted,
+ progress.filesCompleted,
+ );
+ this.#liveParentProgress.add(progressKey(progress));
+ this.#recordParentBoundary(
+ progress,
+ live.position ?? undefined,
+ marker.index,
+ true,
+ undefined,
+ live,
+ );
+ if (live.position !== null)
+ this.#advanceParentFrontier(live.position, marker.index);
+ }
+
+ #rememberParentFact(candidate: OrderedProgress): void {
+ // Unbound live markers stay in the existing completion queue until their
+ // saved occurrence resolves. Inventory markers have their own frontier.
+ if (
+ candidate.position === undefined ||
+ !this.#parentSourceIsEligible(candidate) ||
+ isInventoryProgress(candidate.progress)
+ )
+ return;
+ const total = candidate.progress.filesTotal;
+ const previous = this.#parentFacts.get(total);
+ if (
+ previous === undefined ||
+ !this.#parentSourceIsEligible(previous) ||
+ candidate.progress.filesCompleted > previous.progress.filesCompleted ||
+ (candidate.progress.filesCompleted === previous.progress.filesCompleted &&
+ compareProgressOrder(candidate, previous) > 0)
+ )
+ this.#parentFacts.set(total, candidate);
+ }
+
+ #parentSourceIsEligible(candidate: OrderedProgress): boolean {
+ const marker = candidate.live?.markers[candidate.markerIndex ?? 0];
+ return (
+ // Inventory establishes scope; only coverage is bounded by its prefix.
+ isInventoryProgress(candidate.progress) ||
+ candidate.progress.filesTotal <=
+ (candidate.source?.scopeFilesTotal ??
+ marker?.scopeFilesTotal ??
+ Number.MAX_SAFE_INTEGER)
+ );
+ }
+
+ #parentIsEligible(
+ candidate: OrderedProgress | null,
+ ): candidate is OrderedProgress {
+ return (
+ candidate !== null &&
+ this.#parentSourceIsEligible(candidate) &&
+ candidate.progress.filesTotal <=
+ (this.#expectedFilesTotal ?? Number.MAX_SAFE_INTEGER)
+ );
+ }
+
+ #parentInventoryWitness(): ProgressOrder | undefined {
+ const accepted = this.#acceptedParent;
+ if (accepted === null) return undefined;
+ let witness: ProgressOrder | undefined;
+ // Compute one proof for the accepted live prefix. Later unpositioned items
+ // keep their predecessors' ordering evidence without gaining a position.
+ for (const live of this.#liveParentItems) {
+ for (const marker of live.markers) {
+ if (isInventoryProgress(marker.progress)) continue;
+ const position = live.position ?? marker.projection?.position;
+ if (position === undefined) continue;
+ const candidate = {
+ position,
+ markerIndex:
+ live.position === null
+ ? marker.projection!.markerIndex
+ : marker.index,
+ order: marker.order,
+ live,
+ };
+ if (
+ witness === undefined ||
+ (compareSourceOrder(candidate, witness) ?? 0) > 0
+ )
+ witness = candidate;
+ }
+ if (live === accepted) break;
+ }
+ return witness;
+ }
+
+ #retainedInventory(): InventoryEvidence | undefined {
+ const { progress, ...source } = this.#inventoryFrontier;
+ return progress === undefined ? undefined : { progress, ...source };
+ }
+
+ #acceptedInventory(): LiveInventory | undefined {
+ let accepted: LiveInventory | undefined;
+ let precedingAnchor: StreamedProgressItem | undefined;
+ for (const live of this.#liveParentItems) {
+ for (const marker of live.markers) {
+ if (
+ !marker.accepted ||
+ !isInventoryProgress(marker.progress) ||
+ (live.position !== null &&
+ !this.#inventoryPrecedesReview(
+ live.position,
+ marker.index,
+ live,
+ )) ||
+ // An unresolved command follows the whole preceding exact completion.
+ // That lower bound can exclude it without assigning it a position.
+ (live.position === null &&
+ precedingAnchor !== undefined &&
+ !this.#inventoryPrecedesReview(
+ precedingAnchor.position!,
+ precedingAnchor.markers.length,
+ ))
+ )
+ continue;
+ const candidate = {
+ progress: marker.progress,
+ marker,
+ live,
+ position: live.position ?? undefined,
+ markerIndex: marker.index,
+ order: marker.order,
+ };
+ if ((this.#inventoryReviewOrder(candidate) ?? -1) >= 0) continue;
+ if (
+ accepted === undefined ||
+ compareProgressOrder(candidate, accepted) > 0
+ )
+ accepted = candidate;
+ }
+ if (live.position !== null) precedingAnchor = live;
+ }
+ return accepted;
+ }
+
+ #savedInventorySupersedes(
+ saved: InventoryEvidence,
+ live: LiveInventory,
+ native = this.#parentSession?.completions.some(
+ (completion) => completion.kind === "command",
+ ),
+ ): boolean {
+ const source = this.#inventorySourceOrder(saved, live);
+ if (source !== undefined) {
+ return source >= 0;
+ } else if (live.live.after === undefined && !native) {
+ // Older logs omit command completions. Their later phase receipts still
+ // provide the existing best-effort evidence for a saved inventory.
+ const phase = this.#parentFacts.get(saved.progress.filesTotal);
+ const row = this.#parentSession?.progress.find(
+ (row) =>
+ row.position === saved.position &&
+ row.markerIndex === saved.markerIndex,
+ );
+ const evidence =
+ phase !== undefined && (compareSourceOrder(phase, saved) ?? 0) > 0
+ ? phase
+ : row === undefined || !this.#unboundParentCopy(row)
+ ? saved
+ : undefined;
+ if (evidence !== undefined && compareProgressOrder(evidence, live) >= 0) {
+ // Keep admitted relative authority when a later anchor only narrows
+ // an unknown occurrence. Exact source order can still supersede it.
+ saved.afterLive = live.live;
+ return true;
+ }
+ }
+ return false;
+ }
+
+ #inventorySourceOrder(
+ saved: InventoryEvidence,
+ live: LiveInventory,
+ ): number | undefined {
+ const source = compareSourceOrder(saved, live);
+ if (source !== undefined) return source;
+ const projection = saved.source?.projection;
+ const marker = projection?.markers[saved.markerIndex];
+ // A complete bounded projection preserves live inventory order without
+ // identifying the saved occurrence. Count rejection cannot erase that proof.
+ if (
+ projection !== undefined &&
+ marker !== undefined &&
+ progressKey(marker.progress) === progressKey(saved.progress)
+ )
+ return (
+ compareSourceOrder(
+ { order: marker.order, markerIndex: marker.index, live: projection },
+ live,
+ ) ?? marker.order - live.order
+ );
+ return saved.afterLive === live.live ? 1 : undefined;
+ }
+
+ #projectParentInventory(): void {
+ const saved = this.#retainedInventory();
+ const live = this.#acceptedInventory();
+ const selected =
+ saved !== undefined &&
+ (live === undefined || this.#savedInventorySupersedes(saved, live))
+ ? saved
+ : live;
+ if (selected === saved && saved !== undefined) {
+ if (saved.source !== undefined) saved.source.inventoryAdmitted = true;
+ if (saved.afterLive !== undefined)
+ this.#inventoryFrontier.afterLive = saved.afterLive;
+ }
+ const invalidated =
+ selected === undefined &&
+ this.#liveParentItems.some((item) =>
+ item.markers.some(
+ (marker) => marker.accepted && isInventoryProgress(marker.progress),
+ ),
+ );
+ // Empty source history does not override a caller's explicit scope update.
+ // Roll back only when observed inventory authority has lost eligibility.
+ const filesTotal =
+ selected?.progress.filesTotal ??
+ (invalidated ? this.#parentTurnFilesTotal : undefined);
+ if (filesTotal !== undefined) {
+ // Scope recovered here has not necessarily reached the API, including
+ // its first assignment when registration supplied no file count.
+ if (filesTotal !== this.#expectedFilesTotal)
+ this.#inventoryNeedsReconciliation = true;
+ this.setExpectedFilesTotal(filesTotal);
+ }
+ }
+
+ #recordParentBoundary(
+ progress: ScanProgress,
+ position: number | undefined,
+ markerIndex: number,
+ admitted = false,
+ filesTotal?: number,
+ projection?: StreamedProgressItem,
+ ): void {
+ let reviewed = progress.filesCompleted > 0;
+ filesTotal ??= projection?.markers[markerIndex]?.scopeFilesTotal;
+ if (position === undefined) {
+ if (
+ reviewed &&
+ admitted &&
+ projection?.after !== undefined &&
+ progress.filesTotal <= (filesTotal ?? Number.MAX_SAFE_INTEGER)
+ ) {
+ const marker = projection.markers[markerIndex]!;
+ const previous = this.#parentReviewBefore;
+ if (
+ previous === null ||
+ projection.after < previous.live.after! ||
+ (projection.after === previous.live.after &&
+ marker.order < previous.order)
+ )
+ this.#parentReviewBefore = {
+ order: marker.order,
+ markerIndex,
+ live: projection,
+ };
+ }
+ return;
+ }
+ // Eligible source progress can start review without winning the display.
+ // Merely locating a rejected oversized marker cannot fix that cutoff.
+ if (
+ reviewed &&
+ progress.filesTotal > (filesTotal ?? Number.MAX_SAFE_INTEGER)
+ ) {
+ const boundary = this.#parentInventoryBoundary;
+ if (
+ boundary?.reviewed === true &&
+ boundary.position === position &&
+ boundary.markerIndex === markerIndex
+ )
+ // Retire the contradicted cutoff while preserving its source position
+ // as an ordering witness for preceding inventory.
+ boundary.reviewed = false;
+ if (projection === undefined) return;
+ // A bounded current completion still orders its preceding inventory.
+ // Scope-ineligible progress supplies that witness, not a reviewed cutoff.
+ reviewed = false;
+ }
+ if (isInventoryProgress(progress)) return;
+ const boundary = this.#parentInventoryBoundary;
+ const order =
+ boundary === null
+ ? 0
+ : position - boundary.position || markerIndex - boundary.markerIndex;
+ // Before review starts, each later phase can establish its preceding
+ // inventory. Once coverage starts, preserve the first reviewed boundary.
+ if (
+ boundary === null ||
+ (reviewed
+ ? !boundary.reviewed || order < 0
+ : !boundary.reviewed && order > 0)
+ )
+ this.#parentInventoryBoundary = {
+ position,
+ markerIndex,
+ reviewed,
+ projection:
+ projection === undefined
+ ? reviewed
+ ? undefined
+ : boundary?.projection
+ : {
+ position,
+ markerIndex,
+ order: projection.markers[markerIndex]!.order,
+ live: projection,
+ },
+ };
+ else if (order === 0 && projection !== undefined)
+ boundary.projection = {
+ position,
+ markerIndex,
+ order: projection.markers[markerIndex]!.order,
+ live: projection,
+ };
+ }
+
+ #recordParentSourceBoundaries(
+ command?: UnresolvedParentCommand,
+ ): InventoryEvidence | undefined {
+ const session = this.#parentSession;
+ if (session === null) return;
+ const native = session.completions.some(
+ (completion) => completion.kind === "command",
+ );
+ const projectedItems = new Set<StreamedProgressItem>();
+ for (const completion of session.completions)
+ if (completion.projection !== undefined)
+ projectedItems.add(completion.projection);
+ this.#parentReviewBefore = null;
+ for (const live of this.#liveParentItems) {
+ for (const marker of live.markers) delete marker.projection;
+ if (
+ live.position === null &&
+ live.after !== undefined &&
+ !projectedItems.has(live)
+ )
+ // Complete projections get their eligibility from the ordered rows
+ // below. Only omitted admitted reviews contribute this upper bound.
+ for (const marker of live.markers)
+ if (marker.accepted && marker.progress.filesCompleted > 0)
+ this.#recordParentBoundary(
+ marker.progress,
+ undefined,
+ marker.index,
+ true,
+ undefined,
+ live,
+ );
+ }
+ const authority = this.#acceptedInventory();
+ // Legacy logs without command positions keep the established live scope.
+ // An old copied preview cannot replace it merely by being read later.
+ let filesTotal =
+ !native &&
+ authority?.live.position === null &&
+ authority.live.after === undefined
+ ? authority.progress.filesTotal
+ : this.#parentTurnFilesTotal;
+ let inventory: InventoryEvidence | LiveInventory | undefined;
+ let savedInventory: InventoryEvidence | undefined;
+ const scopeAt = (
+ candidate: InventoryEvidence,
+ completion?: SessionCompletion,
+ ) => {
+ if (
+ !native ||
+ inventory !== undefined ||
+ authority?.live.position !== null ||
+ Number.isFinite(authority.live.after)
+ )
+ return filesTotal;
+ if (
+ candidate.markerIndex < authority.marker.index &&
+ completion?.item?.kind === "command" &&
+ completion.item.outputDigest === authority.live.item?.outputDigest
+ )
+ // Complete output agreement proves marker layout, not occurrence.
+ // A command's later inventory cannot justify its own earlier coverage.
+ return filesTotal;
+ // An initial estimate is not source proof against an admitted inventory
+ // missing from persistence. Keep it for rows known or observed before
+ // that live authority; unresolved later rows retain the admitted scope.
+ const order =
+ this.#inventorySourceOrder(candidate, authority) ??
+ (candidate.order === 0 ? 1 : candidate.order - authority.order);
+ return order < 0 ? filesTotal : authority.progress.filesTotal;
+ };
+ let liveIndex = 0;
+ const applyBounds = (position: number) => {
+ while (liveIndex < this.#liveParentItems.length) {
+ const live = this.#liveParentItems[liveIndex]!;
+ if (live.position !== null || live.after === undefined) {
+ liveIndex++;
+ continue;
+ }
+ if (live.after > position) break;
+ liveIndex++;
+ // Every marker remains available. A rejected trailing zero must not
+ // replace inventory whose order still proves it precedes review.
+ for (const marker of live.markers) {
+ if (
+ !isInventoryProgress(marker.progress) ||
+ // A bound orders a lossy inventory but does not admit its scope.
+ // Unaccepted inventory needs a complete projection or corroboration.
+ (!marker.accepted && !projectedItems.has(live))
+ )
+ continue;
+ const bounded = {
+ progress: marker.progress,
+ marker,
+ live,
+ markerIndex: marker.index,
+ order: marker.order,
+ };
+ if (
+ // An upper bound does not place this inventory at the anchor.
+ // Unknown relative order cannot revoke already admitted scope.
+ (this.#inventoryReviewOrder(bounded) ?? -1) < 0 &&
+ (inventory === undefined ||
+ ("marker" in inventory
+ ? compareProgressOrder(inventory, bounded) < 0
+ : !this.#savedInventorySupersedes(inventory, bounded, native)))
+ ) {
+ inventory = bounded;
+ filesTotal = bounded.progress.filesTotal;
+ }
+ }
+ }
+ };
+ const recordInventory = (candidate: InventoryEvidence) => {
+ const retained = this.#retainedInventory();
+ inventory =
+ retained?.position === candidate.position &&
+ retained.markerIndex === candidate.markerIndex
+ ? retained
+ : candidate;
+ savedInventory = inventory;
+ filesTotal = candidate.progress.filesTotal;
+ };
+ let completionIndex = 0;
+ const remainingMarkers = (completion: SessionCompletion) => {
+ applyBounds(completion.position);
+ const live = completion.projection;
+ if (
+ completion.kind !== "command" ||
+ live?.position !== completion.position
+ )
+ return;
+ // Exact command identity also locates markers omitted by persistence.
+ // Finish that command before examining the next saved source position.
+ for (
+ let index = (completion.lastCommandProgress?.markerIndex ?? -1) + 1;
+ index < live.markers.length;
+ index++
+ ) {
+ const marker = live.markers[index]!;
+ const candidate = {
+ progress: marker.progress,
+ position: completion.position,
+ markerIndex: marker.index,
+ order: marker.order,
+ live,
+ };
+ marker.scopeFilesTotal = scopeAt(candidate, completion);
+ if (isInventoryProgress(marker.progress)) {
+ if (
+ this.#inventoryPrecedesReview(
+ completion.position,
+ marker.index,
+ live,
+ )
+ )
+ recordInventory(candidate);
+ } else
+ this.#recordParentBoundary(
+ marker.progress,
+ completion.position,
+ marker.index,
+ marker.accepted,
+ marker.scopeFilesTotal,
+ );
+ }
+ };
+ for (const saved of session.progress) {
+ while (
+ completionIndex < session.completions.length &&
+ session.completions[completionIndex]!.position < saved.position
+ )
+ remainingMarkers(session.completions[completionIndex++]!);
+ const completion = session.completions[completionIndex];
+ applyBounds(saved.position);
+ saved.projection =
+ completion?.position === saved.position
+ ? completion.projection
+ : undefined;
+ const projected = saved.projection?.markers[saved.markerIndex];
+ if (saved.duplicate) continue;
+ const candidate = savedProgress(saved);
+ const progress = candidate.progress;
+ saved.scopeFilesTotal = scopeAt(
+ candidate,
+ completion?.position === saved.position ? completion : undefined,
+ );
+ const exact = completion?.projection?.position === saved.position;
+ const nativeOccurrence = this.#parentTurnStartKnown && saved.completion;
+ if (projected !== undefined) {
+ projected.scopeFilesTotal = saved.scopeFilesTotal;
+ if (progressKey(projected.progress) === progressKey(progress))
+ projected.projection = {
+ position: saved.position,
+ markerIndex: saved.markerIndex,
+ };
+ }
+ if (isInventoryProgress(progress)) {
+ // Source eligibility follows the inventory at this position, not the
+ // display scope at the start or end of a poll. The retained rows make
+ // this ordered pass identical for every partition of the same input.
+ if (
+ this.#inventoryPrecedesReview(
+ saved.position,
+ saved.markerIndex,
+ saved.projection,
+ saved,
+ )
+ ) {
+ if (exact || nativeOccurrence || !this.#unboundParentCopy(saved))
+ recordInventory(candidate);
+ else if (
+ authority !== undefined &&
+ progressKey(progress) === progressKey(authority.progress) &&
+ (compareSourceOrder(candidate, authority) ?? 0) >= 0
+ ) {
+ // A duplicate can restate the admitted legacy scope without proving
+ // an occurrence or becoming eligible for another notification.
+ inventory = authority;
+ filesTotal = authority.progress.filesTotal;
+ }
+ }
+ continue;
+ }
+ if (
+ projected !== undefined ||
+ // Native current-turn review rows have their own source evidence. Their
+ // eligibility does not depend on the provisional display frontier.
+ (nativeOccurrence && progress.filesCompleted > 0) ||
+ (this.#savedParentProgressIsCurrent(saved) &&
+ (command === undefined ||
+ command.live !== this.#acceptedParent ||
+ command.live.position !== null ||
+ saved.position >= command.after)) ||
+ (!saved.receipt &&
+ progress.filesCompleted > 0 &&
+ this.#liveParentProgress.has(progressKey(progress)))
+ )
+ this.#recordParentBoundary(
+ progress,
+ saved.position,
+ saved.markerIndex,
+ exact && (projected?.accepted ?? false),
+ saved.scopeFilesTotal,
+ projected === undefined ? undefined : completion!.projection,
+ );
+ }
+ while (completionIndex < session.completions.length)
+ remainingMarkers(session.completions[completionIndex++]!);
+ return savedInventory;
+ }
+
+ #precedesParentBoundary(position: number, markerIndex: number): boolean {
+ const first = this.#parentInventoryBoundary;
+ return (
+ first !== null &&
+ (position < first.position ||
+ (position === first.position && markerIndex < first.markerIndex))
+ );
+ }
+
+ #inventoryAllowedInCompletion(
+ live: StreamedProgressItem | undefined,
+ markerIndex: number,
+ ): boolean {
+ return (
+ live?.reviewMarker === undefined ||
+ markerIndex < live.reviewMarker ||
+ live.markers[markerIndex]?.accepted !== false
+ );
+ }
+
+ #inventoryPrecedesReview(
+ position: number,
+ markerIndex: number,
+ live?: StreamedProgressItem,
+ source?: SessionProgress,
+ ): boolean {
+ return (
+ (source?.inventoryAdmitted === true ||
+ this.#inventoryAllowedInCompletion(live, markerIndex)) &&
+ position < (this.#parentReviewBefore?.live.after ?? Infinity) &&
+ (this.#parentInventoryBoundary?.reviewed !== true ||
+ this.#precedesParentBoundary(position, markerIndex))
+ );
+ }
+
+ #inventoryReviewOrder(inventory: ProgressOrder): number | undefined {
+ const projection =
+ inventory.live?.markers[inventory.markerIndex ?? 0]?.projection;
+ if (
+ // A complete projection can exclude this inventory even though its live
+ // occurrence remains unknown. A mere upper bound cannot do so.
+ (projection !== undefined &&
+ !this.#inventoryPrecedesReview(
+ projection.position,
+ projection.markerIndex,
+ )) ||
+ !this.#inventoryAllowedInCompletion(
+ inventory.live,
+ inventory.markerIndex ?? 0,
+ )
+ )
+ return 1;
+ const boundary = this.#parentInventoryBoundary;
+ const reviews: ProgressOrder[] = [];
+ if (boundary?.reviewed === true)
+ reviews.push({
+ position: boundary.position,
+ markerIndex: boundary.markerIndex,
+ live: boundary.projection?.live,
+ order: boundary.projection?.order ?? 0,
+ });
+ if (this.#parentReviewBefore !== null)
+ reviews.push(this.#parentReviewBefore);
+ let order: number | undefined = -1;
+ for (const review of reviews) {
+ const relation =
+ compareSourceOrder(inventory, review) ??
+ // A resolved projection or bounded omitted review preserves the live
+ // sequence, including marker order within one command. It does not
+ // assign either completion an otherwise unknown saved occurrence.
+ (inventory.live !== undefined && review.live !== undefined
+ ? inventory.order - review.order
+ : undefined);
+ if (relation !== undefined && relation >= 0) return relation;
+ if (relation === undefined) order = undefined;
+ }
+ return order;
+ }
+
+ #afterParentFrontier(position: number, index: number): boolean {
+ return (
+ position > this.#parentFrontier.position ||
+ (position === this.#parentFrontier.position &&
+ index > this.#parentFrontier.markerIndex)
+ );
+ }
+
+ #advanceParentFrontier(position: number, markerIndex: number): void {
+ if (this.#afterParentFrontier(position, markerIndex))
+ this.#parentFrontier = { position, markerIndex };
+ }
+
+ #unresolvedParentCommand(): UnresolvedParentCommand | undefined {
+ const live = this.#acceptedParent;
+ if (
+ live?.position !== null ||
+ live.after === undefined ||
+ !live.markers.some((marker) => marker.accepted)
+ )
+ return undefined;
+ return { live, after: live.after };
+ }
+
+ #boundParentCommands(
+ session: SessionUsage,
+ start = 0,
+ end = this.#liveParentItems.length,
+ completionIndex = 0,
+ ): void {
+ // Exact-only intervals require neither source scans nor alias indexes.
+ while (start < end && this.#liveParentItems[start]!.position !== null)
+ start++;
+ if (
+ start === end ||
+ !this.#parentTurnStartKnown ||
+ !session.completions.some((completion) => completion.kind === "command")
+ )
+ return;
+ while (start < end) {
+ if (this.#liveParentItems[start]!.position !== null) {
+ start++;
+ continue;
+ }
+ let stop = start;
+ while (stop < end && this.#liveParentItems[stop]!.position === null)
+ stop++;
+ const before = this.#liveParentItems[start - 1]?.position ?? 0;
+ const after = this.#liveParentItems[stop]?.position ?? Infinity;
+ const saved = new Map<string, SessionCompletion[]>();
+ while (
+ completionIndex < session.completions.length &&
+ session.completions[completionIndex]!.position < after
+ ) {
+ const completion = session.completions[completionIndex++]!;
+ if (
+ completion.position <= before ||
+ completion.item?.kind !== "command"
+ )
+ continue;
+ // Bounded projections are derived from this interval, not occurrences.
+ // Rebuild them when a later completion provides a tighter bound.
+ if (completion.projection?.position === null)
+ delete completion.projection;
+ const key = completion.item.outputDigest;
+ const occurrences = saved.get(key);
+ if (occurrences === undefined) saved.set(key, [completion]);
+ else occurrences.push(completion);
+ }
+ const observed = new Map<string, number[]>();
+ const groups = new Map<string, { keys: string[]; members: number[] }>();
+ for (let index = start; index < stop; index++) {
+ const live = this.#liveParentItems[index]!;
+ if (live.item?.kind !== "command") continue;
+ const keys = [
+ ...new Set([live.item.outputDigest, live.item.persistedOutputDigest]),
+ ]
+ .filter((key) => saved.has(key))
+ .sort();
+ for (const key of keys) {
+ const occurrences = observed.get(key);
+ if (occurrences === undefined) observed.set(key, [index]);
+ else occurrences.push(index);
+ }
+ if (live.markers.length === 0) continue;
+ const key = keys.join(":");
+ const group = groups.get(key);
+ if (group === undefined) groups.set(key, { keys, members: [index] });
+ else group.members.push(index);
+ }
+ const evidence = new Map<
+ number,
+ {
+ candidates: { saved: SessionCompletion[]; first: number }[];
+ reserved: boolean;
+ }
+ >();
+ for (const { keys, members } of groups.values()) {
+ const queues = keys.map((key) => ({
+ key,
+ saved: saved.get(key)!,
+ observed: observed.get(key)!,
+ reserved: 0,
+ next: 0,
+ }));
+ let reservations = 0;
+ for (const index of members) {
+ // Reserve preceding compatible live items once for this signature
+ // group. Advancing ordered cursors is equivalent to consuming the
+ // earliest compatible item for each saved occurrence, without splice.
+ while (true) {
+ const previous = Math.min(
+ ...queues.map((queue) => queue.observed[queue.next] ?? Infinity),
+ );
+ if (previous >= index) break;
+ const item = this.#liveParentItems[previous]!.item!;
+ let selected: (typeof queues)[number] | undefined;
+ for (const queue of queues) {
+ if (queue.observed[queue.next] === previous) queue.next++;
+ if (
+ (queue.key === item.outputDigest ||
+ queue.key === item.persistedOutputDigest) &&
+ queue.reserved < queue.saved.length &&
+ (selected === undefined ||
+ queue.saved[queue.reserved]!.position <
+ selected.saved[selected.reserved]!.position)
+ )
+ selected = queue;
+ }
+ if (selected !== undefined) {
+ selected.reserved++;
+ reservations++;
+ }
+ }
+ evidence.set(index, {
+ candidates: queues.map((queue) => ({
+ saved: queue.saved,
+ first: queue.reserved,
+ })),
+ reserved: reservations > 0,
+ });
+ }
+ }
+ // Later complete projections constrain earlier compatible copies. A
+ // bound narrows the interval without assigning a live occurrence.
+ let bound = after;
+ for (let index = stop - 1; index >= start; index--) {
+ const live = this.#liveParentItems[index]!;
+ bound = Math.min(bound, live.after ?? Infinity);
+ const progress = live.markers.at(-1)?.progress;
+ if (live.item?.kind !== "command" || progress === undefined) {
+ if (bound !== Infinity) live.after = bound;
+ continue;
+ }
+ const { candidates, reserved } = evidence.get(index)!;
+ let latest: SessionCompletion | undefined;
+ for (const { saved, first } of candidates) {
+ let lower = first;
+ let upper = saved.length;
+ while (lower < upper) {
+ const middle = Math.floor((lower + upper) / 2);
+ if (saved[middle]!.position < bound) lower = middle + 1;
+ else upper = middle;
+ }
+ const candidate = lower > first ? saved[lower - 1] : undefined;
+ if (
+ candidate !== undefined &&
+ (latest === undefined || candidate.position > latest.position)
+ )
+ latest = candidate;
+ }
+ if (
+ latest === undefined &&
+ !reserved &&
+ bound === Infinity &&
+ !isInventoryProgress(progress)
+ )
+ continue;
+ const visible = latest?.lastCommandProgress;
+ const fullProjection =
+ bound !== Infinity &&
+ visible !== undefined &&
+ visible.markerIndex === live.markers.length - 1 &&
+ progressKey(visible.update) === progressKey(progress);
+ if (fullProjection) latest!.projection = live;
+ live.after = Math.min(
+ live.after ?? Infinity,
+ fullProjection ? visible.position + 1 : bound,
+ );
+ // A preceding completion ends before this projection's inclusive edge.
+ bound = Math.min(bound, fullProjection ? visible.position : live.after);
+ }
+ start = stop + 1;
+ }
+ }
+
+ #matchParentCompletions(): void {
+ if (this.#parentSession === null || !this.#parentTurnStartKnown) return;
+ const completions = this.#parentSession.completions;
+ // Ordinary live completions can be dropped by native queue backpressure.
+ // Match ordered signatures, not list indexes. Identical output signatures
+ // remain ambiguous; use the earliest compatible occurrence after our anchor.
+ const add = (
+ index: number,
+ key: string,
+ queues: ProgressOccurrenceQueues,
+ ) => {
+ let queue = queues.get(key);
+ if (queue === undefined) {
+ queue = { indexes: [], next: 0 };
+ queues.set(key, queue);
+ }
+ queue.indexes.push(index);
+ this.#queueParentMatch(key);
+ };
+ while (this.#indexedParentCompletions < completions.length) {
+ const index = this.#indexedParentCompletions++;
+ const item = completions[index]!.item;
+ if (item !== null)
+ add(index, progressItemKey(item), this.#parentCompletionKeys);
+ }
+ while (this.#indexedParentItems < this.#liveParentItems.length) {
+ const index = this.#indexedParentItems++;
+ const item = this.#liveParentItems[index]!.item;
+ if (item !== null)
+ for (const key of progressItemKeys(item))
+ add(index, key, this.#parentItemKeys);
+ }
+ while (this.#parentMatches.length > 0) {
+ const index = takeFirstIndex(this.#parentMatches);
+ this.#pendingParentMatches.delete(index);
+ if (index < this.#matchedParentItems) continue;
+ const live = this.#liveParentItems[index]!;
+ if (live.item === null) continue;
+ let matched: number | undefined;
+ for (const key of progressItemKeys(live.item)) {
+ const queue = this.#parentCompletionKeys.get(key);
+ const savedIndex = queue?.indexes[queue.next];
+ if (
+ savedIndex !== undefined &&
+ (matched === undefined || savedIndex < matched)
+ )
+ matched = savedIndex;
+ }
+ if (matched === undefined) continue;
+ live.position = completions[matched]!.position;
+ completions[matched]!.projection = live;
+ for (const marker of live.markers)
+ this.#readyParentMarkers.set(marker, live);
+ this.#boundParentCommands(
+ this.#parentSession,
+ this.#matchedParentItems,
+ index + 1,
+ this.#parentCompletionCursor,
+ );
+ const changed = new Set<string>();
+ const remove = (key: string, queues: ProgressOccurrenceQueues) => {
+ const queue = queues.get(key)!;
+ if (++queue.next === queue.indexes.length) queues.delete(key);
+ changed.add(key);
+ };
+ // A compatible later anchor lets both prefixes advance. Without an
+ // anchor, retain compact unmatched signatures: reads can precede writes
+ // or native persistence can fail and later retry. Neither blocks other
+ // compatible signatures, and each occurrence is indexed/consumed once.
+ while (this.#matchedParentItems <= index) {
+ const previous = this.#liveParentItems[this.#matchedParentItems++]!;
+ if (previous.position === null) {
+ if (previous.item?.kind !== "command") {
+ previous.after = Math.min(
+ previous.after ?? Infinity,
+ live.position,
+ );
+ }
+ }
+ if (previous.item !== null) {
+ for (const key of progressItemKeys(previous.item))
+ remove(key, this.#parentItemKeys);
+ if (previous.position !== null) previous.item = null;
+ }
+ }
+ while (this.#parentCompletionCursor <= matched) {
+ const saved = completions[this.#parentCompletionCursor++]!;
+ if (saved.item !== null) {
+ remove(progressItemKey(saved.item), this.#parentCompletionKeys);
+ if (saved.position === live.position) {
+ saved.item = null;
+ }
+ }
+ }
+ for (const key of changed) this.#queueParentMatch(key);
+ }
+ }
+
+ #queueParentMatch(key: string): void {
+ if (!this.#parentCompletionKeys.has(key)) return;
+ const queue = this.#parentItemKeys.get(key);
+ const index = queue?.indexes[queue.next];
+ if (index === undefined || this.#pendingParentMatches.has(index)) return;
+ this.#pendingParentMatches.add(index);
+ insertIndex(this.#parentMatches, index);
+ }
+
+ #corroboratedInventory(
+ live: StreamedProgressItem,
+ marker: ParentProgressMarker,
+ inventoryWitness?: ProgressOrder,
+ ): InventoryEvidence | undefined {
+ if (
+ !this.#parentTurnStartKnown ||
+ marker.progress.filesCompleted === 0 ||
+ live.position === null
+ )
+ return undefined;
+ let inventory: ParentProgressMarker | undefined;
+ let pending: StreamedProgressItem | undefined;
+ for (
+ let index = this.#liveParentItems.indexOf(live) - 1;
+ index >= 0;
+ index--
+ ) {
+ const candidate = this.#liveParentItems[index]!;
+ inventory = candidate.markers.findLast(
+ (observed) =>
+ (observed.accepted || observed === this.#parentInventory) &&
+ isInventoryProgress(observed.progress) &&
+ observed.progress.filesTotal === marker.progress.filesTotal,
+ );
+ if (inventory !== undefined) {
+ pending = candidate;
+ break;
+ }
+ }
+ if (
+ inventory === undefined ||
+ pending === undefined ||
+ !this.#inventoryAllowedInCompletion(pending, inventory.index)
+ )
+ return undefined;
+ let position = pending.position;
+ if (position === null) {
+ const item = pending.item;
+ if (item?.kind !== "command") return undefined;
+ for (const completion of this.#parentSession?.completions ?? []) {
+ if (
+ completion.item?.kind !== "command" ||
+ completion.item.outputDigest !== item.persistedOutputDigest
+ )
+ continue;
+ if (position !== null) return undefined;
+ position = completion.position;
+ }
+ }
+ // A retained source row may have supplied scope before its lossy live copy
+ // arrived. Reusing that receipt does not locate the live command.
+ const source = this.#inventoryFrontier.source;
+ const admittedSource =
+ source?.inventoryAdmitted === true &&
+ source.position === position &&
+ source.markerIndex === inventory.index &&
+ progressKey(source.update) === progressKey(inventory.progress);
+ // A matched review can corroborate an accepted inventory or admit a lost
+ // inventory without assigning its command a guessed occurrence. A later
+ // inventory still wins, and duplicate lossy output remains ambiguous.
+ const bounded =
+ position !== null &&
+ (position > this.#inventoryFrontier.position ||
+ (position === this.#inventoryFrontier.position &&
+ ((pending.position !== null &&
+ inventory.index >= this.#inventoryFrontier.markerIndex) ||
+ admittedSource))) &&
+ (position < live.position ||
+ (pending.position !== null &&
+ position === live.position &&
+ inventory.index < marker.index));
+ if (
+ !bounded ||
+ !this.#inventoryPrecedesReview(
+ position!,
+ pending.position === null ? 0 : inventory.index,
+ )
+ )
+ return undefined;
+ const later = this.#parentSession?.progress.findLast(
+ (saved) =>
+ !saved.duplicate &&
+ isInventoryProgress(saved.update) &&
+ (saved.position > position! ||
+ (pending.position !== null &&
+ saved.position === position &&
+ saved.markerIndex > inventory.index)) &&
+ (saved.position < live.position! ||
+ (saved.position === live.position &&
+ saved.markerIndex < marker.index)) &&
+ this.#parentInventoryAdmission(
+ saved,
+ undefined,
+ {
+ live: pending,
+ after: {
+ position: position!,
+ markerIndex: inventory.index,
+ order: inventory.order,
+ },
+ },
+ inventoryWitness,
+ ) !== "retained",
+ );
+ // Corroboration admits scope without relocating the inventory to the review.
+ // Its original live order continues to participate alongside newer scopes.
+ if (later === undefined && pending.position === null) {
+ inventory.accepted = true;
+ return undefined;
+ }
+ return later === undefined
+ ? {
+ progress: inventory.progress,
+ position: pending.position!,
+ markerIndex: inventory.index,
+ order: inventory.order,
+ }
+ : {
+ progress: later.update,
+ position: later.position,
+ markerIndex: later.markerIndex,
+ order: (later.order ??= ++this.#progressOrder),
+ afterLive: pending,
+ source: later,
+ };
+ }
+
+ #reconcileParentProgress(): ProgressOrder | undefined {
+ const ready = [...this.#readyParentMarkers];
+ this.#readyParentMarkers.clear();
+ for (const [marker, live] of ready) {
+ if (live.position !== null) {
+ this.#rememberParentFact({
+ progress: marker.progress,
+ order: marker.order,
+ position: live.position,
+ markerIndex: marker.index,
+ live,
+ });
+ if (marker.accepted)
+ this.#recordParentBoundary(
+ marker.progress,
+ live.position,
+ marker.index,
+ true,
+ marker.scopeFilesTotal,
+ live,
+ );
+ }
+ if (marker.accepted && live.position !== null) {
+ const source = { position: live.position, markerIndex: marker.index };
+ if (this.#parentProgress?.order === marker.order)
+ Object.assign(this.#parentProgress, source);
+ if (
+ this.#displayedProgress?.owner !== "worker" &&
+ this.#displayedProgress?.order === marker.order
+ )
+ Object.assign(this.#displayedProgress, source);
+ }
+ }
+ if (this.#parentSession !== null)
+ this.#boundParentCommands(this.#parentSession);
+ const unresolvedCommand = this.#unresolvedParentCommand();
+ // Source proof and its eligible review cutoff precede inventory admission.
+ // A count-rejected review can invalidate a later provisional inventory.
+ const sourceInventory =
+ this.#recordParentSourceBoundaries(unresolvedCommand);
+ let witnessParent = this.#acceptedParent;
+ let inventoryWitness = this.#parentInventoryWitness();
+ if (
+ !this.#inventoryPrecedesReview(
+ this.#inventoryFrontier.position,
+ this.#inventoryFrontier.markerIndex,
+ this.#inventoryFrontier.live ??
+ this.#inventoryFrontier.source?.projection,
+ this.#inventoryFrontier.source,
+ )
+ )
+ this.#inventoryFrontier = { position: 0, markerIndex: -1, order: 0 };
+ const acceptedInventory = this.#acceptedInventory();
+ let corrected:
+ (OrderedProgress & { owner: "worker" | "live" | "parent" }) | null = null;
+ for (const [marker, live] of ready) {
+ const position = live.position;
+ if (position === null) continue;
+ const corroborated = this.#corroboratedInventory(
+ live,
+ marker,
+ inventoryWitness,
+ );
+ const progress = corroborated?.progress ?? marker.progress;
+ if (
+ marker === this.#parentInventory &&
+ !marker.accepted &&
+ this.#parentProgress !== null &&
+ this.#parentProgress.progress.filesCompleted > 0 &&
+ this.#parentIsEligible(this.#parentProgress) &&
+ this.#parentInventoryBoundary?.reviewed !== true
+ ) {
+ // A read can reach EOF before the next completion is appended, then
+ // receive both live items while file.close is pending. Keep the compact
+ // inventory proof until the admitted review's source position resolves.
+ this.#readyParentMarkers.set(marker, live);
+ continue;
+ }
+ if (
+ (corroborated !== undefined ||
+ marker === acceptedInventory?.marker ||
+ (marker === this.#parentInventory &&
+ this.#inventoryPrecedesReview(position, marker.index, live))) &&
+ (corroborated !== undefined ||
+ this.#inventoryPrecedesReview(position, marker.index, live)) &&
+ isInventoryProgress(progress) &&
+ (position > this.#inventoryFrontier.position ||
+ (position === this.#inventoryFrontier.position &&
+ marker.index >= this.#inventoryFrontier.markerIndex))
+ ) {
+ // A saved occurrence remains authoritative when its live copy arrives
+ // after polling consumed it, even if provisional coverage rejects it.
+ // Inventory may precede already-admitted review even when its full live
+ // marker arrives later. For lossy output, the real matched review marks
+ // the scope-proof boundary; the missing inventory position stays unknown.
+ this.#inventoryFrontier = corroborated ?? {
+ position,
+ markerIndex: marker.index,
+ order: marker.order,
+ progress,
+ live,
+ };
+ }
+ }
+ if (
+ acceptedInventory !== undefined &&
+ acceptedInventory.marker === this.#parentInventory &&
+ acceptedInventory.live.position === null &&
+ (!this.#parentIsEligible(this.#parentProgress) ||
+ this.#parentProgress.progress.filesCompleted === 0) &&
+ acceptedInventory.order > (this.#parentProgress?.order ?? 0)
+ ) {
+ // This live inventory was accepted for deferred scope reconciliation;
+ // its saved occurrence remains unknown until source matching resolves it.
+ const progress = acceptedInventory.marker.progress;
+ this.#acceptedParent = acceptedInventory.live;
+ this.#parentProgress = {
+ progress,
+ order: acceptedInventory.order,
+ live: acceptedInventory.live,
+ markerIndex: acceptedInventory.marker.index,
+ };
+ this.#liveParentProgress.add(progressKey(progress));
+ corrected = { ...this.#parentProgress, owner: "live" };
+ witnessParent = this.#acceptedParent;
+ inventoryWitness = this.#parentInventoryWitness();
+ }
+ // Recover eligible retained source authority before a baseline rollback
+ // could temporarily revive an out-of-scope parent or worker phase.
+ if (
+ this.#retainedInventory() === undefined &&
+ this.#acceptedInventory() === undefined &&
+ sourceInventory?.source !== undefined
+ ) {
+ const admission = this.#parentInventoryAdmission(
+ sourceInventory.source,
+ unresolvedCommand,
+ undefined,
+ inventoryWitness,
+ );
+ if (admission === "current" || admission === "proven")
+ this.#inventoryFrontier = sourceInventory;
+ }
+ const inventory = this.#retainedInventory();
+ this.#projectParentInventory();
+ const inventoryChanged = this.#inventoryNeedsReconciliation;
+ this.#inventoryNeedsReconciliation = false;
+ const parentIneligible =
+ this.#parentProgress !== null &&
+ !this.#parentIsEligible(this.#parentProgress);
+ const inventoryReconciled = inventoryChanged || parentIneligible;
+ if (inventoryReconciled) {
+ let retainedWorker: OrderedProgress | null = null;
+ // Reconsider compact worker receipts under the proven inventory. Keep an
+ // oversized receipt available without counting it as reviewed coverage.
+ for (const session of this.#sessions.values()) {
+ if (session.threadId === null || session.threadId === this.#threadId)
+ continue;
+ for (const [total, pending] of session.pendingWorkerProgress) {
+ const progress = pending.progress;
+ if (
+ total > this.#expectedFilesTotal! ||
+ (session.filesTotal !== null && total !== session.filesTotal) ||
+ progress.filesCompleted < session.filesCompleted
+ )
+ continue;
+ session.filesTotal = total;
+ session.filesCompleted = progress.filesCompleted;
+ const latest = session.latestWorkerProgress;
+ if (
+ latest === null ||
+ progress.filesCompleted > latest.progress.filesCompleted ||
+ pending.order > latest.order
+ )
+ session.latestWorkerProgress = pending;
+ session.pendingWorkerProgress.delete(total);
+ if (corrected === null || pending.order > corrected.order)
+ corrected = { ...pending, owner: "worker" };
+ }
+ if (
+ session.filesTotal !== null &&
+ session.filesTotal <= this.#expectedFilesTotal!
+ ) {
+ this.#workerProgress.set(session.threadId, session.filesCompleted);
+ const latest = session.latestWorkerProgress;
+ if (
+ latest !== null &&
+ (retainedWorker === null || latest.order > retainedWorker.order)
+ )
+ retainedWorker = latest;
+ if (
+ parentIneligible &&
+ latest !== null &&
+ (corrected === null || latest.order > corrected.order)
+ )
+ corrected = { ...latest, owner: "worker" };
+ } else this.#workerProgress.delete(session.threadId);
+ }
+ const parentCount = this.#parentIsEligible(this.#parentProgress)
+ ? this.#parentProgress.progress.filesCompleted
+ : 0;
+ // Project the phase from the greatest eligible coverage. A zero-count
+ // inventory establishes scope but cannot mask restored worker progress.
+ const workerCoverage = Math.min(
+ this.#expectedFilesTotal!,
+ this.#workerProgress.values().reduce((sum, count) => sum + count, 0),
+ );
+ if (
+ retainedWorker !== null &&
+ workerCoverage > parentCount &&
+ (corrected === null ||
+ (corrected.owner !== "worker" &&
+ workerCoverage > corrected.progress.filesCompleted))
+ )
+ corrected = { ...retainedWorker, owner: "worker" };
+ this.#highestFilesCompleted = Math.max(parentCount, workerCoverage);
+ if (this.#parentSession !== null) {
+ this.#parentSession.filesCompleted = parentCount;
+ this.#parentSession.filesTotal = this.#expectedFilesTotal!;
+ }
+ }
+ const workerCoverage = Math.min(
+ this.#expectedFilesTotal ?? Number.MAX_SAFE_INTEGER,
+ this.#workerProgress.values().reduce((sum, count) => sum + count, 0),
+ );
+ for (const currentCompletion of this.#liveParentItems) {
+ if (
+ currentCompletion.position !== null ||
+ // Unfamiliar projections supply no source identity. Keep the existing
+ // recovery of an admitted completion's remaining parsed markers.
+ (currentCompletion.item === null &&
+ !currentCompletion.markers.some((marker) => marker.accepted))
+ )
+ continue;
+ // A bound orders other completions; it does not retire later markers
+ // inside any retained completion. Scope can make those markers eligible
+ // after provisional worker coverage prevented their live admission.
+ for (const marker of currentCompletion.markers) {
+ const progress = marker.progress;
+ const candidate: OrderedProgress & { owner: "live" } = {
+ progress,
+ order: marker.order,
+ live: currentCompletion,
+ markerIndex: marker.index,
+ owner: "live",
+ };
+ if (
+ marker.accepted ||
+ !this.#parentSourceIsEligible(candidate) ||
+ // Inventory has its own admission path. A rejected inventory cannot
+ // become a phase merely because coverage later falls to zero.
+ isInventoryProgress(progress) ||
+ progress.filesTotal >
+ (this.#expectedFilesTotal ?? Number.MAX_SAFE_INTEGER) ||
+ progress.filesCompleted < this.#highestFilesCompleted ||
+ (this.#parentProgress !== null &&
+ compareProgressOrder(candidate, this.#parentProgress) < 0)
+ )
+ continue;
+ marker.accepted = true;
+ this.#acceptedParent = currentCompletion;
+ this.#recordParentBoundary(
+ progress,
+ undefined,
+ marker.index,
+ true,
+ undefined,
+ currentCompletion,
+ );
+ this.#parentProgress = candidate;
+ this.#liveParentProgress.add(progressKey(progress));
+ this.#highestFilesCompleted = progress.filesCompleted;
+ const correctedCoverage =
+ corrected?.owner === "worker"
+ ? workerCoverage
+ : (corrected?.progress.filesCompleted ?? -1);
+ if (
+ progress.filesCompleted > correctedCoverage ||
+ (progress.filesCompleted === correctedCoverage &&
+ corrected !== null &&
+ compareProgressOrder(candidate, corrected) > 0)
+ )
+ corrected = candidate;
+ }
+ }
+ for (const [marker, live] of ready) {
+ const position = live.position;
+ const progress = marker.progress;
+ const deferredCoverage =
+ !marker.accepted &&
+ progress.filesCompleted > this.#highestFilesCompleted;
+ if (
+ position === null ||
+ (!deferredCoverage &&
+ !this.#afterParentFrontier(position, marker.index) &&
+ !(
+ inventoryChanged &&
+ marker === this.#parentInventory &&
+ position === this.#parentFrontier.position &&
+ marker.index === this.#parentFrontier.markerIndex
+ ))
+ )
+ continue;
+ const candidate: OrderedProgress & { owner: "live" } = {
+ progress,
+ order: marker.order,
+ position,
+ markerIndex: marker.index,
+ live,
+ owner: "live",
+ };
+ const selectedCoverage =
+ corrected?.owner === "worker"
+ ? workerCoverage
+ : (corrected?.progress.filesCompleted ?? -1);
+ // Do not let a newer, lower-coverage worker candidate mask a valid parent
+ // correction before the final display guards can consider it.
+ const preferCandidate =
+ corrected === null ||
+ progress.filesCompleted > selectedCoverage ||
+ (progress.filesCompleted === selectedCoverage &&
+ compareProgressOrder(candidate, corrected) > 0);
+ if (!marker.accepted) {
+ if (
+ (this.#expectedFilesTotal !== undefined &&
+ progress.filesTotal > this.#expectedFilesTotal) ||
+ progress.filesTotal >
+ (marker.scopeFilesTotal ?? Number.MAX_SAFE_INTEGER) ||
+ progress.filesCompleted < this.#highestFilesCompleted ||
+ (isInventoryProgress(progress) &&
+ !this.#inventoryPrecedesReview(position, marker.index, live))
+ ) {
+ // Saved inventory can admit the live receipt or invalidate provisional
+ // worker coverage. Keep only the parsed fact until it is eligible.
+ this.#readyParentMarkers.set(marker, live);
+ continue;
+ }
+ marker.accepted = true;
+ this.#acceptedParent = live;
+ const selectedParent = this.#parentProgress;
+ if (
+ !this.#parentIsEligible(selectedParent) ||
+ progress.filesCompleted !== selectedParent.progress.filesCompleted ||
+ compareProgressOrder(candidate, selectedParent) >= 0
+ )
+ this.#parentProgress = {
+ progress,
+ order: marker.order,
+ position,
+ markerIndex: marker.index,
+ live,
+ };
+ this.#recordParentBoundary(
+ progress,
+ position,
+ marker.index,
+ false,
+ marker.scopeFilesTotal,
+ );
+ this.#liveParentProgress.add(progressKey(progress));
+ this.#highestFilesCompleted = progress.filesCompleted;
+ if (preferCandidate) corrected = candidate;
+ } else if (
+ this.#parentIsEligible(candidate) &&
+ this.#displayedProgress?.owner === "parent" &&
+ compareProgressOrder(candidate, this.#displayedProgress) > 0 &&
+ preferCandidate
+ ) {
+ corrected = candidate;
+ }
+ this.#advanceParentFrontier(position, marker.index);
+ }
+ if (witnessParent !== this.#acceptedParent)
+ inventoryWitness = this.#parentInventoryWitness();
+ // Parent facts outlive display admission and queue draining. Preserve the
+ // greatest eligible coverage for each original inventory, then source order.
+ let eligible = this.#parentIsEligible(this.#parentProgress)
+ ? this.#parentProgress
+ : null;
+ for (const candidate of [
+ ...this.#parentFacts.values(),
+ ...(inventory === undefined ? [] : [inventory]),
+ ]) {
+ // Apply eligible preceding inventories before promoting a retained phase.
+ // Retained copies and unresolved alternatives are not unapplied work.
+ if (
+ this.#parentSession?.progress.some((saved) => {
+ const admission = this.#parentInventoryAdmission(
+ saved,
+ unresolvedCommand,
+ undefined,
+ inventoryWitness,
+ );
+ return (
+ (admission === "current" || admission === "proven") &&
+ (saved.position < candidate.position! ||
+ (saved.position === candidate.position &&
+ saved.markerIndex < candidate.markerIndex!))
+ );
+ })
+ )
+ continue;
+ if (
+ !this.#parentIsEligible(candidate) ||
+ candidate.progress.filesCompleted < workerCoverage
+ )
+ continue;
+ if (
+ eligible === null ||
+ candidate.progress.filesCompleted > eligible.progress.filesCompleted ||
+ (candidate.progress.filesCompleted ===
+ eligible.progress.filesCompleted &&
+ compareProgressOrder(candidate, eligible) > 0)
+ )
+ eligible = candidate;
+ }
+ if (eligible !== null) {
+ this.#parentProgress = eligible;
+ this.#advanceParentFrontier(eligible.position!, eligible.markerIndex!);
+ this.#recordParentBoundary(
+ eligible.progress,
+ eligible.position!,
+ eligible.markerIndex!,
+ false,
+ eligible.source?.scopeFilesTotal ??
+ eligible.live?.markers[eligible.markerIndex ?? 0]?.scopeFilesTotal,
+ eligible.live,
+ );
+ this.#highestFilesCompleted = Math.max(
+ workerCoverage,
+ eligible.progress.filesCompleted,
+ );
+ if (this.#parentSession !== null) {
+ this.#parentSession.filesCompleted = eligible.progress.filesCompleted;
+ this.#parentSession.filesTotal =
+ this.#expectedFilesTotal ?? eligible.progress.filesTotal;
+ }
+ const correctedCoverage =
+ corrected?.owner === "worker"
+ ? workerCoverage
+ : (corrected?.progress.filesCompleted ?? -1);
+ if (
+ corrected === null ||
+ eligible.progress.filesCompleted > correctedCoverage ||
+ (eligible.progress.filesCompleted === correctedCoverage &&
+ compareProgressOrder(eligible, corrected) > 0)
+ )
+ corrected = { ...eligible, owner: "parent" };
+ }
+ const displayed = this.#displayedProgress;
+ const displayedParentIneligible =
+ displayed !== null &&
+ displayed.owner !== "worker" &&
+ !this.#parentIsEligible({
+ ...displayed,
+ // Scope recovery can replace the parent before changing the display.
+ // Requalify the receipt that actually supplied the displayed phase.
+ progress:
+ displayed.live?.markers[displayed.markerIndex ?? 0]?.progress ??
+ displayed.source?.update ??
+ displayed.update,
+ });
+ if (!inventoryReconciled && corrected === null) return inventoryWitness;
+ const correctedCoverage =
+ corrected?.owner === "worker"
+ ? workerCoverage
+ : (corrected?.progress.filesCompleted ?? 0);
+ const replacePhase =
+ corrected !== null &&
+ correctedCoverage >= this.#highestFilesCompleted &&
+ (displayed === null ||
+ displayedParentIneligible ||
+ correctedCoverage > displayed.update.filesCompleted ||
+ compareProgressOrder(corrected, displayed) >= 0);
+ const selected = replacePhase ? corrected : displayed;
+ const parent = this.#parentProgress;
+ const parentAtEqualCoverage =
+ selected?.owner === "worker" &&
+ this.#parentIsEligible(parent) &&
+ parent.progress.filesCompleted === this.#highestFilesCompleted;
+ const phase = parentAtEqualCoverage
+ ? parent.progress.phase
+ : replacePhase
+ ? corrected!.progress.phase
+ : (displayed?.update.phase ?? "discovery");
+ const progress = {
+ phase,
+ filesCompleted: this.#highestFilesCompleted,
+ filesTotal:
+ this.#expectedFilesTotal ??
+ corrected?.progress.filesTotal ??
+ displayed!.update.filesTotal,
+ };
+ const key = progressKey(progress);
+ // An initial zero-count discovery already reported this inventory. Other
+ // equal raw keys can still require synchronization of the API's file total.
+ const inventoryReported = isInventoryProgress(progress);
+ const duplicate =
+ displayed !== null &&
+ progressKey(displayed.update) === key &&
+ (!inventoryReconciled || inventoryReported);
+ const displaySource = parentAtEqualCoverage
+ ? { ...parent, owner: "parent" as const }
+ : selected;
+ this.#displayedProgress = {
+ update: progress,
+ owner: displaySource?.owner ?? "live",
+ order: displaySource?.order ?? 0,
+ live: displaySource?.live,
+ source: displaySource?.source,
+ markerIndex: displaySource?.markerIndex,
+ ...(displaySource?.position === undefined
+ ? {}
+ : {
+ position: displaySource.position,
+ }),
+ };
+ if (duplicate) return inventoryWitness;
+ this.#options.onProgress?.(progress, {
+ reconciled: true,
+ ...(displaySource?.owner === "worker" ? { worker: true } : {}),
+ // Recovered prefix scope can invalidate coverage even when a later
+ // inventory restores the same total. Synchronize the API's count too.
+ ...(inventoryReconciled ? { inventory: true } : {}),
+ });
+ return inventoryWitness;
+ }
+
+ #savedParentProgressIsCurrent(saved: SessionProgress): boolean {
+ if (!this.#afterParentFrontier(saved.position, saved.markerIndex))
+ return false;
+ // An outer tool result has its own completion order. Native output does not
+ // identify whether its text was copied from a nested command or emitted
+ // directly, so text equality and call-start time cannot establish a copy.
+ // Treat it as a receipt; a copied truncated preview can consequently hide
+ // omitted same-count phases from its earlier command. This is best effort.
+ if (saved.receipt) return true;
+ const live = this.#acceptedParent;
+ if (live === null) return true;
+ // A later saved occurrence may legitimately repeat an earlier live tuple,
+ // including progress recovered only from the original multipart response.
+ if (live.position !== null) return saved.position > live.position;
+ if (live.after !== undefined) return saved.position >= live.after;
+ return !this.#unboundParentCopy(saved);
+ }
+
+ #unboundParentCopy(saved: SessionProgress): boolean {
+ const live = this.#acceptedParent;
+ return (
+ !saved.receipt &&
+ live?.position === null &&
+ live.after === undefined &&
+ this.#liveParentProgress.has(progressKey(saved.update))
+ );
+ }
+
public recordUsage(usage: unknown, threadId = this.#threadId): void {
const normalized = tokenUsage(usage);
if (threadId !== null) {
@@ -254,6 +2270,8 @@ export class ScanCostTracker {
this.#options.onActivity === undefined
? undefined
: this.#options.repository;
+ const progressThread =
+ this.#options.onProgress === undefined ? undefined : this.#threadId;
const unreadable: Array<{ session: SessionUsage; error: unknown }> = [];
for await (const path of sessionFiles(
join(this.#options.codexHome, "sessions"),
@@ -264,7 +2282,7 @@ export class ScanCostTracker {
this.#sessions.set(path, session);
}
try {
- await readSessionUsage(path, session, repository);
+ await readSessionUsage(path, session, repository, progressThread);
} catch (error) {
if (session.threadId === null) throw error;
unreadable.push({ session, error });
@@ -316,19 +2334,36 @@ export class ScanCostTracker {
}
const usages = new Map(this.#receipts);
- for (const [path, tracked] of this.#sessions) {
- const threadId = tracked.threadId;
+ for (const [path, session] of this.#sessions) {
+ const threadId = session.threadId;
if (threadId === null || !included.has(threadId)) continue;
- let session = tracked;
if (
this.#options.onSessionEvent !== undefined &&
session.events === undefined
) {
- // Replay only newly associated sessions, including their early events.
- session = createSessionUsage(observeUsage);
- session.events = [];
- await readSessionUsage(path, session, repository);
- this.#sessions.set(path, session);
+ // Replay event history through the already-read snapshot without
+ // replacing its authoritative progress, usage, or partial-line decoder.
+ const replay: SessionUsage = createSessionUsage(false);
+ replay.events = [];
+ await readSessionUsage(
+ path,
+ replay,
+ undefined,
+ undefined,
+ session.offset,
+ );
+ if (replay.offset === session.offset) {
+ session.events = replay.events;
+ // At stop there is no next poll to read usage appended during replay.
+ if (this.#timer === null)
+ await readSessionUsage(
+ path,
+ session,
+ repository,
+ progressThread,
+ "file-size",
+ );
+ }
}
let worker: number | undefined;
if (threadId !== this.#threadId) {
@@ -356,7 +2391,43 @@ export class ScanCostTracker {
worker,
});
}
- this.#reportWorkerProgress(session);
+ }
+ let unresolvedCommand: UnresolvedParentCommand | undefined;
+ let inventoryWitness: ProgressOrder | undefined;
+ if (threadId === this.#threadId) {
+ this.#parentSession = session;
+ for (const saved of session.progress)
+ if (saved.order !== undefined && !saved.duplicate)
+ this.#rememberParentFact(savedProgress(saved));
+ this.#matchParentCompletions();
+ inventoryWitness = this.#reconcileParentProgress();
+ unresolvedCommand = this.#unresolvedParentCommand();
+ }
+ const reviewWasUnpositioned =
+ this.#parentInventoryBoundary?.reviewed !== true;
+ this.#reportSessionProgress(
+ session,
+ threadId === this.#threadId,
+ unresolvedCommand,
+ inventoryWitness,
+ );
+ // Fresh saved facts are observed at their source-loop position, so initial
+ // inventory notifications keep their order. Recover after the batch too:
+ // a later accepted parent may have hidden an eligible earlier receipt.
+ if (threadId === this.#threadId) {
+ // A newly admitted review locates inventories parked earlier in this
+ // batch. Reconsider them before the final refresh returns.
+ if (
+ reviewWasUnpositioned &&
+ this.#parentInventoryBoundary?.reviewed === true
+ )
+ this.#reportSessionProgress(
+ session,
+ true,
+ unresolvedCommand,
+ inventoryWitness,
+ );
+ this.#reconcileParentProgress();
}
const receipt = usages.get(threadId);
// A discovered thread without a receipt has unknown usage, not zero.
@@ -440,42 +2511,288 @@ export class ScanCostTracker {
this.#options.onUsageObservation?.(observation);
}
- #reportWorkerProgress(session: SessionUsage): void {
+ #parentInventoryAdmission(
+ saved: SessionProgress,
+ command?: UnresolvedParentCommand,
+ corroboration?: { live: StreamedProgressItem; after: ProgressOrder },
+ inventoryWitness?: ProgressOrder,
+ ): "current" | "proven" | "retained" | undefined {
+ if (!isInventoryProgress(saved.update)) return undefined;
+ const newer =
+ saved.position > this.#inventoryFrontier.position ||
+ (saved.position === this.#inventoryFrontier.position &&
+ saved.markerIndex > this.#inventoryFrontier.markerIndex);
+ if (saved.duplicate || !newer) return "retained";
+ if (
+ !this.#inventoryPrecedesReview(
+ saved.position,
+ saved.markerIndex,
+ saved.projection,
+ saved,
+ )
+ )
+ return "retained";
+ const authority = this.#acceptedInventory();
+ const source = savedProgress(saved);
+ // A matched review can order an inventory after a compatible truncated
+ // prefix without identifying the live command's occurrence. That proof
+ // applies to its own inventory, not a newer independent live authority.
+ const relation =
+ authority === undefined
+ ? 0
+ : (this.#inventorySourceOrder(source, authority) ??
+ (corroboration?.live === authority.live
+ ? compareSourceOrder(source, corroboration.after)
+ : undefined) ??
+ (authority.live.after === undefined ? 0 : -1));
+ if (
+ this.#precedesParentBoundary(saved.position, saved.markerIndex) &&
+ (this.#parentInventoryBoundary?.reviewed === true ||
+ !this.#parentIsEligible(this.#parentProgress) ||
+ this.#parentProgress.progress.filesCompleted === 0 ||
+ (inventoryWitness !== undefined &&
+ (compareSourceOrder(source, inventoryWitness) ?? 0) < 0)) &&
+ relation >= 0
+ )
+ return "proven";
+ if (
+ (this.#parentIsEligible(this.#parentProgress) &&
+ this.#parentProgress.progress.filesCompleted > 0) ||
+ !this.#savedParentProgressIsCurrent(saved) ||
+ (command !== undefined &&
+ command.live === this.#acceptedParent &&
+ command.live.position === null &&
+ this.#parentProgress !== null &&
+ saved.position < command.after &&
+ this.#afterParentFrontier(saved.position, saved.markerIndex))
+ )
+ return "retained";
+ return "current";
+ }
+
+ #reportSessionProgress(
+ session: SessionUsage,
+ parent: boolean,
+ command?: UnresolvedParentCommand,
+ inventoryWitness?: ProgressOrder,
+ ): void {
if (this.#options.onProgress === undefined || session.threadId === null) {
return;
}
- for (const progress of session.progress.splice(0)) {
+ const live = this.#acceptedParent;
+ const current = this.#parentProgress;
+ const unresolvedCommandState =
+ parent &&
+ command?.live === live &&
+ live?.position === null &&
+ current !== null;
+ // Parent rows are source evidence, not a notification queue. Admission or
+ // temporary scope exclusion cannot discard an unresolved occurrence.
+ // Worker receipts are independent and retain their compact summaries below.
+ for (const saved of parent
+ ? session.progress
+ : session.progress.splice(0)) {
+ const progress = saved.update;
+ const inventory = parent
+ ? this.#parentInventoryAdmission(
+ saved,
+ command,
+ undefined,
+ inventoryWitness,
+ )
+ : undefined;
+ if (inventory === "retained") continue;
+ const inventoryMarker = inventory !== undefined;
+ const provenInventory = inventory === "proven";
+ // Source order governs equal-count phases. Fresh and parked receipts can
+ // both add coverage after a scope correction makes that coverage eligible.
+ const greaterCoverage =
+ progress.filesCompleted > this.#highestFilesCompleted;
+ if (
+ parent &&
+ !saved.duplicate &&
+ !inventoryMarker &&
+ !this.#unboundParentCopy(saved)
+ ) {
+ saved.order ??= ++this.#progressOrder;
+ this.#rememberParentFact(savedProgress(saved));
+ }
+ if (
+ unresolvedCommandState &&
+ saved.position < (command?.after ?? Infinity) &&
+ this.#afterParentFrontier(saved.position, saved.markerIndex) &&
+ !provenInventory &&
+ progress.filesCompleted <= this.#highestFilesCompleted
+ ) {
+ // Keep lossy-output ambiguity across marker-free anchors; a current
+ // state or greater coverage must supply the missing progress evidence.
+ continue;
+ }
+ if (
+ parent &&
+ !provenInventory &&
+ !greaterCoverage &&
+ !this.#savedParentProgressIsCurrent(saved)
+ )
+ continue;
+ if (saved.duplicate) {
+ if (parent && saved.completion)
+ this.#advanceParentFrontier(saved.position, saved.markerIndex);
+ continue;
+ }
const expectedFilesTotal = this.#expectedFilesTotal;
+ const parentInventory = inventoryMarker;
+ const order = (saved.order ??= ++this.#progressOrder);
if (
- (expectedFilesTotal !== undefined &&
- progress.filesTotal > expectedFilesTotal) ||
- (session.filesTotal !== null &&
+ (!parent &&
+ session.filesTotal !== null &&
progress.filesTotal !== session.filesTotal) ||
- progress.filesCompleted < session.filesCompleted
+ (!parentInventory && progress.filesCompleted < session.filesCompleted)
+ )
+ continue;
+ if (
+ !parentInventory &&
+ ((expectedFilesTotal !== undefined &&
+ progress.filesTotal > expectedFilesTotal) ||
+ (parent &&
+ progress.filesTotal >
+ (saved.scopeFilesTotal ?? Number.MAX_SAFE_INTEGER)))
) {
+ if (!parent) {
+ const pending = session.pendingWorkerProgress.get(
+ progress.filesTotal,
+ );
+ if (
+ pending === undefined ||
+ progress.filesCompleted >= pending.progress.filesCompleted
+ )
+ session.pendingWorkerProgress.set(progress.filesTotal, {
+ progress,
+ order,
+ });
+ }
continue;
}
session.filesTotal = progress.filesTotal;
session.filesCompleted = progress.filesCompleted;
- this.#workerProgress.set(session.threadId, progress.filesCompleted);
- const filesCompleted = Math.min(
- expectedFilesTotal ?? Number.MAX_SAFE_INTEGER,
- this.#workerProgress
- .values()
- .reduce((total, reviewed) => total + reviewed, 0),
- );
- if (filesCompleted < this.#highestFilesCompleted) continue;
- const update = {
+ if (!parent) session.latestWorkerProgress = { progress, order };
+ if (parentInventory && this.#highestFilesCompleted > 0) {
+ // An inventory behind admitted review changes scope without replaying
+ // its earlier phase. At zero coverage it follows normal source-ordered
+ // phase admission below, including when the inventory total changes.
+ if (
+ !this.#parentIsEligible(this.#parentProgress) ||
+ this.#parentProgress.progress.filesCompleted === 0
+ ) {
+ const candidate = {
+ progress,
+ order,
+ position: saved.position,
+ markerIndex: saved.markerIndex,
+ };
+ if (
+ this.#parentProgress === null ||
+ this.#parentProgress.progress.phase !== "discovery" ||
+ compareProgressOrder(candidate, this.#parentProgress) >= 0
+ )
+ this.#parentProgress = candidate;
+ }
+ this.#advanceParentFrontier(saved.position, saved.markerIndex);
+ this.#inventoryFrontier = savedProgress(saved);
+ this.#projectParentInventory();
+ continue;
+ }
+ // Parent markers already describe global coverage, including its workers.
+ // Only worker-local counts belong in the delegated shard sum.
+ if (!parent)
+ this.#workerProgress.set(session.threadId, progress.filesCompleted);
+ const filesCompleted = parent
+ ? progress.filesCompleted
+ : Math.min(
+ expectedFilesTotal ?? Number.MAX_SAFE_INTEGER,
+ this.#workerProgress
+ .values()
+ .reduce((total, reviewed) => total + reviewed, 0),
+ );
+ if (filesCompleted < this.#highestFilesCompleted) {
+ // A provisional worker can exceed this global parent receipt, then
+ // become ineligible when the parent's earlier inventory is recovered.
+ // Keep the parsed parent fact for that correction, without displaying
+ // a count decrease while the worker coverage remains eligible.
+ continue;
+ }
+ // A worker-local phase cannot replace eligible global parent authority
+ // when the aggregate count adds no reviewed files. Counts remain above.
+ if (
+ !parent &&
+ this.#parentIsEligible(this.#parentProgress) &&
+ filesCompleted === this.#parentProgress.progress.filesCompleted
+ )
+ continue;
+ if (parent)
+ this.#recordParentBoundary(
+ progress,
+ saved.position,
+ saved.markerIndex,
+ false,
+ saved.scopeFilesTotal,
+ );
+ // Known parent positions outrank observation order: polling can park a
+ // newer completion before an earlier live completion is displayed.
+ const displayed = this.#displayedProgress;
+ const provenance = {
+ order,
+ position: saved.position,
+ markerIndex: saved.markerIndex,
+ source: saved,
+ };
+ const newerProgress =
+ parent &&
+ displayed !== null &&
+ displayed.owner !== "worker" &&
+ filesCompleted === displayed.update.filesCompleted &&
+ compareProgressOrder(provenance, displayed) < 0
+ ? displayed
+ : null;
+ const update = newerProgress?.update ?? {
...progress,
filesCompleted,
- filesTotal:
- expectedFilesTotal ?? Math.max(progress.filesTotal, filesCompleted),
+ filesTotal: parent
+ ? progress.filesTotal
+ : (expectedFilesTotal ??
+ Math.max(progress.filesTotal, filesCompleted)),
};
- const key = `${update.phase}:${update.filesCompleted}:${update.filesTotal}`;
- if (this.#reportedProgress.has(key)) continue;
- this.#reportedProgress.add(key);
+ // Retaining a newer parent phase retains that whole receipt, including
+ // its actual inventory. Mixing an older total with its phase would discard
+ // valid parent coverage when a later inventory correction arrives.
+ if (parent && newerProgress === null)
+ this.#parentProgress = { progress, ...provenance };
+ const key = progressKey(update);
+ if (parent) {
+ // An original multipart response can expose progress absent from its
+ // concatenated native projection. Its admitted source position still
+ // prevents an older live completion from replaying over that progress.
+ this.#advanceParentFrontier(saved.position, saved.markerIndex);
+ if (parentInventory) {
+ if (newerProgress === null) saved.inventoryAdmitted = true;
+ this.#inventoryFrontier = savedProgress(saved);
+ }
+ }
this.#highestFilesCompleted = update.filesCompleted;
- this.#options.onProgress(update);
+ this.#displayedProgress =
+ newerProgress !== null
+ ? { ...newerProgress, update }
+ : {
+ update,
+ owner: parent ? "parent" : "worker",
+ ...(parent ? provenance : { order }),
+ };
+ // Distinct equal-valued receipts still advance source ownership/order.
+ if (displayed !== null && progressKey(displayed.update) === key) continue;
+ this.#options.onProgress(
+ update,
+ parent ? { reconciled: true } : undefined,
+ );
}
}
@@ -525,11 +2842,15 @@ async function readSessionUsage(
path: string,
session: SessionUsage,
repository?: string,
+ progressThread?: string,
+ throughOffset?: number | "file-size",
): Promise<void> {
if (session.unreadable) return;
let file;
try {
- if ((await stat(path)).size === session.offset) return;
+ const size = (await stat(path)).size;
+ if (size === session.offset) return;
+ if (throughOffset === "file-size") throughOffset = size;
file = await open(path, "r");
} catch (error) {
if (isMissingFile(error)) return;
@@ -537,11 +2858,13 @@ async function readSessionUsage(
}
try {
const buffer = Buffer.alloc(SESSION_READ_SIZE);
- while (true) {
+ while (throughOffset === undefined || session.offset < throughOffset) {
const { bytesRead } = await file.read(
buffer,
0,
- buffer.length,
+ throughOffset === undefined
+ ? buffer.length
+ : Math.min(buffer.length, throughOffset - session.offset),
session.offset,
);
if (bytesRead === 0) return;
@@ -552,7 +2875,12 @@ async function readSessionUsage(
.split("\n");
session.pendingLine.push(lines[0]!);
for (const line of lines.slice(1)) {
- readSessionEvent(session.pendingLine.join(""), session, repository);
+ readSessionEvent(
+ session.pendingLine.join(""),
+ session,
+ repository,
+ progressThread,
+ );
session.pendingLine = [line];
}
} catch (error) {
@@ -570,6 +2898,7 @@ function readSessionEvent(
line: string,
session: SessionUsage,
repository?: string,
+ progressThread?: string,
): void {
if (line.length === 0) return;
const event = parseJson(() => line);
@@ -608,6 +2937,7 @@ function readSessionEvent(
return;
}
session.events?.push(event);
+ const position = ++session.position;
if (event["type"] === "token_usage_record") {
const responseId = payload["response_id"];
if (
@@ -638,7 +2968,40 @@ function readSessionEvent(
return;
}
if (event["type"] === "response_item") {
- session.progress.push(...sessionProgressUpdates(payload));
+ const receipt =
+ payload["type"] === "function_call_output" ||
+ payload["type"] === "custom_tool_call_output" ||
+ payload["type"] === "local_shell_call_output";
+ const message =
+ payload["type"] === "message" &&
+ payload["role"] === "assistant" &&
+ Array.isArray(payload["content"])
+ ? payload["content"]
+ .filter(isRecord)
+ .map((part) =>
+ typeof part["text"] === "string" ? part["text"] : "",
+ )
+ .join("")
+ : null;
+ const updates = sessionProgressUpdates(payload);
+ const duplicateMessage =
+ message !== null &&
+ repeatedMessageProjection(session, digest(message), "response", updates);
+ // Code-mode notifications and the final output can share a call ID.
+ // Each appended output record remains a distinct completion receipt.
+ for (const [markerIndex, update] of (duplicateMessage
+ ? []
+ : updates
+ ).entries()) {
+ session.progress.push({
+ update,
+ position,
+ completion: false,
+ markerIndex,
+ receipt,
+ duplicate: false,
+ });
+ }
if (repository === undefined) return;
if (
payload["type"] === "reasoning" &&
@@ -722,6 +3085,55 @@ function readSessionEvent(
}
return;
}
+ if (
+ session.threadId === progressThread &&
+ event["type"] === "event_msg" &&
+ payload["type"] === "item_completed"
+ ) {
+ const item = nativeProgressItem(payload["item"]);
+ const signature = item?.signature;
+ const value = payload["item"];
+ const duplicateCompletion =
+ signature?.kind === "message" &&
+ repeatedMessageProjection(session, signature.outputDigest, "native");
+ let completion: SessionCompletion | undefined;
+ if (
+ isRecord(value) &&
+ (value["type"] === "CommandExecution" ||
+ value["type"] === "AgentMessage") &&
+ !duplicateCompletion
+ ) {
+ completion = {
+ position,
+ item: signature ?? null,
+ kind: signature?.kind,
+ };
+ session.completions.push(completion);
+ }
+ if (item !== null) {
+ const duplicate =
+ item.signature.kind === "message" &&
+ repeatedMessageProjection(
+ session,
+ item.signature.outputDigest,
+ "native",
+ item.updates,
+ );
+ for (const [markerIndex, update] of item.updates.entries()) {
+ const saved = {
+ update,
+ position,
+ completion: true,
+ markerIndex,
+ receipt: false,
+ duplicate,
+ };
+ session.progress.push(saved);
+ if (completion !== undefined && item.signature.kind === "command")
+ completion.lastCommandProgress = saved;
+ }
+ }
+ }
if (
event["type"] === "event_msg" &&
(payload["type"] === "agent_reasoning" ||
@@ -734,7 +3146,37 @@ function readSessionEvent(
payload["type"] === "agent_message" &&
typeof payload["message"] === "string"
) {
- session.progress.push(...scanProgressUpdatesFromText(payload["message"]));
+ const signature = progressSignature("message", payload["message"]);
+ const updates = scanProgressUpdatesFromText(payload["message"]);
+ const duplicate = repeatedMessageProjection(
+ session,
+ signature.outputDigest,
+ "event",
+ updates,
+ );
+ // Legacy rollouts persist the finalized message instead of the native
+ // item. It provides the same compact output signature for live matching.
+ if (
+ session.threadId === progressThread &&
+ !repeatedMessageProjection(session, signature.outputDigest, "event")
+ )
+ session.completions.push({
+ position,
+ item: signature,
+ });
+ for (const [markerIndex, update] of (duplicate
+ ? []
+ : updates
+ ).entries()) {
+ session.progress.push({
+ update,
+ position,
+ completion: false,
+ markerIndex,
+ receipt: false,
+ duplicate: false,
+ });
+ }
}
if (repository === undefined) return;
if (payload["type"] !== "agent_message") {
@@ -880,6 +3322,262 @@ function recordReasoningActivity(
session.activities.push(activity);
}
+const PERSISTED_OUTPUT_GAP =
+ "\n... command output truncated for persistence ...\n";
+
+// Native Codex 0.162.1 persists command output with a 64 KiB UTF-8 budget.
+// This signature mirrors that representation; emitted diagnostics stay intact.
+const PERSISTED_COMMAND_OUTPUT_BYTES = 64 * 1024;
+const PERSISTED_OUTPUT_GAP_BYTES = Buffer.byteLength(PERSISTED_OUTPUT_GAP);
+const PERSISTED_COMMAND_PREFIX_BYTES = Math.floor(
+ (PERSISTED_COMMAND_OUTPUT_BYTES - PERSISTED_OUTPUT_GAP_BYTES) / 2,
+);
+const PERSISTED_COMMAND_SUFFIX_BYTES =
+ PERSISTED_COMMAND_OUTPUT_BYTES -
+ PERSISTED_OUTPUT_GAP_BYTES -
+ PERSISTED_COMMAND_PREFIX_BYTES;
+
+function digest(text: string): string {
+ return createHash("sha256").update(text).digest("hex");
+}
+
+function persistedOutputDigest(text: string, fullDigest: string): string {
+ if (Buffer.byteLength(text) <= PERSISTED_COMMAND_OUTPUT_BYTES)
+ return fullDigest;
+ const bytes = Buffer.from(text);
+ let prefixEnd = PERSISTED_COMMAND_PREFIX_BYTES;
+ let suffixStart = bytes.length - PERSISTED_COMMAND_SUFFIX_BYTES;
+ while ((bytes[prefixEnd]! & 0xc0) === 0x80) prefixEnd--;
+ while ((bytes[suffixStart]! & 0xc0) === 0x80) suffixStart++;
+ return createHash("sha256")
+ .update(bytes.subarray(0, prefixEnd))
+ .update(PERSISTED_OUTPUT_GAP)
+ .update(bytes.subarray(suffixStart))
+ .digest("hex");
+}
+
+function isInventoryProgress(progress: ScanProgress): boolean {
+ return progress.phase === "discovery" && progress.filesCompleted === 0;
+}
+
+function progressSignature(
+ kind: ProgressItem["kind"],
+ text: string,
+ command?: readonly string[],
+): ProgressItem {
+ const outputDigest = digest(text);
+ return {
+ kind,
+ outputDigest,
+ persistedOutputDigest:
+ kind === "command"
+ ? persistedOutputDigest(text, outputDigest)
+ : outputDigest,
+ ...(command === undefined
+ ? {}
+ : { commandDigest: digest(JSON.stringify(command)) }),
+ };
+}
+
+function repeatedMessageProjection(
+ session: SessionUsage,
+ textDigest: string,
+ projection: "native" | "event" | "response",
+ updates?: readonly ScanProgress[],
+): boolean {
+ if (updates?.length === 0) return false;
+ // Completion matching counts every native/legacy message, even without
+ // progress. Keep those occurrences separate from parsed progress copies:
+ // multipart responses can recover updates absent from their native copy.
+ const key =
+ updates === undefined
+ ? textDigest
+ : `${textDigest}:${digest(JSON.stringify(updates))}`;
+ if (updates !== undefined) {
+ let queue = session.messageProgressProjections.get(key);
+ if (queue === undefined) {
+ queue = { occurrences: [], next: { native: 0, event: 0, response: 0 } };
+ session.messageProgressProjections.set(key, queue);
+ }
+ // Copies retain their order within each projection. A missing earlier copy
+ // cannot consume an identical message after that projection has advanced.
+ // These ordinals identify progress copies only, never completion positions.
+ while (queue.next[projection] < queue.occurrences.length) {
+ const order = queue.occurrences[queue.next[projection]++]!;
+ if (order <= session.messageProgressFrontiers[projection]) continue;
+ session.messageProgressFrontiers[projection] = order;
+ return true;
+ }
+ const order = ++session.messageProgressOrder;
+ queue.occurrences.push(order);
+ queue.next[projection] = queue.occurrences.length;
+ session.messageProgressFrontiers[projection] = order;
+ return false;
+ }
+ let counts = session.messageProjections.get(key);
+ if (counts === undefined) {
+ counts = { native: 0, event: 0, response: 0 };
+ session.messageProjections.set(key, counts);
+ }
+ const previous = Math.max(counts.native, counts.event, counts.response);
+ counts[projection]++;
+ return counts[projection] <= previous;
+}
+
+function progressKey(progress: ScanProgress): string {
+ return `${progress.phase}:${progress.filesCompleted}:${progress.filesTotal}`;
+}
+
+function streamedProgressItem(
+ event: Readonly<Record<string, unknown>>,
+): ProgressItem | null {
+ const item = event["item"];
+ if (!isRecord(item)) return null;
+ if (item["type"] === "agent_message" && typeof item["text"] === "string")
+ return progressSignature("message", item["text"]);
+ if (
+ item["type"] !== "command_execution" ||
+ typeof item["aggregated_output"] !== "string" ||
+ typeof item["command"] !== "string"
+ )
+ return null;
+ const command = splitCommand(item["command"]);
+ return command === null
+ ? null
+ : progressSignature("command", item["aggregated_output"], command);
+}
+
+function nativeProgressItem(value: unknown) {
+ if (!isRecord(value)) return null;
+ let kind: ProgressItem["kind"];
+ let text: string;
+ let command: string[] | undefined;
+ if (value["type"] === "AgentMessage" && Array.isArray(value["content"])) {
+ kind = "message";
+ text = value["content"]
+ .filter(
+ (part): part is { text: string } =>
+ isRecord(part) &&
+ part["type"] === "Text" &&
+ typeof part["text"] === "string",
+ )
+ .map((part) => part.text)
+ .join("");
+ } else if (
+ value["type"] === "CommandExecution" &&
+ typeof value["aggregated_output"] === "string" &&
+ Array.isArray(value["command"]) &&
+ value["command"].every((arg): arg is string => typeof arg === "string")
+ ) {
+ kind = "command";
+ text = value["aggregated_output"];
+ command = value["command"];
+ } else return null;
+ let progressText = text;
+ if (kind === "command") {
+ const bytes = Buffer.from(text);
+ // Native UTF-8 boundary adjustment can shorten each fragment by up to
+ // three bytes. An earlier literal sentinel is ordinary command output.
+ const gap = bytes.indexOf(
+ PERSISTED_OUTPUT_GAP,
+ PERSISTED_COMMAND_PREFIX_BYTES - 3,
+ );
+ const suffixBytes = bytes.length - gap - PERSISTED_OUTPUT_GAP_BYTES;
+ if (
+ gap !== -1 &&
+ gap <= PERSISTED_COMMAND_PREFIX_BYTES &&
+ suffixBytes >= PERSISTED_COMMAND_SUFFIX_BYTES - 3 &&
+ suffixBytes <= PERSISTED_COMMAND_SUFFIX_BYTES
+ ) {
+ // Complete original prefix lines have known fence state. The gap inserts
+ // its own newline, so the partial prefix line and tail remain unproven.
+ // Literal text at these exact boundaries is indistinguishable on disk.
+ const prefix = bytes.subarray(0, gap).toString("utf8");
+ progressText = prefix.slice(0, prefix.lastIndexOf("\n") + 1);
+ }
+ }
+ return {
+ signature: progressSignature(kind, text, command),
+ updates: scanProgressUpdatesFromText(progressText),
+ };
+}
+
+function progressItemKey(item: ProgressItem, persisted = false): string {
+ return `${item.kind}:${item.commandDigest ?? ""}:${persisted ? item.persistedOutputDigest : item.outputDigest}`;
+}
+
+function progressItemKeys(item: ProgressItem): string[] {
+ const keys = [progressItemKey(item)];
+ if (item.outputDigest !== item.persistedOutputDigest)
+ keys.push(progressItemKey(item, true));
+ return keys;
+}
+
+// Min-heap keeps compatible live occurrences ordered without rescanning the
+// unmatched prefix or sorting every completion batch.
+function insertIndex(heap: number[], index: number): void {
+ let child = heap.length;
+ heap.push(index);
+ while (child > 0) {
+ const parent = (child - 1) >>> 1;
+ if (heap[parent]! <= index) break;
+ heap[child] = heap[parent]!;
+ child = parent;
+ }
+ heap[child] = index;
+}
+
+function takeFirstIndex(heap: number[]): number {
+ const first = heap[0]!;
+ const last = heap.pop()!;
+ if (heap.length === 0) return first;
+ let parent = 0;
+ while (parent * 2 + 1 < heap.length) {
+ let child = parent * 2 + 1;
+ if (child + 1 < heap.length && heap[child + 1]! < heap[child]!) child++;
+ if (last <= heap[child]!) break;
+ heap[parent] = heap[child]!;
+ parent = child;
+ }
+ heap[parent] = last;
+ return first;
+}
+
+/** Decode the quoted argv rendering emitted by native command completions. */
+function splitCommand(command: string): string[] | null {
+ const words: string[] = [];
+ let word = "";
+ let started = false;
+ let quote: "'" | '"' | null = null;
+ for (let index = 0; index < command.length; index++) {
+ const character = command[index]!;
+ if (character === "\\" && quote !== "'") {
+ const next = command[++index];
+ if (next === undefined) return null;
+ if (quote === '"' && !["$", "`", '"', "\\", "\n"].includes(next))
+ word += "\\";
+ if (next !== "\n") word += next;
+ started = true;
+ } else if (quote !== null) {
+ if (character === quote) quote = null;
+ else word += character;
+ } else if (character === "'" || character === '"') {
+ quote = character;
+ started = true;
+ } else if (" \t\r\n".includes(character)) {
+ if (started) words.push(word);
+ word = "";
+ started = false;
+ } else {
+ word += character;
+ started = true;
+ }
+ }
+ if (quote !== null) return null;
+ if (started) words.push(word);
+ return words;
+}
+
function sessionProgressUpdates(
payload: Readonly<Record<string, unknown>>,
): ScanProgress[] {
diff --git a/sdk/typescript/tests-ts/api.test.ts b/sdk/typescript/tests-ts/api.test.ts
index 263d3f97f..0d769c920 100644
--- a/sdk/typescript/tests-ts/api.test.ts
+++ b/sdk/typescript/tests-ts/api.test.ts
@@ -1,5 +1,6 @@
import { readReviewState } from "./support/review-state.js";
import { once } from "node:events";
+import { jsonLines } from "./support/json.js";
import { createServer, type Socket } from "node:net";
import {
appendFile,
@@ -68,7 +69,11 @@ import {
resolveCodexProfile,
type JsonObject,
} from "../src/config.js";
-import { estimateScanCost, type ScanCost } from "../src/cost.js";
+import {
+ estimateScanCost,
+ ScanCostTracker,
+ type ScanCost,
+} from "../src/cost.js";
import { resolveCodexCommand, runWorkbench } from "../src/runtime.js";
import * as runtime from "../src/runtime.js";
import * as ownerArtifacts from "../src/scan-owner-suggestions.js";
@@ -103,7 +108,12 @@ import {
} from "./support/api-events.js";
import { createApiTestFixtures } from "./support/temporary-directories.js";
import { runTestInSubprocess } from "./support/test-subprocess.js";
-import { writeSession as writeUsageSession } from "./support/usage-rollout.js";
+import {
+ progressMarker,
+ nativeCommand,
+ completedCommand,
+ writeSession as writeUsageSession,
+} from "./support/usage-rollout.js";
import { importScan } from "../src/import-scan.js";
import { restoreScanKnowledge, scanInputIdentity } from "../src/scan-inputs.js";
import { VERSION } from "../src/version.js";
@@ -112,6 +122,23 @@ import { pythonExecutable, nodeCommand, gitText } from "./support/shell.js";
import { fail, rejecting, throwing } from "./support/errors.js";
import { mockFs, restoreFs } from "./support/module-mocks.js";
+async function registerEightFileScan(
+ _options: unknown,
+ args: readonly string[],
+ input?: string,
+): Promise<JsonObject> {
+ return args[0] === "register-cli-scan"
+ ? { ...mockScanRegistration(args, input), scopeFileCount: 8 }
+ : mockWorkbench(args, input);
+}
+
+// Exact ASCII fixture for the pinned native 64 KiB persistence representation.
+const commandHead = "h".repeat(32_743);
+const commandTail = "t".repeat(32_743);
+const persistedCommandOutput = `${commandHead}\n... command output truncated for persistence ...\n${commandTail}`;
+const commandOutput = (middle: string) =>
+ `${commandHead}\n${middle}\n${commandTail}`;
+
const EXAMPLE = join(PLUGIN_ROOT, "examples", "legacy-completed-scan");
const { cleanup, temporaryDirectory } = createApiTestFixtures();
afterEach(cleanup);
@@ -3404,6 +3431,7 @@ if __name__ == "__main__":
if (scenario === "late marker") {
expect(updates.at(-1)).toEqual({
...updates[1]!,
+ phase: "discovery",
filesCompleted: 3,
});
}
@@ -3991,20 +4019,14 @@ if __name__ == "__main__":
);
});
if (itemType === "command_execution") {
- yield {
- type: "item.completed",
- item: {
- id: "inventory-command",
- type: "command_execution",
- command: "review the files in the inventory",
- aggregated_output: [
- 'CODEX_SECURITY_SCAN_PROGRESS {"phase":"discovery","filesCompleted":3,"filesTotal":5000}',
- ...texts,
- ].join("\n"),
- exit_code: 0,
- status: "completed",
- },
- };
+ yield completedCommand(
+ "review the files in the inventory",
+ [
+ 'CODEX_SECURITY_SCAN_PROGRESS {"phase":"discovery","filesCompleted":3,"filesTotal":5000}',
+ ...texts,
+ ].join("\n"),
+ "inventory-command",
+ );
} else {
for (const [index, text] of texts.entries()) {
yield {
@@ -4163,7 +4185,7 @@ if __name__ == "__main__":
filesTotal: 1_258,
reviewItems: { completed: 0, total: 0 },
},
- ...[3, 1_249, 1_249].map<ScanProgress>((filesCompleted) => ({
+ ...[3, 1_249].map<ScanProgress>((filesCompleted) => ({
phase: parentDispatch ? "validation" : "discovery",
filesCompleted,
filesTotal: 1_258,
@@ -4191,6 +4213,10053 @@ if __name__ == "__main__":
},
);
+ test.each([
+ [
+ "both phases streamed",
+ [0, 1],
+ [
+ { phase: "discovery", filesCompleted: 8, filesTotal: 8 },
+ { phase: "validation", filesCompleted: 8, filesTotal: 8 },
+ ],
+ [0, 1],
+ false,
+ ],
+ [
+ "newer phase omitted from the preview",
+ [0, 1],
+ [
+ { phase: "discovery", filesCompleted: 8, filesTotal: 8 },
+ { phase: "validation", filesCompleted: 8, filesTotal: 8 },
+ ],
+ [0],
+ false,
+ ],
+ [
+ "multipart native marker",
+ [1],
+ [
+ { phase: "discovery", filesCompleted: 8, filesTotal: 8 },
+ { phase: "validation", filesCompleted: 8, filesTotal: 8 },
+ ],
+ [0],
+ false,
+ ],
+ [
+ "older tool phase",
+ [1],
+ [
+ { phase: "discovery", filesCompleted: 8, filesTotal: 8 },
+ { phase: "validation", filesCompleted: 8, filesTotal: 8 },
+ { phase: "attack_path", filesCompleted: 8, filesTotal: 8 },
+ ],
+ [0, 1, 2],
+ false,
+ ],
+ [
+ "older inventory",
+ [1],
+ [
+ { phase: "discovery", filesCompleted: 0, filesTotal: 8 },
+ { phase: "discovery", filesCompleted: 0, filesTotal: 9 },
+ { phase: "discovery", filesCompleted: 1, filesTotal: 9 },
+ ],
+ [0, 1, 2],
+ false,
+ ],
+ [
+ "truncated streamed marker",
+ [0],
+ [
+ { phase: "discovery", filesCompleted: 1, filesTotal: 8 },
+ { phase: "discovery", filesCompleted: 2, filesTotal: 8 },
+ ],
+ [1],
+ false,
+ ],
+ [
+ "truncated streamed inventory",
+ [1],
+ [
+ { phase: "discovery", filesCompleted: 0, filesTotal: 8 },
+ { phase: "discovery", filesCompleted: 0, filesTotal: 9 },
+ { phase: "discovery", filesCompleted: 1, filesTotal: 9 },
+ ],
+ [0, 2],
+ false,
+ ],
+ [
+ "worker already reported the parent phase",
+ [1],
+ [
+ { phase: "discovery", filesCompleted: 8, filesTotal: 8 },
+ { phase: "validation", filesCompleted: 8, filesTotal: 8 },
+ ],
+ [0, 1],
+ true,
+ ],
+ ] as const)(
+ "retains the latest progress across stream and rollout delivery: %s",
+ async (_scenario, streamed, progress, persisted, workerFirst) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const sessionEvents: ScanSessionEvent[] = [];
+ const workerReady = Promise.withResolvers<void>();
+ const markerTexts = progress.map(
+ (update) => "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(update),
+ );
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const rollout = await writeUsageSession(codexHome, "thread-1", {
+ input_tokens: 100,
+ output_tokens: 10,
+ });
+ if (workerFirst) {
+ const worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {
+ input_tokens: 100,
+ output_tokens: 10,
+ },
+ { parent: "thread-1" },
+ );
+ await appendFile(
+ worker,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ output: [{ type: "input_text", text: markerTexts[1] }],
+ },
+ }) + "\n",
+ );
+ }
+ async function* markers(): AsyncGenerator<ThreadEvent> {
+ if (workerFirst) await workerReady.promise;
+ for (const index of streamed) {
+ yield {
+ type: "item.completed",
+ item: {
+ id: `parent-progress-${index}`,
+ type: "agent_message",
+ text: markerTexts[index]!,
+ },
+ };
+ }
+ // Native item completions retain the order even when the separate
+ // response-item preview omits a streamed marker.
+ const saved = progress.flatMap((_update, index) => [
+ ...(streamed.includes(index as never)
+ ? [
+ {
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ id: `native-${index}`,
+ content:
+ _scenario === "multipart native marker"
+ ? [
+ {
+ type: "Text",
+ text: markerTexts[index]!.slice(0, 35),
+ },
+ {
+ type: "Text",
+ text: markerTexts[index]!.slice(35),
+ },
+ ]
+ : [{ type: "Text", text: markerTexts[index] }],
+ },
+ },
+ },
+ ]
+ : []),
+ ...(persisted.includes(index as never)
+ ? [
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ status: "completed",
+ output: [
+ { type: "input_text", text: markerTexts[index] },
+ ],
+ },
+ },
+ ]
+ : []),
+ ]);
+ await appendFile(
+ rollout,
+ saved.map((event) => JSON.stringify(event)).join("\n") + "\n",
+ );
+ }
+ return { events: completedEvents("thread-1", markers()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => {
+ updates.push(update);
+ // Worker counts arrive before this fixture releases the parent phase.
+ if (update.filesCompleted === 8 && update.filesTotal === 8)
+ workerReady.resolve();
+ },
+ onSessionEvent: (event) => sessionEvents.push(event),
+ });
+ expect(updates[0]).toEqual({
+ phase: "preflight",
+ filesCompleted: 0,
+ filesTotal: 8,
+ });
+ expect(updates.at(-1)).toEqual(progress.at(-1));
+ for (let index = 1; index < updates.length; index++) {
+ expect(updates[index]).not.toEqual(updates[index - 1]);
+ expect(updates[index]!.filesCompleted).toBeGreaterThanOrEqual(
+ updates[index - 1]!.filesCompleted,
+ );
+ }
+ expect(
+ sessionEvents.filter(
+ ({ threadId, event }) =>
+ threadId === "thread-1" &&
+ (event["payload"] as Record<string, unknown> | undefined)?.[
+ "type"
+ ] === "custom_tool_call_output",
+ ),
+ ).toHaveLength(persisted.length);
+ } finally {
+ clearInterval(keepAlive);
+ await client.close();
+ }
+ },
+ );
+
+ test.each(
+ (["legacy", "paginated"] as const).flatMap((mode) =>
+ [false, true].map(
+ (savedReviewFirst) => [mode, savedReviewFirst] as const,
+ ),
+ ),
+ )(
+ "retains repeated inventory before saved review (%s, saved review first: %p)",
+ async (mode, savedReviewFirst) => {
+ const total = 8;
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const expanded = Promise.withResolvers<void>(),
+ inventory = Promise.withResolvers<void>(),
+ review = Promise.withResolvers<void>(),
+ workerSeen = Promise.withResolvers<void>();
+ const marker = (count: number, filesTotal: number) =>
+ `CODEX_SECURITY_SCAN_PROGRESS ${JSON.stringify({ phase: "discovery", filesCompleted: count, filesTotal })}`;
+ const saved = (id: string, text: string) => [
+ {
+ type: "event_msg",
+ payload:
+ mode === "legacy"
+ ? { type: "agent_message", message: text }
+ : {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ id,
+ content: [{ type: "Text", text }],
+ },
+ },
+ },
+ {
+ type: "response_item",
+ payload: {
+ type: "message",
+ id,
+ role: "assistant",
+ content: [{ type: "output_text", text }],
+ },
+ },
+ ];
+ const live = (id: string, text: string): ThreadEvent => ({
+ type: "item.completed",
+ item: { type: "agent_message", id, text },
+ });
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const parent = await writeUsageSession(codexHome, "thread-1", {});
+ const append = async (...rows: unknown[]) =>
+ appendFile(
+ parent,
+ rows
+ .flat()
+ .map((row) => JSON.stringify(row))
+ .join("\n") + "\n",
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ yield live("first-inventory", marker(0, 8));
+ await append(
+ saved("first-inventory", marker(0, 8)),
+ saved("expanded-inventory", marker(0, 9)),
+ );
+ await expanded.promise;
+ // The SDK can deliver a review while older persisted inventory is still
+ // being flushed. Its saved position becomes known only in the next poll.
+ yield live("parent-review", marker(1, total));
+ await append(
+ saved("final-inventory", marker(0, total)),
+ ...(savedReviewFirst
+ ? [saved("parent-review", marker(1, total))]
+ : []),
+ );
+ await inventory.promise;
+ if (!savedReviewFirst)
+ await append(saved("parent-review", marker(1, total)));
+ await review.promise;
+ const worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ await appendFile(
+ worker,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "oversized-worker",
+ output: marker(9, 9),
+ },
+ }) + "\n",
+ );
+ await workerSeen.promise;
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ const keepAlive = setInterval(() => {}, 1000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ onSessionEvent: ({ event }) => {
+ const p = event["payload"] as { id?: string; call_id?: string };
+ if (p?.id === "expanded-inventory") expanded.resolve();
+ if (p?.id === "final-inventory") inventory.resolve();
+ if (p?.id === "parent-review") review.resolve();
+ if (p?.call_id === "oversized-worker") workerSeen.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: 1,
+ filesTotal: total,
+ });
+ expect(updates.some((update) => update.filesCompleted === 9)).toBe(
+ false,
+ );
+ } finally {
+ clearInterval(keepAlive);
+ expanded.resolve();
+ inventory.resolve();
+ review.resolve();
+ workerSeen.resolve();
+ await client.close();
+ }
+ },
+ );
+
+ test.each(
+ (["legacy", "paginated"] as const).flatMap((mode) =>
+ (
+ [
+ "live-first",
+ "saved-first",
+ "poll-between",
+ "omitted-inventory-saved-review",
+ "omitted-inventory-live-review",
+ "later-inventory",
+ "oversized-review",
+ "saved-only",
+ "saved-only-stale-live",
+ "inventory-phase",
+ "shrink-saved-review",
+ "shrink-delayed-inventory",
+ ] as const
+ ).map((delivery) => [mode, delivery] as const),
+ ),
+ )(
+ "preserves proven inventory across legacy delivery gaps (%s, %s)",
+ async (mode, delivery) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const inventoryRead = Promise.withResolvers<void>();
+ const boundaryRead = Promise.withResolvers<void>();
+ const completeRead = Promise.withResolvers<void>();
+ const savedFirst = delivery !== "live-first";
+ const completeFirst = delivery === "omitted-inventory-live-review";
+ const shrinking = delivery.startsWith("shrink-");
+ const inventoryPhase = delivery === "inventory-phase";
+ const currentTotal = shrinking ? 7 : 9;
+ const total =
+ delivery === "later-inventory" || shrinking
+ ? 7
+ : delivery === "oversized-review"
+ ? 10
+ : 9;
+ const old = progressMarker(
+ inventoryPhase ? "threat_model" : "discovery",
+ 0,
+ 8,
+ );
+ const current = progressMarker("discovery", 0, currentTotal);
+ const savedOnly = delivery.startsWith("saved-only");
+ const finalPhase =
+ delivery === "saved-only-stale-live" || shrinking
+ ? "validation"
+ : "discovery";
+ const complete = progressMarker(
+ shrinking ? "discovery" : finalPhase,
+ total,
+ total,
+ );
+ const stale = progressMarker("attack_path", 9, 9);
+ const savedMessage = (text: string) => [
+ {
+ type: "event_msg",
+ payload:
+ mode === "legacy"
+ ? { type: "agent_message", message: text }
+ : {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [{ type: "Text", text }],
+ },
+ },
+ },
+ {
+ type: "response_item",
+ payload: {
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text }],
+ },
+ },
+ ];
+ const liveMessage = (id: string, text: string): ThreadEvent => ({
+ type: "item.completed",
+ item: { id, type: "agent_message", text },
+ });
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const rollout = await writeUsageSession(codexHome, "thread-1", {});
+ const persisted = [
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "inventory",
+ output: old,
+ },
+ },
+ ...(mode === "paginated" ? [nativeCommand("inventory", old)] : []),
+ // Legacy saves the agent-message event before its raw response copy,
+ // and does not save the command completion delivered to the SDK.
+ ...savedMessage(current),
+ ];
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ if (inventoryPhase) {
+ await appendFile(rollout, jsonLines(savedMessage(old)) + "\n");
+ yield liveMessage("earlier-phase", old);
+ await boundaryRead.promise;
+ await appendFile(
+ rollout,
+ jsonLines(savedMessage(current)) + "\n",
+ );
+ await inventoryRead.promise;
+ yield liveMessage("current-inventory", current);
+ return;
+ }
+ if (savedFirst) {
+ await appendFile(rollout, jsonLines(persisted) + "\n");
+ await inventoryRead.promise;
+ }
+ yield completedCommand("inventory", old);
+ if (delivery === "poll-between") {
+ await appendFile(
+ rollout,
+ jsonLines(savedMessage("Synthetic poll boundary.")) + "\n",
+ );
+ await boundaryRead.promise;
+ }
+ if (
+ ["live-first", "saved-first", "poll-between"].includes(delivery)
+ )
+ yield liveMessage("current-inventory", current);
+ if (!savedFirst)
+ await appendFile(rollout, jsonLines(persisted) + "\n");
+ if (delivery === "later-inventory")
+ await appendFile(
+ rollout,
+ jsonLines(savedMessage(progressMarker("discovery", 0, 7))) +
+ "\n",
+ );
+ if (completeFirst) yield liveMessage("review-complete", complete);
+ await appendFile(
+ rollout,
+ jsonLines([
+ ...(delivery === "saved-only-stale-live"
+ ? savedMessage(stale)
+ : []),
+ ...savedMessage(complete),
+ ]) + "\n",
+ );
+ if (savedOnly) {
+ await completeRead.promise;
+ if (delivery === "saved-only-stale-live")
+ yield liveMessage("older-review", stale);
+ await appendFile(
+ rollout,
+ jsonLines(savedMessage("Scan finished.")) + "\n",
+ );
+ yield liveMessage("final-summary", "Scan finished.");
+ } else if (!completeFirst) {
+ if (delivery === "omitted-inventory-saved-review" || shrinking)
+ await completeRead.promise;
+ if (shrinking) {
+ if (delivery === "shrink-delayed-inventory")
+ yield liveMessage("current-inventory", current);
+ const final = progressMarker(finalPhase, total, total);
+ await appendFile(
+ rollout,
+ jsonLines(savedMessage(final)) + "\n",
+ );
+ yield liveMessage("final-review", final);
+ } else yield liveMessage("review-complete", complete);
+ }
+ if (delivery === "later-inventory") {
+ await completeRead.promise;
+ const oversized = progressMarker("discovery", 9, 9);
+ await appendFile(
+ rollout,
+ jsonLines(savedMessage(oversized)) + "\n",
+ );
+ yield liveMessage("oversized-review", oversized);
+ }
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onSessionEvent: ({ event }) => {
+ const payload = event["payload"] as {
+ content?: { text?: string }[];
+ };
+ const text = payload?.content?.[0]?.text;
+ if (text === complete) completeRead.resolve();
+ if (
+ text === "Synthetic poll boundary." ||
+ (inventoryPhase && text === old)
+ )
+ boundaryRead.resolve();
+ },
+ onProgress: (update) => {
+ updates.push(update);
+ if (
+ update.filesTotal === currentTotal &&
+ update.filesCompleted === 0
+ )
+ inventoryRead.resolve();
+ },
+ });
+ if (delivery === "oversized-review") {
+ expect(updates.some((update) => update.filesCompleted === 10)).toBe(
+ false,
+ );
+ expect(updates.at(-1)?.filesCompleted).toBe(0);
+ } else
+ expect(updates.at(-1)).toEqual({
+ phase: finalPhase,
+ filesCompleted: inventoryPhase ? 0 : total,
+ filesTotal: total,
+ });
+ if (delivery === "saved-only-stale-live") {
+ const recovered = updates.findIndex(
+ (update) => update.phase === "validation",
+ );
+ expect(recovered).toBeGreaterThanOrEqual(0);
+ expect(
+ updates
+ .slice(recovered)
+ .every((update) => update.phase !== "attack_path"),
+ ).toBe(true);
+ }
+ } finally {
+ clearInterval(keepAlive);
+ inventoryRead.resolve();
+ boundaryRead.resolve();
+ completeRead.resolve();
+ await client.close();
+ }
+ },
+ );
+
+ test.each(
+ (
+ [
+ "admitted",
+ "selected-live",
+ "active-batch",
+ "fresh-batch",
+ "parent-only",
+ "accepted-eligibility",
+ ] as const
+ ).flatMap((family) =>
+ [false, true].flatMap((early) =>
+ (
+ [
+ ["validation", "discovery"],
+ ["discovery", "attack_path"],
+ ] as const
+ ).map(
+ ([parentPhase, workerPhase]) =>
+ [family, early, parentPhase, workerPhase] as const,
+ ),
+ ),
+ ),
+ )(
+ "retains parent facts across admission and batch boundaries (%s, early: %p, parent: %s, worker: %s)",
+ async (family, early, parentPhase, workerPhase) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const seen = new Map<
+ string,
+ ReturnType<typeof Promise.withResolvers<void>>
+ >();
+ const wait = (id: string) => {
+ if (!seen.has(id)) seen.set(id, Promise.withResolvers<void>());
+ return seen.get(id)!;
+ };
+ let path = "",
+ pause = false;
+ const closeEntered = Promise.withResolvers<void>(),
+ release = Promise.withResolvers<void>();
+ const originalOpen = fsPromises.open;
+ const opening = spyOn(fsPromises, "open").mockImplementation((async (
+ ...args: Parameters<typeof originalOpen>
+ ) => {
+ const file = await originalOpen(...args);
+ if (String(args[0]) !== path || !pause) return file;
+ const close = file.close.bind(file);
+ file.close = async () => {
+ if (pause) {
+ pause = false;
+ closeEntered.resolve();
+ await release.promise;
+ }
+ await close();
+ };
+ return file;
+ }) as typeof originalOpen);
+
+ const custom = (id: string, text: string) => ({
+ type: "response_item",
+ payload: { type: "custom_tool_call_output", call_id: id, output: text },
+ });
+ const native = (command: string, output: string) =>
+ nativeCommand(command, output);
+ const live = (command: string, output: string): ThreadEvent =>
+ completedCommand(command, output);
+ const append = async (file: string, rows: readonly unknown[]) => {
+ await appendFile(
+ file,
+ rows.map((x) => JSON.stringify(x)).join("\n") + "\n",
+ );
+ };
+ const worker = async (id: string, count: number, total: number) => {
+ const file = await writeUsageSession(
+ codexHome,
+ id,
+ {},
+ { parent: "thread-1" },
+ );
+ await append(file, [
+ custom(id, progressMarker(workerPhase, count, total)),
+ ]);
+ await wait(id).promise;
+ };
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: async (
+ _options: unknown,
+ args: readonly string[],
+ input?: string,
+ ): Promise<JsonObject> =>
+ args[0] === "register-cli-scan"
+ ? {
+ ...mockScanRegistration(args, input),
+ scopeFileCount:
+ family === "parent-only"
+ ? 9
+ : family === "selected-live"
+ ? 4
+ : 8,
+ }
+ : mockWorkbench(args, input),
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ path = await writeUsageSession(codexHome, "thread-1", {});
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await wait("metadata").promise;
+ if (family === "accepted-eligibility") {
+ await worker("first", 4, 4);
+ const prefix = [
+ native("inventory", progressMarker("discovery", 0, 5)),
+ native("eligible", progressMarker(parentPhase, 4, 5)),
+ ];
+ if (early) {
+ await append(path, prefix);
+ await wait("eligible").promise;
+ }
+ // Native can deliver events after a persistence error, then retry
+ // buffered writes. Recover a prefix before the next live receipt
+ // gains saved provenance. Later retries must also remain eligible.
+ yield live("eligible", progressMarker(parentPhase, 4, 5));
+ yield live("ineligible", progressMarker(workerPhase, 4, 7));
+ yield live("last-parent", progressMarker(parentPhase, 8, 8));
+ if (!early) {
+ await append(path, prefix);
+ await wait("eligible").promise;
+ }
+ await append(path, [
+ native("ineligible", progressMarker(workerPhase, 4, 7)),
+ ]);
+ await wait("ineligible").promise;
+ await append(path, [
+ native("last-parent", progressMarker(parentPhase, 8, 8)),
+ ]);
+ await wait("last-parent").promise;
+ } else if (family === "parent-only") {
+ // Inventory may be absent from SDK delivery; all native records
+ // are durable before either review is delivered live.
+ // Start a real read: unchanged logs are skipped by the tracker.
+ pause = !early;
+ if (!early) {
+ await appendFile(path, "\n");
+ await closeEntered.promise;
+ }
+ await append(path, [
+ native("inventory", progressMarker("discovery", 0, 8)),
+ native("eligible", progressMarker(parentPhase, 4, 8)),
+ native("last-parent", progressMarker(workerPhase, 6, 9)),
+ ]);
+ if (early) await wait("last-parent").promise;
+ yield live("eligible", progressMarker(parentPhase, 4, 8));
+ yield live("last-parent", progressMarker(workerPhase, 6, 9));
+ release.resolve();
+ await wait("last-parent").promise;
+ } else if (family === "fresh-batch") {
+ await worker("first", 3, 3);
+ await worker("second", 1, 8);
+ pause = !early;
+ if (!early) {
+ await appendFile(path, "\n");
+ await closeEntered.promise;
+ }
+ await append(path, [
+ custom("inventory6", progressMarker("discovery", 0, 6)),
+ custom("eligible", progressMarker(parentPhase, 3, 6)),
+ ]);
+ if (early) await wait("eligible").promise;
+ await append(path, [
+ native("last-parent", progressMarker(workerPhase, 4, 8)),
+ ]);
+ yield live("last-parent", progressMarker(workerPhase, 4, 8));
+ release.resolve();
+ await wait("last-parent").promise;
+ } else if (family === "admitted") {
+ await append(path, [native("inventory", persistedCommandOutput)]);
+ if (early) {
+ yield live(
+ "inventory",
+ commandOutput(progressMarker("discovery", 0, 6)),
+ );
+ await wait("scope6").promise;
+ }
+ await worker("first", 3, 3);
+ await append(path, [
+ custom("eligible", progressMarker(parentPhase, 3, 6)),
+ ]);
+ await wait("eligible").promise;
+ await append(path, [
+ custom("oversized", progressMarker(parentPhase, 4, 8)),
+ ]);
+ await wait("oversized").promise;
+ if (!early)
+ yield live(
+ "inventory",
+ commandOutput(progressMarker("discovery", 0, 6)),
+ );
+ } else if (family === "selected-live") {
+ const inventories = [
+ custom("inventory8", progressMarker("discovery", 0, 8)),
+ custom("inventory6", progressMarker("discovery", 0, 6)),
+ ];
+ if (early) {
+ await append(path, inventories);
+ await wait("inventory6").promise;
+ await wait("scope6").promise;
+ } else {
+ pause = true;
+ await appendFile(path, "\n");
+ await closeEntered.promise;
+ }
+ await append(path, [
+ ...(early ? [] : inventories),
+ native("first-parent", persistedCommandOutput),
+ native("last-parent", persistedCommandOutput),
+ ]);
+ yield live(
+ "first-parent",
+ commandOutput(progressMarker(workerPhase, 3, 8)),
+ );
+ yield live(
+ "last-parent",
+ commandOutput(progressMarker(parentPhase, 3, 6)),
+ );
+ release.resolve();
+ await wait("last-parent").promise;
+ } else {
+ if (early) {
+ await append(path, [
+ custom("inventory6", progressMarker("discovery", 0, 6)),
+ ]);
+ await wait("scope6").promise;
+ }
+ await worker("first", 3, 3);
+ await worker("second", 1, 8);
+ pause = !early;
+ await append(path, [
+ ...(early
+ ? []
+ : [custom("inventory6", progressMarker("discovery", 0, 6))]),
+ custom("eligible", progressMarker(parentPhase, 3, 6)),
+ ]);
+ if (!early) await closeEntered.promise;
+ else await wait("eligible").promise;
+ await append(path, [
+ native("last-parent", progressMarker(parentPhase, 4, 8)),
+ ]);
+ yield live("last-parent", progressMarker(parentPhase, 4, 8));
+ release.resolve();
+ await wait("last-parent").promise;
+ }
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ const keepAlive = setInterval(() => {}, 1000);
+ try {
+ await client.run(repository, {
+ onProgress: (p) => {
+ updates.push(p);
+ if (p.filesTotal === 6 && p.filesCompleted === 0)
+ wait("scope6").resolve();
+ },
+ onSessionEvent: ({ event, threadId }) => {
+ if (event["type"] === "session_meta" && threadId === "thread-1")
+ wait("metadata").resolve();
+ const payload = event["payload"] as {
+ call_id?: string;
+ item?: { command?: string[] };
+ };
+ const id = payload?.call_id ?? payload?.item?.command?.[0];
+ if (id) wait(id).resolve();
+ },
+ });
+ if (family === "accepted-eligibility") {
+ const recovered = updates.findIndex(
+ (p) =>
+ p.filesTotal === 5 &&
+ p.filesCompleted === 4 &&
+ p.phase === parentPhase,
+ );
+ expect(recovered).toBeGreaterThanOrEqual(0);
+ // Worker fallback before parent recovery remains valid. Later replay
+ // must not replace the recovered phase with an ineligible receipt.
+ expect(
+ updates
+ .slice(recovered)
+ .filter((p) => p.filesTotal === 5 && p.filesCompleted === 4)
+ .every((p) => p.phase === parentPhase),
+ ).toBe(true);
+ }
+ expect(updates.at(-1)).toEqual({
+ phase: parentPhase,
+ filesCompleted:
+ family === "parent-only" || family === "accepted-eligibility"
+ ? 4
+ : 3,
+ filesTotal:
+ family === "parent-only"
+ ? 8
+ : family === "accepted-eligibility"
+ ? 5
+ : 6,
+ });
+ } finally {
+ clearInterval(keepAlive);
+ release.resolve();
+ for (const p of seen.values()) p.resolve();
+ await client.close();
+ opening.mockRestore();
+ }
+ },
+ );
+
+ test.each(
+ (["command", "paginated message", "legacy message"] as const).flatMap(
+ (projection) =>
+ (
+ ["intact", "gap", "delayed suffix", "repeated signature"] as const
+ ).map((delivery) => [projection, delivery] as const),
+ ),
+ )(
+ "correlates parent completions across notification gaps (%s, %s)",
+ async (projection, delivery) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const pollAllowed = Promise.withResolvers<void>();
+ const closeEntered = Promise.withResolvers<void>();
+ const closeReleased = Promise.withResolvers<void>();
+ let parentPath = "";
+ let pauseClose = delivery === "delayed suffix";
+ const originalOpen = fsPromises.open;
+ const originalReaddir = fsPromises.readdir;
+ const opening = spyOn(fsPromises, "open").mockImplementation((async (
+ ...args: Parameters<typeof originalOpen>
+ ) => {
+ const handle = await originalOpen(...args);
+ if (String(args[0]) !== parentPath || !pauseClose) return handle;
+ const close = handle.close.bind(handle);
+ handle.close = async () => {
+ if (pauseClose) {
+ pauseClose = false;
+ closeEntered.resolve();
+ await closeReleased.promise;
+ }
+ await close();
+ };
+ return handle;
+ }) as typeof originalOpen);
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ if (String(args[0]) === join(codexHome, "sessions"))
+ await pollAllowed.promise;
+ return originalReaddir(...args);
+ }) as typeof originalReaddir);
+ const append = async (id: string, phase: ScanProgress["phase"]) => {
+ const text =
+ "CODEX_SECURITY_SCAN_PROGRESS " +
+ JSON.stringify({
+ phase,
+ filesCompleted: 4,
+ filesTotal: 8,
+ });
+ const native =
+ projection === "command"
+ ? {
+ type: "CommandExecution",
+ id,
+ command: ["review"],
+ aggregated_output: text,
+ }
+ : { type: "AgentMessage", id, content: [{ type: "Text", text }] };
+ await appendFile(
+ parentPath,
+ [
+ {
+ type: "event_msg",
+ payload:
+ projection === "legacy message"
+ ? { type: "agent_message", message: text }
+ : { type: "item_completed", item: native },
+ },
+ {
+ type: "response_item",
+ payload:
+ projection === "command"
+ ? {
+ type: "custom_tool_call_output",
+ call_id: id,
+ output: "done",
+ }
+ : {
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text }],
+ },
+ },
+ ]
+ .map((row) => JSON.stringify(row))
+ .join("\n") + "\n",
+ );
+ return {
+ type: "item.completed",
+ item:
+ projection === "command"
+ ? {
+ type: "command_execution",
+ id,
+ command: "review",
+ aggregated_output: text,
+ status: "completed",
+ exit_code: 0,
+ }
+ : { type: "agent_message", id, text },
+ } as ThreadEvent;
+ };
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ parentPath = await writeUsageSession(codexHome, "thread-1", {});
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ const first = await append("first", "discovery");
+ if (delivery === "delayed suffix") {
+ pollAllowed.resolve();
+ await closeEntered.promise;
+ }
+ const second = await append("second", "validation");
+ // Native queue backpressure can omit an ordinary start/completion.
+ // Every saved completion here precedes its corresponding live copy.
+ if (delivery === "intact") yield first;
+ yield second;
+ if (delivery === "repeated signature")
+ yield await append("third", "discovery");
+ closeReleased.resolve();
+ pollAllowed.resolve();
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: delivery === "repeated signature" ? "discovery" : "validation",
+ filesCompleted: 4,
+ filesTotal: 8,
+ });
+ } finally {
+ clearInterval(keepAlive);
+ pollAllowed.resolve();
+ closeReleased.resolve();
+ await client.close();
+ opening.mockRestore();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each([
+ ["below worker", true, false, 7],
+ ["below worker", true, false, 8],
+ ["below worker", true, true, 7],
+ ["below worker", true, true, 8],
+ ["across frontier", false, true, 7],
+ ["across frontier", true, true, 7],
+ ["across frontier", false, true, 8],
+ ["across frontier", true, true, 8],
+ ["across frontier", false, true, 9],
+ ["across frontier", true, true, 9],
+ ["inventory phase", false, false, 0],
+ ["inventory phase", true, false, 0],
+ ] as const)(
+ "retains eligible live facts through inventory admission (%s, early: %p, truncated: %p, count: %p)",
+ async (scenario, early, truncated, count) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const workerRead = Promise.withResolvers<void>();
+ const parentRead = Promise.withResolvers<void>();
+ const pollAllowed = Promise.withResolvers<void>();
+ let pausePoll = scenario === "inventory phase";
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ if (pausePoll && String(args[0]) === join(codexHome, "sessions"))
+ await pollAllowed.promise;
+ return originalReaddir(...args);
+ }) as typeof originalReaddir);
+
+ const receipt = (id: string, text: string) => ({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: id,
+ output: text,
+ },
+ });
+ const command = (id: string, text: string, truncate = false) => ({
+ saved: nativeCommand(id, truncate ? persistedCommandOutput : text, id),
+ live: completedCommand(id, text) as ThreadEvent,
+ });
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const parent = await writeUsageSession(codexHome, "thread-1", {});
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ if (scenario !== "inventory phase") {
+ const worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ const workerCount = scenario === "below worker" ? count : 8;
+ await appendFile(
+ worker,
+ JSON.stringify(
+ receipt(
+ "worker-reviewed",
+ progressMarker("discovery", workerCount, workerCount),
+ ),
+ ) + "\n",
+ );
+ await workerRead.promise;
+ }
+ pausePoll = true;
+ const commands =
+ scenario === "across frontier"
+ ? [
+ command(
+ "inventory",
+ commandOutput(progressMarker("discovery", 0, 9)),
+ true,
+ ),
+ command(
+ "review",
+ commandOutput(progressMarker("validation", count, 9)),
+ true,
+ ),
+ command(
+ "parent-boundary",
+ progressMarker("discovery", 8, 8),
+ ),
+ ]
+ : [
+ command(
+ "parent-boundary",
+ scenario === "below worker"
+ ? truncated
+ ? commandOutput(progressMarker("validation", 3, 7))
+ : progressMarker("validation", 3, 7)
+ : progressMarker("validation", 5, 8),
+ truncated,
+ ),
+ ];
+ const inventories =
+ scenario === "across frontier"
+ ? []
+ : [
+ receipt("old-inventory", progressMarker("discovery", 0, 7)),
+ ...(scenario === "inventory phase"
+ ? [
+ receipt(
+ "new-inventory",
+ progressMarker("discovery", 0, 8),
+ ),
+ ]
+ : []),
+ ];
+ // All canonical records precede every corresponding SDK item. Only
+ // observer delivery/poll placement differs between paired controls.
+ await appendFile(
+ parent,
+ [...inventories, ...commands.map((item) => item.saved)]
+ .map((item) => JSON.stringify(item))
+ .join("\n") + "\n",
+ );
+ if (early) for (const item of commands) yield item.live;
+ pausePoll = false;
+ pollAllowed.resolve();
+ await parentRead.promise;
+ if (!early) for (const item of commands) yield item.live;
+ if (scenario === "inventory phase") {
+ const next = command("next", progressMarker("reporting", 6, 8));
+ await appendFile(parent, JSON.stringify(next.saved) + "\n");
+ yield next.live;
+ }
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ onSessionEvent: ({ event }) => {
+ const payload = event["payload"] as {
+ call_id?: string;
+ item?: { id?: string };
+ };
+ if (payload?.call_id === "worker-reviewed") workerRead.resolve();
+ if (payload?.item?.id === "parent-boundary") parentRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual(
+ scenario === "below worker"
+ ? {
+ phase: count === 7 ? "preflight" : "validation",
+ filesCompleted: count === 7 ? 7 : 3,
+ filesTotal: 7,
+ }
+ : scenario === "across frontier"
+ ? {
+ phase: count > 8 ? "validation" : "discovery",
+ filesCompleted: Math.max(count, 8),
+ filesTotal: 9,
+ }
+ : { phase: "reporting", filesCompleted: 6, filesTotal: 8 },
+ );
+ } finally {
+ clearInterval(keepAlive);
+ pausePoll = false;
+ pollAllowed.resolve();
+ workerRead.resolve();
+ parentRead.resolve();
+ await client.close();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each([
+ [false, false, 7],
+ [false, true, 7],
+ [true, false, 7],
+ [true, true, 7],
+ [false, false, 8],
+ [false, true, 8],
+ [true, false, 8],
+ [true, true, 8],
+ ] as const)(
+ "keeps the newest proven inventory ahead of saved zeros (split: %p, truncated: %p, worker: %p)",
+ async (split, truncated, workerCount) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const workerRead = Promise.withResolvers<void>();
+ const oldRead = Promise.withResolvers<void>();
+ const newRead = Promise.withResolvers<void>();
+ const pollAllowed = Promise.withResolvers<void>();
+ let pausePoll = false;
+ let parentPath = "";
+ const originalOpen = fsPromises.open;
+ const opening = spyOn(fsPromises, "open").mockImplementation((async (
+ ...args: Parameters<typeof originalOpen>
+ ) => {
+ const handle = await originalOpen(...args);
+ if (String(args[0]) !== parentPath) return handle;
+ const read = handle.read.bind(handle);
+ handle.read = (async (...readArgs: Parameters<typeof read>) => {
+ if (pausePoll) await pollAllowed.promise;
+ const result = await read(...readArgs);
+ // A parent read may already be past directory enumeration when the
+ // fixture pauses. Hold its bytes until both inventories are queued.
+ if (pausePoll) await pollAllowed.promise;
+ return result;
+ }) as typeof handle.read;
+ return handle;
+ }) as typeof originalOpen);
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ if (pausePoll && String(args[0]) === join(codexHome, "sessions"))
+ await pollAllowed.promise;
+ return originalReaddir(...args);
+ }) as typeof originalReaddir);
+
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const parent = await writeUsageSession(codexHome, "thread-1", {});
+ parentPath = parent;
+ const worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ const step = async (
+ id: string,
+ phase: ScanProgress["phase"],
+ count: number,
+ total: number,
+ truncate = false,
+ ): Promise<ThreadEvent> => {
+ const text = truncate
+ ? commandOutput(progressMarker(phase, count, total))
+ : progressMarker(phase, count, total);
+ // Every native record is durable before its corresponding SDK item;
+ // neither the old nor the new live inventory occurrence is omitted.
+ await appendFile(
+ parent,
+ JSON.stringify(
+ nativeCommand(id, truncate ? persistedCommandOutput : text, id),
+ ) + "\n",
+ );
+ return completedCommand(id, text);
+ };
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await appendFile(
+ worker,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "worker-reviewed",
+ output: progressMarker(
+ "validation",
+ workerCount,
+ workerCount,
+ ),
+ },
+ }) + "\n",
+ );
+ await workerRead.promise;
+ pausePoll = !split;
+ yield await step("old-inventory", "discovery", 0, 7);
+ if (split) await oldRead.promise;
+ pausePoll = true;
+ yield await step("new-inventory", "discovery", 0, 8, truncated);
+ pausePoll = false;
+ pollAllowed.resolve();
+ await newRead.promise;
+ yield await step("review", "discovery", 5, 8);
+ yield await step("done", "validation", 8, 8);
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ onSessionEvent: ({ event }) => {
+ const payload = event["payload"] as {
+ call_id?: string;
+ item?: { id?: string };
+ };
+ if (payload?.call_id === "worker-reviewed") workerRead.resolve();
+ if (payload?.item?.id === "old-inventory") oldRead.resolve();
+ if (payload?.item?.id === "new-inventory") newRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "validation",
+ filesCompleted: 8,
+ filesTotal: 8,
+ });
+ if (!split)
+ expect(updates.every((update) => update.filesTotal === 8)).toBe(true);
+ } finally {
+ clearInterval(keepAlive);
+ pausePoll = false;
+ pollAllowed.resolve();
+ workerRead.resolve();
+ oldRead.resolve();
+ newRead.resolve();
+ await client.close();
+ opening.mockRestore();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each([false, true])(
+ "recovers parent coverage suppressed by a provisional worker (worker remains eligible: %p)",
+ async (eligibleWorker) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const workerRead = Promise.withResolvers<void>();
+ const parentRead = Promise.withResolvers<void>();
+
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const parent = await writeUsageSession(codexHome, "thread-1", {});
+ // The inventory is already durable; its full SDK projection is delayed
+ // until after the provisional worker and lower parent count are polled.
+ await appendFile(
+ parent,
+ JSON.stringify(nativeCommand("inventory", persistedCommandOutput)) +
+ "\n",
+ );
+ const worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ const workerCount = eligibleWorker ? 7 : 8;
+ await appendFile(
+ worker,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "worker-review",
+ output: progressMarker("discovery", workerCount, workerCount),
+ },
+ }) + "\n",
+ );
+ await workerRead.promise;
+ await appendFile(
+ parent,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "parent-review",
+ output: progressMarker("validation", 4, 7),
+ },
+ }) + "\n",
+ );
+ await parentRead.promise;
+ yield completedCommand(
+ "inventory",
+ commandOutput(progressMarker("discovery", 0, 7)),
+ "live-inventory",
+ );
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (progress) => updates.push(progress),
+ onSessionEvent: ({ event }) => {
+ const id = (event["payload"] as { call_id?: string })?.call_id;
+ if (id === "worker-review") workerRead.resolve();
+ if (id === "parent-review") parentRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: eligibleWorker ? "preflight" : "validation",
+ filesCompleted: eligibleWorker ? 7 : 4,
+ filesTotal: 7,
+ });
+ } finally {
+ clearInterval(keepAlive);
+ await client.close();
+ }
+ },
+ );
+
+ test.each([
+ [
+ "legacy receipts use completion-order fallback",
+ true,
+ false,
+ false,
+ 8,
+ 9,
+ 1,
+ 1,
+ ],
+ [
+ "missing earlier native occurrence preserves a later anchor",
+ true,
+ true,
+ false,
+ 8,
+ 9,
+ 1,
+ 1,
+ ],
+ ["complete native occurrences", true, true, false, 8, 9, 1, 1],
+ ["tool-only old inventory", false, true, false, 8, 9, 1, 1],
+ ["late upward inventory proof", false, true, true, 8, 9, 1, 1],
+ [
+ "pending worker coverage remains newer than inventory proof",
+ false,
+ true,
+ true,
+ 8,
+ 9,
+ 9,
+ 9,
+ ],
+ ["live inventory readmits pending worker", false, true, true, 8, 9, 9, 9],
+ [
+ "late proof admits a previously oversized worker",
+ false,
+ true,
+ true,
+ 8,
+ 9,
+ 9,
+ 9,
+ ],
+ ["late downward inventory proof", false, true, true, 9, 8, 1, 1],
+ [
+ "late proof excludes an oversized worker shard",
+ false,
+ true,
+ true,
+ 9,
+ 8,
+ 9,
+ 9,
+ ],
+ ] as const)(
+ "reconciles inventory receipts and worker progress: %s",
+ async (
+ _scenario,
+ streamOld,
+ nativeCompletion,
+ delayNative,
+ originalTotal,
+ correctedTotal,
+ workerCount,
+ workerTotal,
+ ) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ let proofIndex = 0;
+ const parentRead = Promise.withResolvers<void>();
+ const workerRead = Promise.withResolvers<void>();
+ const marker = (
+ filesCompleted: number,
+ filesTotal: number,
+ phase: ScanProgress["phase"] = "discovery",
+ ) => progressMarker(phase, filesCompleted, filesTotal);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: async (
+ _options: unknown,
+ args: readonly string[],
+ input?: string,
+ ): Promise<JsonObject> =>
+ args[0] === "register-cli-scan"
+ ? {
+ ...mockScanRegistration(args, input),
+ scopeFileCount: originalTotal,
+ }
+ : mockWorkbench(args, input),
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const rollout = await writeUsageSession(codexHome, "thread-1", {});
+ async function* markers(): AsyncGenerator<ThreadEvent> {
+ for (const filesTotal of streamOld
+ ? [originalTotal, correctedTotal]
+ : [correctedTotal]) {
+ yield completedCommand(
+ `scan-inventory ${filesTotal}`,
+ commandOutput(marker(0, filesTotal)),
+ `inventory-${filesTotal}`,
+ );
+ }
+ const saved: unknown[] = [
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "old-preview",
+ output: marker(0, originalTotal),
+ },
+ },
+ ];
+ if (nativeCompletion)
+ saved.push(
+ nativeCommand(
+ ["scan-inventory", String(correctedTotal)],
+ persistedCommandOutput,
+ "native-inventory",
+ ),
+ );
+ if (_scenario === "complete native occurrences")
+ saved.unshift(
+ nativeCommand(
+ ["scan-inventory", String(originalTotal)],
+ persistedCommandOutput,
+ "native-original-inventory",
+ ),
+ );
+ await appendFile(
+ rollout,
+ saved
+ .slice(0, delayNative ? 1 : saved.length)
+ .map((event) => JSON.stringify(event))
+ .join("\n") + "\n",
+ );
+ await parentRead.promise;
+ const worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ await appendFile(
+ worker,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ output: marker(
+ workerCount,
+ workerTotal,
+ _scenario === "live inventory readmits pending worker" ||
+ _scenario ===
+ "pending worker coverage remains newer than inventory proof"
+ ? "validation"
+ : "discovery",
+ ),
+ },
+ }) + "\n",
+ );
+ await workerRead.promise;
+ if (_scenario === "live inventory readmits pending worker")
+ yield completedCommand(
+ `scan-inventory ${correctedTotal}`,
+ commandOutput(marker(0, correctedTotal)),
+ "restored-inventory",
+ );
+ if (delayNative)
+ await appendFile(
+ rollout,
+ saved
+ .slice(1)
+ .map((event) => JSON.stringify(event))
+ .join("\n") + "\n",
+ );
+ await appendFile(
+ rollout,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ output: marker(2, correctedTotal),
+ },
+ }) + "\n",
+ );
+ }
+ return { events: completedEvents("thread-1", markers()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (progress) => {
+ updates.push(progress);
+ if (progress.filesCompleted === workerCount) workerRead.resolve();
+ },
+ onSessionEvent: ({ threadId, event }) => {
+ if (threadId === "worker-thread") workerRead.resolve();
+ if (
+ (event["payload"] as { item?: { id?: string } } | undefined)?.item
+ ?.id === "native-inventory"
+ )
+ proofIndex = updates.length;
+ if (
+ threadId === "thread-1" &&
+ (event["payload"] as Record<string, unknown> | undefined)?.[
+ "call_id"
+ ] === "old-preview"
+ )
+ parentRead.resolve();
+ },
+ });
+ const uncorrelated = streamOld && !nativeCompletion;
+ if (uncorrelated) {
+ // The outer tool output may be a fresh inventory or a copied preview.
+ // Missing completion identity cannot distinguish these histories.
+ expect(
+ updates.some((update) => update.filesTotal === correctedTotal),
+ ).toBe(true);
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: workerCount,
+ filesTotal: originalTotal,
+ });
+ return;
+ }
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: Math.max(
+ 2,
+ workerTotal <= correctedTotal ? workerCount : 0,
+ ),
+ filesTotal: correctedTotal,
+ });
+ const corrected = updates.findIndex(
+ (progress) => progress.filesTotal === correctedTotal,
+ );
+ expect(corrected).toBeGreaterThanOrEqual(0);
+ expect(
+ updates
+ .slice(delayNative ? proofIndex : corrected)
+ .every((progress) => progress.filesTotal === correctedTotal),
+ ).toBe(true);
+ expect(
+ updates.every(
+ (progress) => progress.filesCompleted <= progress.filesTotal,
+ ),
+ ).toBe(true);
+ if (workerTotal > correctedTotal) {
+ expect(updates.slice(proofIndex)).toContainEqual({
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: correctedTotal,
+ });
+ }
+ } finally {
+ clearInterval(keepAlive);
+ await client.close();
+ }
+ },
+ );
+
+ test.each([false, true])(
+ "retains saved parent coverage across idle polls (split inventory: %p)",
+ async (split) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const inventoryRead = Promise.withResolvers<void>();
+ const completeRead = Promise.withResolvers<void>();
+ const idleRead = Promise.withResolvers<void>();
+ const receipt = (id: string, count?: number) => ({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: id,
+ output:
+ count === undefined
+ ? "Inspection continues."
+ : "CODEX_SECURITY_SCAN_PROGRESS " +
+ JSON.stringify({
+ phase: "discovery",
+ filesCompleted: count,
+ filesTotal: 9,
+ }),
+ },
+ });
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const rollout = await writeUsageSession(codexHome, "thread-1", {});
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ if (split) {
+ await appendFile(
+ rollout,
+ JSON.stringify(receipt("inventory", 0)) + "\n",
+ );
+ await inventoryRead.promise;
+ }
+ await appendFile(
+ rollout,
+ [
+ ...(split ? [] : [receipt("inventory", 0)]),
+ receipt("complete", 7),
+ ]
+ .map((row) => JSON.stringify(row))
+ .join("\n") + "\n",
+ );
+ await completeRead.promise;
+ await appendFile(rollout, JSON.stringify(receipt("idle")) + "\n");
+ await idleRead.promise;
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ onSessionEvent: ({ event }) => {
+ const id = (event["payload"] as { call_id?: string })?.call_id;
+ if (id === "inventory") {
+ inventoryRead.resolve();
+ }
+ if (id === "complete") {
+ completeRead.resolve();
+ }
+ if (id === "idle") {
+ idleRead.resolve();
+ }
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: 7,
+ filesTotal: 9,
+ });
+ const reviewed = updates.findIndex(
+ (update) => update.filesCompleted === 7,
+ );
+ expect(reviewed).toBeGreaterThanOrEqual(0);
+ expect(
+ updates
+ .slice(reviewed)
+ .every(
+ (update) =>
+ update.filesCompleted === 7 && update.filesTotal === 9,
+ ),
+ ).toBe(true);
+ } finally {
+ clearInterval(keepAlive);
+ await client.close();
+ }
+ },
+ );
+
+ test.each([false, true])(
+ "applies saved inventory before reconsidering live receipts (split correction: %p)",
+ async (split) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const staleRead = Promise.withResolvers<void>();
+ const correctedRead = Promise.withResolvers<void>();
+ const marker = (count: number, total: number) =>
+ progressMarker("discovery", count, total);
+ const receipt = (id: string, total: number) => ({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: id,
+ output: marker(0, total),
+ },
+ });
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: async (
+ _options: unknown,
+ args: readonly string[],
+ input?: string,
+ ): Promise<JsonObject> =>
+ args[0] === "register-cli-scan"
+ ? { ...mockScanRegistration(args, input), scopeFileCount: 9 }
+ : mockWorkbench(args, input),
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const rollout = await writeUsageSession(codexHome, "thread-1", {});
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await appendFile(
+ rollout,
+ JSON.stringify(receipt("stale", 8)) + "\n",
+ );
+ await staleRead.promise;
+ yield completedCommand(
+ "inspect-source",
+ commandOutput(marker(9, 9)),
+ "completed-review",
+ );
+ if (split) {
+ await appendFile(
+ rollout,
+ JSON.stringify(receipt("corrected", 9)) + "\n",
+ );
+ await correctedRead.promise;
+ }
+ const completion = nativeCommand(
+ "inspect-source",
+ persistedCommandOutput,
+ );
+ await appendFile(
+ rollout,
+ [...(split ? [] : [receipt("corrected", 9)]), completion]
+ .map((row) => JSON.stringify(row))
+ .join("\n") + "\n",
+ );
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ onSessionEvent: ({ event }) => {
+ const id = (event["payload"] as { call_id?: string })?.call_id;
+ if (id === "stale") staleRead.resolve();
+ if (id === "corrected") correctedRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: 9,
+ filesTotal: 9,
+ });
+ } finally {
+ clearInterval(keepAlive);
+ await client.close();
+ }
+ },
+ );
+
+ test.each([0, 3])(
+ "keeps the latest accepted inventory when only older proof arrives (%p reviewed)",
+ async (count) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const marker = (completed: number, total: number) =>
+ progressMarker("discovery", completed, total);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const rollout = await writeUsageSession(codexHome, "thread-1", {});
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ for (const [completed, total] of [
+ [0, 8],
+ [0, 9],
+ ...(count ? [[count, 9]] : []),
+ ])
+ yield completedCommand(
+ `report-progress ${completed} ${total}`,
+ commandOutput(marker(completed!, total!)),
+ `progress-${completed}-${total}`,
+ );
+ await appendFile(
+ rollout,
+ JSON.stringify(
+ nativeCommand(
+ ["report-progress", "0", "8"],
+ persistedCommandOutput,
+ ),
+ ) + "\n",
+ );
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: count,
+ filesTotal: 9,
+ });
+ const corrected = updates.findIndex(
+ (update) => update.filesTotal === 9,
+ );
+ expect(
+ updates.slice(corrected).every((update) => update.filesTotal === 9),
+ ).toBe(true);
+ } finally {
+ await client.close();
+ }
+ },
+ );
+
+ test.each([
+ ["rejected completion", 8, 9, 9],
+ ["inventory followed by an accepted count", 9, 8, 1],
+ ] as const)(
+ "reconsiders parent receipts after inventory proof: %s",
+ async (_scenario, oldTotal, total, count) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const previewRead = Promise.withResolvers<void>();
+ const marker = (completed: number, inventory: number) =>
+ progressMarker("discovery", completed, inventory);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: async (
+ _options: unknown,
+ args: readonly string[],
+ input?: string,
+ ): Promise<JsonObject> =>
+ args[0] === "register-cli-scan"
+ ? { ...mockScanRegistration(args, input), scopeFileCount: oldTotal }
+ : mockWorkbench(args, input),
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const rollout = await writeUsageSession(codexHome, "thread-1", {});
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ const live = (completed: number): ThreadEvent =>
+ completedCommand(
+ `report-progress ${completed}`,
+ commandOutput(marker(completed, total)),
+ `live-${completed}`,
+ );
+ yield live(0);
+ await appendFile(
+ rollout,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "old-preview",
+ output: marker(0, oldTotal),
+ },
+ }) + "\n",
+ );
+ await previewRead.promise;
+ yield live(count);
+ for (const completed of [0, count])
+ await appendFile(
+ rollout,
+ JSON.stringify(
+ nativeCommand(
+ ["report-progress", String(completed)],
+ persistedCommandOutput,
+ `native-${completed}`,
+ ),
+ ) + "\n",
+ );
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ onSessionEvent: ({ event }) => {
+ if (
+ (event["payload"] as { call_id?: string })?.call_id ===
+ "old-preview"
+ )
+ previewRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: count,
+ filesTotal: total,
+ });
+ } finally {
+ clearInterval(keepAlive);
+ await client.close();
+ }
+ },
+ );
+
+ test.each([
+ ["saved first", false, false, false, ["discovery", "validation"]],
+ [
+ "saved first with a later tool receipt",
+ false,
+ true,
+ false,
+ ["discovery", "validation"],
+ ],
+ [
+ "ambiguous truncated preview uses the later receipt",
+ false,
+ true,
+ true,
+ ["discovery", "validation"],
+ ],
+ [
+ "live first with a later tool receipt",
+ true,
+ true,
+ false,
+ ["discovery", "validation"],
+ ],
+ [
+ "repeated phases in a truncated completion",
+ false,
+ false,
+ true,
+ ["discovery", "validation", "discovery", "attack_path"],
+ ],
+ ] as const)(
+ "orders markers within one native completion: %s",
+ async (_scenario, liveFirst, preview, truncated, phases) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const read = Promise.withResolvers<void>();
+ const marker = (phase: string) => progressMarker(phase, 8, 8);
+ const text = commandOutput(phases.map(marker).join("\n"));
+ const event: ThreadEvent = completedCommand(
+ "scan-batch",
+ text,
+ "live-command",
+ );
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const rollout = await writeUsageSession(codexHome, "thread-1", {});
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ if (liveFirst) yield event;
+ const saved: unknown[] = [
+ nativeCommand(
+ "scan-batch",
+ truncated ? persistedCommandOutput : text,
+ "native-batch",
+ ),
+ ];
+ if (preview)
+ saved.push({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ output: marker("discovery"),
+ },
+ });
+ await appendFile(
+ rollout,
+ saved.map((entry) => JSON.stringify(entry)).join("\n") + "\n",
+ );
+ await read.promise;
+ if (!liveFirst) yield event;
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (progress) => updates.push(progress),
+ onSessionEvent: ({ event }) => {
+ if (
+ (event["payload"] as { item?: { id?: string } } | undefined)?.item
+ ?.id === "native-batch"
+ )
+ read.resolve();
+ },
+ });
+ expect(
+ updates
+ .filter((progress) => progress.filesCompleted === 8)
+ .map((progress) => progress.phase),
+ ).toEqual(
+ // A separate tool completion has no nested-origin identity. Its
+ // completion order wins even when it could be a copied preview.
+ preview
+ ? liveFirst || !truncated
+ ? [...phases, "discovery"]
+ : ["discovery"]
+ : [...phases],
+ );
+ } finally {
+ clearInterval(keepAlive);
+ await client.close();
+ }
+ },
+ );
+
+ test("advances parent provenance after equal worker progress", async () => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const first = Promise.withResolvers<void>();
+ const workerRead = Promise.withResolvers<void>();
+ const latest = Promise.withResolvers<void>();
+ const marker = (phase: string) => progressMarker(phase, 8, 8);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const rollout = await writeUsageSession(codexHome, "thread-1", {});
+ const native = (id: string, phase: string) =>
+ JSON.stringify(
+ nativeCommand(["scan-phase", phase], marker(phase), id),
+ ) + "\n";
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await appendFile(rollout, native("first", "discovery"));
+ await first.promise;
+ const worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ await appendFile(
+ worker,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ output: marker("validation"),
+ },
+ }) + "\n",
+ );
+ await workerRead.promise;
+ await appendFile(rollout, native("latest", "validation"));
+ await latest.promise;
+ yield completedCommand(
+ "scan-phase discovery",
+ marker("discovery"),
+ "old-stream",
+ );
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (progress) => {
+ updates.push(progress);
+ if (progress.phase === "discovery") first.resolve();
+ },
+ onSessionEvent: ({ event, threadId }) => {
+ if (threadId === "worker-thread" && event["type"] === "response_item")
+ workerRead.resolve();
+ if (
+ (event["payload"] as { item?: { id?: string } } | undefined)?.item
+ ?.id === "latest"
+ )
+ latest.resolve();
+ },
+ });
+ expect(
+ updates
+ .filter((progress) => progress.filesCompleted === 8)
+ .map((progress) => progress.phase),
+ ).toEqual(["discovery", "validation"]);
+ } finally {
+ clearInterval(keepAlive);
+ await client.close();
+ }
+ });
+
+ test.each([
+ [false, "discovery", "validation"],
+ [true, "discovery", "validation"],
+ [false, "attack_path", "discovery"],
+ [true, "attack_path", "discovery"],
+ ] as const)(
+ "orders parked parent completions by source position (poll first: %p, first: %s, last: %s)",
+ async (pollFirst, firstPhase, lastPhase) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const pollAllowed = Promise.withResolvers<void>();
+ const initialRead = Promise.withResolvers<void>();
+ const nextRead = Promise.withResolvers<void>();
+ if (pollFirst) pollAllowed.resolve();
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ if (String(args[0]) === join(codexHome, "sessions"))
+ await pollAllowed.promise;
+ return originalReaddir(...args);
+ }) as typeof originalReaddir);
+ const marker = (phase: ScanProgress["phase"], count: number) =>
+ progressMarker(phase, count, 9);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const parent = await writeUsageSession(codexHome, "thread-1", {});
+ const text = [
+ commandOutput(marker("discovery", 0)),
+ marker(firstPhase, 4),
+ marker(lastPhase, 4),
+ ];
+ await appendFile(
+ parent,
+ text
+ .map((output, index) =>
+ JSON.stringify(
+ nativeCommand(
+ `step-${index}`,
+ index === 0 ? persistedCommandOutput : output,
+ `step-${index}`,
+ ),
+ ),
+ )
+ .join("\n") + "\n",
+ );
+ const item = (index: number): ThreadEvent =>
+ completedCommand(`step-${index}`, text[index]!, `live-${index}`);
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ if (pollFirst) await initialRead.promise;
+ yield item(0);
+ yield item(1);
+ pollAllowed.resolve();
+ await appendFile(
+ parent,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "next-poll",
+ output: "Poll boundary",
+ },
+ }) + "\n",
+ );
+ await nextRead.promise;
+ yield item(2);
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ onSessionEvent: ({ event }) => {
+ const payload = event["payload"] as {
+ item?: { id?: string };
+ call_id?: string;
+ };
+ if (payload?.item?.id === "step-2") initialRead.resolve();
+ if (payload?.call_id === "next-poll") nextRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: lastPhase,
+ filesCompleted: 4,
+ filesTotal: 9,
+ });
+ } finally {
+ clearInterval(keepAlive);
+ pollAllowed.resolve();
+ initialRead.resolve();
+ nextRead.resolve();
+ await client.close();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each([
+ [true, [3]],
+ [false, [3]],
+ [true, [7]],
+ [false, [7]],
+ [true, [9]],
+ [false, [9]],
+ [true, [1, 2]],
+ [false, [1, 2]],
+ [true, [3, 4]],
+ [false, [3, 4]],
+ [true, [4, 4]],
+ [false, [4, 4]],
+ ] as const)(
+ "selects recovered worker phase by aggregate coverage (pending first: %p, shards: %p)",
+ async (pendingFirst, counts) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const workersRead = Promise.withResolvers<void>();
+ const parentRead = Promise.withResolvers<void>();
+ const seen = new Set<string>();
+
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const parent = await writeUsageSession(codexHome, "thread-1", {});
+ await appendFile(
+ parent,
+ JSON.stringify(nativeCommand("inventory", persistedCommandOutput)) +
+ "\n",
+ );
+ const appendWorkers = async () => {
+ for (const [index, count] of counts.entries()) {
+ const worker = await writeUsageSession(
+ codexHome,
+ `worker-${index}`,
+ {},
+ { parent: "thread-1" },
+ );
+ await appendFile(
+ worker,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: `worker-${index}`,
+ output: progressMarker("discovery", count, 9),
+ },
+ }) + "\n",
+ );
+ }
+ await workersRead.promise;
+ };
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ if (pendingFirst) await appendWorkers();
+ await appendFile(
+ parent,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "parent-review",
+ output: progressMarker("validation", 7, 8),
+ },
+ }) + "\n",
+ );
+ await parentRead.promise;
+ if (!pendingFirst) await appendWorkers();
+ yield completedCommand(
+ "inventory",
+ commandOutput(progressMarker("discovery", 0, 9)),
+ );
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => {
+ updates.push(update);
+ if (update.phase === "validation" && update.filesCompleted === 7)
+ parentRead.resolve();
+ },
+ onSessionEvent: ({ event }) => {
+ const id = (event["payload"] as { call_id?: string })?.call_id;
+ if (id?.startsWith("worker-")) {
+ seen.add(id);
+ if (seen.size === counts.length) workersRead.resolve();
+ }
+ },
+ });
+ const workerCount = counts.reduce((sum, count) => sum + count, 0);
+ expect(updates.at(-1)).toEqual({
+ phase: "validation",
+ filesCompleted: Math.max(7, workerCount),
+ filesTotal: 9,
+ });
+ } finally {
+ clearInterval(keepAlive);
+ workersRead.resolve();
+ parentRead.resolve();
+ await client.close();
+ }
+ },
+ );
+
+ test.each([false, true])(
+ "preserves the selected parent receipt through a second inventory correction (delayed: %p)",
+ async (delayed) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const pollAllowed = Promise.withResolvers<void>();
+ const parentRead = Promise.withResolvers<void>();
+ const expanded = Promise.withResolvers<void>();
+ if (delayed) pollAllowed.resolve();
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ if (String(args[0]) === join(codexHome, "sessions"))
+ await pollAllowed.promise;
+ return originalReaddir(...args);
+ }) as typeof originalReaddir);
+
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const parent = await writeUsageSession(codexHome, "thread-1", {});
+ const parts = ["Review: ", progressMarker("validation", 3, 8)];
+ const records = [
+ ...[9, 8].map((total) =>
+ nativeCommand(`inventory-${total}`, persistedCommandOutput),
+ ),
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ output: progressMarker("attack_path", 3, 9),
+ },
+ },
+ {
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [{ type: "Text", text: parts.join("") }],
+ },
+ },
+ },
+ {
+ type: "response_item",
+ payload: {
+ type: "message",
+ role: "assistant",
+ id: "newer-review",
+ content: parts.map((text) => ({ type: "output_text", text })),
+ },
+ },
+ ];
+ await appendFile(
+ parent,
+ records.map((row) => JSON.stringify(row)).join("\n") + "\n",
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ if (delayed) await parentRead.promise;
+ for (const total of [9, 8]) {
+ yield completedCommand(
+ `inventory-${total}`,
+ commandOutput(progressMarker("discovery", 0, total)),
+ );
+ if (delayed && total === 9) await expanded.promise;
+ }
+ pollAllowed.resolve();
+ yield {
+ type: "item.completed",
+ item: {
+ type: "agent_message",
+ id: "newer-review",
+ text: parts.join(""),
+ },
+ };
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => {
+ updates.push(update);
+ if (update.filesCompleted === 3 && update.filesTotal === 9)
+ expanded.resolve();
+ },
+ onSessionEvent: ({ event }) => {
+ if ((event["payload"] as { id?: string })?.id === "newer-review")
+ parentRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "validation",
+ filesCompleted: 3,
+ filesTotal: 8,
+ });
+ } finally {
+ clearInterval(keepAlive);
+ pollAllowed.resolve();
+ parentRead.resolve();
+ expanded.resolve();
+ await client.close();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each([
+ [false, 3],
+ [true, 3],
+ [false, 7],
+ [true, 7],
+ [false, 9],
+ [true, 9],
+ ] as const)(
+ "selects eligible parent and worker recovery candidates (split: %p, worker count: %p)",
+ async (split, workerCount) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const closeEntered = Promise.withResolvers<void>();
+ const closeReleased = Promise.withResolvers<void>();
+ const inventoryRead = Promise.withResolvers<void>();
+ const workerRead = Promise.withResolvers<void>();
+ let parentPath = "";
+ let pauseClose = false;
+ const originalOpen = fsPromises.open;
+ const originalReaddir = fsPromises.readdir;
+ const opening = spyOn(fsPromises, "open").mockImplementation((async (
+ ...args: Parameters<typeof originalOpen>
+ ) => {
+ const handle = await originalOpen(...args);
+ if (String(args[0]) !== parentPath || !pauseClose) return handle;
+ const close = handle.close.bind(handle);
+ handle.close = async () => {
+ if (pauseClose) {
+ pauseClose = false;
+ closeEntered.resolve();
+ await closeReleased.promise;
+ }
+ await close();
+ };
+ return handle;
+ }) as typeof originalOpen);
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ const entries = await originalReaddir(...args);
+ if (String(args[0]) === dirname(parentPath))
+ return entries.toSorted(
+ (left, right) =>
+ Number(String(right.name) === basename(parentPath)) -
+ Number(String(left.name) === basename(parentPath)),
+ );
+ return entries;
+ }) as typeof originalReaddir);
+ const marker = (phase: ScanProgress["phase"], count: number) =>
+ progressMarker(phase, count, 9);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ parentPath = await writeUsageSession(codexHome, "thread-1", {});
+ // Both paths exist before enumeration; this poll can read the newly
+ // appended worker receipt after its older parent snapshot closes.
+ const worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ pauseClose = split;
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ if (split) {
+ await appendFile(parentPath, "\n");
+ await closeEntered.promise;
+ }
+ await appendFile(
+ parentPath,
+ [
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ output: marker("discovery", 0),
+ },
+ },
+ nativeCommand("review", persistedCommandOutput),
+ ]
+ .map((row) => JSON.stringify(row))
+ .join("\n") + "\n",
+ );
+ if (!split) await inventoryRead.promise;
+ yield completedCommand(
+ "review",
+ commandOutput(marker("validation", 7)),
+ );
+ await appendFile(
+ worker,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "worker-reviewed",
+ output: marker("discovery", workerCount),
+ },
+ }) + "\n",
+ );
+ closeReleased.resolve();
+ await workerRead.promise;
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => {
+ updates.push(update);
+ if (update.filesCompleted === 0 && update.filesTotal === 9)
+ inventoryRead.resolve();
+ },
+ onWorkerEvent: () => workerRead.resolve(),
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: split && workerCount > 7 ? "preflight" : "validation",
+ filesCompleted: Math.max(7, workerCount),
+ filesTotal: 9,
+ });
+ } finally {
+ clearInterval(keepAlive);
+ pauseClose = false;
+ closeEntered.resolve();
+ closeReleased.resolve();
+ inventoryRead.resolve();
+ workerRead.resolve();
+ await client.close();
+ opening.mockRestore();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each([
+ [false, "discovery", "validation"],
+ [true, "discovery", "validation"],
+ [false, "attack_path", "discovery"],
+ [true, "attack_path", "discovery"],
+ ] as const)(
+ "keeps newer parent phases across a session close (split: %p, first: %s, next: %s)",
+ async (split, firstPhase, nextPhase) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const metadataRead = Promise.withResolvers<void>();
+ const firstRead = Promise.withResolvers<void>();
+ const closeEntered = Promise.withResolvers<void>();
+ const closeReleased = Promise.withResolvers<void>();
+ let parentPath = "";
+ let pauseClose = false;
+ const originalOpen = fsPromises.open;
+ const opening = spyOn(fsPromises, "open").mockImplementation((async (
+ ...args: Parameters<typeof originalOpen>
+ ) => {
+ const handle = await originalOpen(...args);
+ if (String(args[0]) !== parentPath || !pauseClose) return handle;
+ const close = handle.close.bind(handle);
+ handle.close = async () => {
+ if (pauseClose) {
+ pauseClose = false;
+ closeEntered.resolve();
+ await closeReleased.promise;
+ }
+ await close();
+ };
+ return handle;
+ }) as typeof originalOpen);
+ const marker = (phase: ScanProgress["phase"]) =>
+ progressMarker(phase, 8, 8);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ parentPath = await writeUsageSession(codexHome, "thread-1", {});
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ // Finish initial session association so this poll reads only its
+ // original snapshot, rather than replaying a newly associated file.
+ await metadataRead.promise;
+ pauseClose = split;
+ await appendFile(
+ parentPath,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "first-review",
+ output: marker(firstPhase),
+ },
+ }) + "\n",
+ );
+ if (split) await closeEntered.promise;
+ else await firstRead.promise;
+ // The newer completion is durable before its SDK projection arrives,
+ // even when the older snapshot is still waiting for file.close.
+ await appendFile(
+ parentPath,
+ JSON.stringify({
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [{ type: "Text", text: marker(nextPhase) }],
+ },
+ },
+ }) + "\n",
+ );
+ yield {
+ type: "item.completed",
+ item: {
+ id: "next-review",
+ type: "agent_message",
+ text: marker(nextPhase),
+ },
+ };
+ closeReleased.resolve();
+ await firstRead.promise;
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ onSessionEvent: ({ event }) => {
+ if (event["type"] === "session_meta") metadataRead.resolve();
+ if (
+ (event["payload"] as { call_id?: string })?.call_id ===
+ "first-review"
+ )
+ firstRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: nextPhase,
+ filesCompleted: 8,
+ filesTotal: 8,
+ });
+ } finally {
+ clearInterval(keepAlive);
+ pauseClose = false;
+ metadataRead.resolve();
+ firstRead.resolve();
+ closeEntered.resolve();
+ closeReleased.resolve();
+ await client.close();
+ opening.mockRestore();
+ }
+ },
+ );
+
+ test.each([
+ [7, false, false, "validation", "discovery", "none"],
+ [7, false, true, "validation", "discovery", "none"],
+ [8, false, false, "validation", "discovery", "none"],
+ [8, false, true, "validation", "discovery", "none"],
+ [7, false, false, "discovery", "attack_path", "none"],
+ [7, false, true, "discovery", "attack_path", "none"],
+ [8, false, false, "discovery", "attack_path", "none"],
+ [8, false, true, "discovery", "attack_path", "none"],
+ [7, true, false, "validation", "discovery", "none"],
+ [8, true, true, "validation", "discovery", "none"],
+ [7, true, false, "discovery", "attack_path", "none"],
+ [8, true, true, "discovery", "attack_path", "none"],
+ [8, false, false, "validation", "discovery", "accepted"],
+ [8, false, false, "discovery", "attack_path", "accepted"],
+ [8, false, true, "validation", "discovery", "accepted"],
+ [8, false, true, "discovery", "attack_path", "accepted"],
+ [7, false, true, "validation", "discovery", "accepted"],
+ [8, false, true, "validation", "discovery", "mismatch"],
+ ] as const)(
+ "retains eligible worker phases through inventory correction (parent total: %p, worker first: %p, repeat: %p, parent: %s, worker: %s, next: %s)",
+ async (
+ parentTotal,
+ workerFirst,
+ repeat,
+ parentPhase,
+ workerPhase,
+ nextWorker,
+ ) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const metadataRead = Promise.withResolvers<void>();
+ const parentRead = Promise.withResolvers<void>();
+ const workerRead = Promise.withResolvers<void>();
+ const nextWorkerRead = Promise.withResolvers<void>();
+ const scopeChanged = Promise.withResolvers<void>();
+
+ const nextPhase =
+ workerPhase === "discovery" ? "attack_path" : "validation";
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const parent = await writeUsageSession(codexHome, "thread-1", {});
+ let worker = "";
+ const workerReceipt = (
+ id: string,
+ phase: ScanProgress["phase"],
+ total = 3,
+ ) => ({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: id,
+ output: progressMarker(phase, 3, total),
+ },
+ });
+ const appendWorker = async () => {
+ worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ await appendFile(
+ worker,
+ JSON.stringify(workerReceipt("worker-review", workerPhase)) +
+ "\n",
+ );
+ await workerRead.promise;
+ };
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await metadataRead.promise;
+ await appendFile(
+ parent,
+ JSON.stringify(
+ nativeCommand("inventory", persistedCommandOutput),
+ ) + "\n",
+ );
+ if (workerFirst) await appendWorker();
+ await appendFile(
+ parent,
+ JSON.stringify({
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ id: "parent-review",
+ content: [
+ {
+ type: "Text",
+ text: progressMarker(parentPhase, 3, parentTotal),
+ },
+ ],
+ },
+ },
+ }) + "\n",
+ );
+ await parentRead.promise;
+ if (!workerFirst) await appendWorker();
+ if (nextWorker !== "none") {
+ await appendFile(
+ worker,
+ JSON.stringify(
+ workerReceipt(
+ "worker-next",
+ nextPhase,
+ nextWorker === "mismatch" ? 4 : 3,
+ ),
+ ) + "\n",
+ );
+ await nextWorkerRead.promise;
+ }
+ // Both native parent completions precede their SDK projections.
+ // Let the full earlier inventory reconcile before its following item.
+ yield completedCommand(
+ "inventory",
+ commandOutput(progressMarker("discovery", 0, 7)),
+ );
+ await scopeChanged.promise;
+ yield {
+ type: "item.completed",
+ item: {
+ type: "agent_message",
+ id: "parent-review",
+ text: progressMarker(parentPhase, 3, parentTotal),
+ },
+ };
+ // A fresh worker receipt is still consumed without replacing the
+ // last admitted parent phase.
+ if (repeat)
+ await appendFile(
+ worker,
+ JSON.stringify(workerReceipt("worker-repeat", workerPhase)) +
+ "\n",
+ );
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => {
+ updates.push(update);
+ if (update.filesCompleted === 3 && update.filesTotal === 7)
+ scopeChanged.resolve();
+ },
+ onSessionEvent: ({ event, threadId }) => {
+ if (event["type"] === "session_meta" && threadId === "thread-1")
+ metadataRead.resolve();
+ const payload = event["payload"] as {
+ call_id?: string;
+ item?: { id?: string };
+ };
+ if (payload?.item?.id === "parent-review") parentRead.resolve();
+ if (payload?.call_id === "worker-review") workerRead.resolve();
+ if (payload?.call_id === "worker-next") nextWorkerRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: parentPhase,
+ filesCompleted: 3,
+ filesTotal: 7,
+ });
+ } finally {
+ clearInterval(keepAlive);
+ metadataRead.resolve();
+ parentRead.resolve();
+ workerRead.resolve();
+ nextWorkerRead.resolve();
+ scopeChanged.resolve();
+ await client.close();
+ }
+ },
+ );
+
+ test.each([
+ [false, "validation", "discovery"],
+ [true, "validation", "discovery"],
+ [false, "discovery", "attack_path"],
+ [true, "discovery", "attack_path"],
+ ] as const)(
+ "recovers deferred live parents through a saved scope correction (early: %p, parent: %s, worker: %s)",
+ async (early, parentPhase, workerPhase) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const metadataRead = Promise.withResolvers<void>();
+ const inventoryRead = Promise.withResolvers<void>();
+ const firstRead = Promise.withResolvers<void>();
+ const secondRead = Promise.withResolvers<void>();
+ const closeEntered = Promise.withResolvers<void>();
+ const closeReleased = Promise.withResolvers<void>();
+ const recovered = Promise.withResolvers<void>();
+ let parentPath = "";
+ let pauseClose = false;
+ const originalOpen = fsPromises.open;
+ const opening = spyOn(fsPromises, "open").mockImplementation((async (
+ ...args: Parameters<typeof originalOpen>
+ ) => {
+ const handle = await originalOpen(...args);
+ if (String(args[0]) !== parentPath || !pauseClose) return handle;
+ const close = handle.close.bind(handle);
+ handle.close = async () => {
+ if (pauseClose) {
+ pauseClose = false;
+ closeEntered.resolve();
+ await closeReleased.promise;
+ }
+ await close();
+ };
+ return handle;
+ }) as typeof originalOpen);
+
+ const receipt = (id: string, output: string) => ({
+ type: "response_item",
+ payload: { type: "custom_tool_call_output", call_id: id, output },
+ });
+ const completion = (command: string, output: string) =>
+ nativeCommand(command, output);
+ const live = (command: string, output: string): ThreadEvent =>
+ completedCommand(command, output);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ parentPath = await writeUsageSession(codexHome, "thread-1", {});
+ const inventory = receipt(
+ "inventory",
+ progressMarker("discovery", 0, 6),
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await metadataRead.promise;
+ if (early) {
+ await appendFile(parentPath, JSON.stringify(inventory) + "\n");
+ await inventoryRead.promise;
+ }
+ const first = await writeUsageSession(
+ codexHome,
+ "first-worker",
+ {},
+ { parent: "thread-1" },
+ );
+ await appendFile(
+ first,
+ JSON.stringify(
+ receipt("first", progressMarker(workerPhase, 3, 3)),
+ ) + "\n",
+ );
+ await firstRead.promise;
+ const second = await writeUsageSession(
+ codexHome,
+ "second-worker",
+ {},
+ { parent: "thread-1" },
+ );
+ await appendFile(
+ second,
+ JSON.stringify(
+ receipt("second", progressMarker(workerPhase, 1, 8)),
+ ) + "\n",
+ );
+ await secondRead.promise;
+ if (!early) {
+ pauseClose = true;
+ await appendFile(parentPath, "\n");
+ await closeEntered.promise;
+ }
+ // Native rows precede their ordered SDK completions, but an earlier
+ // read can finish closing before it observes those appended rows.
+ const rows = [
+ ...(early ? [] : [inventory]),
+ completion("eligible", persistedCommandOutput),
+ completion("oversized", progressMarker(parentPhase, 4, 8)),
+ ];
+ await appendFile(
+ parentPath,
+ rows.map((row) => JSON.stringify(row)).join("\n") + "\n",
+ );
+ yield live(
+ "eligible",
+ commandOutput(progressMarker(parentPhase, 3, 6)),
+ );
+ yield live("oversized", progressMarker(parentPhase, 4, 8));
+ closeReleased.resolve();
+ await recovered.promise;
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => {
+ updates.push(update);
+ if (update.filesCompleted === 0 && update.filesTotal === 6)
+ inventoryRead.resolve();
+ if (update.filesCompleted === 3 && update.filesTotal === 6)
+ recovered.resolve();
+ },
+ onSessionEvent: ({ event, threadId }) => {
+ if (event["type"] === "session_meta" && threadId === "thread-1")
+ metadataRead.resolve();
+ const id = (event["payload"] as { call_id?: string })?.call_id;
+ if (id === "first") firstRead.resolve();
+ if (id === "second") secondRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: parentPhase,
+ filesCompleted: 3,
+ filesTotal: 6,
+ });
+ } finally {
+ clearInterval(keepAlive);
+ metadataRead.resolve();
+ inventoryRead.resolve();
+ firstRead.resolve();
+ secondRead.resolve();
+ closeReleased.resolve();
+ recovered.resolve();
+ await client.close();
+ opening.mockRestore();
+ }
+ },
+ );
+
+ test.each(
+ (["validation", "discovery"] as const).flatMap((parentPhase) =>
+ [false, true].flatMap((early) =>
+ (
+ [
+ "no-frontier",
+ "immediate",
+ "idle",
+ "lower-parent",
+ "newer-parent",
+ "restore-scope",
+ "cycle-scope",
+ ] as const
+ ).map((scenario) => [early, parentPhase, scenario] as const),
+ ),
+ ),
+ )(
+ "recovers eligible deferred parents before worker fallback (early: %p, parent: %s, scenario: %s)",
+ async (early, parentPhase, scenario) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const workerPhase =
+ parentPhase === "validation" ? "discovery" : "attack_path";
+ const newerPhase =
+ parentPhase === "validation" ? "attack_path" : "validation";
+ const restoreScope =
+ scenario === "restore-scope" || scenario === "cycle-scope";
+ let narrowed = false;
+ let restoredCountSeen = false;
+ const parentCount = scenario === "lower-parent" ? 2 : 3;
+ const updates: ScanProgress[] = [];
+ const metadataRead = Promise.withResolvers<void>();
+ const inventoryRead = Promise.withResolvers<void>();
+ const recovered = Promise.withResolvers<void>();
+ const restored = Promise.withResolvers<void>();
+ const cycled = Promise.withResolvers<void>();
+ const receipts = new Map<
+ string,
+ ReturnType<typeof Promise.withResolvers<void>>
+ >();
+ for (const id of [
+ "first",
+ "second",
+ "eligible",
+ "newer",
+ "oversized",
+ "idle-1",
+ "idle-2",
+ ])
+ receipts.set(id, Promise.withResolvers<void>());
+
+ const inventory: ThreadEvent = completedCommand(
+ "inventory",
+ commandOutput(progressMarker("discovery", 0, 6)),
+ );
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const parent = await writeUsageSession(codexHome, "thread-1", {});
+ const appendReceipt = async (
+ file: string,
+ id: string,
+ output: string,
+ ) => {
+ await appendFile(
+ file,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: id,
+ output,
+ },
+ }) + "\n",
+ );
+ await receipts.get(id)!.promise;
+ };
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await metadataRead.promise;
+ await appendFile(
+ parent,
+ JSON.stringify(
+ nativeCommand("inventory", persistedCommandOutput),
+ ) + "\n",
+ );
+ const restoredInventory: ThreadEvent = completedCommand(
+ "inventory",
+ commandOutput(progressMarker("discovery", 0, 8)),
+ "inventory-restored",
+ );
+ if (restoreScope)
+ await appendFile(
+ parent,
+ JSON.stringify(
+ nativeCommand("inventory", persistedCommandOutput),
+ ) + "\n",
+ );
+ const finalInventory: ThreadEvent = completedCommand(
+ "inventory",
+ commandOutput(progressMarker("discovery", 0, 6)),
+ "inventory-final",
+ );
+ if (scenario === "cycle-scope")
+ await appendFile(
+ parent,
+ JSON.stringify(
+ nativeCommand("inventory", persistedCommandOutput),
+ ) + "\n",
+ );
+ if (early) {
+ yield inventory;
+ await inventoryRead.promise;
+ if (restoreScope) yield restoredInventory;
+ if (scenario === "cycle-scope") yield finalInventory;
+ }
+ const first = await writeUsageSession(
+ codexHome,
+ "first-worker",
+ {},
+ { parent: "thread-1" },
+ );
+ await appendReceipt(
+ first,
+ "first",
+ progressMarker(workerPhase, 3, 3),
+ );
+ const second = await writeUsageSession(
+ codexHome,
+ "second-worker",
+ {},
+ { parent: "thread-1" },
+ );
+ await appendReceipt(
+ second,
+ "second",
+ progressMarker(workerPhase, 1, 8),
+ );
+ await appendReceipt(
+ parent,
+ "eligible",
+ progressMarker(parentPhase, parentCount, 6),
+ );
+ if (scenario === "newer-parent")
+ await appendReceipt(
+ parent,
+ "newer",
+ progressMarker(newerPhase, parentCount, 6),
+ );
+ if (scenario !== "no-frontier")
+ await appendReceipt(
+ parent,
+ "oversized",
+ progressMarker(parentPhase, 4, 8),
+ );
+ if (scenario === "idle" || scenario === "newer-parent") {
+ // Each receipt requires another actual poll. Deferred facts must
+ // survive while the newer parent still fits the provisional scope.
+ await appendReceipt(parent, "idle-1", "done");
+ await appendReceipt(parent, "idle-2", "done");
+ }
+ if (!early) yield inventory;
+ if (restoreScope) {
+ if (!early) {
+ await recovered.promise;
+ // Keep the temporarily ineligible accepted fact across a poll.
+ await appendReceipt(parent, "idle-1", "done");
+ await appendReceipt(parent, "idle-2", "done");
+ yield restoredInventory;
+ await restored.promise;
+ if (scenario === "cycle-scope") yield finalInventory;
+ }
+ if (scenario === "cycle-scope") await cycled.promise;
+ else await restored.promise;
+ } else await recovered.promise;
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => {
+ updates.push(update);
+ if (update.filesCompleted === 0 && update.filesTotal === 6)
+ inventoryRead.resolve();
+ if (update.filesCompleted === 3 && update.filesTotal === 6) {
+ narrowed = true;
+ recovered.resolve();
+ if (early || restoredCountSeen) cycled.resolve();
+ }
+ if (
+ update.filesCompleted === 4 &&
+ update.filesTotal === 8 &&
+ (early || narrowed)
+ ) {
+ restoredCountSeen = true;
+ restored.resolve();
+ }
+ },
+ onSessionEvent: ({ event, threadId }) => {
+ if (event["type"] === "session_meta" && threadId === "thread-1")
+ metadataRead.resolve();
+ const id = (event["payload"] as { call_id?: string })?.call_id;
+ if (id !== undefined) receipts.get(id)?.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase:
+ scenario === "newer-parent"
+ ? newerPhase
+ : scenario === "lower-parent" && early
+ ? "discovery"
+ : parentPhase,
+ filesCompleted: scenario === "restore-scope" ? 4 : 3,
+ filesTotal: scenario === "restore-scope" ? 8 : 6,
+ });
+ if (restoreScope && !early)
+ expect(
+ updates
+ .filter(
+ (update) =>
+ update.filesTotal === 6 && update.filesCompleted === 3,
+ )
+ .at(-1),
+ ).toEqual({ phase: parentPhase, filesCompleted: 3, filesTotal: 6 });
+ } finally {
+ clearInterval(keepAlive);
+ metadataRead.resolve();
+ inventoryRead.resolve();
+ recovered.resolve();
+ restored.resolve();
+ cycled.resolve();
+ for (const receipt of receipts.values()) receipt.resolve();
+ await client.close();
+ }
+ },
+ );
+
+ test.each([
+ [false, "attack_path", "discovery", "validation"],
+ [true, "attack_path", "discovery", "validation"],
+ [false, "validation", "attack_path", "discovery"],
+ [true, "validation", "attack_path", "discovery"],
+ ] as const)(
+ "recovers worker phases when inventory uncaps accepted coverage (early: %p, parent: %s, first: %s, last: %s)",
+ async (early, parentPhase, firstPhase, lastPhase) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const metadataRead = Promise.withResolvers<void>();
+ const inventoryRead = Promise.withResolvers<void>();
+ const parentRead = Promise.withResolvers<void>();
+ const firstRead = Promise.withResolvers<void>();
+ const lastRead = Promise.withResolvers<void>();
+ const recovered = Promise.withResolvers<void>();
+
+ const inventory: ThreadEvent = completedCommand(
+ "inventory",
+ commandOutput(progressMarker("discovery", 0, 10)),
+ );
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: async (
+ _options: unknown,
+ args: readonly string[],
+ input?: string,
+ ): Promise<JsonObject> =>
+ args[0] === "register-cli-scan"
+ ? { ...mockScanRegistration(args, input), scopeFileCount: 6 }
+ : mockWorkbench(args, input),
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const parent = await writeUsageSession(codexHome, "thread-1", {});
+ const receipt = (
+ id: string,
+ phase: ScanProgress["phase"],
+ count: number,
+ total: number,
+ ) => ({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: id,
+ output: progressMarker(phase, count, total),
+ },
+ });
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await metadataRead.promise;
+ await appendFile(
+ parent,
+ JSON.stringify(
+ nativeCommand("inventory", persistedCommandOutput),
+ ) + "\n",
+ );
+ if (early) {
+ yield inventory;
+ await inventoryRead.promise;
+ }
+ await appendFile(
+ parent,
+ JSON.stringify(receipt("parent-review", parentPhase, 6, 6)) +
+ "\n",
+ );
+ await parentRead.promise;
+ const first = await writeUsageSession(
+ codexHome,
+ "first-worker",
+ {},
+ { parent: "thread-1" },
+ );
+ await appendFile(
+ first,
+ JSON.stringify(receipt("first-worker", firstPhase, 4, 4)) + "\n",
+ );
+ await firstRead.promise;
+ const last = await writeUsageSession(
+ codexHome,
+ "last-worker",
+ {},
+ { parent: "thread-1" },
+ );
+ await appendFile(
+ last,
+ JSON.stringify(receipt("last-worker", lastPhase, 5, 5)) + "\n",
+ );
+ await lastRead.promise;
+ // Both workers were accepted under the provisional inventory. Its
+ // earlier full marker reveals their greater aggregate coverage.
+ if (!early) yield inventory;
+ await recovered.promise;
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => {
+ updates.push(update);
+ if (update.filesCompleted === 0 && update.filesTotal === 10)
+ inventoryRead.resolve();
+ if (update.filesCompleted === 9 && update.filesTotal === 10)
+ recovered.resolve();
+ },
+ onSessionEvent: ({ event, threadId }) => {
+ if (event["type"] === "session_meta" && threadId === "thread-1")
+ metadataRead.resolve();
+ const id = (event["payload"] as { call_id?: string })?.call_id;
+ if (id === "parent-review") parentRead.resolve();
+ if (id === "first-worker") firstRead.resolve();
+ if (id === "last-worker") lastRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: parentPhase,
+ filesCompleted: 9,
+ filesTotal: 10,
+ });
+ } finally {
+ clearInterval(keepAlive);
+ metadataRead.resolve();
+ inventoryRead.resolve();
+ parentRead.resolve();
+ firstRead.resolve();
+ lastRead.resolve();
+ recovered.resolve();
+ await client.close();
+ }
+ },
+ );
+
+ test.each(["command", "message"] as const)(
+ "keeps the current parent phase while polling observes equal workers (%s)",
+ async (kind) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const pollAllowed = Promise.withResolvers<void>();
+ const workerRead = Promise.withResolvers<void>();
+ let parentPath = "";
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ if (String(args[0]) === join(codexHome, "sessions"))
+ await pollAllowed.promise;
+ const entries = await originalReaddir(...args);
+ if (String(args[0]) === dirname(parentPath))
+ return entries.toSorted(
+ (left, right) =>
+ Number(String(right.name) === basename(parentPath)) -
+ Number(String(left.name) === basename(parentPath)),
+ );
+ return entries;
+ }) as typeof originalReaddir);
+ const marker = (phase: ScanProgress["phase"]) =>
+ progressMarker(phase, 8, 8);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ parentPath = await writeUsageSession(codexHome, "thread-1", {});
+ const worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ await appendFile(
+ worker,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ output: marker("discovery"),
+ },
+ }) + "\n",
+ );
+ await appendFile(
+ parentPath,
+ JSON.stringify({
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item:
+ kind === "command"
+ ? {
+ type: "CommandExecution",
+ command: ["review-phase"],
+ aggregated_output: marker("validation"),
+ }
+ : {
+ type: "AgentMessage",
+ content: [{ type: "Text", text: marker("validation") }],
+ },
+ },
+ }) + "\n",
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ // Both sources are durable. Parent-first enumeration can lead live
+ // delivery even though the worker emitted its receipt earlier.
+ pollAllowed.resolve();
+ await workerRead.promise;
+ yield {
+ type: "item.completed",
+ item:
+ kind === "command"
+ ? {
+ id: "live-parent",
+ type: "command_execution",
+ command: "review-phase",
+ aggregated_output: marker("validation"),
+ status: "completed",
+ exit_code: 0,
+ }
+ : {
+ id: "live-parent",
+ type: "agent_message",
+ text: marker("validation"),
+ },
+ };
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => {
+ updates.push(update);
+ },
+ onSessionEvent: ({ event, threadId }) => {
+ if (
+ threadId === "worker-thread" &&
+ event["type"] === "response_item"
+ )
+ workerRead.resolve();
+ },
+ });
+ expect(
+ updates
+ .filter((update) => update.filesCompleted === 8)
+ .map((update) => update.phase),
+ ).toEqual(["validation"]);
+ } finally {
+ clearInterval(keepAlive);
+ pollAllowed.resolve();
+ workerRead.resolve();
+ await client.close();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each([
+ [false, false, "paginated"],
+ [true, false, "paginated"],
+ [false, true, "paginated"],
+ [true, true, "paginated"],
+ [false, false, "legacy"],
+ [true, false, "legacy"],
+ [false, true, "legacy"],
+ [true, true, "legacy"],
+ [false, false, "legacy-tool"],
+ [true, false, "legacy-tool"],
+ [false, true, "legacy-tool"],
+ [true, true, "legacy-tool"],
+ ] as const)(
+ "keeps inventory proof across a pending session close (split: %p, review already started: %p, mode: %s)",
+ async (split, reviewedEarlier, mode) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const workerRead = Promise.withResolvers<void>();
+ const workerAdmitted = Promise.withResolvers<void>();
+ const earlierReviewRead = Promise.withResolvers<void>();
+ const closeEntered = Promise.withResolvers<void>();
+ const closeReleased = Promise.withResolvers<void>();
+ let parentPath = "";
+ let pauseClose = false;
+ const originalOpen = fsPromises.open;
+ const opening = spyOn(fsPromises, "open").mockImplementation((async (
+ ...args: Parameters<typeof originalOpen>
+ ) => {
+ const handle = await originalOpen(...args);
+ if (String(args[0]) !== parentPath || !pauseClose) return handle;
+ // The read itself remains real. Delay only close after the snapshot EOF,
+ // so a later native completion can be durable before SDK delivery while
+ // still absent from this poll's already-read snapshot.
+ const close = handle.close.bind(handle);
+ handle.close = async () => {
+ if (pauseClose) {
+ pauseClose = false;
+ closeEntered.resolve();
+ await closeReleased.promise;
+ }
+ await close();
+ };
+ return handle;
+ }) as typeof originalOpen);
+
+ const native = (id: string, text: string) => {
+ if (mode !== "paginated")
+ return (
+ JSON.stringify(
+ mode === "legacy-tool" || id.endsWith("inventory")
+ ? {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: id,
+ output: text,
+ },
+ }
+ : {
+ type: "event_msg",
+ payload: { type: "agent_message", id, message: text },
+ },
+ ) + "\n"
+ );
+ return JSON.stringify(nativeCommand(id, text, id)) + "\n";
+ };
+ const live = (id: string, text: string): ThreadEvent => ({
+ type: "item.completed",
+ item:
+ mode === "legacy" && !id.endsWith("inventory")
+ ? { type: "agent_message", id, text }
+ : {
+ type: "command_execution",
+ id,
+ command: id,
+ aggregated_output: text,
+ status: "completed",
+ exit_code: 0,
+ },
+ });
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ parentPath = await writeUsageSession(codexHome, "thread-1", {});
+ const worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ await appendFile(
+ worker,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "worker-count",
+ output: progressMarker("discovery", 1, 9),
+ },
+ }) + "\n",
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await workerRead.promise;
+ const first = progressMarker("discovery", 0, 9);
+ await appendFile(parentPath, native("first-inventory", first));
+ yield live("first-inventory", first);
+ await workerAdmitted.promise;
+ if (reviewedEarlier) {
+ const earlier = progressMarker("validation", 3, 9);
+ await appendFile(parentPath, native("earlier-review", earlier));
+ yield live("earlier-review", earlier);
+ await earlierReviewRead.promise;
+ }
+ const inventory = progressMarker("discovery", 0, 7);
+ pauseClose = split;
+ await appendFile(
+ parentPath,
+ native("corrected-inventory", inventory),
+ );
+ if (split) await closeEntered.promise;
+ const review = progressMarker(
+ "validation",
+ 7,
+ reviewedEarlier ? 9 : 7,
+ );
+ // Both records are persisted before their corresponding live items.
+ await appendFile(parentPath, native("final-review", review));
+ yield live("corrected-inventory", inventory);
+ yield live("final-review", review);
+ closeReleased.resolve();
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => {
+ updates.push(update);
+ if (update.filesCompleted === 1 && update.filesTotal === 9)
+ workerAdmitted.resolve();
+ },
+ onSessionEvent: ({ event }) => {
+ const payload = event["payload"] as {
+ call_id?: string;
+ id?: string;
+ item?: { id?: string };
+ };
+ if (payload?.call_id === "worker-count") workerRead.resolve();
+ if (
+ (payload?.item?.id ?? payload?.id ?? payload?.call_id) ===
+ "earlier-review"
+ )
+ earlierReviewRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "validation",
+ filesCompleted: 7,
+ filesTotal: reviewedEarlier ? 9 : 7,
+ });
+ if (reviewedEarlier)
+ expect(
+ updates.every(
+ (update) =>
+ update.filesTotal === 9 || update.filesCompleted === 0,
+ ),
+ ).toBe(true);
+ } finally {
+ clearInterval(keepAlive);
+ pauseClose = false;
+ workerRead.resolve();
+ workerAdmitted.resolve();
+ earlierReviewRead.resolve();
+ closeEntered.resolve();
+ closeReleased.resolve();
+ await client.close();
+ opening.mockRestore();
+ }
+ },
+ );
+
+ test.each([
+ [false, 7, "validation", "attack_path", false, "worker"],
+ [true, 7, "validation", "attack_path", false, "worker"],
+ [false, 8, "validation", "attack_path", false, "worker"],
+ [true, 8, "validation", "attack_path", false, "worker"],
+ [false, 9, "validation", "attack_path", false, "worker"],
+ [true, 9, "validation", "attack_path", false, "worker"],
+ [false, 8, "attack_path", "discovery", false, "worker"],
+ [true, 8, "attack_path", "discovery", false, "worker"],
+ [false, 8, "validation", "attack_path", true, "worker"],
+ [true, 8, "validation", "attack_path", true, "worker"],
+ [false, 7, "validation", "attack_path", false, "parent"],
+ [true, 7, "validation", "attack_path", false, "parent"],
+ [false, 8, "validation", "attack_path", false, "parent"],
+ [true, 8, "validation", "attack_path", false, "parent"],
+ [false, 9, "validation", "attack_path", false, "parent"],
+ [true, 9, "validation", "attack_path", false, "parent"],
+ [false, 8, "attack_path", "discovery", false, "parent"],
+ [false, 8, "validation", "attack_path", true, "parent"],
+ ] as const)(
+ "reconciles deferred parent receipts with newer phases (live first: %p, count: %p, parent: %s, newer: %s, later parent: %p, source: %s)",
+ async (
+ liveFirst,
+ parentCount,
+ parentPhase,
+ workerPhase,
+ laterParent,
+ newerSource,
+ ) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const pollAllowed = Promise.withResolvers<void>();
+ const parentRead = Promise.withResolvers<void>();
+ const workerRead = Promise.withResolvers<void>();
+ if (!liveFirst) pollAllowed.resolve();
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ if (String(args[0]) === join(codexHome, "sessions"))
+ await pollAllowed.promise;
+ return originalReaddir(...args);
+ }) as typeof originalReaddir);
+
+ const receipt = (
+ callId: string,
+ phase: ScanProgress["phase"],
+ count: number,
+ total: number,
+ ) => ({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: callId,
+ output: progressMarker(phase, count, total),
+ },
+ });
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const parent = await writeUsageSession(codexHome, "thread-1", {});
+ await appendFile(
+ parent,
+ [
+ nativeCommand("inventory", persistedCommandOutput),
+ receipt("parent-reviewed", parentPhase, parentCount, 9),
+ ]
+ .map((row) => JSON.stringify(row))
+ .join("\n") + "\n",
+ );
+ const inventory: ThreadEvent = completedCommand(
+ "inventory",
+ commandOutput(progressMarker("discovery", 0, 9)),
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ if (liveFirst) yield inventory;
+ await parentRead.promise;
+ const parts = [
+ "Review progress: ",
+ progressMarker(workerPhase, 8, 8),
+ ];
+ if (newerSource === "worker") {
+ const worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ await appendFile(
+ worker,
+ JSON.stringify(receipt("worker-reviewed", workerPhase, 8, 8)) +
+ "\n",
+ );
+ } else {
+ // Paginated persistence finalizes native text without separators,
+ // while the original response retains independently parsed parts.
+ await appendFile(
+ parent,
+ [
+ {
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [{ type: "Text", text: parts.join("") }],
+ },
+ },
+ },
+ {
+ type: "response_item",
+ payload: {
+ type: "message",
+ role: "assistant",
+ id: "worker-reviewed",
+ content: parts.map((text) => ({
+ type: "output_text",
+ text,
+ })),
+ },
+ },
+ ]
+ .map((row) => JSON.stringify(row))
+ .join("\n") + "\n",
+ );
+ }
+ await workerRead.promise;
+ if (!liveFirst) yield inventory;
+ if (newerSource === "parent")
+ yield {
+ type: "item.completed",
+ item: {
+ type: "agent_message",
+ id: "newer-message",
+ text: parts.join(""),
+ },
+ };
+ if (laterParent)
+ await appendFile(
+ parent,
+ JSON.stringify(
+ receipt("parent-later", parentPhase, parentCount, 9),
+ ) + "\n",
+ );
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => {
+ updates.push(update);
+ if (update.filesTotal === 9 && update.filesCompleted === 0)
+ pollAllowed.resolve();
+ },
+ onSessionEvent: ({ event }) => {
+ const payload = event["payload"] as {
+ call_id?: string;
+ id?: string;
+ };
+ const id = payload?.call_id ?? payload?.id;
+ if (id === "parent-reviewed") parentRead.resolve();
+ if (id === "worker-reviewed") workerRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase:
+ newerSource === "worker"
+ ? !liveFirst && parentCount < 8 && !laterParent
+ ? "preflight"
+ : parentPhase
+ : laterParent || parentCount > 8
+ ? parentPhase
+ : workerPhase,
+ filesCompleted: Math.max(parentCount, 8),
+ filesTotal: 9,
+ });
+ if (!liveFirst && !laterParent && parentCount <= 8) {
+ // Worker receipts retain the parent phase, so their public progress
+ // boundary is the accepted coverage count.
+ const coverage = updates.findIndex((update) =>
+ newerSource === "worker"
+ ? update.filesCompleted >= 8
+ : update.phase === workerPhase,
+ );
+ expect(coverage).toBeGreaterThanOrEqual(0);
+ expect(
+ updates
+ .slice(coverage)
+ .every(
+ (update) =>
+ (newerSource === "worker" || update.phase === workerPhase) &&
+ update.filesCompleted >= 8,
+ ),
+ ).toBe(true);
+ }
+ } finally {
+ clearInterval(keepAlive);
+ pollAllowed.resolve();
+ parentRead.resolve();
+ workerRead.resolve();
+ await client.close();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each([
+ [false, 7, 3, false, false],
+ [true, 7, 3, false, false],
+ [false, 9, 4, false, false],
+ [true, 9, 4, false, false],
+ [false, 9, 3, true, false],
+ [false, 9, 4, true, true],
+ ] as const)(
+ "recovers inventory and saved counts when polling leads live delivery (live first: %p, total: %p, reviewed: %p, later inventory: %p, later count: %p)",
+ async (liveFirst, total, reviewed, laterInventory, laterCount) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const pollAllowed = Promise.withResolvers<void>();
+ const receiptRead = Promise.withResolvers<void>();
+ if (!liveFirst) pollAllowed.resolve();
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ if (String(args[0]) === join(codexHome, "sessions"))
+ await pollAllowed.promise;
+ return originalReaddir(...args);
+ }) as typeof originalReaddir);
+ const marker = (phase: ScanProgress["phase"], count: number) =>
+ progressMarker(phase, count, laterInventory && count > 0 ? 8 : total);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const rollout = await writeUsageSession(codexHome, "thread-1", {});
+ // Both records are durable before live delivery. Slow polling is the
+ // only difference between the two schedules, as in the native writer.
+ const records = [
+ nativeCommand("inventory", persistedCommandOutput),
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "review-count",
+ output: marker(
+ "validation",
+ laterCount ? reviewed - 1 : reviewed,
+ ),
+ },
+ },
+ ];
+ if (laterInventory) records.reverse();
+ if (laterCount)
+ records.push({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "later-count",
+ output: marker("validation", reviewed),
+ },
+ });
+ await appendFile(
+ rollout,
+ records.map((row) => JSON.stringify(row)).join("\n") + "\n",
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ if (!liveFirst) await receiptRead.promise;
+ yield completedCommand(
+ "inventory",
+ commandOutput(marker("discovery", 0)),
+ );
+ if (liveFirst) await receiptRead.promise;
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => {
+ updates.push(update);
+ if (update.filesTotal === total && update.filesCompleted === 0)
+ pollAllowed.resolve();
+ },
+ onSessionEvent: ({ event }) => {
+ if (
+ (event["payload"] as { call_id?: string })?.call_id ===
+ "review-count"
+ )
+ receiptRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "validation",
+ filesCompleted: reviewed,
+ filesTotal: laterInventory ? 8 : total,
+ });
+ const counted = updates.findIndex(
+ (update) => update.filesCompleted === reviewed,
+ );
+ expect(counted).toBeGreaterThanOrEqual(0);
+ expect(
+ updates
+ .slice(counted)
+ .every(
+ (update) =>
+ update.filesCompleted === reviewed &&
+ update.phase === "validation",
+ ),
+ ).toBe(true);
+ } finally {
+ clearInterval(keepAlive);
+ pollAllowed.resolve();
+ receiptRead.resolve();
+ await client.close();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each([
+ [true, 9],
+ [false, 9],
+ [true, 7],
+ [false, 7],
+ ] as const)(
+ "restores resumed parent inventory independently of workers (worker first: %p, total: %p)",
+ async (workerFirst, total) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const marker = (count: number) =>
+ progressMarker("discovery", count, total);
+ const parent = await writeUsageSession(
+ codexHome,
+ "thread-1",
+ {},
+ { cwd: scanDir },
+ );
+ const worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ await appendFile(
+ parent,
+ [0, 4]
+ .map((count) =>
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ output: marker(count),
+ },
+ }),
+ )
+ .join("\n") + "\n",
+ );
+ await appendFile(
+ worker,
+ JSON.stringify({
+ type: "event_msg",
+ payload: {
+ type: "agent_message",
+ message:
+ "CODEX_SECURITY_SCAN_PROGRESS " +
+ JSON.stringify({
+ phase: "validation",
+ filesCompleted: 1,
+ filesTotal: 1,
+ }),
+ },
+ }) + "\n",
+ );
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ const entries = await originalReaddir(...args);
+ if (String(args[0]) === dirname(parent)) {
+ return entries.toSorted((left, right) => {
+ const first = workerFirst ? basename(worker) : basename(parent);
+ return (
+ Number(String(right.name) === first) -
+ Number(String(left.name) === first)
+ );
+ });
+ }
+ return entries;
+ }) as typeof originalReaddir);
+ const recipe = {
+ repository,
+ target: { kind: "repository", paths: [] },
+ repositoryRevision: "deadbeef",
+ };
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: async (
+ _options: unknown,
+ args: readonly string[],
+ input?: string,
+ ): Promise<JsonObject> =>
+ args[0] === "get-cli-scan-resume"
+ ? {
+ ...mockScanRegistration(
+ ["--registration-json-stdin", "--scan-dir", scanDir],
+ JSON.stringify({ recipe }),
+ ),
+ threadId: "thread-1",
+ recipe,
+ scopeFileCount: 8,
+ }
+ : mockWorkbench(args, input),
+ createCodex: () => ({
+ startThread: () => {
+ throw new Error("Expected a resumed thread");
+ },
+ resumeThread: (id) => ({
+ id,
+ runStreamed: async () => {
+ await copyCompletedScan(root);
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await appendFile(
+ parent,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ output: marker(5),
+ },
+ }) + "\n",
+ );
+ throw new Error("Synthetic stop after restored inventory");
+ }
+ return { events: completedEvents(id, events()) };
+ },
+ }),
+ }),
+ });
+ try {
+ await expect(
+ client.run(repository, {
+ mode: "deep",
+ outputDir: scanDir,
+ resumeScanId: "scan_example_001",
+ onProgress: (update) => updates.push(update),
+ }),
+ ).rejects.toThrow("Synthetic stop after restored inventory");
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: 5,
+ filesTotal: total,
+ });
+ const reviewed = updates.findIndex(
+ (update) => update.filesCompleted > 0,
+ );
+ expect(reviewed).toBeGreaterThanOrEqual(0);
+ expect(
+ updates
+ .slice(reviewed)
+ .every(
+ (update) =>
+ update.filesCompleted > 0 &&
+ update.filesCompleted <= update.filesTotal,
+ ),
+ ).toBe(true);
+ } finally {
+ await client.close();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each([
+ [false, false],
+ [false, true],
+ [true, false],
+ [true, true],
+ ])(
+ "admits queued inventory before retained phases (projected: %p, raw copy: %p)",
+ async (projected, raw) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const pollAllowed = Promise.withResolvers<void>();
+ const phaseRead = Promise.withResolvers<void>();
+ const reviewRead = Promise.withResolvers<void>();
+ let held = true;
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ if (held && String(args[0]) === join(codexHome, "sessions"))
+ await pollAllowed.promise;
+ return originalReaddir(...args);
+ }) as typeof originalReaddir);
+ const command = (
+ id: string,
+ phase: ScanProgress["phase"],
+ count: number,
+ total: number,
+ changed = false,
+ ) => {
+ const text = progressMarker(phase, count, total);
+ const argv = ["printf", "sk-" + "a".repeat(32)];
+ return {
+ rows: [
+ nativeCommand(argv, text, id),
+ ...(raw
+ ? [
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: id,
+ output: text,
+ },
+ },
+ ]
+ : []),
+ ],
+ live: completedCommand(
+ changed ? "printf [REDACTED_SECRET]" : argv.join(" "),
+ text,
+ id,
+ ) as ThreadEvent,
+ };
+ };
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const parent = await writeUsageSession(codexHome, "thread-1", {});
+ const first = command("initial", "discovery", 0, 10, projected);
+ const middle = command("middle", "discovery", 0, 9);
+ const inventory = command("inventory", "discovery", 0, 6, projected);
+ const phase = command("phase", "threat_model", 0, 6);
+ const review = command("review", "reporting", 6, 6);
+ const append = (rows: unknown[]) =>
+ appendFile(parent, jsonLines(rows) + "\n");
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await append([
+ ...first.rows,
+ ...middle.rows,
+ ...inventory.rows,
+ ...phase.rows,
+ ]);
+ yield first.live;
+ held = false;
+ pollAllowed.resolve();
+ await phaseRead.promise;
+ yield middle.live;
+ await append(review.rows);
+ await reviewRead.promise;
+ yield inventory.live;
+ yield phase.live;
+ yield review.live;
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ onSessionEvent: ({ event }) => {
+ const payload = event["payload"] as { item?: { id?: string } };
+ if (payload?.item?.id === "phase") phaseRead.resolve();
+ if (payload?.item?.id === "review") reviewRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "reporting",
+ filesCompleted: 6,
+ filesTotal: 6,
+ });
+ } finally {
+ clearInterval(keepAlive);
+ held = false;
+ pollAllowed.resolve();
+ phaseRead.resolve();
+ reviewRead.resolve();
+ await client.close();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each([
+ ["projected", 6],
+ ["unchanged command", 6],
+ ["complete output", 6],
+ ["newer inventory", 9],
+ ["newer inventory pending", 8],
+ ["repeated output", 8],
+ ["different review total", 8],
+ ] as const)(
+ "corroborates lost inventory with a positioned review (%s)",
+ async (scenario, expectedTotal) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const pollAllowed = Promise.withResolvers<void>();
+ const reviewRead = Promise.withResolvers<void>();
+ const parentReady = Promise.withResolvers<void>();
+ const workerAdmitted = Promise.withResolvers<void>();
+ const closeEntered = Promise.withResolvers<void>();
+ const closeReleased = Promise.withResolvers<void>();
+ let parentPath = "";
+ let pauseClose = false;
+ const originalOpen = fsPromises.open;
+ const opening = spyOn(fsPromises, "open").mockImplementation((async (
+ ...args: Parameters<typeof originalOpen>
+ ) => {
+ const handle = await originalOpen(...args);
+ if (String(args[0]) !== parentPath) return handle;
+ const close = handle.close.bind(handle);
+ handle.close = async () => {
+ if (pauseClose) {
+ pauseClose = false;
+ closeEntered.resolve();
+ await closeReleased.promise;
+ }
+ return close();
+ };
+ return handle;
+ }) as typeof originalOpen);
+ let held = true;
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ if (held && String(args[0]) === join(codexHome, "sessions"))
+ await pollAllowed.promise;
+ return originalReaddir(...args);
+ }) as typeof originalReaddir);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const parent = await writeUsageSession(codexHome, "thread-1", {});
+ parentPath = parent;
+ const argv = ["printf", "sk-" + "a".repeat(32)];
+ const inventory = progressMarker("discovery", 0, 6);
+ const review = progressMarker(
+ "validation",
+ 1,
+ scenario === "different review total" ? 7 : 6,
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ if (scenario === "newer inventory pending") {
+ const worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ await appendFile(
+ worker,
+ jsonLines([
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "worker",
+ output: progressMarker("discovery", 1, 8),
+ },
+ },
+ ]) + "\n",
+ );
+ await appendFile(
+ parent,
+ jsonLines([
+ nativeCommand("ready", "Synthetic ready.", "ready"),
+ ]) + "\n",
+ );
+ held = false;
+ pollAllowed.resolve();
+ await Promise.all([parentReady.promise, workerAdmitted.promise]);
+ pauseClose = true;
+ }
+ await appendFile(
+ parent,
+ jsonLines([
+ nativeCommand(
+ argv,
+ scenario === "complete output"
+ ? inventory
+ : persistedCommandOutput,
+ "inventory",
+ ),
+ ...(scenario === "newer inventory" ||
+ scenario === "newer inventory pending"
+ ? [
+ nativeCommand(
+ "newer",
+ progressMarker("discovery", 0, expectedTotal),
+ "newer",
+ ),
+ ]
+ : []),
+ ...(scenario === "repeated output"
+ ? [nativeCommand("other", persistedCommandOutput, "other")]
+ : []),
+ nativeCommand("review", review, "review"),
+ ]) + "\n",
+ );
+ held = false;
+ pollAllowed.resolve();
+ if (scenario === "newer inventory pending")
+ await closeEntered.promise;
+ else await reviewRead.promise;
+ yield completedCommand(
+ scenario === "unchanged command"
+ ? argv.join(" ")
+ : "printf [REDACTED_SECRET]",
+ scenario === "complete output"
+ ? inventory
+ : commandOutput(inventory),
+ "inventory",
+ ) as ThreadEvent;
+ yield completedCommand("review", review, "review") as ThreadEvent;
+ closeReleased.resolve();
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => {
+ updates.push(update);
+ if (update.filesCompleted === 1 && update.filesTotal === 8)
+ workerAdmitted.resolve();
+ },
+ onSessionEvent: ({ event }) => {
+ const payload = event["payload"] as { item?: { id?: string } };
+ if (payload?.item?.id === "review") reviewRead.resolve();
+ if (payload?.item?.id === "ready") parentReady.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "validation",
+ filesCompleted: 1,
+ filesTotal: expectedTotal,
+ });
+ const reviewed = updates.findIndex(
+ (update) => update.filesCompleted > 0,
+ );
+ expect(
+ updates.slice(reviewed).every((update) => update.filesCompleted > 0),
+ ).toBe(true);
+ } finally {
+ clearInterval(keepAlive);
+ pauseClose = false;
+ closeReleased.resolve();
+ parentReady.resolve();
+ workerAdmitted.resolve();
+ held = false;
+ pollAllowed.resolve();
+ reviewRead.resolve();
+ await client.close();
+ listing.mockRestore();
+ opening.mockRestore();
+ }
+ },
+ );
+
+ test.each(
+ ["initial-read", "replay", "all-batch"].flatMap((delivery) =>
+ [false, true].flatMap((truncated) =>
+ [false, true].map((worker) => ({ delivery, truncated, worker })),
+ ),
+ ),
+ )(
+ "keeps saved inventory behind live scope (delivery=$delivery, truncated=$truncated, worker=$worker)",
+ async ({ delivery, truncated, worker }) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const parentEvents: string[] = [];
+ const replayClose = Promise.withResolvers<void>();
+ const releaseReplay = Promise.withResolvers<void>();
+ const currentRead = Promise.withResolvers<void>();
+ const pollAllowed = Promise.withResolvers<void>();
+ let holdPoll = true;
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ if (holdPoll && String(args[0]) === join(codexHome, "sessions"))
+ await pollAllowed.promise;
+ return originalReaddir(...args);
+ }) as typeof originalReaddir);
+ let parentPath = "";
+ let closes = 0;
+ const originalOpen = fsPromises.open;
+ const opening = spyOn(fsPromises, "open").mockImplementation((async (
+ ...args: Parameters<typeof originalOpen>
+ ) => {
+ const handle = await originalOpen(...args);
+ if (String(args[0]) !== parentPath) return handle;
+ const close = handle.close.bind(handle);
+ handle.close = async () => {
+ if (
+ ++closes === (delivery === "initial-read" ? 1 : 2) &&
+ delivery !== "all-batch"
+ ) {
+ replayClose.resolve();
+ await releaseReplay.promise;
+ }
+ return close();
+ };
+ return handle;
+ }) as typeof originalOpen);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ parentPath = await writeUsageSession(codexHome, "thread-1", {});
+ await appendFile(
+ parentPath,
+ jsonLines([
+ nativeCommand("old", progressMarker("discovery", 0, 8), "old"),
+ ]) + "\n",
+ );
+ const workerPath = worker
+ ? await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ )
+ : undefined;
+ if (delivery !== "all-batch") {
+ holdPoll = false;
+ pollAllowed.resolve();
+ }
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ // Hold either the original read or the event-history replay after old EOF.
+ if (delivery !== "all-batch") await replayClose.promise;
+ const inventory = progressMarker("discovery", 0, 5);
+ const review = progressMarker("reporting", 1, 5);
+ const reviewRow = nativeCommand("review", review, "review");
+ await appendFile(
+ parentPath,
+ jsonLines([
+ nativeCommand(
+ ["printf", "sk-" + "a".repeat(32)],
+ truncated ? persistedCommandOutput : inventory,
+ "current",
+ ),
+ ...(delivery === "all-batch" ? [reviewRow] : []),
+ ]) + "\n",
+ );
+ yield completedCommand(
+ "printf [REDACTED_SECRET]",
+ truncated ? commandOutput(inventory) : inventory,
+ "current",
+ ) as ThreadEvent;
+ // Admit the live inventory before publishing oversized worker coverage;
+ // directory enumeration must not decide this fixture's precondition.
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 5,
+ });
+ if (workerPath !== undefined) {
+ await appendFile(
+ workerPath,
+ jsonLines([
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "worker",
+ output: progressMarker("discovery", 6, 8),
+ },
+ },
+ ]) + "\n",
+ );
+ }
+ if (delivery !== "all-batch") {
+ releaseReplay.resolve();
+ await currentRead.promise;
+ await appendFile(parentPath, jsonLines([reviewRow]) + "\n");
+ }
+ yield completedCommand("review", review, "review") as ThreadEvent;
+ holdPoll = false;
+ pollAllowed.resolve();
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ onSessionEvent: ({ threadId, event }) => {
+ const payload = event["payload"] as { item?: { id?: string } };
+ if (threadId === "thread-1" && payload?.item?.id !== undefined)
+ parentEvents.push(payload.item.id);
+ if (payload?.item?.id === "current") currentRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "reporting",
+ filesCompleted: 1,
+ filesTotal: 5,
+ });
+ const current = updates.findIndex(
+ (update) => update.filesCompleted === 0 && update.filesTotal === 5,
+ );
+ expect(current).toBeGreaterThanOrEqual(0);
+ expect(
+ updates
+ .slice(current)
+ .every(
+ (update) => update.filesTotal === 5 && update.filesCompleted <= 5,
+ ),
+ ).toBe(true);
+ expect(parentEvents).toEqual(["old", "current", "review"]);
+ } finally {
+ clearInterval(keepAlive);
+ holdPoll = false;
+ pollAllowed.resolve();
+ releaseReplay.resolve();
+ currentRead.resolve();
+ await client.close();
+ opening.mockRestore();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each(
+ [false, true].flatMap((changedDisplay) =>
+ [false, true].flatMap((rawCopy) =>
+ [false, true].map((pollAhead) => ({
+ changedDisplay,
+ rawCopy,
+ pollAhead,
+ })),
+ ),
+ ),
+ )(
+ "restores live parent phase across raw receipts (changed=$changedDisplay, raw=$rawCopy, pollAhead=$pollAhead)",
+ async ({ changedDisplay, rawCopy, pollAhead }) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const pollAllowed = Promise.withResolvers<void>();
+ const savedRead = Promise.withResolvers<void>();
+ let holdPoll = true;
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ if (holdPoll && String(args[0]) === join(codexHome, "sessions"))
+ await pollAllowed.promise;
+ return originalReaddir(...args);
+ }) as typeof originalReaddir);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const parent = await writeUsageSession(codexHome, "thread-1", {});
+ const old = progressMarker("discovery", 3, 8);
+ const current = progressMarker("validation", 3, 8);
+ await appendFile(
+ parent,
+ jsonLines([
+ nativeCommand(["printf", "sk-" + "a".repeat(32)], old, "old"),
+ nativeCommand("validate", current, "current"),
+ ...(rawCopy
+ ? [
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "current",
+ output: current,
+ },
+ },
+ ]
+ : []),
+ ]) + "\n",
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ if (pollAhead) {
+ holdPoll = false;
+ pollAllowed.resolve();
+ await savedRead.promise;
+ }
+ yield completedCommand(
+ changedDisplay
+ ? "printf [REDACTED_SECRET]"
+ : "printf sk-" + "a".repeat(32),
+ old,
+ "item_0",
+ );
+ yield completedCommand("validate", current, "item_1");
+ holdPoll = false;
+ pollAllowed.resolve();
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ onSessionEvent: ({ event }) => {
+ const payload = event["payload"] as {
+ item?: { id?: string };
+ call_id?: string;
+ };
+ if (
+ rawCopy
+ ? payload.call_id === "current"
+ : payload.item?.id === "current"
+ )
+ savedRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "validation",
+ filesCompleted: 3,
+ filesTotal: 8,
+ });
+ } finally {
+ holdPoll = false;
+ pollAllowed.resolve();
+ savedRead.resolve();
+ clearInterval(keepAlive);
+ await client.close();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ describe("partial parent source ordering", () => {
+ const progress = (
+ phase: ScanProgress["phase"],
+ filesCompleted: number,
+ filesTotal: number,
+ ): ScanProgress => ({ phase, filesCompleted, filesTotal });
+ const inventory = (total: number) => progress("discovery", 0, total);
+ const phase = progress("threat_model", 0, 5);
+ type Step =
+ | readonly ["save" | "live", string, ScanProgress | string]
+ | readonly ["worker", ScanProgress]
+ | readonly ["poll"];
+ const scenarios: readonly {
+ name: string;
+ expected: ScanProgress;
+ steps: readonly Step[];
+ }[] = [
+ {
+ name: "an earlier exact match before pending repeated inventory",
+ expected: progress("discovery", 5, 9),
+ steps: [
+ ["live", "first", inventory(9)],
+ ["save", "first", inventory(9)],
+ ["live", "current-display", inventory(9)],
+ ["save", "middle", inventory(8)],
+ ["poll"],
+ ["save", "current", inventory(9)],
+ ["poll"],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ["worker", progress("attack_path", 5, 9)],
+ ["poll"],
+ ],
+ },
+ {
+ name: "a delayed repeated inventory before a pending exact anchor",
+ expected: inventory(8),
+ steps: [
+ ["live", "first", inventory(8)],
+ ["live", "last changed", inventory(8)],
+ ["live", "anchor", "finished"],
+ ["save", "first", inventory(8)],
+ ["save", "middle", inventory(5)],
+ ["poll"],
+ ["save", "last", inventory(8)],
+ ["poll"],
+ ["save", "anchor", "finished"],
+ ],
+ },
+ {
+ name: "a dropped inventory before bounded zero-count phases",
+ expected: progress("reporting", 0, 5),
+ steps: [
+ ["save", "inventory", inventory(5)],
+ ["save", "phase", progress("validation", 0, 5)],
+ ["save", "later-phase", progress("reporting", 0, 5)],
+ ["live", "phase-display", progress("validation", 0, 5)],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ["poll"],
+ ["worker", progress("attack_path", 6, 8)],
+ ["poll"],
+ ],
+ },
+ {
+ name: "parked inventory before an exact zero-count phase",
+ expected: phase,
+ steps: [
+ ["worker", progress("attack_path", 3, 8)],
+ ["live", "later-phase", phase],
+ ["poll"],
+ ["live", "anchor", "finished"],
+ ["save", "inventory", inventory(5)],
+ ["save", "earlier-phase", phase],
+ ["poll"],
+ ["save", "later-phase", phase],
+ ["poll"],
+ ["save", "anchor", "finished"],
+ ],
+ },
+ {
+ name: "source precedence after a delayed live scope correction",
+ expected: phase,
+ steps: [
+ ["save", "initial", inventory(9)],
+ ["live", "initial changed", inventory(9)],
+ ["worker", progress("attack_path", 3, 9)],
+ ["poll"],
+ ["save", "final", inventory(5)],
+ ["poll"],
+ ["save", "phase", phase],
+ ["poll"],
+ ["live", "final changed", inventory(5)],
+ ["live", "phase changed", phase],
+ ["save", "anchor", "finished"],
+ ["poll"],
+ ["live", "anchor", "finished"],
+ ],
+ },
+ {
+ name: "deferred live inventory ahead of an older saved row",
+ expected: progress("preflight", 2, 5),
+ steps: [
+ ["worker", progress("attack_path", 2, 5)],
+ ["poll"],
+ ["live", "current-changed", inventory(5)],
+ ["save", "older", inventory(10)],
+ ["poll"],
+ ["save", "current", inventory(5)],
+ ["poll"],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ],
+ },
+ {
+ name: "inventory between an early zero phase and a later positive review",
+ expected: progress("validation", 5, 5),
+ steps: [
+ ["save", "initial-phase", progress("threat_model", 0, 8)],
+ ["live", "initial-phase", progress("threat_model", 0, 8)],
+ ["poll"],
+ ["worker", progress("attack_path", 3, 8)],
+ ["poll"],
+ ["save", "inventory", inventory(5)],
+ ["save", "review", progress("validation", 5, 5)],
+ ["live", "review", progress("validation", 5, 5)],
+ ["poll"],
+ ],
+ },
+ {
+ name: "a repeated saved inventory beyond the resolved live boundary",
+ expected: progress("preflight", 2, 9),
+ steps: [
+ ["worker", progress("attack_path", 2, 5)],
+ ["poll"],
+ ["save", "first", inventory(9)],
+ ["live", "first-changed", inventory(9)],
+ ["poll"],
+ ["save", "second", inventory(8)],
+ ["live", "second-changed", inventory(8)],
+ ["poll"],
+ ["save", "third", inventory(9)],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ],
+ },
+ ];
+ test.each(
+ scenarios.flatMap((scenario) =>
+ [false, true].map((workerFirst) => ({ ...scenario, workerFirst })),
+ ),
+ )(
+ "preserves $name (workers first=$workerFirst)",
+ async ({ steps, expected, workerFirst }) => {
+ const { root, repository, codexHome, scanDir } =
+ await scanDirectories();
+ const updates: ScanProgress[] = [];
+ let tracker: ScanCostTracker | undefined;
+ const originalStart = ScanCostTracker.prototype.start;
+ const starting = spyOn(
+ ScanCostTracker.prototype,
+ "start",
+ ).mockImplementation(function (
+ this: ScanCostTracker,
+ threadId: string,
+ ) {
+ originalStart.call(this, threadId);
+ if (threadId === "thread-1") tracker = this;
+ });
+ let parentPath = "",
+ workerPath = "";
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ const entries = await originalReaddir(...args);
+ if (String(args[0]) !== dirname(parentPath)) return entries;
+ const first = basename(workerFirst ? workerPath : parentPath);
+ return entries.toSorted(
+ (left, right) =>
+ Number(String(right.name) === first) -
+ Number(String(left.name) === first),
+ );
+ }) as typeof originalReaddir);
+ const text = (value: string | ScanProgress) =>
+ typeof value === "string"
+ ? value
+ : progressMarker(
+ value.phase,
+ value.filesCompleted,
+ value.filesTotal,
+ );
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ parentPath = await writeUsageSession(codexHome, "thread-1", {});
+ workerPath = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ expect(tracker).toBeDefined();
+ await tracker!.stop();
+ for (const [index, step] of steps.entries()) {
+ if (step[0] === "poll") await tracker!.refresh();
+ else if (step[0] === "live")
+ yield completedCommand(
+ step[1],
+ text(step[2]),
+ `item-${index}`,
+ );
+ else if (step[0] === "save")
+ await appendFile(
+ parentPath,
+ jsonLines([
+ nativeCommand(step[1], text(step[2]), `native-${index}`),
+ ]) + "\n",
+ );
+ else
+ await appendFile(
+ workerPath,
+ jsonLines([
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: `worker-${index}`,
+ output: text(step[1]),
+ },
+ },
+ ]) + "\n",
+ );
+ }
+ await tracker!.refresh();
+ await tracker!.refresh();
+ await tracker!.stop();
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ });
+ expect(updates.at(-1)).toEqual(expected);
+ await tracker!.refresh();
+ await tracker!.stop();
+ expect(updates.at(-1)).toEqual(expected);
+ } finally {
+ await client.close();
+ starting.mockRestore();
+ listing.mockRestore();
+ }
+ },
+ );
+ });
+
+ test.each(
+ [
+ "unwritten growth",
+ "unwritten shrink",
+ "unwritten phase",
+ "delayed repeated inventory",
+ "delayed raw inventory",
+ "close growth",
+ "close shrink",
+ "live scope changed",
+ "live scope exact",
+ "live scope changed batch",
+ "live scope exact batch",
+ ].flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ [false, true].flatMap((pollFirst) =>
+ (scenario.startsWith("delayed") ? [false, true] : [false]).map(
+ (deliverLast) => ({
+ scenario,
+ workerFirst,
+ pollFirst,
+ deliverLast,
+ }),
+ ),
+ ),
+ ),
+ ),
+ )(
+ "preserves occurrence authority after dropped callbacks ($scenario, workers first=$workerFirst, read variant=$pollFirst, last live=$deliverLast)",
+ async ({ scenario, workerFirst, pollFirst, deliverLast }) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ let tracker: ScanCostTracker | undefined;
+ const originalStart = ScanCostTracker.prototype.start;
+ const starting = spyOn(
+ ScanCostTracker.prototype,
+ "start",
+ ).mockImplementation(function (this: ScanCostTracker, threadId: string) {
+ originalStart.call(this, threadId);
+ if (threadId === "thread-1") tracker = this;
+ });
+ let parentPath = "";
+ let workerPath = "";
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ const entries = await originalReaddir(...args);
+ if (String(args[0]) !== dirname(parentPath)) return entries;
+ const first = basename(workerFirst ? workerPath : parentPath);
+ return entries.toSorted(
+ (left, right) =>
+ Number(String(right.name) === first) -
+ Number(String(left.name) === first),
+ );
+ }) as typeof originalReaddir);
+ const inventory = (total: number) =>
+ progressMarker("discovery", 0, total);
+ const expected: ScanProgress =
+ scenario === "unwritten growth" || scenario === "close growth"
+ ? { phase: "discovery", filesCompleted: 5, filesTotal: 9 }
+ : scenario === "unwritten phase"
+ ? { phase: "validation", filesCompleted: 3, filesTotal: 8 }
+ : scenario.startsWith("live scope")
+ ? { phase: "validation", filesCompleted: 1, filesTotal: 8 }
+ : {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: scenario.endsWith("shrink") ? 8 : 5,
+ };
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ parentPath = await writeUsageSession(codexHome, "thread-1", {});
+ workerPath = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ {
+ parent: "thread-1",
+ },
+ );
+ const save = (command: string, output: string) =>
+ appendFile(
+ parentPath,
+ jsonLines([nativeCommand(command, output, command)]) + "\n",
+ );
+ const receipt = (path: string, output: string) =>
+ appendFile(
+ path,
+ jsonLines([
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "synthetic-progress",
+ output,
+ },
+ },
+ ]) + "\n",
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ expect(tracker).toBeDefined();
+ await tracker!.stop();
+ if (scenario.startsWith("close")) {
+ const total = scenario === "close growth" ? 9 : 8;
+ await save("old-first", inventory(total));
+ const older =
+ jsonLines([
+ nativeCommand(
+ "old-last",
+ inventory(total === 9 ? 8 : 9),
+ "old-last",
+ ),
+ ]) + "\n";
+ // Cover both an incomplete older row at EOF and a whole older
+ // row appended during close, before the new live callback.
+ const split = pollFirst ? Math.floor(older.length / 2) : 0;
+ if (split !== 0)
+ await appendFile(parentPath, older.slice(0, split));
+ const closing = Promise.withResolvers<void>();
+ const release = Promise.withResolvers<void>();
+ const originalOpen = fsPromises.open;
+ let intercept = true;
+ const opening = spyOn(fsPromises, "open").mockImplementation(
+ async (...args: Parameters<typeof originalOpen>) => {
+ const handle = await originalOpen(...args);
+ if (String(args[0]) === parentPath && intercept) {
+ intercept = false;
+ const close = handle.close.bind(handle);
+ handle.close = async () => {
+ await appendFile(parentPath, older.slice(split));
+ closing.resolve();
+ await release.promise;
+ await close();
+ };
+ }
+ return handle;
+ },
+ );
+ const pending = tracker!.refresh();
+ try {
+ await closing.promise;
+ yield completedCommand(
+ "current",
+ inventory(total),
+ "live-current",
+ );
+ } finally {
+ release.resolve();
+ await pending;
+ opening.mockRestore();
+ }
+ } else if (scenario.startsWith("unwritten")) {
+ const current =
+ scenario === "unwritten phase"
+ ? progressMarker("validation", 3, 8)
+ : inventory(scenario === "unwritten growth" ? 9 : 8);
+ await save("old-first", current);
+ await save(
+ "old-last",
+ scenario === "unwritten phase"
+ ? progressMarker("reporting", 3, 8)
+ : inventory(scenario === "unwritten growth" ? 8 : 9),
+ );
+ if (pollFirst) await tracker!.refresh();
+ // Earlier live callbacks were dropped. This different command
+ // has not been persisted, even though its output repeats a row.
+ yield completedCommand("current", current, "live-current");
+ } else if (scenario.startsWith("live scope")) {
+ const display = (command: string) =>
+ scenario.includes("changed") ? `${command} displayed` : command;
+ await save("first", inventory(9));
+ yield completedCommand(display("first"), inventory(9));
+ await tracker!.refresh();
+ await receipt(workerPath, progressMarker("attack_path", 5, 9));
+ await tracker!.refresh();
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: 5,
+ filesTotal: 9,
+ });
+ // Every parent callback arrives, but none needs an unchanged
+ // command display or a later message to replace worker coverage.
+ const batch = scenario.endsWith("batch");
+ const commands = [
+ ["current", inventory(8)],
+ ["review", progressMarker("validation", 1, 8)],
+ ] as const;
+ if (batch && pollFirst) {
+ for (const [command, output] of commands)
+ await save(command, output);
+ await tracker!.refresh();
+ }
+ for (const [command, output] of commands) {
+ if (pollFirst && !batch) {
+ await save(command, output);
+ await tracker!.refresh();
+ }
+ yield completedCommand(display(command), output);
+ if (!pollFirst) await save(command, output);
+ if (!batch) await tracker!.refresh();
+ }
+ } else {
+ const middle = scenario === "delayed raw inventory" ? 9 : 8;
+ await save("first", inventory(8));
+ await save("middle", inventory(middle));
+ await save("current", inventory(5));
+ if (scenario === "delayed raw inventory")
+ await receipt(parentPath, inventory(5));
+ else await save("last", inventory(5));
+ if (pollFirst) await tracker!.refresh();
+ yield completedCommand(
+ "first displayed",
+ inventory(8),
+ "live-first",
+ );
+ await tracker!.refresh();
+ yield completedCommand(
+ "middle displayed",
+ inventory(middle),
+ "live-middle",
+ );
+ yield completedCommand("current", inventory(5), "live-current");
+ if (deliverLast) {
+ if (scenario === "delayed raw inventory")
+ await save("last", inventory(5));
+ yield completedCommand("last", inventory(5), "live-last");
+ }
+ }
+ await tracker!.refresh();
+ await tracker!.refresh();
+ if (scenario !== "unwritten phase")
+ await receipt(
+ workerPath,
+ progressMarker(
+ "attack_path",
+ scenario.startsWith("delayed") ||
+ scenario.startsWith("live scope")
+ ? 6
+ : 5,
+ scenario === "delayed repeated inventory" ? 8 : 9,
+ ),
+ );
+ await tracker!.refresh();
+ await tracker!.stop();
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ });
+ expect(updates.at(-1)).toEqual(expected);
+ await tracker!.refresh();
+ await tracker!.stop();
+ expect(updates.at(-1)).toEqual(expected);
+ } finally {
+ await client.close();
+ starting.mockRestore();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ describe("retained parent source evidence", () => {
+ const progress = (
+ phase: ScanProgress["phase"],
+ filesCompleted: number,
+ filesTotal: number,
+ ): ScanProgress => ({ phase, filesCompleted, filesTotal });
+ type Step =
+ | readonly ["save" | "live", string, ScanProgress | string]
+ | readonly ["worker", ScanProgress]
+ | readonly ["message", "response" | "native", ScanProgress]
+ | readonly ["poll"];
+ const scenarios: readonly {
+ name: string;
+ expected: ScanProgress;
+ steps: readonly Step[];
+ }[] = [
+ {
+ name: "duplicate inventory projections as evidence only",
+ expected: progress("validation", 1, 9),
+ steps: [
+ ["message", "response", progress("discovery", 0, 8)],
+ ["poll"],
+ ["live", "inventory changed", progress("discovery", 0, 6)],
+ ["save", "inventory", progress("discovery", 0, 6)],
+ ["save", "later inventory", progress("discovery", 0, 9)],
+ ["message", "native", progress("discovery", 0, 8)],
+ ["save", "review", progress("validation", 1, 6)],
+ ["live", "review", progress("validation", 1, 6)],
+ ["poll"],
+ ],
+ },
+ {
+ name: "deferred inventory after greater coverage",
+ expected: progress("validation", 1, 7),
+ steps: [
+ ["live", "inventory changed", progress("discovery", 0, 8)],
+ ["save", "inventory", progress("discovery", 0, 8)],
+ ["save", "smaller", progress("discovery", 0, 7)],
+ ["poll"],
+ ["save", "review", progress("validation", 1, 7)],
+ ["poll"],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ["worker", progress("attack_path", 5, 8)],
+ ],
+ },
+ {
+ name: "a repeated unbound phase copy",
+ expected: progress("reporting", 2, 8),
+ steps: [
+ ["live", "first", progress("reporting", 2, 8)],
+ ["save", "first", progress("reporting", 2, 8)],
+ ["poll"],
+ ["live", "last changed", progress("reporting", 2, 8)],
+ ["poll"],
+ ["save", "middle", progress("validation", 2, 8)],
+ ["poll"],
+ ["save", "last", progress("reporting", 2, 8)],
+ ["poll"],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ],
+ },
+ {
+ name: "an accepted inventory after its own saved copy",
+ expected: progress("discovery", 0, 6),
+ steps: [
+ ["save", "first", progress("discovery", 0, 9)],
+ ["poll"],
+ ["live", "phase", progress("validation", 0, 9)],
+ ["live", "last changed", progress("discovery", 0, 6)],
+ ["save", "middle", progress("threat_model", 0, 9)],
+ ["poll"],
+ ["save", "phase", progress("validation", 0, 9)],
+ ["save", "last", progress("discovery", 0, 6)],
+ ["live", "anchor", "done"],
+ ["save", "anchor", "done"],
+ ["poll"],
+ ["worker", progress("attack_path", 5, 9)],
+ ],
+ },
+ {
+ name: "inventory before a pending reviewed boundary",
+ expected: progress("reporting", 2, 5),
+ steps: [
+ ["live", "initial", progress("discovery", 0, 5)],
+ ["save", "initial", progress("discovery", 0, 5)],
+ ["save", "phase", progress("threat_model", 0, 5)],
+ ["poll"],
+ ["save", "growth", progress("discovery", 0, 9)],
+ ["live", "report", progress("reporting", 2, 5)],
+ ["live", "anchor", "done"],
+ ["save", "final", progress("discovery", 0, 5)],
+ ["poll"],
+ ["save", "report", progress("reporting", 2, 5)],
+ ["save", "anchor", "done"],
+ ["poll"],
+ ["worker", progress("attack_path", 3, 6)],
+ ],
+ },
+ {
+ name: "worker phase after scope growth",
+ expected: progress("discovery", 1, 9),
+ steps: [
+ ["worker", progress("attack_path", 1, 7)],
+ ["save", "smaller", progress("discovery", 0, 5)],
+ ["poll"],
+ ["live", "phase", progress("threat_model", 0, 5)],
+ ["live", "final", progress("discovery", 0, 9)],
+ ["save", "oldphase", progress("validation", 0, 5)],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ["save", "phase", progress("threat_model", 0, 5)],
+ ["poll"],
+ ["save", "final", progress("discovery", 0, 9)],
+ ["save", "anchor", "done"],
+ ],
+ },
+ {
+ name: "deferred inventory at a different total",
+ expected: progress("validation", 1, 8),
+ steps: [
+ ["live", "first changed", progress("discovery", 0, 9)],
+ ["save", "first", progress("discovery", 0, 9)],
+ ["poll"],
+ ["save", "second", progress("discovery", 0, 8)],
+ ["poll"],
+ ["save", "review", progress("validation", 1, 8)],
+ ["poll"],
+ ["live", "anchor", "done"],
+ ["save", "anchor", "done"],
+ ["poll"],
+ ["worker", progress("attack_path", 5, 9)],
+ ["poll"],
+ ],
+ },
+ {
+ name: "inventory after a provisional zero boundary",
+ expected: progress("validation", 1, 5),
+ steps: [
+ ["live", "review", progress("validation", 1, 5)],
+ ["save", "initial", progress("discovery", 0, 9)],
+ ["save", "zero", progress("threat_model", 0, 9)],
+ ["save", "corrected", progress("discovery", 0, 5)],
+ ["poll"],
+ ["poll"],
+ ["save", "review", progress("validation", 1, 5)],
+ ["poll"],
+ ],
+ },
+ {
+ name: "an unbound phase copy",
+ expected: progress("reporting", 2, 8),
+ steps: [
+ ["live", "current changed", progress("reporting", 2, 8)],
+ ["save", "earlier", progress("validation", 2, 8)],
+ ["poll"],
+ ["save", "current", progress("reporting", 2, 8)],
+ ["poll"],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ],
+ },
+ {
+ name: "a zero phase as scope evidence below worker coverage",
+ expected: progress("threat_model", 3, 5),
+ steps: [
+ ["live", "phase changed", progress("threat_model", 0, 5)],
+ ["live", "anchor", "done"],
+ ["worker", progress("attack_path", 3, 5)],
+ ["poll"],
+ ["save", "inventory", progress("discovery", 0, 5)],
+ ["save", "phase", progress("threat_model", 0, 5)],
+ ["poll"],
+ ["save", "anchor", "done"],
+ ["poll"],
+ ],
+ },
+ {
+ name: "known inventory source bounds",
+ expected: progress("discovery", 5, 9),
+ steps: [
+ ["save", "initial", progress("discovery", 0, 8)],
+ ["poll"],
+ ["save", "old-phase", progress("threat_model", 0, 8)],
+ ["save", "inventory", progress("discovery", 0, 9)],
+ ["save", "anchor", "Done"],
+ ["live", "changed-inventory", progress("discovery", 0, 9)],
+ ["live", "anchor", "Done"],
+ ["poll"],
+ ["worker", progress("attack_path", 5, 9)],
+ ["poll"],
+ ],
+ },
+ {
+ name: "the positive-review boundary after provisional scope",
+ expected: progress("validation", 3, 5),
+ steps: [
+ ["live", "changed-inventory", progress("discovery", 0, 9)],
+ ["live", "review", progress("validation", 3, 5)],
+ ["save", "old-phase", progress("threat_model", 0, 8)],
+ ["poll"],
+ ["save", "initial-inventory", progress("discovery", 0, 9)],
+ ["save", "new-inventory", progress("discovery", 0, 5)],
+ ["poll"],
+ ["save", "review", progress("validation", 3, 5)],
+ ["poll"],
+ ],
+ },
+ {
+ name: "deferred inventory after a larger review",
+ expected: progress("validation", 3, 5),
+ steps: [
+ ["live", "changed-inventory", progress("discovery", 0, 8)],
+ ["save", "inventory", progress("discovery", 0, 8)],
+ ["save", "small", progress("discovery", 0, 5)],
+ ["save", "review", progress("validation", 3, 5)],
+ ["poll"],
+ ["live", "anchor", "Done"],
+ ["save", "anchor", "Done"],
+ ["poll"],
+ ],
+ },
+ {
+ name: "an unbound phase at greater coverage",
+ expected: progress("reporting", 3, 8),
+ steps: [
+ ["live", "changed-current", progress("reporting", 3, 8)],
+ ["save", "old", progress("validation", 3, 8)],
+ ["poll"],
+ ["save", "current", progress("reporting", 3, 8)],
+ ["poll"],
+ ["live", "anchor", "Done"],
+ ["save", "anchor", "Done"],
+ ["poll"],
+ ],
+ },
+ ];
+ test.each(
+ scenarios.flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ [false, true].map((stopBeforeResolution) => ({
+ ...scenario,
+ workerFirst,
+ stopBeforeResolution,
+ })),
+ ),
+ ),
+ )(
+ "retains $name (workers first=$workerFirst, stop=$stopBeforeResolution)",
+ async ({ steps, expected, workerFirst, stopBeforeResolution }) => {
+ const { root, repository, codexHome, scanDir } =
+ await scanDirectories();
+ const updates: ScanProgress[] = [];
+ let tracker: ScanCostTracker | undefined;
+ const originalStart = ScanCostTracker.prototype.start;
+ const starting = spyOn(
+ ScanCostTracker.prototype,
+ "start",
+ ).mockImplementation(function (
+ this: ScanCostTracker,
+ threadId: string,
+ ) {
+ originalStart.call(this, threadId);
+ if (threadId === "thread-1") tracker = this;
+ });
+ let parentPath = "",
+ workerPath = "";
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ const entries = await originalReaddir(...args);
+ if (String(args[0]) !== dirname(parentPath)) return entries;
+ const first = basename(workerFirst ? workerPath : parentPath);
+ return entries.toSorted(
+ (left, right) =>
+ Number(String(right.name) === first) -
+ Number(String(left.name) === first),
+ );
+ }) as typeof originalReaddir);
+ const text = (value: string | ScanProgress) =>
+ typeof value === "string"
+ ? value
+ : progressMarker(
+ value.phase,
+ value.filesCompleted,
+ value.filesTotal,
+ );
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ parentPath = await writeUsageSession(codexHome, "thread-1", {});
+ workerPath = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ expect(tracker).toBeDefined();
+ await tracker!.stop();
+ const anchor = steps.findLastIndex(
+ (step) =>
+ (step[0] === "save" || step[0] === "live") &&
+ step[1] === "anchor",
+ );
+ const resolution =
+ anchor === -1
+ ? steps.findLastIndex((step) => step[0] === "save")
+ : anchor;
+ for (const [index, step] of steps.entries()) {
+ if (stopBeforeResolution && index === resolution) {
+ await tracker!.stop();
+ await tracker!.refresh();
+ }
+ if (step[0] === "poll") await tracker!.refresh();
+ else if (step[0] === "live")
+ yield completedCommand(
+ step[1],
+ text(step[2]),
+ `item-${index}`,
+ );
+ else if (step[0] === "save")
+ await appendFile(
+ parentPath,
+ jsonLines([
+ nativeCommand(step[1], text(step[2]), `native-${index}`),
+ ]) + "\n",
+ );
+ else if (step[0] === "message")
+ await appendFile(
+ parentPath,
+ jsonLines([
+ step[1] === "native"
+ ? {
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [
+ { type: "Text", text: text(step[2]) },
+ ],
+ },
+ },
+ }
+ : {
+ type: "response_item",
+ payload: {
+ type: "message",
+ role: "assistant",
+ content: [
+ { type: "output_text", text: text(step[2]) },
+ ],
+ },
+ },
+ ]) + "\n",
+ );
+ else
+ await appendFile(
+ workerPath,
+ jsonLines([
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: `worker-${index}`,
+ output: text(step[1]),
+ },
+ },
+ ]) + "\n",
+ );
+ }
+ await tracker!.refresh();
+ await tracker!.refresh();
+ await tracker!.stop();
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ });
+ expect(updates.at(-1)).toEqual(expected);
+ const settled = [...updates];
+ await tracker!.refresh();
+ await tracker!.stop();
+ expect(updates).toEqual(settled);
+ } finally {
+ await client.close();
+ starting.mockRestore();
+ listing.mockRestore();
+ }
+ },
+ );
+ });
+
+ describe("command proof and inventory admission", () => {
+ const progress = (
+ phase: ScanProgress["phase"],
+ filesCompleted: number,
+ filesTotal: number,
+ ): ScanProgress => ({ phase, filesCompleted, filesTotal });
+ const inventory = progress("discovery", 0, 8);
+ const phase = progress("threat_model", 0, 8);
+ const commandProgress = [inventory, phase]
+ .map((p) => progressMarker(p.phase, p.filesCompleted, p.filesTotal))
+ .join("\n");
+ type Step =
+ | readonly [
+ "save" | "live",
+ string,
+ ScanProgress | readonly ScanProgress[] | string,
+ ]
+ | readonly ["worker", ScanProgress]
+ | readonly ["poll"];
+ const scenarios: readonly {
+ name: string;
+ expected: ScanProgress;
+ unresolvedExpected?: ScanProgress;
+ steps: readonly Step[];
+ }[] = [
+ {
+ name: "a multi-marker command before a smaller inventory",
+ expected: progress("validation", 1, 5),
+ steps: [
+ ["live", "inventory", [inventory, phase]],
+ ["save", "inventory", [inventory, phase]],
+ ["save", "scope", progress("discovery", 0, 5)],
+ ["save", "review", progress("validation", 1, 5)],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ],
+ },
+ {
+ name: "a multi-marker command before an oversized worker",
+ expected: progress("validation", 1, 5),
+ steps: [
+ ["live", "inventory", [inventory, phase]],
+ ["save", "inventory", [inventory, phase]],
+ ["save", "scope", progress("discovery", 0, 5)],
+ ["save", "review", progress("validation", 1, 5)],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["worker", progress("attack_path", 6, 8)],
+ ],
+ },
+ ...[5, 8].map((total) => ({
+ name: `retained inventory before reporting at ${total}`,
+ expected: progress("reporting", 3, total),
+ steps: [
+ ["live", "inventory", progress("discovery", 0, total)],
+ ["live", "report", progress("reporting", 3, total)],
+ ["save", "inventory", progress("discovery", 0, total)],
+ ["save", "validation", progress("validation", 3, total)],
+ ["poll"],
+ ["save", "report", progress("reporting", 3, total)],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ] as const,
+ })),
+ {
+ name: "a truncated command without its final progress projection",
+ expected: progress("validation", 1, 5),
+ unresolvedExpected: progress("validation", 1, 8),
+ steps: [
+ ["live", "inventory", commandOutput(commandProgress)],
+ ["save", "inventory", persistedCommandOutput],
+ ["save", "scope", progress("discovery", 0, 5)],
+ ["save", "review", progress("validation", 1, 5)],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ],
+ },
+ {
+ name: "a final zero marker below worker display coverage",
+ expected: progress("validation", 1, 5),
+ steps: [
+ ["worker", progress("attack_path", 6, 8)],
+ ["poll"],
+ ["live", "inventory", [inventory, phase]],
+ ["save", "inventory", [inventory, phase]],
+ ["save", "scope", progress("discovery", 0, 5)],
+ ["save", "review", progress("validation", 1, 5)],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ],
+ },
+ {
+ name: "an omitted final projection below worker coverage",
+ expected: progress("validation", 1, 5),
+ unresolvedExpected: progress("preflight", 6, 8),
+ steps: [
+ ["worker", progress("attack_path", 6, 8)],
+ ["poll"],
+ ["live", "inventory", commandOutput(commandProgress)],
+ ["save", "inventory", persistedCommandOutput],
+ ["save", "scope", progress("discovery", 0, 5)],
+ ["save", "review", progress("validation", 1, 5)],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ],
+ },
+ ];
+ test.each(
+ scenarios.flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ [false, true].flatMap((stopBeforeResolution) =>
+ [false, true].map((changedDisplay) => ({
+ ...scenario,
+ workerFirst,
+ stopBeforeResolution,
+ changedDisplay,
+ })),
+ ),
+ ),
+ ),
+ )(
+ "reconciles $name (workers first=$workerFirst, stop=$stopBeforeResolution, changed=$changedDisplay)",
+ async ({
+ steps,
+ expected,
+ unresolvedExpected,
+ workerFirst,
+ stopBeforeResolution,
+ changedDisplay,
+ }) => {
+ const { root, repository, codexHome, scanDir } =
+ await scanDirectories();
+ const updates: ScanProgress[] = [];
+ let tracker: ScanCostTracker | undefined;
+ const originalStart = ScanCostTracker.prototype.start;
+ const starting = spyOn(
+ ScanCostTracker.prototype,
+ "start",
+ ).mockImplementation(function (
+ this: ScanCostTracker,
+ threadId: string,
+ ) {
+ originalStart.call(this, threadId);
+ if (threadId === "thread-1") tracker = this;
+ });
+ let parentPath = "",
+ workerPath = "";
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ const entries = await originalReaddir(...args);
+ if (String(args[0]) !== dirname(parentPath)) return entries;
+ const first = basename(workerFirst ? workerPath : parentPath);
+ return entries.toSorted(
+ (left, right) =>
+ Number(String(right.name) === first) -
+ Number(String(left.name) === first),
+ );
+ }) as typeof originalReaddir);
+ const text = (
+ value: string | ScanProgress | readonly ScanProgress[],
+ ) =>
+ typeof value === "string"
+ ? value
+ : [value]
+ .flat()
+ .map((p) =>
+ progressMarker(p.phase, p.filesCompleted, p.filesTotal),
+ )
+ .join("\n");
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ parentPath = await writeUsageSession(codexHome, "thread-1", {});
+ workerPath = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ expect(tracker).toBeDefined();
+ await tracker!.stop();
+ const anchor = steps.findLastIndex(
+ (step) =>
+ (step[0] === "save" || step[0] === "live") &&
+ step[1] === "anchor",
+ );
+ const resolution =
+ anchor === -1
+ ? steps.findLastIndex((step) => step[0] === "save")
+ : anchor;
+ for (const [index, step] of steps.entries()) {
+ if (stopBeforeResolution && index === resolution) {
+ await tracker!.stop();
+ await tracker!.refresh();
+ }
+ if (step[0] === "poll") await tracker!.refresh();
+ else if (step[0] === "live")
+ yield completedCommand(
+ changedDisplay && step[1] !== "anchor"
+ ? `${step[1]} visible`
+ : step[1],
+ text(step[2]),
+ `item-${index}`,
+ );
+ else if (step[0] === "save")
+ await appendFile(
+ parentPath,
+ jsonLines([
+ nativeCommand(step[1], text(step[2]), `native-${index}`),
+ ]) + "\n",
+ );
+ else
+ await appendFile(
+ workerPath,
+ jsonLines([
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: `worker-${index}`,
+ output: text(step[1]),
+ },
+ },
+ ]) + "\n",
+ );
+ }
+ await tracker!.refresh();
+ await tracker!.refresh();
+ await tracker!.stop();
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ });
+ expect(updates.at(-1)).toEqual(
+ changedDisplay ? (unresolvedExpected ?? expected) : expected,
+ );
+ const settled = [...updates];
+ await tracker!.refresh();
+ await tracker!.stop();
+ expect(updates).toEqual(settled);
+ } finally {
+ await client.close();
+ starting.mockRestore();
+ listing.mockRestore();
+ }
+ },
+ );
+ });
+
+ type ProgressScenarioValue = string | ScanProgress | readonly ScanProgress[];
+ type ProgressScenarioStep =
+ | readonly [
+ (
+ | "save"
+ | "save-quiet"
+ | "live"
+ | "save-message"
+ | "live-message"
+ | "save-response"
+ | "live-changed"
+ ),
+ string,
+ ProgressScenarioValue,
+ ]
+ | readonly [
+ "worker" | "additional-worker" | "check" | "scope" | "receipt",
+ ScanProgress,
+ ]
+ | readonly ["poll"]
+ | readonly ["boundary"]
+ | readonly ["resolve"]
+ | readonly ["begin"];
+ type ProgressScenario = {
+ name: string;
+ expected: ScanProgress;
+ steps: readonly ProgressScenarioStep[];
+ stopBeforeResolution?: boolean;
+ };
+ type ScopedProgressScenario = ProgressScenario & {
+ initialScope: number | null;
+ partitions?: readonly ("batch" | "each")[];
+ };
+ type SplitProgressScenario = ProgressScenario & {
+ partitions?: readonly boolean[];
+ };
+ const progress = (
+ phase: ScanProgress["phase"],
+ filesCompleted: number,
+ filesTotal: number,
+ ): ScanProgress => ({ phase, filesCompleted, filesTotal });
+ const inventory = (total: number) => progress("discovery", 0, total);
+ const progressText = (value: ProgressScenarioValue) =>
+ typeof value === "string"
+ ? value
+ : [value]
+ .flat()
+ .map((p) => progressMarker(p.phase, p.filesCompleted, p.filesTotal))
+ .join("\n");
+
+ function lastLiveAnchor(steps: readonly ProgressScenarioStep[]): number {
+ return steps.findLastIndex(
+ (step) =>
+ (step[0] === "live" || step[0] === "live-message") &&
+ step[1] === "anchor",
+ );
+ }
+
+ async function runProgressScenario(
+ {
+ steps,
+ expected,
+ initialScope = 8,
+ workerFirst,
+ stopBeforeResolution,
+ split,
+ partition = split ? "each" : "batch",
+ }: {
+ steps: readonly ProgressScenarioStep[];
+ expected: ScanProgress;
+ initialScope?: number | null;
+ workerFirst: boolean;
+ stopBeforeResolution: boolean;
+ split?: boolean;
+ partition?: "batch" | "staged" | "each";
+ },
+ {
+ resolutionIndex = -1,
+ pollReceipts = true,
+ }: {
+ resolutionIndex?: number;
+ pollReceipts?: boolean;
+ } = {},
+ ): Promise<void> {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const checkpoints: {
+ actual: ScanProgress | undefined;
+ expected: ScanProgress;
+ scopeOnly?: boolean;
+ }[] = [];
+ let tracker: ScanCostTracker | undefined;
+ const originalStart = ScanCostTracker.prototype.start;
+ const starting = spyOn(
+ ScanCostTracker.prototype,
+ "start",
+ ).mockImplementation(function (this: ScanCostTracker, threadId: string) {
+ originalStart.call(this, threadId);
+ if (threadId === "thread-1") tracker = this;
+ });
+ let parentPath = "",
+ workerPath = "";
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ const entries = await originalReaddir(...args);
+ if (String(args[0]) !== dirname(parentPath)) return entries;
+ const first = basename(workerFirst ? workerPath : parentPath);
+ return entries.toSorted(
+ (left, right) =>
+ Number(String(right.name) === first) -
+ Number(String(left.name) === first),
+ );
+ }) as typeof originalReaddir);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: async (
+ _options: unknown,
+ args: readonly string[],
+ input?: string,
+ ): Promise<JsonObject> =>
+ args[0] === "register-cli-scan"
+ ? {
+ ...mockScanRegistration(args, input),
+ scopeFileCount: initialScope,
+ }
+ : mockWorkbench(args, input),
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ parentPath = await writeUsageSession(codexHome, "thread-1", {});
+ workerPath = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ expect(tracker).toBeDefined();
+ await tracker!.stop();
+ for (const [index, step] of steps.entries()) {
+ if (stopBeforeResolution && index === resolutionIndex) {
+ await tracker!.stop();
+ await tracker!.refresh();
+ }
+ if (step[0] === "begin") {
+ tracker!.beginParentTurn(true);
+ continue;
+ }
+ if (step[0] === "resolve") {
+ if (stopBeforeResolution) {
+ await tracker!.stop();
+ await tracker!.refresh();
+ }
+ continue;
+ }
+ if (step[0] === "boundary") {
+ if (partition !== "batch") await tracker!.refresh();
+ } else if (step[0] === "poll") await tracker!.refresh();
+ else if (step[0] === "check" || step[0] === "scope")
+ checkpoints.push({
+ actual: updates.at(-1),
+ expected: step[1],
+ scopeOnly: step[0] === "scope",
+ });
+ else if (step[0] === "live-changed")
+ yield completedCommand(
+ `${step[1]} displayed`,
+ progressText(step[2]),
+ `item-${index}`,
+ );
+ else if (step[0] === "save-response")
+ await appendFile(
+ parentPath,
+ jsonLines([
+ {
+ type: "response_item",
+ payload: {
+ type: "message",
+ role: "assistant",
+ content: [
+ { type: "output_text", text: progressText(step[2]) },
+ ],
+ },
+ },
+ ]) + "\n",
+ );
+ else if (step[0] === "live-message")
+ yield {
+ type: "item.completed",
+ item: {
+ id: `item-${index}`,
+ type: "agent_message",
+ text: progressText(step[2]),
+ },
+ };
+ else if (step[0] === "save-message")
+ await appendFile(
+ parentPath,
+ jsonLines([
+ {
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ id: `native-${index}`,
+ content: [
+ { type: "Text", text: progressText(step[2]) },
+ ],
+ },
+ },
+ },
+ ]) + "\n",
+ );
+ else if (step[0] === "live")
+ yield completedCommand(
+ step[1],
+ progressText(step[2]),
+ `item-${index}`,
+ );
+ else if (step[0] === "save" || step[0] === "save-quiet")
+ await appendFile(
+ parentPath,
+ jsonLines([
+ nativeCommand(
+ step[1],
+ progressText(step[2]),
+ `native-${index}`,
+ ),
+ ]) + "\n",
+ );
+ else
+ await appendFile(
+ step[0] === "additional-worker"
+ ? await writeUsageSession(
+ codexHome,
+ "followup-worker-thread",
+ {},
+ { parent: "thread-1" },
+ )
+ : step[0] === "receipt"
+ ? parentPath
+ : workerPath,
+ jsonLines([
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: `worker-${index}`,
+ output: progressText(step[1]),
+ },
+ },
+ ]) + "\n",
+ );
+ if (
+ partition === "each" &&
+ step[0] !== "save-quiet" &&
+ (step[0].startsWith("save") ||
+ (pollReceipts && step[0] === "receipt"))
+ )
+ await tracker!.refresh();
+ }
+ await tracker!.refresh();
+ await tracker!.refresh();
+ await tracker!.stop();
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ });
+ expect(updates.at(-1)).toEqual(expected);
+ for (const checkpoint of checkpoints)
+ if (checkpoint.scopeOnly)
+ expect(checkpoint.actual).toMatchObject({
+ filesCompleted: checkpoint.expected.filesCompleted,
+ filesTotal: checkpoint.expected.filesTotal,
+ });
+ else expect(checkpoint.actual).toEqual(checkpoint.expected);
+ const settled = [...updates];
+ await tracker!.refresh();
+ await tracker!.stop();
+ expect(updates).toEqual(settled);
+ } finally {
+ await client.close();
+ starting.mockRestore();
+ listing.mockRestore();
+ }
+ }
+
+ describe("displayed receipt eligibility after inventory recovery", () => {
+ const scenarios: ScopedProgressScenario[] = [];
+ for (const mode of [
+ "changed",
+ "exact",
+ "omit latest",
+ "in scope",
+ "multi marker",
+ "truncated latest",
+ "live only latest",
+ "worker prior",
+ "unknown initial",
+ ] as const) {
+ const review = progress("validation", 2, mode === "in scope" ? 5 : 8);
+ const state =
+ mode === "in scope"
+ ? review
+ : mode === "worker prior"
+ ? progress("validation", 1, 5)
+ : inventory(5);
+ const next = progress("reporting", state.filesCompleted + 1, 5);
+ const latest = mode === "multi marker" ? [inventory(5), review] : review;
+ const liveText =
+ mode === "truncated latest"
+ ? commandOutput(progressText(review))
+ : latest;
+ const savedText =
+ mode === "truncated latest" ? persistedCommandOutput : latest;
+ scenarios.push({
+ name: `displayed receipt (mode=${mode})`,
+ initialScope: mode === "unknown initial" ? null : 8,
+ expected: next,
+ steps: [
+ [mode === "exact" ? "live" : "live-changed", "first", review],
+ ["live", "inventory", inventory(5)],
+ ...(mode === "omit latest"
+ ? []
+ : ([["live", "latest", liveText]] as ProgressScenarioStep[])),
+ ...(mode === "worker prior"
+ ? ([
+ ["worker", progress("attack_path", 1, 5)],
+ ["poll"],
+ ] as ProgressScenarioStep[])
+ : []),
+ ["save-quiet", "initial", inventory(5)],
+ ["save-quiet", "first", review],
+ ["save-quiet", "inventory", inventory(5)],
+ ["boundary"],
+ ["resolve"],
+ ...(mode === "live only latest"
+ ? []
+ : ([
+ ["save-quiet", "latest", savedText],
+ ] as ProgressScenarioStep[])),
+ ["poll"],
+ ["check", state],
+ ["save-quiet", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ["poll"],
+ ["check", state],
+ ["worker", progress("attack_path", 6, 8)],
+ ["poll"],
+ ["check", state],
+ ["save-quiet", "followup", next],
+ ["poll"],
+ ["check", next],
+ ],
+ });
+ }
+ test.each(
+ scenarios.flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ (scenario.partitions ?? (["batch", "each"] as const)).flatMap(
+ (partition) =>
+ [false, true].map((stopBeforeResolution) => ({
+ ...scenario,
+ workerFirst,
+ partition,
+ stopBeforeResolution,
+ })),
+ ),
+ ),
+ ),
+ )(
+ "retains $name (workers first=$workerFirst, stop=$stopBeforeResolution, partition=$partition)",
+ (scenario) => runProgressScenario(scenario),
+ );
+ });
+
+ describe("recovered scope and phase authority", () => {
+ const scenarios: ScopedProgressScenario[] = [];
+ for (const initialScope of [null, 8]) {
+ for (const multiple of [false, true]) {
+ scenarios.push({
+ name: `first recovered scope (initial=${initialScope}, multiple=${multiple})`,
+ initialScope,
+ expected: progress("reporting", 4, 5),
+ steps: [
+ ...(multiple
+ ? ([["save", "initial", inventory(8)]] as ProgressScenarioStep[])
+ : []),
+ ["save", "corrected", inventory(5)],
+ ["save", "review", progress("validation", 3, 5)],
+ ["live", "review", progress("validation", 3, 5)],
+ ["poll"],
+ ["check", progress("validation", 3, 5)],
+ ["resolve"],
+ ["poll"],
+ ["check", progress("validation", 3, 5)],
+ ["worker", progress("attack_path", 4, 6)],
+ ["poll"],
+ ["check", progress("validation", 3, 5)],
+ ["save", "followup", progress("reporting", 4, 5)],
+ ["poll"],
+ ["check", progress("reporting", 4, 5)],
+ ],
+ });
+ }
+ for (const mode of ["changed", "exact", "complete"] as const) {
+ const full = commandOutput(progressText(inventory(10)));
+ scenarios.push({
+ name: `unbounded admitted scope (initial=${initialScope}, mode=${mode})`,
+ initialScope,
+ expected: progress("reporting", 10, 10),
+ steps: [
+ [
+ "save",
+ "inventory",
+ mode === "complete" ? full : persistedCommandOutput,
+ ],
+ ["poll"],
+ [mode === "exact" ? "live" : "live-changed", "inventory", full],
+ ["receipt", progress("reporting", 10, 10)],
+ ["poll"],
+ ["check", progress("reporting", 10, 10)],
+ ["resolve"],
+ ["poll"],
+ ["check", progress("reporting", 10, 10)],
+ ],
+ });
+ scenarios.push({
+ name: `bounded admitted scope (initial=${initialScope}, mode=${mode})`,
+ initialScope,
+ expected: progress("reporting", 7, 10),
+ steps: [
+ [
+ "save-quiet",
+ "inventory",
+ mode === "complete" ? full : persistedCommandOutput,
+ ],
+ [mode === "exact" ? "live" : "live-changed", "inventory", full],
+ ["save", "early", progress("discovery", 1, 8)],
+ ["save", "review", progress("validation", 6, 10)],
+ ["live", "review", progress("validation", 6, 10)],
+ ["poll"],
+ ["check", progress("validation", 6, 10)],
+ ["resolve"],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ["poll"],
+ ["check", progress("validation", 6, 10)],
+ ["save", "followup", progress("reporting", 7, 10)],
+ ["poll"],
+ ["check", progress("reporting", 7, 10)],
+ ],
+ });
+ }
+ }
+ for (const total of [6, 8, 10]) {
+ for (const mode of [
+ "changed",
+ "exact",
+ "complete",
+ "no later phase",
+ ] as const) {
+ const latest = progress("validation", 0, total);
+ const first = progress("threat_model", 0, total);
+ const expected = mode === "no later phase" ? first : latest;
+ scenarios.push({
+ name: `older scope preserves phase (total=${total}, mode=${mode})`,
+ initialScope: 8,
+ expected: progress("reporting", 3, total),
+ steps: [
+ ["live-changed", "inventory", inventory(total)],
+ ["save-quiet", "inventory", inventory(total)],
+ ["save-quiet", "first", first],
+ ["live", "first", first],
+ ...(mode === "no later phase"
+ ? []
+ : ([
+ [
+ mode === "exact" ? "live" : "live-changed",
+ "latest",
+ commandOutput(progressText(latest)),
+ ],
+ ] as ProgressScenarioStep[])),
+ ["poll"],
+ ["check", expected],
+ ["resolve"],
+ ...(mode === "no later phase"
+ ? []
+ : ([
+ [
+ "save",
+ "latest",
+ mode === "complete"
+ ? commandOutput(progressText(latest))
+ : persistedCommandOutput,
+ ],
+ ] as ProgressScenarioStep[])),
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ["poll"],
+ ["check", expected],
+ ["worker", progress("attack_path", 2, total)],
+ ["poll"],
+ ["check", progress(expected.phase, 2, total)],
+ ["save", "followup", progress("reporting", 3, total)],
+ ["poll"],
+ ["check", progress("reporting", 3, total)],
+ ],
+ });
+ }
+ }
+ test.each(
+ scenarios.flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ (scenario.partitions ?? (["batch", "each"] as const)).flatMap(
+ (partition) =>
+ [false, true].map((stopBeforeResolution) => ({
+ ...scenario,
+ workerFirst,
+ partition,
+ stopBeforeResolution,
+ })),
+ ),
+ ),
+ ),
+ )(
+ "retains $name (workers first=$workerFirst, stop=$stopBeforeResolution, partition=$partition)",
+ (scenario) => runProgressScenario(scenario),
+ );
+ });
+
+ describe("admitted inventory across truncated live copies", () => {
+ const outputs = (values: readonly ScanProgress[], visible: number) => {
+ const pre = values
+ .slice(0, visible)
+ .map((p) => progressText(p))
+ .join("\n");
+ const prefix =
+ (pre ? pre + "\n" : "") +
+ "h".repeat(32_743 - (pre ? pre.length + 1 : 0));
+ const rest =
+ values
+ .slice(visible)
+ .map((p) => progressText(p))
+ .join("\n") || "m".repeat(100);
+ return {
+ full: `${prefix}\n${rest}\n${commandTail}`,
+ saved: `${prefix}\n... command output truncated for persistence ...\n${commandTail}`,
+ };
+ };
+ const scenarios: ScopedProgressScenario[] = [];
+ for (const initialScope of [8, null]) {
+ for (const mode of [
+ "delayed",
+ "early",
+ "exact",
+ "untruncated",
+ "ambiguous",
+ "unadmitted",
+ "new turn",
+ ] as const) {
+ const old = outputs([inventory(9)], 0);
+ const current = outputs(
+ [inventory(8), progress("validation", 1, 8)],
+ 1,
+ );
+ const unresolved = mode === "ambiguous" || mode === "new turn";
+ const reviewed = progress("reporting", 1, unresolved ? 9 : 8);
+ const settled = unresolved
+ ? progress(reviewed.phase, 6, 9)
+ : progress("reporting", 3, 8);
+ const currentText =
+ mode === "untruncated"
+ ? progressText([inventory(8), progress("validation", 1, 8)])
+ : current.full;
+ const currentSaved =
+ mode === "untruncated" ? currentText : current.saved;
+ scenarios.push({
+ name: `delayed inventory (mode=${mode}, initial=${initialScope})`,
+ initialScope,
+ partitions: mode === "unadmitted" ? ["batch"] : undefined,
+ expected: settled,
+ steps: [
+ ["save", "old", old.saved],
+ ["save", "current", currentSaved],
+ ...(mode === "ambiguous"
+ ? ([
+ ["save", "repeated current", currentSaved],
+ ] as ProgressScenarioStep[])
+ : []),
+ ...(mode === "unadmitted"
+ ? []
+ : ([
+ ["poll"],
+ [
+ "scope",
+ mode === "untruncated"
+ ? progress("validation", 1, 8)
+ : inventory(8),
+ ],
+ ] as ProgressScenarioStep[])),
+ ...(mode === "new turn"
+ ? ([["begin"]] as ProgressScenarioStep[])
+ : []),
+ ...(mode === "early"
+ ? ([
+ ["live-changed", "current", currentText],
+ ] as ProgressScenarioStep[])
+ : []),
+ ["save-quiet", "review", progress("reporting", 1, 8)],
+ ["live-changed", "old", old.full],
+ ["poll"],
+ ["resolve"],
+ ...(mode === "early"
+ ? []
+ : ([
+ [
+ mode === "exact" ? "live" : "live-changed",
+ "current",
+ currentText,
+ ],
+ ] as ProgressScenarioStep[])),
+ ["live", "review", progress("reporting", 1, 8)],
+ ["poll"],
+ ["check", reviewed],
+ ["worker", progress("attack_path", 6, 9)],
+ ["poll"],
+ ["check", unresolved ? settled : reviewed],
+ ...(unresolved
+ ? []
+ : ([
+ ["additional-worker", progress("attack_path", 2, 8)],
+ ["poll"],
+ ["check", progress(reviewed.phase, 2, 8)],
+ ["save", "followup", progress("reporting", 3, 8)],
+ ["poll"],
+ ["check", settled],
+ ] as ProgressScenarioStep[])),
+ ],
+ });
+ }
+ }
+ test.each(
+ scenarios.flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ (scenario.partitions ?? (["batch", "each"] as const)).flatMap(
+ (partition) =>
+ [false, true].map((stopBeforeResolution) => ({
+ ...scenario,
+ workerFirst,
+ partition,
+ stopBeforeResolution,
+ })),
+ ),
+ ),
+ ),
+ )(
+ "retains $name (workers first=$workerFirst, stop=$stopBeforeResolution, partition=$partition)",
+ (scenario) => runProgressScenario(scenario),
+ );
+ });
+
+ describe("saved inventory receipts and live prefix proof", () => {
+ const scenarios: ProgressScenario[] = [];
+ const add = (
+ name: string,
+ state: ScanProgress,
+ steps: ProgressScenarioStep[],
+ ) => {
+ const next = progress(
+ state.filesCompleted === state.filesTotal ? "validation" : "reporting",
+ Math.min(state.filesCompleted + 1, state.filesTotal),
+ state.filesTotal,
+ );
+ scenarios.push({
+ name,
+ expected: next,
+ steps: [
+ ...steps,
+ ["poll"],
+ ["check", state],
+ [
+ "worker",
+ progress("attack_path", state.filesTotal + 1, state.filesTotal + 2),
+ ],
+ ["poll"],
+ ["check", state],
+ ["save", "followup", next],
+ ["poll"],
+ ["check", next],
+ ],
+ });
+ };
+ for (const mode of [
+ "changed",
+ "exact",
+ "live first",
+ "inventory only",
+ "repeated source",
+ ] as const) {
+ const values =
+ mode === "inventory only"
+ ? [inventory(9)]
+ : [progress("validation", 1, 9), inventory(9)];
+ const live = mode === "exact" ? "live" : "live-changed";
+ add(
+ `saved inventory precedes its delayed copy (mode=${mode})`,
+ progress("reporting", 9, 9),
+ [
+ ...(mode === "live first"
+ ? ([[live, "batch", values]] as ProgressScenarioStep[])
+ : []),
+ ["save", "batch", values],
+ ["poll"],
+ ["scope", inventory(9)],
+ ["resolve"],
+ ...(mode === "live first"
+ ? []
+ : ([[live, "batch", values]] as ProgressScenarioStep[])),
+ ["save", "report", progress("reporting", 9, 9)],
+ ["live", "report", progress("reporting", 9, 9)],
+ ...(mode === "repeated source"
+ ? ([
+ ["poll"],
+ ["check", progress("reporting", 9, 9)],
+ ["save", "batch", values],
+ ["save", "late expansion", inventory(10)],
+ ] as ProgressScenarioStep[])
+ : []),
+ ],
+ );
+ }
+ for (const mode of [
+ "omitted",
+ "truncated",
+ "complete",
+ "exact",
+ "message",
+ "unproved prefix",
+ ] as const) {
+ const first = progress("validation", 1, 8);
+ const last = progress("reporting", 3, 5);
+ add(
+ `earlier source proof precedes later live coverage (mode=${mode})`,
+ last,
+ [
+ [
+ mode === "unproved prefix" ? "live-changed" : "live",
+ "first",
+ first,
+ ],
+ [
+ mode === "message"
+ ? "live-message"
+ : mode === "exact"
+ ? "live"
+ : "live-changed",
+ "latest",
+ mode === "truncated" ? commandOutput(progressText(last)) : last,
+ ],
+ ["save", "inventory", inventory(5)],
+ ["save", "first", first],
+ ...(mode === "truncated"
+ ? ([
+ ["save", "latest", persistedCommandOutput],
+ ] as ProgressScenarioStep[])
+ : mode === "complete" || mode === "exact"
+ ? ([["save", "latest", last]] as ProgressScenarioStep[])
+ : []),
+ ["poll"],
+ ...(mode === "unproved prefix"
+ ? ([
+ ["check", progress("reporting", 3, 8)],
+ ["resolve"],
+ ["save", "latest", last],
+ ["live", "latest", last],
+ ] as ProgressScenarioStep[])
+ : ([
+ ["check", last],
+ ["resolve"],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ] as ProgressScenarioStep[])),
+ ["worker", progress("attack_path", 5, 8)],
+ ["poll"],
+ ["check", last],
+ ],
+ );
+ }
+ scenarios.push({
+ name: "prefix proof does not replace independent unresolved inventory",
+ expected: progress("reporting", 3, 9),
+ steps: [
+ ["live-changed", "independent", inventory(9)],
+ ["live", "first", progress("validation", 1, 8)],
+ ["live-changed", "latest", progress("reporting", 3, 5)],
+ ["save", "inventory", inventory(5)],
+ ["save", "first", progress("validation", 1, 8)],
+ ["poll"],
+ ["check", progress("reporting", 3, 9)],
+ ["resolve"],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ],
+ });
+ test.each(
+ scenarios.flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ (["batch", "each"] as const).flatMap((partition) =>
+ [false, true].map((stopBeforeResolution) => ({
+ ...scenario,
+ workerFirst,
+ partition,
+ stopBeforeResolution,
+ })),
+ ),
+ ),
+ ),
+ )(
+ "retains $name (workers first=$workerFirst, stop=$stopBeforeResolution, partition=$partition)",
+ (scenario) => runProgressScenario(scenario),
+ );
+ });
+
+ describe("source eligibility and durable inventory proof", () => {
+ const scenarios: ProgressScenario[] = [];
+ const add = (
+ name: string,
+ state: ScanProgress,
+ steps: ProgressScenarioStep[],
+ ) => {
+ const next = progress(
+ "reporting",
+ state.filesCompleted + 1,
+ state.filesTotal,
+ );
+ scenarios.push({
+ name,
+ expected: next,
+ steps: [
+ ...steps,
+ ["poll"],
+ ["check", state],
+ ["save", "followup", next],
+ ["poll"],
+ ["check", next],
+ ],
+ });
+ };
+ for (const changed of [false, true]) {
+ for (const eligible of [false, true]) {
+ const review = progress("validation", 3, 10);
+ const state = eligible ? review : progress("discovery", 2, 5);
+ add(
+ `accepted coverage after recovered scope (changed=${changed}, eligible=${eligible})`,
+ state,
+ [
+ ["live", "initial", inventory(10)],
+ [changed ? "live-changed" : "live", "review", review],
+ ["save", "initial", inventory(10)],
+ ["save", "correction", inventory(eligible ? 10 : 8)],
+ ["save", "review", review],
+ ["save", "repeated", inventory(10)],
+ ["resolve"],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["boundary"],
+ ["save", "final-inventory", inventory(5)],
+ ["poll"],
+ ["scope", eligible ? review : inventory(5)],
+ ["worker", progress("attack_path", 6, eligible ? 12 : 8)],
+ ["poll"],
+ ["scope", eligible ? review : inventory(5)],
+ ["additional-worker", progress("attack_path", 2, 5)],
+ ],
+ );
+ }
+ }
+ for (const variant of [
+ "discovery",
+ "validation",
+ "zero reporting",
+ ] as const) {
+ for (const mode of [
+ "exact",
+ "changed",
+ "omit rejected",
+ "after anchor",
+ ] as const) {
+ const zero = variant === "zero reporting";
+ const total = zero ? 3 : 5;
+ const review = progress(
+ zero ? "validation" : variant,
+ zero ? 6 : variant === "discovery" ? 1 : 3,
+ 8,
+ );
+ const rejected = progress(
+ "reporting",
+ zero ? 0 : variant === "discovery" ? 3 : 4,
+ zero ? 3 : 10,
+ );
+ const live = mode === "exact" ? "live" : "live-changed";
+ add(
+ `inventory witness survives ${variant} (mode=${mode})`,
+ progress(zero ? "reporting" : "discovery", 2, total),
+ [
+ ...(zero
+ ? ([
+ ["live", "initial", inventory(8)],
+ ["save", "initial", inventory(8)],
+ ] as ProgressScenarioStep[])
+ : []),
+ [live, "review", review],
+ ...(mode === "omit rejected" || mode === "after anchor"
+ ? []
+ : ([[live, "rejected", rejected]] as ProgressScenarioStep[])),
+ ["save", "correction", inventory(total)],
+ ["save", "review", review],
+ ["save", "rejected", rejected],
+ ["boundary"],
+ ["resolve"],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ...(mode === "after anchor"
+ ? ([
+ ["poll"],
+ [live, "rejected", rejected],
+ ] as ProgressScenarioStep[])
+ : []),
+ ["poll"],
+ ["scope", inventory(total)],
+ ["worker", progress("attack_path", 6, 8)],
+ ["poll"],
+ ["scope", inventory(total)],
+ ["additional-worker", progress("attack_path", 2, total)],
+ ],
+ );
+ }
+ }
+ test.each(
+ scenarios.flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ (["batch", "staged", "each"] as const).flatMap((partition) =>
+ [false, true].map((stopBeforeResolution) => ({
+ ...scenario,
+ workerFirst,
+ partition,
+ stopBeforeResolution,
+ })),
+ ),
+ ),
+ ),
+ )(
+ "retains $name (workers first=$workerFirst, stop=$stopBeforeResolution, partition=$partition)",
+ (scenario) => runProgressScenario(scenario),
+ );
+ });
+
+ describe("review eligibility and ordered projections", () => {
+ const scenarios: SplitProgressScenario[] = [];
+ const add = (
+ name: string,
+ state: ScanProgress,
+ steps: ProgressScenarioStep[],
+ partitions?: readonly boolean[],
+ ) => {
+ const next =
+ state.filesCompleted < state.filesTotal
+ ? progress("reporting", state.filesCompleted + 1, state.filesTotal)
+ : progress("validation", state.filesCompleted, state.filesTotal);
+ const expected =
+ next.filesCompleted === next.filesTotal
+ ? next
+ : progress(next.phase, state.filesTotal, state.filesTotal);
+ scenarios.push({
+ name,
+ expected,
+ partitions,
+ steps: [
+ ...steps,
+ ["poll"],
+ ["check", state],
+ [
+ "worker",
+ progress("attack_path", state.filesTotal + 1, state.filesTotal + 2),
+ ],
+ ["poll"],
+ ["check", state],
+ ["save", "followup", next],
+ ["poll"],
+ ["check", next],
+ [
+ "additional-worker",
+ progress("attack_path", state.filesTotal, state.filesTotal),
+ ],
+ ["poll"],
+ ["check", expected],
+ ],
+ });
+ };
+ for (const mode of ["exact", "changed", "after inventory"] as const) {
+ for (const eligible of [false, true]) {
+ const initialTotal = eligible ? 7 : 6;
+ const review = progress("discovery", 1, 7);
+ add(
+ `accepted review after scope correction (mode=${mode}, eligible=${eligible})`,
+ eligible ? review : progress("threat_model", 9, 10),
+ [
+ ...(mode !== "after inventory"
+ ? ([
+ [
+ mode === "changed" ? "live-changed" : "live",
+ "review",
+ review,
+ ],
+ ] as ProgressScenarioStep[])
+ : []),
+ ["save", "initial", inventory(initialTotal)],
+ ...(mode === "after inventory"
+ ? ([
+ ["poll"],
+ ["live", "review", review],
+ ] as ProgressScenarioStep[])
+ : []),
+ ["save", "review", review],
+ ["poll"],
+ ["resolve"],
+ ["live", "growth", inventory(10)],
+ ["save", "growth", inventory(10)],
+ ["poll"],
+ ["live", "valid", progress("threat_model", 9, 10)],
+ ["save", "valid", progress("threat_model", 9, 10)],
+ ],
+ );
+ }
+ }
+ for (const mode of [
+ "changed",
+ "exact",
+ "no repeat",
+ "review exact",
+ ] as const) {
+ const live = mode === "exact" ? "live" : "live-changed";
+ add(
+ `repeated inventories around review (mode=${mode})`,
+ progress("reporting", 3, 8),
+ [
+ [live, "first", inventory(10)],
+ ["save", "first", inventory(10)],
+ [
+ mode === "exact" || mode === "review exact"
+ ? "live"
+ : "live-changed",
+ "review",
+ progress("reporting", 3, 8),
+ ],
+ ...(mode === "no repeat"
+ ? []
+ : ([[live, "last", inventory(10)]] as ProgressScenarioStep[])),
+ ["save", "middle", inventory(8)],
+ ["save", "review", progress("reporting", 3, 8)],
+ ...(mode === "no repeat"
+ ? []
+ : ([["save", "last", inventory(10)]] as ProgressScenarioStep[])),
+ ["save", "anchor", "done"],
+ ["resolve"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ["worker", progress("attack_path", 6, 9)],
+ ],
+ );
+ }
+ test.each(
+ scenarios.flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ (scenario.partitions ?? [false, true]).flatMap((split) =>
+ [false, true].map((stopBeforeResolution) => ({
+ ...scenario,
+ workerFirst,
+ split,
+ stopBeforeResolution,
+ })),
+ ),
+ ),
+ ),
+ )(
+ "retains $name (workers first=$workerFirst, stop=$stopBeforeResolution, split=$split)",
+ (scenario) => runProgressScenario(scenario),
+ );
+ });
+
+ describe("inventory authority before scope projection", () => {
+ const scenarios: SplitProgressScenario[] = [];
+ const add = (
+ name: string,
+ state: ScanProgress,
+ steps: ProgressScenarioStep[],
+ partitions?: readonly boolean[],
+ ) => {
+ const next =
+ state.filesCompleted < state.filesTotal
+ ? progress("reporting", state.filesCompleted + 1, state.filesTotal)
+ : progress("validation", state.filesCompleted, state.filesTotal);
+ const expected =
+ next.filesCompleted === next.filesTotal
+ ? next
+ : progress(next.phase, state.filesTotal, state.filesTotal);
+ scenarios.push({
+ name,
+ expected,
+ partitions,
+ steps: [
+ ...steps,
+ ["poll"],
+ ["check", state],
+ [
+ "worker",
+ progress("attack_path", state.filesTotal + 1, state.filesTotal + 2),
+ ],
+ ["poll"],
+ ["check", state],
+ ["save", "followup", next],
+ ["poll"],
+ ["check", next],
+ [
+ "additional-worker",
+ progress("attack_path", state.filesTotal, state.filesTotal),
+ ],
+ ["poll"],
+ ["check", expected],
+ ],
+ });
+ };
+ for (const persisted of ["late", "early", "absent"] as const) {
+ for (const phase of ["reporting", "attack_path"] as const) {
+ add(
+ `saved authority before fallback (persisted=${persisted}, phase=${phase})`,
+ progress("validation", 3, 5),
+ [
+ ["worker", progress("attack_path", 5, 8)],
+ ["poll"],
+ ["live", "late-inventory", inventory(5)],
+ ["save", "initial-inventory", inventory(5)],
+ ["live", "late-parent", progress(phase, 6, 8)],
+ ["save", "review", progress("validation", 3, 5)],
+ ...(persisted === "early"
+ ? ([
+ ["save", "late-inventory", inventory(5)],
+ ["save", "late-parent", progress(phase, 6, 8)],
+ ] as ProgressScenarioStep[])
+ : []),
+ ["poll"],
+ ["check", progress("validation", 3, 5)],
+ ["resolve"],
+ ...(persisted === "late"
+ ? ([
+ ["save", "late-inventory", inventory(5)],
+ ["save", "late-parent", progress(phase, 6, 8)],
+ ] as ProgressScenarioStep[])
+ : []),
+ ],
+ );
+ }
+ }
+ for (const mode of [
+ "bounded",
+ "exact",
+ "review delivered",
+ "prior inventory",
+ ] as const) {
+ add(
+ `bounded inventory after review (mode=${mode})`,
+ mode === "prior inventory"
+ ? progress("validation", 3, 5)
+ : progress("validation", 7, 8),
+ [
+ ["save", "initial", inventory(mode === "prior inventory" ? 5 : 8)],
+ [
+ "save",
+ "review",
+ progress("validation", 3, mode === "prior inventory" ? 5 : 8),
+ ],
+ ["save", "late", inventory(5)],
+ ["save", "final", inventory(8)],
+ ...(mode === "review delivered"
+ ? ([
+ ["live", "review", progress("validation", 3, 8)],
+ ] as ProgressScenarioStep[])
+ : []),
+ [mode === "exact" ? "live" : "live-changed", "late", inventory(5)],
+ ["resolve"],
+ ["live", "final", inventory(8)],
+ ["poll"],
+ ["worker", progress("attack_path", 7, 8)],
+ ],
+ );
+ }
+ test.each(
+ scenarios.flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ (scenario.partitions ?? [false, true]).flatMap((split) =>
+ [false, true].map((stopBeforeResolution) => ({
+ ...scenario,
+ workerFirst,
+ split,
+ stopBeforeResolution,
+ })),
+ ),
+ ),
+ ),
+ )(
+ "retains $name (workers first=$workerFirst, stop=$stopBeforeResolution, split=$split)",
+ (scenario) => runProgressScenario(scenario),
+ );
+ });
+
+ describe("inventory proof across completion intervals", () => {
+ const scenarios: SplitProgressScenario[] = [];
+ const add = (
+ name: string,
+ state: ScanProgress,
+ steps: ProgressScenarioStep[],
+ partitions?: readonly boolean[],
+ ) => {
+ const next =
+ state.filesCompleted < state.filesTotal
+ ? progress("reporting", state.filesCompleted + 1, state.filesTotal)
+ : progress("validation", state.filesCompleted, state.filesTotal);
+ const expected =
+ next.filesCompleted === next.filesTotal
+ ? next
+ : progress(next.phase, state.filesTotal, state.filesTotal);
+ scenarios.push({
+ name,
+ expected,
+ partitions,
+ steps: [
+ ...steps,
+ ["poll"],
+ ["check", state],
+ [
+ "worker",
+ progress("attack_path", state.filesTotal + 1, state.filesTotal + 2),
+ ],
+ ["poll"],
+ ["check", state],
+ ["save", "followup", next],
+ ["poll"],
+ ["check", next],
+ [
+ "additional-worker",
+ progress("attack_path", state.filesTotal, state.filesTotal),
+ ],
+ ["poll"],
+ ["check", expected],
+ ],
+ });
+ };
+ for (const total of [9, 10]) {
+ for (const tail of ["same", "shrink", "none"] as const) {
+ for (const exact of [false, true]) {
+ const reviewed = total === 9 ? 3 : 1;
+ const markers = [
+ inventory(total),
+ progress("validation", reviewed, total),
+ ...(tail === "none"
+ ? []
+ : [inventory(tail === "same" ? total : 5)]),
+ ];
+ add(
+ `eligible inventory before trailing zero (total=${total}, tail=${tail}, exact=${exact})`,
+ progress("reporting", reviewed + 1, total),
+ [
+ [
+ exact ? "live" : "live-changed",
+ "inventory",
+ commandOutput(progressText(markers)),
+ ],
+ ["save", "inventory", persistedCommandOutput],
+ ["poll"],
+ ["save", "anchor", "done"],
+ ["resolve"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ["save", "report", progress("reporting", reviewed + 1, total)],
+ ],
+ );
+ }
+ }
+ }
+ for (const exact of [false, true]) {
+ for (const intermediate of ["complete", "omitted"] as const) {
+ const review = progress("validation", 1, 10);
+ add(
+ `intermediate completion bound (exact=${exact}, review=${intermediate})`,
+ progress("reporting", 3, 10),
+ [
+ [
+ "live-changed",
+ "inventory",
+ commandOutput(progressText(inventory(10))),
+ ],
+ [
+ exact ? "live" : "live-changed",
+ "review",
+ intermediate === "complete"
+ ? review
+ : commandOutput(progressText(review)),
+ ],
+ ["save", "inventory", persistedCommandOutput],
+ [
+ "save",
+ "review",
+ intermediate === "complete" ? review : persistedCommandOutput,
+ ],
+ ...(intermediate === "complete"
+ ? ([
+ ["save", "report", progress("reporting", 3, 10)],
+ ] as ProgressScenarioStep[])
+ : []),
+ ["save", "anchor", "done"],
+ ["resolve"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ...(intermediate === "omitted"
+ ? ([
+ ["save", "report", progress("reporting", 3, 10)],
+ ] as ProgressScenarioStep[])
+ : []),
+ ],
+ );
+ }
+ }
+ for (const exact of [false, true]) {
+ for (const zero of [false, true]) {
+ for (const eligible of [false, true]) {
+ const review = progress("validation", 1, eligible ? 5 : 8);
+ add(
+ `projection witness across zero phase (exact=${exact}, zero=${zero}, eligible=${eligible})`,
+ eligible
+ ? review
+ : progress(zero ? "threat_model" : "discovery", 0, 5),
+ [
+ ["save", "inventory", inventory(5)],
+ [exact ? "live" : "live-changed", "review", review],
+ ["save", "review", review],
+ ...(zero
+ ? ([
+ ["save", "zero", progress("threat_model", 0, 5)],
+ ] as ProgressScenarioStep[])
+ : []),
+ ["save", "anchor", "done"],
+ ["resolve"],
+ ["live", "anchor", "done"],
+ ],
+ );
+ }
+ }
+ }
+ test.each(
+ scenarios.flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ (scenario.partitions ?? [false, true]).flatMap((split) =>
+ [false, true].map((stopBeforeResolution) => ({
+ ...scenario,
+ workerFirst,
+ split,
+ stopBeforeResolution,
+ })),
+ ),
+ ),
+ ),
+ )(
+ "retains $name (workers first=$workerFirst, stop=$stopBeforeResolution, split=$split)",
+ (scenario) => runProgressScenario(scenario),
+ );
+ });
+
+ describe("bounded inventory marker evidence", () => {
+ const scenarios: SplitProgressScenario[] = [];
+ const add = (
+ name: string,
+ state: ScanProgress,
+ steps: ProgressScenarioStep[],
+ partitions?: readonly boolean[],
+ ) => {
+ const next =
+ state.filesCompleted < state.filesTotal
+ ? progress("reporting", state.filesCompleted + 1, state.filesTotal)
+ : progress("validation", state.filesCompleted, state.filesTotal);
+ const expected =
+ next.filesCompleted === next.filesTotal
+ ? next
+ : progress(next.phase, state.filesTotal, state.filesTotal);
+ scenarios.push({
+ name,
+ expected,
+ partitions,
+ steps: [
+ ...steps,
+ ["poll"],
+ ["check", state],
+ [
+ "worker",
+ progress("attack_path", state.filesTotal + 1, state.filesTotal + 2),
+ ],
+ ["poll"],
+ ["check", state],
+ ["save", "followup", next],
+ ["poll"],
+ ["check", next],
+ [
+ "additional-worker",
+ progress("attack_path", state.filesTotal, state.filesTotal),
+ ],
+ ["poll"],
+ ["check", expected],
+ ],
+ });
+ };
+ for (const command of ["changed", "exact"] as const) {
+ const live = command === "changed" ? "live-changed" : "live";
+ add(
+ `bounded inventory after saved review (${command})`,
+ progress(command === "exact" ? "preflight" : "validation", 7, 8),
+ [
+ ["worker", progress("attack_path", 7, 8)],
+ ["poll"],
+ ["save", "review", progress("validation", 2, 5)],
+ ["save", "late", inventory(5)],
+ ["save", "final", inventory(8)],
+ ["poll"],
+ [live, "review", progress("validation", 2, 5)],
+ ["poll"],
+ [live, "late", inventory(5)],
+ ["poll"],
+ [live, "final", inventory(8)],
+ ["save", "anchor", "done"],
+ ["resolve"],
+ ["live", "anchor", "done"],
+ ],
+ );
+ }
+ for (const total of [9, 5]) {
+ for (const delayed of [true, false]) {
+ const markers = [progress("threat_model", 0, 8), inventory(total)];
+ add(
+ `scope-setting phase (total=${total}, delayed=${delayed})`,
+ inventory(total),
+ [
+ ["save", "old", inventory(8)],
+ ["save", "anchor", inventory(8)],
+ ["save", "current", markers],
+ ["poll"],
+ ...(delayed
+ ? ([
+ ["live-changed", "old", inventory(8)],
+ ] as ProgressScenarioStep[])
+ : []),
+ ["live", "anchor", inventory(8)],
+ ["poll"],
+ ["resolve"],
+ ["live", "current", markers],
+ ],
+ );
+ }
+ const messageTotal = total === 9 ? 10 : total;
+ for (const kind of [
+ "omitted message",
+ "persisted message",
+ "command",
+ ] as const) {
+ add(
+ `bounded inventory evidence (${kind}, total=${messageTotal})`,
+ progress("validation", messageTotal - 1, messageTotal),
+ [
+ [
+ kind === "command" ? "live" : "live-message",
+ "inventory",
+ inventory(messageTotal),
+ ],
+ ...(kind === "persisted message"
+ ? ([
+ ["save-message", "inventory", inventory(messageTotal)],
+ ] as ProgressScenarioStep[])
+ : []),
+ ["save", "anchor", "done"],
+ ["resolve"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ [
+ "save",
+ "review",
+ progress("validation", messageTotal - 1, messageTotal),
+ ],
+ ],
+ );
+ }
+ }
+ for (const command of ["changed", "exact"] as const) {
+ for (const before of [true, false]) {
+ const markers = before
+ ? [inventory(9), progress("discovery", 1, 9)]
+ : [progress("discovery", 1, 8), inventory(9)];
+ const total = before ? 9 : 8;
+ add(
+ `omitted command marker order (${command}, inventory before=${before})`,
+ progress(before ? "reporting" : "validation", before ? 4 : 3, total),
+ [
+ [
+ command === "exact" ? "live" : "live-changed",
+ "inventory",
+ commandOutput(progressText(markers)),
+ ],
+ ["save", "inventory", persistedCommandOutput],
+ ["poll"],
+ ["save", "review", progress("validation", 3, total)],
+ ["resolve"],
+ ["live", "review", progress("validation", 3, total)],
+ ["poll"],
+ ["save", "report", progress("reporting", 4, 9)],
+ ],
+ );
+ }
+ }
+ for (const kind of ["message", "command"] as const) {
+ const live = kind === "message" ? "live-message" : "live-changed";
+ add(
+ `separate inventory after omitted review (${kind})`,
+ progress("validation", 3, 8),
+ [
+ [
+ live,
+ "early-review",
+ commandOutput(progressText(progress("discovery", 1, 8))),
+ ],
+ [live, "late-inventory", commandOutput(progressText(inventory(9)))],
+ ...(kind === "command"
+ ? ([
+ ["save", "early-review", persistedCommandOutput],
+ ["save", "late-inventory", persistedCommandOutput],
+ ] as ProgressScenarioStep[])
+ : []),
+ ["save", "anchor", progress("validation", 3, 8)],
+ ["resolve"],
+ ["live", "anchor", progress("validation", 3, 8)],
+ ["poll"],
+ ["save", "report", progress("reporting", 4, 9)],
+ ],
+ );
+ }
+ test.each(
+ scenarios.flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ (scenario.partitions ?? [false, true]).flatMap((split) =>
+ [false, true].map((stopBeforeResolution) => ({
+ ...scenario,
+ workerFirst,
+ split,
+ stopBeforeResolution,
+ })),
+ ),
+ ),
+ ),
+ )(
+ "retains $name (workers first=$workerFirst, stop=$stopBeforeResolution, split=$split)",
+ (scenario) => runProgressScenario(scenario),
+ );
+ });
+
+ describe("inventory occurrence and cutoff revalidation", () => {
+ const scenarios: SplitProgressScenario[] = [];
+ const add = (
+ name: string,
+ state: ScanProgress,
+ steps: ProgressScenarioStep[],
+ partitions?: readonly boolean[],
+ ) => {
+ const next =
+ state.filesCompleted < state.filesTotal
+ ? progress("reporting", state.filesCompleted + 1, state.filesTotal)
+ : progress("validation", state.filesCompleted, state.filesTotal);
+ const expected =
+ next.filesCompleted === next.filesTotal
+ ? next
+ : progress(next.phase, state.filesTotal, state.filesTotal);
+ scenarios.push({
+ name,
+ expected,
+ partitions,
+ steps: [
+ ...steps,
+ ["poll"],
+ ["check", state],
+ [
+ "worker",
+ progress("attack_path", state.filesTotal + 1, state.filesTotal + 2),
+ ],
+ ["poll"],
+ ["check", state],
+ ["save", "followup", next],
+ ["poll"],
+ ["check", next],
+ [
+ "additional-worker",
+ progress("attack_path", state.filesTotal, state.filesTotal),
+ ],
+ ["poll"],
+ ["check", expected],
+ ],
+ });
+ };
+ for (const control of ["dropped", "delivered", "eligible"] as const) {
+ const review = progress("validation", 3, control === "eligible" ? 8 : 10);
+ add(
+ `repeated native inventory (${control})`,
+ control === "eligible" ? review : progress("reporting", 8, 10),
+ [
+ ["save", "initial", inventory(8)],
+ ["live", "initial", inventory(8)],
+ ["save", "expanded", inventory(10)],
+ ["live", "expanded", inventory(10)],
+ ["save", "restored", inventory(8)],
+ ...(control === "delivered"
+ ? ([["live", "restored", inventory(8)]] as ProgressScenarioStep[])
+ : []),
+ ["save", "review", review],
+ ["poll"],
+ ["live", "review", review],
+ ["live", "final-inventory", inventory(10)],
+ ["live", "final-report", progress("reporting", 8, 10)],
+ ["save", "final-inventory", inventory(10)],
+ ["poll"],
+ ["resolve"],
+ ["save", "final-report", progress("reporting", 8, 10)],
+ ],
+ );
+ }
+ for (const control of ["staged", "exact", "single batch"] as const) {
+ add(
+ `review cutoff after stronger inventory proof (${control})`,
+ progress("reporting", 4, 4),
+ [
+ ["save", "old", inventory(5)],
+ ["save", "note", "done"],
+ [control === "exact" ? "live" : "live-changed", "old", inventory(5)],
+ ["live", "final-inventory", inventory(4)],
+ ["live", "final-report", progress("reporting", 4, 4)],
+ ["save", "review", progress("discovery", 3, 7)],
+ ...(control !== "single batch"
+ ? ([["poll"]] as ProgressScenarioStep[])
+ : []),
+ ...(control !== "single batch"
+ ? ([["resolve"]] as ProgressScenarioStep[])
+ : []),
+ ["save", "final-inventory", inventory(4)],
+ ["save", "final-report", progress("reporting", 4, 4)],
+ ["save", "anchor", "done"],
+ ...(control === "single batch"
+ ? ([["resolve"]] as ProgressScenarioStep[])
+ : []),
+ ["live", "anchor", "done"],
+ ],
+ control === "single batch" ? [false] : undefined,
+ );
+ }
+ for (const control of [
+ "delayed anchor",
+ "early anchor",
+ "eligible",
+ ] as const) {
+ const review = progress("discovery", 3, control === "eligible" ? 5 : 7);
+ add(
+ `omitted inventory changes review eligibility (${control})`,
+ progress("reporting", 4, control === "eligible" ? 5 : 4),
+ [
+ ["save", "old", persistedCommandOutput],
+ ["save", "note", "done"],
+ ["live-changed", "old", commandOutput(progressText(inventory(5)))],
+ ...(control === "early anchor"
+ ? ([["live", "note", "done"]] as ProgressScenarioStep[])
+ : []),
+ ["save", "review", review],
+ ["poll"],
+ ["resolve"],
+ ...(control !== "early anchor"
+ ? ([["live", "note", "done"]] as ProgressScenarioStep[])
+ : []),
+ ["live", "final-inventory", inventory(4)],
+ ["live", "final-report", progress("reporting", 4, 4)],
+ ["save", "final-inventory", inventory(4)],
+ ["save", "final-report", progress("reporting", 4, 4)],
+ ["save", "anchor", "finished"],
+ ["live", "anchor", "finished"],
+ ],
+ );
+ }
+ test.each(
+ scenarios.flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ (scenario.partitions ?? [false, true]).flatMap((split) =>
+ [false, true].map((stopBeforeResolution) => ({
+ ...scenario,
+ workerFirst,
+ split,
+ stopBeforeResolution,
+ })),
+ ),
+ ),
+ ),
+ )(
+ "retains $name (workers first=$workerFirst, stop=$stopBeforeResolution, split=$split)",
+ (scenario) => runProgressScenario(scenario),
+ );
+ });
+
+ describe("inventory cutoffs from retained source proof", () => {
+ const scenarios: ProgressScenario[] = [];
+ for (const control of [false, true]) {
+ const finish = (
+ state: ScanProgress,
+ next: ScanProgress,
+ ): ProgressScenarioStep[] => [
+ ["poll"],
+ ["check", state],
+ [
+ "worker",
+ progress("attack_path", state.filesTotal + 1, state.filesTotal + 2),
+ ],
+ ["poll"],
+ ["check", state],
+ ["save", "followup", next],
+ ["poll"],
+ ["check", next],
+ [
+ "additional-worker",
+ progress("attack_path", state.filesTotal, state.filesTotal),
+ ],
+ ["poll"],
+ ["check", progress(next.phase, state.filesTotal, state.filesTotal)],
+ ];
+ scenarios.push(
+ {
+ name: `restore scope after rejecting a provisional inventory (saved baseline=${control})`,
+ expected: progress("reporting", 8, 8),
+ steps: [
+ ...(control
+ ? ([
+ ["save", "initial", inventory(8)],
+ ["poll"],
+ ] as ProgressScenarioStep[])
+ : []),
+ ["worker", progress("attack_path", 2, 5)],
+ ["poll"],
+ ["live", "inventory", inventory(9)],
+ ["poll"],
+ ["save", "review", progress("validation", 3, 8)],
+ ["poll"],
+ ["resolve"],
+ ["save", "inventory", inventory(9)],
+ ...finish(
+ progress("validation", 3, 8),
+ progress("reporting", 4, 8),
+ ),
+ ],
+ },
+ {
+ name: `copy retains admitted source scope (native copy=${control})`,
+ expected: progress("reporting", 6, 6),
+ steps: [
+ ["receipt", inventory(5)],
+ ["live-message", "inventory", inventory(6)],
+ ["live", "review", progress("discovery", 1, 6)],
+ ["resolve"],
+ [
+ control ? "save-message" : "save-response",
+ "inventory",
+ inventory(6),
+ ],
+ ["poll"],
+ ["receipt", progress("reporting", 2, 6)],
+ ...finish(progress("reporting", 2, 6), progress("reporting", 3, 6)),
+ ],
+ },
+ {
+ name: `later live inventory cannot rescope native history (persisted early=${control})`,
+ expected: progress("reporting", 8, 8),
+ steps: [
+ ["save", "oversized", progress("validation", 9, 10)],
+ ["live", "oversized", progress("validation", 9, 10)],
+ ["poll"],
+ ["worker", progress("attack_path", 5, 5)],
+ ["live", "batch", [inventory(10), progress("threat_model", 0, 8)]],
+ ...(control
+ ? ([
+ [
+ "save",
+ "batch",
+ [inventory(10), progress("threat_model", 0, 8)],
+ ],
+ ] as ProgressScenarioStep[])
+ : []),
+ ["poll"],
+ ["live", "current", inventory(8)],
+ ["resolve"],
+ ...(!control
+ ? ([
+ [
+ "save",
+ "batch",
+ [inventory(10), progress("threat_model", 0, 8)],
+ ],
+ ] as ProgressScenarioStep[])
+ : []),
+ ["live", "phase", progress("discovery", 3, 8)],
+ ["save", "current", inventory(8)],
+ ["save", "phase", progress("discovery", 3, 8)],
+ ...finish(
+ progress("threat_model", 5, 8),
+ progress("reporting", 6, 8),
+ ),
+ ],
+ },
+ {
+ name: `bounded omitted review closes inventory admission (exact review=${control})`,
+ expected: progress("reporting", 5, 5),
+ steps: [
+ ["save", "initial", inventory(5)],
+ ["live", "initial", inventory(5)],
+ ["poll"],
+ [
+ control ? "live" : "live-changed",
+ "review",
+ commandOutput(progressText(progress("validation", 3, 5))),
+ ],
+ ["live", "later", [inventory(8), progress("reporting", 3, 8)]],
+ ["save", "review", persistedCommandOutput],
+ ["resolve"],
+ ["save", "later", [inventory(8), progress("reporting", 3, 8)]],
+ ...finish(
+ progress("validation", 3, 5),
+ progress("reporting", 4, 5),
+ ),
+ ],
+ },
+ {
+ name: `inventory after a known review is excluded through bounds (exact inventory=${control})`,
+ expected: progress("reporting", 8, 8),
+ steps: [
+ ["save", "initial", inventory(8)],
+ ["live", "initial", inventory(8)],
+ ["poll"],
+ ["save", "first", progress("attack_path", 6, 8)],
+ ["save", "before", "before"],
+ ["live", "before", "before"],
+ ["save", "late", inventory(10)],
+ [control ? "live" : "live-changed", "late", inventory(10)],
+ ["save", "last", progress("attack_path", 6, 8)],
+ ["live-changed", "last", progress("attack_path", 6, 8)],
+ ["save", "after", "after"],
+ ["resolve"],
+ ["live", "after", "after"],
+ ...finish(
+ progress("attack_path", 6, 8),
+ progress("reporting", 7, 8),
+ ),
+ ],
+ },
+ {
+ name: `earlier eligible review precedes provisional scope (review polled early=${control})`,
+ expected: progress("reporting", 8, 8),
+ steps: [
+ ["save", "initial", inventory(8)],
+ ["poll"],
+ ["worker", progress("attack_path", 2, 5)],
+ ["poll"],
+ ...(control
+ ? ([
+ ["save", "review", progress("validation", 3, 8)],
+ ["poll"],
+ ] as ProgressScenarioStep[])
+ : []),
+ ["live", "inventory", inventory(6)],
+ ["poll"],
+ ...(!control
+ ? ([
+ ["save", "review", progress("validation", 3, 8)],
+ ["poll"],
+ ] as ProgressScenarioStep[])
+ : []),
+ ["resolve"],
+ ["save", "inventory", inventory(6)],
+ ...finish(
+ progress("validation", 3, 8),
+ progress("reporting", 4, 8),
+ ),
+ ],
+ },
+ );
+ }
+ test.each(
+ scenarios.flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ [false, true].flatMap((split) =>
+ [false, true].map((stopBeforeResolution) => ({
+ ...scenario,
+ workerFirst,
+ split,
+ stopBeforeResolution,
+ })),
+ ),
+ ),
+ ),
+ )(
+ "retains $name (workers first=$workerFirst, stop=$stopBeforeResolution, split=$split)",
+ (scenario) => runProgressScenario(scenario),
+ );
+ });
+
+ describe("source proof before inventory admission", () => {
+ const scenarios: ProgressScenario[] = [];
+ for (const exact of [false, true]) {
+ const live = exact ? "live" : "live-changed";
+ const finish = (
+ state: ScanProgress,
+ next: ScanProgress,
+ ): ProgressScenarioStep[] => [
+ ["poll"],
+ ["check", state],
+ [
+ "worker",
+ progress("attack_path", state.filesTotal + 1, state.filesTotal + 2),
+ ],
+ ["poll"],
+ ["check", state],
+ ["save", "followup", next],
+ ["poll"],
+ ["check", next],
+ [
+ "additional-worker",
+ progress(
+ "attack_path",
+ Math.min(next.filesCompleted + 1, next.filesTotal),
+ next.filesTotal,
+ ),
+ ],
+ ["poll"],
+ [
+ "check",
+ next.filesCompleted === next.filesTotal
+ ? next
+ : progress(next.phase, next.filesCompleted + 1, next.filesTotal),
+ ],
+ ];
+ scenarios.push(
+ {
+ name: `newer inventory after an older truncated bound (exact=${exact})`,
+ expected: progress("reporting", 5, 9),
+ steps: [
+ [
+ "live-changed",
+ "older",
+ commandOutput(progressText(inventory(5))),
+ ],
+ [live, "newer", inventory(9)],
+ ["save", "older", persistedCommandOutput],
+ ["save", "newer", inventory(9)],
+ ["save", "anchor", progress("validation", 2, 9)],
+ ["live", "anchor", progress("validation", 2, 9)],
+ ["poll"],
+ ["save", "report", progress("reporting", 3, 9)],
+ ...finish(progress("reporting", 3, 9), progress("reporting", 4, 9)),
+ ],
+ },
+ {
+ name: `review cutoff before a queued later inventory (split callback=${exact})`,
+ expected: progress("reporting", 3, 5),
+ steps: [
+ ["save", "initial", inventory(8)],
+ ["live-changed", "initial", inventory(8)],
+ ["worker", progress("attack_path", 4, 7)],
+ ["poll"],
+ ["save", "scope", inventory(5)],
+ ["save", "review", progress("validation", 1, 5)],
+ ["poll"],
+ ["save", "anchor", inventory(9)],
+ ["live", "review", progress("validation", 1, 5)],
+ ...(exact ? [["poll"] as ProgressScenarioStep] : []),
+ ["live", "anchor", inventory(9)],
+ ...finish(
+ progress("validation", 1, 5),
+ progress("reporting", 2, 5),
+ ),
+ ],
+ },
+ {
+ name: `count-rejected inventory before a matched review (exact=${exact})`,
+ expected: progress("reporting", 3, 5),
+ steps: [
+ ["save", "initial", persistedCommandOutput],
+ ["save", "current", inventory(5)],
+ ["save", "anchor", progress("validation", 1, 5)],
+ [
+ "live-changed",
+ "initial",
+ commandOutput(progressText(inventory(8))),
+ ],
+ ["poll"],
+ [live, "current", inventory(5)],
+ ["live", "anchor", progress("validation", 1, 5)],
+ ...finish(
+ progress("validation", 1, 5),
+ progress("reporting", 2, 5),
+ ),
+ ],
+ },
+ {
+ name: `count-rejected inventory inside a complete projection (exact=${exact})`,
+ expected: progress("reporting", 4, 5),
+ steps: [
+ [
+ "live-changed",
+ "initial",
+ commandOutput(progressText(inventory(9))),
+ ],
+ ["save", "initial", persistedCommandOutput],
+ ["poll"],
+ ["save", "current", [inventory(5), progress("validation", 2, 5)]],
+ ["poll"],
+ [live, "current", [inventory(5), progress("validation", 2, 5)]],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ...finish(
+ progress("validation", 2, 5),
+ progress("reporting", 3, 5),
+ ),
+ ],
+ },
+ {
+ name: `deferred expansion supersedes a truncated bound (exact=${exact})`,
+ expected: progress("reporting", 8, 8),
+ steps: [
+ ["worker", progress("attack_path", 2, 5)],
+ [
+ "live-changed",
+ "initial",
+ commandOutput(progressText(inventory(5))),
+ ],
+ ["save", "initial", persistedCommandOutput],
+ ["poll"],
+ [live, "expansion", [inventory(8), progress("validation", 2, 5)]],
+ ["save", "expansion", [inventory(8), progress("validation", 2, 5)]],
+ ["save", "anchor", progress("reporting", 5, 8)],
+ ["live", "anchor", progress("reporting", 5, 8)],
+ ["poll"],
+ ["save", "report", progress("reporting", 6, 8)],
+ ...finish(progress("reporting", 6, 8), progress("reporting", 7, 8)),
+ ],
+ },
+ {
+ name: `separate rejected completion after scope correction (exact=${exact})`,
+ expected: progress("reporting", 3, 3),
+ steps: [
+ ["save", "initial", inventory(5)],
+ ["poll"],
+ ["worker", progress("attack_path", 4, 5)],
+ ["save", "scope", inventory(3)],
+ ["save", "review", progress("validation", 1, 3)],
+ ["live-changed", "initial", inventory(5)],
+ ["poll"],
+ ["save", "report", persistedCommandOutput],
+ ["save", "anchor", "done"],
+ ["live-changed", "scope", inventory(3)],
+ ["poll"],
+ ["live-changed", "review", progress("validation", 1, 3)],
+ [
+ live,
+ "report",
+ commandOutput(progressText(progress("reporting", 2, 3))),
+ ],
+ ["live", "anchor", "done"],
+ ...finish(progress("reporting", 2, 3), progress("reporting", 3, 3)),
+ ],
+ },
+ {
+ name: `late inventory proof after saved reporting (exact=${exact})`,
+ expected: progress("reporting", 5, 5),
+ steps: [
+ ["save", "older", persistedCommandOutput],
+ ["save", "newer", inventory(5)],
+ [
+ "live-changed",
+ "older",
+ commandOutput(progressText(inventory(8))),
+ ],
+ ["save", "anchor", progress("reporting", 3, 5)],
+ ["poll"],
+ [live, "newer", inventory(5)],
+ ["live", "anchor", progress("reporting", 3, 5)],
+ ...finish(progress("reporting", 3, 5), progress("reporting", 4, 5)),
+ ],
+ },
+ );
+ }
+ scenarios.push(
+ {
+ name: "inventory proof after review cannot expand admitted scope",
+ expected: progress("reporting", 2, 5),
+ steps: [
+ ["save", "initial", inventory(5)],
+ ["live", "initial", inventory(5)],
+ ["save", "review", progress("validation", 1, 5)],
+ ["live", "review", progress("validation", 1, 5)],
+ ["poll"],
+ ["live-changed", "late", inventory(9)],
+ ["save", "late", inventory(9)],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ["check", progress("validation", 1, 5)],
+ ["worker", progress("attack_path", 6, 9)],
+ ["poll"],
+ ["check", progress("validation", 1, 5)],
+ ["save", "followup", progress("reporting", 2, 5)],
+ ],
+ },
+ {
+ name: "an omitted rejected phase cannot replace later exact progress",
+ expected: progress("reporting", 3, 3),
+ steps: [
+ ["save", "initial", inventory(5)],
+ ["poll"],
+ ["worker", progress("attack_path", 4, 5)],
+ ["poll"],
+ ["save", "scope", inventory(3)],
+ ["live-changed", "scope", inventory(3)],
+ [
+ "live-changed",
+ "old-report",
+ commandOutput(progressText(progress("reporting", 2, 3))),
+ ],
+ ["save", "old-report", persistedCommandOutput],
+ ["save", "anchor", progress("validation", 2, 3)],
+ ["live", "anchor", progress("validation", 2, 3)],
+ ["poll"],
+ ["check", progress("validation", 2, 3)],
+ ["save", "followup", progress("reporting", 3, 3)],
+ ],
+ },
+ );
+ test.each(
+ scenarios.flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ [false, true].flatMap((split) =>
+ [false, true].map((stopBeforeResolution) => ({
+ ...scenario,
+ workerFirst,
+ split,
+ stopBeforeResolution,
+ })),
+ ),
+ ),
+ ),
+ )(
+ "retains $name (workers first=$workerFirst, stop=$stopBeforeResolution, split=$split)",
+ (scenario) =>
+ runProgressScenario(scenario, {
+ resolutionIndex: lastLiveAnchor(scenario.steps),
+ pollReceipts: false,
+ }),
+ );
+ });
+
+ describe("inventory authority through stronger source proof", () => {
+ const scenarios: ProgressScenario[] = [
+ ...[false, true].map((exact): ProgressScenario => ({
+ name: `bounded omitted inventory expansion (exact=${exact})`,
+ expected: progress("reporting", 10, 10),
+ steps: [
+ [
+ exact ? "live" : "live-changed",
+ "inventory",
+ commandOutput(progressText(inventory(10))),
+ ],
+ ["save", "inventory", persistedCommandOutput],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ["save", "review", progress("validation", 9, 10)],
+ ["poll"],
+ ["check", progress("validation", 9, 10)],
+ ["worker", progress("attack_path", 10, 11)],
+ ["poll"],
+ ["check", progress("validation", 9, 10)],
+ ["save", "report", progress("reporting", 10, 10)],
+ ],
+ })),
+ ...[false, true].map((exact): ProgressScenario => ({
+ name: `newer inventory during older-scope corroboration (exact=${exact})`,
+ expected: progress("validation", 5, 9),
+ steps: [
+ [exact ? "live" : "live-changed", "older", inventory(3)],
+ ["save", "older", inventory(3)],
+ [exact ? "live" : "live-changed", "newer", inventory(9)],
+ ["save", "newer", inventory(9)],
+ ["save", "review", progress("validation", 1, 3)],
+ ["live", "review", progress("validation", 1, 3)],
+ ["poll"],
+ ["check", progress("validation", 1, 9)],
+ ["save", "followup", progress("validation", 2, 9)],
+ ["poll"],
+ ["check", progress("validation", 2, 9)],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["worker", progress("attack_path", 5, 9)],
+ ],
+ })),
+ ...["bounded", "exact", "eligible", "discovery"].map(
+ (control): ProgressScenario => {
+ const review = progress(
+ control === "discovery" ? "discovery" : "validation",
+ 2,
+ control === "eligible" ? 3 : 8,
+ );
+ const settled =
+ control === "eligible"
+ ? progress("validation", 2, 3)
+ : inventory(3);
+ return {
+ name: `preceding inventory before bounded review (${control})`,
+ expected: progress("reporting", 3, 3),
+ steps: [
+ ["save", "inventory", inventory(3)],
+ [control === "exact" ? "live" : "live-changed", "review", review],
+ ["save", "review", review],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ["check", settled],
+ ["worker", progress("attack_path", 6, 8)],
+ ["poll"],
+ ["check", settled],
+ ["save", "followup", progress("reporting", 3, 3)],
+ ],
+ };
+ },
+ ),
+ ...[false, true].map((withoutOversized): ProgressScenario => {
+ const first = withoutOversized
+ ? [inventory(8)]
+ : [inventory(8), progress("validation", 2, 10)];
+ const next = [inventory(10), progress("reporting", 5, 10)];
+ return {
+ name: `exact inventory before a newer live scope (without oversized=${withoutOversized})`,
+ expected: progress("validation", 7, 10),
+ steps: [
+ ["live", "first", first],
+ ["save", "first", first],
+ ["live", "next", next],
+ ["poll"],
+ ["save", "next", next],
+ ["poll"],
+ ["check", progress("reporting", 5, 10)],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["save", "followup", progress("validation", 6, 10)],
+ ["poll"],
+ ["check", progress("validation", 6, 10)],
+ ["worker", progress("attack_path", 7, 10)],
+ ],
+ };
+ }),
+ ...[false, true].map((nativeInventory): ProgressScenario => {
+ const steps: ProgressScenarioStep[] = [
+ ["live-message", "inventory", inventory(8)],
+ ["save-response", "inventory", inventory(8)],
+ ];
+ if (nativeInventory)
+ steps.push(["save-message", "inventory", inventory(8)]);
+ steps.push(
+ ["poll"],
+ ["save-response", "corrected", inventory(10)],
+ ["save-response", "report", progress("reporting", 3, 10)],
+ ["poll"],
+ ["check", progress("reporting", 3, 10)],
+ ["save-message", "anchor", "Done."],
+ ["live-message", "anchor", "Done."],
+ ["poll"],
+ ["check", progress("reporting", 3, 10)],
+ ["save-response", "followup", progress("validation", 5, 10)],
+ ["poll"],
+ ["check", progress("validation", 5, 10)],
+ ["worker", progress("attack_path", 7, 10)],
+ );
+ return {
+ name: `response-only authority after an anchor (native inventory=${nativeInventory})`,
+ expected: progress("validation", 7, 10),
+ steps,
+ };
+ }),
+ ];
+ test.each(
+ scenarios.flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ [false, true].flatMap((split) =>
+ [false, true].map((stopBeforeResolution) => ({
+ ...scenario,
+ workerFirst,
+ split,
+ stopBeforeResolution,
+ })),
+ ),
+ ),
+ ),
+ )(
+ "retains $name (workers first=$workerFirst, stop=$stopBeforeResolution, split=$split)",
+ (scenario) =>
+ runProgressScenario(scenario, {
+ resolutionIndex: lastLiveAnchor(scenario.steps),
+ pollReceipts: false,
+ }),
+ );
+ });
+
+ describe("inventory authority across source partitions", () => {
+ const partitioned: ProgressScenario[] = [6, 7].flatMap((total) =>
+ ["oversized", "without-oversized", "eligible-review"].flatMap((control) =>
+ Array.from({ length: 8 }, (_, partition) => {
+ const final = progress(
+ total === 6 ? "validation" : "reporting",
+ total === 6 ? 3 : 2,
+ total,
+ );
+ const rows = [
+ inventory(5),
+ progress("validation", 3, control === "eligible-review" ? 5 : 8),
+ inventory(total),
+ final,
+ ];
+ const steps: ProgressScenarioStep[] = [
+ ["worker", progress("attack_path", 6, 8)],
+ ];
+ for (const [index, row] of rows.entries()) {
+ if (!(control === "without-oversized" && index === 1))
+ steps.push(["save", `row-${index}`, row]);
+ if (index === rows.length - 1 || (partition & (1 << index)) !== 0)
+ steps.push(["poll"]);
+ }
+ return {
+ name: `${total}-file prefix (${control}, partition=${partition})`,
+ expected:
+ control === "eligible-review"
+ ? progress("validation", 3, 5)
+ : final,
+ steps,
+ };
+ }),
+ ),
+ );
+ const delayed: ProgressScenario[] = [
+ {
+ name: "an exact message uses each source prefix once",
+ expected: progress("reporting", 2, 8),
+ steps: [
+ ["save", "initial", inventory(5)],
+ ["live", "initial", inventory(5)],
+ ["poll"],
+ [
+ "live-message",
+ "message",
+ [
+ progress("validation", 3, 8),
+ inventory(8),
+ progress("reporting", 2, 8),
+ ],
+ ],
+ [
+ "save-message",
+ "message",
+ [
+ progress("validation", 3, 8),
+ inventory(8),
+ progress("reporting", 2, 8),
+ ],
+ ],
+ ["poll"],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ] as const,
+ },
+ {
+ name: "bounded raw review uses its preceding scope",
+ expected: progress("validation", 2, 6),
+ steps: [
+ ["save", "initial", inventory(8)],
+ ["live", "initial", inventory(8)],
+ ["poll"],
+ [
+ "live",
+ "displayed",
+ [progress("threat_model", 0, 5), progress("validation", 3, 8)],
+ ],
+ ["save", "preceding", inventory(5)],
+ [
+ "save",
+ "original",
+ [progress("threat_model", 0, 5), progress("validation", 3, 8)],
+ ],
+ ["save", "later", inventory(6)],
+ ["save", "review", progress("validation", 2, 6)],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ] as const,
+ },
+ {
+ name: "admitted saved coverage before an unresolved command boundary",
+ expected: progress("reporting", 4, 8),
+ steps: [
+ ["live", "displayed", progress("validation", 3, 8)],
+ ["receipt", progress("reporting", 4, 8)],
+ ["poll"],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ["save", "late inventory", inventory(5)],
+ ["save", "late review", progress("validation", 1, 5)],
+ ] as const,
+ },
+ ...[
+ { older: 5, current: 8, count: 1 },
+ { older: 8, current: 10, count: 3 },
+ ].flatMap(({ older, current, count }) =>
+ [false, true].map((reviewLocated) => {
+ const review = progress("validation", count, current);
+ const steps: ProgressScenarioStep[] = [
+ ["live", "older displayed", inventory(older)],
+ ["save", "older", inventory(older)],
+ ["poll"],
+ ["live", "current", inventory(current)],
+ ["live", reviewLocated ? "review" : "review displayed", review],
+ ["save", "current", inventory(current)],
+ ];
+ if (reviewLocated) steps.push(["save", "review", review]);
+ steps.push(["poll"], ["check", review]);
+ if (!reviewLocated) steps.push(["save", "review", review]);
+ steps.push(["save", "anchor", "done"], ["live", "anchor", "done"]);
+ return {
+ name: `accepted ${older}-to-${current} growth (review located=${reviewLocated})`,
+ expected: review,
+ steps,
+ };
+ }),
+ ),
+ ...["provisional", "without-zero", "exact-review"].map((control) => {
+ const review = progress("reporting", 3, 8);
+ const steps: ProgressScenarioStep[] = [
+ [
+ "live",
+ control === "exact-review" ? "review" : "review displayed",
+ review,
+ ],
+ ["save", "smaller", inventory(5)],
+ ];
+ if (control !== "without-zero")
+ steps.push(["save", "zero", progress("threat_model", 0, 5)]);
+ steps.push(
+ ["save", "current", inventory(8)],
+ ["poll"],
+ ["save", "review", review],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ );
+ return {
+ name: `unpositioned review (${control})`,
+ expected: review,
+ steps,
+ };
+ }),
+ ...[
+ "repeated-zero",
+ "without-repeat",
+ "full-prefix",
+ "full-output",
+ "exact-command",
+ ].map((control) => {
+ const first = progressText(inventory(9));
+ const review = progress("validation", 3, 9);
+ const markers = [first, progressText(review)];
+ if (control !== "without-repeat") markers.push(first);
+ const prefixMarkers =
+ control === "full-prefix" ? markers.join("\n") : first;
+ const prefix =
+ prefixMarkers + "\n" + "h".repeat(32_743 - prefixMarkers.length - 1);
+ const middle =
+ control === "full-prefix"
+ ? "details" + "m".repeat(128)
+ : markers.slice(1).join("\n");
+ const output =
+ control === "full-output"
+ ? markers.join("\n")
+ : `${prefix}\n${middle}\n${commandTail}`;
+ const persisted = `${prefix}\n... command output truncated for persistence ...\n${commandTail}`;
+ return {
+ name: `command progress sequence (${control})`,
+ expected: review,
+ steps: [
+ [
+ "live",
+ control === "exact-command" ? "original" : "displayed",
+ output,
+ ],
+ [
+ "save",
+ "original",
+ control === "full-output" ? output : persisted,
+ ],
+ ["save", "smaller", inventory(5)],
+ ["save", "later", progress("reporting", 1, 5)],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ] as const,
+ };
+ }),
+ ].flatMap((scenario) =>
+ [false, true].map((stopBeforeResolution) => ({
+ ...scenario,
+ stopBeforeResolution,
+ })),
+ );
+ test.each(
+ [...partitioned, ...delayed].flatMap((scenario) =>
+ [false, true].map((workerFirst) => ({ ...scenario, workerFirst })),
+ ),
+ )(
+ "retains $name (workers first=$workerFirst, stop=$stopBeforeResolution)",
+ ({ steps, expected, workerFirst, stopBeforeResolution = false }) =>
+ runProgressScenario(
+ { steps, expected, workerFirst, stopBeforeResolution },
+ {
+ resolutionIndex: steps.findLastIndex(
+ (step) => step[0] === "live" && step[1] === "anchor",
+ ),
+ },
+ ),
+ );
+ });
+
+ describe("source eligibility and applied progress", () => {
+ const initial: readonly Step[] = [
+ ["save", "initial", inventory(8)],
+ ["live", "initial", inventory(8)],
+ ["poll"],
+ ];
+ const multi = [inventory(5), progress("validation", 0, 5)];
+ type Step =
+ | readonly [
+ "save" | "live",
+ string,
+ ScanProgress | readonly ScanProgress[] | string,
+ ]
+ | readonly ["worker", ScanProgress]
+ | readonly ["poll"];
+ const scenarios: readonly {
+ name: string;
+ expected: ScanProgress;
+ control?: "oversized" | "late-inventory" | "changed";
+ steps: readonly Step[];
+ }[] = [
+ ...[false, true].map((matched) => ({
+ name: `rejected inventory inside ${matched ? "an exact" : "a bounded"} completion`,
+ expected: progress("threat_model", 0, 5),
+ steps: [
+ ...initial,
+ [
+ "live",
+ matched ? "original" : "changed",
+ [
+ progress("threat_model", 0, 5),
+ progress("validation", 3, 8),
+ inventory(4),
+ ],
+ ],
+ ["save", "earlier inventory", inventory(5)],
+ [
+ "save",
+ "original",
+ [
+ progress("threat_model", 0, 5),
+ progress("validation", 3, 8),
+ inventory(4),
+ ],
+ ],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ] as const,
+ })),
+ {
+ name: "scope-ineligible saved validation",
+ expected: progress("reporting", 3, 5),
+ control: "oversized",
+ steps: [
+ ["live", "review", progress("reporting", 3, 5)],
+ ["save", "oversized", progress("validation", 3, 9)],
+ ["poll"],
+ ["save", "inventory", inventory(5)],
+ ["save", "review", progress("reporting", 3, 5)],
+ ["poll"],
+ ["worker", progress("attack_path", 6, 8)],
+ ["poll"],
+ ],
+ },
+ {
+ name: "scope-ineligible saved positive discovery",
+ expected: progress("validation", 1, 5),
+ control: "oversized",
+ steps: [
+ ...initial,
+ ["save", "oversized", progress("discovery", 1, 10)],
+ ["save", "smaller", inventory(5)],
+ ["live", "review", progress("validation", 1, 5)],
+ ["poll"],
+ ["save", "review", progress("validation", 1, 5)],
+ ["poll"],
+ ["worker", progress("attack_path", 6, 8)],
+ ["poll"],
+ ],
+ },
+ {
+ name: "scope-ineligible live validation before source matching",
+ expected: progress("validation", 3, 5),
+ control: "oversized",
+ steps: [
+ ["live", "oversized", progress("validation", 9, 10)],
+ ["save", "oversized", progress("validation", 9, 10)],
+ ["save", "inventory", inventory(5)],
+ ["live", "review", progress("validation", 3, 5)],
+ ["save", "review", progress("validation", 3, 5)],
+ ["poll"],
+ ["worker", progress("attack_path", 7, 8)],
+ ["poll"],
+ ],
+ },
+ {
+ name: "a rejected inventory after admitted review",
+ expected: progress("validation", 2, 8),
+ control: "late-inventory",
+ steps: [
+ ...initial,
+ ["save", "first", progress("discovery", 1, 8)],
+ ["poll"],
+ ["save", "late-inventory", inventory(5)],
+ ["poll"],
+ ["save", "second", progress("validation", 2, 8)],
+ ["live", "second", progress("validation", 2, 8)],
+ ["poll"],
+ ],
+ },
+ {
+ name: "the pending final marker after worker exclusion",
+ expected: progress("validation", 0, 5),
+ control: "changed",
+ steps: [
+ ["worker", progress("attack_path", 5, 8)],
+ ["poll"],
+ ["live", "changed", multi],
+ ["poll"],
+ ["save", "original", multi],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ],
+ },
+ {
+ name: "inventory before the first admitted review",
+ expected: progress("validation", 2, 5),
+ steps: [
+ ...initial,
+ ["save", "inventory", inventory(5)],
+ ["save", "first", progress("discovery", 1, 5)],
+ ["poll"],
+ ["save", "second", progress("validation", 2, 5)],
+ ["live", "second", progress("validation", 2, 5)],
+ ["poll"],
+ ],
+ },
+ {
+ name: "a rejected positive marker after legitimate scope growth",
+ expected: progress("validation", 9, 10),
+ steps: [
+ ...initial,
+ ["live", "review", progress("validation", 9, 10)],
+ ["save", "inventory", inventory(10)],
+ ["save", "review", progress("validation", 9, 10)],
+ ["poll"],
+ ],
+ },
+ {
+ name: "eligible worker coverage ahead of a zero marker",
+ expected: progress("preflight", 5, 5),
+ steps: [
+ ["worker", progress("attack_path", 5, 5)],
+ ["poll"],
+ ["live", "changed", multi],
+ ["poll"],
+ ["save", "original", multi],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ],
+ },
+ {
+ name: "an oversized final marker that remains unaccepted",
+ expected: inventory(5),
+ steps: [
+ ["worker", progress("attack_path", 5, 8)],
+ ["poll"],
+ ["live", "changed", [inventory(5), progress("validation", 9, 10)]],
+ ["poll"],
+ ["save", "original", [inventory(5), progress("validation", 9, 10)]],
+ ["save", "anchor", "done"],
+ ["live", "anchor", "done"],
+ ["poll"],
+ ],
+ },
+ ];
+ test.each(
+ scenarios.flatMap((scenario) =>
+ (scenario.control === undefined ? [false] : [false, true]).flatMap(
+ (causalControl) =>
+ [false, true].flatMap((workerFirst) =>
+ [false, true].map((stopBeforeResolution) => ({
+ ...scenario,
+ causalControl,
+ workerFirst,
+ stopBeforeResolution,
+ })),
+ ),
+ ),
+ ),
+ )(
+ "reconciles $name (workers first=$workerFirst, stop=$stopBeforeResolution, control=$causalControl)",
+ ({
+ steps: originalSteps,
+ expected,
+ control,
+ causalControl,
+ workerFirst,
+ stopBeforeResolution,
+ }) => {
+ const steps: readonly Step[] = !causalControl
+ ? originalSteps
+ : control === "changed"
+ ? originalSteps.map((step) =>
+ step[0] === "live" && step[1] === "changed"
+ ? (["live", "original", step[2]] as const)
+ : step,
+ )
+ : originalSteps.filter((step) => step[1] !== control);
+ const anchor = steps.findLastIndex(
+ (step) =>
+ (step[0] === "save" || step[0] === "live") && step[1] === "anchor",
+ );
+ return runProgressScenario(
+ { steps, expected, workerFirst, stopBeforeResolution },
+ {
+ resolutionIndex:
+ anchor === -1
+ ? steps.findLastIndex((step) => step[0] === "save")
+ : anchor,
+ },
+ );
+ },
+ );
+ });
+
+ test.each(
+ [
+ "drained phase",
+ "drained growth",
+ "drained shrink",
+ "omitted phase",
+ "omitted growth",
+ "omitted shrink",
+ "pending inventory",
+ "pending phase",
+ ].flatMap((scenario) =>
+ [false, true].flatMap((changedDisplay) =>
+ [false, true].map((workerFirst) => ({
+ scenario,
+ changedDisplay,
+ workerFirst,
+ })),
+ ),
+ ),
+ )(
+ "orders persisted command evidence through repeated polls ($scenario, changed=$changedDisplay, workers first=$workerFirst)",
+ async ({ scenario, changedDisplay, workerFirst }) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ let tracker: ScanCostTracker | undefined;
+ const originalStart = ScanCostTracker.prototype.start;
+ const starting = spyOn(
+ ScanCostTracker.prototype,
+ "start",
+ ).mockImplementation(function (this: ScanCostTracker, threadId: string) {
+ originalStart.call(this, threadId);
+ if (threadId === "thread-1") tracker = this;
+ });
+ let parentPath = "";
+ let workerPath = "";
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ const entries = await originalReaddir(...args);
+ if (String(args[0]) !== dirname(parentPath)) return entries;
+ const first = basename(workerFirst ? workerPath : parentPath);
+ return entries.toSorted(
+ (left, right) =>
+ Number(String(right.name) === first) -
+ Number(String(left.name) === first),
+ );
+ }) as typeof originalReaddir);
+ const initial: ScanProgress = scenario.endsWith("phase")
+ ? { phase: "validation", filesCompleted: 3, filesTotal: 8 }
+ : {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: scenario.endsWith("shrink") ? 9 : 8,
+ };
+ const expected: ScanProgress =
+ scenario === "pending phase"
+ ? initial
+ : scenario.endsWith("phase")
+ ? { ...initial, phase: "reporting" }
+ : { ...initial, filesTotal: scenario.endsWith("growth") ? 9 : 8 };
+ const text = (progress: ScanProgress) =>
+ progressMarker(
+ progress.phase,
+ progress.filesCompleted,
+ progress.filesTotal,
+ );
+ const display = (command: string) =>
+ changedDisplay ? `${command} displayed` : command;
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ parentPath = await writeUsageSession(codexHome, "thread-1", {});
+ workerPath = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ const save = (command: string, output: string) =>
+ appendFile(
+ parentPath,
+ jsonLines([nativeCommand(command, output, command)]) + "\n",
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ expect(tracker).toBeDefined();
+ // Control polling through the real tracker while keeping the API's
+ // source, inventory, and count admission callback in the loop.
+ await tracker!.stop();
+ if (scenario.startsWith("pending")) {
+ yield completedCommand(
+ display("first"),
+ text(initial),
+ "live-first",
+ );
+ await save("first", text(initial));
+ await tracker!.refresh();
+ yield completedCommand(
+ display("last"),
+ text(initial),
+ "live-last",
+ );
+ await tracker!.refresh();
+ await save(
+ "middle",
+ scenario === "pending phase"
+ ? progressMarker("reporting", 3, 8)
+ : progressMarker("discovery", 0, 9),
+ );
+ await tracker!.refresh();
+ await save("last", text(initial));
+ if (scenario === "pending phase") {
+ await save("anchor", "Batch finished.");
+ yield completedCommand(
+ "anchor",
+ "Batch finished.",
+ "live-anchor",
+ );
+ }
+ await tracker!.refresh();
+ } else {
+ await save(
+ "initial",
+ scenario.startsWith("omitted")
+ ? persistedCommandOutput
+ : text(initial),
+ );
+ await save("anchor", "Batch finished.");
+ await tracker!.refresh();
+ yield completedCommand(
+ display("initial"),
+ scenario.startsWith("omitted")
+ ? commandOutput(text(initial))
+ : text(initial),
+ "live-initial",
+ );
+ yield completedCommand(
+ "anchor",
+ "Batch finished.",
+ "live-anchor",
+ );
+ await save("final", text(expected));
+ }
+ if (scenario.endsWith("shrink") || scenario === "pending inventory")
+ await appendFile(
+ workerPath,
+ jsonLines([
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "worker-progress",
+ output: progressMarker("attack_path", 5, 9),
+ },
+ },
+ ]) + "\n",
+ );
+ await tracker!.refresh();
+ await tracker!.refresh();
+ await tracker!.stop();
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ });
+ expect(updates.at(-1)).toEqual(expected);
+ await tracker!.refresh();
+ await tracker!.stop();
+ expect(updates.at(-1)).toEqual(expected);
+ } finally {
+ await client.close();
+ starting.mockRestore();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each([false, true])(
+ "restores saved scope after a delayed live inventory fails the API count guard (workers first: %p)",
+ async (workerFirst) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const pollAllowed = Promise.withResolvers<void>();
+ const initialRead = Promise.withResolvers<void>();
+ const finalRead = Promise.withResolvers<void>();
+ const workerRead = Promise.withResolvers<void>();
+ const workerSeen = Promise.withResolvers<void>();
+ let holdPoll = true;
+ let parentPath = "";
+ let workerPath = "";
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ if (holdPoll && String(args[0]) === join(codexHome, "sessions"))
+ await pollAllowed.promise;
+ const entries = await originalReaddir(...args);
+ if (String(args[0]) !== dirname(parentPath)) return entries;
+ const first = basename(workerFirst ? workerPath : parentPath);
+ return entries.toSorted(
+ (left, right) =>
+ Number(String(right.name) === first) -
+ Number(String(left.name) === first),
+ );
+ }) as typeof originalReaddir);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ parentPath = await writeUsageSession(codexHome, "thread-1", {});
+ workerPath = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ const initial = progressMarker("discovery", 0, 8);
+ const larger = progressMarker("discovery", 0, 9);
+ await appendFile(
+ parentPath,
+ jsonLines([nativeCommand("initial", initial, "initial")]) + "\n",
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ yield completedCommand("initial changed", initial, "live-initial");
+ holdPoll = false;
+ pollAllowed.resolve();
+ await initialRead.promise;
+ await appendFile(
+ parentPath,
+ jsonLines([
+ nativeCommand("larger", larger, "larger"),
+ nativeCommand("final", initial, "final"),
+ ]) + "\n",
+ );
+ await appendFile(
+ workerPath,
+ jsonLines([
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "worker-progress",
+ output: progressMarker("attack_path", 5, 9),
+ },
+ },
+ ]) + "\n",
+ );
+ await Promise.all([finalRead.promise, workerRead.promise]);
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 8,
+ });
+ yield completedCommand("larger changed", larger, "live-larger");
+ await workerSeen.promise;
+ yield completedCommand("final", initial, "live-final");
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => {
+ updates.push(update);
+ if (
+ update.phase === "discovery" &&
+ update.filesCompleted === 5 &&
+ update.filesTotal === 9
+ )
+ workerSeen.resolve();
+ },
+ onSessionEvent: ({ event }) => {
+ const payload = event["payload"] as {
+ item?: { id?: string };
+ call_id?: string;
+ };
+ if (payload.item?.id === "initial") initialRead.resolve();
+ if (payload.item?.id === "final") finalRead.resolve();
+ if (payload.call_id === "worker-progress") workerRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 8,
+ });
+ } finally {
+ holdPoll = false;
+ pollAllowed.resolve();
+ initialRead.resolve();
+ finalRead.resolve();
+ workerRead.resolve();
+ workerSeen.resolve();
+ clearInterval(keepAlive);
+ await client.close();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each(
+ ["older-snapshot", "later-inventory"].flatMap((scenario) =>
+ [false, true].flatMap((workerFirst) =>
+ [false, true].map((changedDisplay) => ({
+ scenario,
+ workerFirst,
+ changedDisplay,
+ })),
+ ),
+ ),
+ )(
+ "retains and resolves inventory through old snapshots (scenario=$scenario, workerFirst=$workerFirst, changed=$changedDisplay)",
+ async ({ scenario, workerFirst, changedDisplay }) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const pollAllowed = Promise.withResolvers<void>();
+ const closeEntered = Promise.withResolvers<void>();
+ const closeReleased = Promise.withResolvers<void>();
+ const currentRead = Promise.withResolvers<void>();
+ let holdPoll = true;
+ let pauseClose = true;
+ let parentPath = "";
+ let workerPath = "";
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ if (holdPoll && String(args[0]) === join(codexHome, "sessions"))
+ await pollAllowed.promise;
+ const entries = await originalReaddir(...args);
+ if (String(args[0]) === dirname(parentPath)) {
+ const first = basename(workerFirst ? workerPath : parentPath);
+ return entries.toSorted(
+ (left, right) =>
+ Number(String(right.name) === first) -
+ Number(String(left.name) === first),
+ );
+ }
+ return entries;
+ }) as typeof originalReaddir);
+ const originalOpen = fsPromises.open;
+ const opening = spyOn(fsPromises, "open").mockImplementation((async (
+ ...args: Parameters<typeof originalOpen>
+ ) => {
+ const handle = await originalOpen(...args);
+ if (String(args[0]) !== parentPath) return handle;
+ const close = handle.close.bind(handle);
+ handle.close = async () => {
+ if (pauseClose) {
+ pauseClose = false;
+ closeEntered.resolve();
+ await closeReleased.promise;
+ }
+ return close();
+ };
+ return handle;
+ }) as typeof originalOpen);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ parentPath = await writeUsageSession(codexHome, "thread-1", {});
+ workerPath = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ const inventory = progressMarker("discovery", 0, 9);
+ const current = nativeCommand(
+ ["printf", "sk-" + "a".repeat(32)],
+ inventory,
+ "current",
+ );
+ const other = nativeCommand(
+ "other-inventory",
+ progressMarker("discovery", 0, 8),
+ "other",
+ );
+ const workerReceipt = (count: number) => ({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: `worker-${count}`,
+ output: progressMarker("attack_path", count, 9),
+ },
+ });
+ await appendFile(
+ parentPath,
+ jsonLines(
+ scenario === "older-snapshot" ? [other] : [current, other],
+ ) + "\n",
+ );
+ await appendFile(workerPath, jsonLines([workerReceipt(5)]) + "\n");
+ holdPoll = false;
+ pollAllowed.resolve();
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await closeEntered.promise;
+ if (scenario === "older-snapshot")
+ await appendFile(parentPath, jsonLines([current]) + "\n");
+ yield completedCommand(
+ changedDisplay
+ ? "printf [REDACTED_SECRET]"
+ : "printf sk-" + "a".repeat(32),
+ inventory,
+ "item_current",
+ );
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 9,
+ });
+ closeReleased.resolve();
+ await currentRead.promise;
+ const total = scenario === "older-snapshot" ? 9 : 8;
+ const review = progressMarker("validation", 5, total);
+ await appendFile(
+ parentPath,
+ jsonLines([nativeCommand("review", review, "review")]) + "\n",
+ );
+ yield completedCommand("review", review, "item_review");
+ await appendFile(workerPath, jsonLines([workerReceipt(6)]) + "\n");
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => updates.push(update),
+ onSessionEvent: ({ event }) => {
+ if (
+ (event["payload"] as { item?: { id?: string } }).item?.id ===
+ "current"
+ )
+ currentRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual(
+ scenario === "older-snapshot"
+ ? { phase: "validation", filesCompleted: 6, filesTotal: 9 }
+ : { phase: "validation", filesCompleted: 5, filesTotal: 8 },
+ );
+ if (scenario === "older-snapshot") {
+ const accepted = updates.findIndex(
+ (update) => update.filesTotal === 9,
+ );
+ expect(accepted).toBeGreaterThanOrEqual(0);
+ expect(
+ updates.slice(accepted).every((update) => update.filesTotal === 9),
+ ).toBe(true);
+ }
+ } finally {
+ holdPoll = false;
+ pauseClose = false;
+ pollAllowed.resolve();
+ closeReleased.resolve();
+ currentRead.resolve();
+ clearInterval(keepAlive);
+ await client.close();
+ opening.mockRestore();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each([false, true])(
+ "recovers worker coverage when a newer saved inventory returns to a live total (changed=%s)",
+ async (changedDisplay) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const pollAllowed = Promise.withResolvers<void>();
+ const workerSeen = Promise.withResolvers<void>();
+ const smallerSeen = Promise.withResolvers<void>();
+ const latestRead = Promise.withResolvers<void>();
+ let holdPoll = true;
+ const originalReaddir = fsPromises.readdir;
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ if (holdPoll && String(args[0]) === join(codexHome, "sessions"))
+ await pollAllowed.promise;
+ return originalReaddir(...args);
+ }) as typeof originalReaddir);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const parent = await writeUsageSession(codexHome, "thread-1", {});
+ const worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ const inventory = progressMarker("discovery", 0, 9);
+ const workerReceipt = (count: number) => ({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: `worker-${count}`,
+ output: progressMarker("attack_path", count, 9),
+ },
+ });
+ await appendFile(
+ parent,
+ jsonLines([
+ nativeCommand(
+ ["printf", "sk-" + "a".repeat(32)],
+ inventory,
+ "initial-nine",
+ ),
+ ]) + "\n",
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ yield completedCommand(
+ changedDisplay
+ ? "printf [REDACTED_SECRET]"
+ : "printf sk-" + "a".repeat(32),
+ inventory,
+ "item_initial_nine",
+ );
+ await appendFile(worker, jsonLines([workerReceipt(5)]) + "\n");
+ holdPoll = false;
+ pollAllowed.resolve();
+ await workerSeen.promise;
+ // A later exact message bounds the changed command's source
+ // interval without assigning an equal-output inventory occurrence.
+ const anchor = "Inventory batch finished.";
+ await appendFile(
+ parent,
+ jsonLines([
+ {
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ id: "inventory-anchor",
+ content: [{ type: "Text", text: anchor }],
+ },
+ },
+ },
+ ]) + "\n",
+ );
+ yield {
+ type: "item.completed",
+ item: { type: "agent_message", id: "item_anchor", text: anchor },
+ };
+ await appendFile(
+ parent,
+ jsonLines([
+ nativeCommand(
+ "later-eight",
+ progressMarker("discovery", 0, 8),
+ "later-eight",
+ ),
+ ]) + "\n",
+ );
+ await smallerSeen.promise;
+ await appendFile(
+ parent,
+ jsonLines([
+ nativeCommand("latest-nine", inventory, "latest-nine"),
+ ]) + "\n",
+ );
+ await latestRead.promise;
+ await appendFile(worker, jsonLines([workerReceipt(6)]) + "\n");
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (update) => {
+ updates.push(update);
+ if (update.filesCompleted === 5 && update.filesTotal === 9)
+ workerSeen.resolve();
+ if (
+ update.phase === "discovery" &&
+ update.filesCompleted === 0 &&
+ update.filesTotal === 8
+ )
+ smallerSeen.resolve();
+ },
+ onSessionEvent: ({ event }) => {
+ if (
+ (event["payload"] as { item?: { id?: string } }).item?.id ===
+ "latest-nine"
+ )
+ latestRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: 6,
+ filesTotal: 9,
+ });
+ const smaller = updates.findIndex(
+ (update) =>
+ update.phase === "discovery" &&
+ update.filesCompleted === 0 &&
+ update.filesTotal === 8,
+ );
+ expect(smaller).toBeGreaterThanOrEqual(0);
+ expect(
+ updates
+ .slice(smaller + 1)
+ .some(
+ (update) =>
+ update.filesCompleted === 5 && update.filesTotal === 9,
+ ),
+ ).toBe(true);
+ } finally {
+ holdPoll = false;
+ pollAllowed.resolve();
+ workerSeen.resolve();
+ smallerSeen.resolve();
+ latestRead.resolve();
+ clearInterval(keepAlive);
+ await client.close();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test("does not match a resumed live inventory to a historical truncated command", async () => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+
+ const rollout = await writeUsageSession(
+ codexHome,
+ "thread-1",
+ {},
+ { cwd: scanDir },
+ );
+ const native = (id: string) =>
+ nativeCommand("scan-inventory", persistedCommandOutput, id);
+ await appendFile(
+ rollout,
+ [
+ native("historical"),
+ {
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ id: "historical-phase",
+ content: [
+ { type: "Text", text: progressMarker("threat_model", 0, 8) },
+ ],
+ },
+ },
+ },
+ ]
+ .map((event) => JSON.stringify(event))
+ .join("\n") + "\n",
+ );
+ const recipe = {
+ repository,
+ target: { kind: "repository", paths: [] },
+ repositoryRevision: "deadbeef",
+ };
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: async (
+ _options: unknown,
+ args: readonly string[],
+ input?: string,
+ ): Promise<JsonObject> =>
+ args[0] === "get-cli-scan-resume"
+ ? {
+ ...mockScanRegistration(
+ ["--registration-json-stdin", "--scan-dir", scanDir],
+ JSON.stringify({ recipe }),
+ ),
+ threadId: "thread-1",
+ recipe,
+ scopeFileCount: 8,
+ }
+ : mockWorkbench(args, input),
+ createCodex: () => ({
+ startThread: () => {
+ throw new Error("Expected a resumed thread");
+ },
+ resumeThread: (id) => ({
+ id,
+ runStreamed: async () => {
+ await copyCompletedScan(root);
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ yield completedCommand(
+ "scan-inventory",
+ commandOutput(progressMarker("discovery", 0, 9)),
+ "new-live-inventory",
+ );
+ await appendFile(
+ rollout,
+ JSON.stringify(native("current")) +
+ "\n" +
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ output: progressMarker("discovery", 1, 9),
+ },
+ }) +
+ "\n",
+ );
+ throw new Error("Synthetic stop after resumed progress");
+ }
+ return { events: completedEvents(id, events()) };
+ },
+ }),
+ }),
+ });
+ try {
+ await expect(
+ client.run(repository, {
+ mode: "deep",
+ outputDir: scanDir,
+ resumeScanId: "scan_example_001",
+ onProgress: (progress) => updates.push(progress),
+ }),
+ ).rejects.toThrow("Synthetic stop after resumed progress");
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: 1,
+ filesTotal: 9,
+ });
+ } finally {
+ await client.close();
+ }
+ });
+
+ test("matches a progress command after an identical retained non-progress completion", async () => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const historyRead = Promise.withResolvers<void>();
+
+ const native = (id: string) =>
+ nativeCommand("scan-inventory", persistedCommandOutput, id);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ const rollout = await writeUsageSession(codexHome, "thread-1", {});
+ await appendFile(
+ rollout,
+ [
+ native("first-command"),
+ {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "prior-tool-progress",
+ output: progressMarker("threat_model", 0, 8),
+ },
+ },
+ ]
+ .map((event) => JSON.stringify(event))
+ .join("\n") + "\n",
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await historyRead.promise;
+ for (const [index, text] of [
+ commandOutput("no progress marker"),
+ commandOutput(progressMarker("discovery", 0, 9)),
+ ].entries()) {
+ yield completedCommand("scan-inventory", text, `command-${index}`);
+ }
+ await appendFile(
+ rollout,
+ JSON.stringify(native("second-command")) +
+ "\n" +
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ output: progressMarker("discovery", 1, 9),
+ },
+ }) +
+ "\n",
+ );
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (progress) => updates.push(progress),
+ onSessionEvent: ({ event }) => {
+ if (
+ (event["payload"] as Record<string, unknown> | undefined)?.[
+ "call_id"
+ ] === "prior-tool-progress"
+ )
+ historyRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: 1,
+ filesTotal: 9,
+ });
+ } finally {
+ clearInterval(keepAlive);
+ await client.close();
+ }
+ });
+
+ test.each(
+ (["custom", "function", "notification"] as const).flatMap((kind) =>
+ (
+ [
+ ["validation", "discovery"],
+ ["discovery", "attack_path"],
+ ] as const
+ ).map(
+ ([firstPhase, secondPhase]) => [kind, firstPhase, secondPhase] as const,
+ ),
+ ),
+ )(
+ "preserves fresh worker receipts after another shard advances (%s, %s, %s)",
+ async (kind, firstPhase, secondPhase) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const firstRead = Promise.withResolvers<void>();
+ const secondRead = Promise.withResolvers<void>();
+ const lastRead = Promise.withResolvers<void>();
+ const receipt = (
+ id: string,
+ phase: string,
+ count: number,
+ total: number,
+ ) => ({
+ type: "response_item",
+ payload: {
+ type:
+ kind === "function"
+ ? "function_call_output"
+ : "custom_tool_call_output",
+ call_id: id,
+ output:
+ "CODEX_SECURITY_SCAN_PROGRESS " +
+ JSON.stringify({ phase, filesCompleted: count, filesTotal: total }),
+ },
+ });
+ const append = (file: string, row: unknown) =>
+ appendFile(file, JSON.stringify(row) + "\n");
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ await writeUsageSession(codexHome, "thread-1", {});
+ const first = await writeUsageSession(
+ codexHome,
+ "worker-first",
+ {},
+ { parent: "thread-1" },
+ );
+ const second = await writeUsageSession(
+ codexHome,
+ "worker-second",
+ {},
+ { parent: "thread-1" },
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await append(first, receipt("first", firstPhase, 2, 2));
+ await firstRead.promise;
+ await append(second, receipt("second", secondPhase, 1, 6));
+ await secondRead.promise;
+ // Notifications may share their call ID; each appended output is
+ // still a fresh receipt with the same worker-local coverage.
+ await append(
+ first,
+ receipt(
+ kind === "notification" ? "first" : "next",
+ firstPhase,
+ 2,
+ 2,
+ ),
+ );
+ await append(first, {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "observed-last",
+ output: "done",
+ },
+ });
+ await lastRead.promise;
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (progress) => updates.push(progress),
+ onSessionEvent: ({ event }) => {
+ const id = (event["payload"] as { call_id?: string })?.call_id;
+ if (id === "first") firstRead.resolve();
+ if (id === "second") secondRead.resolve();
+ if (id === "observed-last") lastRead.resolve();
+ },
+ });
+ // The final receipt was consumed, but unchanged parent-phase coverage
+ // is deduplicated even when the worker's own phase changes.
+ expect(updates.filter((p) => p.filesCompleted > 0)).toEqual([
+ { phase: "preflight", filesCompleted: 2, filesTotal: 8 },
+ { phase: "preflight", filesCompleted: 3, filesTotal: 8 },
+ ]);
+ } finally {
+ clearInterval(keepAlive);
+ firstRead.resolve();
+ secondRead.resolve();
+ lastRead.resolve();
+ await client.close();
+ }
+ },
+ );
+
+ test.each(
+ [false, true].flatMap((workerFirst) =>
+ [false, true].map((split) => [workerFirst, split] as const),
+ ),
+ )(
+ "keeps global parent phase through a delayed completion read (worker first: %p, split: %p)",
+ async (workerFirst, split) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const metadata = Promise.withResolvers<void>();
+ const workerMetadata = Promise.withResolvers<void>();
+ const listingEntered = Promise.withResolvers<void>();
+ const listingReleased = Promise.withResolvers<void>();
+ let holdListing = false;
+ const closeEntered = Promise.withResolvers<void>();
+ const release = Promise.withResolvers<void>();
+ const validationRead = Promise.withResolvers<void>();
+ let parentPath = "",
+ pauseClose = false;
+ const originalOpen = fsPromises.open,
+ originalReaddir = fsPromises.readdir;
+ const opening = spyOn(fsPromises, "open").mockImplementation((async (
+ ...args: Parameters<typeof originalOpen>
+ ) => {
+ const handle = await originalOpen(...args);
+ if (String(args[0]) !== parentPath) return handle;
+ const read = handle.read.bind(handle),
+ close = handle.close.bind(handle);
+ let discoveryRead = false;
+ handle.read = (async (...readArgs: Parameters<typeof read>) => {
+ const result = await read(...readArgs);
+ if (
+ Buffer.isBuffer(result.buffer) &&
+ result.buffer
+ .toString("utf8", 0, result.bytesRead)
+ .includes('"id":"old-discovery"')
+ )
+ discoveryRead = true;
+ return result;
+ }) as typeof handle.read;
+ handle.close = async () => {
+ if (pauseClose && discoveryRead) {
+ pauseClose = false;
+ closeEntered.resolve();
+ await release.promise;
+ }
+ await close();
+ };
+ return handle;
+ }) as typeof originalOpen);
+ const listing = spyOn(fsPromises, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ if (holdListing && String(args[0]) === join(codexHome, "sessions")) {
+ holdListing = false;
+ listingEntered.resolve();
+ await listingReleased.promise;
+ }
+ const entries = await originalReaddir(...args);
+ if (String(args[0]) !== dirname(parentPath)) return entries;
+ return entries.toSorted(
+ (left, right) =>
+ (workerFirst ? 1 : -1) *
+ (Number(String(left.name) === basename(parentPath)) -
+ Number(String(right.name) === basename(parentPath))),
+ );
+ }) as typeof originalReaddir);
+ const marker = (phase: string) => progressMarker(phase, 8, 8);
+ const completion = (id: string, phase: string) =>
+ nativeCommand(id, marker(phase), id);
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ parentPath = await writeUsageSession(codexHome, "thread-1", {});
+ const worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await metadata.promise;
+ await workerMetadata.promise;
+ // Finish initial association before holding a fresh poll, so the
+ // buffered worker receipt and parent EOF belong to the same pass.
+ holdListing = true;
+ await listingEntered.promise;
+ await appendFile(
+ worker,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ output: marker("attack_path"),
+ },
+ }) + "\n",
+ );
+ await appendFile(
+ parentPath,
+ JSON.stringify(completion("old-discovery", "discovery")) + "\n",
+ );
+ pauseClose = split;
+ if (split) {
+ listingReleased.resolve();
+ await closeEntered.promise;
+ }
+ // Discovery was omitted from live delivery. Both completed commands
+ // are durably appended before validation reaches the live stream.
+ await appendFile(
+ parentPath,
+ JSON.stringify(completion("new-validation", "validation")) + "\n",
+ );
+ yield completedCommand("new-validation", marker("validation"));
+ release.resolve();
+ listingReleased.resolve();
+ await validationRead.promise;
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (progress) => updates.push(progress),
+ onSessionEvent: ({ event, threadId }) => {
+ if (event["type"] === "session_meta" && threadId === "thread-1")
+ metadata.resolve();
+ if (
+ event["type"] === "session_meta" &&
+ threadId === "worker-thread"
+ )
+ workerMetadata.resolve();
+ if (
+ (event["payload"] as { item?: { id?: string } })?.item?.id ===
+ "new-validation"
+ )
+ validationRead.resolve();
+ },
+ });
+ expect(updates.at(-1)).toEqual({
+ phase: "validation",
+ filesCompleted: 8,
+ filesTotal: 8,
+ });
+ } finally {
+ clearInterval(keepAlive);
+ release.resolve();
+ listingReleased.resolve();
+ metadata.resolve();
+ workerMetadata.resolve();
+ validationRead.resolve();
+ await client.close();
+ opening.mockRestore();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each([false, true])(
+ "ignores worker duplicate projections after a newer parent phase (multiple markers: %p)",
+ async (multiple) => {
+ const { root, repository, codexHome, scanDir } = await scanDirectories();
+ const updates: ScanProgress[] = [];
+ const workerRead = Promise.withResolvers<void>();
+ const marker = (phase: string) => progressMarker(phase, 8, 8);
+ const workerPhases = multiple
+ ? (["discovery", "validation"] as const)
+ : (["discovery"] as const);
+ const workerText = workerPhases.map(marker).join("\n");
+ const parentPhase = multiple ? "attack_path" : "validation";
+ const client = TestClient.withDependencies({
+ ...scanRuntimeDependencies(codexHome, scanDir),
+ runWorkbench: registerEightFileScan,
+ createCodex: codexFactory(async () => {
+ await copyCompletedScan(root);
+ await writeUsageSession(codexHome, "thread-1", {});
+ const worker = await writeUsageSession(
+ codexHome,
+ "worker-thread",
+ {},
+ { parent: "thread-1" },
+ );
+ await appendFile(
+ worker,
+ JSON.stringify({
+ type: "event_msg",
+ payload: { type: "agent_message", message: workerText },
+ }) + "\n",
+ );
+ async function* events(): AsyncGenerator<ThreadEvent> {
+ await workerRead.promise;
+ yield {
+ type: "item.completed",
+ item: {
+ type: "agent_message",
+ id: "parent-validation",
+ text: marker(parentPhase),
+ },
+ };
+ await appendFile(
+ worker,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text: workerText }],
+ },
+ }) + "\n",
+ );
+ }
+ return { events: completedEvents("thread-1", events()) };
+ }),
+ });
+ // The fake stream has no process handle to keep the unref'ed poll alive.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ await client.run(repository, {
+ onProgress: (progress) => {
+ updates.push(progress);
+ },
+ onSessionEvent: ({ event, threadId }) => {
+ if (threadId === "worker-thread" && event["type"] === "event_msg")
+ workerRead.resolve();
+ },
+ });
+ expect(
+ updates
+ .filter((progress) => progress.filesCompleted === 8)
+ .map((progress) => progress.phase),
+ ).toEqual(["preflight", parentPhase]);
+ } finally {
+ clearInterval(keepAlive);
+ await client.close();
+ }
+ },
+ );
+
test.each(["none", "sync", "async"] as const)(
"observes workers before scan completion with %s observer errors",
async (failure) => {
diff --git a/sdk/typescript/tests-ts/cost.test.ts b/sdk/typescript/tests-ts/cost.test.ts
index 12efd2c7d..3d19b3b74 100644
--- a/sdk/typescript/tests-ts/cost.test.ts
+++ b/sdk/typescript/tests-ts/cost.test.ts
@@ -1,9 +1,12 @@
+import { execFile } from "node:child_process";
+import { appendFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { promisify } from "node:util";
import { jsonLines } from "./support/json.js";
import { runNodePython } from "./support/python-probe.js";
import * as filesystem from "node:fs/promises";
import { appendFile, writeFile } from "node:fs/promises";
-import * as fs from "node:fs/promises";
-import { join, parse, sep } from "node:path";
+import { basename, dirname, join, parse, sep } from "node:path";
import { Codex } from "@openai/codex-sdk";
import { afterEach, describe, expect, spyOn, test } from "bun:test";
import {
@@ -20,6 +23,9 @@ import { sessionParentThreadId } from "../src/scan-sessions.js";
import type { ScanProgress } from "../src/worker-progress.js";
import { PLUGIN_ROOT as BUNDLED_PLUGIN_ROOT } from "./plugin-root.js";
import {
+ progressMarker,
+ nativeCommand,
+ completedCommand,
childUuid7Thread,
higherUuid7Turn,
lowerUuid7Turn,
@@ -35,6 +41,13 @@ import {
import { createApiTestFixtures } from "./support/temporary-directories.js";
+// Exact ASCII fixture for the pinned native 64 KiB persistence representation.
+const commandHead = "h".repeat(32_743);
+const commandTail = "t".repeat(32_743);
+const persistedCommandOutput = `${commandHead}\n... command output truncated for persistence ...\n${commandTail}`;
+const commandOutput = (middle: string) =>
+ `${commandHead}\n${middle}\n${commandTail}`;
+
const { temporaryDirectory: codexHome, cleanup } = createApiTestFixtures(
"codex-security-cost-",
);
@@ -48,6 +61,19 @@ async function waitFor(check: () => boolean): Promise<void> {
afterEach(cleanup);
+let costModuleBundle: Promise<string> | undefined;
+function bundledCostModule(): Promise<string> {
+ costModuleBundle ??= Bun.build({
+ entrypoints: [fileURLToPath(new URL("../src/cost.ts", import.meta.url))],
+ target: "node",
+ format: "esm",
+ }).then((built) => {
+ expect(built.success).toBe(true);
+ return built.outputs[0]!.text();
+ });
+ return costModuleBundle;
+}
+
async function workerSessionFixture() {
const home = await codexHome();
const usage = { input_tokens: 100, output_tokens: 10 };
@@ -112,2256 +138,5603 @@ function progressMessage(
};
}
-function nativeUsageRecord(
- threadId: string,
- responseId: string,
- usage: Record<string, number>,
- total: Record<string, number> = usage,
-): Record<string, unknown> {
- return {
- type: "token_usage_record",
- payload: {
- thread_id: threadId,
- response_id: responseId,
- usage: tokenUsage(usage),
- thread_token_usage: tokenUsage(total),
- },
- };
-}
-
-function legacyUsageRecord(usage: Record<string, number>) {
- return {
- type: "event_msg",
- payload: { type: "token_count", info: { total_token_usage: usage } },
- };
-}
-
-test.each([
- [
- "prefers the spawned parent over legacy parent fields",
- {
- source: {
- subagent: { thread_spawn: { parent_thread_id: "spawn-parent" } },
- },
- parent_thread_id: "direct-parent",
- forked_from_id: "fork-parent",
- },
- "spawn-parent",
- ],
- [
- "prefers the direct parent over fork ancestry",
- { parent_thread_id: "direct-parent", forked_from_id: "fork-parent" },
- "direct-parent",
- ],
- [
- "falls back from an empty spawned parent to the direct parent",
- {
- source: { subagent: { thread_spawn: { parent_thread_id: "" } } },
- parent_thread_id: "direct-parent",
- },
- "direct-parent",
- ],
- [
- "falls back from an empty direct parent to fork ancestry",
- { parent_thread_id: "", forked_from_id: "fork-parent" },
- "fork-parent",
- ],
- [
- "ignores a non-string direct parent when fork ancestry is present",
- { parent_thread_id: null, forked_from_id: "fork-parent" },
- "fork-parent",
- ],
- ["recognizes independent CLI sessions", { source: "cli" }, null],
- ["treats an empty parent as missing", { forked_from_id: "" }, null],
-] as const)("session parent metadata %s", (_name, metadata, expected) => {
- expect(sessionParentThreadId(metadata)).toBe(expected);
-});
-
-describe("scan cost", () => {
- test("ignores token-count events without a usage snapshot in both readers", async () => {
- const home = await codexHome();
- const path = await writeSession(
- home,
- childUuid7Thread,
- {},
- { parent: scanThreadId },
- );
- const rollout = ownershipRollout([]);
- rollout.splice(2, 0, {
- type: "event_msg",
- timestamp: "2026-07-26T12:04:00Z",
- payload: {
- type: "token_count",
- info: null,
- rate_limits: { limit_id: "replayed" },
- },
- });
- await writeFile(
- path,
- jsonLines([
- ...rollout,
- {
- type: "event_msg",
- timestamp: "2026-07-26T12:03:00Z",
- payload: {
- type: "token_count",
- info: null,
- rate_limits: { primary: { used_percent: 5 } },
- },
+test.each(
+ ["native", "raw-before", "raw-after"].flatMap((projection) =>
+ ["current", "repeated", "pending", "released"].flatMap((scenario) =>
+ [false, true].map((changedDisplay) => ({
+ projection,
+ scenario,
+ changedDisplay,
+ })),
+ ),
+ ),
+)(
+ "retains live command state with $projection receipts, $scenario counterpart, changed display=$changedDisplay",
+ async ({ projection, scenario, changedDisplay }) => {
+ const { home, parent } = await workerSessionFixture();
+ const current: ScanProgress = {
+ phase: "validation",
+ filesCompleted: 1,
+ filesTotal: 8,
+ };
+ const older: ScanProgress = { ...current, phase: "attack_path" };
+ const later: ScanProgress = {
+ ...current,
+ phase: "reporting",
+ filesCompleted: 2,
+ };
+ const sameCount = { ...later, filesCompleted: 1 };
+ const command = ["printf", "sk-" + "a".repeat(32)];
+ const output = (progress: ScanProgress) =>
+ progressMarker(
+ progress.phase,
+ progress.filesCompleted,
+ progress.filesTotal,
+ );
+ const records = (progress: ScanProgress, id: string, args = command) => {
+ const native = nativeCommand(args, output(progress), id);
+ const raw = {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: id,
+ output: output(progress),
},
- ]) + "\n",
- );
- const observations: ScanUsageObservation[] = [];
- const tracker = new ScanCostTracker({
- codexHome: home,
- model: "gpt-6-astra",
- onUsageObservation: (observation) => observations.push(observation),
- });
- tracker.start(scanThreadId);
- expect((await tracker.stop()).usage).toEqual(ownedSdkUsage);
- expect(observations).toEqual([
- {
- tokensUpdatedAt: "2026-07-26T12:02:00.250Z",
- accountRateLimits: [
- {
- limitId: "codex",
- observedAt: "2026-07-26T12:03:00.000Z",
- primary: { usedPercent: 5, windowMinutes: null, resetsAt: null },
- secondary: null,
- },
- ],
- },
- ]);
- expect(readPythonRolloutUsage(BUNDLED_PLUGIN_ROOT, path)).toEqual({
- usage: ownedPythonUsage,
- warnings: [],
- });
- });
-
- test("does not reopen unchanged rollouts and reads appended worker usage", async () => {
- const { home, parent, worker } = await workerSessionFixture();
- await writeSession(home, "unrelated-thread", {
- input_tokens: 900,
- output_tokens: 90,
- });
- const tracker = new ScanCostTracker({
- codexHome: home,
- model: "gpt-6-astra",
+ };
+ return projection === "native"
+ ? [native]
+ : projection === "raw-before"
+ ? [raw, native]
+ : [native, raw];
+ };
+ const append = (rows: unknown[]) =>
+ appendFile(parent, jsonLines(rows) + "\n");
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => updates.push(update),
});
tracker.start("scan-thread");
- await tracker.refresh();
- const opened = spyOn(fs, "open");
try {
await tracker.refresh();
- expect(opened).not.toHaveBeenCalled();
- await appendFile(
- worker,
- jsonLines([
+ tracker.beginParentTurn();
+ await append([
+ ...(scenario === "current"
+ ? []
+ : records(current, "older-identical", ["different-command"])),
+ ...records(older, "older-phase"),
+ ...(scenario === "pending" ? [] : records(current, "current")),
+ ...(scenario === "released" ? records(sameCount, "later") : []),
+ ]);
+ const event = completedCommand(
+ changedDisplay ? "printf [REDACTED_SECRET]" : command.join(" "),
+ output(current),
+ "item_0",
+ );
+ expect(tracker.recordParentProgress(current, event)).toBe(true);
+ tracker.acceptParentProgress(current, event);
+ updates.push(current);
+ await tracker.refresh();
+ const expected = [current];
+ if (scenario === "released" && !changedDisplay) expected.push(sameCount);
+ expect(updates).toEqual(expected);
+ if (scenario === "released") {
+ // A later exact completion releases the latest held state, not its stale prefix.
+ const text = "Finished reviewing the batch.";
+ await append([
{
type: "event_msg",
payload: {
- type: "token_count",
- info: {
- total_token_usage: { input_tokens: 200, output_tokens: 20 },
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [{ type: "Text", text }],
},
},
},
- ]) + "\n",
- );
- const snapshot = await tracker.refresh();
- expect(opened.mock.calls.map(([path]) => path)).toEqual([worker]);
- expect(snapshot.usage).toMatchObject({
- input_tokens: 300,
- output_tokens: 30,
- });
- expect(opened.mock.calls.map(([path]) => path)).not.toContain(parent);
+ ]);
+ tracker.recordParentItem({
+ type: "item.completed",
+ item: { type: "agent_message", id: "item_1", text },
+ });
+ await tracker.refresh();
+ if (changedDisplay) expected.push(sameCount);
+ expect(updates).toEqual(expected);
+ }
+ if (scenario === "pending") {
+ // An older identical output does not identify the still-unseen current command.
+ await tracker.refresh();
+ expect(updates).toEqual([current]);
+ await append(records(current, "current"));
+ await tracker.refresh();
+ expect(updates).toEqual([current]);
+ }
+ // Saved-only advancement still works after corroboration or missing live delivery.
+ await appendSessionItem(parent, progressMessage(2, 8, "reporting"));
+ await tracker.stop();
+ expect(updates).toEqual([...expected, later]);
} finally {
- opened.mockRestore();
await tracker.stop();
}
- });
+ },
+);
- test("reports known usage even when model pricing is unavailable", async () => {
- const home = await codexHome();
- await writeSession(home, "scan-thread", {
- input_tokens: 100,
- output_tokens: 10,
+test.each(
+ [false, true].flatMap((changedDisplay) =>
+ ["none", "before-poll", "after-poll"].flatMap((anchor) =>
+ [
+ { collision: false, prefixMarker: false },
+ { collision: true, prefixMarker: false },
+ { collision: false, prefixMarker: true },
+ ].map((shape) => ({ changedDisplay, anchor, ...shape })),
+ ),
+ ),
+)(
+ "retains live progress omitted from command persistence (display=$changedDisplay, anchor=$anchor, collision=$collision, prefix=$prefixMarker)",
+ async ({ changedDisplay, anchor, collision, prefixMarker }) => {
+ const { home, parent } = await workerSessionFixture();
+ const current: ScanProgress = {
+ phase: "validation",
+ filesCompleted: 1,
+ filesTotal: 8,
+ };
+ const later: ScanProgress = { ...current, phase: "reporting" };
+ const command = ["printf", "sk-" + "a".repeat(32)];
+ const prefixProgress: ScanProgress = { ...current, phase: "discovery" };
+ const prefix = prefixMarker ? progressMarker("discovery", 1, 8) + "\n" : "";
+ const retainedHead = prefix + commandHead.slice(prefix.length);
+ const fullOutput = `${retainedHead}\n${progressMarker("validation", 1, 8)}\n${commandTail}`;
+ const savedOutput =
+ retainedHead + persistedCommandOutput.slice(commandHead.length);
+ const append = (rows: unknown[]) =>
+ appendFile(parent, jsonLines(rows) + "\n");
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => updates.push(update),
});
- const usages: unknown[] = [];
- const tracker = new ScanCostTracker({
- codexHome: home,
- model: "synthetic-unpriced-model",
- onUsage: (usage) => usages.push(usage),
+ const deliver = (
+ progress: ScanProgress,
+ event: Parameters<typeof tracker.recordParentProgress>[1],
+ ) => {
+ expect(tracker.recordParentProgress(progress, event)).toBe(true);
+ tracker.acceptParentProgress(progress, event);
+ if (JSON.stringify(updates.at(-1)) !== JSON.stringify(progress))
+ updates.push(progress);
+ };
+ const message = (text: string) => ({
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [{ type: "Text", text }],
+ },
+ },
});
+ const completeAnchor = async () => {
+ const text = "Synthetic final response.";
+ await append([message(text)]);
+ tracker.recordParentItem({
+ type: "item.completed",
+ item: {
+ type: "agent_message",
+ id: "item_1",
+ text,
+ },
+ });
+ };
tracker.start("scan-thread");
- const snapshot = await tracker.stop();
- expect(snapshot.cost).toBeNull();
- expect(snapshot.usage).toMatchObject({
- input_tokens: 100,
- output_tokens: 10,
- });
- expect(usages).toHaveLength(1);
- expect(usages[0]).toEqual(snapshot.usage);
- });
-
- test("shows distinct token categories without adding cached input twice", () => {
- expect(
- formatTokenUsage({
- input_tokens: 120,
- cached_input_tokens: 30,
- cache_write_tokens: 12,
- output_tokens: 15,
- }),
- ).toBe(
- "78 uncached input, 30 cache reads, 12 cache writes, 15 output, 135 total",
- );
- });
+ try {
+ await tracker.refresh();
+ tracker.beginParentTurn();
+ await append(
+ collision
+ ? [
+ nativeCommand(command, savedOutput, "current"),
+ nativeCommand("later-review", progressMarker("reporting", 1, 8)),
+ // Different full middles can have the same persisted prefix and suffix.
+ nativeCommand(["different-command"], savedOutput, "other"),
+ ]
+ : [
+ nativeCommand(
+ "older-review",
+ progressMarker("attack_path", 1, 8),
+ ),
+ nativeCommand(command, savedOutput, "current"),
+ ],
+ );
+ const event = completedCommand(
+ changedDisplay ? "printf [REDACTED_SECRET]" : command.join(" "),
+ fullOutput,
+ "item_0",
+ );
+ if (prefixMarker) deliver(prefixProgress, event);
+ deliver(current, event);
+ if (anchor === "before-poll") await completeAnchor();
+ await tracker.refresh();
+ if (anchor === "after-poll") await completeAnchor();
+ await tracker.refresh();
+ // Without command identity, collision order is ambiguous even after an anchor.
+ const expected = [
+ ...(prefixMarker ? [prefixProgress] : []),
+ current,
+ ...(collision && !changedDisplay ? [later] : []),
+ ];
+ expect(updates).toEqual(expected);
+ await tracker.stop();
+ expect(updates).toEqual(expected);
+
+ const text = progressMarker("reporting", 1, 8);
+ await append([message(text)]);
+ deliver(later, {
+ type: "item.completed",
+ item: {
+ type: "agent_message",
+ id: "item_2",
+ text,
+ },
+ });
+ await tracker.refresh();
+ expect(updates.at(-1)).toEqual(later);
+ await appendSessionItem(parent, progressMessage(2, 8, "reporting"));
+ await tracker.stop();
+ expect(updates.at(-1)).toEqual({ ...later, filesCompleted: 2 });
+ } finally {
+ await tracker.stop();
+ }
+ },
+);
- test("distinguishes missing cache writes from a reported zero", () => {
- const usage = {
- input_tokens: 120,
- cached_input_tokens: 30,
- output_tokens: 15,
+test.each(
+ [false, true].flatMap((changedDisplay) =>
+ [false, true].flatMap((truncated) =>
+ [false, true].map((initialRead) => ({
+ changedDisplay,
+ truncated,
+ initialRead,
+ })),
+ ),
+ ),
+)(
+ "keeps live progress ahead of an already-read snapshot (display=$changedDisplay, truncated=$truncated, initial=$initialRead)",
+ async ({ changedDisplay, truncated, initialRead }) => {
+ const { home, parent } = await workerSessionFixture();
+ const current: ScanProgress = {
+ phase: "validation",
+ filesCompleted: 1,
+ filesTotal: 8,
};
- expect(formatTokenUsage(tokenUsage(usage))).toBe(
- "unavailable uncached input, 30 cache reads, unavailable cache writes, 15 output, 135 total",
+ const text = progressMarker("validation", 1, 8);
+ const command = ["printf", "sk-" + "a".repeat(32)];
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => updates.push(update),
+ });
+ const reached = Promise.withResolvers<void>();
+ const release = Promise.withResolvers<void>();
+ const originalOpen = filesystem.open;
+ let held = false;
+ let reading: ReturnType<typeof tracker.refresh> | undefined;
+ const opening = spyOn(filesystem, "open").mockImplementation(
+ async (...args: Parameters<typeof originalOpen>) => {
+ const handle = await originalOpen(...args);
+ if (String(args[0]) === parent) {
+ const close = handle.close.bind(handle);
+ handle.close = async () => {
+ if (held) {
+ reached.resolve();
+ await release.promise;
+ }
+ return close();
+ };
+ }
+ return handle;
+ },
);
- expect(formatTokenUsage({ ...usage, cache_write_input_tokens: 0 })).toBe(
- "90 uncached input, 30 cache reads, 0 cache writes, 15 output, 135 total",
+ // Keep the synthetic close gate alive on all supported test runners.
+ const keepAlive = setInterval(() => {}, 1_000);
+ try {
+ if (!initialRead) {
+ tracker.start("scan-thread");
+ await tracker.refresh();
+ }
+ tracker.beginParentTurn();
+ held = true;
+ await appendFile(
+ parent,
+ jsonLines([
+ nativeCommand("older-review", progressMarker("attack_path", 1, 8)),
+ ]) + "\n",
+ );
+ if (initialRead) tracker.start("scan-thread");
+ reading = tracker.refresh();
+ await reached.promise;
+ // The reader saw old EOF, but current persistence still precedes live delivery.
+ await appendFile(
+ parent,
+ jsonLines([
+ nativeCommand(command, truncated ? persistedCommandOutput : text),
+ ]) + "\n",
+ );
+ const event = completedCommand(
+ changedDisplay ? "printf [REDACTED_SECRET]" : command.join(" "),
+ truncated ? commandOutput(text) : text,
+ "item_0",
+ );
+ expect(tracker.recordParentProgress(current, event)).toBe(true);
+ tracker.acceptParentProgress(current, event);
+ updates.push(current);
+ held = false;
+ release.resolve();
+ await reading;
+ expect(updates).toEqual([current]);
+ await tracker.stop();
+ expect(updates).toEqual([current]);
+ } finally {
+ held = false;
+ release.resolve();
+ clearInterval(keepAlive);
+ await reading?.catch(() => {});
+ opening.mockRestore();
+ await tracker.stop();
+ }
+ },
+);
+
+test.each(
+ [false, true].flatMap((truncated) =>
+ [false, true].flatMap((changedDisplay) =>
+ ["none", "repeat", "changed", "phase", "anchor"].map((rejected) => ({
+ truncated,
+ changedDisplay,
+ rejected,
+ })),
+ ),
+ ),
+)(
+ "retains accepted inventory across later notifications (truncated=$truncated, changedDisplay=$changedDisplay, rejected=$rejected)",
+ async ({ truncated, changedDisplay, rejected }) => {
+ const { home, parent } = await workerSessionFixture();
+ const inventory: ScanProgress = {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 9,
+ };
+ const reviewed: ScanProgress = {
+ phase: "validation",
+ filesCompleted: 1,
+ filesTotal: 9,
+ };
+ const ignored: ScanProgress = {
+ phase: rejected === "phase" ? "threat_model" : "discovery",
+ filesCompleted: 0,
+ filesTotal: rejected === "changed" ? 10 : 9,
+ };
+ const inventoryText = progressMarker("discovery", 0, 9);
+ const reviewText =
+ rejected === "anchor"
+ ? "Synthetic completion."
+ : progressMarker("validation", 1, 9);
+ const ignoredText = progressMarker(ignored.phase, 0, ignored.filesTotal);
+ await appendFile(
+ parent,
+ jsonLines([
+ nativeCommand("older", progressMarker("discovery", 0, 8)),
+ nativeCommand(
+ changedDisplay ? ["printf", "sk-" + "a".repeat(32)] : "inventory",
+ truncated ? persistedCommandOutput : inventoryText,
+ ),
+ nativeCommand("review", reviewText),
+ ...(["none", "anchor"].includes(rejected)
+ ? []
+ : [nativeCommand("ignored", ignoredText)]),
+ ]) + "\n",
);
- expect(estimateScanCost("gpt-6-astra", usage)).toMatchObject({
- cacheWriteInputTokens: 0,
- cacheWriteInputTokensReported: false,
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => updates.push(update),
});
- });
+ tracker.beginParentTurn();
+ tracker.start("scan-thread");
+ try {
+ const older = { ...inventory, filesTotal: 8 };
+ const olderEvent = completedCommand(
+ "older",
+ progressMarker("discovery", 0, 8),
+ );
+ expect(tracker.recordParentProgress(older, olderEvent)).toBe(true);
+ tracker.acceptParentProgress(older, olderEvent);
+ const inventoryEvent = completedCommand(
+ changedDisplay ? "printf [REDACTED_SECRET]" : "inventory",
+ truncated ? commandOutput(inventoryText) : inventoryText,
+ );
+ expect(tracker.recordParentProgress(inventory, inventoryEvent)).toBe(
+ true,
+ );
+ tracker.setExpectedFilesTotal(9);
+ tracker.acceptParentProgress(inventory, inventoryEvent);
+ updates.push(inventory);
+ const reviewEvent = completedCommand("review", reviewText);
+ tracker.recordParentItem(reviewEvent);
+ if (rejected !== "anchor") {
+ expect(tracker.recordParentProgress(reviewed, reviewEvent)).toBe(true);
+ tracker.acceptParentProgress(reviewed, reviewEvent);
+ updates.push(reviewed);
+ }
+ // Observing a later item is distinct from the API admitting its marker.
+ if (!["none", "anchor"].includes(rejected))
+ tracker.recordParentProgress(
+ ignored,
+ completedCommand("ignored", ignoredText),
+ );
+ await tracker.stop();
+ expect(updates.at(-1)).toEqual(
+ rejected === "anchor" ? inventory : reviewed,
+ );
+ expect(updates.every((update) => update.filesTotal === 9)).toBe(true);
+ if (rejected !== "anchor")
+ expect(
+ updates.slice(1).every((update) => update.filesCompleted > 0),
+ ).toBe(true);
+ } finally {
+ await tracker.stop();
+ }
+ },
+);
- test("includes the price source and rates with each estimate", () => {
- const cost = estimateScanCost("gpt-6-astra", {
- input_tokens: 1_000_000,
- cached_input_tokens: 200_000,
- cache_write_input_tokens: 300_000,
- output_tokens: 100_000,
- });
- expect(cost).toEqual({
- model: "gpt-6-astra",
- inputTokens: 1_000_000,
- cachedInputTokens: 200_000,
- cacheWriteInputTokens: 300_000,
- outputTokens: 100_000,
- estimatedUsd: 13.95,
- estimatedUsdRange: { min: 13.95, max: 25.4, context: "unknown" },
- pricing: {
- source: "https://developers.openai.com/api/docs/pricing",
- asOf: "2026-09-14",
- serviceTier: "standard",
- context: "short",
- usdPerMillionTokens: {
- input: 10,
- cacheRead: 1,
- cacheWrite: 12.5,
- output: 50,
- },
- longContextUsdPerMillionTokens: {
- input: 20,
- cacheRead: 2,
- cacheWrite: 25,
- output: 75,
- },
- },
- });
+test("does not multiply pending inventory work across idle refreshes", async () => {
+ const { home, parent, worker } = await workerSessionFixture();
+ await appendSessionItem(worker, progressMessage(3));
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => updates.push(update),
});
- test.each(["gpt-6-sol", "openai.gpt-6-sol"])(
- "prices every token category and both context ranges for %s",
- (model) => {
- expect(
- estimateScanCost(model, {
- input_tokens: 1_000_000,
- cached_input_tokens: 200_000,
- cache_write_input_tokens: 300_000,
- output_tokens: 100_000,
- }),
- ).toEqual({
- model,
- inputTokens: 1_000_000,
- cachedInputTokens: 200_000,
- cacheWriteInputTokens: 300_000,
- outputTokens: 100_000,
- estimatedUsd: 2.79,
- estimatedUsdRange: { min: 2.79, max: 5.08, context: "unknown" },
- pricing: {
- source: "https://developers.openai.com/api/docs/models/gpt-6-sol",
- asOf: "2026-10-10",
- serviceTier: "standard",
- context: "short",
- usdPerMillionTokens: {
- input: 2,
- cacheRead: 0.2,
- cacheWrite: 2.5,
- output: 10,
- },
- longContextUsdPerMillionTokens: {
- input: 4,
- cacheRead: 0.4,
- cacheWrite: 5,
- output: 15,
- },
- },
- });
+ tracker.start("scan-thread");
+ // Drain the initial worker receipt and use explicit refreshes without a timer.
+ await tracker.stop();
+ expect(updates.at(-1)?.filesCompleted).toBe(3);
+ tracker.beginParentTurn();
+ let inventoryReads = 0;
+ const inventory: ScanProgress = {
+ phase: "discovery",
+ filesCompleted: 0,
+ get filesTotal() {
+ inventoryReads++;
+ return 8;
},
+ };
+ const reviewed: ScanProgress = {
+ phase: "validation",
+ filesCompleted: 3,
+ filesTotal: 8,
+ };
+ const inventoryText = progressMarker("discovery", 0, 8);
+ const reviewText = progressMarker("validation", 3, 8);
+ await appendFile(
+ parent,
+ jsonLines([
+ nativeCommand("inventory", inventoryText),
+ nativeCommand(["review", "sk-" + "a".repeat(32)], persistedCommandOutput),
+ ]) + "\n",
);
- test.each([
- [{ cache_write_tokens: 15 }, 15],
- [{ cache_write_input_tokens: 0, cache_write_tokens: 15 }, 15],
- [{ cache_write_input_tokens: 0, cache_write_tokens: 80 }, 0],
- ] as const)(
- "keeps workbench cache-write normalization aligned with SDK usage for %j as %p tokens",
- async (cacheWrites, expectedCacheWrites) => {
- const { PLUGIN_ROOT } = await import("./plugin-root.js");
- const python = Bun.which("python3") ?? Bun.which("python");
- expect(python).not.toBeNull();
- const usage = {
- input_tokens: 100,
- cached_input_tokens: 40,
- ...cacheWrites,
- output_tokens: 20,
- reasoning_output_tokens: 5,
- total_tokens: 120,
- };
- const probe = [
- "import json, sys",
- "sys.path.insert(0, sys.argv[1])",
- "import workbench_scan_usage",
- "payload = {'info': {'total_token_usage': json.loads(sys.argv[2])}}",
- "print(json.dumps(workbench_scan_usage._token_snapshot(payload)))",
- ].join("\n");
- const result = runNodePython(python!, [
- "-c",
- probe,
- join(PLUGIN_ROOT, "scripts"),
- JSON.stringify(usage),
- ]);
-
- expect(result.status, result.stderr).toBe(0);
- expect(JSON.parse(result.stdout)).toMatchObject({
- inputTokens: 100,
- cachedInputTokens: 40,
- cacheWriteInputTokens: expectedCacheWrites,
- outputTokens: 20,
- totalTokens: 120,
- });
- },
+ tracker.recordParentProgress(
+ inventory,
+ completedCommand("inventory", inventoryText),
+ );
+ const event = completedCommand(
+ "review [REDACTED_SECRET]",
+ commandOutput(reviewText),
);
+ expect(tracker.recordParentProgress(reviewed, event)).toBe(true);
+ tracker.acceptParentProgress(reviewed, event);
+ await tracker.refresh();
+ const work: number[] = [];
+ for (let poll = 0; poll < 6; poll++) {
+ inventoryReads = 0;
+ await tracker.refresh();
+ work.push(inventoryReads);
+ }
+ // Count actual accesses to the supplied marker, not a private queue shape or
+ // wall-clock duration. Rechecking one unchanged receipt must stay constant.
+ expect(work[0]).toBeGreaterThan(0);
+ expect(work.every((reads) => reads <= work[0]!)).toBe(true);
+ await tracker.stop();
+});
- test("charges cached input at its discounted rate", () => {
- expect(
- estimateScanCost("gpt-5.6-sol", {
- input_tokens: 1_250,
- cached_input_tokens: 200,
- output_tokens: 30,
- }),
- ).toMatchObject({
- model: "gpt-5.6-sol",
- inputTokens: 1_250,
- cachedInputTokens: 200,
- cacheWriteInputTokens: 0,
- outputTokens: 30,
- estimatedUsd: 0.00488,
+test.each(["missing", "short", "append", "split-utf8"] as const)(
+ "keeps authoritative state while replaying %s event history",
+ async (scenario) => {
+ const home = await codexHome();
+ const parent = await writeSession(home, "scan-thread", {});
+ const measuredAt = "2026-07-26T12:00:00.000Z";
+ const measured = {
+ type: "event_msg",
+ timestamp: measuredAt,
+ payload: {
+ type: "token_count",
+ info: { total_token_usage: { input_tokens: 42, output_tokens: 0 } },
+ rate_limits: { primary: { used_percent: 5 } },
+ },
+ };
+ const early = {
+ type: "response_item",
+ payload: {
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text: "Early Ω😀 output." }],
+ },
+ };
+ const late = {
+ type: "response_item",
+ payload: {
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text: "Later output." }],
+ },
+ };
+ const laterUsage = {
+ type: "event_msg",
+ payload: {
+ type: "token_count",
+ info: { total_token_usage: { input_tokens: 84, output_tokens: 0 } },
+ },
+ };
+ const full = Buffer.concat([
+ await filesystem.readFile(parent),
+ Buffer.from(jsonLines([measured, early]) + "\n"),
+ ]);
+ const split =
+ scenario === "split-utf8"
+ ? full.indexOf(Buffer.from("😀")) + 2
+ : full.length;
+ await writeFile(parent, full.subarray(0, split));
+ const hidden = join(home, "saved-history.jsonl");
+ const originalOpen = filesystem.open;
+ let opens = 0;
+ const opening = spyOn(filesystem, "open").mockImplementation(
+ async (...args: Parameters<typeof originalOpen>) => {
+ const replay = String(args[0]) === parent ? ++opens : 0;
+ if (replay === 2) {
+ if (scenario === "append")
+ await appendFile(parent, jsonLines([late, laterUsage]) + "\n");
+ if (scenario === "split-utf8")
+ await appendFile(parent, full.subarray(split));
+ }
+ const handle = await originalOpen(...args);
+ if (replay === 1 && (scenario === "missing" || scenario === "short")) {
+ const close = handle.close.bind(handle);
+ handle.close = async () => {
+ await close();
+ if (scenario === "missing") await filesystem.rename(parent, hidden);
+ else
+ await writeFile(parent, full.subarray(0, full.indexOf(10) + 1));
+ };
+ }
+ return handle;
+ },
+ );
+ const events: ScanSessionEvent[] = [];
+ const costs: number[] = [];
+ const observations: ScanUsageObservation[] = [];
+ const tracker = costTracker(home, {
+ onSessionEvent: (event) => events.push(event),
+ onCost: (cost) => costs.push(cost.inputTokens),
+ onUsageObservation: (observation) => observations.push(observation),
});
- });
+ try {
+ tracker.start("scan-thread");
+ const first = await tracker.refresh();
+ expect(costs[0]).toBe(42);
+ expect(observations[0]).toMatchObject({
+ tokensUpdatedAt: measuredAt,
+ accountRateLimits: [
+ { observedAt: measuredAt, primary: { usedPercent: 5 } },
+ ],
+ });
+ if (scenario === "missing" || scenario === "short") {
+ expect(first.cost?.inputTokens).toBe(42);
+ expect(events).toEqual([]);
+ if (scenario === "missing") await filesystem.rename(hidden, parent);
+ else await writeFile(parent, full);
+ }
+ const result = await tracker.stop();
+ expect(result.cost?.inputTokens).toBe(scenario === "append" ? 84 : 42);
+ const expected = full
+ .toString("utf8")
+ .trim()
+ .split("\n")
+ .map((line) => JSON.parse(line));
+ if (scenario === "append") expected.push(late, laterUsage);
+ expect(events.map((event) => event.event)).toEqual(expected);
+ } finally {
+ opening.mockRestore();
+ await tracker.stop();
+ }
+ },
+);
- test("charges GPT-5.6 cache writes at their published rate", () => {
- expect(
- estimateScanCost("gpt-5.6-sol", {
- input_tokens: 1_000,
- cached_input_tokens: 100,
- cache_write_input_tokens: 200,
- output_tokens: 10,
- })?.estimatedUsd,
- ).toBe(0.00404);
+test("includes worker usage appended during final event replay", async () => {
+ const home = await codexHome();
+ const parent = await writeSession(home, "scan-thread", {});
+ const worker = join(dirname(parent), "rollout-worker-thread.jsonl");
+ const workerMeta = {
+ type: "session_meta",
+ payload: {
+ id: "worker-thread",
+ ...parentMetadata("scan-thread", "source"),
+ },
+ };
+ const usage = (
+ inputTokens: number,
+ usedPercent: number,
+ timestamp: string,
+ ) => ({
+ type: "event_msg",
+ timestamp,
+ payload: {
+ type: "token_count",
+ info: {
+ total_token_usage: { input_tokens: inputTokens, output_tokens: 0 },
+ },
+ rate_limits: { primary: { used_percent: usedPercent } },
+ },
+ });
+ await appendFile(
+ parent,
+ jsonLines([usage(10, 0, "2026-07-26T12:00:00.000Z")]) + "\n",
+ );
+ const initial = usage(0, 0, "2026-07-26T12:01:00.000Z");
+ const last = usage(5_000, 50, "2026-07-26T12:02:00.000Z");
+ const workerEvents: ScanSessionEvent["event"][] = [];
+ const observations: ScanUsageObservation[] = [];
+ const tracker = costTracker(home, {
+ onUsageObservation: (observation) => observations.push(observation),
+ onSessionEvent: ({ threadId, event }) => {
+ if (threadId === "worker-thread") workerEvents.push(event);
+ // The parent callback runs after the worker's first read and before its replay.
+ if (threadId === "scan-thread" && event["type"] === "response_item")
+ appendFileSync(worker, jsonLines([last]) + "\n");
+ },
});
+ tracker.start("scan-thread");
+ try {
+ await tracker.refresh();
+ writeFileSync(worker, jsonLines([workerMeta, initial]) + "\n");
+ appendFileSync(
+ parent,
+ jsonLines([{ type: "response_item", payload: progressMessage(2) }]) +
+ "\n",
+ );
+ const final = await tracker.stop();
+ expect(await filesystem.readFile(worker, "utf8")).toContain(last.timestamp);
+ expect(final.cost?.inputTokens).toBe(5_010);
+ expect(observations.at(-1)).toMatchObject({
+ tokensUpdatedAt: last.timestamp,
+ accountRateLimits: [
+ { observedAt: last.timestamp, primary: { usedPercent: 50 } },
+ ],
+ });
+ expect(workerEvents).toEqual([workerMeta, initial, last]);
+ } finally {
+ await tracker.stop();
+ }
+});
- test("preserves legacy cache writes after SDK normalization adds zero", () => {
- expect(
- estimateScanCost("gpt-5.6-sol", {
- input_tokens: 1_000,
- cached_input_tokens: 100,
- cache_write_input_tokens: 0,
- cache_write_tokens: 200,
- output_tokens: 10,
- }),
- ).toMatchObject({ cacheWriteInputTokens: 200, estimatedUsd: 0.00404 });
- });
-
- test("ignores impossible legacy cache writes while retaining canonical usage", () => {
- expect(
- estimateScanCost("gpt-5.6-sol", {
- input_tokens: 1_000,
- cached_input_tokens: 100,
- cache_write_input_tokens: 0,
- cache_write_tokens: 1_001,
- output_tokens: 10,
- }),
- ).toMatchObject({ cacheWriteInputTokens: 0, estimatedUsd: 0.00384 });
- });
-
- test("does not double-charge reasoning tokens included in output", () => {
- expect(
- estimateScanCost("gpt-5.6-sol", {
- input_tokens: 1_000,
- output_tokens: 10,
- reasoning_output_tokens: 9,
- })?.estimatedUsd,
- ).toBe(0.0042);
- });
-
- test.each(Object.getOwnPropertyNames(Object.prototype))(
- "does not inherit prices for unknown model %s",
- (model) => {
- for (const selected of [model, `openai.${model}`]) {
- expect(
- estimateScanCost(selected, { input_tokens: 1, output_tokens: 1 }),
- ).toBeNull();
- }
- },
- );
-
- test("does not invent prices for unknown models or incomplete usage", () => {
- for (const [model, usage] of [
- ["unknown-model", { input_tokens: 1, output_tokens: 1 }],
- ["openai.unknown-model", { input_tokens: 1, output_tokens: 1 }],
- ["gpt-5.6-sol", null],
- ["gpt-5.6-sol", {}],
- ["gpt-5.6-sol", { input_tokens: -1, output_tokens: 1 }],
- ["gpt-5.6-sol", { input_tokens: 1.5, output_tokens: 1 }],
- [
- "gpt-5.6-sol",
- { input_tokens: 1, cached_input_tokens: 2, output_tokens: 1 },
- ],
- [
- "gpt-5.6-sol",
- {
- input_tokens: Number.MAX_SAFE_INTEGER,
- output_tokens: Number.MAX_SAFE_INTEGER,
- },
- ],
- ] as const) {
- expect(estimateScanCost(model, usage)).toBeNull();
- }
- });
-});
-
-describe("live scan cost tracking", () => {
- test("observes account limits and actual token measurement times from this scan", async () => {
+test.each(["open", "read", "close"] as const)(
+ "retries an association replay after %s fails without losing early events",
+ async (boundary) => {
const home = await codexHome();
- const path = await writeSession(home, scanThreadId, {});
- const unrelated = await writeSession(home, "unrelated", {});
- const older = "2026-07-26T12:00:00.000Z";
- const limitAt = "2026-07-26T12:01:00.000Z";
- const tokensAt = "2026-07-26T12:02:00.000Z";
- const later = "2026-07-26T12:03:00.000Z";
- const limit = (timestamp: string, usedPercent: number) => ({
- type: "event_msg",
- timestamp,
- payload: {
- type: "token_count",
- info: null,
- rate_limits: {
- limit_id: "codex",
- secondary: { used_percent: usedPercent, window_minutes: 10_080 },
- },
- },
- });
- await appendFile(path, jsonLines([limit(limitAt, 12)]) + "\n");
- await appendFile(unrelated, jsonLines([limit(later, 99)]) + "\n");
- const observations: ScanUsageObservation[] = [];
- const tracker = costTracker(home, {
- onUsageObservation: (observation) => observations.push(observation),
+ const parent = await writeSession(home, "scan-thread", {
+ input_tokens: 42,
+ output_tokens: 0,
});
- tracker.start(scanThreadId);
- const accountRateLimits = [
- {
- limitId: "codex",
- observedAt: limitAt,
- primary: null,
- secondary: { usedPercent: 12, windowMinutes: 10_080, resetsAt: null },
+ const early = {
+ type: "response_item",
+ payload: {
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text: "Synthetic early output." }],
},
- ];
- try {
- expect((await tracker.refresh()).usage).toBeNull();
- expect(observations).toEqual([
- { tokensUpdatedAt: null, accountRateLimits },
- ]);
- const receipt = nativeUsageRecord(
- scanThreadId,
- "response",
- ownedSdkUsage,
- );
- await appendFile(
- path,
- jsonLines([
- { ...receipt, timestamp: tokensAt },
- { ...receipt, timestamp: later },
- limit(older, 3),
- ]) + "\n",
- );
- expect((await tracker.refresh()).usage).toEqual(ownedSdkUsage);
- await tracker.refresh();
- expect(observations.slice(1)).toEqual([
- { tokensUpdatedAt: tokensAt, accountRateLimits },
- ]);
- } finally {
- await tracker.stop();
- }
- });
-
- test("keeps receipt cache-write detail when an equal legacy counter omits it", async () => {
- const home = await codexHome();
- const usage = {
- ...ownedSdkUsage,
- cached_input_tokens: 20,
- cache_write_input_tokens: 12,
};
- const path = await writeSession(home, scanThreadId, ownedSdkUsage);
- await appendFile(
- path,
- jsonLines([
- nativeUsageRecord(scanThreadId, "response-1", usage),
- legacyUsageRecord(ownedSdkUsage),
- ]) + "\n",
+ await appendFile(parent, jsonLines([early]) + "\n");
+ const originalOpen = filesystem.open;
+ let opens = 0;
+ const opening = spyOn(filesystem, "open").mockImplementation(
+ async (...args: Parameters<typeof originalOpen>) => {
+ const replay = String(args[0]) === parent && ++opens === 2;
+ const failure = () =>
+ Object.assign(new Error("Synthetic replay read failure"), {
+ code: "EACCES",
+ });
+ if (replay && boundary === "open") throw failure();
+ const handle = await originalOpen(...args);
+ if (replay && boundary === "read") {
+ handle.read = (async () => {
+ throw failure();
+ }) as typeof handle.read;
+ }
+ if (replay && boundary === "close") {
+ const close = handle.close.bind(handle);
+ handle.close = async () => {
+ await close();
+ throw failure();
+ };
+ }
+ return handle;
+ },
);
- const tracker = costTracker(home);
- tracker.start(scanThreadId);
- expect((await tracker.stop(ownedSdkUsage)).cost).toMatchObject({
- inputTokens: 100,
- cachedInputTokens: 20,
- cacheWriteInputTokens: 12,
- outputTokens: 10,
- });
- });
-
- test("keeps freshness with the last reportable token total", async () => {
- const home = await codexHome();
- const parent = await writeSession(home, scanThreadId, {});
- const first = "2026-07-26T10:01:00.000Z";
- const second = "2026-07-26T10:02:00.000Z";
- const third = "2026-07-26T10:03:00.000Z";
- const measure = (
- path: string,
- timestamp: string | undefined,
- input: number,
- ) =>
- appendFile(
- path,
- jsonLines([
- {
- ...legacyUsageRecord({ input_tokens: input, output_tokens: 0 }),
- timestamp,
- },
- ]) + "\n",
- );
- await measure(parent, first, 10);
- const times: Array<string | null> = [];
+ const failed = Promise.withResolvers<void>();
+ const events: ScanSessionEvent[] = [];
+ const errors: string[] = [];
const tracker = costTracker(home, {
- onUsageObservation: ({ tokensUpdatedAt }) => times.push(tokensUpdatedAt),
+ onSessionEvent: (event) => events.push(event),
+ onError: (error) => {
+ errors.push(String(error));
+ failed.resolve();
+ },
});
- tracker.start(scanThreadId);
+ const keepAlive = setInterval(() => {}, 1_000);
+ tracker.start("scan-thread");
try {
- expect((await tracker.refresh()).usage).toMatchObject({
- total_tokens: 10,
- });
- const worker = await writeSession(
- home,
- "worker",
- {},
- { parent: scanThreadId },
- );
- await measure(parent, second, 20);
- expect((await tracker.refresh()).usage).toBeNull();
- expect(times).toEqual([first]);
- await measure(worker, third, 7);
- expect((await tracker.refresh()).usage).toMatchObject({
- total_tokens: 27,
- });
- expect(times).toEqual([first, third]);
- tracker.recordUsage({ input_tokens: 30, output_tokens: 0 });
- expect((await tracker.refresh()).usage).toMatchObject({
- total_tokens: 37,
- });
- expect(times).toEqual([first, third, null]);
- await measure(parent, third, 30);
- await tracker.refresh();
- expect(times.at(-1)).toBe(third);
- await measure(parent, undefined, 30);
+ await failed.promise;
await tracker.refresh();
- expect(times.at(-1)).toBe(third);
- await measure(parent, undefined, 31);
- expect((await tracker.refresh()).usage).toMatchObject({
- total_tokens: 38,
- });
- expect(times.at(-1)).toBeNull();
+ const result = await tracker.stop();
+ expect(result.cost?.inputTokens).toBe(42);
+ expect(
+ events
+ .map((event) => event.event)
+ .filter((event) => event["type"] === "response_item"),
+ ).toEqual([early]);
+ expect(
+ events.filter((event) => event.event["type"] === "session_meta"),
+ ).toHaveLength(1);
+ expect(errors).toHaveLength(1);
} finally {
+ clearInterval(keepAlive);
+ opening.mockRestore();
await tracker.stop();
}
- });
+ },
+);
- test("counts compaction receipts before stale counters and deduplicates responses", async () => {
- const home = await codexHome();
- const original = { ...ownedSdkUsage };
- const compact = { ...ownedSdkUsage, input_tokens: 40, output_tokens: 3 };
- const compactTotal = {
- ...ownedSdkUsage,
- input_tokens: 140,
- output_tokens: 13,
- };
- const path = await writeSession(home, scanThreadId, original);
- await appendFile(
- path,
- jsonLines([nativeUsageRecord(scanThreadId, "response-1", original)]) +
- "\n",
- );
- const budget = new AbortController();
- const maxCostUsd = 0.000355;
- const tracker = new ScanCostTracker({
- codexHome: home,
- model: "gpt-6.1-sol",
- maxCostUsd,
- onCost: ({ estimatedUsd }) => {
- if (estimatedUsd > maxCostUsd) budget.abort();
+describe("inventory source ordering", () => {
+ async function fixture(workerFirst = false) {
+ const { home, parent, worker } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update, source) => {
+ if (
+ source?.inventory === true ||
+ (update.phase === "discovery" && update.filesCompleted === 0)
+ )
+ tracker.setExpectedFilesTotal(update.filesTotal);
+ updates.push(update);
},
});
- tracker.start(scanThreadId);
- expect((await tracker.refresh()).cost?.estimatedUsd).toBe(0.0003);
- expect(budget.signal.aborted).toBe(false);
-
- const compaction = nativeUsageRecord(
- scanThreadId,
- "response-compaction",
- compact,
- compactTotal,
- );
- await appendFile(
- path,
- jsonLines([
- compaction,
- { type: "compacted", payload: { message: "Compacted context." } },
- legacyUsageRecord(original),
- ]) + "\n",
- );
- expect((await tracker.refresh()).cost?.estimatedUsd).toBe(0.00041);
- expect(budget.signal.aborted).toBe(true);
-
- const final = { ...ownedSdkUsage, input_tokens: 170, output_tokens: 15 };
- const stale = { ...ownedSdkUsage, input_tokens: 130, output_tokens: 12 };
- await appendFile(
- path,
- jsonLines([
- compaction,
- nativeUsageRecord(
- scanThreadId,
- "response-2",
- { ...ownedSdkUsage, input_tokens: 30, output_tokens: 2 },
- final,
- ),
- legacyUsageRecord(stale),
- ]) + "\n",
+ const originalReaddir = filesystem.readdir;
+ const listing = spyOn(filesystem, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ const entries = await originalReaddir(...args);
+ if (String(args[0]) !== dirname(parent)) return entries;
+ const first = basename(workerFirst ? worker : parent);
+ return entries.toSorted(
+ (left, right) =>
+ Number(String(right.name) === first) -
+ Number(String(left.name) === first),
+ );
+ }) as typeof originalReaddir);
+ let beforeClose: (() => void | Promise<void>) | undefined;
+ const originalOpen = filesystem.open;
+ const opening = spyOn(filesystem, "open").mockImplementation(
+ async (...args: Parameters<typeof originalOpen>) => {
+ const handle = await originalOpen(...args);
+ if (String(args[0]) === parent) {
+ const close = handle.close.bind(handle);
+ handle.close = async () => {
+ const callback = beforeClose;
+ beforeClose = undefined;
+ await callback?.();
+ return close();
+ };
+ }
+ return handle;
+ },
);
- expect((await tracker.stop(stale)).usage).toMatchObject({
- input_tokens: 170,
- output_tokens: 15,
- total_tokens: 185,
- });
- });
-
- test("keeps native receipts scoped to the owned fork across resumed turns", async () => {
- const home = await codexHome();
- const inherited = {
- ...ownedSdkUsage,
- input_tokens: 1_000,
- output_tokens: 100,
- };
- const parent = await writeSession(home, scanThreadId, inherited);
- await appendFile(
+ tracker.start("scan-thread");
+ await tracker.refresh();
+ tracker.beginParentTurn();
+ return {
parent,
- jsonLines([
- nativeUsageRecord(scanThreadId, "parent-response", inherited),
- ]) + "\n",
- );
- const child = await writeSession(home, childUuid7Thread, ownedSdkUsage, {
- parent: scanThreadId,
- });
- const rollout = ownershipRollout([lowerUuid7Turn]);
- rollout.splice(
- 3,
- 0,
- nativeUsageRecord(scanThreadId, "parent-response", inherited),
- );
- rollout.push(
- nativeUsageRecord(childUuid7Thread, "child-response", ownedSdkUsage),
- nativeUsageRecord(scanThreadId, "foreign-response", inherited),
- );
- await writeFile(child, jsonLines(rollout) + "\n");
- const tracker = costTracker(home, { onSessionEvent: () => {} });
- tracker.start(scanThreadId);
- expect((await tracker.refresh()).usage).toMatchObject({
- input_tokens: 1_100,
- output_tokens: 110,
- });
- const compact = { ...ownedSdkUsage, input_tokens: 40, output_tokens: 3 };
- const compactTotal = {
- ...ownedSdkUsage,
- input_tokens: 140,
- output_tokens: 13,
+ worker,
+ tracker,
+ updates,
+ beforeClose(callback: () => void | Promise<void>) {
+ beforeClose = callback;
+ },
+ emit(command: string, progress: ScanProgress, output?: string) {
+ const event = completedCommand(
+ command,
+ output ??
+ progressMarker(
+ progress.phase,
+ progress.filesCompleted,
+ progress.filesTotal,
+ ),
+ );
+ const accepted = tracker.recordParentProgress(progress, event);
+ if (accepted) {
+ tracker.acceptParentProgress(progress, event);
+ if (progress.phase === "discovery" && progress.filesCompleted === 0)
+ tracker.setExpectedFilesTotal(progress.filesTotal);
+ updates.push(progress);
+ }
+ return accepted;
+ },
+ async close() {
+ beforeClose = undefined;
+ opening.mockRestore();
+ listing.mockRestore();
+ await tracker.stop();
+ },
};
- const compaction = nativeUsageRecord(
- childUuid7Thread,
- "child-compact",
- compact,
- compactTotal,
- );
- await appendFile(child, jsonLines([compaction, compaction]) + "\n");
- expect((await tracker.stop(inherited)).usage).toMatchObject({
- input_tokens: 1_140,
- output_tokens: 113,
- });
+ }
- await appendFile(
- child,
- jsonLines([
- {
- type: "event_msg",
- payload: {
- type: "task_started",
- turn_id: "019f9e4d-b3bb-7000-8000-000000000004",
- },
- },
- nativeUsageRecord(
- childUuid7Thread,
- "resumed-response",
- { ...ownedSdkUsage, input_tokens: 60, output_tokens: 6 },
- { ...ownedSdkUsage, input_tokens: 200, output_tokens: 19 },
- ),
- ]) + "\n",
- );
- const resumed = costTracker(home);
- resumed.start(scanThreadId);
- expect((await resumed.stop(inherited)).usage).toMatchObject({
- input_tokens: 1_200,
- output_tokens: 119,
- });
- });
+ test.each(
+ [false, true].flatMap((workerFirst) =>
+ [false, true].map((firstChanged) => ({ workerFirst, firstChanged })),
+ ),
+ )(
+ "keeps repeated inventories in occurrence order (workers first=$workerFirst, first display changed=$firstChanged)",
+ async ({ workerFirst, firstChanged }) => {
+ const f = await fixture(workerFirst);
+ const current = {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 5,
+ } as const;
+ const middle = { ...current, filesTotal: 10 };
+ try {
+ f.emit(firstChanged ? "first changed" : "first", current);
+ f.emit("middle changed", middle);
+ f.emit("latest", current);
+ await appendFile(
+ f.parent,
+ jsonLines([
+ nativeCommand("first", progressMarker("discovery", 0, 5)),
+ ]) + "\n",
+ );
+ await f.tracker.refresh();
+ await appendFile(
+ f.parent,
+ jsonLines([
+ nativeCommand("middle", progressMarker("discovery", 0, 10)),
+ ]) + "\n",
+ );
+ await appendSessionItem(
+ f.worker,
+ progressMessage(6, 10, "attack_path"),
+ );
+ await f.tracker.refresh();
+ expect(f.updates.at(-1)).toEqual(current);
+ await appendFile(
+ f.parent,
+ jsonLines([
+ nativeCommand("latest", progressMarker("discovery", 0, 5)),
+ nativeCommand("newer", progressMarker("discovery", 0, 10)),
+ ]) + "\n",
+ );
+ await f.tracker.stop();
+ expect(f.updates.at(-1)).toEqual({
+ phase: "attack_path",
+ filesCompleted: 6,
+ filesTotal: 10,
+ });
+ } finally {
+ await f.close();
+ }
+ },
+ );
- test.each([1_000, 1_100])(
- "reconciles a native resumed total with a final SDK receipt of %p input tokens",
- async (finalInput) => {
- const home = await codexHome();
- const path = await writeSession(home, scanThreadId, {
- ...ownedSdkUsage,
- input_tokens: 1_000,
- });
- await appendFile(
- path,
- jsonLines([
- nativeUsageRecord(
- scanThreadId,
- "resumed-response",
- { ...ownedSdkUsage, input_tokens: 20, output_tokens: 2 },
- { ...ownedSdkUsage, input_tokens: 1_020, output_tokens: 12 },
- ),
- ]) + "\n",
- );
- const tracker = costTracker(home);
- tracker.start(scanThreadId);
- expect(
- (await tracker.stop({ ...ownedSdkUsage, input_tokens: finalInput }))
- .cost?.inputTokens,
- ).toBe(Math.max(1_020, finalInput));
+ test.each(
+ [false, true].flatMap((workerFirst) =>
+ [false, true].map((inventory) => ({ workerFirst, inventory })),
+ ),
+ )(
+ "keeps truncated live progress through an anchor arriving during close (workers first=$workerFirst, inventory=$inventory)",
+ async ({ workerFirst, inventory }) => {
+ const f = await fixture(workerFirst);
+ const old = {
+ phase: "discovery",
+ filesCompleted: inventory ? 0 : 3,
+ filesTotal: 8,
+ } as const;
+ const current = inventory
+ ? { ...old, filesTotal: 9 }
+ : { ...old, phase: "validation" as const };
+ try {
+ await appendFile(
+ f.parent,
+ jsonLines([
+ nativeCommand(
+ "old",
+ progressMarker(old.phase, old.filesCompleted, old.filesTotal),
+ ),
+ nativeCommand("original", persistedCommandOutput),
+ nativeCommand("anchor", "Finished the batch."),
+ ]) + "\n",
+ );
+ if (inventory)
+ await appendSessionItem(
+ f.worker,
+ progressMessage(5, 9, "attack_path"),
+ );
+ f.beforeClose(() => {
+ f.emit(
+ "changed-display",
+ current,
+ commandOutput(
+ progressMarker(
+ current.phase,
+ current.filesCompleted,
+ current.filesTotal,
+ ),
+ ),
+ );
+ f.tracker.recordParentItem(
+ completedCommand("anchor", "Finished the batch."),
+ );
+ });
+ await f.tracker.refresh();
+ await f.tracker.stop();
+ expect(f.updates.at(-1)).toEqual(
+ inventory
+ ? { phase: "attack_path", filesCompleted: 5, filesTotal: 9 }
+ : current,
+ );
+ } finally {
+ await f.close();
+ }
},
);
- test.each([
- [undefined, undefined],
- [0, 0],
- [12, undefined],
- [undefined, 12],
- ] as const)(
- "preserves cache-write usage through SDK normalization: log %p, receipt %p",
- async (writes, receiptWrites) => {
- const home = await codexHome();
- const usage = {
- input_tokens: 120,
- cached_input_tokens: 30,
- output_tokens: 15,
- ...(writes === undefined ? {} : { cache_write_input_tokens: writes }),
- };
- await writeSession(home, "scan-thread", usage);
- const thread = new Codex({
- codexPathOverride: process.execPath,
- }).startThread();
- const executable = thread as unknown as {
- _exec: { run(): AsyncGenerator<string> };
- };
- executable._exec.run = async function* () {
- yield JSON.stringify({
- type: "thread.started",
- thread_id: "scan-thread",
+ test.each([false, true])(
+ "keeps the newest inventory ahead of a raw copy released during close (workers first: %p)",
+ async (workerFirst) => {
+ const f = await fixture(workerFirst);
+ const initial = {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 9,
+ } as const;
+ const current = { ...initial, filesTotal: 8 };
+ try {
+ await appendFile(
+ f.parent,
+ jsonLines([
+ nativeCommand("initial", progressMarker("discovery", 0, 9)),
+ ]) + "\n",
+ );
+ await appendSessionItem(f.parent, {
+ type: "custom_tool_call_output",
+ call_id: "initial-copy",
+ output: progressMarker("discovery", 0, 9),
});
- yield JSON.stringify({
- type: "turn.completed",
- usage: { ...usage, cache_write_input_tokens: receiptWrites },
+ f.emit("initial changed", initial);
+ await appendFile(
+ f.parent,
+ jsonLines([
+ nativeCommand("final", progressMarker("discovery", 0, 8)),
+ ]) + "\n",
+ );
+ await f.tracker.refresh();
+ await appendFile(
+ f.parent,
+ jsonLines([nativeCommand("anchor", "done")]) + "\n",
+ );
+ f.emit("final changed", current);
+ f.beforeClose(() =>
+ f.tracker.recordParentItem(completedCommand("anchor", "done")),
+ );
+ await f.tracker.refresh();
+ await appendSessionItem(f.worker, progressMessage(5, 8, "attack_path"));
+ await f.tracker.stop();
+ expect(f.updates.at(-1)).toEqual({
+ phase: "attack_path",
+ filesCompleted: 5,
+ filesTotal: 8,
});
- };
- const receipt = (await thread.run("Scan the repository.")).usage;
- expect(receipt?.cache_write_input_tokens).toBe(receiptWrites ?? 0);
- const tracker = new ScanCostTracker({
- codexHome: home,
- model: "gpt-6-astra",
- });
- tracker.start("scan-thread");
- const running = await tracker.refresh();
- const completed = await tracker.stop(receipt);
-
- expect(formatTokenUsage(running.usage)).toContain(
- `${writes ?? "unavailable"} cache writes`,
- );
- const expectedWrites = receiptWrites ?? writes;
- expect(completed.cost).toMatchObject({
- inputTokens: 120,
- cachedInputTokens: 30,
- cacheWriteInputTokens: expectedWrites ?? 0,
- outputTokens: 15,
- });
- expect(completed.cost?.cacheWriteInputTokensReported).toBe(
- expectedWrites === undefined ? false : undefined,
- );
- expect(formatTokenUsage(completed.usage)).toContain(
- `${expectedWrites ?? "unavailable"} cache writes`,
- );
+ } finally {
+ await f.close();
+ }
},
);
- test("retains reported write charges when another worker omits cache writes", async () => {
- const home = await codexHome();
- await writeSession(home, "scan-thread", {
- input_tokens: 100,
- cached_input_tokens: 20,
- output_tokens: 10,
- });
- await writeSession(
- home,
- "worker-thread",
- {
- input_tokens: 200,
- cached_input_tokens: 40,
- cache_write_input_tokens: 50,
- output_tokens: 20,
- },
- { parent: "scan-thread" },
- );
- const tracker = new ScanCostTracker({
- codexHome: home,
- model: "gpt-6-astra",
- });
- tracker.start("scan-thread");
- const snapshot = await tracker.stop();
- expect(snapshot.usage).toMatchObject({
- input_tokens: 300,
- cache_write_input_tokens: 50,
- cache_write_input_tokens_reported: false,
- total_tokens: 330,
- });
- expect(snapshot.cost).toMatchObject({
- cacheWriteInputTokens: 50,
- cacheWriteInputTokensReported: false,
- estimatedUsd: 0.004085,
- });
- expect(formatTokenUsage(snapshot.usage)).toContain(
- "unavailable cache writes",
- );
- });
+ test.each([false, true])(
+ "retains inventory provenance after a zero-count phase (workers first: %p)",
+ async (workerFirst) => {
+ const f = await fixture(workerFirst);
+ const initial = {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 9,
+ } as const;
+ try {
+ await appendFile(
+ f.parent,
+ jsonLines([
+ nativeCommand("initial", progressMarker("discovery", 0, 9)),
+ ]) + "\n",
+ );
+ f.emit("initial changed", initial);
+ await f.tracker.refresh();
+ await appendFile(
+ f.parent,
+ jsonLines([
+ nativeCommand("phase", progressMarker("threat_model", 0, 9)),
+ ]) + "\n",
+ );
+ await appendSessionItem(f.worker, progressMessage(5, 9, "attack_path"));
+ f.beforeClose(() => {
+ f.emit("phase changed", { ...initial, phase: "threat_model" });
+ });
+ await f.tracker.refresh();
+ await appendFile(
+ f.parent,
+ jsonLines([
+ nativeCommand("smaller", progressMarker("discovery", 0, 8)),
+ nativeCommand("restored", progressMarker("discovery", 0, 9)),
+ ]) + "\n",
+ );
+ await f.tracker.stop();
+ expect(f.updates.at(-1)).toEqual({
+ phase: "attack_path",
+ filesCompleted: 5,
+ filesTotal: 9,
+ });
+ } finally {
+ await f.close();
+ }
+ },
+ );
- test("reports newly available cache writes even when the dollar amount is unchanged", async () => {
- const home = await codexHome();
- const updates: unknown[] = [];
- const tracker = new ScanCostTracker({
- codexHome: home,
- model: "gpt-5.5",
- onCost: (cost) => updates.push(cost),
- });
- tracker.start("scan-thread");
- tracker.recordUsage(
- { input_tokens: 100, output_tokens: 10 },
- "scan-thread",
- );
- await tracker.refresh();
- tracker.recordUsage(
- { input_tokens: 100, cache_write_input_tokens: 0, output_tokens: 10 },
- "scan-thread",
- );
- await tracker.stop();
- expect(updates).toHaveLength(2);
- expect(updates[0]).toHaveProperty("cacheWriteInputTokensReported", false);
- expect(updates[1]).not.toHaveProperty("cacheWriteInputTokensReported");
- });
- test("coalesces overlapping polling ticks and bounds final work", async () => {
- const home = await codexHome();
- await writeSession(home, "scan-thread", {
- input_tokens: 100,
- output_tokens: 10,
- });
- const releases: Array<() => void> = [];
- const tracker = costTracker(home, {
- maxCostUsd: 1,
- });
- const refresh = tracker.refresh.bind(tracker);
- tracker.refresh = async () => {
- await new Promise<void>((resolve) => releases.push(resolve));
- return refresh();
- };
- tracker.start("scan-thread");
+ test.each([false, true])(
+ "restores replayed inventory when its delayed live copy is rejected (workers first: %p)",
+ async (workerFirst) => {
+ const f = await fixture(workerFirst);
+ const initial = {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 8,
+ } as const;
+ const larger = { ...initial, filesTotal: 9 };
+ try {
+ await appendFile(
+ f.parent,
+ jsonLines([
+ nativeCommand("initial", progressMarker("discovery", 0, 8)),
+ ]) + "\n",
+ );
+ f.emit("initial changed", initial);
+ await f.tracker.refresh();
+ await appendFile(
+ f.parent,
+ jsonLines([
+ nativeCommand("larger", progressMarker("discovery", 0, 9)),
+ nativeCommand("final", progressMarker("discovery", 0, 8)),
+ ]) + "\n",
+ );
+ await appendSessionItem(f.worker, progressMessage(5, 9, "attack_path"));
+ await f.tracker.refresh();
+ f.emit("larger changed", larger);
+ await f.tracker.refresh();
+ // As in the API, observe the final live source before its count guard
+ // rejects the zero following provisional worker coverage.
+ f.tracker.recordParentProgress(
+ initial,
+ completedCommand("final", progressMarker("discovery", 0, 8)),
+ );
+ await f.tracker.stop();
+ await f.tracker.refresh();
+ expect(f.updates.at(-1)).toEqual(initial);
+ // An older delayed inventory cannot undo the source-ordered final one.
+ f.tracker.recordParentProgress(
+ larger,
+ completedCommand("larger", progressMarker("discovery", 0, 9)),
+ );
+ await f.tracker.refresh();
+ expect(f.updates.at(-1)).toEqual(initial);
+ } finally {
+ await f.close();
+ }
+ },
+ );
- await new Promise<void>((resolve) => setTimeout(resolve, 350));
- expect(releases).toHaveLength(1);
+ test.each(["missing", "partial", "older raw copy"])(
+ "keeps live inventory while its saved row is %s",
+ async (persistence) => {
+ const f = await fixture();
+ const initial = {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 9,
+ } as const;
+ const current = { ...initial, filesTotal: 8 };
+ const row =
+ JSON.stringify(
+ nativeCommand("current", progressMarker("discovery", 0, 8)),
+ ) + "\n";
+ try {
+ if (persistence === "older raw copy")
+ await appendSessionItem(f.parent, {
+ type: "custom_tool_call_output",
+ call_id: "older-eight",
+ output: progressMarker("discovery", 0, 8),
+ });
+ await appendFile(
+ f.parent,
+ JSON.stringify(
+ nativeCommand("original", progressMarker("discovery", 0, 9)),
+ ) + "\n",
+ );
+ if (persistence === "partial")
+ await appendFile(f.parent, row.slice(0, 30));
+ expect(f.emit("changed-display", initial)).toBe(true);
+ expect(f.emit("current", current)).toBe(true);
+ await appendSessionItem(f.worker, progressMessage(6, 9, "attack_path"));
+ await f.tracker.refresh();
+ expect(f.updates.at(-1)).toEqual(current);
+ expect(
+ f.updates.slice(1).every((update) => update.filesTotal === 8),
+ ).toBe(true);
+ await appendFile(
+ f.parent,
+ persistence === "partial" ? row.slice(30) : row,
+ );
+ await f.tracker.stop();
+ expect(f.updates.at(-1)).toEqual(current);
+ expect(
+ f.updates.slice(1).every((update) => update.filesTotal === 8),
+ ).toBe(true);
+ } finally {
+ await f.close();
+ }
+ },
+ );
- const stopped = tracker.stop();
- expect(releases).toHaveLength(2);
- releases[0]!();
- releases[1]!();
+ test.each(
+ [false, true].flatMap((workerFirst) =>
+ [false, true].map((changedDisplay) => ({ workerFirst, changedDisplay })),
+ ),
+ )(
+ "bounds an inventory observed during close with a later exact completion (workers first=$workerFirst, changed display=$changedDisplay)",
+ async ({ workerFirst, changedDisplay }) => {
+ const f = await fixture(workerFirst);
+ const initial = {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 9,
+ } as const;
+ const smaller = { ...initial, filesTotal: 8 };
+ try {
+ await appendFile(
+ f.parent,
+ JSON.stringify(
+ nativeCommand("original", progressMarker("discovery", 0, 9)),
+ ) + "\n",
+ );
+ await appendSessionItem(f.worker, progressMessage(5, 9, "attack_path"));
+ f.beforeClose(() => {
+ expect(
+ f.emit(changedDisplay ? "changed-display" : "original", initial),
+ ).toBe(true);
+ });
+ await f.tracker.refresh();
+ expect(f.updates.at(-1)).toEqual({
+ phase: "attack_path",
+ filesCompleted: 5,
+ filesTotal: 9,
+ });
+ // The read boundary and equal output do not locate the live command.
+ // An exact later completion bounds it before the new saved inventory.
+ await appendFile(
+ f.parent,
+ JSON.stringify(nativeCommand("anchor", "Inventory batch finished.")) +
+ "\n",
+ );
+ f.tracker.recordParentItem(
+ completedCommand("anchor", "Inventory batch finished."),
+ );
+ await appendFile(
+ f.parent,
+ JSON.stringify(
+ nativeCommand("smaller", progressMarker("discovery", 0, 8)),
+ ) + "\n",
+ );
+ await f.tracker.refresh();
+ expect(f.updates.at(-1)).toEqual(smaller);
+ await appendSessionItem(f.worker, progressMessage(6, 9, "attack_path"));
+ await f.tracker.stop();
+ expect(f.updates.at(-1)).toEqual(smaller);
+ } finally {
+ await f.close();
+ }
+ },
+ );
- expect((await stopped).cost?.inputTokens).toBe(100);
- expect(releases).toHaveLength(2);
- });
+ test.each([false, true])(
+ "keeps delayed full command progress after a rejected inventory (duplicate: %p)",
+ async (duplicate) => {
+ const f = await fixture();
+ const initial = {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 9,
+ } as const;
+ const discovery = { ...initial, filesCompleted: 3 };
+ const validation = { ...discovery, phase: "validation" } as const;
+ try {
+ await appendFile(
+ f.parent,
+ JSON.stringify(
+ nativeCommand("inventory", progressMarker("discovery", 0, 9)),
+ ) + "\n",
+ );
+ expect(f.emit("inventory", initial)).toBe(true);
+ await f.tracker.refresh();
+ expect(f.emit("unmatched-discovery", discovery)).toBe(true);
+ await appendSessionItem(f.parent, progressMessage(3, 9));
+ await appendFile(
+ f.parent,
+ JSON.stringify(nativeCommand("review", persistedCommandOutput)) +
+ "\n",
+ );
+ await appendSessionItem(f.parent, progressMessage(0, 9));
+ if (duplicate)
+ await appendFile(
+ f.parent,
+ JSON.stringify({
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [
+ { type: "Text", text: progressMarker("discovery", 0, 9) },
+ ],
+ },
+ },
+ }) + "\n",
+ );
+ await f.tracker.refresh();
+ expect(
+ f.emit(
+ "review",
+ validation,
+ commandOutput(progressMarker("validation", 3, 9)),
+ ),
+ ).toBe(true);
+ await f.tracker.stop();
+ expect(f.updates.at(-1)).toEqual(validation);
+ } finally {
+ await f.close();
+ }
+ },
+ );
- test("retries one coalesced poll after a failed refresh", async () => {
- const home = await codexHome();
- await writeSession(home, "scan-thread", {
- input_tokens: 100,
- output_tokens: 10,
- });
- const errors: string[] = [];
- let traversals = 0;
- const { promise: blocked, resolve: release } =
- Promise.withResolvers<void>();
- const tracker = costTracker(home, {
- maxCostUsd: 1,
- onError: (error) => {
- if (error instanceof Error) errors.push(error.message);
- },
- });
- const refresh = tracker.refresh.bind(tracker);
- tracker.refresh = async () => {
- traversals += 1;
- if (traversals === 1) {
- await blocked;
- throw new Error("session read failed");
+ test.each([false, true])(
+ "recovers a repeated live total from newer inventories (same completion: %p)",
+ async (sameCompletion) => {
+ const f = await fixture();
+ const initial = {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 9,
+ } as const;
+ try {
+ await appendFile(
+ f.parent,
+ JSON.stringify(
+ nativeCommand("original", progressMarker("discovery", 0, 9)),
+ ) + "\n",
+ );
+ expect(f.emit("changed-display", initial)).toBe(true);
+ await appendSessionItem(f.worker, progressMessage(5, 9, "attack_path"));
+ await f.tracker.refresh();
+ const smaller = progressMarker("discovery", 0, 8);
+ const restored = progressMarker("discovery", 0, 9);
+ await appendFile(
+ f.parent,
+ jsonLines(
+ sameCompletion
+ ? [nativeCommand("rescope", smaller + "\n" + restored)]
+ : [
+ nativeCommand("smaller", smaller),
+ nativeCommand("restored", restored),
+ ],
+ ) + "\n",
+ );
+ await f.tracker.refresh();
+ await appendSessionItem(f.worker, progressMessage(6, 9, "attack_path"));
+ await f.tracker.stop();
+ expect(f.updates.at(-1)).toEqual({
+ phase: "attack_path",
+ filesCompleted: 6,
+ filesTotal: 9,
+ });
+ } finally {
+ await f.close();
}
- return refresh();
- };
- tracker.start("scan-thread");
+ },
+ );
- await new Promise<void>((resolve) => setTimeout(resolve, 250));
- expect(traversals).toBe(1);
- release!();
- await waitFor(() => traversals === 2);
+ test.each([false, true])(
+ "releases an older live inventory after a later completion anchor (workers first: %p)",
+ async (workerFirst) => {
+ const f = await fixture(workerFirst);
+ const initial = {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 9,
+ } as const;
+ const current = { ...initial, filesTotal: 8 };
+ try {
+ await appendFile(
+ f.parent,
+ jsonLines([
+ nativeCommand("original", progressMarker("discovery", 0, 9)),
+ nativeCommand("smaller", progressMarker("discovery", 0, 8)),
+ nativeCommand("anchor", "Inventory enumeration complete."),
+ ]) + "\n",
+ );
+ await appendSessionItem(f.worker, progressMessage(5, 9, "attack_path"));
+ f.beforeClose(() => {
+ expect(f.emit("changed-display", initial)).toBe(true);
+ f.tracker.recordParentItem(
+ completedCommand("anchor", "Inventory enumeration complete."),
+ );
+ });
+ await f.tracker.refresh();
+ await f.tracker.refresh();
+ await appendSessionItem(f.worker, progressMessage(6, 9, "attack_path"));
+ await f.tracker.stop();
+ expect(f.updates.at(-1)).toEqual(current);
+ } finally {
+ await f.close();
+ }
+ },
+ );
- expect(errors).toEqual(["session read failed"]);
- expect(traversals).toBe(2);
- expect((await tracker.stop()).cost?.inputTokens).toBe(100);
+ test.each([false, true])(
+ "retains proven scope when a live inventory is observed but not accepted (workers first: %p)",
+ async (workerFirst) => {
+ const f = await fixture(workerFirst);
+ const initial = {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 10,
+ } as const;
+ const current = { ...initial, filesTotal: 7 };
+ try {
+ await appendFile(
+ f.parent,
+ jsonLines([
+ nativeCommand("original", progressMarker("discovery", 0, 10)),
+ nativeCommand("smaller", progressMarker("discovery", 0, 7)),
+ ]) + "\n",
+ );
+ await appendSessionItem(f.parent, {
+ type: "custom_tool_call_output",
+ call_id: "current-seven",
+ output: progressMarker("discovery", 0, 7),
+ });
+ await appendSessionItem(f.worker, progressMessage(5, 5, "attack_path"));
+ f.beforeClose(() => {
+ expect(f.emit("changed-display", initial)).toBe(true);
+ });
+ await f.tracker.refresh();
+ expect(f.updates.at(-1)?.filesCompleted).toBe(5);
+ // The API observes source identity before rejecting a count decrease.
+ // Keep the rejected marker available for inventory reconciliation.
+ f.tracker.recordParentProgress(
+ current,
+ completedCommand("smaller", progressMarker("discovery", 0, 7)),
+ );
+ await f.tracker.refresh();
+ await f.tracker.stop();
+ expect(f.updates.at(-1)).toEqual({
+ phase: "attack_path",
+ filesCompleted: 5,
+ filesTotal: 7,
+ });
+ } finally {
+ await f.close();
+ }
+ },
+ );
+
+ test.each(["discovery", "threat_model"] as const)(
+ "takes scope from inventory when a newer zero-count %s arrives during close",
+ async (phase) => {
+ const f = await fixture(true);
+ const current = { phase, filesCompleted: 0, filesTotal: 8 };
+ try {
+ await appendFile(
+ f.parent,
+ JSON.stringify(
+ nativeCommand("inventory", progressMarker("discovery", 0, 5)),
+ ) + "\n",
+ );
+ await appendSessionItem(f.worker, progressMessage(3, 8, "attack_path"));
+ f.beforeClose(async () => {
+ await appendFile(
+ f.parent,
+ JSON.stringify(
+ nativeCommand("next-phase", progressMarker(phase, 0, 8)),
+ ) + "\n",
+ );
+ expect(f.emit("next-phase", current)).toBe(true);
+ });
+ await f.tracker.refresh();
+ await f.tracker.stop();
+ expect(f.updates.at(-1)).toEqual(
+ phase === "discovery"
+ ? { phase: "attack_path", filesCompleted: 3, filesTotal: 8 }
+ : { phase: "discovery", filesCompleted: 0, filesTotal: 5 },
+ );
+ } finally {
+ await f.close();
+ }
+ },
+ );
+});
+
+test("keeps the parent frontier ahead of duplicate saved inventory", async () => {
+ const { home, parent } = await workerSessionFixture();
+ const inventory = {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 8,
+ } as const;
+ const initial = { ...inventory, filesCompleted: 3 };
+ const older = { ...initial, phase: "attack_path" } as const;
+ const newer = { ...initial, phase: "validation" } as const;
+ await appendSessionItem(parent, progressMessage(0));
+ await appendFile(
+ parent,
+ jsonLines([
+ {
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [
+ { type: "Text", text: progressMarker("discovery", 0, 8) },
+ ],
+ },
+ },
+ },
+ nativeCommand("older-review", progressMarker("attack_path", 3, 8)),
+ nativeCommand("newer-review", progressMarker("validation", 3, 8)),
+ ]) + "\n",
+ );
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => updates.push(update),
});
+ tracker.beginParentTurn();
+ const first = completedCommand(
+ "unpersisted-review",
+ progressMarker("discovery", 3, 8),
+ );
+ expect(tracker.recordParentProgress(initial, first)).toBe(true);
+ tracker.acceptParentProgress(initial, first);
+ updates.push(initial);
+ tracker.start("scan-thread");
+ try {
+ await tracker.refresh();
+ await tracker.refresh();
+ expect(updates.at(-1)).toEqual(newer);
+ expect(
+ tracker.recordParentProgress(
+ older,
+ completedCommand("older-review", progressMarker("attack_path", 3, 8)),
+ ),
+ ).toBe(false);
+ expect(updates.at(-1)).toEqual(newer);
+ } finally {
+ await tracker.stop();
+ }
+});
- test("reports live token use and cost without a spending limit", async () => {
- const home = await codexHome();
- await writeSession(home, "scan-thread", {
- input_tokens: 1_250,
- cached_input_tokens: 200,
- output_tokens: 30,
- });
- const { promise: reportedCost, resolve: reportCost } =
- Promise.withResolvers<unknown>();
+test.each(["short literal", "UTF-8 truncation", "earlier literal"])(
+ "recognizes native persistence gaps by their byte boundaries (%s)",
+ async (scenario) => {
+ const { home, parent } = await workerSessionFixture();
+ const gap = "\n... command output truncated for persistence ...\n";
+ const progress = {
+ phase: "validation",
+ filesCompleted: 3,
+ filesTotal: 8,
+ } as const;
+ const lead =
+ (scenario === "UTF-8 truncation" ? "" : "normal output" + gap) +
+ progressMarker("validation", 3, 8) +
+ "\n";
+ let saved = lead;
+ if (scenario !== "short literal") {
+ const fill = scenario === "UTF-8 truncation" ? "😀" : "a";
+ const tail = "\n" + progressMarker("attack_path", 4, 8) + "\n";
+ // Exact fragments of the pinned Rust64KiB persistence representation.
+ saved =
+ lead +
+ fill.repeat(
+ Math.floor(
+ (32_743 - Buffer.byteLength(lead)) / Buffer.byteLength(fill),
+ ),
+ ) +
+ gap +
+ fill.repeat(
+ Math.floor(
+ (32_743 - Buffer.byteLength(tail)) / Buffer.byteLength(fill),
+ ),
+ ) +
+ tail;
+ expect(Buffer.byteLength(saved)).toBe(
+ scenario === "UTF-8 truncation" ? 65_532 : 65_536,
+ );
+ } else expect(Buffer.byteLength(saved)).toBe(149);
+ await appendFile(
+ parent,
+ JSON.stringify(nativeCommand("review", saved)) + "\n",
+ );
+ const updates: ScanProgress[] = [];
const tracker = costTracker(home, {
- onCost: reportCost,
+ expectedFilesTotal: 8,
+ onProgress: (update) => updates.push(update),
});
tracker.start("scan-thread");
-
try {
- await expect(reportedCost).resolves.toMatchObject({
- model: "gpt-5.6-sol",
- inputTokens: 1_250,
- cachedInputTokens: 200,
- cacheWriteInputTokens: 0,
- outputTokens: 30,
- estimatedUsd: 0.00488,
- });
+ await tracker.refresh();
+ expect(updates).toEqual([progress]);
} finally {
await tracker.stop();
}
- });
+ },
+);
- test.each([...parentFields])(
- "observes worker metadata without status markers or usage via %s",
- async (parentField) => {
- const home = await codexHome();
- const parent = await writeSession(home, "scan-thread", {});
- await appendSessionItem(parent, {
- type: "message",
- role: "assistant",
- content: [
- {
- type: "output_text",
- text:
- 'CODEX_SECURITY_WORKER_STATUS {"phase":"validation","planned":1,"started":1}\n' +
- '{"type":"session_meta","payload":{"id":"fictional-worker","parent_thread_id":"scan-thread"}}',
- },
- ],
- });
- await writeSession(
- home,
- "unrelated-worker",
- {},
- { parent: "other-scan" },
- );
- const workers: ScanWorkerEvent[] = [];
- const tracker = costTracker(home, {
- onWorkerEvent: (event) => workers.push(event),
- });
- tracker.start("scan-thread");
- try {
- await tracker.refresh();
- expect(workers).toEqual([]);
- const path = join(parse(parent).dir, "rollout-worker-thread.jsonl");
- const metadata =
+test.each([
+ ["complete prefix", true],
+ ["fenced prefix", false],
+ ["partial prefix line", false],
+ ["ambiguous tail", false],
+] as const)(
+ "recovers only complete original lines before a persistence gap (%s)",
+ async (scenario, reported) => {
+ const { home, parent } = await workerSessionFixture();
+ const progress = {
+ phase: "discovery",
+ filesCompleted: 4,
+ filesTotal: 8,
+ } as const;
+ const marker = "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(progress);
+ let prefix = commandHead;
+ let tail = commandTail;
+ if (scenario === "complete prefix" || scenario === "fenced prefix") {
+ const text =
+ "h".repeat(24_999) +
+ "\n" +
+ (scenario === "fenced prefix" ? "```text\n" : "") +
+ marker +
+ "\n";
+ prefix = text + "h".repeat(commandHead.length - text.length);
+ } else if (scenario === "partial prefix line") {
+ prefix =
+ "h".repeat(commandHead.length - marker.length - 1) + "\n" + marker;
+ } else {
+ const text = "\n" + marker + "\n";
+ tail = text + "t".repeat(commandTail.length - text.length);
+ }
+ const saved =
+ prefix + "\n... command output truncated for persistence ...\n" + tail;
+ // The omitted suffix invalidates a marker ending at the prefix boundary;
+ // the gap's inserted newline must not turn it into a complete source line.
+ const full =
+ prefix +
+ " omitted same-line suffix\n```text\n" +
+ "m".repeat(20_000) +
+ tail;
+ expect(Buffer.byteLength(saved)).toBe(64 * 1024);
+ await appendFile(
+ parent,
+ JSON.stringify(nativeCommand("review", saved)) + "\n",
+ );
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => updates.push(update),
+ });
+ tracker.start("scan-thread");
+ try {
+ await tracker.refresh();
+ expect(updates).toEqual(reported ? [progress] : []);
+ if (reported) {
+ const latest = { ...progress, phase: "validation" } as const;
+ await appendFile(
+ parent,
JSON.stringify({
- type: "session_meta",
+ type: "event_msg",
payload: {
- id: "worker-thread",
- ...parentMetadata("scan-thread", parentField),
- instructions: "Synthetic private instructions",
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [
+ {
+ type: "Text",
+ text:
+ "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(latest),
+ },
+ ],
+ },
},
- }) + "\n";
- await writeFile(path, metadata);
- await tracker.refresh();
- expect(workers).toEqual([{ kind: "observed", worker: 1 }]);
- await writeFile(path.replace(".jsonl", "-copy.jsonl"), metadata);
- await tracker.refresh();
+ }) + "\n",
+ );
await tracker.refresh();
- expect(workers).toEqual([{ kind: "observed", worker: 1 }]);
- } finally {
- await tracker.stop();
+ expect(updates.at(-1)).toEqual(latest);
+ // Parsing a prefix must preserve the original full-output signature.
+ expect(
+ tracker.recordParentProgress(progress, {
+ type: "item.completed",
+ item: {
+ type: "command_execution",
+ command: "review",
+ aggregated_output: full,
+ },
+ }),
+ ).toBe(false);
}
- },
- );
-
- test("polls for workers with only a worker observer and keeps concurrent scans separate", async () => {
- const home = await codexHome();
- const workers: ScanWorkerEvent[][] = [[], []];
- const trackers = workers.map((events) =>
- costTracker(home, {
- onWorkerEvent: (event) => events.push(event),
- }),
- );
- trackers.forEach((tracker, index) => tracker.start(`scan-${index}`));
- try {
- await Promise.all(trackers.map((tracker) => tracker.refresh()));
- await writeSession(home, "worker-0", {}, { parent: "scan-0" });
- await writeSession(home, "worker-1", {}, { parent: "scan-1" });
- await waitFor(() => workers.every((events) => events.length === 1));
- expect(workers).toEqual([
- [{ kind: "observed", worker: 1 }],
- [{ kind: "observed", worker: 1 }],
- ]);
} finally {
- await Promise.all(trackers.map((tracker) => tracker.stop()));
+ await tracker.stop();
}
- const resumed: ScanWorkerEvent[] = [];
- const tracker = costTracker(home, {
- onWorkerEvent: (event) => resumed.push(event),
- });
- tracker.start("scan-0");
- await tracker.stop();
- expect(resumed).toEqual([{ kind: "observed", worker: 1 }]);
+ },
+);
+
+test("cost-only tracking does not retain unrelated marker-free message history", async () => {
+ const root = await codexHome();
+ await writeSession(root, "scan-thread", {
+ input_tokens: 100,
+ output_tokens: 10,
});
+ const history = await writeSession(root, "unrelated-history", {});
+ const file = await filesystem.open(history, "a");
+ try {
+ for (let batch = 0; batch < 200; batch++) {
+ const lines = Array.from({ length: 1_000 }, (_, index) =>
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "message",
+ role: "assistant",
+ content: [
+ {
+ type: "output_text",
+ text: `Historical note ${batch * 1_000 + index}`,
+ },
+ ],
+ },
+ }),
+ );
+ await file.write(lines.join("\n") + "\n");
+ }
+ } finally {
+ await file.close();
+ }
+ const module = join(root, "cost.mjs");
+ await writeFile(module, await bundledCostModule());
+ const { stdout } = await promisify(execFile)(
+ "node",
+ [
+ "--max-old-space-size=64",
+ "--input-type=module",
+ "--eval",
+ `
+ const { ScanCostTracker } = await import(${JSON.stringify(pathToFileURL(module).href)});
+ const tracker = new ScanCostTracker({codexHome: ${JSON.stringify(root)}, model: "gpt-5.6-sol", onCost() {}});
+ tracker.start("scan-thread");
+ const result = await tracker.stop();
+ console.log(result.usage.total_tokens);
+ `,
+ ],
+ { encoding: "utf8" },
+ );
+ expect(stdout.trim()).toBe("110");
+});
- test("counts the scan and delegated workers without including other scans", async () => {
- const home = await codexHome();
- const parent = await writeSession(home, "scan-thread", {
- input_tokens: 1_000,
- cached_input_tokens: 100,
- cache_write_input_tokens: 200,
- output_tokens: 10,
- reasoning_output_tokens: 2,
- });
- const worker = await writeSession(
- home,
- "worker-thread",
- {
- input_tokens: 250,
- cached_input_tokens: 50,
- output_tokens: 5,
- reasoning_output_tokens: 1,
+test("does not retain completed command payloads when native logs are absent", async () => {
+ const root = await codexHome();
+ const module = join(root, "cost.mjs");
+ await writeFile(module, await bundledCostModule());
+ const { stdout } = await promisify(execFile)(
+ "node",
+ [
+ "--max-old-space-size=64",
+ "--expose-gc",
+ "--input-type=module",
+ "--eval",
+ `
+ const { ScanCostTracker } = await import(${JSON.stringify(pathToFileURL(module).href)});
+ const tracker = new ScanCostTracker({codexHome: ${JSON.stringify(root)}, model: "gpt-5.6-sol", onProgress() {}});
+ for (let index = 0; index < 100; index++) {
+ const output = "x".repeat(1024 * 1024) + index;
+ output.charCodeAt(output.length - 1);
+ tracker.recordParentItem({type: "item.completed", item: {type: "command_execution", id: "item-" + index, command: "inspect-source", aggregated_output: output}});
+ global.gc();
+ }
+ console.log("processed 100 command outputs");
+ `,
+ ],
+ { encoding: "utf8" },
+ );
+ expect(stdout.trim()).toBe("processed 100 command outputs");
+});
+
+test.each(["é", "漢", "😀"])(
+ "correlates commands truncated at UTF-8 boundaries (%s)",
+ async (character) => {
+ const { home, parent } = await workerSessionFixture();
+ const tracker = costTracker(home, { onProgress() {} });
+ tracker.start("scan-thread");
+ await tracker.refresh();
+ const progress = {
+ phase: "discovery",
+ filesCompleted: 8,
+ filesTotal: 8,
+ } as const;
+ const marker = "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(progress);
+ const fullEdge = character.repeat(40_000);
+ // Native keeps complete UTF-8 characters within each 32,743-byte edge.
+ const savedEdge = character.repeat(
+ Math.floor(32_743 / Buffer.byteLength(character)),
+ );
+ const event = {
+ type: "item.completed",
+ item: {
+ type: "command_execution",
+ command: "inspect-source",
+ aggregated_output: `${fullEdge}\n${marker}\n${fullEdge}`,
},
- { parent: "scan-thread" },
+ };
+ expect(tracker.recordParentProgress(progress, event)).toBe(true);
+ tracker.acceptParentProgress(progress, event);
+ await appendFile(
+ parent,
+ JSON.stringify(
+ nativeCommand(
+ "inspect-source",
+ `${savedEdge}\n... command output truncated for persistence ...\n${savedEdge}`,
+ ),
+ ) + "\n",
);
- await writeSession(home, "unrelated-thread", {
- input_tokens: 1_000_000,
- output_tokens: 1_000_000,
- });
- const events: ScanSessionEvent[] = [];
- const tracker = costTracker(home, {
- onSessionEvent: (event) => events.push(event),
- });
- tracker.start("scan-thread");
- await waitFor(() => events.length === 4);
await appendFile(
parent,
- `${JSON.stringify({ type: "turn_context", payload: { instructions: "Check authorization" } })}\n`,
+ JSON.stringify({
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [
+ {
+ type: "Text",
+ text:
+ "CODEX_SECURITY_SCAN_PROGRESS " +
+ JSON.stringify({ ...progress, phase: "validation" }),
+ },
+ ],
+ },
+ },
+ }) + "\n",
);
- await appendSessionItem(worker, {
- type: "function_call",
- name: "spawn_agent",
- });
- await tracker.refresh();
await tracker.refresh();
+ expect(tracker.recordParentProgress(progress, event)).toBe(false);
+ await tracker.stop();
+ },
+);
+function nativeUsageRecord(
+ threadId: string,
+ responseId: string,
+ usage: Record<string, number>,
+ total: Record<string, number> = usage,
+): Record<string, unknown> {
+ return {
+ type: "token_usage_record",
+ payload: {
+ thread_id: threadId,
+ response_id: responseId,
+ usage: tokenUsage(usage),
+ thread_token_usage: tokenUsage(total),
+ },
+ };
+}
- expect(await tracker.stop()).toMatchObject({
- usage: {
- input_tokens: 1_250,
- cached_input_tokens: 150,
- cache_write_input_tokens: 200,
- output_tokens: 15,
- reasoning_output_tokens: 3,
- total_tokens: 1_265,
- },
- cost: {
- model: "gpt-5.6-sol",
- inputTokens: 1_250,
- cachedInputTokens: 150,
- cacheWriteInputTokens: 200,
- outputTokens: 15,
- estimatedUsd: 0.00496,
- },
- });
- expect(
- events.map(({ threadId, parentThreadId, event }) => [
- threadId,
- parentThreadId,
- event["type"],
- ]),
- ).toEqual(
- expect.arrayContaining([
- ["scan-thread", null, "session_meta"],
- ["scan-thread", null, "event_msg"],
- ["worker-thread", "scan-thread", "session_meta"],
- ["worker-thread", "scan-thread", "event_msg"],
- ["scan-thread", null, "turn_context"],
- ["worker-thread", "scan-thread", "response_item"],
- ]),
- );
- expect(events).toHaveLength(6);
- });
+function legacyUsageRecord(usage: Record<string, number>) {
+ return {
+ type: "event_msg",
+ payload: { type: "token_count", info: { total_token_usage: usage } },
+ };
+}
- test.each(["parent", "main"] as const)(
- "replays early worker events when the %s session arrives later",
- async (missing) => {
- const home = await codexHome();
- const scanDirectory = join(home, "scan");
- const usage = { input_tokens: 10, output_tokens: 1 };
- const writeMain = () =>
- writeSession(home, "scan-thread", usage, {
- cwd: scanDirectory,
- timestamp: "2026-07-26T12:00:00Z",
- });
- if (missing === "parent") await writeMain();
- const worker = await writeSession(home, "worker-thread", usage, {
- parent: missing === "parent" ? "parent-worker" : undefined,
- cwd: join(
- scanDirectory,
- "artifacts",
- "deep_discovery",
- "workers",
- "one",
- "output",
- ),
- timestamp: "2026-07-26T12:01:00Z",
- });
- const message = (text: string) => ({
- type: "message",
- role: "assistant",
- content: [{ type: "output_text", text }],
- });
- await appendSessionItem(worker, message("Early worker output."));
- const unrelated = await writeSession(home, "unrelated-thread", usage);
- await appendSessionItem(unrelated, message("Unrelated output."));
- const events: ScanSessionEvent[] = [];
- const workers: ScanWorkerEvent[] = [];
- const tracker = costTracker(home, {
- scanDirectory,
- onSessionEvent: (event) => events.push(event),
- onWorkerEvent: (event) => workers.push(event),
- });
- tracker.start("scan-thread");
- await tracker.refresh();
- expect(events.some((event) => event.threadId === "worker-thread")).toBe(
- false,
- );
-
- expect(workers).toEqual([]);
- if (missing === "parent") {
- await writeSession(home, "parent-worker", usage, {
- parent: "scan-thread",
- });
- } else {
- await writeMain();
- }
- await appendSessionItem(worker, message("Late worker output."));
- await tracker.refresh();
- await tracker.refresh();
- await tracker.stop();
-
- expect(workers).toEqual(
- missing === "parent"
- ? [
- { kind: "observed", worker: 1 },
- { kind: "observed", worker: 2 },
- ]
- : [{ kind: "observed", worker: 1 }],
- );
- const workerEvents = events.filter(
- (event) => event.threadId === "worker-thread",
- );
- expect(workerEvents.map((event) => event.event)).toEqual([
- expect.objectContaining({ type: "session_meta" }),
- expect.objectContaining({ type: "event_msg" }),
- { type: "response_item", payload: message("Early worker output.") },
- { type: "response_item", payload: message("Late worker output.") },
- ]);
- expect(new Set(workerEvents.map((event) => event.worker))).toEqual(
- new Set([1]),
- );
- expect(
- events.some((event) => event.threadId === "unrelated-thread"),
- ).toBe(false);
+test.each([
+ [
+ "prefers the spawned parent over legacy parent fields",
+ {
+ source: {
+ subagent: { thread_spawn: { parent_thread_id: "spawn-parent" } },
+ },
+ parent_thread_id: "direct-parent",
+ forked_from_id: "fork-parent",
},
- );
+ "spawn-parent",
+ ],
+ [
+ "prefers the direct parent over fork ancestry",
+ { parent_thread_id: "direct-parent", forked_from_id: "fork-parent" },
+ "direct-parent",
+ ],
+ [
+ "falls back from an empty spawned parent to the direct parent",
+ {
+ source: { subagent: { thread_spawn: { parent_thread_id: "" } } },
+ parent_thread_id: "direct-parent",
+ },
+ "direct-parent",
+ ],
+ [
+ "falls back from an empty direct parent to fork ancestry",
+ { parent_thread_id: "", forked_from_id: "fork-parent" },
+ "fork-parent",
+ ],
+ [
+ "ignores a non-string direct parent when fork ancestry is present",
+ { parent_thread_id: null, forked_from_id: "fork-parent" },
+ "fork-parent",
+ ],
+ ["recognizes independent CLI sessions", { source: "cli" }, null],
+ ["treats an empty parent as missing", { forked_from_id: "" }, null],
+] as const)("session parent metadata %s", (_name, metadata, expected) => {
+ expect(sessionParentThreadId(metadata)).toBe(expected);
+});
- test.each([
- ["EACCES", true],
- ["EACCES", false],
- ["EPERM", true],
- ["EPERM", false],
- ] as const)(
- "retains and retries a %s worker when its parent appears later (already identified: %j)",
- async (code, identified) => {
- const home = await codexHome();
- const usage = (input_tokens: number) => ({
- input_tokens,
- output_tokens: 0,
- });
- await writeSession(home, "scan-thread", usage(10));
- const worker = await writeSession(home, "worker", usage(1), {
- parent: "middle",
- });
- let denied = !identified;
- let attempts = 0;
- const opened = filesystem.open;
- const opening = spyOn(filesystem, "open").mockImplementation(
- async (...args: Parameters<typeof filesystem.open>) => {
- if (String(args[0]) === worker && denied) {
- attempts += 1;
- throw Object.assign(new Error(`Synthetic ${code}`), {
- code,
- syscall: "open",
- path: worker,
- });
- }
- return await opened(...args);
+describe("scan cost", () => {
+ test("ignores token-count events without a usage snapshot in both readers", async () => {
+ const home = await codexHome();
+ const path = await writeSession(
+ home,
+ childUuid7Thread,
+ {},
+ { parent: scanThreadId },
+ );
+ const rollout = ownershipRollout([]);
+ rollout.splice(2, 0, {
+ type: "event_msg",
+ timestamp: "2026-07-26T12:04:00Z",
+ payload: {
+ type: "token_count",
+ info: null,
+ rate_limits: { limit_id: "replayed" },
+ },
+ });
+ await writeFile(
+ path,
+ jsonLines([
+ ...rollout,
+ {
+ type: "event_msg",
+ timestamp: "2026-07-26T12:03:00Z",
+ payload: {
+ type: "token_count",
+ info: null,
+ rate_limits: { primary: { used_percent: 5 } },
+ },
},
+ ]) + "\n",
+ );
+ const observations: ScanUsageObservation[] = [];
+ const tracker = new ScanCostTracker({
+ codexHome: home,
+ model: "gpt-6-astra",
+ onUsageObservation: (observation) => observations.push(observation),
+ });
+ tracker.start(scanThreadId);
+ expect((await tracker.stop()).usage).toEqual(ownedSdkUsage);
+ expect(observations).toEqual([
+ {
+ tokensUpdatedAt: "2026-07-26T12:02:00.250Z",
+ accountRateLimits: [
+ {
+ limitId: "codex",
+ observedAt: "2026-07-26T12:03:00.000Z",
+ primary: { usedPercent: 5, windowMinutes: null, resetsAt: null },
+ secondary: null,
+ },
+ ],
+ },
+ ]);
+ expect(readPythonRolloutUsage(BUNDLED_PLUGIN_ROOT, path)).toEqual({
+ usage: ownedPythonUsage,
+ warnings: [],
+ });
+ });
+
+ test("does not reopen unchanged rollouts and reads appended worker usage", async () => {
+ const { home, parent, worker } = await workerSessionFixture();
+ await writeSession(home, "unrelated-thread", {
+ input_tokens: 900,
+ output_tokens: 90,
+ });
+ const tracker = new ScanCostTracker({
+ codexHome: home,
+ model: "gpt-6-astra",
+ });
+ tracker.start("scan-thread");
+ await tracker.refresh();
+ const opened = spyOn(filesystem, "open");
+ try {
+ await tracker.refresh();
+ expect(opened).not.toHaveBeenCalled();
+ await appendFile(
+ worker,
+ jsonLines([
+ {
+ type: "event_msg",
+ payload: {
+ type: "token_count",
+ info: {
+ total_token_usage: { input_tokens: 200, output_tokens: 20 },
+ },
+ },
+ },
+ ]) + "\n",
);
- const reported: number[] = [];
- const tracker = new ScanCostTracker({
- codexHome: home,
- model: "gpt-5.6-sol",
- maxCostUsd: 1,
- onCost: (cost) => reported.push(cost.inputTokens),
+ const snapshot = await tracker.refresh();
+ expect(opened.mock.calls.map(([path]) => path)).toEqual([worker]);
+ expect(snapshot.usage).toMatchObject({
+ input_tokens: 300,
+ output_tokens: 30,
});
- tracker.start("scan-thread");
- try {
- if (identified) {
- expect((await tracker.refresh()).cost?.inputTokens).toBe(10);
- denied = true;
- expect((await tracker.refresh()).cost?.inputTokens).toBe(10);
- } else {
- await expect(tracker.refresh()).rejects.toMatchObject({ code });
- }
- await appendFile(
- worker,
- `${JSON.stringify({ type: "event_msg", payload: { type: "token_count", info: { total_token_usage: usage(1_000_000) } } })}\n`,
- );
- await writeSession(home, "middle", usage(20), {
- parent: "scan-thread",
- });
- await expect(tracker.refresh()).rejects.toMatchObject({ code });
- await expect(tracker.refresh()).rejects.toMatchObject({ code });
- denied = false;
- const snapshot = await tracker.stop();
- expect(snapshot.cost?.inputTokens).toBe(1_000_030);
- expect(snapshot.cost!.estimatedUsd).toBeGreaterThan(1);
- expect(reported).toContain(1_000_030);
- expect(attempts).toBeGreaterThanOrEqual(2);
- } finally {
- denied = false;
- await tracker.stop().catch(() => {});
- opening.mockRestore();
+ expect(opened.mock.calls.map(([path]) => path)).not.toContain(parent);
+ } finally {
+ opened.mockRestore();
+ await tracker.stop();
+ }
+ });
+
+ test("reports known usage even when model pricing is unavailable", async () => {
+ const home = await codexHome();
+ await writeSession(home, "scan-thread", {
+ input_tokens: 100,
+ output_tokens: 10,
+ });
+ const usages: unknown[] = [];
+ const tracker = new ScanCostTracker({
+ codexHome: home,
+ model: "synthetic-unpriced-model",
+ onUsage: (usage) => usages.push(usage),
+ });
+ tracker.start("scan-thread");
+ const snapshot = await tracker.stop();
+ expect(snapshot.cost).toBeNull();
+ expect(snapshot.usage).toMatchObject({
+ input_tokens: 100,
+ output_tokens: 10,
+ });
+ expect(usages).toHaveLength(1);
+ expect(usages[0]).toEqual(snapshot.usage);
+ });
+
+ test("shows distinct token categories without adding cached input twice", () => {
+ expect(
+ formatTokenUsage({
+ input_tokens: 120,
+ cached_input_tokens: 30,
+ cache_write_tokens: 12,
+ output_tokens: 15,
+ }),
+ ).toBe(
+ "78 uncached input, 30 cache reads, 12 cache writes, 15 output, 135 total",
+ );
+ });
+
+ test("distinguishes missing cache writes from a reported zero", () => {
+ const usage = {
+ input_tokens: 120,
+ cached_input_tokens: 30,
+ output_tokens: 15,
+ };
+ expect(formatTokenUsage(tokenUsage(usage))).toBe(
+ "unavailable uncached input, 30 cache reads, unavailable cache writes, 15 output, 135 total",
+ );
+ expect(formatTokenUsage({ ...usage, cache_write_input_tokens: 0 })).toBe(
+ "90 uncached input, 30 cache reads, 0 cache writes, 15 output, 135 total",
+ );
+ expect(estimateScanCost("gpt-6-astra", usage)).toMatchObject({
+ cacheWriteInputTokens: 0,
+ cacheWriteInputTokensReported: false,
+ });
+ });
+
+ test("includes the price source and rates with each estimate", () => {
+ const cost = estimateScanCost("gpt-6-astra", {
+ input_tokens: 1_000_000,
+ cached_input_tokens: 200_000,
+ cache_write_input_tokens: 300_000,
+ output_tokens: 100_000,
+ });
+ expect(cost).toEqual({
+ model: "gpt-6-astra",
+ inputTokens: 1_000_000,
+ cachedInputTokens: 200_000,
+ cacheWriteInputTokens: 300_000,
+ outputTokens: 100_000,
+ estimatedUsd: 13.95,
+ estimatedUsdRange: { min: 13.95, max: 25.4, context: "unknown" },
+ pricing: {
+ source: "https://developers.openai.com/api/docs/pricing",
+ asOf: "2026-09-14",
+ serviceTier: "standard",
+ context: "short",
+ usdPerMillionTokens: {
+ input: 10,
+ cacheRead: 1,
+ cacheWrite: 12.5,
+ output: 50,
+ },
+ longContextUsdPerMillionTokens: {
+ input: 20,
+ cacheRead: 2,
+ cacheWrite: 25,
+ output: 75,
+ },
+ },
+ });
+ });
+ test.each(["gpt-6-sol", "openai.gpt-6-sol"])(
+ "prices every token category and both context ranges for %s",
+ (model) => {
+ expect(
+ estimateScanCost(model, {
+ input_tokens: 1_000_000,
+ cached_input_tokens: 200_000,
+ cache_write_input_tokens: 300_000,
+ output_tokens: 100_000,
+ }),
+ ).toEqual({
+ model,
+ inputTokens: 1_000_000,
+ cachedInputTokens: 200_000,
+ cacheWriteInputTokens: 300_000,
+ outputTokens: 100_000,
+ estimatedUsd: 2.79,
+ estimatedUsdRange: { min: 2.79, max: 5.08, context: "unknown" },
+ pricing: {
+ source: "https://developers.openai.com/api/docs/models/gpt-6-sol",
+ asOf: "2026-10-10",
+ serviceTier: "standard",
+ context: "short",
+ usdPerMillionTokens: {
+ input: 2,
+ cacheRead: 0.2,
+ cacheWrite: 2.5,
+ output: 10,
+ },
+ longContextUsdPerMillionTokens: {
+ input: 4,
+ cacheRead: 0.4,
+ cacheWrite: 5,
+ output: 15,
+ },
+ },
+ });
+ },
+ );
+ test.each([
+ [{ cache_write_tokens: 15 }, 15],
+ [{ cache_write_input_tokens: 0, cache_write_tokens: 15 }, 15],
+ [{ cache_write_input_tokens: 0, cache_write_tokens: 80 }, 0],
+ ] as const)(
+ "keeps workbench cache-write normalization aligned with SDK usage for %j as %p tokens",
+ async (cacheWrites, expectedCacheWrites) => {
+ const { PLUGIN_ROOT } = await import("./plugin-root.js");
+ const python = Bun.which("python3") ?? Bun.which("python");
+ expect(python).not.toBeNull();
+ const usage = {
+ input_tokens: 100,
+ cached_input_tokens: 40,
+ ...cacheWrites,
+ output_tokens: 20,
+ reasoning_output_tokens: 5,
+ total_tokens: 120,
+ };
+ const probe = [
+ "import json, sys",
+ "sys.path.insert(0, sys.argv[1])",
+ "import workbench_scan_usage",
+ "payload = {'info': {'total_token_usage': json.loads(sys.argv[2])}}",
+ "print(json.dumps(workbench_scan_usage._token_snapshot(payload)))",
+ ].join("\n");
+ const result = runNodePython(python!, [
+ "-c",
+ probe,
+ join(PLUGIN_ROOT, "scripts"),
+ JSON.stringify(usage),
+ ]);
+
+ expect(result.status, result.stderr).toBe(0);
+ expect(JSON.parse(result.stdout)).toMatchObject({
+ inputTokens: 100,
+ cachedInputTokens: 40,
+ cacheWriteInputTokens: expectedCacheWrites,
+ outputTokens: 20,
+ totalTokens: 120,
+ });
+ },
+ );
+
+ test("charges cached input at its discounted rate", () => {
+ expect(
+ estimateScanCost("gpt-5.6-sol", {
+ input_tokens: 1_250,
+ cached_input_tokens: 200,
+ output_tokens: 30,
+ }),
+ ).toMatchObject({
+ model: "gpt-5.6-sol",
+ inputTokens: 1_250,
+ cachedInputTokens: 200,
+ cacheWriteInputTokens: 0,
+ outputTokens: 30,
+ estimatedUsd: 0.00488,
+ });
+ });
+
+ test("charges GPT-5.6 cache writes at their published rate", () => {
+ expect(
+ estimateScanCost("gpt-5.6-sol", {
+ input_tokens: 1_000,
+ cached_input_tokens: 100,
+ cache_write_input_tokens: 200,
+ output_tokens: 10,
+ })?.estimatedUsd,
+ ).toBe(0.00404);
+ });
+
+ test("preserves legacy cache writes after SDK normalization adds zero", () => {
+ expect(
+ estimateScanCost("gpt-5.6-sol", {
+ input_tokens: 1_000,
+ cached_input_tokens: 100,
+ cache_write_input_tokens: 0,
+ cache_write_tokens: 200,
+ output_tokens: 10,
+ }),
+ ).toMatchObject({ cacheWriteInputTokens: 200, estimatedUsd: 0.00404 });
+ });
+
+ test("ignores impossible legacy cache writes while retaining canonical usage", () => {
+ expect(
+ estimateScanCost("gpt-5.6-sol", {
+ input_tokens: 1_000,
+ cached_input_tokens: 100,
+ cache_write_input_tokens: 0,
+ cache_write_tokens: 1_001,
+ output_tokens: 10,
+ }),
+ ).toMatchObject({ cacheWriteInputTokens: 0, estimatedUsd: 0.00384 });
+ });
+
+ test("does not double-charge reasoning tokens included in output", () => {
+ expect(
+ estimateScanCost("gpt-5.6-sol", {
+ input_tokens: 1_000,
+ output_tokens: 10,
+ reasoning_output_tokens: 9,
+ })?.estimatedUsd,
+ ).toBe(0.0042);
+ });
+
+ test.each(Object.getOwnPropertyNames(Object.prototype))(
+ "does not inherit prices for unknown model %s",
+ (model) => {
+ for (const selected of [model, `openai.${model}`]) {
+ expect(
+ estimateScanCost(selected, { input_tokens: 1, output_tokens: 1 }),
+ ).toBeNull();
}
},
);
- test.each([...parentFields])(
- "counts independent Deep workers and %s descendants",
- async (parentField) => {
- const home = await codexHome();
- const scanDirectory = join(home, "scans", "current");
- const artifacts = join(scanDirectory, "artifacts");
- const workerDirectory = join(
- artifacts,
- "deep_discovery",
- "workers",
- "worker",
- "output",
- );
- await writeSession(
- home,
- "scan-thread",
- { input_tokens: 1_000, output_tokens: 10 },
- { cwd: scanDirectory, timestamp: "2026-07-26T12:00:00.900Z" },
- );
- await writeSession(
- home,
- "deep-worker",
- { input_tokens: 250, output_tokens: 2 },
+ test("does not invent prices for unknown models or incomplete usage", () => {
+ for (const [model, usage] of [
+ ["unknown-model", { input_tokens: 1, output_tokens: 1 }],
+ ["openai.unknown-model", { input_tokens: 1, output_tokens: 1 }],
+ ["gpt-5.6-sol", null],
+ ["gpt-5.6-sol", {}],
+ ["gpt-5.6-sol", { input_tokens: -1, output_tokens: 1 }],
+ ["gpt-5.6-sol", { input_tokens: 1.5, output_tokens: 1 }],
+ [
+ "gpt-5.6-sol",
+ { input_tokens: 1, cached_input_tokens: 2, output_tokens: 1 },
+ ],
+ [
+ "gpt-5.6-sol",
+ {
+ input_tokens: Number.MAX_SAFE_INTEGER,
+ output_tokens: Number.MAX_SAFE_INTEGER,
+ },
+ ],
+ ] as const) {
+ expect(estimateScanCost(model, usage)).toBeNull();
+ }
+ });
+});
+
+describe("live scan cost tracking", () => {
+ test("observes account limits and actual token measurement times from this scan", async () => {
+ const home = await codexHome();
+ const path = await writeSession(home, scanThreadId, {});
+ const unrelated = await writeSession(home, "unrelated", {});
+ const older = "2026-07-26T12:00:00.000Z";
+ const limitAt = "2026-07-26T12:01:00.000Z";
+ const tokensAt = "2026-07-26T12:02:00.000Z";
+ const later = "2026-07-26T12:03:00.000Z";
+ const limit = (timestamp: string, usedPercent: number) => ({
+ type: "event_msg",
+ timestamp,
+ payload: {
+ type: "token_count",
+ info: null,
+ rate_limits: {
+ limit_id: "codex",
+ secondary: { used_percent: usedPercent, window_minutes: 10_080 },
+ },
+ },
+ });
+ await appendFile(path, jsonLines([limit(limitAt, 12)]) + "\n");
+ await appendFile(unrelated, jsonLines([limit(later, 99)]) + "\n");
+ const observations: ScanUsageObservation[] = [];
+ const tracker = costTracker(home, {
+ onUsageObservation: (observation) => observations.push(observation),
+ });
+ tracker.start(scanThreadId);
+ const accountRateLimits = [
+ {
+ limitId: "codex",
+ observedAt: limitAt,
+ primary: null,
+ secondary: { usedPercent: 12, windowMinutes: 10_080, resetsAt: null },
+ },
+ ];
+ try {
+ expect((await tracker.refresh()).usage).toBeNull();
+ expect(observations).toEqual([
+ { tokensUpdatedAt: null, accountRateLimits },
+ ]);
+ const receipt = nativeUsageRecord(
+ scanThreadId,
+ "response",
+ ownedSdkUsage,
+ );
+ await appendFile(
+ path,
+ jsonLines([
+ { ...receipt, timestamp: tokensAt },
+ { ...receipt, timestamp: later },
+ limit(older, 3),
+ ]) + "\n",
+ );
+ expect((await tracker.refresh()).usage).toEqual(ownedSdkUsage);
+ await tracker.refresh();
+ expect(observations.slice(1)).toEqual([
+ { tokensUpdatedAt: tokensAt, accountRateLimits },
+ ]);
+ } finally {
+ await tracker.stop();
+ }
+ });
+
+ test("keeps receipt cache-write detail when an equal legacy counter omits it", async () => {
+ const home = await codexHome();
+ const usage = {
+ ...ownedSdkUsage,
+ cached_input_tokens: 20,
+ cache_write_input_tokens: 12,
+ };
+ const path = await writeSession(home, scanThreadId, ownedSdkUsage);
+ await appendFile(
+ path,
+ jsonLines([
+ nativeUsageRecord(scanThreadId, "response-1", usage),
+ legacyUsageRecord(ownedSdkUsage),
+ ]) + "\n",
+ );
+ const tracker = costTracker(home);
+ tracker.start(scanThreadId);
+ expect((await tracker.stop(ownedSdkUsage)).cost).toMatchObject({
+ inputTokens: 100,
+ cachedInputTokens: 20,
+ cacheWriteInputTokens: 12,
+ outputTokens: 10,
+ });
+ });
+
+ test("keeps freshness with the last reportable token total", async () => {
+ const home = await codexHome();
+ const parent = await writeSession(home, scanThreadId, {});
+ const first = "2026-07-26T10:01:00.000Z";
+ const second = "2026-07-26T10:02:00.000Z";
+ const third = "2026-07-26T10:03:00.000Z";
+ const measure = (
+ path: string,
+ timestamp: string | undefined,
+ input: number,
+ ) =>
+ appendFile(
+ path,
+ jsonLines([
+ {
+ ...legacyUsageRecord({ input_tokens: input, output_tokens: 0 }),
+ timestamp,
+ },
+ ]) + "\n",
+ );
+ await measure(parent, first, 10);
+ const times: Array<string | null> = [];
+ const tracker = costTracker(home, {
+ onUsageObservation: ({ tokensUpdatedAt }) => times.push(tokensUpdatedAt),
+ });
+ tracker.start(scanThreadId);
+ try {
+ expect((await tracker.refresh()).usage).toMatchObject({
+ total_tokens: 10,
+ });
+ const worker = await writeSession(
+ home,
+ "worker",
+ {},
+ { parent: scanThreadId },
+ );
+ await measure(parent, second, 20);
+ expect((await tracker.refresh()).usage).toBeNull();
+ expect(times).toEqual([first]);
+ await measure(worker, third, 7);
+ expect((await tracker.refresh()).usage).toMatchObject({
+ total_tokens: 27,
+ });
+ expect(times).toEqual([first, third]);
+ tracker.recordUsage({ input_tokens: 30, output_tokens: 0 });
+ expect((await tracker.refresh()).usage).toMatchObject({
+ total_tokens: 37,
+ });
+ expect(times).toEqual([first, third, null]);
+ await measure(parent, third, 30);
+ await tracker.refresh();
+ expect(times.at(-1)).toBe(third);
+ await measure(parent, undefined, 30);
+ await tracker.refresh();
+ expect(times.at(-1)).toBe(third);
+ await measure(parent, undefined, 31);
+ expect((await tracker.refresh()).usage).toMatchObject({
+ total_tokens: 38,
+ });
+ expect(times.at(-1)).toBeNull();
+ } finally {
+ await tracker.stop();
+ }
+ });
+
+ test("counts compaction receipts before stale counters and deduplicates responses", async () => {
+ const home = await codexHome();
+ const original = { ...ownedSdkUsage };
+ const compact = { ...ownedSdkUsage, input_tokens: 40, output_tokens: 3 };
+ const compactTotal = {
+ ...ownedSdkUsage,
+ input_tokens: 140,
+ output_tokens: 13,
+ };
+ const path = await writeSession(home, scanThreadId, original);
+ await appendFile(
+ path,
+ jsonLines([nativeUsageRecord(scanThreadId, "response-1", original)]) +
+ "\n",
+ );
+ const budget = new AbortController();
+ const maxCostUsd = 0.000355;
+ const tracker = new ScanCostTracker({
+ codexHome: home,
+ model: "gpt-6.1-sol",
+ maxCostUsd,
+ onCost: ({ estimatedUsd }) => {
+ if (estimatedUsd > maxCostUsd) budget.abort();
+ },
+ });
+ tracker.start(scanThreadId);
+ expect((await tracker.refresh()).cost?.estimatedUsd).toBe(0.0003);
+ expect(budget.signal.aborted).toBe(false);
+
+ const compaction = nativeUsageRecord(
+ scanThreadId,
+ "response-compaction",
+ compact,
+ compactTotal,
+ );
+ await appendFile(
+ path,
+ jsonLines([
+ compaction,
+ { type: "compacted", payload: { message: "Compacted context." } },
+ legacyUsageRecord(original),
+ ]) + "\n",
+ );
+ expect((await tracker.refresh()).cost?.estimatedUsd).toBe(0.00041);
+ expect(budget.signal.aborted).toBe(true);
+
+ const final = { ...ownedSdkUsage, input_tokens: 170, output_tokens: 15 };
+ const stale = { ...ownedSdkUsage, input_tokens: 130, output_tokens: 12 };
+ await appendFile(
+ path,
+ jsonLines([
+ compaction,
+ nativeUsageRecord(
+ scanThreadId,
+ "response-2",
+ { ...ownedSdkUsage, input_tokens: 30, output_tokens: 2 },
+ final,
+ ),
+ legacyUsageRecord(stale),
+ ]) + "\n",
+ );
+ expect((await tracker.stop(stale)).usage).toMatchObject({
+ input_tokens: 170,
+ output_tokens: 15,
+ total_tokens: 185,
+ });
+ });
+
+ test("keeps native receipts scoped to the owned fork across resumed turns", async () => {
+ const home = await codexHome();
+ const inherited = {
+ ...ownedSdkUsage,
+ input_tokens: 1_000,
+ output_tokens: 100,
+ };
+ const parent = await writeSession(home, scanThreadId, inherited);
+ await appendFile(
+ parent,
+ jsonLines([
+ nativeUsageRecord(scanThreadId, "parent-response", inherited),
+ ]) + "\n",
+ );
+ const child = await writeSession(home, childUuid7Thread, ownedSdkUsage, {
+ parent: scanThreadId,
+ });
+ const rollout = ownershipRollout([lowerUuid7Turn]);
+ rollout.splice(
+ 3,
+ 0,
+ nativeUsageRecord(scanThreadId, "parent-response", inherited),
+ );
+ rollout.push(
+ nativeUsageRecord(childUuid7Thread, "child-response", ownedSdkUsage),
+ nativeUsageRecord(scanThreadId, "foreign-response", inherited),
+ );
+ await writeFile(child, jsonLines(rollout) + "\n");
+ const tracker = costTracker(home, { onSessionEvent: () => {} });
+ tracker.start(scanThreadId);
+ expect((await tracker.refresh()).usage).toMatchObject({
+ input_tokens: 1_100,
+ output_tokens: 110,
+ });
+ const compact = { ...ownedSdkUsage, input_tokens: 40, output_tokens: 3 };
+ const compactTotal = {
+ ...ownedSdkUsage,
+ input_tokens: 140,
+ output_tokens: 13,
+ };
+ const compaction = nativeUsageRecord(
+ childUuid7Thread,
+ "child-compact",
+ compact,
+ compactTotal,
+ );
+ await appendFile(child, jsonLines([compaction, compaction]) + "\n");
+ expect((await tracker.stop(inherited)).usage).toMatchObject({
+ input_tokens: 1_140,
+ output_tokens: 113,
+ });
+
+ await appendFile(
+ child,
+ jsonLines([
+ {
+ type: "event_msg",
+ payload: {
+ type: "task_started",
+ turn_id: "019f9e4d-b3bb-7000-8000-000000000004",
+ },
+ },
+ nativeUsageRecord(
+ childUuid7Thread,
+ "resumed-response",
+ { ...ownedSdkUsage, input_tokens: 60, output_tokens: 6 },
+ { ...ownedSdkUsage, input_tokens: 200, output_tokens: 19 },
+ ),
+ ]) + "\n",
+ );
+ const resumed = costTracker(home);
+ resumed.start(scanThreadId);
+ expect((await resumed.stop(inherited)).usage).toMatchObject({
+ input_tokens: 1_200,
+ output_tokens: 119,
+ });
+ });
+
+ test.each([1_000, 1_100])(
+ "reconciles a native resumed total with a final SDK receipt of %p input tokens",
+ async (finalInput) => {
+ const home = await codexHome();
+ const path = await writeSession(home, scanThreadId, {
+ ...ownedSdkUsage,
+ input_tokens: 1_000,
+ });
+ await appendFile(
+ path,
+ jsonLines([
+ nativeUsageRecord(
+ scanThreadId,
+ "resumed-response",
+ { ...ownedSdkUsage, input_tokens: 20, output_tokens: 2 },
+ { ...ownedSdkUsage, input_tokens: 1_020, output_tokens: 12 },
+ ),
+ ]) + "\n",
+ );
+ const tracker = costTracker(home);
+ tracker.start(scanThreadId);
+ expect(
+ (await tracker.stop({ ...ownedSdkUsage, input_tokens: finalInput }))
+ .cost?.inputTokens,
+ ).toBe(Math.max(1_020, finalInput));
+ },
+ );
+
+ test.each([
+ [undefined, undefined],
+ [0, 0],
+ [12, undefined],
+ [undefined, 12],
+ ] as const)(
+ "preserves cache-write usage through SDK normalization: log %p, receipt %p",
+ async (writes, receiptWrites) => {
+ const home = await codexHome();
+ const usage = {
+ input_tokens: 120,
+ cached_input_tokens: 30,
+ output_tokens: 15,
+ ...(writes === undefined ? {} : { cache_write_input_tokens: writes }),
+ };
+ await writeSession(home, "scan-thread", usage);
+ const thread = new Codex({
+ codexPathOverride: process.execPath,
+ }).startThread();
+ const executable = thread as unknown as {
+ _exec: { run(): AsyncGenerator<string> };
+ };
+ executable._exec.run = async function* () {
+ yield JSON.stringify({
+ type: "thread.started",
+ thread_id: "scan-thread",
+ });
+ yield JSON.stringify({
+ type: "turn.completed",
+ usage: { ...usage, cache_write_input_tokens: receiptWrites },
+ });
+ };
+ const receipt = (await thread.run("Scan the repository.")).usage;
+ expect(receipt?.cache_write_input_tokens).toBe(receiptWrites ?? 0);
+ const tracker = new ScanCostTracker({
+ codexHome: home,
+ model: "gpt-6-astra",
+ });
+ tracker.start("scan-thread");
+ const running = await tracker.refresh();
+ const completed = await tracker.stop(receipt);
+
+ expect(formatTokenUsage(running.usage)).toContain(
+ `${writes ?? "unavailable"} cache writes`,
+ );
+ const expectedWrites = receiptWrites ?? writes;
+ expect(completed.cost).toMatchObject({
+ inputTokens: 120,
+ cachedInputTokens: 30,
+ cacheWriteInputTokens: expectedWrites ?? 0,
+ outputTokens: 15,
+ });
+ expect(completed.cost?.cacheWriteInputTokensReported).toBe(
+ expectedWrites === undefined ? false : undefined,
+ );
+ expect(formatTokenUsage(completed.usage)).toContain(
+ `${expectedWrites ?? "unavailable"} cache writes`,
+ );
+ },
+ );
+
+ test("retains reported write charges when another worker omits cache writes", async () => {
+ const home = await codexHome();
+ await writeSession(home, "scan-thread", {
+ input_tokens: 100,
+ cached_input_tokens: 20,
+ output_tokens: 10,
+ });
+ await writeSession(
+ home,
+ "worker-thread",
+ {
+ input_tokens: 200,
+ cached_input_tokens: 40,
+ cache_write_input_tokens: 50,
+ output_tokens: 20,
+ },
+ { parent: "scan-thread" },
+ );
+ const tracker = new ScanCostTracker({
+ codexHome: home,
+ model: "gpt-6-astra",
+ });
+ tracker.start("scan-thread");
+ const snapshot = await tracker.stop();
+ expect(snapshot.usage).toMatchObject({
+ input_tokens: 300,
+ cache_write_input_tokens: 50,
+ cache_write_input_tokens_reported: false,
+ total_tokens: 330,
+ });
+ expect(snapshot.cost).toMatchObject({
+ cacheWriteInputTokens: 50,
+ cacheWriteInputTokensReported: false,
+ estimatedUsd: 0.004085,
+ });
+ expect(formatTokenUsage(snapshot.usage)).toContain(
+ "unavailable cache writes",
+ );
+ });
+
+ test("reports newly available cache writes even when the dollar amount is unchanged", async () => {
+ const home = await codexHome();
+ const updates: unknown[] = [];
+ const tracker = new ScanCostTracker({
+ codexHome: home,
+ model: "gpt-5.5",
+ onCost: (cost) => updates.push(cost),
+ });
+ tracker.start("scan-thread");
+ tracker.recordUsage(
+ { input_tokens: 100, output_tokens: 10 },
+ "scan-thread",
+ );
+ await tracker.refresh();
+ tracker.recordUsage(
+ { input_tokens: 100, cache_write_input_tokens: 0, output_tokens: 10 },
+ "scan-thread",
+ );
+ await tracker.stop();
+ expect(updates).toHaveLength(2);
+ expect(updates[0]).toHaveProperty("cacheWriteInputTokensReported", false);
+ expect(updates[1]).not.toHaveProperty("cacheWriteInputTokensReported");
+ });
+ test("coalesces overlapping polling ticks and bounds final work", async () => {
+ const home = await codexHome();
+ await writeSession(home, "scan-thread", {
+ input_tokens: 100,
+ output_tokens: 10,
+ });
+ const releases: Array<() => void> = [];
+ const tracker = costTracker(home, {
+ maxCostUsd: 1,
+ });
+ const refresh = tracker.refresh.bind(tracker);
+ tracker.refresh = async () => {
+ await new Promise<void>((resolve) => releases.push(resolve));
+ return refresh();
+ };
+ tracker.start("scan-thread");
+
+ await new Promise<void>((resolve) => setTimeout(resolve, 350));
+ expect(releases).toHaveLength(1);
+
+ const stopped = tracker.stop();
+ expect(releases).toHaveLength(2);
+ releases[0]!();
+ releases[1]!();
+
+ expect((await stopped).cost?.inputTokens).toBe(100);
+ expect(releases).toHaveLength(2);
+ });
+
+ test("retries one coalesced poll after a failed refresh", async () => {
+ const home = await codexHome();
+ await writeSession(home, "scan-thread", {
+ input_tokens: 100,
+ output_tokens: 10,
+ });
+ const errors: string[] = [];
+ let traversals = 0;
+ const { promise: blocked, resolve: release } =
+ Promise.withResolvers<void>();
+ const tracker = costTracker(home, {
+ maxCostUsd: 1,
+ onError: (error) => {
+ if (error instanceof Error) errors.push(error.message);
+ },
+ });
+ const refresh = tracker.refresh.bind(tracker);
+ tracker.refresh = async () => {
+ traversals += 1;
+ if (traversals === 1) {
+ await blocked;
+ throw new Error("session read failed");
+ }
+ return refresh();
+ };
+ tracker.start("scan-thread");
+
+ await new Promise<void>((resolve) => setTimeout(resolve, 250));
+ expect(traversals).toBe(1);
+ release!();
+ await waitFor(() => traversals === 2);
+
+ expect(errors).toEqual(["session read failed"]);
+ expect(traversals).toBe(2);
+ expect((await tracker.stop()).cost?.inputTokens).toBe(100);
+ });
+
+ test("reports live token use and cost without a spending limit", async () => {
+ const home = await codexHome();
+ await writeSession(home, "scan-thread", {
+ input_tokens: 1_250,
+ cached_input_tokens: 200,
+ output_tokens: 30,
+ });
+ const { promise: reportedCost, resolve: reportCost } =
+ Promise.withResolvers<unknown>();
+ const tracker = costTracker(home, {
+ onCost: reportCost,
+ });
+ tracker.start("scan-thread");
+
+ try {
+ await expect(reportedCost).resolves.toMatchObject({
+ model: "gpt-5.6-sol",
+ inputTokens: 1_250,
+ cachedInputTokens: 200,
+ cacheWriteInputTokens: 0,
+ outputTokens: 30,
+ estimatedUsd: 0.00488,
+ });
+ } finally {
+ await tracker.stop();
+ }
+ });
+
+ test.each([...parentFields])(
+ "observes worker metadata without status markers or usage via %s",
+ async (parentField) => {
+ const home = await codexHome();
+ const parent = await writeSession(home, "scan-thread", {});
+ await appendSessionItem(parent, {
+ type: "message",
+ role: "assistant",
+ content: [
+ {
+ type: "output_text",
+ text:
+ 'CODEX_SECURITY_WORKER_STATUS {"phase":"validation","planned":1,"started":1}\n' +
+ '{"type":"session_meta","payload":{"id":"fictional-worker","parent_thread_id":"scan-thread"}}',
+ },
+ ],
+ });
+ await writeSession(
+ home,
+ "unrelated-worker",
+ {},
+ { parent: "other-scan" },
+ );
+ const workers: ScanWorkerEvent[] = [];
+ const tracker = costTracker(home, {
+ onWorkerEvent: (event) => workers.push(event),
+ });
+ tracker.start("scan-thread");
+ try {
+ await tracker.refresh();
+ expect(workers).toEqual([]);
+ const path = join(parse(parent).dir, "rollout-worker-thread.jsonl");
+ const metadata =
+ JSON.stringify({
+ type: "session_meta",
+ payload: {
+ id: "worker-thread",
+ ...parentMetadata("scan-thread", parentField),
+ instructions: "Synthetic private instructions",
+ },
+ }) + "\n";
+ await writeFile(path, metadata);
+ await tracker.refresh();
+ expect(workers).toEqual([{ kind: "observed", worker: 1 }]);
+ await writeFile(path.replace(".jsonl", "-copy.jsonl"), metadata);
+ await tracker.refresh();
+ await tracker.refresh();
+ expect(workers).toEqual([{ kind: "observed", worker: 1 }]);
+ } finally {
+ await tracker.stop();
+ }
+ },
+ );
+
+ test("polls for workers with only a worker observer and keeps concurrent scans separate", async () => {
+ const home = await codexHome();
+ const workers: ScanWorkerEvent[][] = [[], []];
+ const trackers = workers.map((events) =>
+ costTracker(home, {
+ onWorkerEvent: (event) => events.push(event),
+ }),
+ );
+ trackers.forEach((tracker, index) => tracker.start(`scan-${index}`));
+ try {
+ await Promise.all(trackers.map((tracker) => tracker.refresh()));
+ await writeSession(home, "worker-0", {}, { parent: "scan-0" });
+ await writeSession(home, "worker-1", {}, { parent: "scan-1" });
+ await waitFor(() => workers.every((events) => events.length === 1));
+ expect(workers).toEqual([
+ [{ kind: "observed", worker: 1 }],
+ [{ kind: "observed", worker: 1 }],
+ ]);
+ } finally {
+ await Promise.all(trackers.map((tracker) => tracker.stop()));
+ }
+ const resumed: ScanWorkerEvent[] = [];
+ const tracker = costTracker(home, {
+ onWorkerEvent: (event) => resumed.push(event),
+ });
+ tracker.start("scan-0");
+ await tracker.stop();
+ expect(resumed).toEqual([{ kind: "observed", worker: 1 }]);
+ });
+
+ test("counts the scan and delegated workers without including other scans", async () => {
+ const home = await codexHome();
+ const parent = await writeSession(home, "scan-thread", {
+ input_tokens: 1_000,
+ cached_input_tokens: 100,
+ cache_write_input_tokens: 200,
+ output_tokens: 10,
+ reasoning_output_tokens: 2,
+ });
+ const worker = await writeSession(
+ home,
+ "worker-thread",
+ {
+ input_tokens: 250,
+ cached_input_tokens: 50,
+ output_tokens: 5,
+ reasoning_output_tokens: 1,
+ },
+ { parent: "scan-thread" },
+ );
+ await writeSession(home, "unrelated-thread", {
+ input_tokens: 1_000_000,
+ output_tokens: 1_000_000,
+ });
+ const events: ScanSessionEvent[] = [];
+ const tracker = costTracker(home, {
+ onSessionEvent: (event) => events.push(event),
+ });
+ tracker.start("scan-thread");
+ await waitFor(() => events.length === 4);
+ await appendFile(
+ parent,
+ `${JSON.stringify({ type: "turn_context", payload: { instructions: "Check authorization" } })}\n`,
+ );
+ await appendSessionItem(worker, {
+ type: "function_call",
+ name: "spawn_agent",
+ });
+ await tracker.refresh();
+ await tracker.refresh();
+
+ expect(await tracker.stop()).toMatchObject({
+ usage: {
+ input_tokens: 1_250,
+ cached_input_tokens: 150,
+ cache_write_input_tokens: 200,
+ output_tokens: 15,
+ reasoning_output_tokens: 3,
+ total_tokens: 1_265,
+ },
+ cost: {
+ model: "gpt-5.6-sol",
+ inputTokens: 1_250,
+ cachedInputTokens: 150,
+ cacheWriteInputTokens: 200,
+ outputTokens: 15,
+ estimatedUsd: 0.00496,
+ },
+ });
+ expect(
+ events.map(({ threadId, parentThreadId, event }) => [
+ threadId,
+ parentThreadId,
+ event["type"],
+ ]),
+ ).toEqual(
+ expect.arrayContaining([
+ ["scan-thread", null, "session_meta"],
+ ["scan-thread", null, "event_msg"],
+ ["worker-thread", "scan-thread", "session_meta"],
+ ["worker-thread", "scan-thread", "event_msg"],
+ ["scan-thread", null, "turn_context"],
+ ["worker-thread", "scan-thread", "response_item"],
+ ]),
+ );
+ expect(events).toHaveLength(6);
+ });
+
+ test.each(["parent", "main"] as const)(
+ "replays early worker events when the %s session arrives later",
+ async (missing) => {
+ const home = await codexHome();
+ const scanDirectory = join(home, "scan");
+ const usage = { input_tokens: 10, output_tokens: 1 };
+ const writeMain = () =>
+ writeSession(home, "scan-thread", usage, {
+ cwd: scanDirectory,
+ timestamp: "2026-07-26T12:00:00Z",
+ });
+ if (missing === "parent") await writeMain();
+ const worker = await writeSession(home, "worker-thread", usage, {
+ parent: missing === "parent" ? "parent-worker" : undefined,
+ cwd: join(
+ scanDirectory,
+ "artifacts",
+ "deep_discovery",
+ "workers",
+ "one",
+ "output",
+ ),
+ timestamp: "2026-07-26T12:01:00Z",
+ });
+ const message = (text: string) => ({
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text }],
+ });
+ await appendSessionItem(worker, message("Early worker output."));
+ const unrelated = await writeSession(home, "unrelated-thread", usage);
+ await appendSessionItem(unrelated, message("Unrelated output."));
+ const events: ScanSessionEvent[] = [];
+ const workers: ScanWorkerEvent[] = [];
+ const tracker = costTracker(home, {
+ scanDirectory,
+ onSessionEvent: (event) => events.push(event),
+ onWorkerEvent: (event) => workers.push(event),
+ });
+ tracker.start("scan-thread");
+ await tracker.refresh();
+ expect(events.some((event) => event.threadId === "worker-thread")).toBe(
+ false,
+ );
+
+ expect(workers).toEqual([]);
+ if (missing === "parent") {
+ await writeSession(home, "parent-worker", usage, {
+ parent: "scan-thread",
+ });
+ } else {
+ await writeMain();
+ }
+ await appendSessionItem(worker, message("Late worker output."));
+ await tracker.refresh();
+ await tracker.refresh();
+ await tracker.stop();
+
+ expect(workers).toEqual(
+ missing === "parent"
+ ? [
+ { kind: "observed", worker: 1 },
+ { kind: "observed", worker: 2 },
+ ]
+ : [{ kind: "observed", worker: 1 }],
+ );
+ const workerEvents = events.filter(
+ (event) => event.threadId === "worker-thread",
+ );
+ expect(workerEvents.map((event) => event.event)).toEqual([
+ expect.objectContaining({ type: "session_meta" }),
+ expect.objectContaining({ type: "event_msg" }),
+ { type: "response_item", payload: message("Early worker output.") },
+ { type: "response_item", payload: message("Late worker output.") },
+ ]);
+ expect(new Set(workerEvents.map((event) => event.worker))).toEqual(
+ new Set([1]),
+ );
+ expect(
+ events.some((event) => event.threadId === "unrelated-thread"),
+ ).toBe(false);
+ },
+ );
+
+ test.each([
+ ["EACCES", true],
+ ["EACCES", false],
+ ["EPERM", true],
+ ["EPERM", false],
+ ] as const)(
+ "retains and retries a %s worker when its parent appears later (already identified: %j)",
+ async (code, identified) => {
+ const home = await codexHome();
+ const usage = (input_tokens: number) => ({
+ input_tokens,
+ output_tokens: 0,
+ });
+ await writeSession(home, "scan-thread", usage(10));
+ const worker = await writeSession(home, "worker", usage(1), {
+ parent: "middle",
+ });
+ let denied = !identified;
+ let attempts = 0;
+ const opened = filesystem.open;
+ const opening = spyOn(filesystem, "open").mockImplementation(
+ async (...args: Parameters<typeof filesystem.open>) => {
+ if (String(args[0]) === worker && denied) {
+ attempts += 1;
+ throw Object.assign(new Error(`Synthetic ${code}`), {
+ code,
+ syscall: "open",
+ path: worker,
+ });
+ }
+ return await opened(...args);
+ },
+ );
+ const reported: number[] = [];
+ const tracker = new ScanCostTracker({
+ codexHome: home,
+ model: "gpt-5.6-sol",
+ maxCostUsd: 1,
+ onCost: (cost) => reported.push(cost.inputTokens),
+ });
+ tracker.start("scan-thread");
+ try {
+ if (identified) {
+ expect((await tracker.refresh()).cost?.inputTokens).toBe(10);
+ denied = true;
+ expect((await tracker.refresh()).cost?.inputTokens).toBe(10);
+ } else {
+ await expect(tracker.refresh()).rejects.toMatchObject({ code });
+ }
+ await appendFile(
+ worker,
+ `${JSON.stringify({ type: "event_msg", payload: { type: "token_count", info: { total_token_usage: usage(1_000_000) } } })}\n`,
+ );
+ await writeSession(home, "middle", usage(20), {
+ parent: "scan-thread",
+ });
+ await expect(tracker.refresh()).rejects.toMatchObject({ code });
+ await expect(tracker.refresh()).rejects.toMatchObject({ code });
+ denied = false;
+ const snapshot = await tracker.stop();
+ expect(snapshot.cost?.inputTokens).toBe(1_000_030);
+ expect(snapshot.cost!.estimatedUsd).toBeGreaterThan(1);
+ expect(reported).toContain(1_000_030);
+ expect(attempts).toBeGreaterThanOrEqual(2);
+ } finally {
+ denied = false;
+ await tracker.stop().catch(() => {});
+ opening.mockRestore();
+ }
+ },
+ );
+
+ test.each([...parentFields])(
+ "counts independent Deep workers and %s descendants",
+ async (parentField) => {
+ const home = await codexHome();
+ const scanDirectory = join(home, "scans", "current");
+ const artifacts = join(scanDirectory, "artifacts");
+ const workerDirectory = join(
+ artifacts,
+ "deep_discovery",
+ "workers",
+ "worker",
+ "output",
+ );
+ await writeSession(
+ home,
+ "scan-thread",
+ { input_tokens: 1_000, output_tokens: 10 },
+ { cwd: scanDirectory, timestamp: "2026-07-26T12:00:00.900Z" },
+ );
+ await writeSession(
+ home,
+ "deep-worker",
+ { input_tokens: 250, output_tokens: 2 },
+ {
+ cwd:
+ process.platform === "win32"
+ ? workerDirectory.toUpperCase()
+ : workerDirectory,
+ timestamp: "2026-07-26T12:00:00.900Z",
+ },
+ );
+ await writeSession(
+ home,
+ "deep-reducer",
+ { input_tokens: 125, output_tokens: 1 },
+ {
+ cwd:
+ (process.platform === "win32"
+ ? artifacts.toUpperCase()
+ : artifacts) + sep,
+ timestamp: "2026-07-26T12:02:00Z",
+ },
+ );
+ await writeSession(
+ home,
+ "deep-worker-child",
+ { input_tokens: 50, output_tokens: 1 },
+ { parent: "deep-worker", parentField },
+ );
+ await writeSession(
+ home,
+ "unrelated-thread",
+ { input_tokens: 1_000_000, output_tokens: 1_000_000 },
+ { cwd: `${scanDirectory}-other` },
+ );
+ await writeSession(
+ home,
+ "previous-scan",
+ { input_tokens: 1_000_000, output_tokens: 1_000_000 },
+ {
+ cwd: join(
+ scanDirectory,
+ "artifacts",
+ "deep_discovery",
+ "previous-worker",
+ ),
+ timestamp: "2026-07-26T11:59:00Z",
+ },
+ );
+ await writeSession(
+ home,
+ "unknown-start",
+ { input_tokens: 1_000_000, output_tokens: 1_000_000 },
+ {
+ cwd: join(
+ scanDirectory,
+ "artifacts",
+ "deep_discovery",
+ "workers",
+ "stale",
+ "output",
+ ),
+ },
+ );
+ await writeSession(
+ home,
+ "nested-scan",
+ { input_tokens: 1_000_000, output_tokens: 1_000_000 },
+ {
+ cwd: join(scanDirectory, "nested", "artifacts"),
+ timestamp: "2026-07-26T12:03:00Z",
+ },
+ );
+ const events: ScanSessionEvent[] = [];
+ const workers: ScanWorkerEvent[] = [];
+ const tracker = costTracker(home, {
+ scanDirectory,
+ onSessionEvent: (event) => events.push(event),
+ onWorkerEvent: (event) => workers.push(event),
+ });
+ tracker.start("scan-thread");
+
+ expect((await tracker.stop()).usage).toMatchObject({
+ input_tokens: 1_425,
+ output_tokens: 14,
+ });
+ expect(workers).toEqual(
+ [1, 2, 3].map((worker) => ({ kind: "observed", worker })),
+ );
+ const labels = new Map(
+ events.map(({ threadId, worker }) => [threadId, worker]),
+ );
+ expect(new Set(labels.keys())).toEqual(
+ new Set([
+ "scan-thread",
+ "deep-worker",
+ "deep-reducer",
+ "deep-worker-child",
+ ]),
+ );
+ expect(labels.get("scan-thread")).toBeUndefined();
+ expect(
+ [...labels.values()].filter((worker) => worker !== undefined).sort(),
+ ).toEqual([1, 2, 3]);
+ const logs = await readScanLogs({
+ scanId: "scan-example",
+ threadId: "scan-thread",
+ codexHome: home,
+ scanDirectory,
+ });
+ expect(new Set(logs.sessions.map(({ threadId }) => threadId))).toEqual(
+ new Set(labels.keys()),
+ );
+ },
+ );
+
+ test.each([
+ [
+ "sessions beside the deep worker output directories",
+ (scan: string) => join(scan, "artifacts", "deep_discovery", "output"),
+ "2026-07-26T12:02:00Z",
+ undefined,
+ "source",
+ ],
+ [
+ "sessions on another Windows drive",
+ (scan: string) =>
+ parse(scan).root.toLowerCase().startsWith("c:")
+ ? "D:\\output"
+ : "C:\\output",
+ "2026-07-26T12:02:00Z",
+ undefined,
+ "source",
+ ],
+ [
+ "sessions earlier in the same second",
+ (scan: string) => join(scan, "artifacts"),
+ "2026-07-26T12:00:00.100Z",
+ undefined,
+ "source",
+ ],
+ [
+ "sessions with an invalid timestamp",
+ (scan: string) => join(scan, "artifacts"),
+ "not-a-timestamp",
+ undefined,
+ "source",
+ ],
+ [
+ "sessions with an unrelated parent",
+ (scan: string) => join(scan, "artifacts"),
+ "2026-07-26T12:02:00Z",
+ "unrelated-parent",
+ "source",
+ ],
+ [
+ "sessions with an unrelated direct parent",
+ (scan: string) => join(scan, "artifacts"),
+ "2026-07-26T12:02:00Z",
+ "unrelated-parent",
+ "parent_thread_id",
+ ],
+ [
+ "sessions forked from an unrelated parent",
+ (scan: string) => join(scan, "artifacts"),
+ "2026-07-26T12:02:00Z",
+ "unrelated-parent",
+ "forked_from_id",
+ ],
+ ] as const)(
+ "excludes %s from scan cost and logs",
+ async (_name, workingDirectory, timestamp, parentThreadId, parentField) => {
+ const home = await codexHome();
+ const scanDirectory = join(home, "scans", "current");
+ await writeSession(
+ home,
+ "scan-thread",
+ { input_tokens: 1_000, output_tokens: 10 },
+ { cwd: scanDirectory, timestamp: "2026-07-26T12:00:00.900Z" },
+ );
+ await writeSession(
+ home,
+ "deep-worker",
+ { input_tokens: 250, output_tokens: 2 },
+ {
+ cwd: join(
+ scanDirectory,
+ "artifacts",
+ "deep_discovery",
+ "workers",
+ "worker",
+ "output",
+ ),
+ timestamp: "2026-07-26T12:00:00.950Z",
+ },
+ );
+ await writeSession(
+ home,
+ "bystander",
+ { input_tokens: 1_000_000, output_tokens: 1_000_000 },
+ {
+ parent: parentThreadId,
+ cwd: workingDirectory(scanDirectory),
+ timestamp,
+ parentField,
+ },
+ );
+ await writeSession(
+ home,
+ "bystander-child",
+ { input_tokens: 1_000_000, output_tokens: 1_000_000 },
+ { parent: "bystander" },
+ );
+ const events: ScanSessionEvent[] = [];
+ const tracker = costTracker(home, {
+ scanDirectory,
+ maxCostUsd: 0.01,
+ onSessionEvent: (event) => events.push(event),
+ });
+ tracker.start("scan-thread");
+
+ const snapshot = await tracker.stop();
+ expect(snapshot.usage).toMatchObject({
+ input_tokens: 1_250,
+ output_tokens: 12,
+ });
+ expect(snapshot.cost?.estimatedUsd).toBe(0.00524);
+ const included = [
+ ...new Set(events.map(({ threadId }) => threadId)),
+ ].sort();
+ expect(included).toEqual(["deep-worker", "scan-thread"]);
+ const logs = await readScanLogs({
+ scanId: "scan-example",
+ threadId: "scan-thread",
+ codexHome: home,
+ scanDirectory,
+ });
+ expect(logs.sessions.map(({ threadId }) => threadId).sort()).toEqual(
+ included,
+ );
+ },
+ );
+
+ test.each([undefined, "not-a-timestamp"])(
+ "does not infer independent workers when the scan timestamp is %s",
+ async (timestamp) => {
+ const home = await codexHome();
+ const scanDirectory = join(home, "scan");
+ await writeSession(
+ home,
+ "scan-thread",
+ { input_tokens: 1_000, output_tokens: 10 },
+ { cwd: scanDirectory, timestamp },
+ );
+ await writeSession(
+ home,
+ "independent-worker",
+ { input_tokens: 1_000_000, output_tokens: 1_000_000 },
+ {
+ cwd: join(scanDirectory, "artifacts"),
+ timestamp: "2026-07-26T12:01:00Z",
+ },
+ );
+ await writeSession(
+ home,
+ "child-worker",
+ { input_tokens: 250, output_tokens: 2 },
+ { parent: "scan-thread" },
+ );
+ const tracker = costTracker(home, {
+ scanDirectory,
+ });
+ tracker.start("scan-thread");
+ expect((await tracker.stop()).usage).toMatchObject({
+ input_tokens: 1_250,
+ output_tokens: 12,
+ });
+ },
+ );
+
+ test.each([...parentFields])(
+ "ignores replayed parent history in %s worker sessions",
+ async (parentField) => {
+ const home = await codexHome();
+ const inherited = {
+ input_tokens: 1_000,
+ cached_input_tokens: 500,
+ cache_write_input_tokens: 100,
+ output_tokens: 100,
+ reasoning_output_tokens: 20,
+ };
+ await writeSession(home, "scan-thread", inherited);
+ const worker = await writeSession(home, "worker-thread", inherited);
+ const command =
+ 'rg "password" "$CODEX_SECURITY_REPOSITORY/routes/login.ts"';
+
+ await writeFile(
+ worker,
+ jsonLines([
+ {
+ type: "session_meta",
+ payload: {
+ id: "worker-thread",
+ timestamp: "2026-07-26T12:02:00.250Z",
+ ...parentMetadata("scan-thread", parentField),
+ },
+ },
+ {
+ type: "session_meta",
+ payload: {
+ id: "scan-thread",
+ timestamp: "2026-07-26T12:00:00.000Z",
+ source: "exec",
+ },
+ },
+ {
+ type: "event_msg",
+ payload: { type: "task_started", started_at: 1_785_067_200 },
+ },
+ {
+ type: "event_msg",
+ payload: {
+ type: "agent_message",
+ message: "Inherited parent commentary.",
+ },
+ },
+ {
+ type: "response_item",
+ payload: {
+ type: "function_call",
+ name: "exec_command",
+ call_id: "inherited-search",
+ arguments: JSON.stringify({ cmd: command }),
+ },
+ },
+ { type: "response_item", payload: progressMessage(7) },
+ {
+ type: "event_msg",
+ payload: {
+ type: "token_count",
+ info: { total_token_usage: inherited },
+ },
+ },
+ {
+ type: "event_msg",
+ payload: { type: "task_started", started_at: 1_785_067_320 },
+ },
+ {
+ type: "event_msg",
+ timestamp: "2026-07-26T12:02:01.000Z",
+ payload: {
+ type: "agent_message",
+ message: "Reviewing the login query.",
+ },
+ },
+ {
+ type: "response_item",
+ payload: {
+ type: "function_call",
+ name: "exec_command",
+ call_id: "worker-search",
+ arguments: JSON.stringify({ cmd: command }),
+ },
+ },
+ {
+ type: "response_item",
+ payload: {
+ type: "function_call_output",
+ call_id: "worker-search",
+ output:
+ "Batch reviewed.\n" +
+ 'CODEX_SECURITY_SCAN_PROGRESS {"phase":"discovery","filesCompleted":3,"filesTotal":8}',
+ },
+ },
+ {
+ type: "event_msg",
+ payload: {
+ type: "token_count",
+ info: {
+ total_token_usage: {
+ input_tokens: 1_300,
+ cached_input_tokens: 650,
+ cache_write_input_tokens: 150,
+ output_tokens: 130,
+ reasoning_output_tokens: 30,
+ },
+ },
+ },
+ },
+ ]) + "\n",
+ );
+
+ const activities: ScanActivity[] = [];
+ const progress: ScanProgress[] = [];
+ const events: ScanSessionEvent[] = [];
+ const workers: ScanWorkerEvent[] = [];
+ const tracker = new ScanCostTracker({
+ codexHome: home,
+ model: "gpt-5.6-terra",
+ repository: "/code/juice-shop",
+ expectedFilesTotal: 8,
+ onActivity: (activity) => activities.push(activity),
+ onProgress: (update) => progress.push(update),
+ onSessionEvent: (event) => events.push(event),
+ onWorkerEvent: (event) => workers.push(event),
+ });
+ tracker.start("scan-thread");
+
+ expect(await tracker.stop()).toMatchObject({
+ usage: {
+ input_tokens: 1_300,
+ cached_input_tokens: 650,
+ cache_write_input_tokens: 150,
+ output_tokens: 130,
+ reasoning_output_tokens: 30,
+ total_tokens: 1_430,
+ },
+ cost: {
+ model: "gpt-5.6-terra",
+ inputTokens: 1_300,
+ cachedInputTokens: 650,
+ cacheWriteInputTokens: 150,
+ outputTokens: 130,
+ estimatedUsd: 0.003065,
+ },
+ });
+ expect(workers).toEqual([{ kind: "observed", worker: 1 }]);
+ expect(activities).toEqual([
+ expect.objectContaining({
+ kind: "message",
+ description: "Reviewing the login query.",
+ worker: 1,
+ }),
+ expect.objectContaining({
+ id: "worker-thread:worker-search",
+ kind: "command",
+ status: "running",
+ worker: 1,
+ }),
+ expect.objectContaining({
+ id: "worker-thread:worker-search",
+ kind: "command",
+ status: "completed",
+ worker: 1,
+ }),
+ ]);
+ expect(progress).toEqual([
+ { phase: "discovery", filesCompleted: 3, filesTotal: 8 },
+ ]);
+ const workerEvents = events.filter(
+ ({ threadId }) => threadId === "worker-thread",
+ );
+ expect(workerEvents).toHaveLength(6);
+ expect(JSON.stringify(workerEvents)).not.toContain(
+ "Inherited parent commentary.",
+ );
+ },
+ );
+
+ test.each([
+ [
+ "keeps an earlier-millisecond UUIDv7 turn in inherited history",
+ ["019f9e4d-b3b9-7000-8000-000000000001"],
+ ],
+ [
+ "keeps a same-millisecond lower UUIDv7 turn in inherited history",
+ [lowerUuid7Turn],
+ ],
+ ["accepts a same-millisecond higher UUIDv7 turn as child-owned", []],
+ ] as const)("%s", async (_name, replayedTurnIds) => {
+ const home = await codexHome();
+ const rolloutPath = await writeSession(
+ home,
+ childUuid7Thread,
+ { input_tokens: 1_100, output_tokens: 110 },
+ { parent: scanThreadId },
+ );
+ const rollout = ownershipRollout(replayedTurnIds);
+ await writeFile(rolloutPath, jsonLines(rollout) + "\n");
+
+ const maxCostUsd = 0.001;
+ const observedCosts: number[] = [];
+ const forwardedEvents: ScanSessionEvent[] = [];
+ const tracker = costTracker(home, {
+ maxCostUsd,
+ onCost: ({ estimatedUsd }) => observedCosts.push(estimatedUsd),
+ onSessionEvent: (event) => forwardedEvents.push(event),
+ });
+ tracker.start(scanThreadId);
+ const tracked = await tracker.stop();
+ const python = readPythonRolloutUsage(BUNDLED_PLUGIN_ROOT, rolloutPath);
+
+ expect({
+ trackedUsage: tracked.usage,
+ estimatedUsd: tracked.cost?.estimatedUsd,
+ python,
+ }).toMatchObject({
+ trackedUsage: ownedSdkUsage,
+ estimatedUsd: 0.0006,
+ python: {
+ usage: ownedPythonUsage,
+ warnings: [],
+ },
+ });
+ expect(observedCosts.length).toBeGreaterThan(0);
+ expect(observedCosts.every((cost) => cost < maxCostUsd)).toBe(true);
+ const forwardedTurnIds = forwardedEvents.flatMap(({ event }) => {
+ const payload = event["payload"];
+ return typeof payload === "object" &&
+ payload !== null &&
+ (payload as Record<string, unknown>)["type"] === "task_started"
+ ? [(payload as Record<string, unknown>)["turn_id"]]
+ : [];
+ });
+ expect(forwardedTurnIds).toEqual([higherUuid7Turn]);
+ const saved = await readScanLogs({
+ scanId: "scan-example",
+ threadId: childUuid7Thread,
+ codexHome: home,
+ });
+ const ownedEvents = [rollout[0]!, ...rollout.slice(-3)];
+ expect(forwardedEvents.map(({ event }) => event)).toEqual(ownedEvents);
+ expect(saved.events.map(({ event }) => event)).toEqual(ownedEvents);
+ });
+
+ test("forwards actions from this scan's delegated workers only", async () => {
+ const {
+ home,
+ usage,
+ parent: parentPath,
+ worker: workerPath,
+ } = await workerSessionFixture();
+ const unrelatedPath = await writeSession(home, "unrelated-thread", usage);
+ const command =
+ 'rg -n "password" "$CODEX_SECURITY_REPOSITORY/routes/login.ts"';
+
+ for (const [path, callId] of [
+ [parentPath, "parent-command"],
+ [workerPath, "worker-command"],
+ [unrelatedPath, "unrelated-command"],
+ ] as const) {
+ await appendSessionItem(path, {
+ type: "function_call",
+ name: "exec_command",
+ call_id: callId,
+ arguments: JSON.stringify({ cmd: command }),
+ });
+ await appendSessionItem(path, {
+ type: "function_call_output",
+ call_id: callId,
+ });
+ }
+
+ const activities: ScanActivity[] = [];
+ const events: ScanSessionEvent[] = [];
+ const tracker = costTracker(home, {
+ repository: "/code/juice-shop",
+ onActivity: (activity) => activities.push(activity),
+ onSessionEvent: (event) => events.push(event),
+ });
+ tracker.start("scan-thread");
+ await tracker.stop();
+
+ expect(activities).toEqual([
+ {
+ id: "worker-thread:worker-command",
+ kind: "command",
+ status: "running",
+ description: command,
+ paths: ["routes/login.ts"],
+ worker: 1,
+ },
+ {
+ id: "worker-thread:worker-command",
+ kind: "command",
+ status: "completed",
+ description: command,
+ paths: ["routes/login.ts"],
+ worker: 1,
+ },
+ ]);
+ expect(
+ new Map(events.map(({ threadId, worker }) => [threadId, worker])),
+ ).toEqual(
+ new Map([
+ ["scan-thread", undefined],
+ ["worker-thread", 1],
+ ]),
+ );
+ });
+
+ test("forwards genuine worker reasoning and transcript text", async () => {
+ const { home, worker: path } = await workerSessionFixture();
+ await appendSessionItem(path, {
+ id: "thinking-1",
+ type: "reasoning",
+ summary: [{ type: "summary_text", text: "Following the login query." }],
+ encrypted_content: "do-not-display",
+ });
+ await appendSessionItem(path, {
+ id: "message-1",
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text: "The query uses request input." }],
+ });
+
+ const { activities, tracker } = activityTracker(home);
+ tracker.start("scan-thread");
+ await tracker.stop();
+
+ expect(activities).toEqual([
+ {
+ id: "worker-thread:thinking-1",
+ kind: "reasoning",
+ status: "completed",
+ description: "Following the login query.",
+ paths: [],
+ worker: 1,
+ },
+ {
+ id: "worker-thread:message-1",
+ kind: "message",
+ status: "completed",
+ description: "The query uses request input.",
+ paths: [],
+ worker: 1,
+ },
+ ]);
+ });
+
+ test("streams worker reasoning and commentary from live session events once", async () => {
+ const { home, worker } = await workerSessionFixture();
+ await appendFile(
+ worker,
+ [
+ JSON.stringify({
+ type: "event_msg",
+ timestamp: "2026-07-26T12:00:00.000Z",
+ payload: {
+ type: "agent_reasoning",
+ text: "Tracing the login query.",
+ },
+ }),
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ id: "reasoning-1",
+ type: "reasoning",
+ summary: [
+ { type: "summary_text", text: "Tracing the login query." },
+ ],
+ encrypted_content: "must-never-be-displayed",
+ },
+ }),
+ JSON.stringify({
+ type: "event_msg",
+ timestamp: "2026-07-26T12:00:01.000Z",
+ payload: {
+ type: "agent_message",
+ message:
+ "Reviewed the login query.\n" +
+ 'CODEX_SECURITY_SCAN_PROGRESS {"phase":"discovery","filesCompleted":3,"filesTotal":8}',
+ },
+ }),
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ id: "message-1",
+ type: "message",
+ role: "assistant",
+ content: [
+ { type: "output_text", text: "Reviewed the login query." },
+ ],
+ },
+ }),
+ "",
+ ].join("\n"),
+ );
+
+ const activities: ScanActivity[] = [];
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ repository: "/code/juice-shop",
+ expectedFilesTotal: 8,
+ onActivity: (activity) => activities.push(activity),
+ onProgress: (progress) => updates.push(progress),
+ });
+ tracker.start("scan-thread");
+ await tracker.stop();
+
+ expect(activities).toEqual([
+ expect.objectContaining({
+ kind: "reasoning",
+ description: "Tracing the login query.",
+ worker: 1,
+ }),
+ expect.objectContaining({
+ kind: "message",
+ description: "Reviewed the login query.",
+ worker: 1,
+ }),
+ ]);
+ expect(updates).toEqual([
+ { phase: "discovery", filesCompleted: 3, filesTotal: 8 },
+ ]);
+ });
+
+ test("expands streamed worker reasoning without duplicating summaries or exposing encrypted content", async () => {
+ const { home, worker } = await workerSessionFixture();
+ const details = `${"The query reaches a privileged tenant boundary. ".repeat(30)}Final authorization check.`;
+ const raw = `**The route builds SQL from request parameters.** ${details}`;
+ await appendFile(
+ worker,
+ [
{
- cwd:
- process.platform === "win32"
- ? workerDirectory.toUpperCase()
- : workerDirectory,
- timestamp: "2026-07-26T12:00:00.900Z",
+ type: "event_msg",
+ payload: {
+ type: "agent_reasoning_delta",
+ delta: "Checking whether ",
+ },
},
- );
- await writeSession(
- home,
- "deep-reducer",
- { input_tokens: 125, output_tokens: 1 },
{
- cwd:
- (process.platform === "win32"
- ? artifacts.toUpperCase()
- : artifacts) + sep,
- timestamp: "2026-07-26T12:02:00Z",
+ type: "event_msg",
+ payload: {
+ type: "agent_reasoning_delta",
+ delta: "the login query escapes user input.",
+ },
},
- );
- await writeSession(
- home,
- "deep-worker-child",
- { input_tokens: 50, output_tokens: 1 },
- { parent: "deep-worker", parentField },
- );
- await writeSession(
- home,
- "unrelated-thread",
- { input_tokens: 1_000_000, output_tokens: 1_000_000 },
- { cwd: `${scanDirectory}-other` },
- );
- await writeSession(
- home,
- "previous-scan",
- { input_tokens: 1_000_000, output_tokens: 1_000_000 },
{
- cwd: join(
- scanDirectory,
- "artifacts",
- "deep_discovery",
- "previous-worker",
- ),
- timestamp: "2026-07-26T11:59:00Z",
+ type: "event_msg",
+ payload: {
+ type: "agent_reasoning",
+ text: "Checking whether the login query escapes user input.",
+ },
},
- );
- await writeSession(
- home,
- "unknown-start",
- { input_tokens: 1_000_000, output_tokens: 1_000_000 },
{
- cwd: join(
- scanDirectory,
- "artifacts",
- "deep_discovery",
- "workers",
- "stale",
- "output",
- ),
+ type: "event_msg",
+ payload: {
+ type: "agent_reasoning_raw_content_delta",
+ delta: "The route builds SQL ",
+ },
},
- );
- await writeSession(
- home,
- "nested-scan",
- { input_tokens: 1_000_000, output_tokens: 1_000_000 },
{
- cwd: join(scanDirectory, "nested", "artifacts"),
- timestamp: "2026-07-26T12:03:00Z",
+ type: "event_msg",
+ payload: {
+ type: "agent_reasoning_raw_content_delta",
+ delta: "from request parameters.",
+ },
+ },
+ {
+ type: "event_msg",
+ payload: {
+ type: "agent_reasoning_raw_content",
+ text: raw,
+ },
+ },
+ {
+ type: "event_msg",
+ payload: {
+ type: "agent_reasoning",
+ text: "This summary must not replace public raw reasoning.",
+ },
},
- );
- const events: ScanSessionEvent[] = [];
- const workers: ScanWorkerEvent[] = [];
- const tracker = costTracker(home, {
- scanDirectory,
- onSessionEvent: (event) => events.push(event),
- onWorkerEvent: (event) => workers.push(event),
- });
- tracker.start("scan-thread");
-
- expect((await tracker.stop()).usage).toMatchObject({
- input_tokens: 1_425,
- output_tokens: 14,
- });
- expect(workers).toEqual(
- [1, 2, 3].map((worker) => ({ kind: "observed", worker })),
- );
- const labels = new Map(
- events.map(({ threadId, worker }) => [threadId, worker]),
- );
- expect(new Set(labels.keys())).toEqual(
- new Set([
- "scan-thread",
- "deep-worker",
- "deep-reducer",
- "deep-worker-child",
- ]),
- );
- expect(labels.get("scan-thread")).toBeUndefined();
- expect(
- [...labels.values()].filter((worker) => worker !== undefined).sort(),
- ).toEqual([1, 2, 3]);
- const logs = await readScanLogs({
- scanId: "scan-example",
- threadId: "scan-thread",
- codexHome: home,
- scanDirectory,
- });
- expect(new Set(logs.sessions.map(({ threadId }) => threadId))).toEqual(
- new Set(labels.keys()),
- );
- },
- );
-
- test.each([
- [
- "sessions beside the deep worker output directories",
- (scan: string) => join(scan, "artifacts", "deep_discovery", "output"),
- "2026-07-26T12:02:00Z",
- undefined,
- "source",
- ],
- [
- "sessions on another Windows drive",
- (scan: string) =>
- parse(scan).root.toLowerCase().startsWith("c:")
- ? "D:\\output"
- : "C:\\output",
- "2026-07-26T12:02:00Z",
- undefined,
- "source",
- ],
- [
- "sessions earlier in the same second",
- (scan: string) => join(scan, "artifacts"),
- "2026-07-26T12:00:00.100Z",
- undefined,
- "source",
- ],
- [
- "sessions with an invalid timestamp",
- (scan: string) => join(scan, "artifacts"),
- "not-a-timestamp",
- undefined,
- "source",
- ],
- [
- "sessions with an unrelated parent",
- (scan: string) => join(scan, "artifacts"),
- "2026-07-26T12:02:00Z",
- "unrelated-parent",
- "source",
- ],
- [
- "sessions with an unrelated direct parent",
- (scan: string) => join(scan, "artifacts"),
- "2026-07-26T12:02:00Z",
- "unrelated-parent",
- "parent_thread_id",
- ],
- [
- "sessions forked from an unrelated parent",
- (scan: string) => join(scan, "artifacts"),
- "2026-07-26T12:02:00Z",
- "unrelated-parent",
- "forked_from_id",
- ],
- ] as const)(
- "excludes %s from scan cost and logs",
- async (_name, workingDirectory, timestamp, parentThreadId, parentField) => {
- const home = await codexHome();
- const scanDirectory = join(home, "scans", "current");
- await writeSession(
- home,
- "scan-thread",
- { input_tokens: 1_000, output_tokens: 10 },
- { cwd: scanDirectory, timestamp: "2026-07-26T12:00:00.900Z" },
- );
- await writeSession(
- home,
- "deep-worker",
- { input_tokens: 250, output_tokens: 2 },
{
- cwd: join(
- scanDirectory,
- "artifacts",
- "deep_discovery",
- "workers",
- "worker",
- "output",
- ),
- timestamp: "2026-07-26T12:00:00.950Z",
+ type: "response_item",
+ payload: {
+ id: "reasoning-1",
+ type: "reasoning",
+ summary: [
+ {
+ type: "summary_text",
+ text: "Checking whether the login query escapes user input.",
+ },
+ { type: "summary_text", text: "Preparing SQL validation." },
+ ],
+ encrypted_content: "never-display-encrypted-reasoning",
+ },
},
- );
- await writeSession(
- home,
- "bystander",
- { input_tokens: 1_000_000, output_tokens: 1_000_000 },
+ "",
+ ]
+ .map((event) =>
+ typeof event === "string" ? event : JSON.stringify(event),
+ )
+ .join("\n"),
+ );
+
+ const { activities, tracker } = activityTracker(home);
+ tracker.start("scan-thread");
+ await tracker.stop();
+
+ expect(new Set(activities.map((activity) => activity.id))).toEqual(
+ new Set(["worker-thread:reasoning-1"]),
+ );
+ expect(activities).toContainEqual(
+ expect.objectContaining({
+ kind: "reasoning",
+ status: "running",
+ description: "Checking whether the login query escapes user input.",
+ worker: 1,
+ }),
+ );
+ expect(activities.at(-1)).toEqual({
+ id: "worker-thread:reasoning-1",
+ kind: "reasoning",
+ status: "completed",
+ description: `The route builds SQL from request parameters. ${details}`,
+ paths: [],
+ worker: 1,
+ });
+ expect(activities.at(-1)!.description.length).toBeGreaterThan(1_000);
+ expect(JSON.stringify(activities)).not.toContain("encrypted-reasoning");
+ });
+
+ test("keeps distinct streamed worker reasoning summaries separate", async () => {
+ const { home, worker } = await workerSessionFixture();
+ const summaries = [
+ "**Planning discovery worker tasks**",
+ "**Preparing thorough file batch reading**",
+ "**Verifying repository read access and tools**",
+ ];
+ await appendFile(
+ worker,
+ [
+ ...summaries.map((text) => ({
+ type: "event_msg",
+ payload: { type: "agent_reasoning", text },
+ })),
{
- parent: parentThreadId,
- cwd: workingDirectory(scanDirectory),
- timestamp,
- parentField,
+ type: "response_item",
+ payload: {
+ id: "reasoning-1",
+ type: "reasoning",
+ summary: summaries.map((text) => ({ type: "summary_text", text })),
+ encrypted_content: "must-never-be-displayed",
+ },
},
- );
- await writeSession(
- home,
- "bystander-child",
- { input_tokens: 1_000_000, output_tokens: 1_000_000 },
- { parent: "bystander" },
- );
- const events: ScanSessionEvent[] = [];
- const tracker = costTracker(home, {
- scanDirectory,
- maxCostUsd: 0.01,
- onSessionEvent: (event) => events.push(event),
- });
- tracker.start("scan-thread");
+ "",
+ ]
+ .map((event) =>
+ typeof event === "string" ? event : JSON.stringify(event),
+ )
+ .join("\n"),
+ );
- const snapshot = await tracker.stop();
- expect(snapshot.usage).toMatchObject({
- input_tokens: 1_250,
- output_tokens: 12,
- });
- expect(snapshot.cost?.estimatedUsd).toBe(0.00524);
- const included = [
- ...new Set(events.map(({ threadId }) => threadId)),
- ].sort();
- expect(included).toEqual(["deep-worker", "scan-thread"]);
- const logs = await readScanLogs({
- scanId: "scan-example",
- threadId: "scan-thread",
- codexHome: home,
- scanDirectory,
- });
- expect(logs.sessions.map(({ threadId }) => threadId).sort()).toEqual(
- included,
- );
- },
- );
+ const { activities, tracker } = activityTracker(home);
+ tracker.start("scan-thread");
+ await tracker.stop();
- test.each([undefined, "not-a-timestamp"])(
- "does not infer independent workers when the scan timestamp is %s",
- async (timestamp) => {
- const home = await codexHome();
- const scanDirectory = join(home, "scan");
- await writeSession(
- home,
- "scan-thread",
- { input_tokens: 1_000, output_tokens: 10 },
- { cwd: scanDirectory, timestamp },
- );
- await writeSession(
- home,
- "independent-worker",
- { input_tokens: 1_000_000, output_tokens: 1_000_000 },
+ expect(activities).toEqual(
+ summaries.map((text, index) => ({
+ id: `worker-thread:reasoning-${index + 1}`,
+ kind: "reasoning",
+ status: "completed",
+ description: text.replaceAll("**", ""),
+ paths: [],
+ worker: 1,
+ })),
+ );
+ });
+
+ test("splits worker reasoning summaries without streamed events", async () => {
+ const { home, worker } = await workerSessionFixture();
+ await appendSessionItem(worker, {
+ id: "reasoning-1",
+ type: "reasoning",
+ summary: [
+ { type: "summary_text", text: "**Planning discovery worker tasks**" },
{
- cwd: join(scanDirectory, "artifacts"),
- timestamp: "2026-07-26T12:01:00Z",
+ type: "summary_text",
+ text: "**Preparing thorough file batch reading**",
},
- );
- await writeSession(
- home,
- "child-worker",
- { input_tokens: 250, output_tokens: 2 },
- { parent: "scan-thread" },
- );
+ ],
+ encrypted_content: "must-never-be-displayed",
+ });
+
+ const { activities, tracker } = activityTracker(home);
+ tracker.start("scan-thread");
+ await tracker.stop();
+
+ expect(activities).toEqual([
+ {
+ id: "worker-thread:reasoning-1:0",
+ kind: "reasoning",
+ status: "completed",
+ description: "Planning discovery worker tasks",
+ paths: [],
+ worker: 1,
+ },
+ {
+ id: "worker-thread:reasoning-1:1",
+ kind: "reasoning",
+ status: "completed",
+ description: "Preparing thorough file batch reading",
+ paths: [],
+ worker: 1,
+ },
+ ]);
+ expect(JSON.stringify(activities)).not.toContain("must-never-be-displayed");
+ });
+
+ test("aggregates descendant worker progress and ignores unrelated sessions", async () => {
+ const { home, usage, worker } = await workerSessionFixture();
+ const descendant = await writeSession(home, "nested-worker-thread", usage, {
+ parent: "worker-thread",
+ });
+ const unrelated = await writeSession(home, "unrelated-thread", usage);
+
+ await appendSessionItem(worker, progressMessage(3));
+ await appendSessionItem(worker, progressMessage(4, 9));
+ await appendSessionItem(descendant, progressMessage(5));
+ await appendSessionItem(unrelated, progressMessage(7));
+
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (progress) => updates.push(progress),
+ });
+ tracker.start("scan-thread");
+ await tracker.stop();
+
+ expect(updates).toEqual([
+ { phase: "discovery", filesCompleted: expect.any(Number), filesTotal: 8 },
+ { phase: "discovery", filesCompleted: 8, filesTotal: 8 },
+ ]);
+ expect([3, 5]).toContain(updates[0]!.filesCompleted);
+ });
+
+ test("forwards parent custom-tool progress without adding global counts to worker totals", async () => {
+ const { home, parent, worker } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 942,
+ onProgress: (update) => updates.push(update),
+ });
+ tracker.start("scan-thread");
+ await tracker.refresh();
+ const marker =
+ 'CODEX_SECURITY_SCAN_PROGRESS {"phase":"discovery","filesCompleted":49,"filesTotal":942}';
+ await appendSessionItem(parent, {
+ type: "custom_tool_call_output",
+ call_id: "parent-progress",
+ output: [
+ { type: "input_text", text: "Script completed\nOutput:" },
+ { type: "input_text", text: marker },
+ ],
+ });
+ await tracker.refresh();
+ await appendSessionItem(parent, progressMessage(49, 942));
+ await appendSessionItem(worker, progressMessage(49, 942));
+ await tracker.refresh();
+ await appendSessionItem(parent, progressMessage(49, 942, "validation"));
+ await tracker.stop();
+ expect(updates).toEqual([
+ { phase: "discovery", filesCompleted: 49, filesTotal: 942 },
+ { phase: "validation", filesCompleted: 49, filesTotal: 942 },
+ ]);
+ });
+
+ test("keeps a global parent phase through equal worker progress and delayed provenance", async () => {
+ const { home, parent, worker } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => updates.push(update),
+ });
+ tracker.start("scan-thread");
+ await tracker.refresh();
+ const progress = {
+ phase: "discovery",
+ filesCompleted: 8,
+ filesTotal: 8,
+ } as const;
+ const text = "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(progress);
+ const event = {
+ type: "item.completed",
+ item: { type: "agent_message", text },
+ };
+ expect(tracker.recordParentProgress(progress, event)).toBe(true);
+ tracker.acceptParentProgress(progress, event);
+ updates.push(progress);
+ await appendSessionItem(worker, progressMessage(8, 8, "validation"));
+ await tracker.refresh();
+ await appendFile(
+ parent,
+ JSON.stringify({
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: { type: "AgentMessage", content: [{ type: "Text", text }] },
+ },
+ }) + "\n",
+ );
+ await tracker.stop();
+ expect(updates.map((update) => update.phase)).toEqual(["discovery"]);
+ });
+
+ test.each([false, true])(
+ "orders independent tool receipts by completion, not call start (%p)",
+ async (overlap) => {
+ const { home, parent } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
const tracker = costTracker(home, {
- scanDirectory,
+ expectedFilesTotal: 8,
+ onProgress: (update) => updates.push(update),
});
tracker.start("scan-thread");
- expect((await tracker.stop()).usage).toMatchObject({
- input_tokens: 1_250,
- output_tokens: 12,
+ await tracker.refresh();
+ const marker = (phase: string) => progressMarker(phase, 8, 8);
+ const call = {
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call",
+ call_id: "outer-call",
+ name: "exec",
+ input: "synthetic tool invocation",
+ },
+ };
+ const native = nativeCommand(
+ "inspect-source",
+ overlap ? commandOutput(marker("discovery")) : persistedCommandOutput,
+ );
+ const records: unknown[] = overlap
+ ? [
+ call,
+ native,
+ {
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [{ type: "Text", text: marker("validation") }],
+ },
+ },
+ },
+ ]
+ : [native, call];
+ records.push({
+ type: "response_item",
+ payload: {
+ type: "custom_tool_call_output",
+ call_id: "outer-call",
+ output: marker(overlap ? "discovery" : "validation"),
+ },
});
+ await appendFile(
+ parent,
+ records.map((record) => JSON.stringify(record)).join("\n") + "\n",
+ );
+ await tracker.refresh();
+ const event = {
+ type: "item.completed",
+ item: {
+ type: "command_execution",
+ command: "inspect-source",
+ aggregated_output: commandOutput(marker("discovery")),
+ },
+ };
+ expect(
+ tracker.recordParentProgress(
+ { phase: "discovery", filesCompleted: 8, filesTotal: 8 },
+ event,
+ ),
+ ).toBe(false);
+ await tracker.stop();
+ expect(updates.map((update) => update.phase)).toEqual(
+ overlap ? ["discovery", "validation", "discovery"] : ["validation"],
+ );
},
);
- test.each([...parentFields])(
- "ignores replayed parent history in %s worker sessions",
- async (parentField) => {
- const home = await codexHome();
- const inherited = {
- input_tokens: 1_000,
- cached_input_tokens: 500,
- cache_write_input_tokens: 100,
- output_tokens: 100,
- reasoning_output_tokens: 20,
- };
- await writeSession(home, "scan-thread", inherited);
- const worker = await writeSession(home, "worker-thread", inherited);
- const command =
- 'rg "password" "$CODEX_SECURITY_REPOSITORY/routes/login.ts"';
-
- await writeFile(
- worker,
- jsonLines([
- {
- type: "session_meta",
- payload: {
- id: "worker-thread",
- timestamp: "2026-07-26T12:02:00.250Z",
- ...parentMetadata("scan-thread", parentField),
- },
- },
- {
- type: "session_meta",
- payload: {
- id: "scan-thread",
- timestamp: "2026-07-26T12:00:00.000Z",
- source: "exec",
- },
- },
- {
- type: "event_msg",
- payload: { type: "task_started", started_at: 1_785_067_200 },
- },
+ test.each([false, true])(
+ "keeps recovered response progress ahead of an older live command (multipart: %p)",
+ async (multipart) => {
+ const { home, parent } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 9,
+ onProgress: (update) => updates.push(update),
+ });
+ const progress = {
+ phase: "attack_path",
+ filesCompleted: 3,
+ filesTotal: 9,
+ } as const;
+ const text = "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(progress);
+ const parts = multipart ? ["Report: ", text] : [text];
+ // Paginated mode persists the concatenated message before the original
+ // parts. Only the original response exposes the multipart marker here.
+ await appendFile(
+ parent,
+ [
+ nativeCommand("older-review", persistedCommandOutput),
{
type: "event_msg",
payload: {
- type: "agent_message",
- message: "Inherited parent commentary.",
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [{ type: "Text", text: parts.join("") }],
+ },
},
},
{
type: "response_item",
payload: {
- type: "function_call",
- name: "exec_command",
- call_id: "inherited-search",
- arguments: JSON.stringify({ cmd: command }),
- },
- },
- { type: "response_item", payload: progressMessage(7) },
- {
- type: "event_msg",
- payload: {
- type: "token_count",
- info: { total_token_usage: inherited },
+ type: "message",
+ role: "assistant",
+ content: parts.map((text) => ({ type: "output_text", text })),
},
},
- {
- type: "event_msg",
- payload: { type: "task_started", started_at: 1_785_067_320 },
- },
- {
- type: "event_msg",
- timestamp: "2026-07-26T12:02:01.000Z",
- payload: {
- type: "agent_message",
- message: "Reviewing the login query.",
+ ]
+ .map((row) => JSON.stringify(row))
+ .join("\n") + "\n",
+ );
+ tracker.start("scan-thread");
+ try {
+ await tracker.refresh();
+ expect(updates).toEqual([progress]);
+ const older = { ...progress, phase: "validation" } as const;
+ expect(
+ tracker.recordParentProgress(older, {
+ type: "item.completed",
+ item: {
+ type: "command_execution",
+ command: "older-review",
+ aggregated_output: commandOutput(
+ "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(older),
+ ),
},
+ }),
+ ).toBe(false);
+ tracker.recordParentItem({
+ type: "item.completed",
+ item: {
+ type: "agent_message",
+ text: parts.join(""),
},
- {
- type: "response_item",
- payload: {
- type: "function_call",
- name: "exec_command",
- call_id: "worker-search",
- arguments: JSON.stringify({ cmd: command }),
+ });
+ await tracker.refresh();
+ expect(updates).toEqual([progress]);
+ } finally {
+ await tracker.stop();
+ }
+ },
+ );
+
+ test("admits a newer recovered response that repeats an earlier live phase", async () => {
+ const { home, parent } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 9,
+ onProgress: (update) => updates.push(update),
+ });
+ const first = {
+ phase: "discovery",
+ filesCompleted: 3,
+ filesTotal: 9,
+ } as const;
+ const second = { ...first, phase: "validation" } as const;
+ const marker = (progress: ScanProgress) =>
+ "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(progress);
+ // Every native completion and its original multipart response is durable
+ // before SDK delivery. Reusing a tuple is not reusing a message occurrence.
+ await appendFile(
+ parent,
+ [
+ ...[first, second].map((progress, index) =>
+ nativeCommand(`review-${index}`, marker(progress)),
+ ),
+ {
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [{ type: "Text", text: "Report: " + marker(first) }],
},
},
- {
- type: "response_item",
- payload: {
- type: "function_call_output",
- call_id: "worker-search",
- output:
- "Batch reviewed.\n" +
- 'CODEX_SECURITY_SCAN_PROGRESS {"phase":"discovery","filesCompleted":3,"filesTotal":8}',
- },
+ },
+ {
+ type: "response_item",
+ payload: {
+ type: "message",
+ role: "assistant",
+ content: ["Report: ", marker(first)].map((text) => ({
+ type: "output_text",
+ text,
+ })),
},
- {
- type: "event_msg",
- payload: {
- type: "token_count",
- info: {
- total_token_usage: {
- input_tokens: 1_300,
- cached_input_tokens: 650,
- cache_write_input_tokens: 150,
- output_tokens: 130,
- reasoning_output_tokens: 30,
- },
- },
- },
+ },
+ ]
+ .map((row) => JSON.stringify(row))
+ .join("\n") + "\n",
+ );
+ tracker.start("scan-thread");
+ try {
+ for (const [index, progress] of [first, second].entries()) {
+ const event = {
+ type: "item.completed",
+ item: {
+ type: "command_execution",
+ command: `review-${index}`,
+ aggregated_output: marker(progress),
},
- ]) + "\n",
- );
+ };
+ expect(tracker.recordParentProgress(progress, event)).toBe(true);
+ tracker.acceptParentProgress(progress, event);
+ }
+ await tracker.refresh();
+ expect(updates).toEqual([first]);
+ tracker.recordParentItem({
+ type: "item.completed",
+ item: {
+ type: "agent_message",
+ text: "Report: " + marker(first),
+ },
+ });
+ await tracker.refresh();
+ expect(updates).toEqual([first]);
+ } finally {
+ await tracker.stop();
+ }
+ });
- const activities: ScanActivity[] = [];
- const progress: ScanProgress[] = [];
- const events: ScanSessionEvent[] = [];
- const workers: ScanWorkerEvent[] = [];
- const tracker = new ScanCostTracker({
- codexHome: home,
- model: "gpt-5.6-terra",
- repository: "/code/juice-shop",
- expectedFilesTotal: 8,
- onActivity: (activity) => activities.push(activity),
- onProgress: (update) => progress.push(update),
- onSessionEvent: (event) => events.push(event),
- onWorkerEvent: (event) => workers.push(event),
+ test.each([
+ [false, "discovery", "validation"],
+ [true, "discovery", "validation"],
+ [false, "validation", "discovery"],
+ [true, "validation", "discovery"],
+ ] as const)(
+ "keeps parent phase when repeated receipts meet tied worker coverage (%p, %s, %s)",
+ async (repeat, parentPhase, workerPhase) => {
+ const { home, parent, worker } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 9,
+ onProgress: (update) => updates.push(update),
});
+ const inventory = {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 10,
+ } as const;
+ const parentProgress = {
+ phase: parentPhase,
+ filesCompleted: 9,
+ filesTotal: 9,
+ };
+ const marker = (progress: ScanProgress) =>
+ "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(progress);
+ await appendFile(
+ parent,
+ JSON.stringify(nativeCommand("inventory", persistedCommandOutput)) +
+ "\n",
+ );
tracker.start("scan-thread");
+ try {
+ await appendSessionItem(parent, {
+ type: "custom_tool_call_output",
+ call_id: "first",
+ output: marker(parentProgress),
+ });
+ await tracker.refresh();
+ await appendSessionItem(worker, {
+ type: "custom_tool_call_output",
+ output: marker({
+ phase: workerPhase,
+ filesCompleted: 9,
+ filesTotal: 10,
+ }),
+ });
+ await tracker.refresh();
+ if (repeat) {
+ await appendSessionItem(parent, {
+ type: "custom_tool_call_output",
+ call_id: "repeat",
+ output: marker(parentProgress),
+ });
+ await tracker.refresh();
+ }
+ // A repeated receipt updates ownership/order without duplicate callbacks.
+ expect(updates).toEqual([parentProgress]);
+ tracker.recordParentProgress(inventory, {
+ type: "item.completed",
+ item: {
+ type: "command_execution",
+ command: "inventory",
+ aggregated_output: commandOutput(marker(inventory)),
+ },
+ });
+ await tracker.refresh();
+ await tracker.refresh();
+ expect(updates.at(-1)).toEqual({
+ phase: parentPhase,
+ filesCompleted: 9,
+ filesTotal: 10,
+ });
+ expect(updates).toHaveLength(2);
+ } finally {
+ await tracker.stop();
+ }
+ },
+ );
- expect(await tracker.stop()).toMatchObject({
- usage: {
- input_tokens: 1_300,
- cached_input_tokens: 650,
- cache_write_input_tokens: 150,
- output_tokens: 130,
- reasoning_output_tokens: 30,
- total_tokens: 1_430,
- },
- cost: {
- model: "gpt-5.6-terra",
- inputTokens: 1_300,
- cachedInputTokens: 650,
- cacheWriteInputTokens: 150,
- outputTokens: 130,
- estimatedUsd: 0.003065,
- },
- });
- expect(workers).toEqual([{ kind: "observed", worker: 1 }]);
- expect(activities).toEqual([
- expect.objectContaining({
- kind: "message",
- description: "Reviewing the login query.",
- worker: 1,
- }),
- expect.objectContaining({
- id: "worker-thread:worker-search",
- kind: "command",
- status: "running",
- worker: 1,
- }),
- expect.objectContaining({
- id: "worker-thread:worker-search",
- kind: "command",
- status: "completed",
- worker: 1,
- }),
- ]);
- expect(progress).toEqual([
- { phase: "discovery", filesCompleted: 3, filesTotal: 8 },
- ]);
- const workerEvents = events.filter(
- ({ threadId }) => threadId === "worker-thread",
+ test.each([
+ ["legacy", false],
+ ["legacy", true],
+ ["paginated", false],
+ ["paginated", true],
+ ] as const)(
+ "recovers multipart progress from the original response (%s, worker: %p)",
+ async (mode, workerMessage) => {
+ const { home, parent, worker } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => updates.push(update),
+ });
+ const expected: ScanProgress[] = [
+ { phase: "discovery", filesCompleted: 1, filesTotal: 8 },
+ { phase: "validation", filesCompleted: 2, filesTotal: 8 },
+ ];
+ const parts = expected.map(
+ (update) => "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(update),
);
- expect(workerEvents).toHaveLength(6);
- expect(JSON.stringify(workerEvents)).not.toContain(
- "Inherited parent commentary.",
+ // Codex finalizes one concatenated message before storing the original
+ // response parts. Legacy and paginated rollouts keep different projections.
+ const finalized = parts.join("");
+ const projection =
+ mode === "legacy"
+ ? {
+ type: "event_msg",
+ payload: { type: "agent_message", message: finalized },
+ }
+ : {
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [{ type: "Text", text: finalized }],
+ },
+ },
+ };
+ await appendFile(
+ workerMessage ? worker : parent,
+ [
+ projection,
+ {
+ type: "response_item",
+ payload: {
+ type: "message",
+ role: "assistant",
+ content: parts.map((text) => ({ type: "output_text", text })),
+ },
+ },
+ ]
+ .map((row) => JSON.stringify(row))
+ .join("\n") + "\n",
);
+ tracker.start("scan-thread");
+ await tracker.refresh();
+ await tracker.stop();
+ expect(updates).toEqual(expected);
+ },
+ );
+
+ test.each([false, true])(
+ "preserves distinct notifications sharing a call ID (worker: %p)",
+ async (workerOutput) => {
+ const { home, parent, worker } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => updates.push(update),
+ });
+ tracker.start("scan-thread");
+ await tracker.refresh();
+ const values: ScanProgress[] = [
+ { phase: "discovery", filesCompleted: 1, filesTotal: 8 },
+ { phase: "discovery", filesCompleted: 4, filesTotal: 8 },
+ { phase: "validation", filesCompleted: 8, filesTotal: 8 },
+ ];
+ if (!workerOutput)
+ values.push({ ...values[2]!, phase: "discovery" }, values[2]!);
+ for (const progress of values) {
+ await appendSessionItem(workerOutput ? worker : parent, {
+ type: "custom_tool_call_output",
+ call_id: "notify-call",
+ output: "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(progress),
+ });
+ await tracker.refresh();
+ }
+ await tracker.stop();
+ expect(updates).toEqual(values);
},
);
test.each([
+ ["function_call_output", "text", "completed"],
+ ["custom_tool_call_output", "text", "completed"],
+ ["local_shell_call_output", "text", "completed"],
+ ["local_shell_call_output", "parts", "completed"],
+ ["local_shell_call_output", "text", "failed"],
+ ["message", "text", "completed"],
+ ] as const)(
+ "keeps distinct saved progress receipts after live output (%s, %s, %s)",
+ async (type, shape, status) => {
+ const { home, parent } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => updates.push(update),
+ });
+ const discovery: ScanProgress = {
+ phase: "discovery",
+ filesCompleted: 8,
+ filesTotal: 8,
+ };
+ const marker = (phase: ScanProgress["phase"]) =>
+ "CODEX_SECURITY_SCAN_PROGRESS " +
+ JSON.stringify({ ...discovery, phase });
+ tracker.start("scan-thread");
+ try {
+ await tracker.stop();
+ tracker.beginParentTurn(true);
+ const event = completedCommand("inspect-source", marker("discovery"));
+ expect(tracker.recordParentProgress(discovery, event)).toBe(true);
+ tracker.acceptParentProgress(discovery, event);
+ updates.push(discovery);
+ await appendSessionItem(parent, {
+ type: "function_call_output",
+ call_id: "intervening-validation",
+ output: marker("validation"),
+ });
+ await tracker.refresh();
+ expect(updates.at(-1)?.phase).toBe("validation");
+ await appendSessionItem(
+ parent,
+ type === "message"
+ ? {
+ type,
+ role: "assistant",
+ content: [{ type: "output_text", text: marker("discovery") }],
+ }
+ : {
+ type,
+ call_id: "distinct-completion",
+ status,
+ output:
+ shape === "parts"
+ ? [{ type: "output_text", text: marker("discovery") }]
+ : marker("discovery"),
+ },
+ );
+ await tracker.refresh();
+ await tracker.refresh();
+ await tracker.stop();
+ expect(updates.map((update) => update.phase)).toEqual(
+ status === "failed" || type === "message"
+ ? ["discovery", "validation"]
+ : ["discovery", "validation", "discovery"],
+ );
+ } finally {
+ await tracker.stop();
+ }
+ },
+ );
+
+ const messageProjectionCases = [
[
- "keeps an earlier-millisecond UUIDv7 turn in inherited history",
- ["019f9e4d-b3b9-7000-8000-000000000001"],
+ "missing native copy",
+ [
+ ["native", "discovery"],
+ ["response", "validation"],
+ ["response", "discovery"],
+ ],
+ "discovery/validation/discovery",
],
[
- "keeps a same-millisecond lower UUIDv7 turn in inherited history",
- [lowerUuid7Turn],
+ "missing legacy copy",
+ [
+ ["event", "discovery"],
+ ["response", "validation"],
+ ["response", "discovery"],
+ ],
+ "discovery/validation/discovery",
],
- ["accepts a same-millisecond higher UUIDv7 turn as child-owned", []],
- ] as const)("%s", async (_name, replayedTurnIds) => {
- const home = await codexHome();
- const rolloutPath = await writeSession(
- home,
- childUuid7Thread,
- { input_tokens: 1_100, output_tokens: 110 },
- { parent: scanThreadId },
- );
- const rollout = ownershipRollout(replayedTurnIds);
- await writeFile(rolloutPath, jsonLines(rollout) + "\n");
-
- const maxCostUsd = 0.001;
- const observedCosts: number[] = [];
- const forwardedEvents: ScanSessionEvent[] = [];
- const tracker = costTracker(home, {
- maxCostUsd,
- onCost: ({ estimatedUsd }) => observedCosts.push(estimatedUsd),
- onSessionEvent: (event) => forwardedEvents.push(event),
- });
- tracker.start(scanThreadId);
- const tracked = await tracker.stop();
- const python = readPythonRolloutUsage(BUNDLED_PLUGIN_ROOT, rolloutPath);
-
- expect({
- trackedUsage: tracked.usage,
- estimatedUsd: tracked.cost?.estimatedUsd,
- python,
- }).toMatchObject({
- trackedUsage: ownedSdkUsage,
- estimatedUsd: 0.0006,
- python: {
- usage: ownedPythonUsage,
- warnings: [],
- },
- });
- expect(observedCosts.length).toBeGreaterThan(0);
- expect(observedCosts.every((cost) => cost < maxCostUsd)).toBe(true);
- const forwardedTurnIds = forwardedEvents.flatMap(({ event }) => {
- const payload = event["payload"];
- return typeof payload === "object" &&
- payload !== null &&
- (payload as Record<string, unknown>)["type"] === "task_started"
- ? [(payload as Record<string, unknown>)["turn_id"]]
- : [];
- });
- expect(forwardedTurnIds).toEqual([higherUuid7Turn]);
- const saved = await readScanLogs({
- scanId: "scan-example",
- threadId: childUuid7Thread,
- codexHome: home,
- });
- const ownedEvents = [rollout[0]!, ...rollout.slice(-3)];
- expect(forwardedEvents.map(({ event }) => event)).toEqual(ownedEvents);
- expect(saved.events.map(({ event }) => event)).toEqual(ownedEvents);
- });
-
- test("forwards actions from this scan's delegated workers only", async () => {
- const {
- home,
- usage,
- parent: parentPath,
- worker: workerPath,
- } = await workerSessionFixture();
- const unrelatedPath = await writeSession(home, "unrelated-thread", usage);
- const command =
- 'rg -n "password" "$CODEX_SECURITY_REPOSITORY/routes/login.ts"';
-
- for (const [path, callId] of [
- [parentPath, "parent-command"],
- [workerPath, "worker-command"],
- [unrelatedPath, "unrelated-command"],
- ] as const) {
- await appendSessionItem(path, {
- type: "function_call",
- name: "exec_command",
- call_id: callId,
- arguments: JSON.stringify({ cmd: command }),
- });
- await appendSessionItem(path, {
- type: "function_call_output",
- call_id: callId,
+ [
+ "missing response copy",
+ [
+ ["response", "discovery"],
+ ["native", "validation"],
+ ["native", "discovery"],
+ ],
+ "discovery/validation/discovery",
+ ],
+ [
+ "same projection",
+ [
+ ["response", "discovery"],
+ ["response", "validation"],
+ ["response", "discovery"],
+ ],
+ "discovery/validation/discovery",
+ ],
+ [
+ "adjacent copies",
+ [
+ ["native", "discovery"],
+ ["event", "discovery"],
+ ["response", "discovery"],
+ ["native", "validation"],
+ ["event", "validation"],
+ ["response", "validation"],
+ ],
+ "discovery/validation",
+ ],
+ [
+ "delayed copies",
+ [
+ ["native", "discovery"],
+ ["native", "validation"],
+ ["response", "discovery"],
+ ["response", "validation"],
+ ],
+ "discovery/validation",
+ ],
+ [
+ "repeated delayed copies",
+ [
+ ["native", "discovery"],
+ ["native", "validation"],
+ ["native", "discovery"],
+ ["response", "discovery"],
+ ["response", "validation"],
+ ["response", "discovery"],
+ ],
+ "discovery/validation/discovery",
+ ],
+ [
+ "follow-on native counterpart",
+ [
+ ["native", "discovery/validation"],
+ ["response", "attack_path"],
+ ["response", "discovery/validation"],
+ ["native", "discovery/validation"],
+ ],
+ "discovery/validation/attack_path/discovery/validation",
+ ],
+ ] as const;
+
+ test.each(
+ messageProjectionCases.flatMap(([name, rows, expected]) =>
+ [false, true].map((staged) => [name, staged, rows, expected] as const),
+ ),
+ )(
+ "preserves message progress with %s (staged: %p)",
+ async (name, staged, rows, expected) => {
+ const { home, parent } = await workerSessionFixture();
+ const phases: string[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => phases.push(update.phase),
});
- }
-
- const activities: ScanActivity[] = [];
- const events: ScanSessionEvent[] = [];
- const tracker = costTracker(home, {
- repository: "/code/juice-shop",
- onActivity: (activity) => activities.push(activity),
- onSessionEvent: (event) => events.push(event),
- });
- tracker.start("scan-thread");
- await tracker.stop();
-
- expect(activities).toEqual([
- {
- id: "worker-thread:worker-command",
- kind: "command",
- status: "running",
- description: command,
- paths: ["routes/login.ts"],
- worker: 1,
- },
- {
- id: "worker-thread:worker-command",
- kind: "command",
- status: "completed",
- description: command,
- paths: ["routes/login.ts"],
- worker: 1,
- },
- ]);
- expect(
- new Map(events.map(({ threadId, worker }) => [threadId, worker])),
- ).toEqual(
- new Map([
- ["scan-thread", undefined],
- ["worker-thread", 1],
- ]),
- );
- });
-
- test("forwards genuine worker reasoning and transcript text", async () => {
- const { home, worker: path } = await workerSessionFixture();
- await appendSessionItem(path, {
- id: "thinking-1",
- type: "reasoning",
- summary: [{ type: "summary_text", text: "Following the login query." }],
- encrypted_content: "do-not-display",
- });
- await appendSessionItem(path, {
- id: "message-1",
- type: "message",
- role: "assistant",
- content: [{ type: "output_text", text: "The query uses request input." }],
- });
-
- const { activities, tracker } = activityTracker(home);
- tracker.start("scan-thread");
- await tracker.stop();
-
- expect(activities).toEqual([
- {
- id: "worker-thread:thinking-1",
- kind: "reasoning",
- status: "completed",
- description: "Following the login query.",
- paths: [],
- worker: 1,
- },
- {
- id: "worker-thread:message-1",
- kind: "message",
- status: "completed",
- description: "The query uses request input.",
- paths: [],
- worker: 1,
- },
- ]);
- });
+ tracker.start("scan-thread");
+ try {
+ await tracker.stop();
+ tracker.beginParentTurn(true);
+ for (const [index, [projection, sourcePhases]] of rows.entries()) {
+ const text = sourcePhases
+ .split("/")
+ .map(
+ (phase) =>
+ "CODEX_SECURITY_SCAN_PROGRESS " +
+ JSON.stringify({
+ phase,
+ filesCompleted: 8,
+ filesTotal: 8,
+ }),
+ )
+ .join("\n");
+ const record =
+ projection === "native"
+ ? {
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [{ type: "Text", text }],
+ },
+ },
+ }
+ : projection === "event"
+ ? {
+ type: "event_msg",
+ payload: { type: "agent_message", message: text },
+ }
+ : {
+ type: "response_item",
+ payload: {
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text }],
+ },
+ };
+ await appendFile(parent, JSON.stringify(record) + "\n");
+ if (staged) {
+ await tracker.refresh();
+ // The response must advance immediately; its later native copy
+ // must not compensate for an incorrectly suppressed response.
+ if (name === "follow-on native counterpart" && index >= 2)
+ expect(phases).toEqual(expected.split("/"));
+ }
+ }
+ await tracker.refresh();
+ await tracker.refresh();
+ await tracker.stop();
+ expect(phases).toEqual(expected.split("/"));
+ } finally {
+ await tracker.stop();
+ }
+ },
+ );
- test("streams worker reasoning and commentary from live session events once", async () => {
- const { home, worker } = await workerSessionFixture();
- await appendFile(
- worker,
- [
- JSON.stringify({
+ test.each([false, true])(
+ "rebases message projections after legacy history (history: %p)",
+ async (history) => {
+ const { home, parent } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => {
+ if (JSON.stringify(updates.at(-1)) !== JSON.stringify(update))
+ updates.push(update);
+ },
+ });
+ const progress = (phase: "discovery" | "validation") => ({
+ phase,
+ filesCompleted: 8,
+ filesTotal: 8,
+ });
+ const marker = (phase: "discovery" | "validation") =>
+ "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(progress(phase));
+ const projections = (phase: "discovery" | "validation") => [
+ {
type: "event_msg",
- timestamp: "2026-07-26T12:00:00.000Z",
- payload: {
- type: "agent_reasoning",
- text: "Tracing the login query.",
- },
- }),
- JSON.stringify({
- type: "response_item",
payload: {
- id: "reasoning-1",
- type: "reasoning",
- summary: [
- { type: "summary_text", text: "Tracing the login query." },
- ],
- encrypted_content: "must-never-be-displayed",
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [{ type: "Text", text: marker(phase) }],
+ },
},
- }),
- JSON.stringify({
+ },
+ {
type: "event_msg",
- timestamp: "2026-07-26T12:00:01.000Z",
- payload: {
- type: "agent_message",
- message:
- "Reviewed the login query.\n" +
- 'CODEX_SECURITY_SCAN_PROGRESS {"phase":"discovery","filesCompleted":3,"filesTotal":8}',
- },
- }),
- JSON.stringify({
+ payload: { type: "agent_message", message: marker(phase) },
+ },
+ {
type: "response_item",
payload: {
- id: "message-1",
type: "message",
role: "assistant",
- content: [
- { type: "output_text", text: "Reviewed the login query." },
- ],
+ content: [{ type: "output_text", text: marker(phase) }],
},
- }),
- "",
- ].join("\n"),
- );
+ },
+ ];
+ const append = async (rows: unknown[]) =>
+ appendFile(
+ parent,
+ rows.map((row) => JSON.stringify(row)).join("\n") + "\n",
+ );
+ if (history) await append(projections("discovery").slice(1));
+ tracker.start("scan-thread");
+ await tracker.refresh();
+ tracker.beginParentTurn(true);
+ const stream = (phase: "discovery" | "validation") => {
+ const update = progress(phase);
+ const event = {
+ type: "item.completed",
+ item: { type: "agent_message", text: marker(phase) },
+ };
+ if (tracker.recordParentProgress(update, event)) {
+ tracker.acceptParentProgress(update, event);
+ if (JSON.stringify(updates.at(-1)) !== JSON.stringify(update))
+ updates.push(update);
+ }
+ };
+ stream("discovery");
+ stream("validation");
+ await append([...projections("discovery"), ...projections("validation")]);
+ await tracker.refresh();
+ await append(projections("discovery"));
+ await tracker.refresh();
+ stream("discovery");
+ await tracker.stop();
+ expect(updates.map((update) => update.phase)).toEqual([
+ "discovery",
+ "validation",
+ "discovery",
+ ]);
+ },
+ );
- const activities: ScanActivity[] = [];
+ test("deduplicates legacy parent message projections by occurrence", async () => {
+ const { home, parent } = await workerSessionFixture();
const updates: ScanProgress[] = [];
const tracker = costTracker(home, {
- repository: "/code/juice-shop",
expectedFilesTotal: 8,
- onActivity: (activity) => activities.push(activity),
- onProgress: (progress) => updates.push(progress),
+ onProgress: (update) => updates.push(update),
});
tracker.start("scan-thread");
+ await tracker.refresh();
+ const text = ["discovery", "validation"]
+ .map(
+ (phase) =>
+ "CODEX_SECURITY_SCAN_PROGRESS " +
+ JSON.stringify({ phase, filesCompleted: 8, filesTotal: 8 }),
+ )
+ .join("\n");
+ for (let occurrence = 0; occurrence < 2; occurrence++) {
+ await appendFile(
+ parent,
+ JSON.stringify({
+ type: "event_msg",
+ payload: { type: "agent_message", message: text },
+ }) + "\n",
+ );
+ await tracker.refresh();
+ await appendFile(
+ parent,
+ JSON.stringify({
+ type: "response_item",
+ payload: {
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text }],
+ },
+ }) + "\n",
+ );
+ await tracker.refresh();
+ }
await tracker.stop();
-
- expect(activities).toEqual([
- expect.objectContaining({
- kind: "reasoning",
- description: "Tracing the login query.",
- worker: 1,
- }),
- expect.objectContaining({
- kind: "message",
- description: "Reviewed the login query.",
- worker: 1,
- }),
- ]);
- expect(updates).toEqual([
- { phase: "discovery", filesCompleted: 3, filesTotal: 8 },
+ expect(updates.map((update) => update.phase)).toEqual([
+ "discovery",
+ "validation",
+ "discovery",
+ "validation",
]);
});
- test("expands streamed worker reasoning without duplicating summaries or exposing encrypted content", async () => {
- const { home, worker } = await workerSessionFixture();
- const details = `${"The query reaches a privileged tenant boundary. ".repeat(30)}Final authorization check.`;
- const raw = `**The route builds SQL from request parameters.** ${details}`;
- await appendFile(
- worker,
- [
- {
- type: "event_msg",
- payload: {
- type: "agent_reasoning_delta",
- delta: "Checking whether ",
- },
- },
- {
- type: "event_msg",
- payload: {
- type: "agent_reasoning_delta",
- delta: "the login query escapes user input.",
- },
- },
- {
- type: "event_msg",
- payload: {
- type: "agent_reasoning",
- text: "Checking whether the login query escapes user input.",
- },
- },
- {
- type: "event_msg",
- payload: {
- type: "agent_reasoning_raw_content_delta",
- delta: "The route builds SQL ",
- },
- },
- {
- type: "event_msg",
- payload: {
- type: "agent_reasoning_raw_content_delta",
- delta: "from request parameters.",
- },
- },
- {
- type: "event_msg",
- payload: {
- type: "agent_reasoning_raw_content",
- text: raw,
+ test.each([
+ ["saved", false, "validation", "discovery"],
+ ["saved", true, "validation", "discovery"],
+ ["saved", false, "discovery", "attack_path"],
+ ["saved", true, "discovery", "attack_path"],
+ ["live", false, "validation", "discovery"],
+ ["live", true, "validation", "discovery"],
+ ["live", false, "discovery", "attack_path"],
+ ["live", true, "discovery", "attack_path"],
+ ] as const)(
+ "keeps the global parent phase at equal worker coverage (%s, worker first: %p, parent: %s, worker: %s)",
+ async (source, workerFirst, parentPhase, workerPhase) => {
+ const { home, usage, parent, worker } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 9,
+ onProgress: (update) => updates.push(update),
+ });
+ const originalReaddir = filesystem.readdir;
+ const listing = spyOn(filesystem, "readdir").mockImplementation((async (
+ ...args: Parameters<typeof originalReaddir>
+ ) => {
+ const entries = await originalReaddir(...args);
+ if (String(args[0]) === dirname(parent)) {
+ const first = basename(workerFirst ? worker : parent);
+ return entries.toSorted(
+ (left, right) =>
+ Number(String(right.name) === first) -
+ Number(String(left.name) === first),
+ );
+ }
+ return entries;
+ }) as typeof originalReaddir);
+ try {
+ if (source === "saved") {
+ await appendSessionItem(parent, progressMessage(8, 9, parentPhase));
+ await appendSessionItem(worker, progressMessage(8, 8, workerPhase));
+ tracker.start("scan-thread");
+ await tracker.refresh();
+ } else {
+ tracker.start("scan-thread");
+ await tracker.refresh();
+ tracker.beginParentTurn();
+ if (workerFirst) {
+ await appendSessionItem(worker, progressMessage(8, 8, workerPhase));
+ await tracker.refresh();
+ }
+ const progress = {
+ phase: parentPhase,
+ filesCompleted: 8,
+ filesTotal: 9,
+ };
+ const event = {
+ type: "item.completed",
+ item: {
+ type: "agent_message",
+ text: "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(progress),
+ },
+ };
+ expect(tracker.recordParentProgress(progress, event)).toBe(true);
+ tracker.acceptParentProgress(progress, event);
+ updates.push(progress);
+ if (!workerFirst) {
+ await appendSessionItem(worker, progressMessage(8, 8, workerPhase));
+ await tracker.refresh();
+ }
+ }
+ expect(updates.at(-1)).toEqual({
+ phase: parentPhase,
+ filesCompleted: 8,
+ filesTotal: 9,
+ });
+ expect(updates.map((update) => update.phase)).toEqual(
+ workerFirst ? [workerPhase, parentPhase] : [parentPhase],
+ );
+
+ // A later global parent update remains authoritative at the same count.
+ await appendSessionItem(parent, progressMessage(8, 9, "reporting"));
+ await tracker.refresh();
+ expect(updates.at(-1)).toEqual({
+ phase: "reporting",
+ filesCompleted: 8,
+ filesTotal: 9,
+ });
+
+ // Keep each worker's coverage even when its phase did not reach the UI.
+ const additional = await writeSession(
+ home,
+ "additional-worker",
+ usage,
+ {
+ parent: "scan-thread",
},
- },
- {
- type: "event_msg",
- payload: {
- type: "agent_reasoning",
- text: "This summary must not replace public raw reasoning.",
+ );
+ await appendSessionItem(additional, progressMessage(1, 1, "discovery"));
+ await tracker.refresh();
+ expect(updates.at(-1)).toEqual({
+ phase: "discovery",
+ filesCompleted: 9,
+ filesTotal: 9,
+ });
+ await appendSessionItem(parent, progressMessage(9, 9, "validation"));
+ await tracker.stop();
+ expect(updates.at(-1)).toEqual({
+ phase: "validation",
+ filesCompleted: 9,
+ filesTotal: 9,
+ });
+ } finally {
+ await tracker.stop();
+ listing.mockRestore();
+ }
+ },
+ );
+
+ test.each([
+ [8, "validation", "discovery"],
+ [9, "validation", "discovery"],
+ [8, "discovery", "attack_path"],
+ [9, "discovery", "attack_path"],
+ ] as const)(
+ "keeps the global parent phase when inventory admits equal worker coverage (%p, parent: %s, worker: %s)",
+ async (workerCount, parentPhase, workerPhase) => {
+ const { home, parent, worker } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 9,
+ onProgress: (update) => updates.push(update),
+ });
+ try {
+ await appendSessionItem(parent, progressMessage(8, 9, parentPhase));
+ tracker.start("scan-thread");
+ await tracker.refresh();
+ await appendSessionItem(
+ worker,
+ progressMessage(workerCount, 10, workerPhase),
+ );
+ await tracker.refresh();
+ expect(updates.at(-1)).toEqual({
+ phase: parentPhase,
+ filesCompleted: 8,
+ filesTotal: 9,
+ });
+ tracker.setExpectedFilesTotal(10);
+ await tracker.refresh();
+ expect(updates.at(-1)).toEqual({
+ phase: workerCount === 8 ? parentPhase : workerPhase,
+ filesCompleted: workerCount,
+ filesTotal: 10,
+ });
+ } finally {
+ await tracker.stop();
+ }
+ },
+ );
+
+ test.each([
+ [false, 7, false, "validation", "attack_path"],
+ [true, 7, false, "validation", "attack_path"],
+ [false, 8, false, "validation", "attack_path"],
+ [true, 8, false, "validation", "attack_path"],
+ [false, 7, true, "attack_path", "discovery"],
+ [true, 7, true, "attack_path", "discovery"],
+ [false, 8, true, "attack_path", "discovery"],
+ [true, 8, true, "attack_path", "discovery"],
+ ] as const)(
+ "uses only an eligible parent phase after inventory correction (live first: %p, parent total: %p, worker after: %p, parent: %s, worker: %s)",
+ async (liveFirst, parentTotal, workerAfter, parentPhase, workerPhase) => {
+ const { home, parent, worker } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => updates.push(update),
+ });
+ const inventory = {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 7,
+ } as const;
+ const text = `CODEX_SECURITY_SCAN_PROGRESS ${JSON.stringify(inventory)}`;
+ const deliverInventory = () => {
+ const event = {
+ type: "item.completed",
+ item: {
+ type: "command_execution",
+ command: "inventory",
+ aggregated_output: commandOutput(text),
},
- },
- {
- type: "response_item",
- payload: {
- id: "reasoning-1",
- type: "reasoning",
- summary: [
- {
- type: "summary_text",
- text: "Checking whether the login query escapes user input.",
+ };
+ const current = tracker.recordParentProgress(inventory, event);
+ if (liveFirst && current) {
+ tracker.acceptParentProgress(inventory, event);
+ tracker.setExpectedFilesTotal(inventory.filesTotal);
+ updates.push(inventory);
+ }
+ };
+ try {
+ tracker.start("scan-thread");
+ await tracker.refresh();
+ tracker.beginParentTurn();
+ await appendFile(
+ parent,
+ JSON.stringify(nativeCommand("inventory", persistedCommandOutput)) +
+ "\n",
+ );
+ if (liveFirst) {
+ deliverInventory();
+ await tracker.refresh();
+ }
+ await appendFile(
+ parent,
+ JSON.stringify({
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "AgentMessage",
+ content: [
+ {
+ type: "Text",
+ text: `CODEX_SECURITY_SCAN_PROGRESS ${JSON.stringify({
+ phase: parentPhase,
+ filesCompleted: 3,
+ filesTotal: parentTotal,
+ })}`,
+ },
+ ],
},
- { type: "summary_text", text: "Preparing SQL validation." },
- ],
- encrypted_content: "never-display-encrypted-reasoning",
+ },
+ }) + "\n",
+ );
+ await tracker.refresh();
+ if (!workerAfter) {
+ await appendSessionItem(
+ worker,
+ progressMessage(3, 3, "threat_model"),
+ );
+ await tracker.refresh();
+ }
+ // The same inventory was persisted before parent review in both cases.
+ // Its delayed live copy proves scope without resetting reviewed coverage.
+ if (!liveFirst) {
+ deliverInventory();
+ await tracker.refresh();
+ }
+ await appendSessionItem(worker, progressMessage(3, 3, workerPhase));
+ await tracker.stop();
+ expect(updates.at(-1)).toEqual({
+ phase: parentTotal === 7 ? parentPhase : workerPhase,
+ filesCompleted: 3,
+ filesTotal: 7,
+ });
+ } finally {
+ await tracker.stop();
+ }
+ },
+ );
+
+ test.each([
+ ["discovery", "validation", "attack_path"],
+ ["attack_path", "discovery", "validation"],
+ ] as const)(
+ "keeps greater newly admitted worker coverage ahead of retained phases (%s, %s, %s)",
+ async (parentPhase, pendingPhase, acceptedPhase) => {
+ const { home, parent, worker, usage } = await workerSessionFixture();
+ const accepted = await writeSession(home, "accepted-worker", usage, {
+ parent: "scan-thread",
+ });
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => updates.push(update),
+ });
+
+ tracker.start("scan-thread");
+ try {
+ await tracker.refresh();
+ tracker.beginParentTurn();
+ await appendFile(
+ parent,
+ JSON.stringify(nativeCommand("inventory", persistedCommandOutput)) +
+ "\n",
+ );
+ await appendSessionItem(parent, {
+ type: "custom_tool_call_output",
+ output: progressMarker(parentPhase, 4, 8),
+ });
+ await tracker.refresh();
+ await appendSessionItem(worker, {
+ type: "custom_tool_call_output",
+ output: progressMarker(pendingPhase, 3, 9),
+ });
+ await tracker.refresh();
+ await appendSessionItem(accepted, {
+ type: "custom_tool_call_output",
+ output: progressMarker(acceptedPhase, 3, 3),
+ });
+ await tracker.refresh();
+ expect(updates).toEqual([
+ { phase: parentPhase, filesCompleted: 4, filesTotal: 8 },
+ ]);
+ tracker.recordParentProgress(
+ { phase: "discovery", filesCompleted: 0, filesTotal: 9 },
+ {
+ type: "item.completed",
+ item: {
+ type: "command_execution",
+ command: "inventory",
+ aggregated_output: commandOutput(
+ progressMarker("discovery", 0, 9),
+ ),
+ },
},
- },
- "",
- ]
- .map((event) =>
- typeof event === "string" ? event : JSON.stringify(event),
- )
- .join("\n"),
- );
+ );
+ await tracker.stop();
+ expect(updates.at(-1)).toEqual({
+ phase: pendingPhase,
+ filesCompleted: 6,
+ filesTotal: 9,
+ });
+ } finally {
+ await tracker.stop();
+ }
+ },
+ );
- const { activities, tracker } = activityTracker(home);
+ test("does not replace a global parent phase with equal worker progress", async () => {
+ const { home, parent, worker } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (update) => updates.push(update),
+ });
tracker.start("scan-thread");
+ await tracker.refresh();
+ await appendSessionItem(parent, progressMessage(8, 8, "validation"));
+ await tracker.refresh();
+ await appendSessionItem(worker, progressMessage(8, 8));
+ await tracker.refresh();
+ await appendSessionItem(parent, progressMessage(8, 8, "validation"));
await tracker.stop();
-
- expect(new Set(activities.map((activity) => activity.id))).toEqual(
- new Set(["worker-thread:reasoning-1"]),
- );
- expect(activities).toContainEqual(
- expect.objectContaining({
- kind: "reasoning",
- status: "running",
- description: "Checking whether the login query escapes user input.",
- worker: 1,
- }),
- );
- expect(activities.at(-1)).toEqual({
- id: "worker-thread:reasoning-1",
- kind: "reasoning",
- status: "completed",
- description: `The route builds SQL from request parameters. ${details}`,
- paths: [],
- worker: 1,
- });
- expect(activities.at(-1)!.description.length).toBeGreaterThan(1_000);
- expect(JSON.stringify(activities)).not.toContain("encrypted-reasoning");
+ expect(updates).toEqual([
+ { phase: "validation", filesCompleted: 8, filesTotal: 8 },
+ ]);
});
- test("keeps distinct streamed worker reasoning summaries separate", async () => {
- const { home, worker } = await workerSessionFixture();
- const summaries = [
- "**Planning discovery worker tasks**",
- "**Preparing thorough file batch reading**",
- "**Verifying repository read access and tools**",
- ];
- await appendFile(
- worker,
- [
- ...summaries.map((text) => ({
+ test.each([false, true])(
+ "keeps live inventory through a stale preview and worker update (native completion: %p)",
+ async (nativeCompletion) => {
+ const { home, parent, worker } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const report = (progress: ScanProgress) => {
+ if (progress.phase === "discovery" && progress.filesCompleted === 0)
+ tracker.setExpectedFilesTotal(progress.filesTotal);
+ updates.push(progress);
+ };
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: report,
+ });
+ tracker.start("scan-thread");
+ await tracker.refresh();
+ const first = {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 8,
+ } as const;
+ const latest = { ...first, filesTotal: 9 };
+ const marker = (value: ScanProgress) =>
+ "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(value);
+ for (const [index, progress] of [first, latest].entries()) {
+ const event = {
+ type: "item.completed",
+ item: {
+ type: "command_execution",
+ id: `item-${index}`,
+ command: `scan-progress ${index}`,
+ aggregated_output: commandOutput(marker(progress)),
+ },
+ };
+ if (tracker.recordParentProgress(progress, event)) {
+ tracker.acceptParentProgress(progress, event);
+ report(progress);
+ }
+ }
+ await appendSessionItem(parent, progressMessage(0));
+ if (nativeCompletion) {
+ // Even the full persisted completion can omit the marker. Its retained
+ // command and output identify it without waiting for the missing text.
+ await appendFile(
+ parent,
+ JSON.stringify(
+ nativeCommand(
+ ["scan-progress", "1"],
+ persistedCommandOutput,
+ "native-latest",
+ ),
+ ) + "\n",
+ );
+ }
+ await tracker.refresh();
+ expect(updates.at(-1)).toEqual(latest);
+ await appendSessionItem(worker, progressMessage(1, 1));
+ await tracker.refresh();
+ expect(updates.at(-1)).toEqual({ ...latest, filesCompleted: 1 });
+ await appendSessionItem(parent, progressMessage(2, 9));
+ await tracker.stop();
+ expect(updates.at(-1)).toEqual({ ...latest, filesCompleted: 2 });
+ expect(updates.slice(2).every((update) => update.filesTotal === 9)).toBe(
+ true,
+ );
+ },
+ );
+
+ test.each(
+ [
+ ["native"],
+ ["event"],
+ ["native", "event"],
+ ["event", "native"],
+ ["response", "native", "event"],
+ ].map((projections) => [projections] as const),
+ )(
+ "keeps command ordering through marker-free message projections (%j)",
+ async (projections) => {
+ const { home, parent } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const report = (progress: ScanProgress) => {
+ if (progress.phase === "discovery" && progress.filesCompleted === 0)
+ tracker.setExpectedFilesTotal(progress.filesTotal);
+ updates.push(progress);
+ };
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: report,
+ });
+ const text = "Continuing the scan.";
+ const native = (item: Record<string, unknown>) => ({
+ type: "event_msg",
+ payload: { type: "item_completed", item },
+ });
+ const message = native({
+ type: "AgentMessage",
+ content: [{ type: "Text", text }],
+ });
+ const copies = {
+ native: message,
+ event: {
type: "event_msg",
- payload: { type: "agent_reasoning", text },
- })),
- {
+ payload: { type: "agent_message", message: text },
+ },
+ response: {
type: "response_item",
payload: {
- id: "reasoning-1",
- type: "reasoning",
- summary: summaries.map((text) => ({ type: "summary_text", text })),
- encrypted_content: "must-never-be-displayed",
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text }],
},
},
- "",
- ]
- .map((event) =>
- typeof event === "string" ? event : JSON.stringify(event),
- )
- .join("\n"),
- );
+ };
+ tracker.start("scan-thread");
+ try {
+ await appendFile(
+ parent,
+ jsonLines(
+ projections.map((kind) => copies[kind as keyof typeof copies]),
+ ) + "\n",
+ );
+ await tracker.refresh();
+ tracker.recordParentItem({
+ type: "item.completed",
+ item: { type: "agent_message", text },
+ });
+ const inventory = {
+ phase: "discovery",
+ filesCompleted: 0,
+ filesTotal: 9,
+ } as const;
+ const marker =
+ "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(inventory);
+ const event = {
+ type: "item.completed",
+ item: {
+ type: "command_execution",
+ command: "inventory",
+ aggregated_output: commandOutput(marker),
+ },
+ };
+ expect(tracker.recordParentProgress(inventory, event)).toBe(true);
+ tracker.acceptParentProgress(inventory, event);
+ report(inventory);
+ tracker.recordParentItem({
+ type: "item.completed",
+ item: { type: "agent_message", text },
+ });
+ await appendSessionItem(parent, {
+ type: "custom_tool_call_output",
+ output:
+ 'CODEX_SECURITY_SCAN_PROGRESS {"phase":"discovery","filesCompleted":0,"filesTotal":8}',
+ });
+ // The inventory marker is absent from this persisted output. Matching its
+ // completion is the only proof that the live 9-file inventory is newer.
+ await appendFile(
+ parent,
+ jsonLines([
+ native({
+ type: "CommandExecution",
+ command: ["inventory"],
+ aggregated_output: persistedCommandOutput,
+ }),
+ message,
+ ]) + "\n",
+ );
+ await tracker.refresh();
+ await appendSessionItem(parent, progressMessage(2, 9));
+ await tracker.stop();
+ expect(updates.at(-1)).toEqual({ ...inventory, filesCompleted: 2 });
+ expect(updates.every((update) => update.filesTotal === 9)).toBe(true);
+ } finally {
+ await tracker.stop();
+ }
+ },
+ );
- const { activities, tracker } = activityTracker(home);
+ test("ignores old live phase copies without blocking new tool-only progress in legacy logs", async () => {
+ const { home, parent } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (progress) => updates.push(progress),
+ });
tracker.start("scan-thread");
+ await tracker.refresh();
+ for (const phase of ["discovery", "validation"] as const) {
+ const progress = { phase, filesCompleted: 8, filesTotal: 8 };
+ const event = {
+ type: "item.completed",
+ item: {
+ type: "agent_message",
+ text: "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(progress),
+ },
+ };
+ if (tracker.recordParentProgress(progress, event)) {
+ tracker.acceptParentProgress(progress, event);
+ updates.push(progress);
+ }
+ }
+ await appendSessionItem(parent, progressMessage(8));
+ await tracker.refresh();
+ expect(updates.at(-1)?.phase).toBe("validation");
+ await appendSessionItem(parent, progressMessage(8, 8, "attack_path"));
await tracker.stop();
-
- expect(activities).toEqual(
- summaries.map((text, index) => ({
- id: `worker-thread:reasoning-${index + 1}`,
- kind: "reasoning",
- status: "completed",
- description: text.replaceAll("**", ""),
- paths: [],
- worker: 1,
- })),
- );
+ expect(updates.map((update) => update.phase)).toEqual([
+ "discovery",
+ "validation",
+ "attack_path",
+ ]);
});
- test("splits worker reasoning summaries without streamed events", async () => {
- const { home, worker } = await workerSessionFixture();
- await appendSessionItem(worker, {
- id: "reasoning-1",
- type: "reasoning",
- summary: [
- { type: "summary_text", text: "**Planning discovery worker tasks**" },
- {
- type: "summary_text",
- text: "**Preparing thorough file batch reading**",
- },
- ],
- encrypted_content: "must-never-be-displayed",
+ test("orders repeated commands by completion and allows a later tool-only repeated phase", async () => {
+ const { home, parent } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 8,
+ onProgress: (progress) => updates.push(progress),
});
-
- const { activities, tracker } = activityTracker(home);
tracker.start("scan-thread");
- await tracker.stop();
-
- expect(activities).toEqual([
- {
- id: "worker-thread:reasoning-1:0",
- kind: "reasoning",
- status: "completed",
- description: "Planning discovery worker tasks",
- paths: [],
- worker: 1,
- },
- {
- id: "worker-thread:reasoning-1:1",
- kind: "reasoning",
- status: "completed",
- description: "Preparing thorough file batch reading",
- paths: [],
- worker: 1,
+ await tracker.refresh();
+ const discovery = {
+ phase: "discovery",
+ filesCompleted: 8,
+ filesTotal: 8,
+ } as const;
+ const validation = { ...discovery, phase: "validation" } as const;
+ const marker = (progress: ScanProgress) =>
+ "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(progress);
+ const command = `'/tool with spaces' 'a b' 'it'"'"'s' 'C:\\work'`;
+ const argv = ["/tool with spaces", "a b", "it's", "C:\\work"];
+ const live = (progress: ScanProgress) => ({
+ type: "item.completed",
+ item: {
+ type: "command_execution",
+ command,
+ aggregated_output: marker(progress),
},
+ });
+ for (const progress of [discovery, validation]) {
+ const event = live(progress);
+ if (tracker.recordParentProgress(progress, event)) {
+ tracker.acceptParentProgress(progress, event);
+ updates.push(progress);
+ }
+ }
+ // Commands can start in a different order. Only completion order carries
+ // progress ordering; the repeated command/output is not a unique identity.
+ for (const [index, progress] of [
+ discovery,
+ validation,
+ discovery,
+ ].entries()) {
+ await appendFile(
+ parent,
+ JSON.stringify({
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ started_at_ms: [20, 10, 30][index],
+ completed_at_ms: 40 + index,
+ item: {
+ type: "CommandExecution",
+ id: `native-${index}`,
+ command: argv,
+ aggregated_output: marker(progress),
+ },
+ },
+ }) + "\n",
+ );
+ }
+ await tracker.refresh();
+ expect(updates.at(-1)).toEqual(discovery);
+ await appendSessionItem(parent, {
+ type: "custom_tool_call",
+ call_id: "later-tool",
+ input: "emit a progress receipt",
+ });
+ await appendSessionItem(parent, {
+ type: "custom_tool_call_output",
+ call_id: "later-tool",
+ output: marker(validation),
+ });
+ await tracker.stop();
+ expect(updates.map((update) => update.phase)).toEqual([
+ "discovery",
+ "validation",
+ "discovery",
+ "validation",
]);
- expect(JSON.stringify(activities)).not.toContain("must-never-be-displayed");
});
- test("forwards reviewed-file progress from descendant workers only", async () => {
- const { home, usage, parent, worker } = await workerSessionFixture();
- const descendant = await writeSession(home, "nested-worker-thread", usage, {
- parent: "worker-thread",
- });
- const unrelated = await writeSession(home, "unrelated-thread", usage);
-
- await appendSessionItem(parent, progressMessage(1));
- await appendSessionItem(worker, progressMessage(3));
- await appendSessionItem(worker, progressMessage(4, 9));
- await appendSessionItem(descendant, progressMessage(5));
- await appendSessionItem(unrelated, progressMessage(7));
-
+ test("does not derive ordering from a mismatched or unfamiliar command projection", async () => {
+ const { home, parent } = await workerSessionFixture();
const updates: ScanProgress[] = [];
const tracker = costTracker(home, {
expectedFilesTotal: 8,
onProgress: (progress) => updates.push(progress),
});
tracker.start("scan-thread");
+ await tracker.refresh();
+ const progress = {
+ phase: "discovery",
+ filesCompleted: 1,
+ filesTotal: 8,
+ } as const;
+ const text = "CODEX_SECURITY_SCAN_PROGRESS " + JSON.stringify(progress);
+ tracker.recordParentProgress(progress, {
+ type: "item.completed",
+ item: {
+ type: "command_execution",
+ command: "'unfinished",
+ aggregated_output: text,
+ },
+ });
+ await appendSessionItem(parent, progressMessage(2));
+ await appendFile(
+ parent,
+ JSON.stringify(nativeCommand("different", text)) + "\n",
+ );
await tracker.stop();
-
- expect(updates).toEqual([
- { phase: "discovery", filesCompleted: expect.any(Number), filesTotal: 8 },
- { phase: "discovery", filesCompleted: 8, filesTotal: 8 },
- ]);
- expect([3, 5]).toContain(updates[0]!.filesCompleted);
+ expect(updates).toEqual([{ ...progress, filesCompleted: 2 }]);
});
+ test.each([940, 944])(
+ "preserves the parent's exact inventory of %p in custom-tool progress",
+ async (filesTotal) => {
+ const { home, parent } = await workerSessionFixture();
+ const updates: ScanProgress[] = [];
+ const tracker = costTracker(home, {
+ expectedFilesTotal: 942,
+ onProgress: (update) => {
+ updates.push(update);
+ if (update.phase === "discovery" && update.filesCompleted === 0)
+ tracker.setExpectedFilesTotal(update.filesTotal);
+ },
+ });
+ tracker.start("scan-thread");
+ for (const filesCompleted of [0, 7]) {
+ await appendSessionItem(parent, {
+ type: "custom_tool_call_output",
+ call_id: `parent-progress-${filesCompleted}`,
+ output: [
+ {
+ type: "input_text",
+ text: `CODEX_SECURITY_SCAN_PROGRESS ${JSON.stringify({
+ phase: "discovery",
+ filesCompleted,
+ filesTotal,
+ })}`,
+ },
+ ],
+ });
+ await tracker.refresh();
+ }
+ await appendSessionItem(parent, progressMessage(0, filesTotal + 1));
+ await appendSessionItem(parent, progressMessage(8, filesTotal + 1));
+ await tracker.stop();
+ expect(updates).toEqual([
+ { phase: "discovery", filesCompleted: 0, filesTotal },
+ { phase: "discovery", filesCompleted: 7, filesTotal },
+ ]);
+ },
+ );
+
test("aggregates worker progress without regressing or changing assigned shards", async () => {
const { home, usage, parent, worker } = await workerSessionFixture();
const otherWorker = await writeSession(home, "other-worker-thread", usage, {
@@ -2380,6 +5753,7 @@ describe("live scan cost tracking", () => {
await tracker.refresh();
await appendSessionItem(otherWorker, progressMessage(2, 2));
+ await tracker.refresh();
await appendSessionItem(otherWorker, progressMessage(3, 3));
await appendSessionItem(otherWorker, progressMessage(1, 1_259));
await appendSessionItem(parent, progressMessage(1_200, 1_258));
@@ -2416,6 +5790,7 @@ describe("live scan cost tracking", () => {
expect(updates).toEqual([
{ phase: "discovery", filesCompleted: 3, filesTotal: 1_258 },
{ phase: "discovery", filesCompleted: 5, filesTotal: 1_258 },
+ { phase: "discovery", filesCompleted: 1_200, filesTotal: 1_258 },
{ phase: "discovery", filesCompleted: 1_251, filesTotal: 1_258 },
{ phase: "validation", filesCompleted: 1_251, filesTotal: 1_258 },
]);
@@ -2462,11 +5837,7 @@ describe("live scan cost tracking", () => {
test("counts only explicit successful worker review receipts", async () => {
const { home, worker } = await workerSessionFixture();
const marker = (filesCompleted: number) =>
- `CODEX_SECURITY_SCAN_PROGRESS ${JSON.stringify({
- phase: "discovery",
- filesCompleted,
- filesTotal: 8,
- })}`;
+ progressMarker("discovery", filesCompleted, 8);
for (const payload of [
{
diff --git a/sdk/typescript/tests-ts/custom-validation.test.ts b/sdk/typescript/tests-ts/custom-validation.test.ts
index d09b62371..bde41dc32 100644
--- a/sdk/typescript/tests-ts/custom-validation.test.ts
+++ b/sdk/typescript/tests-ts/custom-validation.test.ts
@@ -3,6 +3,7 @@ import { resolveCodexProfile } from "../src/config.js";
import { randomUUID } from "node:crypto";
import { mkdirSync, renameSync, writeFileSync } from "node:fs";
import {
+ appendFile,
chmod,
cp,
mkdir,
@@ -16,6 +17,8 @@ import { join, resolve } from "node:path";
import type { ScanReadFile } from "../../../plugins/codex-security/native/scan-read-binding.mjs";
import type { ThreadEvent } from "@openai/codex-sdk";
import type { ScanActivity } from "../src/scan-activity.js";
+import type { ScanSessionEvent } from "../src/cost.js";
+import { progressMarker, writeSession } from "./support/usage-rollout.js";
import Ajv2020 from "ajv/dist/2020.js";
import { afterEach, describe, expect, mock, spyOn, test } from "bun:test";
import {
@@ -722,6 +725,9 @@ describe("custom validation", () => {
"empty",
"incomplete",
"dismissed",
+ "late-progress",
+ "live-progress",
+ "late-progress-observer-error",
"unfinished-source",
];
test.each(completionScenarios)(
@@ -772,6 +778,33 @@ describe("custom validation", () => {
const workingDirectories: Array<string | undefined> = [];
const commands: string[] = [];
const activities: ScanActivity[] = [];
+ const progressScenario =
+ scenario !== "progress" && scenario.includes("progress");
+ const progressUpdates: Array<
+ ScanProgress & { validationStarted: boolean }
+ > = [];
+ const observerErrors: string[] = [];
+ let validationStarted = false;
+ let parentRollout = "";
+ const parentSeen = Promise.withResolvers<void>();
+ const parentMessage = (
+ id: string,
+ phase: ScanProgress["phase"],
+ filesCompleted: number,
+ ) => ({
+ type: "response_item",
+ payload: {
+ type: "message",
+ id,
+ role: "assistant",
+ content: [
+ {
+ type: "output_text",
+ text: progressMarker(phase, filesCompleted, 1),
+ },
+ ],
+ },
+ });
const progress: ScanProgress[] = [];
const validationActivity = "Synthetic validation activity.";
const profileDisabledTools =
@@ -889,6 +922,39 @@ describe("custom validation", () => {
);
expect(commands).not.toContain("prepare-scan-completion");
expect(commands).not.toContain("complete-scan");
+ if (progressScenario) {
+ parentRollout = await writeSession(
+ codexHome,
+ "thread-1",
+ { input_tokens: 10, output_tokens: 3 },
+ );
+ const messages = [
+ parentMessage("inventory", "discovery", 0),
+ parentMessage("review", "discovery", 1),
+ ];
+ if (scenario === "live-progress")
+ messages.push(
+ parentMessage("parent-final", "reporting", 1),
+ );
+ await appendFile(
+ parentRollout,
+ jsonLines(messages) + "\n",
+ );
+ async function* progressEvents(): AsyncGenerator<ThreadEvent> {
+ for (const message of messages)
+ yield {
+ type: "item.completed",
+ item: {
+ id: message.payload.id,
+ type: "agent_message",
+ text: message.payload.content[0]!.text,
+ },
+ };
+ }
+ return {
+ events: completedEvents("thread-1", progressEvents()),
+ };
+ }
if (scenario === "progress") {
return {
events:
@@ -999,6 +1065,26 @@ describe("custom validation", () => {
);
}
}
+ if (progressScenario) {
+ validationStarted = true;
+ if (scenario !== "live-progress") {
+ await appendFile(
+ parentRollout,
+ JSON.stringify(
+ parentMessage("parent-final", "reporting", 1),
+ ) + "\n",
+ );
+ // The observer fires during the same synchronous batch that
+ // processes progress, so this awaits the actual saved receipt.
+ await parentSeen.promise;
+ }
+ expect(progressUpdates.at(-1)?.phase).toBe("validation");
+ expect(
+ progressUpdates
+ .filter((update) => update.validationStarted)
+ .every((update) => update.phase === "validation"),
+ ).toBe(true);
+ }
return {
events: responseEvents(
output,
@@ -1023,6 +1109,10 @@ describe("custom validation", () => {
},
},
);
+ // Keep the synthetic validation turn alive while it awaits an unref'ed poll.
+ const keepAlive = progressScenario
+ ? setInterval(() => {}, 1_000)
+ : undefined;
try {
const pending = client.run(repository, {
cyberAccessProgram: "daybreak_blue",
@@ -1031,6 +1121,27 @@ describe("custom validation", () => {
? { validationPromptFile: workflowFile }
: { validationPrompt: workflow }),
onActivity: (activity) => activities.push(activity),
+ ...(progressScenario
+ ? {
+ onProgress: (progress: ScanProgress) => {
+ progressUpdates.push({ ...progress, validationStarted });
+ if (
+ scenario === "late-progress-observer-error" &&
+ progress.phase === "validation"
+ )
+ throw new Error("Synthetic optional progress failure.");
+ },
+ onSessionEvent: ({ event }: ScanSessionEvent) => {
+ if (
+ (event["payload"] as { id?: string } | undefined)?.id ===
+ "parent-final"
+ )
+ parentSeen.resolve();
+ },
+ onObserverError: (observer: string) =>
+ observerErrors.push(observer),
+ }
+ : {}),
...(scenario === "progress"
? { onProgress: (update: ScanProgress) => progress.push(update) }
: {}),
@@ -1081,6 +1192,18 @@ describe("custom validation", () => {
return;
}
const completed = await pending;
+ if (progressScenario) {
+ expect(observerErrors).toEqual(
+ scenario === "late-progress-observer-error" ? ["onProgress"] : [],
+ );
+ if (scenario === "live-progress")
+ expect(
+ progressUpdates.some(
+ (update) =>
+ update.phase === "reporting" && !update.validationStarted,
+ ),
+ ).toBe(true);
+ }
if (scenario === "standard") {
const report = await readFile(join(scanDir, "report.md"), "utf8");
expect(report).toContain(
@@ -1128,6 +1251,7 @@ describe("custom validation", () => {
count === 0 || scenario === "dismissed" ? "No findings" : "Fixture 0",
);
} finally {
+ clearInterval(keepAlive);
await client.close();
}
},
diff --git a/sdk/typescript/tests-ts/security-policy.test.ts b/sdk/typescript/tests-ts/security-policy.test.ts
index 1f5734ad3..bc50095e1 100644
--- a/sdk/typescript/tests-ts/security-policy.test.ts
+++ b/sdk/typescript/tests-ts/security-policy.test.ts
@@ -1158,15 +1158,17 @@ describe("security policy preview", () => {
const f = await fixture();
const draft = await f.generate();
const source = new URL("../src/security-policy.ts", import.meta.url);
- const built = await Bun.build({
- entrypoints: [fileURLToPath(source)],
- target: "node",
- format: "esm",
- define: { "import.meta.url": JSON.stringify(source.href) },
- });
- expect(built.success).toBe(true);
const module = join(f.root, "policy.mjs");
- await writeFile(module, await built.outputs[0]!.text());
+ // Repeated in-process Bun builds can misread dependency files on macOS.
+ execFileSync(process.execPath, [
+ "build",
+ fileURLToPath(source),
+ "--target=node",
+ "--format=esm",
+ "--define",
+ `import.meta.url=${JSON.stringify(source.href)}`,
+ `--outfile=${module}`,
+ ]);
const missingPython = join(f.root, "missing-python");
const result = JSON.parse(
execFileSync(
diff --git a/sdk/typescript/tests-ts/support/usage-rollout.ts b/sdk/typescript/tests-ts/support/usage-rollout.ts
index 201464738..706af41eb 100644
--- a/sdk/typescript/tests-ts/support/usage-rollout.ts
+++ b/sdk/typescript/tests-ts/support/usage-rollout.ts
@@ -1,6 +1,7 @@
import { mkdir, writeFile } from "node:fs/promises";
import { runNodePython } from "./python-probe.js";
import { join } from "node:path";
+import type { ThreadEvent } from "@openai/codex-sdk";
import assert from "node:assert/strict";
export const scanThreadId = "scan-thread";
@@ -25,6 +26,51 @@ export const ownedPythonUsage = {
totalTokens: 110,
};
+export function progressMarker(
+ phase: string,
+ filesCompleted: number,
+ filesTotal: number,
+): string {
+ return `CODEX_SECURITY_SCAN_PROGRESS ${JSON.stringify({ phase, filesCompleted, filesTotal })}`;
+}
+
+export function nativeCommand(
+ command: string | readonly string[],
+ output: string,
+ id?: string,
+) {
+ return {
+ type: "event_msg",
+ payload: {
+ type: "item_completed",
+ item: {
+ type: "CommandExecution",
+ ...(id === undefined ? {} : { id }),
+ command: typeof command === "string" ? [command] : command,
+ aggregated_output: output,
+ },
+ },
+ };
+}
+
+export function completedCommand(
+ command: string,
+ output: string,
+ id = command,
+): ThreadEvent {
+ return {
+ type: "item.completed",
+ item: {
+ type: "command_execution",
+ id,
+ command,
+ aggregated_output: output,
+ status: "completed",
+ exit_code: 0,
+ },
+ };
+}
+
function uuid7TaskStarted(turnId: string): Record<string, unknown> {
return {
type: "event_msg",