| name | maintain-diagnostics |
| description | Maintain native diagnostics and operations: runtime metrics, playback counters, verified log discovery/rotation clearing, bounded logging, startup readiness, and operational command boundaries. Use when changing telemetry, log maintenance, or native support workflows. |
Maintain diagnostics and operations
Role and boundary
Keep native diagnostics authoritative, bounded, and text/PCM/credential-free. Operations may inspect process/runtime state and clear only verified Voice Layer log files after confirmation; they must not become generic filesystem access or fabricated product telemetry.
Source map
src-tauri/src/diagnostics.rs: RuntimeDiagnosticsState, RuntimeDiagnosticsSnapshot, CPU/RSS/uptime sampling, PlaybackCounters, gap semantics, verified active/rotated log matching, bounded clear passes, and typed failures.src-tauri/src/lib.rs: log plugin setup, native diagnostic parsing, internally resolved app-log directory, managed diagnostic state, and the three exposed commands read_diagnostics, read_runtime_diagnostics, and clear_native_logs; the directory lookup stays native/internal and is not exposed through IPC.src/debug-contract.ts, src/speech-metrics.ts, and src/main.ts wireDebugPage: typed frontend projections, merge/filter/copy/clear workflow, bounded in-memory ring, and privacy copy.src-tauri/src/tts/playback.rs, src-tauri/src/live/mod.rs, and src-tauri/src/tts/stream.rs: atomic underrun/gap counters and playback metric contexts; tests/debug-contract.test.ts, tests/debug-metrics.test.ts, native diagnostics tests, and relevant playback tests.
Cover
- Sample uptime from monotonic process start; report CPU as process user+system delta over a prior wall-clock window, RSS as macOS availability permits, and explicit unavailable reasons rather than fake zeros.
- Keep Chat underrun frames and qualifying Live
DataPlayedBack excess counters atomic and since-launch; document that they are transport/timing observations, not audible-device proof.
- Recognize only the active
voice-layer.log and correctly shaped timestamped rotated files; clear active files by safe truncation and rotated files by safe removal, with at most three bounded re-scans and per-file/unresolved-activity failures.
- Keep diagnostic lines bounded/classified, avoid conversation/audio/credentials/hidden reasoning, serialize camelCase typed results, and preserve refresh/clear operation serialization and stale-entry invalidation in the UI.
- Inspect current native command registration and logger behavior before changing an operational path. Scope file access to the app-owned log/workspace roots and require explicit user confirmation for clear actions.
Validate and accept
- Run focused native diagnostics/playback tests plus
bun test tests/debug-contract.test.ts tests/debug-metrics.test.ts; run git diff --check against the actual files changed, and run just check when the change crosses TypeScript/Rust/build boundaries.
- Exercise unavailable metrics, log rotation/clear races, failures, copy privacy, and operation serialization in the packaged Debug view through
$test-voice-layer-app.
- Treat live app-log paths, process sampling, startup/readiness, and human authorization to clear logs as operational/device acceptance; do not claim packaged or audible behavior from unit metrics alone.
Relationships
Use $maintain-debug for presentation, $maintain-app-shell/$maintain-navigation for lifecycle, $maintain-voice-output for interpreting playback counters, and $maintain-local-tools for the separate workspace boundary.
