feat(worker): expose usage/model-usage hub surface and persist run model

Adds GetUsageSnapshot/GetModelUsage/GetTaskUsage to WorkerHub (backed by a
shared UsageSnapshotBuilder), a UsageUpdated broadcast fired after every
UsageMonitorService poll cycle, and records the resolved model on each
task_runs row so per-model/per-task usage can be reported from history.

src/ClaudeDo.Worker/CLAUDE.md

@@ -21,7 +21,7 @@ Worker/
   Report/       — ClaudeHistoryReader, WeekReportPromptBuilder, WeekReportService; interfaces in Report/Interfaces/
   Prime/        — daily-prep ("Prime Claude"): PrimeScheduler (BackgroundService), PrimeRunner (runs the daily prep), DailyPrepPrompt (fixed prompt + CLI args + LogPath() helper), NextDueCalculator, PrimeScheduleSignal; interfaces in Prime/Interfaces/ (IPrimeRunner, IPrimeClock, IPrimeScheduleSignal, IPrimeBroadcaster)
   Online/       — optional Online Inbox sync: OnlineInboxConfig (config record), Dtos (RemoteList/RemoteTask/MirrorTask), IOnlineInboxApi, OnlineInboxApiClient (typed HttpClient, bearer auth, HTTPS guard), OnlineTokenStore (DPAPI refresh-token store, Windows-only), StaticTokenAuthProvider (default/test IOnlineAuthProvider), ZitadelAuthProvider (OIDC discovery + refresh-token flow), OnlineSyncService (BackgroundService: reconcile loop), OnlineBacklog (Idle-backlog filter/query); interface in Online/Interfaces/ (IOnlineAuthProvider)
-  Usage/        — OAuth usage monitor: UsageModels (UsageBucket/UsageLimitRow/UsageSnapshot), ClaudeOAuthUsageClient (reads the access token Claude Code keeps fresh at `~/.claude/.credentials.json`, calls `GET https://api.anthropic.com/api/oauth/usage`; defensive parsing — missing/null buckets → null, missing `limits` → empty list; never logs the token), UsageState (threadsafe singleton; a failed poll never overwrites the last good snapshot, only sets `LastError`), UsageMonitorService (BackgroundService, polls on `usage_poll_interval_seconds`, one poll at startup, logs a failure at most once per distinct error message), TranscriptUsageReader (aggregates Claude Code transcript token usage from `~/.claude/projects/**/*.jsonl` by date/model/scope (ClaudeDo vs Other), deduped by requestId, with a per-file length+mtime cache), UsageGate (reads `UsageState` + `AppSettings.UsageGateFiveHourPct`/`UsageGateSevenDayPct`, returns a `UsageGateDecision(IsBlocked, Reason)`; `Utilization` from `UsageBucket` is already a 0–100 percent, compared directly against the threshold with `>=`; threshold `0` = that bucket never gates; fail-open — no snapshot yet, a failed last poll, or a settings-read error all resolve to not-blocked); interfaces in Usage/Interfaces/ (IUsageClient, ITranscriptUsageReader, IUsageGate)
+  Usage/        — OAuth usage monitor: UsageModels (UsageBucket/UsageLimitRow/UsageSnapshot), ClaudeOAuthUsageClient (reads the access token Claude Code keeps fresh at `~/.claude/.credentials.json`, calls `GET https://api.anthropic.com/api/oauth/usage`; defensive parsing — missing/null buckets → null, missing `limits` → empty list; never logs the token), UsageState (threadsafe singleton; a failed poll never overwrites the last good snapshot, only sets `LastError`), UsageMonitorService (BackgroundService, polls on `usage_poll_interval_seconds`, one poll at startup, logs a failure at most once per distinct error message, broadcasts `HubBroadcaster.UsageUpdated` after every tick via `UsageSnapshotBuilder`), UsageSnapshotBuilder (builds the Hub-facing `UsageSnapshotDto` from `UsageState` + `IUsageGate` + `AppSettings` thresholds — the one place `WorkerHub.GetUsageSnapshot` and `UsageMonitorService` share the stale/threshold/gate logic), TranscriptUsageReader (aggregates Claude Code transcript token usage from `~/.claude/projects/**/*.jsonl` by date/model/scope (ClaudeDo vs Other), deduped by requestId, with a per-file length+mtime cache), UsageGate (reads `UsageState` + `AppSettings.UsageGateFiveHourPct`/`UsageGateSevenDayPct`, returns a `UsageGateDecision(IsBlocked, Reason)`; `Utilization` from `UsageBucket` is already a 0–100 percent, compared directly against the threshold with `>=`; threshold `0` = that bucket never gates; fail-open — no snapshot yet, a failed last poll, or a settings-read error all resolve to not-blocked); interfaces in Usage/Interfaces/ (IUsageClient, ITranscriptUsageReader, IUsageGate)
 ```
 
 Interfaces (e.g. `IQueueWaker`, `IPrimeClock`, `ITaskStateService`) live in an `Interfaces/` subfolder within their area; the namespace stays the area namespace.
@@ -181,8 +181,9 @@ Each CLI invocation is recorded in the `task_runs` table via `TaskRunRepository`
 - Agents/settings/lists: `GetAgents`, `RefreshAgents`, `RestoreDefaultAgents`, `GetAppSettings`, `UpdateAppSettings`, `UpdateList`, `UpdateListConfig`, `GetListConfig`, `UpdateTaskAgentSettings`
 - Reports/notes/prep: `GetWeekReport`, `GenerateWeekReport`, `GetDailyNotes`, `AddDailyNote`, `UpdateDailyNote`, `DeleteDailyNote`, `RunDailyPrepNow`, `ClearMyDay`, `GetLastPrepLog`, `ListPrimeSchedules`, `UpsertPrimeSchedule`, `DeletePrimeSchedule`
 - Diagnostics: `GetRecentLogs` (last 30 min of buffered log records, all levels, for the Log Visualizer overlay)
+- Usage: `GetUsageSnapshot() -> UsageSnapshotDto` (built by `UsageSnapshotBuilder` from `UsageState` + `IUsageGate` + `AppSettings` gate thresholds; percentages/limits/`FetchedAtUtc` null and `IsStale=true` when no snapshot has landed yet; `IsStale` also trips on a failed last poll or a snapshot older than 3× `usage_poll_interval_seconds`), `GetModelUsage(from, to) -> IReadOnlyList<ModelUsageRowDto>` (thin wrapper over `ITranscriptUsageReader.ReadAsync`), `GetTaskUsage(from, to) -> IReadOnlyList<TaskUsageRowDto>` (top consumers from `task_runs` joined to task/list, grouped per task — `Runs`/summed `TokensIn`/`TokensOut` (null token columns count as 0, never dropped), `Model` from that task's most recent run — sorted by total tokens descending, capped at 100)
 
-**HubBroadcaster** events: `TaskStarted`, `TaskFinished`, `TaskMessage`, `WorktreeUpdated`, `TaskUpdated`, `RunCreated`, `ListUpdated`, `WorkerLog`, `PrimeFired`, `PrepStarted`, `PrepLine`, `PrepFinished`, `PlanningMergeStarted`, `PlanningSubtaskMerged`, `PlanningMergeConflict`, `PlanningMergeAborted`, `PlanningCompleted`, `RefineStarted`, `RefineFinished`
+**HubBroadcaster** events: `TaskStarted`, `TaskFinished`, `TaskMessage`, `WorktreeUpdated`, `TaskUpdated`, `RunCreated`, `ListUpdated`, `WorkerLog`, `PrimeFired`, `PrepStarted`, `PrepLine`, `PrepFinished`, `PlanningMergeStarted`, `PlanningSubtaskMerged`, `PlanningMergeConflict`, `PlanningMergeAborted`, `PlanningCompleted`, `RefineStarted`, `RefineFinished`, `UsageUpdated` (carries the same `UsageSnapshotDto` as `GetUsageSnapshot`; `UsageMonitorService` fires it after every poll cycle, success or failure, via the shared `UsageSnapshotBuilder`)
 
 `WorkerLog` carries two sources: the hand-curated business events (`_broadcaster.WorkerLog(...)` in TaskRunner/TaskMergeService/TaskResetService) **and** every Serilog **Warn/Error** event, re-broadcast by `BroadcastLogSink` (deduped within a 120 s per-message window; SignalR plumbing source-contexts filtered to avoid feedback loops). The sink also buffers **all** levels into `LogRingBuffer` for `GetRecentLogs`.
 

src/ClaudeDo.Worker/Hub/HubBroadcaster.cs

@@ -38,6 +38,9 @@ public sealed class HubBroadcaster : IPrimeBroadcaster, IRefineBroadcaster
     public Task RunCreated(string taskId, int runNumber, bool isRetry) =>
         _hub.Clients.All.SendAsync("RunCreated", taskId, runNumber, isRetry);
 
+    public Task UsageUpdated(UsageSnapshotDto snapshot) =>
+        _hub.Clients.All.SendAsync("UsageUpdated", snapshot);
+
     public Task WorkerLog(string message, WorkerLogLevel level, DateTime timestampUtc) =>
         _hub.Clients.All.SendAsync("WorkerLog", message, level, timestampUtc);
 

src/ClaudeDo.Worker/Hub/WorkerHub.cs

@@ -17,6 +17,8 @@ using ClaudeDo.Worker.Report;
 using ClaudeDo.Worker.Report.Interfaces;
 using ClaudeDo.Worker.Skills;
 using ClaudeDo.Worker.State;
+using ClaudeDo.Worker.Usage;
+using ClaudeDo.Worker.Usage.Interfaces;
 using ClaudeDo.Worker.Worktrees;
 using System.Text.Json;
 using TaskStatus = ClaudeDo.Data.Models.TaskStatus;
@@ -103,6 +105,49 @@ public record OnlineInboxConfigInput(
     string Scopes,
     string RedirectUri);
 
+public record UsageLimitDto(
+    string Kind,
+    string Group,
+    double Percent,
+    string Severity,
+    DateTimeOffset? ResetsAt,
+    string? ScopeModelDisplayName,
+    bool IsActive);
+
+public record UsageSnapshotDto(
+    double? FiveHourPercent,
+    DateTimeOffset? FiveHourResetsAt,
+    double? SevenDayPercent,
+    DateTimeOffset? SevenDayResetsAt,
+    IReadOnlyList<UsageLimitDto> Limits,
+    int FiveHourThresholdPct,
+    int SevenDayThresholdPct,
+    bool IsGateBlocked,
+    string? GateReason,
+    DateTime? FetchedAtUtc,
+    bool IsStale,
+    string? LastError);
+
+public record ModelUsageRowDto(
+    DateOnly Date,
+    string Model,
+    string Scope,
+    long InputTokens,
+    long OutputTokens,
+    long CacheReadTokens,
+    long CacheCreationTokens,
+    int Messages);
+
+public record TaskUsageRowDto(
+    string TaskId,
+    string TaskTitle,
+    string ListId,
+    string ListName,
+    string? Model,
+    int Runs,
+    long TokensIn,
+    long TokensOut);
+
 public sealed class WorkerHub : Microsoft.AspNetCore.SignalR.Hub
 {
     private static readonly string Version =
@@ -136,6 +181,8 @@ public sealed class WorkerHub : Microsoft.AspNetCore.SignalR.Hub
     private readonly IInteractiveLaunchSpecService? _interactiveLaunchSpec;
     private readonly WorktreeManager? _worktreeManager;
     private readonly Data.Git.GitService? _git;
+    private readonly UsageSnapshotBuilder? _usageSnapshotBuilder;
+    private readonly ITranscriptUsageReader? _usageReader;
 
     public WorkerHub(
         QueueService queue,
@@ -165,7 +212,9 @@ public sealed class WorkerHub : Microsoft.AspNetCore.SignalR.Hub
         LogRingBuffer? logBuffer = null,
         IInteractiveLaunchSpecService? interactiveLaunchSpec = null,
         WorktreeManager? worktreeManager = null,
-        Data.Git.GitService? git = null)
+        Data.Git.GitService? git = null,
+        UsageSnapshotBuilder? usageSnapshotBuilder = null,
+        ITranscriptUsageReader? usageReader = null)
     {
         _queue = queue;
         _waker = waker;
@@ -195,6 +244,8 @@ public sealed class WorkerHub : Microsoft.AspNetCore.SignalR.Hub
         _interactiveLaunchSpec = interactiveLaunchSpec;
         _worktreeManager = worktreeManager;
         _git = git;
+        _usageSnapshotBuilder = usageSnapshotBuilder;
+        _usageReader = usageReader;
     }
 
     // Persistence boundary for the session_skills JSON-array columns (task/list/global).
@@ -978,4 +1029,65 @@ public sealed class WorkerHub : Microsoft.AspNetCore.SignalR.Hub
         _onlineTokenStore.Clear();
     }
 #pragma warning restore CA1416
+
+    public Task<UsageSnapshotDto> GetUsageSnapshot() => HubGuard(() =>
+    {
+        if (_usageSnapshotBuilder is null)
+            throw new InvalidOperationException("Usage snapshot builder is not configured.");
+        return _usageSnapshotBuilder.BuildAsync(Context.ConnectionAborted);
+    });
+
+    public Task<IReadOnlyList<ModelUsageRowDto>> GetModelUsage(DateOnly from, DateOnly to) => HubGuard(async () =>
+    {
+        if (_usageReader is null)
+            throw new InvalidOperationException("Transcript usage reader is not configured.");
+        var rows = await _usageReader.ReadAsync(from, to, Context.ConnectionAborted);
+        return (IReadOnlyList<ModelUsageRowDto>)rows
+            .Select(r => new ModelUsageRowDto(
+                r.Date, r.Model, r.Scope == UsageScope.ClaudeDo ? "claudedo" : "other",
+                r.InputTokens, r.OutputTokens, r.CacheReadTokens, r.CacheCreationTokens, r.Messages))
+            .ToList();
+    });
+
+    public async Task<IReadOnlyList<TaskUsageRowDto>> GetTaskUsage(DateOnly from, DateOnly to)
+    {
+        var fromDt = from.ToDateTime(TimeOnly.MinValue);
+        var toDt = to.ToDateTime(TimeOnly.MaxValue);
+
+        await using var ctx = await _dbFactory.CreateDbContextAsync(Context.ConnectionAborted);
+        var runs = await ctx.TaskRuns
+            .Where(r => r.StartedAt != null && r.StartedAt >= fromDt && r.StartedAt <= toDt)
+            .ToListAsync(Context.ConnectionAborted);
+
+        if (runs.Count == 0) return Array.Empty<TaskUsageRowDto>();
+
+        var taskIds = runs.Select(r => r.TaskId).Distinct().ToList();
+        var tasks = await ctx.Tasks.Where(t => taskIds.Contains(t.Id)).ToListAsync(Context.ConnectionAborted);
+        var taskById = tasks.ToDictionary(t => t.Id);
+
+        var listIds = tasks.Select(t => t.ListId).Distinct().ToList();
+        var lists = await ctx.Lists.Where(l => listIds.Contains(l.Id)).ToDictionaryAsync(l => l.Id, Context.ConnectionAborted);
+
+        return runs
+            .Where(r => taskById.ContainsKey(r.TaskId))
+            .GroupBy(r => r.TaskId)
+            .Select(g =>
+            {
+                var task = taskById[g.Key];
+                var listName = lists.TryGetValue(task.ListId, out var list) ? list.Name : "";
+                var latestModel = g.OrderByDescending(r => r.StartedAt).First().Model;
+                return new TaskUsageRowDto(
+                    task.Id,
+                    task.Title,
+                    task.ListId,
+                    listName,
+                    latestModel,
+                    g.Count(),
+                    g.Sum(r => (long)(r.TokensIn ?? 0)),
+                    g.Sum(r => (long)(r.TokensOut ?? 0)));
+            })
+            .OrderByDescending(r => r.TokensIn + r.TokensOut)
+            .Take(100)
+            .ToList();
+    }
 }

src/ClaudeDo.Worker/Program.cs

@@ -206,8 +206,9 @@ builder.Services.AddHttpClient<IUsageClient, ClaudeOAuthUsageClient>(client =>
 {
     client.Timeout = TimeSpan.FromSeconds(5);
 });
-builder.Services.AddHostedService<UsageMonitorService>();
 builder.Services.AddSingleton<IUsageGate, UsageGate>();
+builder.Services.AddSingleton<UsageSnapshotBuilder>();
+builder.Services.AddHostedService<UsageMonitorService>();
 
 // Loopback-only bind. Firewall is irrelevant for 127.0.0.1.
 builder.WebHost.UseUrls($"http://127.0.0.1:{cfg.SignalRPort}");

src/ClaudeDo.Worker/Runner/TaskRunner.cs

@@ -318,6 +318,7 @@ public sealed class TaskRunner
             Prompt = prompt,
             LogPath = logPath,
             StartedAt = DateTime.UtcNow,
+            Model = config.Model,
         };
 
         using (var context = _dbFactory.CreateDbContext())

src/ClaudeDo.Worker/Usage/UsageMonitorService.cs

@@ -1,4 +1,5 @@
 using ClaudeDo.Worker.Config;
+using ClaudeDo.Worker.Hub;
 using ClaudeDo.Worker.Usage.Interfaces;
 
 namespace ClaudeDo.Worker.Usage;
@@ -7,6 +8,8 @@ namespace ClaudeDo.Worker.Usage;
 /// Polls <see cref="IUsageClient"/> on <see cref="WorkerConfig.UsagePollIntervalSeconds"/> and keeps
 /// <see cref="UsageState"/> current. Polls once immediately at startup. A failure is logged as a
 /// warning at most once per distinct error message, to avoid log spam on a persistent outage.
+/// Broadcasts <see cref="HubBroadcaster.UsageUpdated"/> after every poll cycle, success or failure,
+/// so the UI can reflect a stale/blocked state as soon as it happens.
 /// </summary>
 public sealed class UsageMonitorService : BackgroundService
 {
@@ -14,15 +17,20 @@ public sealed class UsageMonitorService : BackgroundService
     private readonly UsageState _state;
     private readonly WorkerConfig _config;
     private readonly ILogger<UsageMonitorService> _logger;
+    private readonly UsageSnapshotBuilder _snapshotBuilder;
+    private readonly HubBroadcaster _broadcaster;
     private string? _lastLoggedError;
 
     public UsageMonitorService(
-        IUsageClient client, UsageState state, WorkerConfig config, ILogger<UsageMonitorService> logger)
+        IUsageClient client, UsageState state, WorkerConfig config, ILogger<UsageMonitorService> logger,
+        UsageSnapshotBuilder snapshotBuilder, HubBroadcaster broadcaster)
     {
         _client = client;
         _state = state;
         _config = config;
         _logger = logger;
+        _snapshotBuilder = snapshotBuilder;
+        _broadcaster = broadcaster;
     }
 
     protected override async Task ExecuteAsync(CancellationToken stoppingToken)
@@ -64,5 +72,8 @@ public sealed class UsageMonitorService : BackgroundService
                 _lastLoggedError = ex.Message;
             }
         }
+
+        var dto = await _snapshotBuilder.BuildAsync(ct);
+        await _broadcaster.UsageUpdated(dto);
     }
 }

src/ClaudeDo.Worker/Usage/UsageSnapshotBuilder.cs

@@ -0,0 +1,63 @@
+using ClaudeDo.Data;
+using ClaudeDo.Data.Repositories;
+using ClaudeDo.Worker.Config;
+using ClaudeDo.Worker.Hub;
+using ClaudeDo.Worker.Usage.Interfaces;
+using Microsoft.EntityFrameworkCore;
+
+namespace ClaudeDo.Worker.Usage;
+
+/// <summary>
+/// Builds the Hub-facing usage snapshot DTO from UsageState + IUsageGate + AppSettings
+/// thresholds. Shared by WorkerHub.GetUsageSnapshot and UsageMonitorService's post-poll
+/// broadcast so both surfaces agree on staleness/threshold logic.
+/// </summary>
+public sealed class UsageSnapshotBuilder
+{
+    private readonly UsageState _state;
+    private readonly IUsageGate _gate;
+    private readonly IDbContextFactory<ClaudeDoDbContext> _dbFactory;
+    private readonly WorkerConfig _cfg;
+
+    public UsageSnapshotBuilder(
+        UsageState state, IUsageGate gate, IDbContextFactory<ClaudeDoDbContext> dbFactory, WorkerConfig cfg)
+    {
+        _state = state;
+        _gate = gate;
+        _dbFactory = dbFactory;
+        _cfg = cfg;
+    }
+
+    public async Task<UsageSnapshotDto> BuildAsync(CancellationToken ct = default)
+    {
+        var snapshot = _state.Snapshot;
+        var lastError = _state.LastError;
+
+        Data.Models.AppSettingsEntity settings;
+        using (var context = _dbFactory.CreateDbContext())
+            settings = await new AppSettingsRepository(context).GetAsync(ct);
+
+        var decision = await _gate.EvaluateAsync(ct);
+
+        var maxAge = TimeSpan.FromSeconds(_cfg.UsagePollIntervalSeconds * 3);
+        var isStale = snapshot is null || lastError is not null || (DateTime.UtcNow - snapshot.FetchedAtUtc) > maxAge;
+
+        var limits = (snapshot?.Limits ?? Array.Empty<UsageLimitRow>())
+            .Select(l => new UsageLimitDto(l.Kind, l.Group, l.Percent, l.Severity, l.ResetsAt, l.ScopeModelDisplayName, l.IsActive))
+            .ToList();
+
+        return new UsageSnapshotDto(
+            snapshot?.FiveHour?.Utilization,
+            snapshot?.FiveHour?.ResetsAt,
+            snapshot?.SevenDay?.Utilization,
+            snapshot?.SevenDay?.ResetsAt,
+            limits,
+            settings.UsageGateFiveHourPct,
+            settings.UsageGateSevenDayPct,
+            decision.IsBlocked,
+            decision.Reason,
+            snapshot?.FetchedAtUtc,
+            isStale,
+            lastError);
+    }
+}