@letta-ai/letta-code 0.30.27 → 0.30.29

package/scripts/codex-watch/tracker.test.ts

@@ -1,14 +1,17 @@
 import { describe, expect, test } from "bun:test";
 import type { CodexWatchAnalysis } from "./release-analysis.ts";
 import {
+  advanceCodexAuditCursor,
   emptyTrackerState,
-  hasProcessedTag,
+  getCodexAuditCursorTag,
+  hasProcessedRange,
   parseTrackerState,
   recordAnalysis,
   renderTrackerBody,
   serializeTrackerState,
   type TrackerEntry,
   upsertTrackerEntry,
+  validateLegacyCodexAuditCursor,
 } from "./tracker.ts";
 
 function analysis(
@@ -18,6 +21,7 @@ function analysis(
   return {
     previous_tag: "rust-v0.1.0",
     current_tag: tag,
+    is_adjacent_release: true,
     release_url: `https://github.com/openai/codex/releases/tag/${tag}`,
     release_notes_md: "",
     verdict,
@@ -31,6 +35,12 @@ function analysis(
   };
 }
 
+function withoutAuditCursor(body: string): string {
+  return body
+    .replace(/  "audit_cursor_tag": (?:null|"[^"]+"),\n/, "")
+    .replace('  "audit_cursor_validated": true,\n', "");
+}
+
 function entry(index: number, outcome: TrackerEntry["outcome"]): TrackerEntry {
   const verdict =
     outcome === "recorded_noop" ? "no-op" : "tool-surface review needed";
@@ -51,11 +61,38 @@ function entry(index: number, outcome: TrackerEntry["outcome"]): TrackerEntry {
 }
 
 describe("tracker state", () => {
-  test("returns empty state when hidden state is absent or malformed", () => {
-    expect(parseTrackerState("plain body")).toEqual(emptyTrackerState());
-    expect(
+  test("fails closed when hidden state is absent or malformed", () => {
+    expect(() => parseTrackerState("plain body")).toThrow(
+      "Codex tracker hidden state is missing",
+    );
+    expect(() =>
       parseTrackerState("<!-- codex-agent-watch-state\nnot json\n-->"),
-    ).toEqual(emptyTrackerState());
+    ).toThrow("Codex tracker hidden state is invalid");
+    expect(() =>
+      parseTrackerState(
+        '<!-- codex-agent-watch-state\n{"last_checked_tag":null,"last_checked_at":null,"processed":[{}]}\n-->',
+      ),
+    ).toThrow("Codex tracker hidden state is invalid");
+    expect(() =>
+      parseTrackerState(
+        '<!-- codex-agent-watch-state\n{"audit_cursor_tag":null,"last_checked_tag":"rust-v0.2.0","last_checked_at":"2026-08-20T00:00:00Z","processed":[]}\n-->',
+      ),
+    ).toThrow("Codex tracker hidden state is invalid");
+  });
+
+  test("fails closed on an unsupported durable cursor", () => {
+    const state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(1, "no_local_impact"),
+    );
+    const body = renderTrackerBody(state).replace(
+      '"audit_cursor_tag": "rust-v0.1.0"',
+      '"audit_cursor_tag": "rust-v0.5.0"',
+    );
+
+    expect(() => parseTrackerState(body)).toThrow(
+      "Codex tracker hidden state is invalid",
+    );
   });
 
   test("round-trips hidden state through rendered body", () => {
@@ -72,6 +109,85 @@ describe("tracker state", () => {
     expect(body).toContain("upstream-only router change");
   });
 
+  test("derives the durable cursor from legacy hidden state", () => {
+    const state = recordAnalysis(emptyTrackerState(), {
+      analysis: analysis("rust-v0.2.0"),
+      outcome: "recorded_noop",
+      notes: "no watched changes",
+      processedAt: "2026-07-02T00:00:00.000Z",
+    });
+    const legacyBody = withoutAuditCursor(renderTrackerBody(state));
+
+    const legacy = parseTrackerState(legacyBody);
+    expect(legacy.audit_cursor_validated).toBe(false);
+    const migrated = validateLegacyCodexAuditCursor(legacy, [
+      "rust-v0.1.0",
+      "rust-v0.2.0",
+    ]);
+    expect(migrated.audit_cursor_validated).toBe(true);
+    expect(getCodexAuditCursorTag(migrated)).toBe("rust-v0.2.0");
+  });
+
+  test("migrates a legacy cursor independently of an older replay", () => {
+    let state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(1, "no_local_impact"),
+    );
+    state = upsertTrackerEntry(state, entry(2, "no_local_impact"));
+    state = upsertTrackerEntry(state, entry(3, "no_local_impact"));
+    state = upsertTrackerEntry(state, entry(1, "no_local_impact"));
+
+    const legacy = parseTrackerState(
+      withoutAuditCursor(renderTrackerBody(state)),
+    );
+    const migrated = validateLegacyCodexAuditCursor(legacy, [
+      "rust-v0.0.0",
+      "rust-v0.1.0",
+      "rust-v0.2.0",
+      "rust-v0.3.0",
+    ]);
+    expect(migrated.last_checked_tag).toBe("rust-v0.1.0");
+    expect(getCodexAuditCursorTag(migrated)).toBe("rust-v0.3.0");
+  });
+
+  test("fails closed on a disconnected future legacy replay", () => {
+    let state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(1, "no_local_impact"),
+    );
+    state = upsertTrackerEntry(state, entry(2, "no_local_impact"));
+    state = upsertTrackerEntry(state, entry(5, "no_local_impact"));
+
+    expect(() =>
+      parseTrackerState(withoutAuditCursor(renderTrackerBody(state))),
+    ).toThrow("Codex tracker hidden state is invalid");
+  });
+
+  test("fails closed on a cumulative legacy replay", () => {
+    const cumulative = {
+      ...analysis("rust-v0.5.0", "tool-surface review needed"),
+      is_adjacent_release: false,
+    };
+    const state = recordAnalysis(emptyTrackerState(), {
+      analysis: cumulative,
+      outcome: "no_local_impact",
+      notes: "legacy cumulative replay",
+    });
+    const legacy = parseTrackerState(
+      withoutAuditCursor(renderTrackerBody(state)),
+    );
+
+    expect(() =>
+      validateLegacyCodexAuditCursor(legacy, [
+        "rust-v0.1.0",
+        "rust-v0.2.0",
+        "rust-v0.3.0",
+        "rust-v0.4.0",
+        "rust-v0.5.0",
+      ]),
+    ).toThrow("Legacy Codex tracker range is not adjacent");
+  });
+
   test("records noops in hidden state without adding visible table rows", () => {
     const state = recordAnalysis(emptyTrackerState(), {
       analysis: analysis("rust-v0.2.0"),
@@ -81,11 +197,132 @@ describe("tracker state", () => {
     });
 
     const body = renderTrackerBody(state);
-    expect(hasProcessedTag(parseTrackerState(body), "rust-v0.2.0")).toBe(true);
+    expect(
+      hasProcessedRange(
+        parseTrackerState(body),
+        "rust-v0.1.0",
+        "rust-v0.2.0",
+      ),
+    ).toBe(true);
     expect(body).toContain("_No actionable releases recorded yet._");
     expect(body).toContain("no watched changes");
   });
 
+  test("retries an errored release from its previous tag", () => {
+    let state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(1, "recorded_noop"),
+    );
+    state = upsertTrackerEntry(state, entry(2, "error"));
+
+    expect(
+      hasProcessedRange(state, "rust-v0.1.0", "rust-v0.2.0"),
+    ).toBe(false);
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.1.0");
+
+    state = upsertTrackerEntry(state, entry(2, "no_local_impact"));
+    expect(
+      hasProcessedRange(state, "rust-v0.1.0", "rust-v0.2.0"),
+    ).toBe(true);
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.2.0");
+  });
+
+  test("uses an errored release baseline when no terminal entry exists", () => {
+    const state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(2, "error"),
+    );
+
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.1.0");
+  });
+
+  test("does not regress the cursor after an older replay", () => {
+    let state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(10, "no_local_impact"),
+    );
+    state = upsertTrackerEntry(state, entry(5, "no_local_impact"));
+
+    expect(state.last_checked_tag).toBe("rust-v0.5.0");
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.10.0");
+  });
+
+  test("does not let a future replay skip an errored release", () => {
+    let state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(1, "no_local_impact"),
+    );
+    state = upsertTrackerEntry(state, entry(2, "error"));
+    state = upsertTrackerEntry(state, entry(5, "no_local_impact"));
+
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.1.0");
+
+    state = upsertTrackerEntry(state, entry(2, "no_local_impact"));
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.2.0");
+  });
+
+  test("does not advance for an explicit non-adjacent range", () => {
+    const initial = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(1, "no_local_impact"),
+    );
+    const cumulative = {
+      ...analysis("rust-v0.5.0", "tool-surface review needed"),
+      is_adjacent_release: false,
+    };
+    const state = recordAnalysis(initial, {
+      analysis: cumulative,
+      outcome: "no_local_impact",
+      notes: "explicit cumulative replay",
+    });
+
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.1.0");
+    expect(
+      getCodexAuditCursorTag(
+        advanceCodexAuditCursor(
+          state,
+          "rust-v0.1.0",
+          "rust-v0.5.0",
+          false,
+        ),
+      ),
+    ).toBe("rust-v0.1.0");
+  });
+
+  test("advances across an already audited adjacent range", () => {
+    let state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(1, "no_local_impact"),
+    );
+    state = upsertTrackerEntry(state, entry(3, "no_local_impact"));
+    state = upsertTrackerEntry(state, entry(2, "no_local_impact"));
+
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.2.0");
+    state = advanceCodexAuditCursor(
+      state,
+      "rust-v0.2.0",
+      "rust-v0.3.0",
+      true,
+    );
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.3.0");
+  });
+
+  test("retains the durable cursor entry when history is truncated", () => {
+    let state = upsertTrackerEntry(
+      emptyTrackerState(),
+      entry(100, "no_local_impact"),
+    );
+    for (let index = 1; index <= 60; index += 1) {
+      state = upsertTrackerEntry(state, entry(index, "no_local_impact"));
+    }
+
+    expect(state.processed).toHaveLength(50);
+    expect(state.processed.some(({ tag }) => tag === "rust-v0.100.0")).toBe(
+      true,
+    );
+    expect(getCodexAuditCursorTag(state)).toBe("rust-v0.100.0");
+  });
+
   test("keeps the last 50 processed releases in hidden state", () => {
     let state = emptyTrackerState();
     for (let i = 1; i <= 60; i++) {

package/scripts/codex-watch/tracker.ts

@@ -26,6 +26,8 @@ export interface TrackerEntry {
 }
 
 export interface TrackerState {
+  audit_cursor_tag: string | null;
+  audit_cursor_validated: boolean;
   last_checked_tag: string | null;
   last_checked_at: string | null;
   processed: TrackerEntry[];
@@ -41,6 +43,8 @@ export interface RecordAnalysisOptions {
 
 export function emptyTrackerState(): TrackerState {
   return {
+    audit_cursor_tag: null,
+    audit_cursor_validated: true,
     last_checked_tag: null,
     last_checked_at: null,
     processed: [],
@@ -49,21 +53,81 @@ export function emptyTrackerState(): TrackerState {
 
 export function parseTrackerState(body: string): TrackerState {
   const start = body.indexOf(STATE_START);
-  if (start === -1) return emptyTrackerState();
+  if (start === -1) throw new Error("Codex tracker hidden state is missing");
 
   const jsonStart = start + STATE_START.length;
   const end = body.indexOf(STATE_END, jsonStart);
-  if (end === -1) return emptyTrackerState();
+  if (end === -1) throw new Error("Codex tracker hidden state is incomplete");
 
   try {
     return normalizeState(JSON.parse(body.slice(jsonStart, end).trim()));
-  } catch {
-    return emptyTrackerState();
+  } catch (error) {
+    throw new Error("Codex tracker hidden state is invalid", { cause: error });
   }
 }
 
-export function hasProcessedTag(state: TrackerState, tag: string): boolean {
-  return state.processed.some((entry) => entry.tag === tag);
+export function isTerminalOutcome(outcome: TrackerOutcome): boolean {
+  return outcome !== "error";
+}
+
+export function hasProcessedRange(
+  state: TrackerState,
+  previousTag: string,
+  currentTag: string,
+): boolean {
+  return state.processed.some(
+    (entry) =>
+      entry.previous_tag === previousTag &&
+      entry.tag === currentTag &&
+      isTerminalOutcome(entry.outcome),
+  );
+}
+
+export function getCodexAuditCursorTag(state: TrackerState): string | null {
+  return state.audit_cursor_tag;
+}
+
+export function validateLegacyCodexAuditCursor(
+  state: TrackerState,
+  stableTags: string[],
+): TrackerState {
+  if (state.audit_cursor_validated) return state;
+
+  let tag = state.audit_cursor_tag;
+  while (tag !== null) {
+    const entry = state.processed.find(
+      (candidate) =>
+        candidate.tag === tag && isTerminalOutcome(candidate.outcome),
+    );
+    if (!entry) break;
+    const currentIndex = stableTags.indexOf(entry.tag);
+    if (
+      currentIndex < 1 ||
+      stableTags[currentIndex - 1] !== entry.previous_tag
+    ) {
+      throw new Error(
+        `Legacy Codex tracker range is not adjacent: ${entry.previous_tag}...${entry.tag}`,
+      );
+    }
+    tag = entry.previous_tag;
+  }
+
+  return { ...state, audit_cursor_validated: true };
+}
+
+export function advanceCodexAuditCursor(
+  state: TrackerState,
+  previousTag: string,
+  currentTag: string,
+  isAdjacentRelease: boolean,
+): TrackerState {
+  if (!isAdjacentRelease || state.audit_cursor_tag !== previousTag) return state;
+  if (!hasProcessedRange(state, previousTag, currentTag)) {
+    throw new Error(
+      `Cannot advance Codex audit cursor without terminal ${previousTag}...${currentTag}`,
+    );
+  }
+  return { ...state, audit_cursor_tag: currentTag };
 }
 
 export function recordAnalysis(
@@ -81,19 +145,51 @@ export function recordAnalysis(
     processed_at: processedAt,
     compare_url: options.analysis.compare_url,
     workflow_run_url: options.analysis.workflow_run_url,
-  });
+  }, options.analysis.is_adjacent_release);
 }
 
 export function upsertTrackerEntry(
   state: TrackerState,
   entry: TrackerEntry,
+  advanceAuditCursor = true,
 ): TrackerState {
-  const processed = [
+  let auditCursorTag = state.audit_cursor_tag;
+  if (auditCursorTag === null && !advanceAuditCursor) {
+    auditCursorTag = entry.previous_tag;
+  } else if (
+    advanceAuditCursor &&
+    entry.outcome === "error" &&
+    auditCursorTag === null
+  ) {
+    auditCursorTag = entry.previous_tag;
+  } else if (
+    advanceAuditCursor &&
+    isTerminalOutcome(entry.outcome) &&
+    (auditCursorTag === null || entry.previous_tag === auditCursorTag)
+  ) {
+    auditCursorTag = entry.tag;
+  }
+
+  const candidates = [
     entry,
-    ...state.processed.filter((existing) => existing.tag !== entry.tag),
-  ].slice(0, HIDDEN_STATE_LIMIT);
+    ...state.processed.filter(
+      (existing) =>
+        existing.tag !== entry.tag ||
+        existing.previous_tag !== entry.previous_tag,
+    ),
+  ];
+  let processed = candidates.slice(0, HIDDEN_STATE_LIMIT);
+  if (auditCursorTag !== null && !isSupportedAuditCursor(processed, auditCursorTag)) {
+    const support = candidates.find((candidate) =>
+      isAuditCursorSupportEntry(candidate, auditCursorTag),
+    );
+    if (!support) throw new Error("Codex audit cursor has no supporting entry");
+    processed = [...processed.slice(0, HIDDEN_STATE_LIMIT - 1), support];
+  }
 
   return {
+    audit_cursor_tag: auditCursorTag,
+    audit_cursor_validated: state.audit_cursor_validated,
     last_checked_tag: entry.tag,
     last_checked_at: entry.processed_at,
     processed,
@@ -103,9 +199,7 @@ export function upsertTrackerEntry(
 export function renderTrackerBody(state: TrackerState): string {
   const normalized = normalizeState(state);
   const parts: string[] = [
-    "Central tracker for the Amelia-driven Codex upstream drift watch experiment.",
-    "",
-    "The legacy per-release `codex-release-watch.yml` issue workflow is still enabled as the baseline while this tracker bakes off the new automation path.",
+    "Central tracker for Amelia-driven Codex upstream drift monitoring.",
     "",
     renderLastChecked(normalized),
     "",
@@ -181,28 +275,129 @@ function escapeTable(value: string): string {
 }
 
 function normalizeState(value: unknown): TrackerState {
-  if (!isRecord(value)) return emptyTrackerState();
+  if (!isRecord(value)) throw new TypeError("tracker state must be an object");
+  if (!Array.isArray(value.processed) || !value.processed.every(isTrackerEntry)) {
+    throw new TypeError("tracker processed entries are invalid");
+  }
+  if (
+    value.last_checked_tag !== null &&
+    typeof value.last_checked_tag !== "string"
+  ) {
+    throw new TypeError("tracker last_checked_tag is invalid");
+  }
+  if (
+    value.last_checked_at !== null &&
+    typeof value.last_checked_at !== "string"
+  ) {
+    throw new TypeError("tracker last_checked_at is invalid");
+  }
 
-  const processed = Array.isArray(value.processed)
-    ? value.processed.filter(isTrackerEntry).slice(0, HIDDEN_STATE_LIMIT)
-    : [];
+  const processed = value.processed.slice(
+    0,
+    HIDDEN_STATE_LIMIT,
+  ) as TrackerEntry[];
+  const lastCheckedTag = value.last_checked_tag as string | null;
+  const lastChecked =
+    lastCheckedTag === null
+      ? null
+      : processed.find((entry) => entry.tag === lastCheckedTag);
+  if (lastCheckedTag === null ? processed.length > 0 : !lastChecked) {
+    throw new TypeError("tracker last_checked_tag is inconsistent");
+  }
+
+  let auditCursorTag: string | null;
+  let auditCursorValidated: boolean;
+  if (value.audit_cursor_tag === undefined) {
+    auditCursorTag = deriveLegacyAuditCursor(processed);
+    auditCursorValidated = false;
+  } else if (
+    (value.audit_cursor_tag === null ||
+      typeof value.audit_cursor_tag === "string") &&
+    value.audit_cursor_validated === true
+  ) {
+    auditCursorTag = value.audit_cursor_tag;
+    auditCursorValidated = true;
+  } else {
+    throw new TypeError("tracker audit cursor is invalid");
+  }
+  if (auditCursorTag !== null && !isStableTag(auditCursorTag)) {
+    throw new TypeError("tracker audit_cursor_tag is invalid");
+  }
+  if (auditCursorTag === null && processed.length > 0) {
+    throw new TypeError("tracker audit_cursor_tag is missing");
+  }
+  if (
+    auditCursorTag !== null &&
+    !isSupportedAuditCursor(processed, auditCursorTag)
+  ) {
+    throw new TypeError("tracker audit_cursor_tag is inconsistent");
+  }
 
   return {
-    last_checked_tag:
-      typeof value.last_checked_tag === "string"
-        ? value.last_checked_tag
-        : null,
-    last_checked_at:
-      typeof value.last_checked_at === "string" ? value.last_checked_at : null,
+    audit_cursor_tag: auditCursorTag,
+    audit_cursor_validated: auditCursorValidated,
+    last_checked_tag: lastCheckedTag,
+    last_checked_at: value.last_checked_at as string | null,
     processed,
   };
 }
 
+function isSupportedAuditCursor(
+  processed: TrackerEntry[],
+  cursorTag: string,
+): boolean {
+  return processed.some((entry) =>
+    isAuditCursorSupportEntry(entry, cursorTag),
+  );
+}
+
+function isAuditCursorSupportEntry(
+  entry: TrackerEntry,
+  cursorTag: string,
+): boolean {
+  return (
+    (entry.tag === cursorTag && isTerminalOutcome(entry.outcome)) ||
+    entry.previous_tag === cursorTag
+  );
+}
+
+function deriveLegacyAuditCursor(processed: TrackerEntry[]): string | null {
+  const terminal = processed.filter((entry) =>
+    isTerminalOutcome(entry.outcome),
+  );
+  if (terminal.length === 0) {
+    const errorBaselines = [
+      ...new Set(
+        processed
+          .filter((entry) => entry.outcome === "error")
+          .map((entry) => entry.previous_tag),
+      ),
+    ];
+    if (errorBaselines.length > 1) {
+      throw new TypeError("legacy tracker error baselines are ambiguous");
+    }
+    return errorBaselines[0] ?? null;
+  }
+
+  const tags = terminal.map((entry) => entry.tag);
+  if (new Set(tags).size !== tags.length) {
+    throw new TypeError("legacy tracker terminal tags are duplicated");
+  }
+  const previousTags = new Set(terminal.map((entry) => entry.previous_tag));
+  const endpoints = tags.filter((tag) => !previousTags.has(tag));
+  if (endpoints.length !== 1) {
+    throw new TypeError("legacy tracker audit chain is ambiguous");
+  }
+  return endpoints[0] ?? null;
+}
+
 function isTrackerEntry(value: unknown): value is TrackerEntry {
   if (!isRecord(value)) return false;
   return (
     typeof value.tag === "string" &&
+    isStableTag(value.tag) &&
     typeof value.previous_tag === "string" &&
+    isStableTag(value.previous_tag) &&
     isVerdict(value.verdict) &&
     isOutcome(value.outcome) &&
     (typeof value.pr_url === "string" || value.pr_url === null) &&
@@ -213,6 +408,10 @@ function isTrackerEntry(value: unknown): value is TrackerEntry {
   );
 }
 
+function isStableTag(value: string): boolean {
+  return /^(?:rust-v|v)?\d+\.\d+\.\d+$/.test(value);
+}
+
 function isVerdict(value: unknown): value is Verdict {
   return (
     value === "no-op" ||