Skip to content

feat(diagnostics): add bounded runtime capture CLI - #800

Open
beruro wants to merge 2 commits into
developfrom
junyu/runtime-diagnostics-cli
Open

feat(diagnostics): add bounded runtime capture CLI#800
beruro wants to merge 2 commits into
developfrom
junyu/runtime-diagnostics-cli

Conversation

@beruro

@beruro beruro commented Aug 14, 2026

Copy link
Copy Markdown
Collaborator

Problem

Runtime investigations relied on ad-hoc shell commands and screenshots. There was no repository-owned way to discover the ORGII process tree, record a bounded memory session, attach phase markers, stop safely, or turn samples into reviewable artifacts.

Solution

Add a standalone developer CLI under tools/orgii-diagnostics:

  • pnpm diag:process discovers the ORGII root and related processes without mutating them.
  • pnpm diag:memory records bounded NDJSON samples, supports markers/status/stop/report, and emits JSON, CSV, and Markdown summaries.

The recorder has an explicit lifecycle, a single active-session owner, PID-start-token validation, default 15-second sampling, default 720-sample limit, per-sample process caps, three-error termination, and symmetric timer/watcher cleanup. It is inert until explicitly invoked and adds no App import, Tauri command, frontend subscription, background task, or wire change.

Potential risks

  • macOS WebKit attribution depends on system metadata and can become partial when the OS denies visibility; Linux records the root tree without macOS WebKit attribution, and Windows is rejected explicitly.
  • Reports contain process names, command lines, and memory metadata, so artifacts must be inspected before sharing.
  • Very large user-selected sample limits can create large files and make report generation use more memory.
  • Simultaneous competing recorders are protected by PID identity and exclusive session metadata but have not been stress-tested at high concurrency.
  • Rollback is deletion of the tool directory and three package scripts; there is no application data or schema migration.

Performance guard

Verdict: pass. The tool is opt-in, has one recorder owner, bounded default samples/process details/output, incremental persistence, and symmetric timer/stop-watcher cleanup.

Verification

Validated after merging current develop (017fb9afa) into head 5ee1ad30c without conflicts:

  • pnpm diag:testPASS, 13/13 tests covering parsing, lifecycle/cleanup, process snapshots, redaction, and report generation.
  • pnpm typecheckPASS.
  • git diff --cached --check before the merge commit — PASS.
  • Packaged /Applications/ORG2.app process discovery — PASS against a live installed app root.
  • Packaged memory recording — PASS, 4/4 samples, sample_limit_reached, complete attribution on every sample, no skipped PID, and JSON/CSV/Markdown artifacts generated.
  • The packaged capture identified backend, WebKit GPU, WebKit network, WebKit renderer, and owned tool roles; peak role RSS values were present in the generated report.
  • The temporary packaged app instance was stopped after capture. No user-visible UI change is included, so screenshots are not applicable.

Published GitHub CI on head 5ee1ad30c is fully green: Frontend typecheck/lint/test, Rust clippy, and AI attribution all passed.

@beruro
beruro marked this pull request as ready for review August 14, 2026 15:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant