fix(diagnose): format disk byte counters as sizes, not percentages

[agent-zhang-beihai]

What was broken

insforge diagnose metrics formatted every non-network metric as a percentage, so the raw disk byte counters returned by the metrics API were rendered with a percent sign:

Disk Usage    42.1%            <- correct
disk_total    8511270912.0%    <- wrong, this is bytes
disk_used     ...%
disk_database ...%
disk_wal      ...%

The affected counters also had no METRIC_LABELS entry, so they showed up under their raw metric names.

What changed

src/commands/diagnose/metrics.ts:

• Added BYTE_METRICS = new Set(['disk_used', 'disk_total', 'disk_database', 'disk_wal']), checked in formatValue before the percent fallback so those metrics route through formatBytes. Mirrors the existing BYTE_METRICS pattern in src/commands/usage/index.ts.
• Extended formatBytes past MB to GB/TB, so multi-GB volumes read as 7.9 GB instead of 8116.0 MB.
• Added the four missing METRIC_LABELS entries: Disk Used / Disk Total / Disk Database / Disk WAL.

disk_usage remains a percentage, and network metrics keep their /s suffix. No flags, command names, or JSON output shapes changed — the --json path already emitted raw numbers and is untouched, so no InsForge/agent-skills update is needed for this fix.

How it was verified

• New src/commands/diagnose/metrics.test.ts pins the behavior: formatValue('disk_total', 8511270912) → "7.9 GB", the KB/MB/GB/TB ladder, formatValue('disk_usage', 42.1) → "42.1%", and the network rate cases.
• npm run lint (full vitest suite + eslint): 784 passed, 13 skipped, no eslint findings.
• npm run build: clean.

Addresses user feedback 1dbfad65-96ad-4f6f-bfb1-88040b7aafab (cli): diagnose metrics formats byte counters as percentages

---

Summary by cubic

Fixes insforge diagnose metrics rendering of disk byte counters. Previously, non-network metrics showed a percent sign; now disk_* byte counters render as human-readable sizes with proper labels. This improves CLI readability without changing JSON output.

• Routes disk_used, disk_total, disk_database, disk_wal through a BYTE_METRICS path so they use formatBytes.
• Extends formatBytes to support GB/TB; adds METRIC_LABELS for the four disk counters.
• Keeps disk_usage as a percentage and network_* as B/s; --json output remains raw numbers.
• Adds tests to pin formatting behavior.

Addresses Linear feedback 1dbfad65.

^{Written for commit 4b68c18. Summary will update on new commits.}

Note

Fix disk byte counter formatting in diagnose metrics to display as sizes

• Disk metrics (disk_used, disk_total, disk_database, disk_wal) were previously formatted as percentages; they now render as human-readable byte sizes (e.g. 1.2 GB).
• Adds a BYTE_METRICS set in metrics.ts to identify raw byte counters, and updates formatValue to branch on this set.
• Extends formatBytes to support GB and TB units in addition to B, KB, and MB.
• Behavioral Change: any large byte value previously displayed as a percentage string will now display as a size string.

^{Macroscope summarized 4b68c18.}

[greptile-apps]

Greptile Summary

The PR corrects human-readable diagnostic metric output by formatting four disk counters as byte sizes and assigning descriptive labels, while preserving percentage and network-rate formatting.

• Adds explicit classification and labels for disk used, total, database, and WAL byte metrics.
• Extends byte formatting through GB and TB units.
• Adds focused tests covering disk sizes, percentages, and network rates.

Confidence Score: 5/5

The PR appears safe to merge with no actionable defects identified.

The changed formatter correctly routes the four current disk byte counters through byte-size formatting while retaining the established behavior for percentage and network metrics, and the tests cover the relevant unit boundaries.

Important Files Changed

Filename	Overview
src/commands/diagnose/metrics.ts	Correctly classifies disk byte counters, adds readable labels, and extends the existing formatter through GB and TB without changing JSON output.
src/commands/diagnose/metrics.test.ts	Adds targeted regression coverage for all newly classified counters and verifies existing percentage and network-rate behavior.

_{Reviews (1): Last reviewed commit: "fix(diagnose): format disk byte counters..." | Re-trigger Greptile}

[jwfing]

Review — fix(diagnose): format disk byte counters as sizes, not percentages

Summary: A tight, well-tested bugfix that routes disk_* byte counters through formatBytes (with GB/TB support) instead of the percent fallback, and adds the four missing table labels — no Critical issues found.

Requirements context

Consulted docs/specs/2026-03-27-diagnose-command-design.md and docs/specs/2026-03-27-diagnose-implementation-plan.md. The design specifies Disk Usage 42.1% and "Network values (bytes/sec) auto-scaled to B/KB/MB" — this fix keeps disk_usage as a percent and network as a rate while correctly treating the raw byte counters as sizes. Extending the ladder to GB/TB is a reasonable enhancement consistent with the intent (multi-GB volumes shouldn't read as 8116.0 MB). Fully in scope for the referenced feedback item.

Findings

Critical
(none)

Suggestion

• Software engineering — src/commands/diagnose/metrics.test.ts unit-tests formatValue thoroughly (the byte ladder, percent, and network rate cases all check out numerically), but nothing exercises the new METRIC_LABELS entries or the table wiring in metrics.ts:166-176. Low blast radius (a plain Record lookup), so this is optional — a small assertion that disk_wal renders under Disk WAL would fully pin the reported behavior.

Information

• Software engineering — There are now three slightly divergent formatBytes implementations: src/commands/diagnose/metrics.ts:55-65 (1dp, B→TB), src/commands/diagnose/index.ts:386-390 (formatBytesCompact, 1dp, B→MB, no space), and src/commands/usage/index.ts:10-15 (log-based, 2dp, !n → '0 B' guard). Not worth changing in this PR, but a shared formatBytes util would prevent future drift.
• Functionality — The --metrics option help (metrics.ts:125) and the spec still enumerate only cpu_usage,memory_usage,disk_usage,network_in,network_out; the new disk_used/total/database/wal aren't listed. If those counters are always returned (not user-selectable) this is fine as-is; if they're selectable, the help string could mention them. No behavior impact either way.
• Functionality — Verified the fix is complete for its scope: the unified insforge diagnose summary view (index.ts:308-318) only renders disk_usage as a percent and never surfaces the raw byte counters, so there's no parallel byte-as-percent bug left behind.

Security: No security-relevant changes — pure output formatting, no new user input reaching SQL/shell/HTTP, no secrets logged, --json path untouched.

Performance: No concerns — constant-time formatting on an already-fetched, aggregated result set.

Verdict

approved (informational — no Critical findings; the two Suggestion/Information items are optional). Posted as a COMMENT; explicit GitHub approval remains a separate human action.

[jwfing]

LGTM - approved.