GPU receipt accounting: remote runs emit spend rows; ledger gpu sums them (#425)

packages/amico-run/src/ledger.ts

@@ -267,6 +267,22 @@ export interface PlanCompiledRecord {
 
 /** One ADVISORY todo transition. `open` is the absence of a row; multiple rows per id
  *  resolve last-ts-wins. No `actor` field — no trustworthy actor identity exists here. */
+/** GPU/compute accounting for a remote run (#425, GPU-plane spec): pure
+ *  spend record — no fidelity, never feeds priors. The campaign warrant fold
+ *  sums these (unit-keyed bounds). Emitted by the remote executor at settle. */
+export interface ReceiptRecord {
+  type: "receipt";
+  ts: string;
+  task_id: string;
+  executor: "remote";
+  gpu_sku?: string;
+  gpu_seconds?: number;
+  cost_usd?: number;
+  problem?: string;
+  session?: string;
+  status?: "completed" | "failed" | "aborted";
+}
+
 export interface TodoRecord {
   type: "todo";
   ts: string;
@@ -279,6 +295,7 @@ export interface TodoRecord {
 
 export type LedgerRecord =
   | SolveRecord
+  | ReceiptRecord
   | VerdictRecord
   | AttemptErrorRecord
   | FallbackRecord
@@ -297,6 +314,49 @@ export function ledgerPath(): string {
   return join(studioPathsOrLegacy().ledger, "runs.jsonl");
 }
 
+/** GPU spend totals over receipt rows (#425) — the warrant fold's view.
+ *  Pure aggregation: never throws, zeros on empty. by_sku/by_status keyed
+ *  breakdowns; cost_usd omitted per-row when the runner didn't report it. */
+export interface GpuTotals {
+  receipts: number;
+  gpu_seconds: number;
+  cost_usd: number;
+  by_sku: Record<string, { gpu_seconds?: number; cost_usd?: number }>;
+  by_status: Record<string, number>;
+}
+
+export function gpuTotals(file = ledgerPath()): GpuTotals {
+  const t: GpuTotals = { receipts: 0, gpu_seconds: 0, cost_usd: 0, by_sku: {}, by_status: {} };
+  let raw: string;
+  try {
+    raw = readFileSync(file, "utf8");
+  } catch {
+    return t; // absent ledger = zero spend, not an error
+  }
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    let rec: LedgerRecord;
+    try {
+      rec = JSON.parse(line) as LedgerRecord;
+    } catch {
+      continue; // a torn line never breaks accounting
+    }
+    if (rec.type !== "receipt") continue;
+    t.receipts += 1;
+    if (rec.gpu_seconds !== undefined) t.gpu_seconds += rec.gpu_seconds;
+    if (rec.cost_usd !== undefined) t.cost_usd += rec.cost_usd;
+    if (rec.gpu_sku !== undefined) {
+      const b = t.by_sku[rec.gpu_sku] ?? {};
+      if (rec.gpu_seconds !== undefined) b.gpu_seconds = (b.gpu_seconds ?? 0) + rec.gpu_seconds;
+      if (rec.cost_usd !== undefined) b.cost_usd = (b.cost_usd ?? 0) + rec.cost_usd;
+      t.by_sku[rec.gpu_sku] = b;
+    }
+    if (rec.status !== undefined) t.by_status[rec.status] = (t.by_status[rec.status] ?? 0) + 1;
+  }
+  t.cost_usd = Math.round(t.cost_usd * 1e4) / 1e4;
+  return t;
+}
+
 /** Append one record as a single JSONL line. Validates against the `ledger-record`
  *  schema (Task 2 wires this in) before writing so no malformed line ever lands.
  *  Throws when the serialized line exceeds PIPE_BUF (would break O_APPEND

packages/amico-run/src/ledger_verb.ts

@@ -44,7 +44,7 @@
 //         §5.1 rule 2 refuses a launch needing a bound the warrant omits — so a
 //         helpfully-filled default would silently widen the warrant.
 import { readFileSync } from "node:fs";
-import { appendRecord, type ApprovalRecord, type LedgerRecord, type WarrantBounds } from "./ledger.js";
+import { appendRecord, gpuTotals, type ApprovalRecord, type LedgerRecord, type WarrantBounds } from "./ledger.js";
 import { bucketN, bucketT, queryDefaults, type QueryKey } from "./ledger_query.js";
 import { dispatchTable, type DispatchKey } from "./ledger_dispatch.js";
 import type { VerbResult } from "./verbs.js";
@@ -68,6 +68,21 @@ function readStanza(argv: string[]): string | undefined {
 }
 
 // ── append ────────────────────────────────────────────────────────────────────
+export function ledgerGpu(_argv: string[]): VerbResult {
+  // #425: GPU spend totals over receipt rows — the warrant fold's view.
+  const t = gpuTotals();
+  const hours = t.gpu_seconds / 3600;
+  const lines = [
+    `receipts      ${t.receipts}`,
+    `gpu_seconds   ${t.gpu_seconds}  (${hours.toFixed(2)} h)`,
+    `cost_usd      ${t.cost_usd}`,
+  ];
+  for (const [sku, b] of Object.entries(t.by_sku))
+    lines.push(`  ${sku}  ${(b.gpu_seconds ?? 0)}s${b.cost_usd !== undefined ? ` · $${b.cost_usd}` : ""}`);
+  for (const [st, n] of Object.entries(t.by_status)) lines.push(`  status ${st}: ${n}`);
+  return { json: { verb: "ledger", subcommand: "gpu", totals: t, table: lines.join("\n") }, code: 0 };
+}
+
 export function ledgerAppend(argv: string[]): VerbResult {
   const fail = (error: string): VerbResult => ({ json: { verb: "ledger", subcommand: "append", error }, code: 64 });
 
@@ -241,6 +256,7 @@ export function ledgerApprove(argv: string[]): VerbResult {
 export function ledgerVerb(argv: string[]): VerbResult {
   const sub = argv[0];
   const rest = argv.slice(1);
+  if (sub === "gpu") return ledgerGpu(rest);
   if (sub === "append") return ledgerAppend(rest);
   if (sub === "query") return ledgerQuery(rest);
   if (sub === "dispatch") return ledgerDispatch(rest);

packages/amico-run/src/remote_executor.ts

@@ -9,6 +9,7 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, utimesSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { EventQueue } from "./event_queue.js";
+import { appendRecord, type ReceiptRecord } from "./ledger.js";
 import { classifyLine } from "./telemetry.js";
 import {
   appendIndex,
@@ -160,6 +161,12 @@ export class RemoteExecutor implements Executor {
       events.push(classifyLine(line, "stdout"));
     };
 
+    // #425 GPU receipt: the runner-contract fields ride the finished payload;
+    // stashed here, consumed at settle. Absent fields → null → no receipt row
+    // (nothing to account — the pre-contract runner emits none).
+    type GpuReceipt = { gpu_sku?: string; gpu_seconds?: number; cost_usd?: number };
+    let gpuReceipt: GpuReceipt | null = null;
+
     const settle = (status: RunStatus, exitCode: number): void => {
       if (settled) return;
       settled = true;
@@ -168,6 +175,32 @@ export class RemoteExecutor implements Executor {
       } catch (e) {
         process.stderr.write(`amico-run: failed to write FINISHED: ${(e as Error).message}\n`);
       }
+      // GPU accounting (#425): the receipt row is spend, not science —
+      // emitted on FAILED runs too (they burn the same GPU time), never
+      // feeding priors (no fidelity field exists on it by design).
+      if (gpuReceipt) {
+        try {
+          const rec: ReceiptRecord = {
+            type: "receipt",
+            ts: new Date().toISOString(),
+            task_id: taskId,
+            executor: "remote",
+            ...gpuReceipt,
+          };
+          if (status === "completed" || status === "failed" || status === "aborted") rec.status = status;
+          appendRecord(rec); // validates against the ledger-record schema
+          atomicWriteFile(runDir, "receipt.toml", [
+            "# GPU receipt (runner contract #424) — mirrored from the cloud finished payload",
+            `task_id = "${taskId}"`,
+            ...(rec.gpu_sku ? [`gpu_sku = ${JSON.stringify(rec.gpu_sku)}`] : []),
+            ...(rec.gpu_seconds !== undefined ? [`gpu_seconds = ${rec.gpu_seconds}`] : []),
+            ...(rec.cost_usd !== undefined ? [`cost_usd = ${rec.cost_usd}`] : []),
+            `status = "${status}"`,
+          ].join("\n") + "\n");
+        } catch (e) {
+          process.stderr.write(`amico-run: failed to emit GPU receipt stanza: ${(e as Error).message}\n`);
+        }
+      }
       events.push({ kind: "finished", status, exitCode });
       events.close();
       resolveFinished({ status, exitCode });
@@ -322,6 +355,16 @@ export class RemoteExecutor implements Executor {
         settle("failed", EXIT_INFERRED);
         return;
       }
+      const fin = s.finished as
+        | { status?: string; gpu_sku?: unknown; gpu_seconds?: unknown; cost_usd?: unknown }
+        | undefined;
+      if (fin && gpuReceipt === null) {
+        const sku = typeof fin.gpu_sku === "string" && fin.gpu_sku !== "" ? fin.gpu_sku : undefined;
+        const secs = typeof fin.gpu_seconds === "number" && Number.isFinite(fin.gpu_seconds) && fin.gpu_seconds > 0 ? fin.gpu_seconds : undefined;
+        const cost = typeof fin.cost_usd === "number" && Number.isFinite(fin.cost_usd) && fin.cost_usd > 0 ? fin.cost_usd : undefined;
+        if (sku !== undefined || secs !== undefined || cost !== undefined)
+          gpuReceipt = { ...(sku !== undefined ? { gpu_sku: sku } : {}), ...(secs !== undefined ? { gpu_seconds: secs } : {}), ...(cost !== undefined ? { cost_usd: cost } : {}) };
+      }
       const f = s.finished?.status;
       if (f === "completed" || f === "failed" || f === "aborted") settle(f, EXIT[f]);
     };

packages/amico-run/test/fake_cloud.ts

@@ -16,7 +16,14 @@ export interface FakeIter {
 
 export interface FakeState {
   task_status: "Pending" | "Running";
-  finished?: { status: "completed" | "failed" | "aborted" };
+  /** finished with the runner-contract receipt fields (#424/#425) — the
+   *  client parses defensively; absent fields → no receipt ledger row. */
+  finished?: {
+    status: "completed" | "failed" | "aborted";
+    gpu_sku?: string;
+    gpu_seconds?: number;
+    cost_usd?: number;
+  };
   liveness: "alive" | "gone";
   iters: FakeIter[]; // Δ4 stats: full history each poll (client dedups on high-water)
   frame?: { iter: number; png_base64: string }; // Δ4 frames: newest only

packages/amico-run/test/ledger.test.ts

@@ -5,7 +5,7 @@ import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { appendRecord, readRecords, ledgerPath, PIPE_BUF, type SolveRecord } from "../src/ledger.js";
+import { appendRecord, readRecords, ledgerPath, PIPE_BUF, gpuTotals, type SolveRecord, type LedgerRecord } from "../src/ledger.js";
 
 let dir: string;
 const prevEnv = process.env.AMICO_LEDGER;
@@ -19,6 +19,12 @@ afterEach(() => {
   else process.env.AMICO_LEDGER = prevEnv;
 });
 
+
+function writeTmpLedger(rows: LedgerRecord[]): string {
+  for (const r of rows) appendRecord(r);
+  return ledgerPath();
+}
+
 const solve = (over: Partial<SolveRecord> = {}): SolveRecord => ({
   type: "solve",
   ts: "2026-07-22T00:00:00Z",
@@ -89,3 +95,25 @@ describe("ledger core", () => {
     expect(Buffer.byteLength(line + "\n", "utf8")).toBeLessThan(PIPE_BUF);
   });
 });
+
+// ── ledger gpu (#425): sum the receipt rows — the warrant fold's view ──────
+describe("ledger gpu totals (receipt rows, #425)", () => {
+  it("sums gpu_seconds/cost across receipt rows, breaks down by SKU, counts by status", () => {
+    const f = writeTmpLedger([
+      { type: "receipt", ts: "2026-08-18T10:00:00Z", task_id: "a", executor: "remote", gpu_sku: "H100-80GB", gpu_seconds: 900, cost_usd: 2.7, status: "completed" },
+      { type: "receipt", ts: "2026-08-18T11:00:00Z", task_id: "b", executor: "remote", gpu_sku: "H100-80GB", gpu_seconds: 300, cost_usd: 0.9, status: "failed" },
+      { type: "receipt", ts: "2026-08-18T12:00:00Z", task_id: "c", executor: "remote", gpu_sku: "A100-40GB", gpu_seconds: 600 },
+      { type: "solve", ts: "2026-08-18T13:00:00Z", structure_hash: "x", problem_hash: "y", kind: "control", tier: "hpc", summary: { platform: "p", template: "t", trajectory: "g", N: 10, T: 10, goal: "g", solver: "s", strategy: "s" }, source: "user", outcome: { converged: true, fidelity: 0.99, iterations: 5 } },
+    ]);
+    const t = gpuTotals(f);
+    expect(t.receipts).toBe(3);
+    expect(t.gpu_seconds).toBe(1800);
+    expect(t.cost_usd).toBeCloseTo(3.6);
+    expect(t.by_sku).toEqual({ "H100-80GB": { gpu_seconds: 1200, cost_usd: 3.6 }, "A100-40GB": { gpu_seconds: 600 } });
+    expect(t.by_status).toEqual({ completed: 1, failed: 1 });
+  });
+  it("an empty or receipt-less ledger is zeros, never a throw", () => {
+    const t = gpuTotals(writeTmpLedger([]));
+    expect(t).toEqual({ receipts: 0, gpu_seconds: 0, cost_usd: 0, by_sku: {}, by_status: {} });
+  });
+});

packages/amico-run/test/remote_executor.test.ts

@@ -397,3 +397,48 @@ describe("stats records arrive in either shape", () => {
     });
   });
 });
+
+// ── GPU receipt accounting (#425): remote settle → receipt ledger row ──────
+describe("RemoteExecutor — GPU receipt accounting (#425)", () => {
+  it("a completed run whose finished payload carries GPU fields emits a receipt ledger row + mirror receipt.toml", async () => {
+    await withCloud(async (fake) => {
+      fake.state.finished = { status: "completed", gpu_sku: "H100-80GB", gpu_seconds: 900, cost_usd: 2.7 };
+      const ledgerFile = join(tmpRoot(), `ledger-${Date.now()}.jsonl`);
+      process.env.AMICO_LEDGER = ledgerFile;
+      try {
+        const h = await ex(fake, { pollMs: 5, warmingBudgetMs: 5000, lostAfterMs: 5000 })
+          .submit(fakeJulia(tmpRoot(), "solve.jl", "// julia body"), { runsRoot: join(tmpRoot(), "runs"), lab: "t" });
+        for await (const _ of h.events) void _;
+        const rows = readFileSync(ledgerFile, "utf8").trim().split("\n").map((l) => JSON.parse(l));
+        const receipt = rows.find((r) => r.type === "receipt");
+        expect(receipt).toMatchObject({
+          task_id: fake.taskId, executor: "remote",
+          gpu_sku: "H100-80GB", gpu_seconds: 900, cost_usd: 2.7,
+        });
+        // the mirror carries the durable artifact too
+        const mirror = join(h.runDir, "receipt.toml");
+        expect(readFileSync(mirror, "utf8")).toContain('gpu_sku = "H100-80GB"');
+      } finally {
+        delete process.env.AMICO_LEDGER;
+      }
+    });
+  });
+  it("a finished payload WITHOUT GPU fields emits no receipt row (nothing to account)", async () => {
+    await withCloud(async (fake) => {
+      fake.state.finished = { status: "completed" };
+      const ledgerFile = join(tmpRoot(), `ledger-${Date.now()}.jsonl`);
+      process.env.AMICO_LEDGER = ledgerFile;
+      try {
+        const h = await ex(fake, { pollMs: 5, warmingBudgetMs: 5000, lostAfterMs: 5000 })
+          .submit(fakeJulia(tmpRoot(), "solve.jl", "// julia body"), { runsRoot: join(tmpRoot(), "runs"), lab: "t2" });
+        for await (const _ of h.events) void _;
+        if (existsSync(ledgerFile)) {
+          const rows = readFileSync(ledgerFile, "utf8").trim().split("\n").map((l) => JSON.parse(l));
+          expect(rows.some((r) => r.type === "receipt")).toBe(false);
+        }
+      } finally {
+        delete process.env.AMICO_LEDGER;
+      }
+    });
+  });
+});