@cohortapp/agent-sdk 2.3.0

package/lib/org/cohort-client.mjs

@@ -0,0 +1,67 @@
+/**
+ * lib/org/cohort-client.mjs — RETIRED shim.
+ *
+ * This module USED to speak a defunct contract (PUT `${apiUrl}/{orgId}/agents/{id}`,
+ * POST `${base}/agents/{id}/status`, GET `${base}/agents`) that hq's /api/v1 RPC
+ * surface NEVER exposed. It is now a thin re-export of the aligned client in
+ * lib/org/client.mjs so the published export `@cohortapp/agent-sdk/org/cohort-client`
+ * keeps resolving for any external importer, while the wire behaviour is the
+ * correct one:
+ *   - publishEntry   → registry.register  (POST /api/v1/registry.register)
+ *   - fetchDirectory → GET /api/v1/directory
+ *   - isEnabled      → the client's enablement check
+ *   - heartbeat      → presence.beat liveness (the old per-agent status POST is
+ *                      fully superseded; presence.beat rides the status snapshot,
+ *                      driven by lib/org/mesh.mjs through the same client).
+ *
+ * Fail-open is preserved end-to-end by client.mjs (benign value on error/disabled,
+ * never a throw). `fetchImpl` stays injectable for tests. New code SHOULD import
+ * from "./client.mjs" directly; this shim exists only for back-compat.
+ *
+ * @module lib/org/cohort-client
+ */
+
+"use strict";
+
+export { isEnabled, publishEntry, fetchDirectory } from "./client.mjs";
+
+import { configFromAgent, isEnabled, presenceBeat } from "./client.mjs";
+
+/**
+ * Heartbeat this agent's liveness. The legacy per-agent status POST
+ * (`${base}/agents/{id}/status`) has NO equivalent on hq; liveness is the
+ * presence.beat snapshot. This shim maps the old `{cfg,id,status,focus,presence}`
+ * call onto presence.beat (strict status snapshot subset) so external callers of
+ * the old export keep working. New code should use lib/org/mesh.mjs (which beats
+ * the full telemetry snapshot) or client.presenceBeat directly. Fail-open.
+ *
+ * @param {object} o - { cfg, id?, status?, focus?, presence?, fetchImpl? }
+ * @returns {Promise<{ok:boolean, status?:number, skipped?:boolean, reason?:string}>}
+ */
+export async function heartbeat(o = {}) {
+  const { cfg } = o;
+  if (!isEnabled(cfg)) return { ok: false, skipped: true };
+  const c = configFromAgent(cfg);
+  // Build a minimal, strict-schema-safe status snapshot. presence.beat's status
+  // is z.object().strict() over {state,activity,subAgentsRunning,machine,
+  // claudeAuth,alerts,...}; keep this a conservative subset.
+  const state = typeof o.status === "string" && o.status ? o.status : "active";
+  const params = {
+    focus: o.focus || [],
+    status: {
+      state,
+      activity: "",
+      subAgentsRunning: 0,
+      machine: "",
+      claudeAuth: "unknown",
+      alerts: [],
+    },
+  };
+  const frame = await presenceBeat(params, {
+    base: c.base,
+    token: c.token,
+    orgId: c.orgId,
+    fetchImpl: o.fetchImpl,
+  });
+  return { ok: !!(frame && frame.ok), status: frame && frame.ok ? 200 : 0 };
+}

package/lib/org/cohort-client.test.mjs

@@ -0,0 +1,126 @@
+/**
+ * cohort-client.test.mjs — RETIRED shim re-exporting the aligned client.mjs.
+ *
+ * The old module spoke a defunct contract (PUT `${apiUrl}/{orgId}/agents/{id}`,
+ * POST `${base}/agents/{id}/status`, GET `${base}/agents`). It is now a thin
+ * re-export of lib/org/client.mjs, so these tests assert the NEW wire shape:
+ *   - publishEntry   → POST /v1/registry.register (Bearer + x-idempotency-key)
+ *   - fetchDirectory → GET  /v1/directory  (parses members/agents/array shapes)
+ *   - heartbeat      → POST /v1/presence.beat (liveness snapshot)
+ * and that the OLD `/{orgId}/agents` endpoints are NEVER hit.
+ * Run: node --test lib/org/cohort-client.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { isEnabled, publishEntry, heartbeat, fetchDirectory } from "./cohort-client.mjs";
+import { PROTOCOL_VERSION } from "./protocol.mjs";
+
+// Ambient COHORT_* creds would leak into header assertions; clear them so the
+// tests are hermetic regardless of host env.
+delete process.env.COHORT_API_TOKEN;
+delete process.env.COHORT_TOKEN;
+delete process.env.COHORT_API_KEY;
+delete process.env.COHORT_ORG_ID;
+
+const BASE = "https://org.cohortapp.com";
+// New enablement contract: enabled + (base || apiUrl+orgId).
+const ON = { org: { cohort: { enabled: true, base: BASE, token: "tok-xyz" } } };
+const OFF = { org: { cohort: { enabled: false, base: BASE } } };
+
+/** A fake fetch that records calls and returns a canned res frame. */
+function fakeFetch(responder) {
+  const calls = [];
+  const impl = async (url, init) => {
+    calls.push({ url, init, headers: (init && init.headers) || {} });
+    const r = responder ? responder(url, init, calls.length - 1) : null;
+    const status = r && typeof r.status === "number" ? r.status : 200;
+    const ok = r && typeof r.ok === "boolean" ? r.ok : status >= 200 && status < 300;
+    const body = r ? r.body : { ok: true, result: null };
+    return { ok, status, headers: { get: () => undefined }, json: async () => body };
+  };
+  impl.calls = calls;
+  return impl;
+}
+
+test("isEnabled: requires enabled + (base or apiUrl+orgId)", () => {
+  assert.equal(isEnabled(ON), true);
+  assert.equal(isEnabled(OFF), false);
+  assert.equal(isEnabled({ org: { cohort: { enabled: true, apiUrl: "x", orgId: "o" } } }), true);
+  assert.equal(isEnabled(null), false);
+});
+
+test("publishEntry: no-op disabled; POSTs registry.register (NOT /agents) when enabled", async () => {
+  assert.deepEqual(await publishEntry({ cfg: OFF, entry: { id: "a" } }), { ok: false, skipped: true });
+  const f = fakeFetch(() => ({ body: { ok: true, result: null } }));
+  const r = await publishEntry({ cfg: ON, entry: { id: "alex-ai", name: "Alex" }, fetchImpl: f });
+  assert.equal(r.ok, true);
+  assert.equal(f.calls[0].url, `${BASE}/api/v1/registry.register`);
+  assert.equal(f.calls[0].init.method, "POST");
+  assert.equal(f.calls[0].headers.authorization, "Bearer tok-xyz");
+  assert.equal(f.calls[0].headers["x-org-protocol"], String(PROTOCOL_VERSION));
+  assert.equal(f.calls[0].headers["x-idempotency-key"], "registry.register:alex-ai");
+  // the OLD /{orgId}/agents endpoint must NEVER be hit
+  assert.doesNotMatch(f.calls[0].url, /\/agents\//);
+});
+
+test("publishEntry: trims a rich entry to the strict registerSchema (archetype object → string)", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: null } }));
+  const entry = {
+    id: "robin-ai",
+    name: "Robin",
+    fullName: "Robin Vega",
+    archetype: { function: "engineering", altitude: "vp", label: "VP Eng" },
+    principal: { fullName: "Sam Human", title: "CEO" },
+    towers: [{ id: "t1", name: "Platform" }],
+    focus: [{ title: "ship the thing" }],
+  };
+  await publishEntry({ cfg: ON, entry, fetchImpl: f });
+  const sent = JSON.parse(f.calls[0].init.body);
+  assert.equal(sent.displayName, "Robin Vega");
+  assert.equal(sent.archetype, "VP Eng");
+  assert.equal(sent.humanSponsor, "Sam Human");
+  // the full rich entry rides under `card` (server chain-redacts to hasCard)
+  assert.equal(sent.card.id, "robin-ai");
+  assert.deepEqual(sent.card.archetype, entry.archetype);
+});
+
+test("publishEntry: server error frame → {ok:false} (fail-open shape preserved)", async () => {
+  const f = fakeFetch(() => ({ ok: false, status: 500, body: { ok: false, error: { code: "INTERNAL", message: "boom" } } }));
+  const r = await publishEntry({ cfg: ON, entry: { id: "x" }, fetchImpl: f });
+  assert.equal(r.ok, false);
+});
+
+test("heartbeat: no-op disabled; POSTs presence.beat (NOT /agents/{id}/status) when enabled", async () => {
+  assert.deepEqual(await heartbeat({ cfg: OFF, id: "a" }), { ok: false, skipped: true });
+  const f = fakeFetch(() => ({ body: { ok: true, result: { directives: [] } } }));
+  const r = await heartbeat({ cfg: ON, id: "alex-ai", status: "active", fetchImpl: f });
+  assert.equal(r.ok, true);
+  assert.equal(f.calls[0].url, `${BASE}/api/v1/presence.beat`);
+  assert.equal(f.calls[0].init.method, "POST");
+  assert.doesNotMatch(f.calls[0].url, /\/agents\//);
+  const sent = JSON.parse(f.calls[0].init.body);
+  assert.equal(sent.status.state, "active");
+});
+
+test("fetchDirectory: [] disabled; parses array + {members:[]} + {agents:[]} shapes", async () => {
+  assert.deepEqual(await fetchDirectory({ cfg: OFF }), []);
+  const arr = await fetchDirectory({ cfg: ON, fetchImpl: fakeFetch(() => ({ body: [{ id: "x" }] })) });
+  assert.equal(arr.length, 1);
+  const members = await fetchDirectory({ cfg: ON, fetchImpl: fakeFetch(() => ({ body: { members: [{ id: "m1" }, { id: "m2" }] } })) });
+  assert.equal(members.length, 2);
+  const agents = await fetchDirectory({ cfg: ON, fetchImpl: fakeFetch(() => ({ body: { agents: [{ id: "y" }] } })) });
+  assert.equal(agents.length, 1);
+  // GET /v1/directory, never the old /{orgId}/agents
+  const f = fakeFetch(() => ({ body: { members: [] } }));
+  await fetchDirectory({ cfg: ON, fetchImpl: f });
+  assert.equal(f.calls[0].url, `${BASE}/api/v1/directory`);
+  assert.equal(f.calls[0].init.method, "GET");
+});
+
+test("fetchDirectory: network error → [] (fail-open)", async () => {
+  const arr = await fetchDirectory({ cfg: ON, fetchImpl: async () => { throw new Error("network down"); } });
+  assert.deepEqual(arr, []);
+});

package/lib/org/cost-sync.mjs

@@ -0,0 +1,227 @@
+/**
+ * lib/org/cost-sync.mjs — ship the maestro router ledger to Cohort cost.report.
+ *
+ * The agent reports its per-session model spend into the org-wide rollup (SPEC
+ * §4.8 cost telemetry). The source of truth is the local router ledger written by
+ * lib/model-router/ledger.mjs to `state/cost-tracking/<date>.jsonl` (one JSON row
+ * per session: agent, model, input_tokens, output_tokens, estimated_usd,
+ * decision_id, cadence/source). This module reads today's rows and POSTs them to
+ * `cost.report`, batched and IDEMPOTENT on each row's id so a re-run never
+ * double-counts — the cadence (`org-sync`) can fire this every tick safely.
+ *
+ * Reconciliation: the ledger is local-first and remains the budget-guard SoT
+ * (budget-guard sums `estimated_usd` from the SAME file). cost.report only
+ * MIRRORS those rows into the org rollup; it never mutates the local ledger, so
+ * the local and org views always reconcile by construction. `reportLedger`
+ * returns the local total alongside the per-row push results so a caller can
+ * assert ledger.localUSD == rollup contribution.
+ *
+ * G16 (zero-LLM-in-the-coordination-loop): this is a pure file-read + HTTP push.
+ * It makes ZERO LLM calls. Critically, it preserves each row's `source`/`cadence`
+ * field on the wire so the org rollup can attribute LLM spend to a coordination
+ * cadence — that attribution is exactly what makes a G16 violation VISIBLE in
+ * `cost.rollup`. Do not strip `source`/`cadence` from the reported row.
+ *
+ * Idempotency key: derived per row from a stable identity (row.id ||
+ * `${decision_id}:${session_id}:${ts}` || a content hash). The server is
+ * idempotent on cost.report, so the same row reported twice is a no-op replay.
+ *
+ * Node builtins only. Fail-open (a down/disabled server reports nothing rather
+ * than throwing). `fetchImpl`, `now`, and `ledgerDir`/`agentRoot` are injectable
+ * for deterministic tests. ESM.
+ *
+ * @module lib/org/cost-sync
+ */
+
+"use strict";
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { isEnabled, configFromAgent, costReport } from "./client.mjs";
+
+const REPORT_BATCH = 100;
+
+// ---------------------------------------------------------------------------
+// Ledger location (mirror of lib/model-router/ledger.mjs)
+// ---------------------------------------------------------------------------
+
+function ledgerDir(deps = {}) {
+  if (deps.ledgerDir) return resolve(deps.ledgerDir);
+  const root = deps.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
+  return join(resolve(root), "state", "cost-tracking");
+}
+
+function dayStr(deps = {}) {
+  if (deps.day) return String(deps.day);
+  const now = (typeof deps.now === "function" ? deps.now : Date.now)();
+  return new Date(now).toISOString().slice(0, 10);
+}
+
+function ledgerFile(deps = {}) {
+  return join(ledgerDir(deps), `${dayStr(deps)}.jsonl`);
+}
+
+// ---------------------------------------------------------------------------
+// Read + normalise ledger rows
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the JSONL ledger rows for a day. NEVER throws — a missing/corrupt file or
+ * an unparseable line yields fewer rows, never an error. Pure over the fs.
+ *
+ * @param {object} deps - { ledgerDir?, agentRoot?, day?, now? }
+ * @returns {object[]} parsed ledger rows (in file order)
+ */
+export function readLedgerRows(deps = {}) {
+  const file = ledgerFile(deps);
+  if (!existsSync(file)) return [];
+  let body;
+  try { body = readFileSync(file, "utf-8"); } catch { return []; }
+  const rows = [];
+  for (const line of body.split("\n")) {
+    if (!line.trim()) continue;
+    try { rows.push(JSON.parse(line)); } catch { /* skip a corrupt line */ }
+  }
+  return rows;
+}
+
+/**
+ * Derive a stable idempotency identity for a ledger row: row.id when present,
+ * else a composite of the natural keys, else a content hash. Two reports of the
+ * SAME logical session collapse to one row in the rollup. Pure.
+ *
+ * @param {object} row
+ * @returns {string}
+ */
+export function rowId(row) {
+  if (!row || typeof row !== "object") return "";
+  if (row.id) return String(row.id);
+  if (row.row_id) return String(row.row_id);
+  const natural = [row.decision_id, row.session_id, row.ts].filter(Boolean).join(":");
+  if (natural) return natural;
+  // Last resort: hash the content so identical rows dedupe and distinct rows don't.
+  return "h:" + createHash("sha256").update(stableJson(row)).digest("hex").slice(0, 24);
+}
+
+function stableJson(value) {
+  const sortDeep = (v) => {
+    if (Array.isArray(v)) return v.map(sortDeep);
+    if (v && typeof v === "object") {
+      const out = {};
+      for (const k of Object.keys(v).sort()) out[k] = sortDeep(v[k]);
+      return out;
+    }
+    return v;
+  };
+  return JSON.stringify(sortDeep(value));
+}
+
+/**
+ * Project a ledger row onto the cost.report wire shape. Preserves the
+ * router-ledger fields the rollup aggregates by (agent / model / cadence|source /
+ * day) and the budget figure (estimated_usd). KEEPS `source`/`cadence` for the
+ * G16 attribution line. Pure.
+ *
+ * @param {object} row
+ * @param {object} deps - { day? }
+ * @returns {object} the wire row (with a stable `id`)
+ */
+export function toReportRow(row, deps = {}) {
+  const id = rowId(row);
+  const day = (row && row.ts && String(row.ts).slice(0, 10)) || dayStr(deps);
+  return {
+    id,
+    agent: row.agent ?? null,
+    model: row.model ?? null,
+    backend: row.backend ?? null,
+    input_tokens: numOr0(row.input_tokens),
+    output_tokens: numOr0(row.output_tokens),
+    cache_read_tokens: numOr0(row.cache_read_tokens),
+    cache_creation_tokens: numOr0(row.cache_creation_tokens),
+    estimated_usd: numOr0(row.estimated_usd),
+    total_cost_usd: row.total_cost_usd ?? null,
+    decision_id: row.decision_id ?? null,
+    session_id: row.session_id ?? null,
+    // G16: attribution fields — DO NOT STRIP. cadence/source surface coordination
+    // spend in the rollup so an LLM-in-the-loop violation is visible.
+    source: row.source ?? null,
+    cadence: row.cadence ?? row.lane ?? null,
+    task_class: row.task_class ?? null,
+    ts: row.ts ?? null,
+    day,
+  };
+}
+
+function numOr0(v) {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : 0;
+}
+
+// ---------------------------------------------------------------------------
+// Report — batched, idempotent push to cost.report
+// ---------------------------------------------------------------------------
+
+/**
+ * Read today's router ledger and report its rows to Cohort via cost.report,
+ * batched and idempotent. Cadence-friendly: safe to call every org-sync tick —
+ * the server's cost.report idempotency on each row's id collapses replays.
+ *
+ * Reconciles by returning the LOCAL ledger total alongside the push outcome so a
+ * caller can assert the org rollup contribution matches the local budget figure.
+ *
+ * Always resolves (fail-open): a disabled/unreachable server reports 0 rows.
+ *
+ * @param {object} o - {
+ *   cfg, agentRoot?, ledgerDir?, day?, now?, batchSize?, fetchImpl?
+ * }
+ * @returns {Promise<{
+ *   enabled:boolean, rowsRead:number, reported:number, failed:number,
+ *   localUSD:number, batches:Array<{count:number, ok:boolean, code?:string}>
+ * }>}
+ */
+export async function reportLedger(o = {}) {
+  const rows = readLedgerRows(o);
+  const localUSD = round6(rows.reduce((s, r) => s + numOr0(r.estimated_usd), 0));
+
+  if (!isEnabled(o.cfg)) {
+    return { enabled: false, rowsRead: rows.length, reported: 0, failed: 0, localUSD, batches: [] };
+  }
+  if (rows.length === 0) {
+    return { enabled: true, rowsRead: 0, reported: 0, failed: 0, localUSD, batches: [] };
+  }
+
+  const c = configFromAgent(o.cfg);
+  const batchSize = Number.isFinite(o.batchSize) && o.batchSize > 0 ? Math.floor(o.batchSize) : REPORT_BATCH;
+  const wireRows = rows.map((r) => toReportRow(r, o));
+
+  let reported = 0;
+  let failed = 0;
+  const batches = [];
+  for (let i = 0; i < wireRows.length; i += batchSize) {
+    const slice = wireRows.slice(i, i + batchSize);
+    // Stable idempotency key over the batch's row ids so a re-pushed identical
+    // batch is a no-op replay (the server is also per-row idempotent on id).
+    const key = "cost.report:" + createHash("sha256").update(slice.map((r) => r.id).join("|")).digest("hex").slice(0, 24);
+    const frame = await costReport({ rows: slice }, {
+      base: c.base,
+      token: c.token,
+      idempotencyKey: key,
+      fetchImpl: o.fetchImpl,
+    });
+    const ok = !!(frame && frame.ok);
+    if (ok) reported += slice.length; else failed += slice.length;
+    batches.push({ count: slice.length, ok, code: ok ? undefined : (frame && frame.error && frame.error.code) || "error" });
+  }
+
+  return { enabled: true, rowsRead: rows.length, reported, failed, localUSD, batches };
+}
+
+function round6(n) {
+  return Number(Number(n).toFixed(6));
+}
+
+export const _internals = { ledgerFile, ledgerDir, dayStr, stableJson, REPORT_BATCH };
+
+export default { readLedgerRows, rowId, toReportRow, reportLedger };

package/lib/org/cost-sync.test.mjs

@@ -0,0 +1,153 @@
+/**
+ * cost-sync.test.mjs — read today's router ledger and report rows to Cohort via
+ * cost.report, idempotently and batched, preserving the G16 attribution fields,
+ * reconciling with the local budget total. Tmp ledger dir + injected fetchImpl.
+ * Run: node --test lib/org/cost-sync.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { readLedgerRows, rowId, toReportRow, reportLedger } from "./cost-sync.mjs";
+
+const BASE = "https://org.cohortapp.com";
+const CFG = { org: { cohort: { enabled: true, base: BASE, token: "tok", orgId: "alex-ai" } } };
+const OFF = { org: { cohort: { enabled: false } } };
+const DAY = "2026-06-11";
+
+delete process.env.COHORT_API_TOKEN;
+delete process.env.COHORT_TOKEN;
+
+/** Write a JSONL ledger file for a day under a fresh tmp ledger dir. Returns dir. */
+function tmpLedger(rows, day = DAY) {
+  const dir = mkdtempSync(join(tmpdir(), "cost-sync-"));
+  mkdirSync(dir, { recursive: true });
+  const body = rows.map((r) => JSON.stringify(r)).join("\n") + "\n";
+  writeFileSync(join(dir, `${day}.jsonl`), body);
+  return dir;
+}
+
+function fakeFetch(responder) {
+  const calls = [];
+  const impl = async (url, init) => {
+    calls.push({ url, init, headers: (init && init.headers) || {}, body: init && init.body ? JSON.parse(init.body) : null });
+    const r = responder ? responder(url, init, calls.length - 1) : null;
+    const status = r && typeof r.status === "number" ? r.status : 200;
+    const ok = r && typeof r.ok === "boolean" ? r.ok : status >= 200 && status < 300;
+    const body = r ? r.body : { ok: true, result: null };
+    return { ok, status, headers: { get: () => undefined }, json: async () => body };
+  };
+  impl.calls = calls;
+  return impl;
+}
+
+const SAMPLE_ROWS = [
+  { ts: `${DAY}T01:00:00.000Z`, agent: "alex", model: "claude-opus-4", input_tokens: 1000, output_tokens: 200, estimated_usd: 0.05, decision_id: "d-1", session_id: "s-1", source: "router", cadence: null },
+  { ts: `${DAY}T02:00:00.000Z`, agent: "alex", model: "claude-haiku", input_tokens: 500, output_tokens: 50, estimated_usd: 0.001, session_id: "s-2", source: "cadence", lane: "org-sync" },
+];
+
+// --- read + normalise ------------------------------------------------------
+
+test("readLedgerRows: parses JSONL, skips blank/corrupt lines, [] when missing", () => {
+  const dir = tmpLedger(SAMPLE_ROWS);
+  const rows = readLedgerRows({ ledgerDir: dir, day: DAY });
+  assert.equal(rows.length, 2);
+  assert.equal(rows[0].decision_id, "d-1");
+  // missing file → []
+  assert.deepEqual(readLedgerRows({ ledgerDir: dir, day: "1999-01-01" }), []);
+  // corrupt line is skipped
+  const dir2 = mkdtempSync(join(tmpdir(), "cost-sync-corrupt-"));
+  writeFileSync(join(dir2, `${DAY}.jsonl`), '{"agent":"a","estimated_usd":1}\nnot json\n\n{"agent":"b","estimated_usd":2}\n');
+  assert.equal(readLedgerRows({ ledgerDir: dir2, day: DAY }).length, 2);
+});
+
+test("rowId: stable identity (id > natural keys > content hash)", () => {
+  assert.equal(rowId({ id: "explicit" }), "explicit");
+  assert.equal(rowId({ decision_id: "d", session_id: "s", ts: "t" }), "d:s:t");
+  const h1 = rowId({ agent: "a", estimated_usd: 1 });
+  const h2 = rowId({ estimated_usd: 1, agent: "a" }); // key order independent
+  assert.equal(h1, h2);
+  assert.notEqual(rowId({ agent: "a" }), rowId({ agent: "b" }));
+});
+
+test("toReportRow: preserves the G16 attribution fields (source/cadence) + budget figure", () => {
+  const wire = toReportRow(SAMPLE_ROWS[1], { day: DAY });
+  assert.equal(wire.source, "cadence");
+  assert.equal(wire.cadence, "org-sync");           // falls back to `lane`
+  assert.equal(wire.estimated_usd, 0.001);
+  assert.equal(wire.day, DAY);
+  assert.ok(wire.id);
+});
+
+// --- reportLedger: idempotent batched push ---------------------------------
+
+test("reportLedger: posts rows to cost.report, reconciles local USD total", async () => {
+  const dir = tmpLedger(SAMPLE_ROWS);
+  const f = fakeFetch((url) => (url.endsWith("/v1/cost.report") ? { body: { ok: true, result: { ingested: 2 } } } : null));
+  const out = await reportLedger({ cfg: CFG, ledgerDir: dir, day: DAY, fetchImpl: f });
+  assert.equal(out.enabled, true);
+  assert.equal(out.rowsRead, 2);
+  assert.equal(out.reported, 2);
+  assert.equal(out.failed, 0);
+  // reconciles with budget-guard's view (sum of estimated_usd)
+  assert.equal(out.localUSD, 0.051);
+  // one batch (default batch size), routed to cost.report
+  const reportCalls = f.calls.filter((c) => c.url.endsWith("/v1/cost.report"));
+  assert.equal(reportCalls.length, 1);
+  assert.equal(reportCalls[0].body.rows.length, 2);
+  // each wire row carried its stable id + attribution
+  assert.ok(reportCalls[0].body.rows[0].id);
+  assert.equal(reportCalls[0].body.rows[1].source, "cadence");
+});
+
+test("reportLedger: idempotency key is stable across re-runs of the same rows", async () => {
+  const dir = tmpLedger(SAMPLE_ROWS);
+  const f1 = fakeFetch(() => ({ body: { ok: true, result: null } }));
+  const f2 = fakeFetch(() => ({ body: { ok: true, result: null } }));
+  await reportLedger({ cfg: CFG, ledgerDir: dir, day: DAY, fetchImpl: f1 });
+  await reportLedger({ cfg: CFG, ledgerDir: dir, day: DAY, fetchImpl: f2 });
+  const k1 = f1.calls.find((c) => c.url.endsWith("/v1/cost.report")).headers["x-idempotency-key"];
+  const k2 = f2.calls.find((c) => c.url.endsWith("/v1/cost.report")).headers["x-idempotency-key"];
+  assert.ok(k1);
+  assert.equal(k1, k2); // same rows → same key → server collapses the replay
+});
+
+test("reportLedger: batches by batchSize", async () => {
+  const many = Array.from({ length: 5 }, (_, i) => ({ id: `r-${i}`, agent: "a", estimated_usd: 0.01 }));
+  const dir = tmpLedger(many);
+  const f = fakeFetch(() => ({ body: { ok: true, result: null } }));
+  const out = await reportLedger({ cfg: CFG, ledgerDir: dir, day: DAY, batchSize: 2, fetchImpl: f });
+  assert.equal(out.reported, 5);
+  assert.equal(out.batches.length, 3); // 2 + 2 + 1
+  assert.deepEqual(out.batches.map((b) => b.count), [2, 2, 1]);
+});
+
+test("reportLedger: disabled org → reports nothing but still reconciles local total", async () => {
+  const dir = tmpLedger(SAMPLE_ROWS);
+  const out = await reportLedger({ cfg: OFF, ledgerDir: dir, day: DAY });
+  assert.equal(out.enabled, false);
+  assert.equal(out.reported, 0);
+  assert.equal(out.localUSD, 0.051);
+});
+
+test("reportLedger: server error → rows counted as failed, never throws", async () => {
+  const dir = tmpLedger(SAMPLE_ROWS);
+  const f = fakeFetch(() => ({ ok: false, status: 500, body: { ok: false, error: { code: "INTERNAL", message: "boom" } } }));
+  const out = await reportLedger({ cfg: CFG, ledgerDir: dir, day: DAY, fetchImpl: f });
+  assert.equal(out.reported, 0);
+  assert.equal(out.failed, 2);
+  assert.equal(out.batches[0].code, "INTERNAL");
+});
+
+test("reportLedger: empty ledger → no call, zero totals", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "cost-sync-empty-"));
+  const f = fakeFetch(() => ({ body: { ok: true, result: null } }));
+  const out = await reportLedger({ cfg: CFG, ledgerDir: dir, day: DAY, fetchImpl: f });
+  assert.equal(out.rowsRead, 0);
+  assert.equal(out.reported, 0);
+  assert.equal(f.calls.length, 0);
+});