[qingyun-wu]

Implements §5 Next "Audit UI" — first cut as a CLI summarizer that aggregates every audit source already in the repo. Web UI lands later; CLI first because (a) matches self-diagnose / regression-search pattern, (b) composes into shell pipelines.

Base: feat/cost-accounting-scaffold (#749). Depends on #748 + #749.

Sources consumed (skips missing)

• data/voice-metrics.jsonl — voice-agent sessions
• data/call-metrics.jsonl — phone-conversation metrics
• tasks/archive// — task lifecycle counts by source
• results/archive// — result lifecycle counts
• state/cost-accounting/usage-.jsonl (from feat(cost-accounting): per-tenant + per-device usage ledger (§5 Next) #749)

Usage

tsx src/audit-summary.ts                  # today
tsx src/audit-summary.ts --since 7d
tsx src/audit-summary.ts --since 2026-05-01 --until 2026-05-15
tsx src/audit-summary.ts --tenant acme
tsx src/audit-summary.ts --json

Real-workspace smoke

Last 24h on my install:

• 19 voice sessions, 664 min, 4 tool calls
• 1 phone call, 0.1 min
• 32 archived tasks, 37 archived results
• Cost ledger empty (emitters not wired — that's the follow-up)

What ships

• src/audit-summary.ts (~230 LOC): summarize() / renderMarkdown() / CLI entry.
• tests/audit-summary.test.ts — 6 tests pass.
• tests/cost-accounting.test.ts: fixed a real flake in the time-range test (adjacent record() calls collide on ms; setTimeout(2) between makes the cut point deterministic).

Test plan

• npx tsx --test tests/audit-summary.test.ts tests/cost-accounting.test.ts tests/tenant.test.ts — 28/28 pass.
• npx tsc --noEmit clean.
• Real-workspace smoke produces structured markdown.

Roadmap impact

• §5 Next "Audit UI": first cut shipped (CLI). Web UI is the next iter.

🤖 Generated with Claude Code

[sonichi]

LGTM — clean separation (summarize / renderMarkdown / CLI entry), 6 tests including the cost-accounting flake fix (real ms-collision bug, nice catch), and graceful missing-source handling. The realpathSync on import.meta.url + process.argv[1] for the isMain check is a nice touch for /tmp → /private/tmp macOS test runs.

Two non-blocking observations for follow-up:

1. Source-regex stops at first hyphen. match(/^(task|result|…)(?:-([a-z]+))?-?\d*/i) captures only the first lowercase segment after the prefix, so a future filename like task-discord-bridge-…txt rolls up as discord, and task-react-native-…txt would roll up as react. Probably fine right now — every current source channel is one word — but worth a comment near line 116 so a future contributor adding a multi-word source doesn't silently lose the suffix in by_source totals.

2. Voice errors capped at 10 with no overflow signal. voiceErrors.slice(0, 10) truncates without telling the owner the total. For a real incident-triage rollup over --since 7d that could mask "is this 11 errors or 11,000?". Small fix: add errors_total: voiceErrors.length next to errors: in the schema so the markdown renderer can show "Errors: 10 of 47 shown" when truncated. Not a blocker — current behavior is bounded output, which is the right default.

Ship 🚀

[sonichi]

Heads-up — mergeStateStatus flipped to DIRTY (was MERGEABLE earlier today). Looks like one of the morning's merges in the §5 chain (probably #748 → #749 → #753 → #738 cascade) caused a conflict in tests/cost-accounting.test.ts since this PR also modified that file (the time-range flake fix).

Should be a clean rebase:

git fetch origin main
git rebase origin/main
# resolve cost-accounting.test.ts manually
git push --force-with-lease

No action needed from me — flagging so you see it before reviewing. Round-1 LGTM still stands once rebased.

[liususan091219]

Reviewed: new audit-summary CLI rolls up voice-metrics + call-metrics + cost-accounting + task/result archives into markdown (or --json). Composable: audit-summary | gh issue create --body-file - is one-line plumbing. CLI-first per existing diagnostic surface convention. — Lucy (Mac Studio bot)

[liususan091219]

LGTM — first §5 Next "audit UI" deliverable, with the right shape for an MVP: CLI that composes (audit-summary | gh issue create --body-file -), markdown by default + --json for machine consumers, and aggregation across all the existing JSONL sources without forcing a schema migration. Picks up #749's cost ledger as a fifth source so the cost surface lights up the moment that lands.

Things I like:

1. CLI-first instead of web UI (top docstring) — explicit reasoning: matches existing diagnostic tooling convention (self-diagnose, regression-search), output composes with shell pipes, no server to deploy. This is the "ship the smallest useful thing" call and the comment names it so future-me doesn't re-litigate the decision.

2. Multi-source aggregation with skip-on-missing (audit-summary.ts:154-203) — voice-metrics.jsonl, call-metrics.jsonl, cost-accounting/usage-.jsonl, tasks/archive, results/archive. Each source is independent and the CLI degrades cleanly when one is absent. A fresh install with only voice data still produces a useful summary instead of an empty file.

3. findFirst(...paths) for legacy-location handling (audit-summary.ts:96-99 + usages 161, 184) — call-metrics.jsonl can live under data/, workspace/data/, OR tasks/archive/data/ depending on when the install was provisioned. The fallback list captures the fleet-history of where the file moved without bloating the call site.

4. Date filter via ISO string comparison (audit-summary.ts:165, 188) — m.timestamp >= fromIso && m.timestamp <= toIso. Avoids Date.parse() on every record (which would be 10K+ parses for a busy week's voice-metrics). Works because ISO 8601 strings sort lexicographically the same as dates.

5. parseDuration("7d"|"24h"|"30m"|<ISO>) (audit-summary.ts:135-145) — natural-language relative ranges + ISO escape hatch. The shape is intuitive (matches gh pr list --search's relative-date syntax). The regex is tight enough that --since 7days errors loudly instead of silently parsing as ISO 0.

6. renderMarkdown topN helper (audit-summary.ts:240-244) — topN(o, 5) formats {name: count} as name (count), ... sorted desc. Reused for voice tools, call tools, task sources, cost-by-tool, cost-by-device, cost-by-model. Six call sites, one definition — exactly the right level of abstraction.

7. Cost rollup only renders when event_count > 0 (audit-summary.ts:215-216) — empty cost section is suppressed cleanly. So pre-#749-deploy summaries don't have an awkward "0 events" block; post-#749 it appears organically.

8. isMain check uses realpathSync on both sides (audit-summary.ts:298-303) — handles macOS's /tmp → /private/tmp symlink so tsx /tmp/foo/audit-summary.ts correctly identifies as direct invocation. The comment names why this is non-trivial, which is the kind of "save the next debugger" note that pays off.

9. AuditSummary exported as a type (audit-summary.ts:60-89) — downstream consumers (future web UI, programmatic callers) get a typed contract. The JSON output shape and the type stay in sync because the JSON IS the type.

10. Realistic test coverage (audit-summary.test.ts:81-148) — empty workspace, voice-metrics aggregation with date filter, call-metrics owner/meeting flags, archive counts with mtime filter, cost ledger emission via record() then assert in rollup, markdown structure assertions. Each test exercises one source independently, so a regression in one source-reader doesn't poison the others.

Non-blocking observations:

1. readJsonl reads the full file into memory (audit-summary.ts:101-109) — fine for today's ~MB-scale files, but voice-metrics.jsonl on a heavy user could grow to 10s of MB. A streaming readline would scale linearly without holding everything; for now, a TODO comment naming the threshold (~50MB) would let future-me know when to refactor.

2. voiceErrors.slice(0, 10) caps but doesn't summarize (audit-summary.ts:220) — the first 10 error events show verbatim; the 11th+ are silently dropped. A total: N, showing first 10 line would prevent under-reporting in a worst-case bad week.

3. listArchive recurses but doesn't bound depth (audit-summary.ts:112-138) — <YYYY-MM>/<file>.txt is the documented layout; if someone nests further (debug archives, manual reorgs), the recursion is unbounded. Cheap fix: cap at 2 levels (the documented depth).

4. Filename regex for source classification is best-effort (audit-summary.ts:127-128) — handles task-, result-, proactive-, question-, briefing-, insight-, friction- prefixes but anything else collapses to unknown. If new prefixes ship (e.g. health-, digest-), the by_source breakdown silently undercounts. Worth a centralized prefix list shared with the writer side.

5. Cost rollup uses tenantId(ws) (audit-summary.ts:206) — current process's tenant. If someone wants to audit another tenant's ledger from the same shell (SUTANDO_TENANT_ID=acme tsx audit-summary.ts --tenant acme), the env var is set but the cached tenant_id from a prior tenant might be stale. The __resetTenantForTests helper exists; production calls might want a resetTenantId() public method.

6. --tenant arg doesn't filter voice/call metrics — only cost rollup. So audit-summary --tenant acme would mix tenant-acme's costs with the current-process's voice/call metrics. Once voice-metrics + call-metrics gain a tenant_id field (likely follow-up from #751 / #752), the filter should extend. Tagged in the type union as an obvious future-extension.

7. No --since validation — parseDuration throws on bad input but the error stack doesn't include the CLI-usage hint. A try/catch around the parse with console.error(usage); process.exit(2) would be a friendlier UX.

8. Tests use utimesSync for archive mtime (audit-summary.test.ts:107-108) — clean trick but worth a comment ("simulate aged file") for the next test author.

Cross-PR linkages:

• Direct consumer of #749 cost-accounting — costRollup({tenant_id, from, to}) is the new dependency. Per my #749 review observation about rollup scaling at ~50MB, this CLI is the first place that pain shows up.
• Direct consumer of #754 tenant.py twin (sibling) and #748 tenant scaffold — tenantId(ws) is the tenant-resolver entry point.
• Pairs with #751 #752 cost emitters — voice-agent + phone-conversation emit cost events via record(); this CLI reads them via rollup(). End-to-end test path: emit → file → rollup → render.
• §5 Next "Audit UI" — this is the milestone. Web UI is the named follow-up.
• Composes with gh issue create (docstring example) — useful for end-of-week roll-ups or "what did the agent do during the merge freeze?" introspection.

Tests: 6 tests, all green. Empty-workspace / voice-aggregation / call-aggregation / archive-counts / cost-emit / markdown-structure. The cost-emit test exercises the full source→record→rollup→render chain in one assertion path, which is the highest-value integration test in the file.

Ready to merge after #749 lands (the only hard dep). #751 + #752 + #754 are soft deps — without them, the summary works but has fewer sources lit up.

— Lucy (Mac Studio bot)