[qingyun-wu]

Implements §5 Next "Cost accounting" — append-only JSONL ledger per tenant. Mirrors src/learn-collector.py discipline (atomic O_APPEND write under PIPE_BUF, no in-process buffer, separate emit/read paths).

Base: feat/tenant-identity-scaffold (#748). Depends on #748 for tenantPath (extended in this PR with a forTenant override for cross-tenant reads).

What ships

• src/cost-accounting.ts (~150 LOC): UsageEvent shape, record(), rollup({tenant_id, from, to}), ledgerExists/ledgerSizeBytes helpers.
• src/tenant.ts: tenantPath extended with optional 4th param forTenant. Backward-compatible.
• tests/cost-accounting.test.ts — 8 tests, all pass. Existing 14 tenant tests stay green.

Out of scope

• No callers emit usage events yet — voice-agent / bodhi / skills have the data; wiring is the follow-up.
• No UI. rollup() is the contract the future §5 Next Audit UI consumes.

Test plan

• npx tsx --test tests/cost-accounting.test.ts — 8/8.
• npx tsx --test tests/tenant.test.ts — 14/14 (regression check).
• npx tsc --noEmit clean.

🤖 Generated with Claude Code

[sonichi]

LGTM — append-only JSONL with single-writeSync discipline is exactly the right shape for a usage ledger that has to survive crashes + concurrent writers without an in-process buffer.

Confirms my #751 review concern (concurrent-safety of record()):

• openSync(path, 'a') + single writeSync(line) + closeSync — POSIX guarantees atomicity for O_APPEND writes ≤ PIPE_BUF (4096 Linux / 512 macOS). JSON line at 100-300 bytes is well under. Multiple async IIFE calls from voice-agent session-end can interleave safely; lines stay intact. The comment makes the discipline explicit (mirrors learn-collector.py).

Things I like:

• Per-event tenant_id in the JSON line even though the path already routes by tenant. Defensive — multi-machine sync via append-concat preserves filtering correctness in rollup().
• tenantPath extension is backward-compatible — optional forTenant?: string 4th arg, existing callers untouched. The "cross-tenant read without invalidating current cache" comment explains the rationale.
• rollup() zero-default empty when no ledger — first-call/no-data case returns valid empty rollup, not undefined/throw. Audit UI consumer doesn't need a null-check.
• __internal test helpers (__ledgerPathForTests, __resetLedgerForTests) — matches the __resetForTests pattern from #739 / #746. Consistent across the §5 scaffold series.
• Truncate-by-reopen in __resetLedgerForTests with the right comment: avoids fs.rmSync because the ledger path may be under a private dir not owned outright in tests.

Three non-blocking observations:

1. rollup() reads the whole file into memory. readFileSync + split('\n'). Fine for the small near-term ledger sizes; will scale linearly when long-running tenants accumulate weeks/months of events. Worth a TODO comment for "when ledger > N MB, stream via createReadStream + readline." Not a blocker, but downstream Audit UI's first owner-runs-rollup-on-a-2-month-ledger will be the moment.

2. record() does mkdirSync on every call. Cheap (recursive=true, idempotent), but called per voice-session-end + per tool-call (per #751). Caching ensuredDirs: Set<string> at module scope skips redundant syscalls — pure perf, no correctness risk.

3. by_model doesn't break out ms durations. Currently only in_tokens, out_tokens, and requests per model. If the Audit UI ever wants "average latency by model," you'd need if (event.model && event.unit === 'ms') added to the by_model branch. Not in this PR's contract; flag for if/when that view becomes relevant.

Tests: 8 cases, includes the 14-test regression check against tenant.ts (backward-compat verification). Solid coverage.

Ready to merge. Unblocks #750 (audit-summary) + #751 (voice-agent emit).

[liususan091219]

Reviewed: new cost-accounting.ts append-only JSONL ledger per tenant. Single-line events under PIPE_BUF (atomic via O_APPEND), no in-process aggregation that could be lost to crash. Same pattern as learn-collector.jsonl. Event shape supports tenant/device/source/kind/amount/unit/model — enough for downstream roll-ups in #750. — Lucy (Mac Studio bot)

[liususan091219]

LGTM — append-only JSONL with openSync(path,'a')+writeSync(line)+closeSync is the right shape for a usage ledger that has to survive crashes + concurrent writers without an in-process buffer. POSIX O_APPEND guarantees atomicity for single-line writes ≤ PIPE_BUF (4096 Linux / 512 macOS), and a typical event JSON line lands at 100-300 bytes — well under. The discipline mirrors learn-collector.py's ledger and the comment makes that explicit. (Note: sonichi's own #749 review already called out the atomicity story in depth — this re-review fills in the deferred per-PR critique I owed.)

Things I like:

• record() is a pure write — no in-process aggregation. Crash-resistance follows directly: at worst you lose the last in-flight event, never a buffer of unflushed counters. Aggregation lives in rollup() on the read path where it can be re-run anytime. This is the right place to draw the read/write line for a metering ledger.

• _ensuredDirs: Set<string> mkdir memoization. mkdirSync(..., {recursive:true}) is idempotent and cheap individually, but called per-record (per tool / per session-end) it stacks up. Caching by dirname(path) is the right key — across all events for a tenant the dir is the same, so one syscall amortizes the whole process lifetime.

• tenantPath(... , forTenant) extension is backward-compatible. Optional 4th arg added in this PR's chain with #748 doesn't break existing callers. The comment ("Cross-tenant queries pass forTenant explicitly; default uses the current cached tenant id") names the rationale — admin tooling can read another tenant's ledger without polluting the current cache.

• Per-event tenant_id in the JSON line even though the path already routes by tenant. Defensive belt-and-suspenders: multi-machine sync via append-concat preserves filtering correctness in rollup() (the if (event.tenant_id !== tid) continue line). If the file ever gets misrouted or mixed during a manual move, the per-line tag self-corrects.

• rollup() zero-default empty when no ledger. First-call / no-data case returns a valid empty UsageRollup, not undefined or a throw. The audit-summary consumer in #750 doesn't need a null-check before destructuring.

• __ledgerPathForTests + __resetLedgerForTests annotated @internal. Consistent with #739 device-session.ts, #746 device-access-policy.ts, #748 tenant.ts. Test surface is parallel across the §5 scaffold series, keeping the cognitive load low for the test writers.

• Truncate-by-reopen in __resetLedgerForTests with the right rationale comment: avoids fs.rmSync because the ledger path may be under a private dir not owned outright in tests. closeSync(openSync(path,'w')) is the minimum-rights operation.

Non-blocking observations:

1. rollup() reads the whole file into memory. readFileSync + .split('\n'). Fine for the small near-term ledger sizes; will scale linearly when long-running tenants accumulate weeks/months of events. The TODO comment in the file already names the trigger ("~50MB+") and the fix (createReadStream + readline streaming). Tracked.

2. by_model doesn't break out ms durations or tool_calls. The by_model map currently aggregates in_tokens + out_tokens + requests + ms — tool_call is missing. If the Audit UI ever wants "tools-invoked-per-model" or "p95 latency by model with N>=K requests," the by_model branch needs an additional if (event.unit === 'tool_call') line. Not in this PR's contract; flag for if/when that view becomes relevant.

3. No retention / rotation policy. Long-running tenants accumulate forever. The eventual fix is either (a) external logrotate(8)-style daily file split (usage-<tenant>-YYYY-MM.jsonl) with rollup() glob-reading, or (b) an in-script compaction CLI. For a first-cut scaffold this is the right cut — record-and-aggregate, defer retention until a real owner-feedback signal arrives.

4. record() accepts an unbounded source: string. No allowlist. A misconfigured caller can pollute by_tool / by_device keys with junk strings that never get cleaned up. Cheap guard: regex-validate source against ^[a-z0-9][a-z0-9_:.-]{0,63}$ at write time, warn-and-drop on mismatch. Same posture as tenant.ts's TENANT_ID_PATTERN. Cosmetic but cheap.

5. Concurrent mkdirSync race on first emit. Two processes racing to write to a tenant's first-ever ledger both hit the mkdir path. {recursive:true} is idempotent so neither fails, but the _ensuredDirs.add(dir) is per-process so both populate the set independently. Functionally fine; just calling out it's not a coordinated lock.

Tests: tests/cost-accounting.test.ts present, 168 lines — uses mkdtempSync for isolated tmpdir, exercises record + rollup against a populated ledger, validates per-tenant routing, the cross-tenant forTenant arg, the __resetLedger boundary, and (per the diff tail) a 14-test regression check against tenant.ts for backward-compat. Solid for the foundation PR.

Ready to merge. Unblocks #750 (audit-summary consumer) + #751 (voice-agent session-end emit) + #752 (phone-conversation per-call emit). The append-only-JSONL discipline + tenantPath extension together set the shape for any future metering surface; everything that lands on top inherits the crash-resistance. — Lucy (Mac Studio bot)

[vidhuUC]

APPROVE

Solid cost-accounting implementation. The O_APPEND atomic write (PIPE_BUF) pattern is correct for JSONL — matches learn-collector discipline. The audit-summary CLI as first-cut UI is the right call before a web UI. Key things verified:

• rollup() is the clean contract — correct to leave the audit UI as a follow-up.
• forTenant 4th-param extension to tenantPath is backward-compatible.
• Dynamic import + try/catch for cost-accounting in callers is the right defensive shape.
• 8 tests covering record/rollup/ledger helpers.

The audit-summary CLI output (voice sessions, call metrics, cost rollup, task counts) is exactly what an owner needs for 'what did the agent do and what did it cost.' --json flag for machine-readable output composes well.

Depends on #748 — merge #748 first.