@dzhechkov/harness-core 0.3.99 → 0.3.100

package/src/usage.ts

@@ -1,34 +1,29 @@
 /**
  * `dz usage` data source — a READONLY, never-throw, best-effort estimate of Claude SESSION
- * (active 5h-block) and WEEKLY (rolling 7d) token usage, aggregated from the local Claude Code
- * transcript files under `~/.claude/projects/<munged>/<session>.jsonl`.
+ * and WEEKLY token usage, aggregated from the local Claude Code transcript files under
+ * `~/.claude/projects/<munged>/<session>.jsonl`.
  *
- * ## Honest-uncertainty contract (LOAD-BEARING — NFR-4)
+ * ## Honest-uncertainty contract (LOAD-BEARING)
  *
- * These percentages are **ESTIMATES** derived by aggregating local transcript token counts against
- * a USER-CONFIGURED limit. There is **no official usage API** being consulted — this is a fuel
- * gauge built from the flow meter, not a tank sensor. Therefore:
+ * These percentages are ESTIMATES derived by aggregating local transcript token counts against
+ * USER-CONFIGURED limits. There is no official Anthropic usage API being consulted; claude.ai is
+ * authoritative. Therefore:
  *
- * - Every payload carries `estimated: true` so a consumer can NEVER mistake it for ground truth.
- * - When a limit is **unconfigured** (`.dz/config.json` has no `memory.usage.sessionTokenLimit` /
- *   `weeklyTokenLimit`), the corresponding `pct` is `null` — **unknown, never 0, never a guess**.
- * - **Calibration protocol (observed-exhaustion):** when a real limit-hit occurs at an estimated
- *   `X%`, scale the configured limit by `X/100` so the next estimate lines up with reality. The
- *   4 token fields are summed with equal weight; the relative weighting (cache-read tokens
- *   dominate real transcripts) is absorbed into the calibrated limit value.
+ * - Every JSON payload emitted by the CLI carries `estimated: true`.
+ * - When a limit is unconfigured, the corresponding `pct` is `null` — unknown, never 0.
+ * - Weekly usage counts from a fixed configured reset anchor such as `Wed 08:59`, not from a
+ *   rolling seven-day window.
+ * - Session usage counts from the active fixed-length transcript block, not from a rolling
+ *   last-N-hours window.
  *
- * ## Statusline discipline (NFR-1)
+ * ## Statusline discipline
  *
  * Modeled on {@link ./statusline.ts} and {@link ./vector-tier.ts}'s `readVectorEngineMode`:
- * - **never-throw** — any error (missing `~/.claude/projects`, corrupt jsonl line, missing/corrupt
- *   config, garbled usage object) collapses to a value with `null` pcts, never an exception.
- * - **readonly** — zero writes/appends/mkdir/unlink anywhere (the optional aggregate cache in
- *   arch §2.2(6) is DEFERRED — v1 ships with zero writes so READONLY is trivially true).
- * - **<100ms steady-state** via an `mtime` prefilter: a file whose `mtime` is older than the weekly
- *   window cannot contribute and is skipped WITHOUT opening it; only files touched inside the
- *   session window are line-parsed for the active block.
- * - **injectable clock** — `computeUsage(root, now?)` takes an optional `now` (ms epoch) so all
- *   window math is deterministic under test.
+ * - never-throw — missing/corrupt config, transcript directories, and jsonl lines collapse to
+ *   best-effort zero/null values, never exceptions;
+ * - readonly — `computeUsage` performs zero writes;
+ * - bounded scanning via an mtime prefilter;
+ * - injectable clock — `computeUsage(root, now?)` takes an optional epoch-ms clock.
  *
  * @packageDocumentation
  */
@@ -38,40 +33,195 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 const HOUR_MS = 60 * 60 * 1000;
-const SESSION_BLOCK_MS = 5 * HOUR_MS; // ccusage 5h-block
-const WEEK_MS = 7 * 24 * HOUR_MS; // rolling 7-day weekly window
-// mtime prefilter slack (+1h) — guards against clock skew between the writer and this reader
-// (a file with a slightly-stale mtime that is actually in-window must not be dropped).
+const DEFAULT_SESSION_BLOCK_HOURS = 5;
+const DEFAULT_WEEKLY_RESET_ANCHOR = 'Wed 08:59';
+// mtime prefilter slack (+1h) — guards against clock skew between the writer and this reader.
 const MTIME_SLACK_MS = HOUR_MS;
 
+export const CLAUDE_USAGE_MODELS = ['fable', 'opus', 'sonnet', 'haiku'] as const;
+export type ClaudeUsageModel = (typeof CLAUDE_USAGE_MODELS)[number];
+
+export interface UsageWindow {
+  readonly startedAtMs: number;
+  readonly resetsAtMs: number;
+}
+
+export interface WeeklyResetAnchor {
+  readonly weekday: number; // local Date#getDay(): Sun=0, Mon=1, ...
+  readonly hour: number;
+  readonly minute: number;
+}
+
 /** Optional, plan-dependent calibration limits from `.dz/config.json`. Absent ⇒ pct is `null`. */
 export interface UsageLimits {
   readonly sessionTokenLimit?: number;
   readonly weeklyTokenLimit?: number;
+  readonly weeklyTokenLimitByModel?: Partial<Record<ClaudeUsageModel, number>>;
+  readonly weeklyResetAnchor?: string;
+  readonly sessionBlockHours?: number;
+  readonly calibratedAt?: string;
+  readonly source?: string;
+}
+
+export interface UsageModelEstimate {
+  readonly tokens: number;
+  readonly pct: number | null;
 }
 
 /** A never-throw usage estimate. `estimated` is ALWAYS `true` (honest-uncertainty marker). */
 export interface UsageEstimate {
-  /** Active 5h-block token total (all projects). `0` when there is no active block. */
+  /** Active fixed-length session block token total (all projects). */
   readonly sessionTokens: number;
-  /** Rolling 7d token total (all projects). */
+  /** Fixed weekly-reset-window token total (all projects). */
   readonly weeklyTokens: number;
-  /** `null` ⇔ `sessionTokenLimit` unconfigured (unknown — never 0). */
+  /** `null` ⇔ `sessionTokenLimit` unconfigured (unknown — never a guess). */
   readonly sessionPct: number | null;
-  /** `null` ⇔ `weeklyTokenLimit` unconfigured (unknown — never 0). */
+  /** Binding weekly pct: per-model max when configured, otherwise all-model aggregate. */
   readonly weeklyPct: number | null;
-  /** ISO — active block start + 5h; `null` when there is no active block. */
+  /** ISO — active block start + configured session hours; `null` when there is no active block. */
   readonly sessionResetsAt: string | null;
-  /** ISO — oldest in-window sample ts + 7d (estimate); `null` when the weekly window is empty. */
+  /** ISO — next configured fixed weekly reset. */
   readonly weeklyResetsAt: string | null;
   /** ALWAYS `true` — these are estimates from local aggregation, not an official API. */
   readonly estimated: true;
+  /** Present only when per-model weekly limits are configured. */
+  readonly weeklyByModel?: Partial<Record<ClaudeUsageModel, UsageModelEstimate>>;
+  /** Raw weekly model totals for calibration; CLI omits this from the compatibility JSON. */
+  readonly weeklyTokensByModel: Partial<Record<ClaudeUsageModel, number>>;
+  /** Model family that supplied the binding top-level weeklyPct, if any. */
+  readonly weeklyBindingModel?: ClaudeUsageModel;
+  /** Traceability for tests and calibration diagnostics. */
+  readonly sessionStartedAt: string | null;
+  readonly weeklyStartedAt: string | null;
+}
+
+export interface UsageCalibrationInput {
+  readonly sessionPct?: unknown;
+  readonly weeklyPct?: unknown;
+  readonly modelPct?: Readonly<Record<string, unknown>>;
+  readonly calibratedAt: string;
+  readonly source: 'claude.ai/settings/usage';
+}
+
+export interface UsageCalibrationChange {
+  readonly key: string;
+  readonly before: number | null;
+  readonly after: number;
+  readonly tokens: number;
+  readonly pct: number;
+}
+
+export interface UsageCalibrationPlan {
+  readonly before: UsageLimits;
+  readonly after: UsageLimits;
+  readonly changes: readonly UsageCalibrationChange[];
+  readonly skipped: readonly string[];
+}
+
+interface MutableUsageLimits {
+  sessionTokenLimit?: number;
+  weeklyTokenLimit?: number;
+  weeklyTokenLimitByModel?: Partial<Record<ClaudeUsageModel, number>>;
+  weeklyResetAnchor?: string;
+  sessionBlockHours?: number;
+  calibratedAt?: string;
+  source?: string;
+}
+
+const WEEKDAY_TO_DAY: Record<string, number> = {
+  sun: 0,
+  mon: 1,
+  tue: 2,
+  wed: 3,
+  thu: 4,
+  fri: 5,
+  sat: 6,
+};
+
+const DAY_TO_WEEKDAY = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function positiveFiniteNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && isFinite(value) && value > 0 ? value : undefined;
+}
+
+function hasOwn(obj: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+function canonicalWeeklyResetAnchor(anchor: WeeklyResetAnchor): string {
+  return `${DAY_TO_WEEKDAY[anchor.weekday] ?? 'Wed'} ${String(anchor.hour).padStart(2, '0')}:${String(anchor.minute).padStart(2, '0')}`;
+}
+
+export function parseWeeklyResetAnchor(anchor: string): WeeklyResetAnchor | null {
+  const m = /^\s*(sun|mon|tue|wed|thu|fri|sat)\s+(\d{1,2}):(\d{2})\s*$/i.exec(anchor);
+  if (!m) return null;
+  const weekday = WEEKDAY_TO_DAY[m[1]!.toLowerCase()];
+  const hour = Number(m[2]);
+  const minute = Number(m[3]);
+  if (weekday === undefined || !Number.isInteger(hour) || !Number.isInteger(minute)) return null;
+  if (hour < 0 || hour > 23 || minute < 0 || minute > 59) return null;
+  return { weekday, hour, minute };
+}
+
+export function weeklyWindowFor(nowMs: number, anchor: string): UsageWindow | null {
+  if (!isFinite(nowMs)) return null;
+  const parsed = parseWeeklyResetAnchor(anchor);
+  if (!parsed) return null;
+
+  const now = new Date(nowMs);
+  const candidate = new Date(
+    now.getFullYear(),
+    now.getMonth(),
+    now.getDate(),
+    parsed.hour,
+    parsed.minute,
+    0,
+    0,
+  );
+  candidate.setDate(candidate.getDate() + (parsed.weekday - now.getDay()));
+  if (candidate.getTime() > nowMs) candidate.setDate(candidate.getDate() - 7);
+  const next = new Date(candidate.getTime());
+  next.setDate(next.getDate() + 7);
+  return { startedAtMs: candidate.getTime(), resetsAtMs: next.getTime() };
+}
+
+/**
+ * A simple fixed-duration grid helper kept exported for pure date-math tests. `computeUsage` uses
+ * transcript-established session blocks per the feature requirements because no account-specific
+ * session anchor is stored today.
+ */
+export function fixedBlockWindowFor(nowMs: number, blockHours: number): UsageWindow | null {
+  if (!isFinite(nowMs)) return null;
+  const hours = positiveFiniteNumber(blockHours);
+  if (hours === undefined) return null;
+  const blockMs = hours * HOUR_MS;
+  const startedAtMs = Math.floor(nowMs / blockMs) * blockMs;
+  return { startedAtMs, resetsAtMs: startedAtMs + blockMs };
+}
+
+export function normalizeClaudeUsageModel(raw: unknown): ClaudeUsageModel | null {
+  if (typeof raw !== 'string') return null;
+  const s = raw.toLowerCase();
+  if (s.includes('fable')) return 'fable';
+  if (s.includes('opus')) return 'opus';
+  if (s.includes('sonnet')) return 'sonnet';
+  if (s.includes('haiku')) return 'haiku';
+  return null;
+}
+
+export function normalizeClaudeUsageModelKey(raw: unknown): ClaudeUsageModel | null {
+  if (typeof raw !== 'string') return null;
+  const key = raw.trim().toLowerCase();
+  return (CLAUDE_USAGE_MODELS as readonly string[]).includes(key) ? (key as ClaudeUsageModel) : null;
 }
 
 /**
  * The `~/.claude/projects` root (the account-wide transcript store). Overridable via
- * `DZ_CLAUDE_PROJECTS_ROOT` — used by tests to point at a temp tree (and by any user who relocates
- * the Claude home). Never throws.
+ * `DZ_CLAUDE_PROJECTS_ROOT` — used by tests to point at a temp tree. Never throws.
  */
 function claudeProjectsRoot(): string {
   const override = process.env['DZ_CLAUDE_PROJECTS_ROOT'];
@@ -80,23 +230,45 @@ function claudeProjectsRoot(): string {
 }
 
 /**
- * Read `memory.usage.{sessionTokenLimit,weeklyTokenLimit}` from `<projectRoot>/.dz/config.json`.
- * NEVER throws — absent/corrupt/partial config ⇒ `{}` (⇒ pct `null`). Mirrors the
- * `readVectorEngineMode` never-throw shape exactly. `projectRoot` is the ONLY thing that scopes to
- * a project; the MEASUREMENT below is account-wide (FR-1.6).
+ * Read `memory.usage.*` from `<projectRoot>/.dz/config.json`. NEVER throws —
+ * absent/corrupt/partial config ⇒ `{}` or only valid fields.
  */
 export function readUsageLimits(projectRoot: string): UsageLimits {
   try {
-    const cfg = JSON.parse(readFileSync(join(projectRoot, '.dz', 'config.json'), 'utf-8')) as {
-      memory?: { usage?: { sessionTokenLimit?: unknown; weeklyTokenLimit?: unknown } };
-    };
-    const u = cfg.memory?.usage;
-    if (!u || typeof u !== 'object') return {};
-    const out: { sessionTokenLimit?: number; weeklyTokenLimit?: number } = {};
-    const s = u.sessionTokenLimit;
-    const w = u.weeklyTokenLimit;
-    if (typeof s === 'number' && isFinite(s) && s > 0) out.sessionTokenLimit = s;
-    if (typeof w === 'number' && isFinite(w) && w > 0) out.weeklyTokenLimit = w;
+    const cfg = JSON.parse(readFileSync(join(projectRoot, '.dz', 'config.json'), 'utf-8')) as unknown;
+    if (!isRecord(cfg)) return {};
+    const memory = cfg['memory'];
+    if (!isRecord(memory)) return {};
+    const u = memory['usage'];
+    if (!isRecord(u)) return {};
+
+    const out: MutableUsageLimits = {};
+    const sessionLimit = positiveFiniteNumber(u['sessionTokenLimit']);
+    const weeklyLimit = positiveFiniteNumber(u['weeklyTokenLimit']);
+    const sessionBlockHours = positiveFiniteNumber(u['sessionBlockHours']);
+    if (sessionLimit !== undefined) out.sessionTokenLimit = sessionLimit;
+    if (weeklyLimit !== undefined) out.weeklyTokenLimit = weeklyLimit;
+    if (sessionBlockHours !== undefined) out.sessionBlockHours = sessionBlockHours;
+
+    const anchor = u['weeklyResetAnchor'];
+    if (typeof anchor === 'string') {
+      const parsed = parseWeeklyResetAnchor(anchor);
+      if (parsed) out.weeklyResetAnchor = canonicalWeeklyResetAnchor(parsed);
+    }
+
+    const byModel = u['weeklyTokenLimitByModel'];
+    if (isRecord(byModel)) {
+      const modelLimits: Partial<Record<ClaudeUsageModel, number>> = {};
+      for (const [key, value] of Object.entries(byModel)) {
+        const model = normalizeClaudeUsageModelKey(key);
+        const limit = positiveFiniteNumber(value);
+        if (model && limit !== undefined) modelLimits[model] = limit;
+      }
+      if (Object.keys(modelLimits).length > 0) out.weeklyTokenLimitByModel = modelLimits;
+    }
+
+    if (typeof u['calibratedAt'] === 'string') out.calibratedAt = u['calibratedAt'];
+    if (typeof u['source'] === 'string') out.source = u['source'];
     return out;
   } catch {
     return {};
@@ -108,6 +280,7 @@ interface Sample {
   readonly ts: number; // ms epoch
   readonly tokens: number;
   readonly key: string; // dedup key: message.id + ':' + requestId
+  readonly model: ClaudeUsageModel | null;
 }
 
 /**
@@ -139,7 +312,7 @@ function listTranscriptFiles(root: string): Array<{ path: string; mtimeMs: numbe
       try {
         out.push({ path: p, mtimeMs: statSync(p).mtimeMs });
       } catch {
-        // skip a file we can't stat
+        // skip a file we cannot stat
       }
     }
   }
@@ -147,11 +320,10 @@ function listTranscriptFiles(root: string): Array<{ path: string; mtimeMs: numbe
 }
 
 /**
- * Extract usage samples from one transcript file. Never throws — a corrupt line is skipped
- * (statusline discipline). A cheap `"usage"` substring pre-filter avoids `JSON.parse` on lines
- * that cannot carry a token count. `weeklyCutoff` drops samples older than the rolling window.
+ * Extract usage samples from one transcript file. Never throws — a corrupt line is skipped.
+ * `scanCutoff` drops samples older than every window that could affect the estimate.
  */
-function extractSamples(path: string, weeklyCutoff: number, into: Sample[], seen: Set<string>): void {
+function extractSamples(path: string, scanCutoff: number, into: Sample[], seen: Set<string>): void {
   let raw: string;
   try {
     raw = readFileSync(path, 'utf-8');
@@ -165,8 +337,10 @@ function extractSamples(path: string, weeklyCutoff: number, into: Sample[], seen
     let rec: {
       timestamp?: unknown;
       requestId?: unknown;
+      model?: unknown;
       message?: {
         id?: unknown;
+        model?: unknown;
         usage?: {
           input_tokens?: unknown;
           cache_creation_input_tokens?: unknown;
@@ -176,7 +350,7 @@ function extractSamples(path: string, weeklyCutoff: number, into: Sample[], seen
       };
     };
     try {
-      rec = JSON.parse(line);
+      rec = JSON.parse(line) as typeof rec;
     } catch {
       continue; // corrupt line — skip, never throw
     }
@@ -186,7 +360,7 @@ function extractSamples(path: string, weeklyCutoff: number, into: Sample[], seen
     if (typeof tsRaw !== 'string' && typeof tsRaw !== 'number') continue;
     const ts = typeof tsRaw === 'number' ? tsRaw : Date.parse(tsRaw);
     if (!isFinite(ts)) continue;
-    if (ts < weeklyCutoff) continue; // outside the weekly window — cannot contribute
+    if (ts < scanCutoff) continue;
     const n = (v: unknown): number => (typeof v === 'number' && isFinite(v) && v > 0 ? v : 0);
     const tokens =
       n(usage.input_tokens) +
@@ -202,88 +376,242 @@ function extractSamples(path: string, weeklyCutoff: number, into: Sample[], seen
       if (seen.has(key)) continue;
       seen.add(key);
     }
-    into.push({ ts, tokens, key });
+    into.push({ ts, tokens, key, model: normalizeClaudeUsageModel(rec.message?.model ?? rec.model) });
   }
 }
 
-/**
- * Compute the SESSION active-block total using ccusage 5h-block semantics: walk samples in ts
- * order; a block starts at the first sample after the previous block ends, FLOORED to the hour;
- * `end = start + 5h`. The ACTIVE block is the one whose `[start, end)` contains `now`. No active
- * block ⇒ `{ tokens: 0, resetsAt: null }`.
- */
-function activeBlock(samplesAsc: Sample[], now: number): { tokens: number; resetsAt: string | null } {
+function activeSessionBlock(
+  samplesAsc: Sample[],
+  nowMs: number,
+  blockHours: number,
+): { tokens: number; startedAtMs: number | null; resetsAtMs: number | null } {
+  const hours = positiveFiniteNumber(blockHours) ?? DEFAULT_SESSION_BLOCK_HOURS;
+  const blockMs = hours * HOUR_MS;
   let blockStart = -1;
   let blockEnd = -1;
   let tokens = 0;
-  let activeStart = -1;
+  let activeStart: number | null = null;
+  let activeEnd: number | null = null;
   let activeTokens = 0;
+
   for (const s of samplesAsc) {
+    if (s.ts > nowMs) continue;
     if (blockStart === -1 || s.ts >= blockEnd) {
-      // close the previous block, open a new one floored to the hour
-      blockStart = Math.floor(s.ts / HOUR_MS) * HOUR_MS;
-      blockEnd = blockStart + SESSION_BLOCK_MS;
+      blockStart = s.ts;
+      blockEnd = blockStart + blockMs;
       tokens = 0;
     }
     tokens += s.tokens;
-    if (now >= blockStart && now < blockEnd) {
+    if (nowMs >= blockStart && nowMs < blockEnd) {
       activeStart = blockStart;
+      activeEnd = blockEnd;
       activeTokens = tokens;
     }
   }
-  if (activeStart === -1) return { tokens: 0, resetsAt: null };
-  return { tokens: activeTokens, resetsAt: new Date(activeStart + SESSION_BLOCK_MS).toISOString() };
+
+  return { tokens: activeTokens, startedAtMs: activeStart, resetsAtMs: activeEnd };
+}
+
+function pct(tokens: number, limit?: number): number | null {
+  return typeof limit === 'number' && limit > 0 ? Math.round((100 * tokens) / limit) : null;
+}
+
+function configuredModelLimits(
+  limits?: Partial<Record<ClaudeUsageModel, number>>,
+): Array<[ClaudeUsageModel, number]> {
+  if (!limits) return [];
+  const out: Array<[ClaudeUsageModel, number]> = [];
+  for (const model of CLAUDE_USAGE_MODELS) {
+    const limit = limits[model];
+    if (typeof limit === 'number' && isFinite(limit) && limit > 0) out.push([model, limit]);
+  }
+  return out;
 }
 
 /**
  * Estimate SESSION + WEEKLY token usage from the local Claude transcript store. NEVER throws;
- * READONLY; `<100ms` steady-state via the `mtime` prefilter. `projectRoot` scopes ONLY the config
- * (limits) read — measurement is account-wide (all projects). `now` is injectable for tests.
+ * READONLY; `projectRoot` scopes ONLY the config (limits) read — measurement is account-wide
+ * (all projects). `now` is injectable for tests.
  */
 export function computeUsage(projectRoot: string, now?: number): UsageEstimate {
   const nowMs = typeof now === 'number' && isFinite(now) ? now : Date.now();
   const limits = readUsageLimits(projectRoot);
-  const weeklyCutoff = nowMs - WEEK_MS - MTIME_SLACK_MS;
+  const sessionBlockHours = limits.sessionBlockHours ?? DEFAULT_SESSION_BLOCK_HOURS;
+  const weeklyAnchor = limits.weeklyResetAnchor ?? DEFAULT_WEEKLY_RESET_ANCHOR;
+  const weeklyWindow = weeklyWindowFor(nowMs, weeklyAnchor);
+  // For transcript-established blocks, one previous block may be needed to prove that an event just
+  // before the current boundary belongs to the prior block rather than opening the active one.
+  const sessionScanCutoff = nowMs - 2 * sessionBlockHours * HOUR_MS;
+  const weeklyScanCutoff = weeklyWindow?.startedAtMs ?? nowMs;
+  const scanCutoff = Math.min(sessionScanCutoff, weeklyScanCutoff) - MTIME_SLACK_MS;
 
   const samples: Sample[] = [];
   const seen = new Set<string>();
   try {
     const files = listTranscriptFiles(claudeProjectsRoot());
     for (const f of files) {
-      // mtime prefilter: a file last written before the weekly cutoff cannot hold in-window
-      // samples — skip it WITHOUT opening it (the <100ms lever).
-      if (f.mtimeMs < weeklyCutoff) continue;
-      extractSamples(f.path, weeklyCutoff, samples, seen);
+      // mtime prefilter: a file last written before every relevant cutoff cannot contribute.
+      if (f.mtimeMs < scanCutoff) continue;
+      extractSamples(f.path, scanCutoff, samples, seen);
     }
   } catch {
     // total scan failure ⇒ fall through with empty samples (nulls), never throw
   }
 
-  // Weekly total: every sample inside the exact 7d window (the +slack was only a prefilter guard).
-  const weeklyHardCutoff = nowMs - WEEK_MS;
   let weeklyTokens = 0;
-  let oldestInWindow = -1;
-  for (const s of samples) {
-    if (s.ts < weeklyHardCutoff) continue;
-    weeklyTokens += s.tokens;
-    if (oldestInWindow === -1 || s.ts < oldestInWindow) oldestInWindow = s.ts;
+  const weeklyTokensByModel: Partial<Record<ClaudeUsageModel, number>> = {};
+  if (weeklyWindow) {
+    for (const s of samples) {
+      if (s.ts < weeklyWindow.startedAtMs || s.ts >= weeklyWindow.resetsAtMs || s.ts > nowMs) continue;
+      weeklyTokens += s.tokens;
+      if (s.model) weeklyTokensByModel[s.model] = (weeklyTokensByModel[s.model] ?? 0) + s.tokens;
+    }
   }
 
   const asc = samples.slice().sort((a, b) => a.ts - b.ts);
-  const block = activeBlock(asc, nowMs);
-
-  const pct = (tokens: number, limit?: number): number | null =>
-    typeof limit === 'number' && limit > 0 ? Math.round((100 * tokens) / limit) : null;
+  const block = activeSessionBlock(asc, nowMs, sessionBlockHours);
 
-  const weeklyResetsAt = oldestInWindow === -1 ? null : new Date(oldestInWindow + WEEK_MS).toISOString();
+  const modelLimits = configuredModelLimits(limits.weeklyTokenLimitByModel);
+  let weeklyByModel: Partial<Record<ClaudeUsageModel, UsageModelEstimate>> | undefined;
+  let weeklyPct = pct(weeklyTokens, limits.weeklyTokenLimit);
+  let weeklyBindingModel: ClaudeUsageModel | undefined;
+  if (modelLimits.length > 0) {
+    weeklyByModel = {};
+    weeklyPct = null;
+    for (const [model, limit] of modelLimits) {
+      const tokens = weeklyTokensByModel[model] ?? 0;
+      const modelPct = pct(tokens, limit);
+      weeklyByModel[model] = { tokens, pct: modelPct };
+      if (modelPct !== null && (weeklyPct === null || modelPct > weeklyPct)) {
+        weeklyPct = modelPct;
+        weeklyBindingModel = model;
+      }
+    }
+  }
 
   return {
     sessionTokens: block.tokens,
     weeklyTokens,
     sessionPct: pct(block.tokens, limits.sessionTokenLimit),
-    weeklyPct: pct(weeklyTokens, limits.weeklyTokenLimit),
-    sessionResetsAt: block.resetsAt,
-    weeklyResetsAt,
+    weeklyPct,
+    sessionResetsAt: block.resetsAtMs === null ? null : new Date(block.resetsAtMs).toISOString(),
+    weeklyResetsAt: weeklyWindow === null ? null : new Date(weeklyWindow.resetsAtMs).toISOString(),
     estimated: true,
+    ...(weeklyByModel !== undefined ? { weeklyByModel } : {}),
+    weeklyTokensByModel,
+    ...(weeklyBindingModel !== undefined ? { weeklyBindingModel } : {}),
+    sessionStartedAt: block.startedAtMs === null ? null : new Date(block.startedAtMs).toISOString(),
+    weeklyStartedAt: weeklyWindow === null ? null : new Date(weeklyWindow.startedAtMs).toISOString(),
   };
 }
+
+function validPct(label: string, value: unknown, skipped: string[]): number | null {
+  const n = typeof value === 'number' ? value : typeof value === 'string' && value.trim() !== '' ? Number(value) : NaN;
+  if (!isFinite(n) || n <= 0 || n > 100) {
+    skipped.push(`${label}: skipped invalid percentage ${String(value)}`);
+    return null;
+  }
+  return n;
+}
+
+function applyCalibrationLimit(opts: {
+  label: string;
+  tokens: number;
+  rawPct: unknown;
+  before: number | undefined;
+  set: (limit: number) => void;
+  skipped: string[];
+  changes: UsageCalibrationChange[];
+}): void {
+  const suppliedPct = validPct(opts.label, opts.rawPct, opts.skipped);
+  if (suppliedPct === null) return;
+  if (!isFinite(opts.tokens) || opts.tokens <= 0) {
+    opts.skipped.push(`${opts.label}: skipped because current token count is 0`);
+    return;
+  }
+  const limit = Math.round(opts.tokens / (suppliedPct / 100));
+  if (!isFinite(limit) || limit <= 0) {
+    opts.skipped.push(`${opts.label}: skipped because derived limit is invalid`);
+    return;
+  }
+  opts.set(limit);
+  opts.changes.push({
+    key: opts.label,
+    before: opts.before ?? null,
+    after: limit,
+    tokens: opts.tokens,
+    pct: suppliedPct,
+  });
+}
+
+export function deriveUsageCalibration(
+  current: UsageEstimate,
+  before: UsageLimits,
+  input: UsageCalibrationInput,
+): UsageCalibrationPlan {
+  const after: MutableUsageLimits = {
+    ...before,
+    ...(before.weeklyTokenLimitByModel !== undefined
+      ? { weeklyTokenLimitByModel: { ...before.weeklyTokenLimitByModel } }
+      : {}),
+  };
+  const skipped: string[] = [];
+  const changes: UsageCalibrationChange[] = [];
+
+  if (hasOwn(input, 'sessionPct')) {
+    applyCalibrationLimit({
+      label: 'session',
+      tokens: current.sessionTokens,
+      rawPct: input.sessionPct,
+      before: before.sessionTokenLimit,
+      set: (limit) => {
+        after.sessionTokenLimit = limit;
+      },
+      skipped,
+      changes,
+    });
+  }
+
+  if (hasOwn(input, 'weeklyPct')) {
+    applyCalibrationLimit({
+      label: 'weekly',
+      tokens: current.weeklyTokens,
+      rawPct: input.weeklyPct,
+      before: before.weeklyTokenLimit,
+      set: (limit) => {
+        after.weeklyTokenLimit = limit;
+      },
+      skipped,
+      changes,
+    });
+  }
+
+  if (input.modelPct !== undefined) {
+    for (const [key, rawPct] of Object.entries(input.modelPct)) {
+      const model = normalizeClaudeUsageModelKey(key);
+      if (!model) {
+        skipped.push(`model ${key}: skipped unknown model`);
+        continue;
+      }
+      applyCalibrationLimit({
+        label: model,
+        tokens: current.weeklyTokensByModel[model] ?? 0,
+        rawPct,
+        before: before.weeklyTokenLimitByModel?.[model],
+        set: (limit) => {
+          if (after.weeklyTokenLimitByModel === undefined) after.weeklyTokenLimitByModel = {};
+          after.weeklyTokenLimitByModel[model] = limit;
+        },
+        skipped,
+        changes,
+      });
+    }
+  }
+
+  if (changes.length > 0) {
+    after.calibratedAt = input.calibratedAt;
+    after.source = input.source;
+  }
+
+  return { before, after, changes, skipped };
+}