Skip to content

feat: main_thread_sampler.py — sample a stuck PID #62

Description

@conorluddy

Problem

When hang_watcher.py (C1) fires, the next question is always "what's the main thread doing?" macOS sample produces that stack trace, but the raw output is unparseable noise. A summary surface is needed.

Sketch

python scripts/main_thread_sampler.py --pid 12345 --duration 3
python scripts/main_thread_sampler.py --bundle-id com.example.app --duration 5

Wraps sample <pid> <duration> and produces a deduplicated top-of-stack summary: most common frame paths, % time, sample counts.

Reuses

  • resolve_device_identifier + a new bundle_id → pid helper (probably belongs in device_utils)
  • common/cache_utils.ProgressiveCache for the full sample output

Open questions

  • Symbolication when the binary has stripped symbols (production-style builds).
  • Whether to surface a flame-graph-like ASCII view in --verbose.

Definition of done

  • --pid and --bundle-id both working
  • Deduplicated summary in default output
  • Full sample output cached and retrievable
  • --json, --help, SKILL.md updated

Part of the v2.0 coverage expansion epic.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Core features, ship after P1ai-shippableDelegatable to AI agents — clarity:4+ and risk:2 or lowerblast:1Single file — one view or one service, no ripple effectsclarity:3Direction known, details TBD — can start with questionsenhancementNew feature or requestrisk:2Small surface area, existing patterns, minor regression chancesize:MModerate scope, some design neededtype:featureNew functionality or capability

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions