usagemax 0.3.0 → 0.3.2

package/README.md

@@ -78,21 +78,31 @@ connector. UsageMax never invents usage that the source did not retain.
 
 ## Privacy, correctness, and load
 
-- The sync payload contains authoritative aggregate token counts,
+Interrupted uploads resume with `bunx usagemax sync`. Server upload runs expire
+after 30 idle days. If the server reports an expired run, use `sync --restart`:
+this preserves the last committed checkpoint and performs a fresh full scan.
+It never automatically replays an old authoritative deletion against newer data.
+
+- The sync payload contains aggregate token counts,
   model/provider names, costs, source names, dates, coverage state, and opaque
   SHA-256 session identities.
 - It does not upload prompts, completions, source code, file contents, project
   paths, or provider credentials.
 - Sync is one-shot. There is no resident scanner or high-frequency polling loop.
-- A metadata inventory exits without parsing logs or using the network when
-  nothing changed.
+- A successful previous parse with a complete, unchanged metadata inventory skips
+  parsing and uploading again that day. Inventory stability is independent of
+  deletion authority; a no-change result retains the previous partial coverage
+  label. New sources, date rollover, explicit full/archive requests and weekly
+  reconciliation still trigger the appropriate scan.
 - Normal changed syncs parse today or today plus yesterday. A bounded weekly
   full reconciliation catches restored files, parser changes, and older logs.
-- Full history means all retained local history from 2024 onward. UsageMax
-  publishes complete source/day partitions, so decreased or removed local rows
-  correct the server-owned contribution instead of being silently retained.
-  Deleted or
-  never-persisted usage requires a provider export; no local tool can reconstruct it.
+- Full history scans retained local history from 2024 onward. Inventory success
+  does not prove every file parsed. Until the parser certifies source/day coverage,
+  uploads are marked partial and any row with a decreasing counter retains its
+  entire previous vector. This includes explicit zeros and missing sources.
+  Older checkpoints survive incremental windows. Authoritative corrections remain
+  supported by the planner but are not claimed by this parser integration.
+  Deleted or never-persisted usage requires a provider export.
 - Source totals that cannot be assigned to a model are retained as
   `unattributed` rather than silently discarded.
 - The collector key is written with user-only permissions where the operating
@@ -103,7 +113,8 @@ connector. UsageMax never invents usage that the source did not retain.
   its hash and applies device binding, replay checks, payload caps, and quotas.
 - A private random installation ID survives collector rotation, relinking, and
   display-name changes. It is not a hardware fingerprint; the server stores only
-  its SHA-256 hash. Concurrent and repeated syncs are idempotent.
+  its SHA-256 hash. A local config lock prevents overlapping commands from
+  overwriting pending runs; server receipts make repeated uploads idempotent.
 - The server, not the local checkpoint, owns the accounting baseline. A lost
   response or interrupted run can be retried without adding the same partition twice.
 - Do not point two different installations at the same copied or network-mounted
@@ -113,5 +124,36 @@ connector. UsageMax never invents usage that the source did not retain.
 Use `USAGEMAX_CONFIG_DIR` to select another config directory. Development and
 self-hosted installations may set `USAGEMAX_LINK_ENDPOINT` before linking.
 
+## Interrupted uploads and protocol 0.3.1
+
+Before uploading, the CLI saves the exact run, ordered request payloads and next
+checkpoint in the private config. `sync` resumes this journal before scanning new
+data. Local snapshots advance only after completion is acknowledged. A resumed
+command finishes the saved scan; run `sync` again to collect subsequent changes.
+`sync --dry-run` reports pending work without uploading. Do not delete config.json
+to retry a failed upload. A successful relink or unlink replaces/removes the local
+journal along with its credential.
+
+Network failures, malformed success responses, HTTP 429 and 5xx get at most five
+attempts per request with exponential jitter. Retry-After seconds and HTTP dates
+are honored up to 60 seconds; longer waits stop with an instruction to retry later.
+Only completion's `snapshot_run_incomplete` HTTP 409 is retried, because server
+cleanup can still be pending. Authentication, validation and other conflicts fail
+with an actionable message and retain the journal. JSON `accepted` is null for
+uploads because lost responses/replays cannot reliably reconstruct that count;
+`changedRows` is the local planned count, not a server accounting receipt.
+
+Each sorted source/day is sent as ordered chunks of at most 100 rows. Each has a
+unique partitionId, zero-based chunkIndex and shared chunkCount. The payload hash
+covers `{source, day, complete, pricingVersion, chunkIndex, chunkCount, rows}` in
+that order. `partitionCount` counts transmitted chunks. The server must accept
+this protocol, receipt replays, and finish omitted-row cleanup before completing
+an authoritative run.
+
+An abrupt process kill can leave `collector.lock` in the config directory. The
+next command reports the owner PID and exact path. Confirm that process has exited
+before removing only that lock file, then rerun sync. Never remove an active lock
+or the saved config to recover. Normal completion and handled failures release it.
+
 See the [collector coverage audit](../../docs/collector-coverage-audit.md) for
 the full support matrix and known boundaries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usagemax",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Link local coding-agent usage to your UsageMax profile",
   "license": "MIT",
   "author": "UsageMax",
@@ -23,6 +23,8 @@
     "src/core.js",
     "src/installation.js",
     "src/sources.js",
+    "src/transport.js",
+    "src/resume.js",
     "README.md",
     "LICENSE"
   ],

package/src/cli.js

@@ -10,18 +10,19 @@ import process from "node:process";
 import { promisify } from "node:util";
 
 import { prepareArchiveRecovery } from "./archives.js";
-import { buildSessionPlan, buildSnapshotPlan, normalizeLinkCode, sourceSummary, validHttpsUrl } from "./core.js";
+import { buildSessionPlan, buildSnapshotPlan, normalizeLinkCode, reportDateArgs, scanPolicy, sourceSummary, validHttpsUrl } from "./core.js";
 import { stableInstallationId } from "./installation.js";
+import { requestSnapshot } from "./transport.js";
+import { resumeUpload, restartExpiredUpload, withConfigLock } from "./resume.js";
 import { CCUSAGE_VERSION, ccusageEnvironment, ccusageHome, discoverProviderArchives, SOURCE_INVENTORY_VERSION, sourceInventory, SUPPORTED_SOURCES } from "./sources.js";
 
 const require = createRequire(import.meta.url);
 const executeFile = promisify(execFile);
-const VERSION = "0.3.0";
+const VERSION = "0.3.2";
 const PUBLIC_API_ORIGIN = "https://usagemax.com/api";
 const DEFAULT_LINK_ENDPOINT = `${PUBLIC_API_ORIGIN}/v1/devices/link`;
 const CONFIG_FILE = "config.json";
 const MAX_REPORT_BYTES = 100 * 1024 * 1024;
-const FULL_RECONCILE_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000;
 
 function configDirectory() {
   if (process.env.USAGEMAX_CONFIG_DIR) return process.env.USAGEMAX_CONFIG_DIR;
@@ -103,7 +104,7 @@ function help() {
   process.stdout.write("  usagemax                         Sync changed local usage\n");
   process.stdout.write("  usagemax link <one-use-code>     Link and sync this computer\n");
   process.stdout.write("           [--no-sync] [--name <name>]\n");
-  process.stdout.write("  usagemax sync [--full] [--archives] [--dry-run] [--explain] [--json]\n");
+  process.stdout.write("  usagemax sync [--full] [--archives] [--restart] [--dry-run] [--explain] [--json]\n");
   process.stdout.write("                                  Reconcile once; --archives performs one-time recovery\n");
   process.stdout.write("  usagemax status                  Show local link status\n");
   process.stdout.write("  usagemax doctor [--deep] [--json]\n");
@@ -122,12 +123,7 @@ async function ccusageJson(config, { full = false, env } = {}) {
   // Reconcile yesterday once after the UTC date changes. All other incremental
   // scans parse only today; a metadata fingerprint avoids invoking ccusage when
   // no supported local source changed at all.
-  if (full) {
-    args.push("--since", "2024-01-01", "--until", new Date().toISOString().slice(0, 10));
-  } else if (config?.lastSyncAt) {
-    const today = new Date().toISOString().slice(0, 10);
-    args.push("--last", config.lastReconciledDay === today ? "1" : "2");
-  }
+  args.push(...reportDateArgs(config, { full }));
   const { stdout } = await executeFile(process.execPath, args, {
     encoding: "utf8",
     maxBuffer: MAX_REPORT_BYTES,
@@ -142,22 +138,7 @@ function snapshotEndpoint(config) {
 }
 
 async function snapshotRequest(config, operation, payload, timeout = 30_000) {
-  const response = await fetch(snapshotEndpoint(config), {
-    method: "POST",
-    headers: {
-      authorization: `Bearer ${config.token}`,
-      "content-type": "application/json",
-      "x-usagemax-device-id": config.deviceId,
-    },
-    body: JSON.stringify({ operation, ...payload }),
-    signal: AbortSignal.timeout(timeout),
-  });
-  const body = await response.json().catch(() => ({}));
-  if (!response.ok) {
-    if (body?.error === "unauthorized") throw new Error("This collector key is no longer valid. Link the computer again.");
-    throw new Error(`UsageMax rejected ${operation} (${response.status}${body?.error ? `: ${body.error}` : ""}).`);
-  }
-  return body;
+  return requestSnapshot(snapshotEndpoint(config), config, operation, payload, { timeout });
 }
 
 function newerVersion(recommended) {
@@ -243,32 +224,44 @@ async function syncPrepared(args, suppliedConfig, recovery) {
   const dryRun = args.includes("--dry-run");
   const explain = args.includes("--explain");
   const json = args.includes("--json");
+  if (args.includes("--restart") && !dryRun) {
+    restartExpiredUpload(config);
+    await writeConfig(config);
+  }
+  if (config.pendingSync) {
+    if (dryRun) {
+      const result = { ...config.pendingSync.result, dryRun: true, pendingRunId: config.pendingSync.runId };
+      process.stdout.write(json ? `${JSON.stringify(result)}\n` : `Dry run: saved run ${config.pendingSync.runId} awaits resume; no upload.\n`);
+      return result;
+    }
+    const result = await resumeUpload(config, { save: writeConfig, request: snapshotRequest, warn: warnVersion });
+    process.stdout.write(json ? `${JSON.stringify(result)}\n` : "Resumed and completed the saved sync. Run sync again to scan newer local changes.\n");
+    return result;
+  }
   const inventory = await sourceInventory({ env: recovery.env, home: ccusageHome(recovery.env) });
   const today = new Date().toISOString().slice(0, 10);
   const knownSources = Array.isArray(config.knownSources) ? config.knownSources : [];
-  const foundNewSource = inventory.sources.some((source) => !knownSources.includes(source));
-  const lastFullSync = Date.parse(config.lastFullSyncAt || "");
-  const fullDue = config.snapshotProtocolVersion !== 2
-    || config.sourceInventoryVersion !== SOURCE_INVENTORY_VERSION
-    || !Number.isFinite(lastFullSync)
-    || Date.now() - lastFullSync >= FULL_RECONCILE_INTERVAL_MS
-    || foundNewSource;
-  const full = requestedFull || requestedArchives || fullDue;
-  if (!full && inventory.complete && config.lastSyncComplete && config.lastReconciledDay === today && config.sourceFingerprint === inventory.fingerprint) {
-    const result = { accepted: 0, changedRows: 0, sessions: 0, sources: inventory.sources, corrections: 0, scanned: false, full: false, coverage: inventory.complete ? "complete" : "partial" };
+  const { bootstrap, full, skip, inventoryStable } = scanPolicy(config, inventory, {
+    today, now: Date.now(), inventoryVersion: SOURCE_INVENTORY_VERSION, requestedFull, requestedArchives,
+  });
+  if (skip) {
+    const result = { accepted: 0, changedRows: 0, sessions: 0, sources: inventory.sources, corrections: 0, scanned: false, full: false, coverage: config.lastCoverage || "partial" };
     if (json) process.stdout.write(`${JSON.stringify(result)}\n`);
     else process.stdout.write("Already up to date. Local usage files have not changed; no logs were parsed or uploaded.\n");
     return;
   }
   const report = await ccusageJson(config, { env: recovery.env, full });
-  const legacySnapshotBootstrap = config.snapshotProtocolVersion !== 2
+  // ccusage v20 exposes aggregates, not proof that every discovered file was
+  // parsed. Inventory success alone cannot authorize destructive corrections.
+  const authoritative = false;
+  const legacySnapshotBootstrap = bootstrap
     && Object.keys(config.snapshots || {}).length > 0;
   const runId = randomUUID();
   const revision = Date.now();
   const pricingVersion = `ccusage@${CCUSAGE_VERSION}`;
   const { partitions, nextSnapshots, regressions } = buildSnapshotPlan(report, config.snapshots, {
-    bootstrap: config.snapshotProtocolVersion !== 2,
-    complete: inventory.complete,
+    bootstrap,
+    complete: authoritative,
     full,
     pricingVersion,
     revision,
@@ -280,15 +273,17 @@ async function syncPrepared(args, suppliedConfig, recovery) {
     ? report.daily.map((row) => row?.period).filter((day) => /^\d{4}-\d{2}-\d{2}$/.test(day || "")).sort()
     : [];
   const result = {
-    accepted: 0,
+    accepted: null,
     changedRows: partitions.reduce((sum, partition) => sum + partition.rows.filter((row) => JSON.stringify(row.previous) !== JSON.stringify(row.current)).length, 0),
     sessions: sessions.length,
     sources,
-    corrections: regressions.length,
+    corrections: authoritative ? regressions.length : 0,
+    protectedRegressions: authoritative ? 0 : regressions.length,
     partitions: partitions.length,
     scanned: true,
     full,
-    coverage: inventory.complete && !inventory.truncated && inventory.errors === 0 ? "complete" : "partial",
+    coverage: authoritative ? "complete" : "partial",
+    coverageReason: "Parser does not certify complete source/day coverage; decreases and deletions are protected.",
     range: { from: days[0], to: days.at(-1) },
   };
   if (requestedArchives) {
@@ -299,60 +294,52 @@ async function syncPrepared(args, suppliedConfig, recovery) {
     if (json) process.stdout.write(`${JSON.stringify({ ...result, dryRun: true })}\n`);
     else {
       process.stdout.write(`Dry run: ${partitions.length} partition(s), ${result.changedRows} changed row(s), ${sessions.length} private session identifiers, no upload.\n`);
-      if (explain) process.stdout.write(`Coverage ${result.coverage}; ${sources.length} source(s); ${days[0] || "unknown"} to ${days.at(-1) || "unknown"}; ${regressions.length} downward correction(s).\n`);
+      if (explain) process.stdout.write(`Coverage ${result.coverage}; ${sources.length} source(s); ${days[0] || "unknown"} to ${days.at(-1) || "unknown"}; ${regressions.length} protected regression(s). ${result.coverageReason}\n`);
     }
     return result;
   }
-  config.lastSyncComplete = false;
-  await writeConfig(config);
-  try {
-    const begin = await snapshotRequest(config, "begin", {
+  const requests = [{ operation: "begin", payload: {
       runId,
       mode: requestedArchives ? "archives" : full ? "full" : "incremental",
       baselineMode: legacySnapshotBootstrap ? "adopt-current" : "apply",
       sourceCount: sources.length,
       partitionCount: partitions.length,
-      inventoryComplete: inventory.complete,
+      inventoryComplete: authoritative,
       inventoryErrors: inventory.errors,
       inventoryTruncated: inventory.truncated,
       coverageStartDay: days[0],
       coverageEndDay: days.at(-1),
-    });
-    warnVersion(begin);
-    for (let offset = 0; offset < sessions.length; offset += 100) {
-      await snapshotRequest(config, "sessions", { runId, sessions: sessions.slice(offset, offset + 100) });
-    }
-    for (let offset = 0; offset < partitions.length; offset += 10) {
-      const response = await snapshotRequest(config, "partitions", { runId, partitions: partitions.slice(offset, offset + 10) }, 60_000);
-      result.accepted += Number(response.changedRows || 0);
-      if (!json && process.stderr.isTTY && partitions.length > 10) {
-        process.stderr.write(`UsageMax: uploaded ${Math.min(offset + 10, partitions.length)}/${partitions.length} history partitions\r`);
-      }
-    }
-    if (!json && process.stderr.isTTY && partitions.length > 10) process.stderr.write("\n");
-    const completed = await snapshotRequest(config, "complete", { runId });
-    warnVersion(completed);
-    config.snapshots = nextSnapshots;
-    config.snapshotProtocolVersion = 2;
-    config.lastSyncAt = new Date().toISOString();
-    config.lastReconciledDay = today;
-    config.lastSyncComplete = true;
-    config.sourceInventoryVersion = SOURCE_INVENTORY_VERSION;
-    config.knownSources = [...new Set([...knownSources, ...inventory.sources, ...sources])].sort();
-    if (inventory.complete) config.sourceFingerprint = inventory.fingerprint;
-    else delete config.sourceFingerprint;
-    if (full) config.lastFullSyncAt = config.lastSyncAt;
-    await writeConfig(config);
-  } catch (error) {
-    await snapshotRequest(config, "fail", { runId, failureCode: error instanceof Error ? error.message.slice(0, 80) : "sync_failed" }).catch(() => undefined);
-    throw error;
+    } }];
+  for (let offset = 0; offset < sessions.length; offset += 100) {
+    requests.push({ operation: "sessions", payload: { runId, sessions: sessions.slice(offset, offset + 100) } });
   }
+  for (let offset = 0; offset < partitions.length; offset += 10) {
+    requests.push({ operation: "partitions", payload: { runId, partitions: partitions.slice(offset, offset + 10) } });
+  }
+  requests.push({ operation: "complete", payload: { runId } });
+  const syncedAt = new Date().toISOString();
+  config.pendingSync = {
+    version: 1, runId, cursor: 0, requests, result,
+    checkpoint: {
+      snapshots: nextSnapshots, snapshotProtocolVersion: 2,
+      lastSyncAt: syncedAt, lastReconciledDay: today, lastSyncComplete: authoritative,
+      lastScanSucceeded: true, lastCoverage: result.coverage,
+      sourceInventoryVersion: SOURCE_INVENTORY_VERSION,
+      knownSources: [...new Set([...knownSources, ...inventory.sources, ...sources])].sort(),
+      sourceFingerprint: inventoryStable ? inventory.fingerprint : null,
+      ...(full ? { lastFullSyncAt: syncedAt } : {}),
+    },
+  };
+  config.lastSyncComplete = false;
+  await writeConfig(config);
+  await resumeUpload(config, { save: writeConfig, request: snapshotRequest, warn: warnVersion });
   if (json) process.stdout.write(`${JSON.stringify(result)}\n`);
   else {
     process.stdout.write(partitions.length || sessions.length
-      ? `Reconciled ${result.accepted} changed usage row(s) and ${sessions.length} session identifier(s) from ${sources.join(", ") || "local agents"}${full ? " across retained history" : ""}.\n`
+      ? `Completed ${partitions.length} usage chunk(s) and ${sessions.length} session identifier(s) from ${sources.join(", ") || "local agents"}${full ? " across retained history" : ""}.\n`
       : `Already up to date. No usage rows changed${full ? " after a full-history reconciliation" : ""}.\n`);
-    if (regressions.length) process.stdout.write(`${regressions.length} local row(s) moved backward and were submitted as authoritative corrections.\n`);
+    if (regressions.length) process.stdout.write(`${regressions.length} local row(s) moved backward; prior counter dimensions were preserved because coverage is incomplete.\n`);
+    if (!authoritative) process.stdout.write(`${result.coverageReason}\n`);
     if (explain) process.stdout.write(`Coverage ${result.coverage}; ${sources.length} source(s); ${days[0] || "unknown"} to ${days.at(-1) || "unknown"}; ${partitions.length} atomic partition(s).\n`);
   }
   return result;
@@ -372,6 +359,7 @@ async function status() {
   process.stdout.write(`Linked: ${config.deviceName || deviceLabel()}${config.profileHandle ? ` → @${config.profileHandle}` : ""}\n`);
   process.stdout.write(`Last sync: ${config.lastSyncAt || "never"}\n`);
   process.stdout.write(`Last full reconciliation: ${config.lastFullSyncAt || "never"}\n`);
+  if (config.pendingSync) process.stdout.write(`Pending sync: ${config.pendingSync.runId}; rerun sync to resume\n`);
   process.stdout.write(`Profile: ${config.profileUrl || "https://usagemax.com/account"}\n`);
 }
 
@@ -458,12 +446,16 @@ async function main() {
   const command = args[0] || "sync";
   if (["--help", "-h", "help"].includes(command)) return help();
   if (["--version", "-v"].includes(command)) return process.stdout.write(`${VERSION}\n`);
-  if (command === "link") return link(args.slice(1));
-  if (command === "sync") return sync(args.slice(1));
-  if (command === "status") return status();
-  if (command === "doctor") return doctor(args.slice(1));
   if (command === "report") return report(args.slice(1));
-  if (command === "unlink") return removeLink(args.slice(1));
+  if (["link", "sync", "status", "doctor", "unlink"].includes(command)) {
+    return withConfigLock(configDirectory(), async () => {
+      if (command === "link") return link(args.slice(1));
+      if (command === "sync") return sync(args.slice(1));
+      if (command === "status") return status();
+      if (command === "doctor") return doctor(args.slice(1));
+      return removeLink(args.slice(1));
+    });
+  }
   throw new Error(`Unknown command: ${command}. Run usagemax --help.`);
 }
 

package/src/core.js

@@ -262,7 +262,7 @@ export function buildDeltaPlan(report, priorSnapshots, deviceId, pricingVersion
         pricingVersion,
         status: "ok",
         state: "synced",
-        occurredAt: `${row.period}T12:00:00.000Z`,
+        occurredAt: `${row.period}T00:00:00.000Z`,
         completeness: "estimated",
       },
     });
@@ -300,7 +300,9 @@ export function buildSnapshotPlan(report, priorSnapshots, {
   }
 
   const grouped = new Map();
-  const nextSnapshots = {};
+  // Carry forward history outside this scan's window. Only reconciled keys may
+  // replace or remove a checkpoint, including legacy three-part identities.
+  const nextSnapshots = Object.fromEntries([...priorRows].map(([key, row]) => [key, row.current]));
   const regressions = [];
   for (const key of allKeys) {
     const currentRow = rows.get(key);
@@ -308,9 +310,14 @@ export function buildSnapshotPlan(report, priorSnapshots, {
     const identity = currentRow || priorRow;
     if (!identity) continue;
     const previous = priorRow?.current ?? snapshotCounters();
-    const current = currentRow?.current ?? snapshotCounters();
-    if (snapshotCounterFields.some((field) => current[field] < previous[field])) regressions.push(key);
+    let current = currentRow?.current ?? snapshotCounters();
+    const regressed = snapshotCounterFields.some((field) => current[field] < previous[field]);
+    if (regressed) regressions.push(key);
+    // A larger total can conceal a missing dimension. Keep the coherent prior
+    // vector (including in the checkpoint) until coverage is authoritative.
+    if (!complete && regressed) current = { ...previous };
     if (!sameCounters(current, snapshotCounters())) nextSnapshots[key] = current;
+    else delete nextSnapshots[key];
     const partitionKey = `${identity.source}\u001f${identity.period}`;
     const rowsForPartition = grouped.get(partitionKey) ?? [];
     rowsForPartition.push({
@@ -321,7 +328,9 @@ export function buildSnapshotPlan(report, priorSnapshots, {
       current,
       costBasis: "estimated",
       contentHash: sha256(`${key}\u001f${JSON.stringify(current)}`),
-      lastUsedAt: Date.parse(`${identity.period}T12:00:00.000Z`),
+      // A daily aggregate has no exact event time. Use the start of its UTC day
+      // so today's partition is valid even when the collector runs before noon.
+      lastUsedAt: Date.parse(`${identity.period}T00:00:00.000Z`),
     });
     grouped.set(partitionKey, rowsForPartition);
   }
@@ -341,17 +350,23 @@ export function buildSnapshotPlan(report, priorSnapshots, {
       contentHash,
       lastUsedAt,
     }));
-    const payloadHash = sha256(JSON.stringify({ source, day, complete, pricingVersion, rows: wireRows }));
-    partitions.push({
-      partitionId: `${runId}:${sha256(partitionKey).slice(0, 24)}`,
-      payloadHash,
-      revision,
-      source,
-      day,
-      complete,
-      pricingVersion,
-      rows: wireRows,
-    });
+    const chunkCount = Math.ceil(wireRows.length / 100);
+    for (let chunkIndex = 0; chunkIndex < chunkCount; chunkIndex += 1) {
+      const rows = wireRows.slice(chunkIndex * 100, (chunkIndex + 1) * 100);
+      const payloadHash = sha256(JSON.stringify({ source, day, complete, pricingVersion, chunkIndex, chunkCount, rows }));
+      partitions.push({
+        partitionId: `${runId}:${sha256(partitionKey).slice(0, 24)}:${chunkIndex}`,
+        payloadHash,
+        revision,
+        source,
+        day,
+        complete,
+        pricingVersion,
+        chunkIndex,
+        chunkCount,
+        rows,
+      });
+    }
   }
   partitions.sort((left, right) => left.day === right.day ? left.source.localeCompare(right.source) : left.day.localeCompare(right.day));
   return { partitions, nextSnapshots, regressions };
@@ -361,6 +376,22 @@ function randomPlanId() {
   return `run-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
 }
 
+// Inventory stability certifies that repeating a successful parse is unnecessary;
+// it does not certify authority to remove server history. Bootstrap is separate.
+export function scanPolicy(config, inventory, { today, now, inventoryVersion, requestedFull = false, requestedArchives = false }) {
+  const knownSources = Array.isArray(config.knownSources) ? config.knownSources : [];
+  const lastFull = Date.parse(config.lastFullSyncAt || "");
+  const bootstrap = config.snapshotProtocolVersion !== 2;
+  const full = requestedFull || requestedArchives || bootstrap
+    || config.sourceInventoryVersion !== inventoryVersion
+    || !Number.isFinite(lastFull) || now - lastFull >= 7 * 24 * 60 * 60 * 1000
+    || inventory.sources.some((source) => !knownSources.includes(source));
+  const inventoryStable = inventory.complete && !inventory.truncated && inventory.errors === 0;
+  const skip = !config.pendingSync && !full && inventoryStable && config.lastScanSucceeded === true
+    && config.lastReconciledDay === today && config.sourceFingerprint === inventory.fingerprint;
+  return { bootstrap, full, skip, inventoryStable };
+}
+
 export function buildSessionPlan(report, deviceId) {
   const sessionRows = Array.isArray(report?.session) ? report.session : [];
   const sessions = new Map();
@@ -396,3 +427,11 @@ export function sourceSummary(report) {
   });
   return [...new Set(sources)].sort();
 }
+// Explicit UTC dates work with ccusage's combined daily/session sections.
+export function reportDateArgs(config, { full = false, now = Date.now() } = {}) {
+  const today = new Date(now).toISOString().slice(0, 10);
+  const since = full || !config?.lastSyncAt ? "2024-01-01"
+    : config.lastReconciledDay === today ? today
+      : new Date(Date.parse(today + "T00:00:00Z") - 86_400_000).toISOString().slice(0, 10);
+  return ["--since", since, "--until", today];
+}

package/src/resume.js

@@ -0,0 +1,58 @@
+// A pending run is saved before network I/O. Persisting the acknowledged cursor
+// after each request permits replays when the response or local write is lost.
+// The server must receipt begin, chunks, sessions and complete idempotently.
+export async function resumeUpload(config, { save, request, warn = () => {} }) {
+  const pending = config.pendingSync;
+  if (!pending || pending.version !== 1 || !Array.isArray(pending.requests)) {
+    throw new Error("Invalid saved sync; preserve the config for recovery.");
+  }
+  try {
+    for (let index = pending.cursor; index < pending.requests.length; index += 1) {
+      const { operation, payload } = pending.requests[index];
+      const response = await request(config, operation, payload, operation === "partitions" ? 60_000 : 30_000);
+      warn(response);
+      pending.cursor = index + 1;
+      await save(config);
+    }
+    // Commit local baseline and remove the journal in the same atomic write.
+    const next = { ...config, ...pending.checkpoint };
+    delete next.pendingSync;
+    await save(next);
+    Object.assign(config, next);
+    delete config.pendingSync;
+    return { ...pending.result, resumed: true };
+  } catch (error) {
+    if (error?.code === "snapshot_run_expired") {
+      pending.terminalError = "snapshot_run_expired";
+      await save(config);
+      throw new Error("Saved upload expired. Run usagemax sync --restart to rescan retained history while preserving the last committed checkpoint. Already accepted usage remains on the server.", { cause: error });
+    }
+    throw new Error(`${error instanceof Error ? error.message : "Upload failed."} Run usagemax sync again to resume saved run ${pending.runId}; its payload and checkpoints have been retained.`, { cause: error });
+  }
+}
+
+export function restartExpiredUpload(config) {
+  if (config.pendingSync?.terminalError !== "snapshot_run_expired") throw new Error("Only an expired upload can restart. Run sync normally to resume or verify its status first.");
+  delete config.pendingSync;
+  config.lastFullSyncAt = undefined;
+  config.sourceFingerprint = null;
+}
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export async function withConfigLock(directory, action) {
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const path = join(directory, "collector.lock");
+  try {
+    await writeFile(path, `${process.pid}\n`, { flag: "wx", mode: 0o600 });
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    const owner = (await readFile(path, "utf8").catch(() => "unknown")).trim();
+    throw new Error(`Collector config is locked by PID ${/^\d+$/.test(owner) ? owner : "unknown"}. If that process has exited, remove only ${path} and rerun sync; keep config.json for resume.`);
+  }
+  try {
+    return await action();
+  } finally {
+    await unlink(path);
+  }
+}

package/src/transport.js

@@ -0,0 +1,54 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+export function retryAfterMs(value, now = Date.now()) {
+  if (value == null || value === "") return 0;
+  if (/^\d+(?:\.\d+)?$/.test(value)) return Number(value) * 1000;
+  const date = Date.parse(value);
+  return Number.isFinite(date) ? Math.max(0, date - now) : 0;
+}
+
+// Only snapshot operations have server receipts. Never automatically replay a
+// one-use link request or apply this policy to arbitrary POST operations.
+export async function requestSnapshot(endpoint, config, operation, payload, {
+  timeout = 30_000, attempts = 5, maxDelayMs = 60_000,
+  fetchImpl = fetch, sleep = delay, random = Math.random, now = Date.now,
+} = {}) {
+  const body = JSON.stringify({ operation, ...payload });
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    let response;
+    let result;
+    let failure;
+    let retryable = true;
+    try {
+      response = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: { authorization: `Bearer ${config.token}`, "content-type": "application/json", "x-usagemax-device-id": config.deviceId },
+        body,
+        signal: AbortSignal.timeout(timeout),
+      });
+      result = await response.json().catch(() => null);
+      if (response.ok && result?.ok === true) return result;
+      retryable = response.ok || response.status === 429 || response.status >= 500
+        || (operation === "complete" && response.status === 409
+          && String(result?.error).toLowerCase() === "snapshot_run_incomplete");
+      const code = typeof result?.error === "string" ? result.error.replace(/[^a-zA-Z0-9_-]/g, "").slice(0, 80) : "invalid_response";
+      const advice = response.status === 401 ? " Link this computer again."
+        : response.status === 403 ? " Check workspace membership and collector permissions."
+        : response.status === 409 ? " The saved run needs reconciliation; do not delete its checkpoint or repeatedly start new runs."
+        : response.status === 400 ? " Check CLI/server protocol compatibility."
+        : "";
+      failure = new Error(`Snapshot ${operation} failed (HTTP ${response.status}: ${code}).${advice}`);
+      failure.code = code;
+    } catch {
+      failure = new Error(`Snapshot ${operation} could not reach UsageMax or timed out. Check your network connection.`);
+    }
+    if (!retryable || attempt + 1 >= attempts) throw failure;
+    const retryAfter = retryAfterMs(response?.headers?.get("retry-after"), now());
+    // Never retry earlier than the server's requested interval. Long backoffs
+    // remain durably resumable instead of blocking the command indefinitely.
+    if (retryAfter > maxDelayMs) throw new Error(`${failure.message} Server requested a longer wait; retry sync after ${Math.ceil(retryAfter / 1000)} seconds.`);
+    const jitter = Math.min(maxDelayMs, 1000 * 2 ** attempt) * (0.5 + random() * 0.5);
+    await sleep(Math.max(retryAfter, jitter));
+  }
+  throw new Error("Snapshot retry budget is empty.");
+}