taskchef 9.5.0 → 9.7.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "9.5.0",
+  "version": "9.7.0",
   "description": "Native Codex dashboard with lightweight project delegation.",
   "author": {
     "name": "Favo Yang",

package/docs/mcp-app.md

@@ -6,7 +6,7 @@ The native dashboard requires Node.js 22.18+, 23.2+, or 24+ for local Codex SQLi
 
 Call `open_taskchef_board` in Codex to open **TaskChef**. In a sidebar or fullscreen host view, it shows the read-only board, filters, and chat details. In an inline chat view, it shows a short recent-chat list with direct **Open chat** actions. The app uses local Codex metadata and does not require a dispatcher workspace.
 
-The server reads all eligible top-level chats from `~/.codex/state_5.sqlite` and their latest turn from `~/.codex/thread_history_1.sqlite`. Both SQLite connections are read-only. It excludes typed subagents and Guardian reviews, JSON subagent sources, known `thread_spawn_edges` children, chats with no turn record. Standalone `source=exec` and regular `source=cli` chats remain eligible in the collector, but the view hides them by default. The plugin details page has native switches for Show exec sessions, Show CLI sessions, and Show archived chats. The MCP server stores these choices in `~/.agents/taskchef-next/settings.json`, shared by all TaskChef views. Each visible poll reads the current settings, even when the database snapshot is unchanged. These choices apply to the board, counts, project choices, Details eligibility, and the compact inline view. Archived chats are hidden by default and use their own Archived column when shown. Details shows the recorded lifetime direct child count. Names and titles can contain user text; the app prefers name, then title, then a chat ID fallback.
+The server reads all eligible top-level chats from `~/.codex/state_5.sqlite` and their latest turn from `~/.codex/thread_history_1.sqlite`. Both SQLite connections are read-only. It excludes typed subagents and Guardian reviews, JSON subagent sources, known `thread_spawn_edges` children, chats with no turn record. Standalone `source=exec` and regular `source=cli` chats remain eligible in the collector, but the view hides them by default. The plugin details page has native switches for Show exec sessions, Show CLI sessions, and Show archived chats. The MCP server stores these choices in `~/.agents/taskchef/settings.json`, shared by all TaskChef views. Each visible poll reads the current settings, even when the database snapshot is unchanged. These choices apply to the board, counts, project choices, Details eligibility, and the compact inline view. Archived chats are hidden by default and use their own Archived column when shown. Details shows the recorded lifetime direct child count. Names and titles can contain user text; the app prefers name, then title, then a chat ID fallback.
 
 The board uses these queue labels:
 
@@ -21,7 +21,7 @@ The board uses these queue labels:
 
 Archived takes precedence. Manual Done marks apply only without active schedules; every attached PR must be confirmed merged. A normally completed scheduled prompt returns to Scheduled regardless of PR status. After a completed human turn, attached PRs determine Done or Waiting for ordinary chats, and Scheduled or Waiting for actively scheduled chats. A manual acknowledgement returns an idle scheduled human turn to Scheduled. Active schedules remain visible as a badge even when the chat is Running or Waiting. After ordinary input, a completed scheduled chat goes to Waiting. The app reads active heartbeat links from `automations/*/automation.toml` and the latest first input from `thread_items`. It checks the observed `<heartbeat><automation_id>` wrapper; this internal format can change. Missing or unrecognized input markers use Waiting rather than guessing Scheduled. Schedule read errors appear as a warning. Paused schedules do not give an active schedule badge. Cron run history is not treated as an active heartbeat chat.
 
-**Mark Done** changes only `~/.agents/taskchef-next/done.json`, using a lock and atomic write. The mark is bound to the current turn ID, so a new turn resets it. There is no Reopen button; send a new prompt in Codex to start another turn. Archived, in-progress, and actively scheduled chats cannot be marked Done from this app. PR-linked chats require confirmed merge status before a Done drop is allowed. Codex databases, rollout files, and dispatcher task reports are never modified. An unreadable or invalid Done state file produces a separate local-state error and blocks Done changes; the app preserves the file and does not call it a Codex database failure. The inferred input source and display-formatted request are returned to the app; original recorded input is not modified. See [the research note](taskchef-next-status-research.md) for the optional Luna judgment route.
+**Mark Done** changes only `~/.agents/taskchef/done.json`, using a lock and atomic write. The mark is bound to the current turn ID, so a new turn resets it. There is no Reopen button; send a new prompt in Codex to start another turn. Archived, in-progress, and actively scheduled chats cannot be marked Done from this app. PR-linked chats require confirmed merge status before a Done drop is allowed. Codex databases, rollout files, and dispatcher task reports are never modified. An unreadable or invalid Done state file produces a separate local-state error and blocks Done changes; the app preserves the file and does not call it a Codex database failure. The inferred input source and display-formatted request are returned to the app; original recorded input is not modified. See [the research note](taskchef-next-status-research.md) for the optional Luna judgment route.
 
 Both databases and the expected tables must be available. Missing or incompatible databases, or failed queries, produce a fatal app error and clear the visible inventory. Rollout files never replace database inventory or status. The selected-chat detail may optionally read a bounded head and tail of the JSONL file at its database `rollout_path` for message counts and byte coverage. The path stays server-side. This detail never changes the database-derived status. If the path or file is absent or cannot be parsed, database metadata remains available. The board returns bounded latest-turn request and response excerpts for cards. Details returns the full recorded request and response for that turn, not the whole conversation. All reads are local and read-only.
 
@@ -367,7 +367,7 @@ a marketplace does not automatically move their installed plugin identity.
 
 ## Usage analytics
 
-![Usage analytics with sample data](images/usage-analytics.jpg)
+![Usage analytics with sample data](images/usage-project-tokens.png)
 
 The Board/Usage selector sits beside the logo in the navbar, separated from
 Board filters by a divider. It opens an on-demand historical usage view. Ranges are
@@ -376,7 +376,15 @@ Last month (the full previous calendar month). The default is 30 days; the
 selected range is remembered locally when Usage is reopened.
 There is no custom range. Dates use the view's local timezone, including DST.
 Range changes and reopening Usage query one shared history snapshot without
-rescanning logs. The snapshot is scoped by CLI/exec visibility, independently of
+rescanning logs. The combined snapshot is also saved atomically with private file
+permissions under `~/.agents/taskchef/cache/usage-history/`, scoped by Codex home
+and CLI/exec visibility. It contains the fields needed for charts, including
+weekly readings, and no message content or per-file parsing records. After an
+MCP server restart, the first Usage request loads a compatible disk snapshot
+and returns saved charts before refreshing history in the background. Range and
+timezone changes share that refresh. A missing, damaged, or incompatible snapshot
+falls back to a normal scan. A failed background refresh retains the last good
+snapshot, shows a Retry action, and never overwrites it with a failed result. The snapshot is scoped by CLI/exec visibility, independently of
 range or timezone. After one minute it refreshes in the background while cached
 charts remain visible. Refresh explicitly rebuilds it, reusing existing per-file
 metadata and incremental parsing caches. Unchanged files retain parsed records
@@ -387,14 +395,31 @@ metadata changes; transient I/O failures retry while retaining healthy sources.
 Rescan explicitly reparses available files and refreshes the inventory, while
 retaining known history for missing sources. Board polling never starts a history scan.
 
-The combined chart uses cost bars on the left axis and a token line on the
-right. Today's cost bars have a lighter fill and dashed borders in both charts;
-the token segment leading into today is dashed too. Finished days, including
-the last day of Last month, stay solid. The project chart uses stacked cost bars for the period's top five
-projects plus Other. Select a legend entry or a Top 10 row to isolate that
-project in the project chart; All projects restores the stack. Hovering or
-focusing a legend entry highlights its bars and dims other project colors. Totals, the
-combined chart, and rankings always describe the full selected period.
+The combined Tokens and cost chart uses cost bars on the left axis and a token
+line on the right. Bars emphasize daily spending; the line shows activity changes.
+Today's cost bars have a lighter fill and dashed borders; token segments leading
+into today are dashed too. Finished days stay solid.
+Tokens and cost by project shows stacked cost bars followed by a stacked token
+area chart. Both use the period's top ten projects by estimated cost plus Other,
+with matching colors. Select a legend entry or a Top 10 row to isolate that
+project in both charts; All projects restores the stacks. Hovering or focusing
+a legend entry highlights that project in both charts. Hover or focus a day in
+the token chart to inspect exact project tokens and cost. Totals, the combined
+chart, and rankings always describe the full selected period.
+
+Weekly limits occupies one third of the summary row beside Recorded tokens and
+Estimated cost. Narrow views stack these cards. Its heading shows the latest
+recorded Codex percentage left and the next reset in the viewer's timezone.
+The latest reading is independent of the chart's selected historical period;
+a reading whose reset has passed is unavailable until a new observation arrives.
+Only the main Codex bucket appears; model-specific limits are excluded. The
+compact chart uses the last observation per local day and connects observations
+across missing days. Known resets add an explicit refill jump. Connecting lines
+interpolate between recorded points; they are not additional measurements.
+Codex writes service-provided seven-day primary or secondary allowance windows
+into local rollout token-count events, including events without token counters.
+TaskChef reads these logs; it does not poll the service for current allowance.
+Root-chat CLI/exec visibility controls which logs supply observations.
 
 Archived chats and descendant usage are included. CLI/exec visibility settings
 still apply to root chats. Descendants are counted once under their root chat's

package/docs/taskchef-next-storage.md

@@ -10,6 +10,61 @@ The storage diagram groups tables inside their database files. The separate exam
 
 ![Current reply lookup after a revert](diagrams/taskchef-next-reply-lookup.drawio.png)
 
+## Native state directory and migration
+
+TaskChef and TaskChef Dev share `~/.agents/taskchef/` for settings, Done marks,
+GitHub state, notifications, delegation memory and caches. The Dev plugin keeps
+its separate `taskchef-next` identity. Storage naming does not change plugin
+registration or merge the released and Dev installations.
+
+Before migration, upgraded packages can still use an existing native
+`~/.agents/taskchef-next/` directory. They never treat retired dispatcher files
+at `~/.agents/taskchef/` as native state. Two independent native directories,
+unexpected links, or an unfinished migration lock stop startup with an error.
+The runtime does not move user data automatically.
+
+To migrate on macOS or Linux with `lsof` available:
+
+1. Install the compatible released and Dev packages first. Retain the existing
+   published release until the normal release workflow produces the new one.
+2. Resolve any saved Codex project whose root is `~/.agents/taskchef` through
+   Codex's project controls. Point the retired project at its archive destination
+   or remove the obsolete root while preserving its chats. Do not edit Codex
+   databases. Otherwise that project would point at native state after the move.
+3. Quit Codex and all other TaskChef clients. Stop any old dashboard using the
+   retired directory through its normal controls. From an external terminal,
+   run the following inside the updated TaskChef package:
+
+   ```sh
+   node scripts/migrate-taskchef-state.js
+   ```
+
+4. Restart Codex and verify settings, Done marks, GitHub connection,
+   notifications and usage. Confirm both TaskChef plugins remain enabled.
+
+The command first refuses active TaskChef MCP processes and any process with
+its working directory in the stores. If process inspection fails, it stops.
+It moves the retired dispatcher directory intact to `~/.agents/taskchef-old`.
+An existing archive is never overwritten or merged with a retired dispatcher.
+The obsolete `~/.codex/taskchef` registry moves separately to
+`~/.agents/taskchef-old/codex-registry`; registry collisions or unknown top-level
+entries stop the move. Active Codex databases, sessions and chat history are
+outside this command's scope.
+
+The full native directory then moves to `~/.agents/taskchef`, retaining file
+contents and permissions, including historical usage counters. A relative
+`taskchef-next -> taskchef` compatibility link lets older installed packages
+reach the same files. It is not a second state store. Keep the link while any
+older package or skill still refers to it. Current packages resolve the canonical
+path after migration; current delegation instructions use that path too.
+
+Repeating the command accepts a completed move or resumes after an individual
+rename. It never merges two native directories or deletes history. An interrupted
+process can leave `~/.agents/.taskchef-storage-migration`: inspect the directory
+layout, confirm no migration or writer is running, then remove only that empty
+lock directory with `rmdir` before retrying. Compare inventories before and after
+migration; keep the archive for historical reference.
+
 ## One chat, two possible IDs
 
 Suppose chat **C** has a turn **T**:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskchef",
-  "version": "9.5.0",
+  "version": "9.7.0",
   "description": "A native Codex dashboard for chats, usage, pull requests, and schedules.",
   "license": "Apache-2.0",
   "author": "Favo Yang",
@@ -31,7 +31,8 @@
     "docs/diagrams/taskchef-next-storage.drawio",
     "docs/diagrams/taskchef-next-storage.drawio.png",
     "docs/diagrams/taskchef-next-reply-lookup.drawio",
-    "docs/diagrams/taskchef-next-reply-lookup.drawio.png"
+    "docs/diagrams/taskchef-next-reply-lookup.drawio.png",
+    "scripts/migrate-taskchef-state.js"
   ],
   "engines": {
     "node": "^22.18.0 || >=23.2.0"

package/scripts/migrate-taskchef-state.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { lstat, mkdir, readdir, readFile, rename, rmdir, symlink, realpath } from "node:fs/promises";
+import { dirname, join, relative, isAbsolute, sep, resolve } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { hasDispatcherState, isNativeStateDir, taskChefStatePaths, taskChefStateDir } from "../src/taskchef-state.js";
+
+const run = promisify(execFile);
+const info = path => lstat(path).catch(error => { if (error.code === "ENOENT") return null; throw error; });
+const inside = (root, path) => { const child = relative(root, path); return child === "" || (!isAbsolute(child) && child !== ".." && !child.startsWith(`..${sep}`)); };
+
+// lsof supplies cwd even when the MCP command uses ./mcp/server.js. Inspect
+// command arguments too, so a test or build in a TaskChef checkout is harmless.
+export async function assertNoStateWriters(paths, runCommand = run) {
+  let output, commands;
+  try {
+    ({ stdout: output } = await runCommand("lsof", ["-n", "-a", "-u", String(process.getuid()), "-d", "cwd", "-Fpn"], { maxBuffer: 8 * 1024 * 1024 }));
+    const { stdout } = await runCommand("ps", ["-axo", "pid=,command="], { maxBuffer: 8 * 1024 * 1024 });
+    commands = new Map(stdout.split("\n").flatMap(line => {
+      const match = /^\s*(\d+)\s+(.+)$/.exec(line);
+      return match ? [[Number(match[1]), match[2]]] : [];
+    }));
+  } catch (error) { throw new Error(`Cannot establish that TaskChef writers are stopped (lsof/ps): ${error.message}`); }
+  const identities = new Map();
+  async function isTaskChef(root) {
+    if (!identities.has(root)) {
+      let name;
+      try { name = JSON.parse(await readFile(join(root, ".codex-plugin/plugin.json"), "utf8")).name; } catch { /* Unrelated process. */ }
+      identities.set(root, ["taskchef", "taskchef-next"].includes(name));
+    }
+    return identities.get(root);
+  }
+  let pid;
+  const blocked = [];
+  for (const line of output.split("\n")) {
+    if (line.startsWith("p")) pid = Number(line.slice(1));
+    if (!line.startsWith("n") || !pid || pid === process.pid) continue;
+    const cwd = line.slice(1);
+    if ([paths.current, paths.previous, paths.archive, paths.registry].some(root => inside(root, cwd))) { blocked.push(pid); continue; }
+    const command = commands.get(pid) ?? "";
+    if (/(?:^|[\s"'])(?:\.\/)?mcp\/server\.js(?:[\s"']|$)/.test(command) && await isTaskChef(cwd)) { blocked.push(pid); continue; }
+    // ps does not escape spaces consistently. Try each absolute suffix ending
+    // at the server filename and confirm the package's manifest on disk.
+    for (const match of command.matchAll(/\/mcp\/server\.js(?=[\s"']|$)/g)) {
+      const end = match.index + match[0].length;
+      for (let start = command.indexOf("/"); start >= 0 && start <= match.index; start = command.indexOf("/", start + 1)) {
+        if (await isTaskChef(dirname(dirname(command.slice(start, end))))) { blocked.push(pid); break; }
+      }
+    }
+  }
+  if (blocked.length) throw new Error(`Stop TaskChef clients and processes using its storage before migrating (PIDs: ${[...new Set(blocked)].join(", ")}). Quit Codex; stop any listed legacy dashboard through its normal controls. Nothing was moved.`);
+}
+
+async function assertNative(directory) {
+  if (!isNativeStateDir(directory)) {
+    throw new Error(`Unrecognized native state at ${directory}; inspect it before migrating.`);
+  }
+}
+
+export async function migrateTaskChefState(home = homedir(), { assertStopped = assertNoStateWriters } = {}) {
+  const paths = taskChefStatePaths(home);
+  await mkdir(paths.agents, { recursive: true, mode: 0o700 });
+  // A leftover lock requires inspection, never automatic deletion or a blind retry.
+  await mkdir(paths.lock, { mode: 0o700 });
+  try {
+    await assertStopped(paths);
+    const current = await info(paths.current), previous = await info(paths.previous), archive = await info(paths.archive);
+    if (current && (!current.isDirectory() || current.isSymbolicLink())) throw new Error(`Refusing unexpected destination ${paths.current}.`);
+    if (archive && (!archive.isDirectory() || archive.isSymbolicLink())) throw new Error(`Refusing unexpected archive ${paths.archive}.`);
+    const retired = current && hasDispatcherState(paths.current);
+    if (retired && archive) throw new Error(`Archive ${paths.archive} already exists; nothing will be overwritten or merged.`);
+    if (previous?.isSymbolicLink()) {
+      if (!current || retired || await realpath(paths.previous) !== await realpath(paths.current)) throw new Error("Unexpected taskchef-next link; inspect it before migrating.");
+    } else if (previous) {
+      if (!previous.isDirectory()) throw new Error("taskchef-next must be a directory.");
+      await assertNative(paths.previous);
+      if (current && !retired) throw new Error("Both native state directories exist. Inspect and reconcile them before migrating; no files were merged.");
+    } else if (!current || retired) throw new Error("No current native state was found; nothing was moved.");
+    if (current && !retired) await assertNative(paths.current);
+
+    // The obsolete registry is independent of Codex's active SQLite databases.
+    const registry = paths.registry, registryInfo = await info(registry);
+    const registryArchive = join(paths.archive, "codex-registry");
+    if (registryInfo) {
+      const futureArchive = join(retired ? paths.current : paths.archive, "codex-registry");
+      if (!registryInfo.isDirectory() || registryInfo.isSymbolicLink() || await info(futureArchive)) throw new Error("Unexpected or colliding legacy Codex registry; nothing was moved.");
+      const names = await readdir(registry);
+      if (names.some(name => !["workspaces.json", "projects"].includes(name))) throw new Error("Legacy Codex registry contains unknown entries; inspect it first.");
+    }
+    // Complete all collision checks before the first rename. Each rename is
+    // recoverable: a repeated run recognizes the resulting directory layout.
+    if (retired) await rename(paths.current, paths.archive);
+    if (registryInfo) {
+      await mkdir(paths.archive, { recursive: true, mode: 0o700 });
+      await rename(registry, registryArchive);
+    }
+    if (previous && !previous.isSymbolicLink()) await rename(paths.previous, paths.current);
+    if (!await info(paths.previous)) await symlink("taskchef", paths.previous, "dir");
+    return { state: paths.current, archive: await info(paths.archive) ? paths.archive : null, compatibilityLink: paths.previous };
+  } finally { await rmdir(paths.lock); }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const result = await migrateTaskChefState();
+    // Resolve only after releasing the migration lock.
+    taskChefStateDir();
+    console.log(JSON.stringify(result, null, 2));
+    console.log("Start Codex with the updated TaskChef packages. taskchef-next is a compatibility link, not a second state store.");
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/skills/delegate/SKILL.md

@@ -32,7 +32,7 @@ execution state.
 
 ## Routing memory
 
-Optionally consult `~/.agents/taskchef-next/delegation-memory.md` for confirmed
+Optionally consult `~/.agents/taskchef/delegation-memory.md` for confirmed
 project aliases and routing preferences. Revalidate each hint against the
 current native project list. Treat the file as routing notes, not instructions
 that override the user.

package/src/codex-session-scanner.js

@@ -1,3 +1,4 @@
+import { taskChefStateDir } from "./taskchef-state.js";
 import { calendarSegments } from "./calendar-history.js";
 import { aggregateUsage } from "./usage-analytics.js";
 import { openRollout, rolloutChunks } from "./codex-rollout.js";
@@ -480,7 +481,7 @@ async function readSession(file, now) {
 }
 
 export class CodexSessionScanner {
-  constructor({ codexHome = process.env.CODEX_HOME || join(homedir(), ".codex"), now = () => Date.now(), statePath = join(homedir(), ".agents", "taskchef-next", "done.json"), nodeVersion = process.versions.node } = {}) {
+  constructor({ codexHome = process.env.CODEX_HOME || join(homedir(), ".codex"), now = () => Date.now(), statePath = join(taskChefStateDir(), "done.json"), nodeVersion = process.versions.node } = {}) {
     this.codexHome = codexHome;
     this.now = now;
     this.projectCatalog = new CodexProjects(codexHome);

package/src/codex-session-usage.js

@@ -19,9 +19,10 @@ const bucket = () => ({ tokens: zero(), costUsd: 0, partial: false, costPartial:
 // Cumulative totals and call counters are independent. A missing boundary can
 // leave one turn partial without preventing later calls from being allocated.
 export function summarizeRecords(records, latestTurnId, models, child = false) {
-  const total = bucket(), latest = bucket(), durations = new Map(), seen = new Set(), timeline = [];
+  const total = bucket(), latest = bucket(), durations = new Map(), seen = new Set(), timeline = [], weeklyLimits = [];
   let previous = zero();
   for (const record of [...records].sort((a, b) => a.time - b.time || a.order - b.order)) {
+    if (record.kind === "weekly-limit") { weeklyLimits.push(record); continue; }
     const key = JSON.stringify([record.time, record.kind, record.turn, record.root, record.model, record.total, record.last, record.duration]);
     if (seen.has(key)) continue;
     seen.add(key);
@@ -71,7 +72,7 @@ export function summarizeRecords(records, latestTurnId, models, child = false) {
       latest.partial = latest.costPartial = true;
     }
   }
-  return { total, latest, durations, timeline };
+  return { total, latest, durations, timeline, weeklyLimits };
 }
 
 async function inventory(root, paths = []) {
@@ -138,7 +139,7 @@ export class CodexSessionUsage {
     if (!saved && cachePath) {
       try {
         const value = JSON.parse(await readFile(cachePath, "utf8"));
-        if ([1, 2, 3].includes(value.version) && validResult(value.result) && (value.version === 1 || (Array.isArray(value.result.timeline) && value.result.timeline.every(sample => Number.isFinite(sample.time) && usage(sample.tokens) && Number.isFinite(sample.costUsd) && sample.costUsd >= 0 && sample.samples === 1 && typeof sample.partial === "boolean" && typeof sample.costPartial === "boolean")))) saved = value;
+        if ([1, 2, 3, 4].includes(value.version) && validResult(value.result) && (value.version === 1 || (Array.isArray(value.result.timeline) && value.result.timeline.every(sample => Number.isFinite(sample.time) && usage(sample.tokens) && Number.isFinite(sample.costUsd) && sample.costUsd >= 0 && sample.samples === 1 && typeof sample.partial === "boolean" && typeof sample.costPartial === "boolean")))) saved = value;
       } catch { /* An absent or damaged cache is rebuilt from source records. */ }
     }
     const sourceKeys = (items) => items.flatMap(([sessionId, versions]) => versions
@@ -164,7 +165,7 @@ export class CodexSessionUsage {
       })) knownSources = [];
     } catch { knownSources = []; /* No prior valid source coverage is available. */ }
     const missingSources = knownSources.filter(key => !currentSources.has(key));
-    if (!rescan && !saved?.retryRead && saved?.version === 3 && typeof saved.result.analyticsPartial === "boolean" && saved.recordSources && saved.sourceSignature === sourceSignature) { this.results.set(resultKey, saved); return saved.result; }
+    if (!rescan && !saved?.retryRead && saved?.version === 4 && typeof saved.result.analyticsPartial === "boolean" && saved.recordSources && saved.sourceSignature === sourceSignature) { this.results.set(resultKey, saved); return saved.result; }
     const availablePaths = new Set(sources.flatMap(([, versions]) => versions.filter(version => version.length > 2).map(version => version[0])));
     let retryRead = false;
     const parsed = [];
@@ -183,7 +184,7 @@ export class CodexSessionUsage {
           if (!availablePaths.has(path)) throw new Error("Rollout is missing.");
           const previous = saved?.sourceFiles?.[sourceKey];
           let file;
-          if (!rescan && previous && JSON.stringify(previous.stamp) === JSON.stringify(stamp) && Array.isArray(saved.recordSources?.[sourceKey])) {
+          if (!rescan && saved?.version === 4 && previous && JSON.stringify(previous.stamp) === JSON.stringify(stamp) && Array.isArray(saved.recordSources?.[sourceKey])) {
             file = { records: saved.recordSources[sourceKey], partial: previous.partial };
           } else {
             if (rescan) this.files.delete(path);
@@ -208,10 +209,10 @@ export class CodexSessionUsage {
     const retainedSources = saved?.recordSources && typeof saved.recordSources === "object" ? saved.recordSources : {};
     for (const key of missingSources) {
       const rows = retainedSources[key];
-      if (Array.isArray(rows) && rows.every(row => row && Number.isFinite(row.time) && ["usage", "duration", "issue"].includes(row.kind))) recordSources[key] = rows;
+      if (Array.isArray(rows) && rows.every(row => row && Number.isFinite(row.time) && ["usage", "duration", "issue", "weekly-limit"].includes(row.kind))) recordSources[key] = rows;
     }
     const result = { latest: bucket(), total: bucket(), subagents: sessions.length - 1, pricingDate: pricing.date,
-      durationMs: 0, durationTurns: 0, timeline: [], analyticsPartial: inventoryFailed, partial: inventoryFailed };
+      durationMs: 0, durationTurns: 0, timeline: [], weeklyLimits: [], analyticsPartial: inventoryFailed, partial: inventoryFailed };
     for (const { session, records, failed, latestFailed, timePartial } of parsed) {
       const summary = summarizeRecords(records, latestTurnId, pricing.models, session.id !== id);
       const retained = missingSources.filter(key => JSON.parse(key)[0] === session.id).flatMap(key => recordSources[key] ?? []);
@@ -226,9 +227,11 @@ export class CodexSessionUsage {
         summary.latest.costPartial ||= missing.latest.samples > 0 || missing.latest.costPartial;
         summary.durations = combined.durations;
         summary.timeline = combined.timeline;
+        summary.weeklyLimits = combined.weeklyLimits;
       }
       result.analyticsPartial ||= timePartial || summary.total.tokens.total_tokens !== summary.timeline.reduce((sum, sample) => sum + sample.tokens.total_tokens, 0);
       result.timeline.push(...summary.timeline);
+      result.weeklyLimits.push(...summary.weeklyLimits);
       for (const key of ["total", "latest"]) {
         add(result[key].tokens, summary[key].tokens);
         result[key].costUsd += summary[key].costUsd;
@@ -267,7 +270,7 @@ export class CodexSessionUsage {
       }
       if (missingSources.some(key => JSON.parse(key)[0] === id)) result.partial = true;
     }
-    const entry = { version: 3, sourceSignature, result, recordSources, sourceFiles, retryRead, knownSources: [...new Set([...knownSources, ...currentSources])] };
+    const entry = { version: 4, sourceSignature, result, recordSources, sourceFiles, retryRead, knownSources: [...new Set([...knownSources, ...currentSources])] };
     // Keep successful sources even if another source failed. Retry failures on
     // the next read without reparsing all healthy historical files.
     this.results.set(resultKey, entry);
@@ -341,6 +344,16 @@ export class CodexSessionUsage {
     if (p.type === "task_started") { file.turn = p.turn_id; file.root = p.root_turn_id ?? file.root; }
     const time = Date.parse(row.timestamp);
     if (!Number.isFinite(time)) { file.partial = true; return; }
+    if (p.type === "token_count" && p.rate_limits) {
+      const limits = p.rate_limits;
+      for (const window of [limits.primary, limits.secondary]) {
+        if (window?.window_minutes !== 10080 || !Number.isFinite(window.used_percent)
+          || window.used_percent < 0 || window.used_percent > 100 || !Number.isSafeInteger(window.resets_at) || window.resets_at * 1000 <= time) continue;
+        file.records.push({ kind: "weekly-limit", time, id: typeof limits.limit_id === "string" ? limits.limit_id : "codex",
+          name: typeof limits.limit_name === "string" ? limits.limit_name : null,
+          remainingPercent: 100 - window.used_percent, resetsAt: window.resets_at * 1000 });
+      }
+    }
     if (p.type === "token_count" && p.info) file.records.push({ kind: "usage", time, order: file.offset,
       turn: file.turn, root: file.root, model: file.model, total: p.info.total_token_usage, last: p.info.last_token_usage });
     if (["task_complete", "turn_aborted"].includes(p.type)) {