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.

tests/ClaudeDo.Worker.Tests/Hub/TaskUsageHubTests.cs

@@ -0,0 +1,161 @@
+using ClaudeDo.Data.Models;
+using ClaudeDo.Data.Repositories;
+using ClaudeDo.Worker.Hub;
+using ClaudeDo.Worker.Tests.Infrastructure;
+using Xunit;
+using TaskStatus = ClaudeDo.Data.Models.TaskStatus;
+
+namespace ClaudeDo.Worker.Tests.Hub;
+
+public sealed class TaskUsageHubTests : IDisposable
+{
+    private readonly DbFixture _db = new();
+
+    public void Dispose() => _db.Dispose();
+
+    private WorkerHub CreateHub()
+    {
+        var broadcaster = new HubBroadcaster(new CapturingHubContext());
+        var hub = new WorkerHub(
+            null!, null!, null!, null!, broadcaster, _db.CreateFactory(),
+            null!, null!, null!, null!, null!, null!, null!, null!, null!, null!, null!, null!, null!,
+            null!, new ClaudeDo.Worker.Online.OnlineInboxConfig(), new ClaudeDo.Worker.Online.OnlineTokenStore(),
+            new ClaudeDo.Worker.Runner.PendingQuestionRegistry(), null!);
+        hub.Clients = new FakeHubCallerClients(new RecordingClientProxy());
+        hub.Context = new FakeHubCallerContext();
+        return hub;
+    }
+
+    private async Task<string> SeedListAsync(string name = "L")
+    {
+        using var ctx = _db.CreateContext();
+        var listId = Guid.NewGuid().ToString();
+        await new ListRepository(ctx).AddAsync(new ListEntity
+        {
+            Id = listId, Name = name, CreatedAt = DateTime.UtcNow,
+        });
+        return listId;
+    }
+
+    private async Task<string> SeedTaskAsync(string listId, string title = "T")
+    {
+        using var ctx = _db.CreateContext();
+        var taskId = Guid.NewGuid().ToString();
+        await new TaskRepository(ctx).AddAsync(new TaskEntity
+        {
+            Id = taskId, ListId = listId, Title = title, Status = TaskStatus.Done,
+            CreatedAt = DateTime.UtcNow, CommitType = "feat",
+        });
+        return taskId;
+    }
+
+    private async Task SeedRunAsync(
+        string taskId, DateTime startedAt, int? tokensIn, int? tokensOut, string? model, int runNumber = 1)
+    {
+        using var ctx = _db.CreateContext();
+        await new TaskRunRepository(ctx).AddAsync(new TaskRunEntity
+        {
+            Id = Guid.NewGuid().ToString(),
+            TaskId = taskId,
+            RunNumber = runNumber,
+            IsRetry = false,
+            Prompt = "p",
+            StartedAt = startedAt,
+            TokensIn = tokensIn,
+            TokensOut = tokensOut,
+            Model = model,
+        });
+    }
+
+    [Fact]
+    public async Task Groups_multiple_runs_for_same_task_and_sums_tokens()
+    {
+        var listId = await SeedListAsync();
+        var taskId = await SeedTaskAsync(listId, "Task A");
+        var day = new DateTime(2026, 8, 1);
+        await SeedRunAsync(taskId, day, 100, 50, "sonnet", 1);
+        await SeedRunAsync(taskId, day.AddHours(1), 200, 75, "sonnet", 2);
+        await SeedRunAsync(taskId, day.AddHours(2), 300, 25, "sonnet", 3);
+
+        var hub = CreateHub();
+        var rows = await hub.GetTaskUsage(DateOnly.FromDateTime(day), DateOnly.FromDateTime(day));
+
+        var row = Assert.Single(rows);
+        Assert.Equal(taskId, row.TaskId);
+        Assert.Equal(3, row.Runs);
+        Assert.Equal(600, row.TokensIn);
+        Assert.Equal(150, row.TokensOut);
+    }
+
+    [Fact]
+    public async Task Sorts_descending_by_total_tokens()
+    {
+        var listId = await SeedListAsync();
+        var smallTask = await SeedTaskAsync(listId, "Small");
+        var bigTask = await SeedTaskAsync(listId, "Big");
+        var day = new DateTime(2026, 8, 1);
+        await SeedRunAsync(smallTask, day, 10, 10, "haiku");
+        await SeedRunAsync(bigTask, day, 1000, 1000, "opus");
+
+        var hub = CreateHub();
+        var rows = await hub.GetTaskUsage(DateOnly.FromDateTime(day), DateOnly.FromDateTime(day));
+
+        Assert.Equal(2, rows.Count);
+        Assert.Equal(bigTask, rows[0].TaskId);
+        Assert.Equal(smallTask, rows[1].TaskId);
+    }
+
+    [Fact]
+    public async Task Respects_date_range()
+    {
+        var listId = await SeedListAsync();
+        var taskId = await SeedTaskAsync(listId);
+        var inRange = new DateTime(2026, 8, 5);
+        var outOfRange = new DateTime(2026, 8, 1);
+        await SeedRunAsync(taskId, inRange, 100, 100, "sonnet", 1);
+        await SeedRunAsync(taskId, outOfRange, 999, 999, "sonnet", 2);
+
+        var hub = CreateHub();
+        var rows = await hub.GetTaskUsage(DateOnly.FromDateTime(inRange), DateOnly.FromDateTime(inRange));
+
+        var row = Assert.Single(rows);
+        Assert.Equal(1, row.Runs);
+        Assert.Equal(100, row.TokensIn);
+    }
+
+    [Fact]
+    public async Task Null_token_values_are_counted_as_zero_not_excluded()
+    {
+        var listId = await SeedListAsync();
+        var taskId = await SeedTaskAsync(listId);
+        var day = new DateTime(2026, 8, 1);
+        await SeedRunAsync(taskId, day, null, null, null);
+
+        var hub = CreateHub();
+        var rows = await hub.GetTaskUsage(DateOnly.FromDateTime(day), DateOnly.FromDateTime(day));
+
+        var row = Assert.Single(rows);
+        Assert.Equal(1, row.Runs);
+        Assert.Equal(0, row.TokensIn);
+        Assert.Equal(0, row.TokensOut);
+    }
+
+    [Fact]
+    public async Task Caps_at_100_rows()
+    {
+        var listId = await SeedListAsync();
+        var day = new DateTime(2026, 8, 1);
+        for (var i = 0; i < 105; i++)
+        {
+            var taskId = await SeedTaskAsync(listId, $"Task {i}");
+            await SeedRunAsync(taskId, day, i, 0, "sonnet");
+        }
+
+        var hub = CreateHub();
+        var rows = await hub.GetTaskUsage(DateOnly.FromDateTime(day), DateOnly.FromDateTime(day));
+
+        Assert.Equal(100, rows.Count);
+        // Highest token counts (100..4) survive the cap; the lowest (0..3) are dropped.
+        Assert.All(rows, r => Assert.True(r.TokensIn >= 5));
+    }
+}

tests/ClaudeDo.Worker.Tests/Runner/RunModelPersistenceTests.cs

@@ -0,0 +1,105 @@
+using ClaudeDo.Data;
+using ClaudeDo.Data.Git;
+using ClaudeDo.Data.Models;
+using ClaudeDo.Data.Repositories;
+using ClaudeDo.Worker.Config;
+using ClaudeDo.Worker.Hub;
+using ClaudeDo.Worker.Runner;
+using ClaudeDo.Worker.Tests.Infrastructure;
+using Microsoft.Extensions.Logging.Abstractions;
+using TaskStatus = ClaudeDo.Data.Models.TaskStatus;
+using Xunit;
+
+namespace ClaudeDo.Worker.Tests.Runner;
+
+/// Verifies TaskRunner persists the resolved model (task -> list -> AppSettings.DefaultModel)
+/// onto the task_runs row it creates, since the hub's usage-by-model report reads it back from there.
+public sealed class RunModelPersistenceTests : IDisposable
+{
+    private readonly DbFixture _db = new();
+    private readonly string _tempDir;
+    private readonly WorkerConfig _cfg;
+
+    public RunModelPersistenceTests()
+    {
+        _tempDir = Path.Combine(Path.GetTempPath(), $"cd_runmodel_{Guid.NewGuid():N}");
+        Directory.CreateDirectory(_tempDir);
+        _cfg = new WorkerConfig { SandboxRoot = _tempDir, LogRoot = _tempDir };
+    }
+
+    public void Dispose() { _db.Dispose(); try { Directory.Delete(_tempDir, true); } catch { } }
+
+    private TaskRunner BuildRunner()
+    {
+        var dbFactory = _db.CreateFactory();
+        var state = TaskStateServiceBuilder.Build(dbFactory).State;
+        var wt = new WorktreeManager(new GitService(), dbFactory, _cfg, NullLogger<WorktreeManager>.Instance);
+        var fake = new FakeClaudeProcess((_, _, _, _, _) =>
+            Task.FromResult(new RunResult { ExitCode = 0, ResultMarkdown = "ok" }));
+        return new TaskRunner(fake, dbFactory, new HubBroadcaster(new CapturingHubContext()), wt,
+            new ClaudeArgsBuilder(), _cfg, NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(),
+            new AttachmentStore(), new FakeSessionSkillSeeder());
+    }
+
+    private async Task SeedAsync(string? taskModel, string? listModel)
+    {
+        using var ctx = _db.CreateContext();
+        ctx.Lists.Add(new ListEntity { Id = "l1", Name = "L", WorkingDir = null, CreatedAt = DateTime.UtcNow });
+        if (listModel is not null)
+            ctx.ListConfigs.Add(new ListConfigEntity { ListId = "l1", Model = listModel });
+        ctx.Tasks.Add(new TaskEntity
+        {
+            Id = "t1", ListId = "l1", Title = "Task", Status = TaskStatus.Idle, CreatedAt = DateTime.UtcNow,
+            Model = taskModel,
+        });
+        await ctx.SaveChangesAsync();
+    }
+
+    private async Task<string?> RunAndGetPersistedModelAsync()
+    {
+        var runner = BuildRunner();
+        using (var ctx = _db.CreateContext())
+            await runner.RunAsync((await new TaskRepository(ctx).GetByIdAsync("t1"))!, "slot-1", CancellationToken.None);
+
+        using var readCtx = _db.CreateContext();
+        var run = await new TaskRunRepository(readCtx).GetLatestByTaskIdAsync("t1");
+        return run?.Model;
+    }
+
+    [Fact]
+    public async Task Task_level_model_override_is_persisted_on_the_run()
+    {
+        await SeedAsync(taskModel: "opus", listModel: "haiku");
+
+        var persisted = await RunAndGetPersistedModelAsync();
+
+        Assert.Equal("opus", persisted);
+    }
+
+    [Fact]
+    public async Task List_default_model_is_persisted_when_task_has_no_override()
+    {
+        await SeedAsync(taskModel: null, listModel: "haiku");
+
+        var persisted = await RunAndGetPersistedModelAsync();
+
+        Assert.Equal("haiku", persisted);
+    }
+
+    [Fact]
+    public async Task Global_default_model_is_persisted_when_task_and_list_have_no_override()
+    {
+        await SeedAsync(taskModel: null, listModel: null);
+
+        string globalDefault;
+        using (var ctx = _db.CreateContext())
+        {
+            var settings = await new AppSettingsRepository(ctx).GetAsync();
+            globalDefault = settings.DefaultModel;
+        }
+
+        var persisted = await RunAndGetPersistedModelAsync();
+
+        Assert.Equal(globalDefault, persisted);
+    }
+}

tests/ClaudeDo.Worker.Tests/Usage/UsageMonitorServiceTests.cs

@@ -1,12 +1,18 @@
 using ClaudeDo.Worker.Config;
+using ClaudeDo.Worker.Hub;
+using ClaudeDo.Worker.Tests.Infrastructure;
 using ClaudeDo.Worker.Usage;
 using ClaudeDo.Worker.Usage.Interfaces;
 using Microsoft.Extensions.Logging.Abstractions;
 
 namespace ClaudeDo.Worker.Tests.Usage;
 
-public sealed class UsageMonitorServiceTests
+public sealed class UsageMonitorServiceTests : IDisposable
 {
+    private readonly DbFixture _db = new();
+
+    public void Dispose() => _db.Dispose();
+
     private sealed class FakeClient : IUsageClient
     {
         public Queue<Func<UsageSnapshot>> Results { get; } = new();
@@ -20,15 +26,31 @@ public sealed class UsageMonitorServiceTests
         }
     }
 
+    private sealed class FakeGate : IUsageGate
+    {
+        public Task<UsageGateDecision> EvaluateAsync(CancellationToken ct = default) =>
+            Task.FromResult(new UsageGateDecision(false, null));
+    }
+
     private static UsageSnapshot MakeSnapshot() => new(new UsageBucket(1, null), null, [], DateTime.UtcNow);
 
+    private (UsageMonitorService Service, UsageState State, CapturingHubContext Hub) CreateService(FakeClient client, WorkerConfig? cfg = null)
+    {
+        var state = new UsageState();
+        var config = cfg ?? new WorkerConfig();
+        var builder = new UsageSnapshotBuilder(state, new FakeGate(), _db.CreateFactory(), config);
+        var hubContext = new CapturingHubContext();
+        var broadcaster = new HubBroadcaster(hubContext);
+        var service = new UsageMonitorService(client, state, config, NullLogger<UsageMonitorService>.Instance, builder, broadcaster);
+        return (service, state, hubContext);
+    }
+
     [Fact]
     public async Task TickAsync_Success_UpdatesState()
     {
         var client = new FakeClient();
         client.Results.Enqueue(MakeSnapshot);
-        var state = new UsageState();
-        var service = new UsageMonitorService(client, state, new WorkerConfig(), NullLogger<UsageMonitorService>.Instance);
+        var (service, state, _) = CreateService(client);
 
         await service.TickAsync(CancellationToken.None);
 
@@ -41,8 +63,7 @@ public sealed class UsageMonitorServiceTests
     {
         var client = new FakeClient();
         client.Results.Enqueue(() => throw new InvalidOperationException("network unreachable"));
-        var state = new UsageState();
-        var service = new UsageMonitorService(client, state, new WorkerConfig(), NullLogger<UsageMonitorService>.Instance);
+        var (service, state, _) = CreateService(client);
 
         await service.TickAsync(CancellationToken.None);
 
@@ -56,8 +77,7 @@ public sealed class UsageMonitorServiceTests
         var client = new FakeClient();
         client.Results.Enqueue(MakeSnapshot);
         client.Results.Enqueue(() => throw new InvalidOperationException("down"));
-        var state = new UsageState();
-        var service = new UsageMonitorService(client, state, new WorkerConfig(), NullLogger<UsageMonitorService>.Instance);
+        var (service, state, _) = CreateService(client);
 
         await service.TickAsync(CancellationToken.None);
         await service.TickAsync(CancellationToken.None);
@@ -65,4 +85,19 @@ public sealed class UsageMonitorServiceTests
         Assert.NotNull(state.Snapshot);
         Assert.Equal("down", state.LastError);
     }
+
+    [Fact]
+    public async Task TickAsync_BroadcastsUsageUpdated_OnSuccessAndFailure()
+    {
+        var client = new FakeClient();
+        client.Results.Enqueue(MakeSnapshot);
+        client.Results.Enqueue(() => throw new InvalidOperationException("down"));
+        var (service, _, hubContext) = CreateService(client);
+
+        await service.TickAsync(CancellationToken.None);
+        await service.TickAsync(CancellationToken.None);
+
+        var calls = hubContext.Proxy.Calls.Where(c => c.Method == "UsageUpdated").ToList();
+        Assert.Equal(2, calls.Count);
+    }
 }

tests/ClaudeDo.Worker.Tests/Usage/UsageSnapshotBuilderTests.cs

@@ -0,0 +1,145 @@
+using ClaudeDo.Data.Repositories;
+using ClaudeDo.Worker.Config;
+using ClaudeDo.Worker.Tests.Infrastructure;
+using ClaudeDo.Worker.Usage;
+using ClaudeDo.Worker.Usage.Interfaces;
+
+namespace ClaudeDo.Worker.Tests.Usage;
+
+public sealed class UsageSnapshotBuilderTests : IDisposable
+{
+    private readonly DbFixture _db = new();
+
+    public void Dispose() => _db.Dispose();
+
+    private sealed class FakeGate : IUsageGate
+    {
+        private readonly UsageGateDecision _decision;
+        public FakeGate(UsageGateDecision decision) => _decision = decision;
+        public Task<UsageGateDecision> EvaluateAsync(CancellationToken ct = default) => Task.FromResult(_decision);
+    }
+
+    private async Task SetThresholdsAsync(int fiveHourPct, int sevenDayPct)
+    {
+        using var ctx = _db.CreateContext();
+        var repo = new AppSettingsRepository(ctx);
+        var settings = await repo.GetAsync();
+        settings.UsageGateFiveHourPct = fiveHourPct;
+        settings.UsageGateSevenDayPct = sevenDayPct;
+        await repo.UpdateAsync(settings);
+    }
+
+    private UsageSnapshotBuilder CreateBuilder(UsageState state, UsageGateDecision decision, WorkerConfig? cfg = null) =>
+        new(state, new FakeGate(decision), _db.CreateFactory(), cfg ?? new WorkerConfig());
+
+    [Fact]
+    public async Task Maps_buckets_limits_thresholds_and_gate_state()
+    {
+        await SetThresholdsAsync(70, 85);
+
+        var fiveHourReset = DateTimeOffset.UtcNow.AddHours(2);
+        var sevenDayReset = DateTimeOffset.UtcNow.AddDays(3);
+        var limit = new UsageLimitRow("session", "default", 42.5, "warn", fiveHourReset, "sonnet", true);
+        var snapshot = new UsageSnapshot(
+            new UsageBucket(55.5, fiveHourReset),
+            new UsageBucket(88.8, sevenDayReset),
+            new[] { limit },
+            DateTime.UtcNow);
+
+        var state = new UsageState();
+        state.ReportSuccess(snapshot);
+
+        var builder = CreateBuilder(state, new UsageGateDecision(true, "5h-Limit 90% >= 70%"));
+
+        var dto = await builder.BuildAsync();
+
+        Assert.Equal(55.5, dto.FiveHourPercent);
+        Assert.Equal(fiveHourReset, dto.FiveHourResetsAt);
+        Assert.Equal(88.8, dto.SevenDayPercent);
+        Assert.Equal(sevenDayReset, dto.SevenDayResetsAt);
+        Assert.Equal(70, dto.FiveHourThresholdPct);
+        Assert.Equal(85, dto.SevenDayThresholdPct);
+        Assert.True(dto.IsGateBlocked);
+        Assert.Equal("5h-Limit 90% >= 70%", dto.GateReason);
+        Assert.Equal(snapshot.FetchedAtUtc, dto.FetchedAtUtc);
+        Assert.False(dto.IsStale);
+        Assert.Null(dto.LastError);
+
+        var mappedLimit = Assert.Single(dto.Limits);
+        Assert.Equal(limit.Kind, mappedLimit.Kind);
+        Assert.Equal(limit.Group, mappedLimit.Group);
+        Assert.Equal(limit.Percent, mappedLimit.Percent);
+        Assert.Equal(limit.Severity, mappedLimit.Severity);
+        Assert.Equal(limit.ResetsAt, mappedLimit.ResetsAt);
+        Assert.Equal(limit.ScopeModelDisplayName, mappedLimit.ScopeModelDisplayName);
+        Assert.Equal(limit.IsActive, mappedLimit.IsActive);
+    }
+
+    [Fact]
+    public async Task No_snapshot_yields_null_percents_stale_and_not_blocked()
+    {
+        await SetThresholdsAsync(80, 90);
+        var state = new UsageState();
+        var builder = CreateBuilder(state, new UsageGateDecision(false, null));
+
+        var dto = await builder.BuildAsync();
+
+        Assert.Null(dto.FiveHourPercent);
+        Assert.Null(dto.SevenDayPercent);
+        Assert.Empty(dto.Limits);
+        Assert.Null(dto.FetchedAtUtc);
+        Assert.True(dto.IsStale);
+        Assert.False(dto.IsGateBlocked);
+    }
+
+    [Fact]
+    public async Task Snapshot_older_than_4x_poll_interval_is_stale()
+    {
+        await SetThresholdsAsync(80, 90);
+        var cfg = new WorkerConfig { UsagePollIntervalSeconds = 60 };
+        var state = new UsageState();
+        state.ReportSuccess(new UsageSnapshot(
+            new UsageBucket(10, null), null, Array.Empty<UsageLimitRow>(),
+            DateTime.UtcNow.AddSeconds(-4 * 60)));
+
+        var builder = CreateBuilder(state, new UsageGateDecision(false, null), cfg);
+
+        var dto = await builder.BuildAsync();
+
+        Assert.True(dto.IsStale);
+    }
+
+    [Fact]
+    public async Task Fresh_snapshot_is_not_stale()
+    {
+        await SetThresholdsAsync(80, 90);
+        var cfg = new WorkerConfig { UsagePollIntervalSeconds = 60 };
+        var state = new UsageState();
+        state.ReportSuccess(new UsageSnapshot(
+            new UsageBucket(10, null), null, Array.Empty<UsageLimitRow>(),
+            DateTime.UtcNow));
+
+        var builder = CreateBuilder(state, new UsageGateDecision(false, null), cfg);
+
+        var dto = await builder.BuildAsync();
+
+        Assert.False(dto.IsStale);
+    }
+
+    [Fact]
+    public async Task Failed_last_poll_marks_stale_even_with_fresh_snapshot()
+    {
+        await SetThresholdsAsync(80, 90);
+        var state = new UsageState();
+        state.ReportSuccess(new UsageSnapshot(
+            new UsageBucket(10, null), null, Array.Empty<UsageLimitRow>(), DateTime.UtcNow));
+        state.ReportFailure("boom", DateTime.UtcNow);
+
+        var builder = CreateBuilder(state, new UsageGateDecision(false, null));
+
+        var dto = await builder.BuildAsync();
+
+        Assert.True(dto.IsStale);
+        Assert.Equal("boom", dto.LastError);
+    }
+}