feat(usage): Capture orchestrator usage through a source ledger

.specs/features/run-usage-statusline/spec.md

@@ -1,5 +1,7 @@
 # Uso agregado do run na statusline
 
+> Substituído em parte por `.specs/features/orchestrator-usage/spec.md` (seção "Supersedes"): a linha `open` no store, o formato de `usage <run-id> --json`, o registro do custo do orquestrador pela statusline e o preço de cached tokens no Codex.
+
 ## Goal
 
 O CodeDeck SHALL mostrar na statusline do Claude Code o custo local do orquestrador e o custo e os tokens agregados dos workers do run atual. A configuração SHALL pedir atualização em dois segundos, com degradação para atualização orientada a eventos quando a versão do Claude Code não aceitar essa configuração.

plugin/hooks/session-id.sh

@@ -20,4 +20,4 @@ target=${CODEDECK_SESSION_FILE:-}
 id=$(grep -oE '"session_id":"[0-9a-fA-F-]+"' | head -1 | cut -d'"' -f4)
 [[ -n "$id" ]] || exit 0
 
-printf '%s' "$id" > "$target"
+printf '%s\n' "$id" >> "$target"

plugin/statusline.sh

@@ -181,8 +181,17 @@ const getRunUsage = () => {
   const runId = text(process.env.CODEDECK_RUN_ID);
   if (!runId) return undefined;
 
+  const args = ["usage", runId, "--json"];
+  const sessionId = payload.session_id;
+  const observeCost = nonNegativeNumber(payload.cost?.total_cost_usd);
+  if (
+    typeof sessionId === "string" &&
+    /^[0-9a-fA-F-]{8,}$/.test(sessionId) &&
+    observeCost !== undefined
+  ) args.push("--observe", `${sessionId}=${observeCost}`);
+
   try {
-    const output = execFileSync("codedeck", ["usage", runId, "--json"], {
+    const output = execFileSync("codedeck", args, {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 1000,
@@ -215,8 +224,30 @@ const getRunUsage = () => {
   }
 };
 
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+const getOrchestratorUsage = (usage) => {
+  const value = usage.orchestrator;
+  if (
+    !isObject(value) ||
+    nonNegativeNumber(value.costUsd) === undefined ||
+    typeof value.costComplete !== "boolean" ||
+    nonNegativeNumber(value.inputTokens) === undefined ||
+    nonNegativeNumber(value.outputTokens) === undefined ||
+    nonNegativeNumber(value.cachedTokens) === undefined ||
+    !Array.isArray(value.sources)
+  ) return undefined;
+  if (!value.sources.every((source) =>
+    isObject(source) &&
+    typeof source.nativeId === "string" &&
+    nonNegativeNumber(source.costUsd) !== undefined
+  )) return undefined;
+  return value;
+};
+
 const local = localCost();
 const runUsage = getRunUsage();
+const orchestratorUsage = runUsage ? getOrchestratorUsage(runUsage) : undefined;
 const workerTokens = runUsage
   ? runUsage.inputTokens + runUsage.outputTokens + runUsage.cachedTokens
   : undefined;
@@ -227,8 +258,14 @@ const tokenField = () => {
 
 const runField = () => {
   if (!runUsage) return undefined;
-  const total = (local ?? 0) + runUsage.costUsd;
-  const incomplete = !runUsage.costComplete;
+  const sourceCost = orchestratorUsage
+    ? orchestratorUsage.sources.reduce(
+      (sum, source) => source.nativeId === payload.session_id ? sum : sum + source.costUsd,
+      0,
+    )
+    : 0;
+  const total = (local ?? 0) + runUsage.costUsd + sourceCost;
+  const incomplete = !runUsage.costComplete || Boolean(orchestratorUsage && !orchestratorUsage.costComplete);
   if (!incomplete && total < COST_DISPLAY_THRESHOLD) return undefined;
   return paint(MUTED, "run ") + costAmount(total, incomplete);
 };

src/cli/commands/open.ts

@@ -23,6 +23,7 @@ import { createWorktree } from "../../git/worktree.js";
 import { ptyShimPath, type PtyLaunch } from "../../open/pty.js";
 import { isInteractiveTerminal } from "./setup.js";
 import { sessionsDir } from "../../open/pty.js";
+import { startLinkWatcher } from "../../open/link-watcher.js";
 
 import { ROLES, parseRole, resolvePluginDir, type Role } from "../../core/roles.js";
 import { getCliName } from "../cli-name.js";
@@ -656,6 +657,27 @@ export function registerOpenCommand(program: Command): void {
         ...(opts.resume !== undefined ? { resume: opts.resume } : {}),
       });
       const runId = adoptRes.session.id;
+      let linkWatcher: ReturnType<typeof startLinkWatcher> | undefined;
+      let linkWatcherFlush: Promise<void> | undefined;
+      const flushLinkWatcher = async () => {
+        if (linkWatcherFlush !== undefined) {
+          await linkWatcherFlush;
+          return;
+        }
+        if (linkWatcher === undefined) return;
+
+        const watcher = linkWatcher;
+        linkWatcherFlush = (async () => {
+          try {
+            await watcher.flush();
+          } catch {}
+          try {
+            watcher.stop();
+          } catch {}
+          linkWatcher = undefined;
+        })();
+        await linkWatcherFlush;
+      };
 
       let patchPromise: Promise<unknown> | undefined;
       try {
@@ -712,6 +734,7 @@ export function registerOpenCommand(program: Command): void {
                 fs.writeFileSync(sessionFile, id);
               } catch {}
             }
+            if (linkWatcher !== undefined || linkWatcherFlush !== undefined) await flushLinkWatcher();
             const nativeSessionId = finishOpenSession(role, sessionFile);
             try {
               if (patchPromise) await patchPromise;
@@ -812,6 +835,7 @@ export function registerOpenCommand(program: Command): void {
                 fs.writeFileSync(sessionFile, id);
               } catch {}
             }
+            if (linkWatcher !== undefined || linkWatcherFlush !== undefined) await flushLinkWatcher();
             const nativeSessionId = finishOpenSession(role, sessionFile);
             try {
               if (patchPromise) await patchPromise;
@@ -872,12 +896,19 @@ export function registerOpenCommand(program: Command): void {
           await playBoot(role, model, effort);
         }
 
+        linkWatcher = startLinkWatcher({
+          sessionFile,
+          runId,
+          link: (id, nativeId) => client.request("session.linkNative", { id, nativeId }),
+        });
+
         const closeClaude = async () => {
           if (!fs.existsSync(sessionFile) && opts.resume && SESSION_ID_PATTERN.test(opts.resume)) {
             try {
               fs.writeFileSync(sessionFile, opts.resume);
             } catch {}
           }
+          if (linkWatcher !== undefined || linkWatcherFlush !== undefined) await flushLinkWatcher();
           const nativeSessionId = finishOpenSession(role, sessionFile);
           try {
             if (patchPromise) await patchPromise;
@@ -911,6 +942,7 @@ export function registerOpenCommand(program: Command): void {
           },
         );
       } catch (err: unknown) {
+        if (linkWatcher !== undefined || linkWatcherFlush !== undefined) await flushLinkWatcher();
         try {
           await client.request("session.release", {
             id: runId,

src/cli/commands/usage-backfill.ts

@@ -0,0 +1,177 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { DatabaseSync } from "node:sqlite";
+import { findTranscript, readTranscriptUsage } from "../../core/claude-transcript.js";
+import { openSourceKey } from "../../core/usage-source.js";
+import { getPaths } from "../../config/paths.js";
+import { SESSION_ID_PATTERN } from "../../open/runtime.js";
+import { Database } from "../../store/database.js";
+import { UsageLedger } from "../../store/usage-ledger.js";
+
+export interface UsageBackfillSummary {
+  imported: number;
+  skipped: number;
+}
+
+interface NativeSessionRow {
+  native_session_id: string;
+}
+
+function addId(ids: Set<string>, value: string): void {
+  const nativeId = value.trim();
+  if (SESSION_ID_PATTERN.test(nativeId)) ids.add(nativeId);
+}
+
+function collectNativeIds(
+  db: DatabaseSync,
+  sessionsDir: string,
+): { ids: Set<string>; workerIds: Set<string> } {
+  const ids = new Set<string>();
+  const openRows = db.prepare(`
+    SELECT native_session_id FROM sessions
+    WHERE origin = 'open' AND native_session_id IS NOT NULL
+  `).all() as unknown as NativeSessionRow[];
+  for (const row of openRows) addId(ids, row.native_session_id);
+
+  const workerRows = db.prepare(`
+    SELECT native_session_id FROM sessions
+    WHERE native_session_id IS NOT NULL AND (origin IS NULL OR origin <> 'open')
+  `).all() as unknown as NativeSessionRow[];
+  const workerIds = new Set(workerRows.map((row) => row.native_session_id));
+
+  let files: string[];
+  try {
+    files = fs.readdirSync(sessionsDir);
+  } catch {
+    return { ids, workerIds };
+  }
+
+  for (const file of files) {
+    const nameSidecar = file.match(/^codedeck-session-\d+\.([^.]+)\.name$/);
+    if (nameSidecar?.[1]) addId(ids, nameSidecar[1]);
+
+    if (!/^codedeck-session-\d+$/.test(file)) continue;
+    let contents: string;
+    try {
+      contents = fs.readFileSync(path.join(sessionsDir, file), "utf8");
+    } catch {
+      continue;
+    }
+    for (const line of contents.split(/\r?\n/)) addId(ids, line);
+  }
+
+  return { ids, workerIds };
+}
+
+function repositoryRoot(cwd: string | undefined): string | null {
+  if (cwd === undefined) return null;
+  let current = path.resolve(cwd);
+  while (true) {
+    if (fs.existsSync(path.join(current, ".git"))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function importLegacyUsage(
+  db: DatabaseSync,
+  ledger: UsageLedger,
+  nativeId: string,
+  usage: Awaited<ReturnType<typeof readTranscriptUsage>>,
+): boolean {
+  const sourceKey = openSourceKey(nativeId);
+  const endedAt = usage.endedAt;
+  if (endedAt === undefined) return false;
+
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    if (ledger.hasSource(sourceKey)) {
+      db.exec("ROLLBACK");
+      return false;
+    }
+
+    const cost = usage.cost ?? null;
+    const inputTokens = usage.inputTokens;
+    const outputTokens = usage.outputTokens;
+    const cachedTokens = usage.cachedTokens;
+    const updatedAt = new Date().toISOString();
+    db.prepare(`
+      INSERT INTO usage_legacy (
+        native_id, ended_at, cwd, repository, model, cost,
+        input_tokens, output_tokens, cached_tokens
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      nativeId,
+      endedAt,
+      usage.cwd ?? null,
+      repositoryRoot(usage.cwd ?? undefined),
+      usage.model ?? null,
+      cost,
+      inputTokens,
+      outputTokens,
+      cachedTokens,
+    );
+    db.prepare(`
+      INSERT INTO usage_sources (
+        source_key, cost, input_tokens, output_tokens, cached_tokens, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?)
+    `).run(sourceKey, cost, inputTokens, outputTokens, cachedTokens, updatedAt);
+    db.exec("COMMIT");
+    return true;
+  } catch (error) {
+    try {
+      db.exec("ROLLBACK");
+    } catch {}
+    throw error;
+  }
+}
+
+export async function backfillUsage(): Promise<UsageBackfillSummary> {
+  const paths = getPaths();
+  const db = new Database(paths.db);
+  try {
+    const handle = db.getHandle();
+    const ledger = new UsageLedger(handle);
+    const { ids, workerIds } = collectNativeIds(handle, paths.sessionsDir);
+    const summary: UsageBackfillSummary = { imported: 0, skipped: 0 };
+
+    for (const nativeId of ids) {
+      if (workerIds.has(nativeId)) {
+        summary.skipped++;
+        continue;
+      }
+
+      const sourceKey = openSourceKey(nativeId);
+      if (ledger.hasSource(sourceKey)) {
+        summary.skipped++;
+        continue;
+      }
+
+      const transcript = findTranscript(nativeId);
+      if (!transcript) {
+        summary.skipped++;
+        continue;
+      }
+
+      let usage: Awaited<ReturnType<typeof readTranscriptUsage>>;
+      try {
+        usage = await readTranscriptUsage(transcript);
+      } catch {
+        summary.skipped++;
+        continue;
+      }
+      if (usage.state !== "cost-state" || usage.endedAt === undefined) {
+        summary.skipped++;
+        continue;
+      }
+
+      if (importLegacyUsage(handle, ledger, nativeId, usage)) summary.imported++;
+      else summary.skipped++;
+    }
+
+    return summary;
+  } finally {
+    db.close();
+  }
+}