fix(runner): deprecation race condition

Author: nicktrn

packages/cli-v3/src/entryPoints/managed/snapshot.test.ts

@@ -697,6 +697,65 @@ describe("SnapshotManager", () => {
       true
     );
   });
+
+  it("should handle deprecated snapshot race condition - avoid false positives from stale polls", async () => {
+    const onSnapshotChange = vi.fn();
+
+    // Mock MetadataClient to simulate runner ID change (restore detected) on first call
+    let isFirstCall = true;
+    const mockMetadataClient = {
+      getEnvOverrides: vi.fn().mockImplementation(() => {
+        if (isFirstCall) {
+          isFirstCall = false;
+          return Promise.resolve([null, { TRIGGER_RUNNER_ID: "test-runner-2" }]); // Different runner ID = restore
+        }
+        return Promise.resolve([null, { TRIGGER_RUNNER_ID: "test-runner-2" }]); // Same runner ID afterward
+      }),
+    };
+
+    const manager = new SnapshotManager({
+      runnerId: "test-runner-1",
+      runFriendlyId: "test-run-1",
+      initialSnapshotId: "snapshot-1",
+      initialStatus: "EXECUTING_WITH_WAITPOINTS",
+      logger: mockLogger,
+      metadataClient: mockMetadataClient as any,
+      onSnapshotChange,
+      onSuspendable: mockSuspendableHandler,
+    });
+
+    // First update: Process restore transition with deprecated statuses (normal case)
+    // This simulates: EXECUTING_WITH_WAITPOINTS -> [SUSPENDED, QUEUED] -> PENDING_EXECUTING
+    await manager.handleSnapshotChanges([
+      createRunExecutionData({ snapshotId: "snapshot-suspended", executionStatus: "SUSPENDED" }),
+      createRunExecutionData({ snapshotId: "snapshot-queued", executionStatus: "QUEUED" }),
+      createRunExecutionData({ snapshotId: "snapshot-2", executionStatus: "PENDING_EXECUTING" }),
+    ]);
+
+    // First call should be deprecated=false (restore detected)
+    expect(onSnapshotChange).toHaveBeenCalledWith(
+      expect.objectContaining({ snapshot: expect.objectContaining({ friendlyId: "snapshot-2" }) }),
+      false
+    );
+
+    onSnapshotChange.mockClear();
+
+    // Second update: Should only get new snapshot (race condition case)
+    // This simulates a stale poll that returns: getSnapshotsSince(snapshot-1) -> [SUSPENDED, QUEUED, snapshot-2, snapshot-3]
+    // The SUSPENDED/QUEUED should be ignored as already seen
+    await manager.handleSnapshotChanges([
+      createRunExecutionData({ snapshotId: "snapshot-suspended", executionStatus: "SUSPENDED" }), // Already seen
+      createRunExecutionData({ snapshotId: "snapshot-queued", executionStatus: "QUEUED" }), // Already seen
+      createRunExecutionData({ snapshotId: "snapshot-2", executionStatus: "PENDING_EXECUTING" }), // Already processed
+      createRunExecutionData({ snapshotId: "snapshot-3", executionStatus: "EXECUTING" }), // New
+    ]);
+
+    // Should call onSnapshotChange with deprecated = false (no new deprecated snapshots)
+    expect(onSnapshotChange).toHaveBeenCalledWith(
+      expect.objectContaining({ snapshot: expect.objectContaining({ friendlyId: "snapshot-3" }) }),
+      false
+    );
+  });
 });
 
 // Helper to generate RunExecutionData with sensible defaults

packages/cli-v3/src/entryPoints/managed/snapshot.ts

@@ -49,6 +49,10 @@ export class SnapshotManager {
   private changeQueue: QueuedChangeItem[] = [];
   private isProcessingQueue = false;
 
+  // Track seen deprecated snapshots to prevent false positives
+  private seenDeprecatedSnapshotIds: string[] = [];
+  private readonly maxSeenDeprecatedSnapshotIds = 50;
+
   constructor(opts: SnapshotManagerOptions) {
     this.runFriendlyId = opts.runFriendlyId;
     this.runnerId = opts.runnerId;
@@ -284,9 +288,13 @@ export class SnapshotManager {
 
         // Check if any previous snapshot is QUEUED or SUSPENDED
         const deprecatedStatus: TaskRunExecutionStatus[] = ["QUEUED", "SUSPENDED"];
-        const deprecatedSnapshots = previousSnapshots.filter((snap) =>
-          deprecatedStatus.includes(snap.snapshot.executionStatus)
-        );
+        const deprecatedSnapshots = previousSnapshots.filter((snap) => {
+          const isDeprecated = deprecatedStatus.includes(snap.snapshot.executionStatus);
+          const previouslySeen = this.seenDeprecatedSnapshotIds.some(
+            (s) => s === snap.snapshot.friendlyId
+          );
+          return isDeprecated && !previouslySeen;
+        });
 
         let deprecated = false;
         if (deprecatedSnapshots.length > 0) {
@@ -298,6 +306,18 @@ export class SnapshotManager {
           } else {
             deprecated = true;
           }
+
+          // Add the deprecated snapshot IDs to the seen list
+          this.seenDeprecatedSnapshotIds.push(
+            ...deprecatedSnapshots.map((s) => s.snapshot.friendlyId)
+          );
+
+          if (this.seenDeprecatedSnapshotIds.length > this.maxSeenDeprecatedSnapshotIds) {
+            // Only keep the latest maxSeenDeprecatedSnapshotIds
+            this.seenDeprecatedSnapshotIds = this.seenDeprecatedSnapshotIds.slice(
+              -this.maxSeenDeprecatedSnapshotIds
+            );
+          }
         }
 
         const { snapshot } = latestSnapshot;