Merge claudedo/38394081d47048fea82317c6c52e01a5

tests/ClaudeDo.Data.Tests/UsageGateAndRunModelTests.cs

@@ -117,4 +117,58 @@ public sealed class UsageGateAndRunModelTests : IDisposable
 
         Assert.Null(reloaded.Model);
     }
+
+    [Fact]
+    public async Task TaskRun_cache_token_fields_roundtrip_when_set()
+    {
+        var list = new ListEntity { Id = "l3", Name = "Test", CreatedAt = DateTime.UtcNow };
+        var task = new TaskEntity { Id = "t3", ListId = "l3", Title = "T", Status = TaskStatus.Idle, CreatedAt = DateTime.UtcNow };
+        var run = new TaskRunEntity
+        {
+            Id = "r3",
+            TaskId = "t3",
+            RunNumber = 1,
+            IsRetry = false,
+            Prompt = "do the thing",
+            CacheReadTokens = 12345,
+            CacheWriteTokens = 678,
+        };
+        _ctx.Lists.Add(list);
+        _ctx.Tasks.Add(task);
+        _ctx.TaskRuns.Add(run);
+        await _ctx.SaveChangesAsync();
+
+        await using var freshCtx = new ClaudeDoDbContext(
+            new DbContextOptionsBuilder<ClaudeDoDbContext>().UseSqlite($"Data Source={_dbPath}").Options);
+        var reloaded = await freshCtx.TaskRuns.AsNoTracking().FirstAsync(r => r.Id == "r3");
+
+        Assert.Equal(12345, reloaded.CacheReadTokens);
+        Assert.Equal(678, reloaded.CacheWriteTokens);
+    }
+
+    [Fact]
+    public async Task TaskRun_cache_token_fields_stay_null_when_not_set()
+    {
+        var list = new ListEntity { Id = "l4", Name = "Test", CreatedAt = DateTime.UtcNow };
+        var task = new TaskEntity { Id = "t4", ListId = "l4", Title = "T", Status = TaskStatus.Idle, CreatedAt = DateTime.UtcNow };
+        var run = new TaskRunEntity
+        {
+            Id = "r4",
+            TaskId = "t4",
+            RunNumber = 1,
+            IsRetry = false,
+            Prompt = "do the thing",
+        };
+        _ctx.Lists.Add(list);
+        _ctx.Tasks.Add(task);
+        _ctx.TaskRuns.Add(run);
+        await _ctx.SaveChangesAsync();
+
+        await using var freshCtx = new ClaudeDoDbContext(
+            new DbContextOptionsBuilder<ClaudeDoDbContext>().UseSqlite($"Data Source={_dbPath}").Options);
+        var reloaded = await freshCtx.TaskRuns.AsNoTracking().FirstAsync(r => r.Id == "r4");
+
+        Assert.Null(reloaded.CacheReadTokens);
+        Assert.Null(reloaded.CacheWriteTokens);
+    }
 }

tests/ClaudeDo.Worker.Tests/External/AddSubtaskToolTests.cs

@@ -71,7 +71,7 @@ public sealed class AddSubtaskToolTests : IDisposable
         var argsBuilder = new ClaudeArgsBuilder();
         var state = TaskStateServiceBuilder.Build(dbFactory).State;
         var runner = new TaskRunner(fake, dbFactory, broadcaster, wtManager, argsBuilder, cfg,
-            NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder());
+            NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder(), new FakeTranscriptUsageReader());
         var waker = new ClaudeDo.Worker.Queue.QueueWaker();
         var picker = new ClaudeDo.Worker.Queue.QueuePicker(dbFactory);
         var runCancels = new RunCancellationRegistry();

tests/ClaudeDo.Worker.Tests/External/BatchMcpToolsTests.cs

@@ -93,7 +93,7 @@ public sealed class BatchMcpToolsTests : IDisposable
         var wtManager = new WorktreeManager(new GitService(), dbFactory, cfg, NullLogger<WorktreeManager>.Instance);
         var state = TaskStateServiceBuilder.Build(dbFactory).State;
         var runner = new TaskRunner(new FakeClaudeProcess(), dbFactory, broadcaster, wtManager, new ClaudeArgsBuilder(), cfg,
-            NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder());
+            NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder(), new FakeTranscriptUsageReader());
         var runCancels = new RunCancellationRegistry();
         var overrideSlot = new OverrideSlotService(dbFactory, runner, NullLogger<OverrideSlotService>.Instance, runCancels);
         return new QueueService(dbFactory, runner, cfg, NullLogger<QueueService>.Instance,

tests/ClaudeDo.Worker.Tests/External/ExternalMcpServiceTests.cs

@@ -157,7 +157,7 @@ public sealed class ExternalMcpServiceTests : IDisposable
         var argsBuilder = new ClaudeArgsBuilder();
         var state = TaskStateServiceBuilder.Build(dbFactory).State;
         var runner = new TaskRunner(fake, dbFactory, broadcaster, wtManager, argsBuilder, cfg,
-            NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder());
+            NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder(), new FakeTranscriptUsageReader());
         var waker = new ClaudeDo.Worker.Queue.QueueWaker();
         var picker = new ClaudeDo.Worker.Queue.QueuePicker(dbFactory);
         var runCancels = new RunCancellationRegistry();

tests/ClaudeDo.Worker.Tests/Infrastructure/FakeTranscriptUsageReader.cs

@@ -0,0 +1,18 @@
+using ClaudeDo.Worker.Usage;
+using ClaudeDo.Worker.Usage.Interfaces;
+
+namespace ClaudeDo.Worker.Tests.Infrastructure;
+
+public sealed class FakeTranscriptUsageReader : ITranscriptUsageReader
+{
+    private readonly Dictionary<string, SessionUsageTotals> _totalsBySession = new();
+
+    public void SetTotals(string sessionId, SessionUsageTotals totals) => _totalsBySession[sessionId] = totals;
+
+    public Task<IReadOnlyList<UsageAggregateRow>> ReadAsync(
+        DateOnly start, DateOnly end, CancellationToken ct = default) =>
+        Task.FromResult<IReadOnlyList<UsageAggregateRow>>(Array.Empty<UsageAggregateRow>());
+
+    public Task<SessionUsageTotals?> ReadSessionTotalsAsync(string sessionId, CancellationToken ct = default) =>
+        Task.FromResult(_totalsBySession.TryGetValue(sessionId, out var totals) ? totals : null);
+}

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

@@ -36,7 +36,7 @@ public sealed class ContinueAsyncExceptionTests : IDisposable
         var state = TaskStateServiceBuilder.Build(dbFactory).State;
         var wt = new WorktreeManager(new ClaudeDo.Data.Git.GitService(), dbFactory, _cfg, NullLogger<WorktreeManager>.Instance);
         return new TaskRunner(claude, dbFactory, broadcaster, wt, new ClaudeArgsBuilder(), _cfg,
-            NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder());
+            NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder(), new FakeTranscriptUsageReader());
     }
 
     [Fact]

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

@@ -43,7 +43,7 @@ public sealed class ModelResolutionWireTests : IDisposable
         });
         var runner = new TaskRunner(fake, dbFactory, new HubBroadcaster(new CapturingHubContext()), wt,
             new ClaudeArgsBuilder(), _cfg, NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(),
-            new AttachmentStore(), new FakeSessionSkillSeeder());
+            new AttachmentStore(), new FakeSessionSkillSeeder(), new FakeTranscriptUsageReader());
         getArgs = () => captured!;
         return (runner, Array.Empty<string>());
     }

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

@@ -38,7 +38,7 @@ public sealed class RunModelPersistenceTests : IDisposable
             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());
+            new AttachmentStore(), new FakeSessionSkillSeeder(), new FakeTranscriptUsageReader());
     }
 
     private async Task SeedAsync(string? taskModel, string? listModel)

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

@@ -0,0 +1,165 @@
+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 ClaudeDo.Worker.Usage;
+using ClaudeDo.Worker.Usage.Interfaces;
+using Microsoft.Extensions.Logging.Abstractions;
+using TaskStatus = ClaudeDo.Data.Models.TaskStatus;
+using Xunit;
+
+namespace ClaudeDo.Worker.Tests.Runner;
+
+/// Verifies TaskRunner persists raw token usage (input, output, cache-read, cache-write)
+/// aggregated from the session transcript via ITranscriptUsageReader, instead of the
+/// uncached-only counters the stream-json "result" event carries. See the bug report:
+/// task_runs.tokens_in was off by a factor of ~400,000 because it only read the API's
+/// per-call "input_tokens" field, ignoring cache_read/cache_creation.
+public sealed class RunUsagePersistenceTests : IDisposable
+{
+    private readonly DbFixture _db = new();
+    private readonly string _tempDir;
+    private readonly WorkerConfig _cfg;
+    private readonly FakeTranscriptUsageReader _reader = new();
+
+    public RunUsagePersistenceTests()
+    {
+        _tempDir = Path.Combine(Path.GetTempPath(), $"cd_runusage_{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(IClaudeProcess claude, ITranscriptUsageReader? reader = null)
+    {
+        var dbFactory = _db.CreateFactory();
+        var state = TaskStateServiceBuilder.Build(dbFactory).State;
+        var wt = new WorktreeManager(new GitService(), dbFactory, _cfg, NullLogger<WorktreeManager>.Instance);
+        return new TaskRunner(claude, dbFactory, new HubBroadcaster(new CapturingHubContext()), wt,
+            new ClaudeArgsBuilder(), _cfg, NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(),
+            new AttachmentStore(), new FakeSessionSkillSeeder(), reader ?? _reader);
+    }
+
+    private async Task SeedTaskAsync(string taskId, TaskStatus status = TaskStatus.Idle)
+    {
+        using var ctx = _db.CreateContext();
+        var listId = Guid.NewGuid().ToString();
+        ctx.Lists.Add(new ListEntity { Id = listId, Name = "L", WorkingDir = null, CreatedAt = DateTime.UtcNow });
+        ctx.Tasks.Add(new TaskEntity
+        {
+            Id = taskId, ListId = listId, Title = "Task", Status = status, CreatedAt = DateTime.UtcNow,
+        });
+        await ctx.SaveChangesAsync();
+    }
+
+    [Fact]
+    public async Task First_run_persists_all_four_token_fields_from_the_transcript_reader()
+    {
+        const string taskId = "t1";
+        await SeedTaskAsync(taskId);
+        _reader.SetTotals("sess-a", new SessionUsageTotals(10, 20, 300, 5));
+
+        var fake = new FakeClaudeProcess((_, _, _, _, _) =>
+            Task.FromResult(new RunResult { ExitCode = 0, ResultMarkdown = "ok", SessionId = "sess-a" }));
+        var runner = BuildRunner(fake);
+
+        using (var ctx = _db.CreateContext())
+            await runner.RunAsync((await new TaskRepository(ctx).GetByIdAsync(taskId))!, "slot-1", CancellationToken.None);
+
+        using var verify = _db.CreateContext();
+        var run = await new TaskRunRepository(verify).GetLatestByTaskIdAsync(taskId);
+        Assert.Equal(10, run!.TokensIn);
+        Assert.Equal(20, run.TokensOut);
+        Assert.Equal(300, run.CacheReadTokens);
+        Assert.Equal(5, run.CacheWriteTokens);
+    }
+
+    [Fact]
+    public async Task Resumed_run_on_the_same_session_persists_only_the_delta()
+    {
+        const string taskId = "t2";
+        await SeedTaskAsync(taskId, TaskStatus.WaitingForReview);
+        _reader.SetTotals("sess-b", new SessionUsageTotals(10, 20, 100, 0));
+
+        var fake = new FakeClaudeProcess((_, _, _, _, _) =>
+            Task.FromResult(new RunResult { ExitCode = 0, ResultMarkdown = "ok", SessionId = "sess-b" }));
+        var runner = BuildRunner(fake);
+
+        using (var ctx = _db.CreateContext())
+            await runner.RunAsync((await new TaskRepository(ctx).GetByIdAsync(taskId))!, "slot-1", CancellationToken.None);
+
+        // Cumulative transcript totals grow after the second (resumed) turn.
+        _reader.SetTotals("sess-b", new SessionUsageTotals(30, 50, 250, 10));
+        await runner.ContinueAsync(taskId, "follow up", "slot-1", CancellationToken.None);
+
+        using var verify = _db.CreateContext();
+        var runs = await new TaskRunRepository(verify).GetByTaskIdAsync(taskId);
+        Assert.Equal(2, runs.Count);
+        var run2 = runs.Single(r => r.RunNumber == 2);
+        Assert.Equal(20, run2.TokensIn);
+        Assert.Equal(30, run2.TokensOut);
+        Assert.Equal(150, run2.CacheReadTokens);
+        Assert.Equal(10, run2.CacheWriteTokens);
+    }
+
+    [Fact]
+    public async Task Missing_transcript_totals_leave_token_fields_null_but_run_still_succeeds()
+    {
+        const string taskId = "t3";
+        await SeedTaskAsync(taskId);
+        // No totals registered for "sess-missing" -> reader returns null.
+
+        var fake = new FakeClaudeProcess((_, _, _, _, _) =>
+            Task.FromResult(new RunResult { ExitCode = 0, ResultMarkdown = "ok", SessionId = "sess-missing" }));
+        var runner = BuildRunner(fake);
+
+        using (var ctx = _db.CreateContext())
+            await runner.RunAsync((await new TaskRepository(ctx).GetByIdAsync(taskId))!, "slot-1", CancellationToken.None);
+
+        using var verify = _db.CreateContext();
+        var run = await new TaskRunRepository(verify).GetLatestByTaskIdAsync(taskId);
+        Assert.Null(run!.TokensIn);
+        Assert.Null(run.TokensOut);
+        Assert.Null(run.CacheReadTokens);
+        Assert.Null(run.CacheWriteTokens);
+        Assert.Equal(0, run.ExitCode);
+
+        var task = await new TaskRepository(verify).GetByIdAsync(taskId);
+        Assert.Equal(TaskStatus.WaitingForReview, task!.Status);
+    }
+
+    [Fact]
+    public async Task A_failing_usage_reader_does_not_fail_the_run()
+    {
+        const string taskId = "t4";
+        await SeedTaskAsync(taskId);
+
+        var fake = new FakeClaudeProcess((_, _, _, _, _) =>
+            Task.FromResult(new RunResult { ExitCode = 0, ResultMarkdown = "ok", SessionId = "sess-throws" }));
+        var runner = BuildRunner(fake, new ThrowingUsageReader());
+
+        using (var ctx = _db.CreateContext())
+            await runner.RunAsync((await new TaskRepository(ctx).GetByIdAsync(taskId))!, "slot-1", CancellationToken.None);
+
+        using var verify = _db.CreateContext();
+        var run = await new TaskRunRepository(verify).GetLatestByTaskIdAsync(taskId);
+        Assert.Null(run!.TokensIn);
+        var task = await new TaskRepository(verify).GetByIdAsync(taskId);
+        Assert.Equal(TaskStatus.WaitingForReview, task!.Status);
+    }
+
+    private sealed class ThrowingUsageReader : ITranscriptUsageReader
+    {
+        public Task<IReadOnlyList<UsageAggregateRow>> ReadAsync(
+            DateOnly start, DateOnly end, CancellationToken ct = default) =>
+            throw new IOException("boom");
+
+        public Task<SessionUsageTotals?> ReadSessionTotalsAsync(string sessionId, CancellationToken ct = default) =>
+            throw new IOException("boom");
+    }
+}

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

@@ -40,7 +40,7 @@ public sealed class SkillSeedingWireTests : IDisposable
         var seeder = new FakeSessionSkillSeeder();
         var runner = new TaskRunner(fake, dbFactory, new HubBroadcaster(new CapturingHubContext()), wt,
             new ClaudeArgsBuilder(), _cfg, NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(),
-            new AttachmentStore(), seeder);
+            new AttachmentStore(), seeder, new FakeTranscriptUsageReader());
         return (runner, seeder);
     }
 

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

@@ -45,7 +45,7 @@ public sealed class StandaloneChildrenRoutingTests : IDisposable
         var state = TaskStateServiceBuilder.Build(dbFactory).State;
         var wt = new WorktreeManager(new GitService(), dbFactory, _cfg, NullLogger<WorktreeManager>.Instance);
         var runner = new TaskRunner(fake, dbFactory, broadcaster, wt, new ClaudeArgsBuilder(), _cfg,
-            NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder());
+            NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder(), new FakeTranscriptUsageReader());
 
         using (var ctx = _db.CreateContext())
             await runner.RunAsync((await new TaskRepository(ctx).GetByIdAsync("p1"))!, "slot-1", default, alreadyClaimed: true);
@@ -72,7 +72,7 @@ public sealed class StandaloneChildrenRoutingTests : IDisposable
         var state = TaskStateServiceBuilder.Build(dbFactory).State;
         var wt = new WorktreeManager(new GitService(), dbFactory, _cfg, NullLogger<WorktreeManager>.Instance);
         var runner = new TaskRunner(fake, dbFactory, new HubBroadcaster(new CapturingHubContext()), wt,
-            new ClaudeArgsBuilder(), _cfg, NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder());
+            new ClaudeArgsBuilder(), _cfg, NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder(), new FakeTranscriptUsageReader());
 
         using (var ctx = _db.CreateContext())
             await runner.RunAsync((await new TaskRepository(ctx).GetByIdAsync("solo"))!, "slot-1", default, alreadyClaimed: true);

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

@@ -33,7 +33,7 @@ public sealed class StartRunningGuardTests : IDisposable
         var state = TaskStateServiceBuilder.Build(dbFactory).State;
         var wt = new WorktreeManager(new ClaudeDo.Data.Git.GitService(), dbFactory, _cfg, NullLogger<WorktreeManager>.Instance);
         return new TaskRunner(claude, dbFactory, new HubBroadcaster(new CapturingHubContext()), wt,
-            new ClaudeArgsBuilder(), _cfg, NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder());
+            new ClaudeArgsBuilder(), _cfg, NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder(), new FakeTranscriptUsageReader());
     }
 
     [Fact]

tests/ClaudeDo.Worker.Tests/Services/QueueServiceSlotGuardTests.cs

@@ -56,7 +56,7 @@ public sealed class QueueServiceSlotGuardTests : IDisposable
         var built = TaskStateServiceBuilder.Build(dbFactory);
         var state = built.State;
         var runner = new TaskRunner(fake, dbFactory, broadcaster, wtManager, argsBuilder, _cfg,
-            NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder());
+            NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder(), new FakeTranscriptUsageReader());
         _waker = new QueueWaker();
         var picker = new QueuePicker(dbFactory);
         var overrideSlot = new OverrideSlotService(dbFactory, runner, NullLogger<OverrideSlotService>.Instance, built.RunCancels);

tests/ClaudeDo.Worker.Tests/Services/QueueServiceTests.cs

@@ -61,7 +61,7 @@ public sealed class QueueServiceTests : IDisposable
         var built = TaskStateServiceBuilder.Build(dbFactory);
         var state = built.State;
         var runner = new TaskRunner(fake, dbFactory, broadcaster, wtManager, argsBuilder, _cfg,
-            NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder());
+            NullLogger<TaskRunner>.Instance, state, new TaskRunTokenRegistry(), new AttachmentStore(), new FakeSessionSkillSeeder(), new FakeTranscriptUsageReader());
         _waker = new QueueWaker();
         var picker = new QueuePicker(dbFactory);
         var overrideSlot = new OverrideSlotService(dbFactory, runner, NullLogger<OverrideSlotService>.Instance, built.RunCancels);

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

@@ -199,4 +199,69 @@ public class TranscriptUsageReaderTests : IDisposable
 
         Assert.Empty(result);
     }
+
+    [Fact]
+    public async Task ReadSessionTotalsAsync_Sums_All_Assistant_Messages_In_The_Session_File()
+    {
+        WriteSession("proj", "sess-1.jsonl",
+            AssistantLine(@"C:\Dev\App", "2026-06-01T08:00:00Z", "claude-sonnet-5", 10, 20, 100, 5, requestId: "r1"),
+            AssistantLine(@"C:\Dev\App", "2026-06-01T09:00:00Z", "claude-sonnet-5", 3, 7, 200, 0, requestId: "r2"));
+
+        var reader = MakeReader();
+        var totals = await reader.ReadSessionTotalsAsync("sess-1");
+
+        Assert.NotNull(totals);
+        Assert.Equal(13, totals!.InputTokens);
+        Assert.Equal(27, totals.OutputTokens);
+        Assert.Equal(300, totals.CacheReadTokens);
+        Assert.Equal(5, totals.CacheCreationTokens);
+    }
+
+    [Fact]
+    public async Task ReadSessionTotalsAsync_Skips_Synthetic_Model_Messages()
+    {
+        WriteSession("proj", "sess-2.jsonl",
+            AssistantLine(@"C:\Dev\App", "2026-06-01T08:00:00Z", "claude-sonnet-5", 10, 20, 0, 0, requestId: "r1"),
+            AssistantLine(@"C:\Dev\App", "2026-06-01T09:00:00Z", "<synthetic>", 999, 999, 999, 999, requestId: "r2"));
+
+        var reader = MakeReader();
+        var totals = await reader.ReadSessionTotalsAsync("sess-2");
+
+        Assert.NotNull(totals);
+        Assert.Equal(10, totals!.InputTokens);
+        Assert.Equal(20, totals.OutputTokens);
+    }
+
+    [Fact]
+    public async Task ReadSessionTotalsAsync_Dedupes_By_RequestId_Within_The_Session()
+    {
+        WriteSession("proj", "sess-3.jsonl",
+            AssistantLine(@"C:\Dev\App", "2026-06-01T08:00:00Z", "claude-sonnet-5", 10, 20, 0, 0, requestId: "dup"),
+            AssistantLine(@"C:\Dev\App", "2026-06-01T08:00:01Z", "claude-sonnet-5", 10, 20, 0, 0, requestId: "dup"));
+
+        var reader = MakeReader();
+        var totals = await reader.ReadSessionTotalsAsync("sess-3");
+
+        Assert.NotNull(totals);
+        Assert.Equal(10, totals!.InputTokens);
+        Assert.Equal(20, totals.OutputTokens);
+    }
+
+    [Fact]
+    public async Task ReadSessionTotalsAsync_Returns_Null_When_No_Matching_Transcript_File()
+    {
+        var reader = MakeReader();
+        var totals = await reader.ReadSessionTotalsAsync("does-not-exist");
+
+        Assert.Null(totals);
+    }
+
+    [Fact]
+    public async Task ReadSessionTotalsAsync_Returns_Null_When_ProjectsRoot_Missing()
+    {
+        var reader = new TranscriptUsageReader(_cfg, Path.Combine(_root, "does-not-exist"));
+        var totals = await reader.ReadSessionTotalsAsync("sess-1");
+
+        Assert.Null(totals);
+    }
 }