@deksden-com/dd-flow-cli 0.7.0 → 0.8.0

package/dist/services/usage.js

@@ -1,8 +1,66 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
+import { parseJsonObject } from "../shared/json.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { registerProject, requireProjectByRoot } from "./projects.js";
+export function ingestZcodeUsage(context, input) {
+    return ingestHarnessUsage(context, input, { harness: "zcode-acp", label: "ZCode", idPrefix: "ZUSG", sourceKind: "zcode_session_usage_v1" });
+}
+/** Store a Grok Build ACP usage snapshot. Root snapshots may include child usage. */
+export function ingestGrokUsage(context, input) {
+    return ingestHarnessUsage(context, input, { harness: "grok-acp", label: "Grok Build", idPrefix: "GUSG", sourceKind: "grok_session_usage_v1" });
+}
+/** Store an OpenCode cumulative Session usage snapshot. */
+export function ingestOpenCodeUsage(context, input) {
+    return ingestHarnessUsage(context, input, { harness: "opencode-server", label: "OpenCode", idPrefix: "OUSG", sourceKind: "opencode_session_usage_v1" });
+}
+/** Store an Antigravity CLI cumulative conversation usage snapshot. */
+export function ingestAgyUsage(context, input) {
+    return ingestHarnessUsage(context, input, { harness: "antigravity-cli", label: "Antigravity", idPrefix: "AUSG", sourceKind: "antigravity_cli_session_usage_v1" });
+}
+function ingestHarnessUsage(context, input, harness) {
+    const payload = parseJsonObject(input.stdin || "{}", `${harness.label} usage snapshot`);
+    const usage = object(payload.usage);
+    const providerSessionId = stringValue(payload.provider_session_id) ?? stringValue(usage?.sessionId);
+    if (!usage || !providerSessionId)
+        throw new Error(`${harness.label} usage snapshot requires usage and provider_session_id`);
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    registerProject(context, { root: projectRoot });
+    const project = requireProjectByRoot(context, projectRoot);
+    const observedAt = stringValue(payload.observed_at) ?? context.now();
+    const requestUsageMeasured = stringValue(usage.requestUsageStatus) === "measured";
+    const total = tokenField(usage, requestUsageMeasured ? ["requestTotalTokens"] : ["totalTokens", "total_tokens"]);
+    if (total === undefined || total === null)
+        throw new Error(`${harness.label} usage snapshot has no total token count`);
+    const toolUsage = object(payload.tool_calls);
+    const values = {
+        total,
+        input: tokenField(usage, requestUsageMeasured ? ["requestInputTokens"] : ["inputTokens", "input_tokens"]) ?? null,
+        cacheRead: tokenField(usage, requestUsageMeasured ? ["requestCacheReadTokens"] : ["cacheReadTokens", "cachedReadTokens", "cacheReadInputTokens", "cache_read_input_tokens"]) ?? null,
+        cacheWrite: tokenField(usage, requestUsageMeasured ? ["requestCacheCreationTokens"] : ["cacheCreationTokens", "cacheCreationInputTokens", "cache_write_input_tokens"]) ?? null,
+        output: tokenField(usage, requestUsageMeasured ? ["requestOutputTokens"] : ["outputTokens", "output_tokens"]) ?? null,
+        reasoning: tokenField(usage, requestUsageMeasured ? ["requestReasoningTokens"] : ["reasoningTokens", "reasoning_output_tokens"]) ?? null,
+        requests: tokenField(usage, requestUsageMeasured ? ["requestCount"] : ["modelRequestCount", "modelCalls", "request_count"]) ?? null,
+        errors: tokenField(usage, ["modelErrorCount", "error_count"]) ?? null,
+        toolCalls: toolUsage ? tokenField(toolUsage, ["total"]) ?? null : null,
+        toolFailures: toolUsage ? tokenField(toolUsage, ["failures"]) ?? null : null,
+        toolByName: object(toolUsage?.by_tool) ?? object(toolUsage?.by_name) ?? null
+    };
+    const id = `${harness.idPrefix}-${crypto.createHash("sha256").update(JSON.stringify({ project: project.id, providerSessionId, observedAt, values })).digest("hex")}`;
+    const inserted = context.db.run(`INSERT OR IGNORE INTO harness_usage_snapshots
+      (id, project_id, harness, provider_session_id, daemon_id, observed_at, total_tokens, input_tokens,
+       cache_read_input_tokens, cache_write_input_tokens, output_tokens, reasoning_output_tokens,
+       request_count, error_count, tool_calls, tool_failures, tool_by_name_json, source_kind, usage_scope, completeness, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [id, project.id, harness.harness, providerSessionId, stringValue(payload.daemon_id) ?? null, observedAt, values.total,
+        values.input, values.cacheRead, values.cacheWrite, values.output, values.reasoning, values.requests, values.errors,
+        values.toolCalls, values.toolFailures, values.toolByName ? JSON.stringify(values.toolByName) : null, harness.sourceKind,
+        stringValue(payload.usage_scope) ?? "physical_session", stringValue(payload.completeness) ?? "complete", context.now()]);
+    return { ok: true, observed: inserted.changes === 1, duplicate: inserted.changes === 0, snapshot_id: id, provider_session_id: providerSessionId, harness: harness.harness };
+}
 export function checkpointSessionUsage(context, session, input) {
     const observedAt = context.now();
     const result = readCodexTranscript(session.transcript_path, session.session_id);
+    const source = sourceFacts(session.transcript_path);
     const snapshot = {
         id: `USG-${crypto.randomUUID()}`,
         ...session,
@@ -19,6 +77,10 @@ export function checkpointSessionUsage(context, session, input) {
         output_tokens: result.counter?.usage.output_tokens ?? null,
         reasoning_output_tokens: result.counter?.usage.reasoning_output_tokens ?? null,
         source_kind: "codex_transcript_v1",
+        source_locator: source.locator,
+        source_sha256: source.sha256,
+        source_size_bytes: source.size,
+        source_mtime_ms: source.mtime,
         token_event_at: result.counter?.token_event_at ?? null,
         turn_id: result.counter?.turn_id ?? null,
         turn_attribution: result.counter?.turn_attribution ?? "unavailable",
@@ -27,23 +89,25 @@ export function checkpointSessionUsage(context, session, input) {
         diagnostic_code: result.diagnostic ?? null
     };
     const previous = context.db.get(`SELECT s.*, f.parent_session_id, f.role, f.aspect_id, f.plan_item_id, f.session_kind
-       FROM flow_run_usage_snapshots s
-       LEFT JOIN flow_sessions f ON f.project_id = s.project_id AND f.session_id = s.session_id
+       FROM usage s
+       LEFT JOIN sessions f ON f.project_id = s.project_id AND f.session_id = s.session_id
       WHERE s.project_id = ? AND s.run_id = ? AND s.session_id = ? AND s.checkpoint = ?
       ORDER BY s.observed_at DESC, s.id DESC LIMIT 1`, [session.project_id, session.run_id, session.session_id, input.checkpoint]);
     if (previous && sameUsageSnapshot(previous, snapshot)) {
         return snapshotForOutput(previous);
     }
-    context.db.run(`INSERT INTO flow_run_usage_snapshots
+    context.db.run(`INSERT INTO usage
       (id, project_id, run_id, session_id, checkpoint, stage, stage_attempt, observed_at,
        total_tokens, input_tokens, cached_input_tokens, cache_read_input_tokens, cache_write_input_tokens, uncached_input_tokens,
        output_tokens, reasoning_output_tokens,
-       source_kind, token_event_at, turn_id, turn_attribution, parser_version, extraction_status, diagnostic_code, created_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+       source_kind, source_locator, source_sha256, source_size_bytes, source_mtime_ms,
+       token_event_at, turn_id, turn_attribution, parser_version, extraction_status, diagnostic_code, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
         snapshot.id, snapshot.project_id, snapshot.run_id, snapshot.session_id, snapshot.checkpoint, snapshot.stage,
         snapshot.stage_attempt, snapshot.observed_at, snapshot.total_tokens, snapshot.input_tokens,
         snapshot.cached_input_tokens, snapshot.cache_read_input_tokens, snapshot.cache_write_input_tokens,
         snapshot.uncached_input_tokens, snapshot.output_tokens, snapshot.reasoning_output_tokens, snapshot.source_kind,
+        snapshot.source_locator, snapshot.source_sha256, snapshot.source_size_bytes, snapshot.source_mtime_ms,
         snapshot.token_event_at, snapshot.turn_id, snapshot.turn_attribution, snapshot.parser_version,
         snapshot.extraction_status, snapshot.diagnostic_code, observedAt
     ]);
@@ -51,22 +115,400 @@ export function checkpointSessionUsage(context, session, input) {
 }
 export function checkpointRunUsage(context, input) {
     const sessions = context.db.all(`SELECT session_id, project_id, run_id, transcript_path, parent_session_id, role, aspect_id, plan_item_id, session_kind
-     FROM flow_sessions WHERE project_id = ? AND run_id = ?`, [input.projectId, input.runId]);
+     FROM sessions WHERE project_id = ? AND run_id = ?`, [input.projectId, input.runId]);
     return sessions.map((session) => checkpointSessionUsage(context, session, input));
 }
 export function usageForRun(context, input) {
+    return usageReport(context, input, true);
+}
+/** Reads saved checkpoints only; reporting must not create a new measurement. */
+export function storedUsageForRun(context, input) {
+    return usageReport(context, input, false);
+}
+/**
+ * The vNext controller owns this operation. It rereads source transcripts and
+ * replaces the current RUN projection; it does not build a checkpoint ledger.
+ */
+export function recalculateRunUsage(context, input) {
+    const observedAt = context.now();
+    const runRow = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [input.projectId, input.runId]);
+    const runCompletedAt = runRow ? terminalTimestamp(runRow.index_json) : null;
+    const accountingAt = input.stage?.completedAt ?? runCompletedAt ?? observedAt;
+    const links = context.db.all(`SELECT ws.id, ws.work_id, ws.session_id, ws.created_at, ws.completed_at,
+            w.project_id, s.harness, s.transcript_path, s.parent_session_id, s.agent_id, s.provider_session_id
+       FROM work_sessions ws
+       JOIN works w ON w.work_id = ws.work_id
+       LEFT JOIN sessions s ON s.project_id = w.project_id AND s.session_id = ws.session_id
+      WHERE w.project_id = ? AND w.run_id = ?
+      ORDER BY ws.created_at, ws.id`, [input.projectId, input.runId]).filter((link) => (!input.sessionId || link.session_id === input.sessionId) && (!input.stage || overlapsStage(link, input.stage, observedAt)))
+        .map((link) => input.stage ? clipToStage(link, input.stage, observedAt) : link);
+    if (input.sessionId && links.length === 0)
+        throw new Error(`Session is not associated with RUN: ${input.sessionId}`);
+    const final = !context.db.get("SELECT 1 FROM works WHERE project_id = ? AND run_id = ? AND status IN ('created', 'running') LIMIT 1", [input.projectId, input.runId]);
+    const rows = usageRowsForPhysicalSessions(context, links, accountingAt, input.stage);
+    const totals = emptyUsage();
+    for (const row of rows)
+        if (row.tokens)
+            addUsage(totals, row.tokens);
+    const settledSessions = settledRunSessions(context, links, observedAt);
+    const unsettledSessions = [...new Set(links.map((link) => link.session_id))].filter((sessionId) => !settledSessions.some((session) => session.session_id === sessionId));
+    const usageFinal = final && unsettledSessions.length === 0;
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        context.db.run("DELETE FROM usage WHERE project_id = ? AND run_id = ?", [input.projectId, input.runId]);
+        for (const row of rows) {
+            context.db.run(`INSERT INTO usage (id, project_id, run_id, session_id, checkpoint, stage, stage_attempt, observed_at, total_tokens, input_tokens, cached_input_tokens, cache_read_input_tokens, cache_write_input_tokens, uncached_input_tokens, output_tokens, reasoning_output_tokens, source_kind, source_locator, source_sha256, source_size_bytes, source_mtime_ms, token_event_at, turn_id, turn_attribution, parser_version, extraction_status, diagnostic_code, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, 'windowed_work_session', 1, ?, ?, ?)`, [
+                `USG-${crypto.randomUUID()}`, input.projectId, input.runId, row.session_id, usageFinal ? "final" : "provisional", input.stage?.name ?? null, row.observed_at,
+                row.tokens?.total_tokens ?? null, row.tokens?.input_tokens ?? null, row.tokens?.cache_read_input_tokens ?? null,
+                row.tokens?.cache_read_input_tokens ?? null, row.tokens?.cache_write_input_tokens ?? null, row.tokens?.uncached_input_tokens ?? null,
+                row.tokens?.output_tokens ?? null, row.tokens?.reasoning_output_tokens ?? null, row.source_kind, row.source.locator, row.source.sha256, row.source.size, row.source.mtime,
+                row.status, row.diagnostic, observedAt
+            ]);
+        }
+        for (const session of settledSessions) {
+            context.db.run(`UPDATE sessions
+            SET status = 'stopped', stop_reason = 'provider_turn_complete', updated_at = ?, stopped_at = ?
+          WHERE project_id = ? AND run_id = ? AND session_id = ?
+            AND status = 'idle'
+            AND NOT EXISTS (SELECT 1 FROM work_sessions WHERE session_id = ? AND status = 'running')`, [observedAt, session.completed_at, input.projectId, input.runId, session.session_id, session.session_id]);
+        }
+        context.db.exec("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    return {
+        ok: true,
+        schema_id: "dd-flow/run-usage@2",
+        run_id: input.runId,
+        status: usageFinal ? "final" : "provisional",
+        scope: input.stage ? { kind: "stage", stage: input.stage.name, started_at: input.stage.startedAt, completed_at: input.stage.completedAt } : { kind: "run" },
+        observed_at: observedAt,
+        totals: outputUsageTotals(totals),
+        sessions: rows,
+        session_reconciliation: {
+            stopped: settledSessions.map((session) => session.session_id),
+            unsettled: unsettledSessions
+        },
+        tool_calls: toolCallsForLinks(context, links, accountingAt),
+        coverage: rows.reduce((coverage, row) => ({ ...coverage, [row.status]: (coverage[row.status] ?? 0) + 1 }), {})
+    };
+}
+function overlapsStage(link, stage, observedAt) {
+    const linkStart = Date.parse(link.created_at);
+    const linkEnd = Date.parse(link.completed_at ?? observedAt);
+    const stageStart = Date.parse(stage.startedAt);
+    const stageEnd = Date.parse(stage.completedAt ?? observedAt);
+    return (!Number.isFinite(linkEnd) || !Number.isFinite(stageStart) || linkEnd >= stageStart)
+        && (!Number.isFinite(linkStart) || !Number.isFinite(stageEnd) || linkStart <= stageEnd);
+}
+function clipToStage(link, stage, observedAt) {
+    const startedAt = Date.parse(link.created_at) < Date.parse(stage.startedAt) ? stage.startedAt : link.created_at;
+    const naturalEnd = link.completed_at ?? observedAt;
+    const stageEnd = stage.completedAt ?? observedAt;
+    const completedAt = Date.parse(naturalEnd) > Date.parse(stageEnd) ? stageEnd : naturalEnd;
+    return { ...link, created_at: startedAt, completed_at: completedAt };
+}
+function toolCallsForLinks(context, links, observedAt) {
+    const result = { status: "unavailable", total: 0, failures: 0, by_tool: {}, observed_sessions: 0, unavailable_sessions: [] };
+    const sessions = new Map();
+    for (const link of links)
+        sessions.set(link.session_id, [...(sessions.get(link.session_id) ?? []), link]);
+    for (const [sessionId, windows] of sessions) {
+        const first = windows[0];
+        const parsed = isExternalHarness(first.harness)
+            ? readHarnessToolCallsWindow(context, first.harness, first.project_id, first.provider_session_id, windows.map((item) => item.created_at).sort()[0], windows.map((item) => item.completed_at ?? observedAt).sort().at(-1), observedAt)
+            : readToolCallsForWindows(first.transcript_path, sessionId, windows, observedAt);
+        if (!parsed) {
+            result.unavailable_sessions.push(sessionId);
+            continue;
+        }
+        result.observed_sessions += 1;
+        result.total += parsed.total;
+        result.failures += parsed.failures;
+        for (const [name, count] of Object.entries(parsed.by_tool))
+            result.by_tool[name] = (result.by_tool[name] ?? 0) + count;
+    }
+    result.status = result.observed_sessions === 0 ? "unavailable" : result.unavailable_sessions.length ? "partial" : "measured";
+    return result;
+}
+function isExternalHarness(harness) { return harness === "zcode-acp" || harness === "grok-acp" || harness === "opencode-server" || harness === "antigravity-cli"; }
+function harnessSourceKind(harness) {
+    return harness === "grok-acp" ? "grok_session_usage_v1" : harness === "zcode-acp" ? "zcode_session_usage_v1" : harness === "antigravity-cli" ? "antigravity_cli_session_usage_v1" : "opencode_session_usage_v1";
+}
+function readHarnessToolCallsWindow(context, harness, projectId, providerSessionId, startedAt, endedAt, observedAt) {
+    if (!providerSessionId)
+        return null;
+    const snapshots = context.db.all(`SELECT observed_at, tool_calls, tool_failures, tool_by_name_json FROM harness_usage_snapshots
+      WHERE project_id = ? AND harness = ? AND provider_session_id = ? AND observed_at <= ?
+      ORDER BY observed_at, id`, [projectId, harness, providerSessionId, observedAt]);
+    const last = snapshots.find((snapshot) => Date.parse(snapshot.observed_at) > Date.parse(endedAt))
+        ?? snapshots.filter((snapshot) => Date.parse(snapshot.observed_at) <= Date.parse(endedAt)).at(-1);
+    const before = snapshots.filter((snapshot) => Date.parse(snapshot.observed_at) <= Date.parse(startedAt)).at(-1);
+    if (!last || !before || last === before || last.tool_calls === null || before.tool_calls === null)
+        return null;
+    const parse = (value) => {
+        if (!value)
+            return {};
+        try {
+            return Object.fromEntries(Object.entries(JSON.parse(value)).filter((entry) => typeof entry[1] === "number"));
+        }
+        catch {
+            return {};
+        }
+    };
+    const latestByTool = parse(last.tool_by_name_json);
+    const baselineByTool = parse(before.tool_by_name_json);
+    const byTool = {};
+    for (const name of Object.keys(latestByTool).sort()) {
+        const count = Math.max(0, latestByTool[name] - (baselineByTool[name] ?? 0));
+        if (count > 0)
+            byTool[name] = count;
+    }
+    return { total: Math.max(0, last.tool_calls - before.tool_calls), failures: Math.max(0, (last.tool_failures ?? 0) - (before.tool_failures ?? 0)), by_tool: byTool };
+}
+function readToolCallsForWindows(transcriptPath, expectedSessionId, windows, observedAt) {
+    if (!transcriptPath || !fs.existsSync(transcriptPath))
+        return null;
+    try {
+        let sessionId;
+        let total = 0;
+        let failures = 0;
+        const byTool = {};
+        for (const line of fs.readFileSync(transcriptPath, "utf8").split(/\r?\n/)) {
+            if (!line.trim())
+                continue;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const payload = object(event.payload);
+            if (event.type === "session_meta")
+                sessionId ??= stringValue(payload?.id);
+            if (event.type !== "response_item" || !payload)
+                continue;
+            const eventAt = stringValue(event.timestamp);
+            if (eventAt && !windows.some((window) => eventInsideWindow(eventAt, window, observedAt)))
+                continue;
+            const type = stringValue(payload.type);
+            if (type === "function_call" || type === "custom_tool_call") {
+                const name = stringValue(payload.name) ?? "unknown";
+                byTool[name] = (byTool[name] ?? 0) + 1;
+                total += 1;
+            }
+            if ((type === "function_call_output" || type === "custom_tool_call_output") && outputIndicatesFailure(payload))
+                failures += 1;
+        }
+        if (sessionId && sessionId !== expectedSessionId)
+            return null;
+        return { total, failures, by_tool: Object.fromEntries(Object.entries(byTool).sort(([left], [right]) => left.localeCompare(right))) };
+    }
+    catch {
+        return null;
+    }
+}
+function eventInsideWindow(eventAt, window, observedAt) {
+    const at = Date.parse(eventAt);
+    const start = Date.parse(window.created_at);
+    const end = Date.parse(window.completed_at ?? observedAt);
+    return Number.isFinite(at) && (!Number.isFinite(start) || at >= start) && (!Number.isFinite(end) || at <= end);
+}
+function outputIndicatesFailure(payload) {
+    if (payload.error === true || typeof payload.error === "string")
+        return true;
+    return containsFailure(payload.output);
+}
+function containsFailure(value) {
+    if (Array.isArray(value))
+        return value.some(containsFailure);
+    if (typeof value === "string") {
+        if (/(?:^|\n)exit=(?:[1-9]\d*)\b|Process exited with code [1-9]\d*/.test(value))
+            return true;
+        const trimmed = value.trim();
+        if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+            try {
+                return containsFailure(JSON.parse(trimmed));
+            }
+            catch {
+                return false;
+            }
+        }
+        return false;
+    }
+    const item = object(value);
+    if (!item)
+        return false;
+    if (item.ok === false || item.is_error === true || item.isError === true || item.error === true || typeof item.error === "string")
+        return true;
+    if (typeof item.exit_code === "number" && item.exit_code !== 0)
+        return true;
+    return Object.values(item).some(containsFailure);
+}
+/** RUN accounting belongs to the physical provider Session, not to every Work link. */
+function usageRowsForPhysicalSessions(context, links, observedAt, stage) {
+    const sessions = new Map();
+    for (const link of links)
+        sessions.set(link.session_id, [...(sessions.get(link.session_id) ?? []), link]);
+    const physicalSessions = [...sessions.values()].filter((sessionLinks) => {
+        const link = sessionLinks[0];
+        if (!link.parent_session_id)
+            return true;
+        const parent = links.find((candidate) => candidate.session_id === link.parent_session_id);
+        return !parent || !hasInclusiveUsageSnapshot(context, parent.project_id, parent.harness, parent.provider_session_id, observedAt);
+    });
+    return physicalSessions.map((sessionLinks) => {
+        const link = sessionLinks[0];
+        const startedAt = stage?.startedAt ?? sessionLinks.map((item) => item.created_at).sort()[0];
+        const completedTurn = stage ? null : completedProviderTurn(link.transcript_path, link.session_id);
+        const naturalEnd = isExternalHarness(link.harness)
+            ? observedAt
+            : completedTurn?.completed_at ?? sessionLinks.map((item) => item.completed_at ?? observedAt).sort().at(-1);
+        const endedAt = stage?.completedAt ?? (Date.parse(naturalEnd) > Date.parse(observedAt) ? observedAt : naturalEnd);
+        const harnessUsage = isExternalHarness(link.harness)
+            ? readHarnessUsageWindow(context, link.harness, link.project_id, link.provider_session_id, startedAt, endedAt, observedAt)
+            : null;
+        const parsed = harnessUsage ?? readCodexTranscriptWindow(link.transcript_path, link.session_id, startedAt, endedAt);
+        return {
+            work_session_id: link.id,
+            work_id: link.work_id,
+            session_id: link.session_id,
+            provider_session_id: link.provider_session_id,
+            agent_id: link.agent_id,
+            parent_session_id: link.parent_session_id,
+            status: parsed.status,
+            diagnostic: parsed.diagnostic ?? null,
+            observed_at: observedAt,
+            tokens: parsed.counter?.usage ?? null,
+            source: harnessUsage ? { locator: link.provider_session_id ? `${link.harness}:${link.provider_session_id}` : null, sha256: null, size: null, mtime: null } : sourceFacts(link.transcript_path),
+            source_kind: harnessUsage ? harnessSourceKind(link.harness) : "codex_transcript_v1"
+        };
+    });
+}
+function hasInclusiveUsageSnapshot(context, projectId, harness, providerSessionId, observedAt) {
+    if (!providerSessionId)
+        return false;
+    return Boolean(context.db.get("SELECT 1 FROM harness_usage_snapshots WHERE project_id = ? AND harness = ? AND provider_session_id = ? AND usage_scope = 'execution_tree_inclusive' AND observed_at <= ? LIMIT 1", [projectId, harness, providerSessionId, observedAt]));
+}
+function readHarnessUsageWindow(context, harness, projectId, providerSessionId, startedAt, endedAt, observedAt) {
+    if (!providerSessionId)
+        return { status: "not_observable", diagnostic: "provider_session_id_missing" };
+    const snapshots = context.db.all(`SELECT observed_at, total_tokens, input_tokens, cache_read_input_tokens, cache_write_input_tokens, output_tokens, reasoning_output_tokens
+       FROM harness_usage_snapshots
+      WHERE project_id = ? AND harness = ? AND provider_session_id = ? AND observed_at <= ?
+      ORDER BY observed_at, id`, [projectId, harness, providerSessionId, observedAt]);
+    const last = snapshots.find((snapshot) => Date.parse(snapshot.observed_at) > Date.parse(endedAt))
+        ?? snapshots.filter((snapshot) => Date.parse(snapshot.observed_at) <= Date.parse(endedAt)).at(-1);
+    const before = snapshots.filter((snapshot) => Date.parse(snapshot.observed_at) <= Date.parse(startedAt)).at(-1);
+    if (!last || !before || last === before)
+        return { status: "not_yet_emitted", diagnostic: `${harness}_usage_window_incomplete` };
+    const delta = (value, baseline) => value === null || baseline === null ? null : Math.max(0, value - baseline);
+    const input = delta(last.input_tokens, before.input_tokens);
+    const cacheRead = delta(last.cache_read_input_tokens, before.cache_read_input_tokens);
+    return {
+        status: "measured",
+        counter: {
+            usage: {
+                total_tokens: Math.max(0, last.total_tokens - before.total_tokens),
+                input_tokens: input,
+                cache_read_input_tokens: cacheRead,
+                cache_write_input_tokens: delta(last.cache_write_input_tokens, before.cache_write_input_tokens),
+                uncached_input_tokens: input === null || cacheRead === null ? null : Math.max(0, input - cacheRead),
+                output_tokens: delta(last.output_tokens, before.output_tokens),
+                reasoning_output_tokens: delta(last.reasoning_output_tokens, before.reasoning_output_tokens)
+            },
+            token_event_at: last.observed_at,
+            turn_id: null,
+            turn_attribution: "unavailable"
+        }
+    };
+}
+function terminalTimestamp(indexJson) {
+    try {
+        const index = JSON.parse(indexJson);
+        return ["done", "blocked", "cancelled", "failed"].includes(index.status ?? "") && typeof index.completed_at === "string" ? index.completed_at : null;
+    }
+    catch {
+        return null;
+    }
+}
+function settledRunSessions(context, links, observedAt) {
+    const sessions = new Map();
+    for (const link of links)
+        sessions.set(link.session_id, [...(sessions.get(link.session_id) ?? []), link]);
+    return [...sessions.entries()].flatMap(([sessionId, sessionLinks]) => {
+        if (sessionLinks.some((link) => !link.completed_at))
+            return [];
+        const link = sessionLinks[0];
+        const latestWorkFinish = sessionLinks.map((item) => Date.parse(item.completed_at)).filter(Number.isFinite).sort((left, right) => right - left)[0];
+        if (isExternalHarness(link.harness) && link.provider_session_id && latestWorkFinish !== undefined) {
+            const snapshot = context.db.get(`SELECT observed_at FROM harness_usage_snapshots
+          WHERE project_id = ? AND harness = ? AND provider_session_id = ?
+            AND observed_at >= ? AND observed_at <= ?
+          ORDER BY observed_at DESC, id DESC LIMIT 1`, [link.project_id, link.harness, link.provider_session_id, new Date(latestWorkFinish).toISOString(), observedAt]);
+            return snapshot ? [{ session_id: sessionId, completed_at: snapshot.observed_at }] : [];
+        }
+        const completed = completedProviderTurn(sessionLinks[0].transcript_path, sessionId);
+        if (!completed || (latestWorkFinish !== undefined && Date.parse(completed.completed_at) < latestWorkFinish))
+            return [];
+        return [{ session_id: sessionId, completed_at: completed.completed_at }];
+    });
+}
+/** The final lifecycle event must be task_complete; a later task_started means the Session is live again. */
+function completedProviderTurn(transcriptPath, expectedSessionId) {
+    if (!transcriptPath || !fs.existsSync(transcriptPath))
+        return null;
+    try {
+        let sessionId;
+        let latestLifecycle = null;
+        for (const line of fs.readFileSync(transcriptPath, "utf8").split(/\r?\n/)) {
+            if (!line.trim())
+                continue;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const payload = object(event.payload);
+            if (event.type === "session_meta")
+                sessionId ??= stringValue(payload?.id);
+            const type = event.type === "event_msg" ? stringValue(payload?.type) : null;
+            const at = stringValue(event.timestamp);
+            if ((type === "task_started" || type === "task_complete") && at)
+                latestLifecycle = { type, at };
+        }
+        if (sessionId && sessionId !== expectedSessionId)
+            return null;
+        return latestLifecycle?.type === "task_complete" ? { completed_at: latestLifecycle.at } : null;
+    }
+    catch {
+        return null;
+    }
+}
+function usageReport(context, input, refresh) {
     const sessions = context.db.all(`SELECT DISTINCT session_id, project_id, ? AS run_id, transcript_path, parent_session_id, role, aspect_id, plan_item_id, session_kind
-     FROM flow_sessions WHERE project_id = ? AND run_id = ?
+     FROM sessions WHERE project_id = ? AND run_id = ?
      UNION
      SELECT DISTINCT f.session_id, f.project_id, ? AS run_id, f.transcript_path, f.parent_session_id, f.role, f.aspect_id, f.plan_item_id, f.session_kind
-     FROM flow_session_segments s JOIN flow_sessions f ON f.project_id = s.project_id AND f.session_id = s.session_id
+     FROM flow_session_segments s JOIN sessions f ON f.project_id = s.project_id AND f.session_id = s.session_id
      WHERE s.project_id = ? AND s.run_id = ?`, [input.runId, input.projectId, input.runId, input.runId, input.projectId, input.runId]);
-    const refreshed = sessions.map((session) => checkpointSessionUsage(context, session, { checkpoint: "manual_sync" }));
+    const selectedSessions = input.sessionId ? sessions.filter((session) => session.session_id === input.sessionId) : sessions;
+    if (input.sessionId && selectedSessions.length === 0) {
+        throw new Error(`Session is not associated with RUN: ${input.sessionId}`);
+    }
+    const refreshed = refresh ? selectedSessions.map((session) => checkpointSessionUsage(context, session, { checkpoint: "manual_sync" })) : [];
     const rows = context.db.all(`SELECT s.*, f.parent_session_id, f.role, f.aspect_id, f.plan_item_id, f.session_kind
-     FROM flow_run_usage_snapshots s
-     LEFT JOIN flow_sessions f ON f.project_id = s.project_id AND f.session_id = s.session_id
+     FROM usage s
+     LEFT JOIN sessions f ON f.project_id = s.project_id AND f.session_id = s.session_id
      WHERE s.project_id = ? AND s.run_id = ? ORDER BY s.session_id, s.observed_at, s.id`, [input.projectId, input.runId]);
-    const deltas = usageDeltas(rows);
+    const selectedRows = input.sessionId ? rows.filter((row) => row.session_id === input.sessionId) : rows;
+    const deltas = usageDeltas(selectedRows);
     const segments = context.db.all(`SELECT id, session_id, run_id, protocol_id, started_at, ended_at, cwd, tool_name
      FROM flow_session_segments WHERE project_id = ? AND run_id = ? ORDER BY started_at, id`, [input.projectId, input.runId]);
     const supported = new Set(["session", "role", "aspect", "plan-item", "stage", "protocol"]);
@@ -87,13 +529,14 @@ export function usageForRun(context, input) {
         ok: true,
         schema_id: "dd-flow/run-usage@1",
         run_id: input.runId,
-        source: { kind: "codex_transcript_v1", parser_version: 1, refreshed_sessions: refreshed.length },
-        sessions: sessions.map((session) => ({
+        source: { kind: "codex_transcript_v1", parser_version: 1, refreshed_sessions: refreshed.length, checkpoint_source: refresh ? "refreshed" : "stored" },
+        sessions: selectedSessions.map((session) => ({
             session_id: session.session_id, parent_session_id: session.parent_session_id ?? null, role: session.role ?? null,
             aspect_id: session.aspect_id ?? null, plan_item_id: session.plan_item_id ?? null, session_kind: session.session_kind ?? null
         })),
         groups: [...groups.entries()].map(([key, group]) => ({ key, ...group, tokens: outputUsageTotals(group.tokens) })),
         deltas,
+        tool_calls: toolCallsForSessions(sessions),
         segments: segments.map((segment) => ({
             segment_id: segment.id,
             session_id: segment.session_id,
@@ -101,11 +544,70 @@ export function usageForRun(context, input) {
             protocol_id: segment.protocol_id,
             started_at: segment.started_at,
             ended_at: segment.ended_at,
-            usage: segmentUsage(context, sessions.find((session) => session.session_id === segment.session_id), segment)
+            usage: segmentUsage(context, selectedSessions.find((session) => session.session_id === segment.session_id), segment)
         })),
-        coverage: coverageForRows(rows)
+        coverage: coverageForRows(selectedRows)
     };
 }
+function toolCallsForSessions(sessions) {
+    const result = { status: "unavailable", total: 0, failures: 0, by_tool: {}, observed_sessions: 0, unavailable_sessions: [] };
+    for (const session of sessions) {
+        const parsed = readToolCalls(session.transcript_path, session.session_id);
+        if (!parsed) {
+            result.unavailable_sessions.push(session.session_id);
+            continue;
+        }
+        result.observed_sessions += 1;
+        result.total += parsed.total;
+        result.failures += parsed.failures;
+        for (const [name, count] of Object.entries(parsed.by_tool))
+            result.by_tool[name] = (result.by_tool[name] ?? 0) + count;
+    }
+    result.status = result.observed_sessions === 0 ? "unavailable" : result.unavailable_sessions.length === 0 ? "measured" : "partial";
+    return result;
+}
+function readToolCalls(transcriptPath, expectedSessionId) {
+    if (!transcriptPath || !fs.existsSync(transcriptPath))
+        return null;
+    try {
+        let sessionId;
+        const byTool = {};
+        let total = 0;
+        let failures = 0;
+        for (const line of fs.readFileSync(transcriptPath, "utf8").split(/\r?\n/)) {
+            if (!line.trim())
+                continue;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const payload = object(event.payload);
+            if (!payload)
+                continue;
+            if (event.type === "session_meta")
+                sessionId = stringValue(payload.id) ?? sessionId;
+            if (event.type !== "response_item")
+                continue;
+            const type = stringValue(payload.type);
+            if (type === "function_call" || type === "custom_tool_call") {
+                const name = stringValue(payload.name) ?? "unknown";
+                byTool[name] = (byTool[name] ?? 0) + 1;
+                total += 1;
+            }
+            if ((type === "function_call_output" || type === "custom_tool_call_output") && outputIndicatesFailure(payload))
+                failures += 1;
+        }
+        if (sessionId && sessionId !== expectedSessionId)
+            return null;
+        return { total, failures, by_tool: Object.fromEntries(Object.entries(byTool).sort(([left], [right]) => left.localeCompare(right))) };
+    }
+    catch {
+        return null;
+    }
+}
 function segmentUsage(context, session, segment) {
     if (!session)
         return { status: "unavailable", diagnostic: "session_record_missing" };
@@ -134,7 +636,7 @@ function readCodexTranscript(transcriptPath, expectedSessionId) {
             }
             const payload = object(event.payload);
             if (event.type === "session_meta")
-                sessionId = stringValue(payload?.id) ?? sessionId;
+                sessionId ??= stringValue(payload?.id);
             if (event.type === "event_msg" && payload?.type === "task_started")
                 nearestTurn = stringValue(payload.turn_id) ?? nearestTurn;
             if (event.type !== "event_msg" || payload?.type !== "token_count")
@@ -195,7 +697,7 @@ function readTranscriptEvents(transcriptPath, expectedSessionId) {
             }
             const payload = object(event.payload);
             if (event.type === "session_meta")
-                sessionId = stringValue(payload?.id) ?? sessionId;
+                sessionId ??= stringValue(payload?.id);
             if (event.type === "event_msg" && payload?.type === "task_started")
                 nearestTurn = stringValue(payload.turn_id) ?? nearestTurn;
             if (event.type !== "event_msg" || payload?.type !== "token_count")
@@ -293,6 +795,12 @@ function snapshotForOutput(snapshot) {
     delete safe.cached_input_tokens;
     return { schema_id: "dd-flow/session-usage-snapshot@1", ...safe };
 }
+function sourceFacts(file) {
+    if (!file || !fs.existsSync(file))
+        return { locator: file, sha256: null, size: null, mtime: null };
+    const stat = fs.statSync(file);
+    return { locator: file, sha256: crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"), size: stat.size, mtime: Math.trunc(stat.mtimeMs) };
+}
 function sameUsageSnapshot(previous, current) {
     return previous.stage === current.stage
         && previous.stage_attempt === current.stage_attempt