Skip to content

BumpyClock/agent-templates / skills/ios-macos-development

ios-macos-development

Flagged

Build, debug, or release iOS and macOS apps with Swift and Apple platform tools.

FileKindSize
SKILL.mdskill md2.1 KB
agents/openai.yamlconfig278 B
app-store-connect-cli/asc-app-create-ui/guide.mdmarkdown6.3 KB
app-store-connect-cli/asc-build-lifecycle/guide.mdmarkdown1.8 KB
app-store-connect-cli/asc-cli-usage/guide.mdmarkdown1.3 KB
app-store-connect-cli/asc-id-resolver/guide.mdmarkdown1.3 KB
app-store-connect-cli/asc-metadata-sync/guide.mdmarkdown4.5 KB
app-store-connect-cli/asc-notarization/guide.mdmarkdown7.2 KB
app-store-connect-cli/asc-ppp-pricing/guide.mdmarkdown4.4 KB
app-store-connect-cli/asc-release-flow/guide.mdmarkdown4.7 KB
app-store-connect-cli/asc-shots-pipeline/guide.mdmarkdown10.7 KB
app-store-connect-cli/asc-signing-setup/guide.mdmarkdown2.6 KB
app-store-connect-cli/asc-submission-health/guide.mdmarkdown6.9 KB
app-store-connect-cli/asc-subscription-localization/guide.mdmarkdown10.2 KB
app-store-connect-cli/asc-testflight-orchestration/guide.mdmarkdown1.7 KB
app-store-connect-cli/asc-workflow/guide.mdmarkdown5.3 KB
app-store-connect-cli/asc-xcode-build/guide.mdmarkdown3.7 KB
app-store-connect-cli/guide.mdmarkdown3.6 KB
instruments-profiling/guide.mdmarkdown3.7 KB
ios-app-intents/guide.mdmarkdown4.8 KB
ios-app-intents/references/code-templates.mdmarkdown7.4 KB
ios-app-intents/references/example-patterns.mdmarkdown3.6 KB
ios-app-intents/references/first-pass-checklist.mdmarkdown1.4 KB
ios-app-intents/references/system-surfaces.mdmarkdown1.0 KB
ios-debugger-agent/guide.mdmarkdown2.7 KB
ios-simulator/guide.mdmarkdown21.0 KB
ios-simulator/references/accessibility_checklist.mdmarkdown1.5 KB
ios-simulator/references/idb_quick.mdmarkdown1.1 KB
ios-simulator/references/simctl_quick.mdmarkdown1.3 KB
ios-simulator/references/test_patterns.mdmarkdown1.6 KB
ios-simulator/references/troubleshooting.mdmarkdown1.3 KB
ios-simulator/scripts/accessibility_audit.pyexecutablescript10.3 KB
ios-simulator/scripts/app_launcher.pyexecutablescript9.7 KB
ios-simulator/scripts/app_state_capture.pyexecutablescript13.2 KB
ios-simulator/scripts/appearance.pyscript11.3 KB
ios-simulator/scripts/build_and_test.pyexecutablescript11.3 KB
ios-simulator/scripts/clipboard.pyscript2.6 KB
ios-simulator/scripts/common/__init__.pyscript1.5 KB
ios-simulator/scripts/common/cache_utils.pyscript9.3 KB
ios-simulator/scripts/common/device_utils.pyscript13.5 KB
ios-simulator/scripts/common/env_config.pyscript1.1 KB
ios-simulator/scripts/common/hang_pipeline.pyscript29.6 KB
ios-simulator/scripts/common/hang_sessions.pyscript17.9 KB
ios-simulator/scripts/common/idb_utils.pyscript5.3 KB
ios-simulator/scripts/common/screenshot_utils.pyscript10.0 KB
ios-simulator/scripts/container.pyscript22.7 KB
ios-simulator/scripts/gesture.pyexecutablescript12.3 KB
ios-simulator/scripts/hang_watcher.pyscript56.5 KB
ios-simulator/scripts/keyboard.pyexecutablescript11.5 KB
ios-simulator/scripts/localization_audit.pyscript16.2 KB
ios-simulator/scripts/location.pyscript15.4 KB
ios-simulator/scripts/log_monitor.pyexecutablescript14.8 KB
ios-simulator/scripts/model_inspector.pyscript21.7 KB
ios-simulator/scripts/navigator.pyexecutablescript14.2 KB
ios-simulator/scripts/privacy_manager.pyscript8.7 KB
ios-simulator/scripts/push_notification.pyscript6.5 KB
ios-simulator/scripts/screen_mapper.pyexecutablescript10.7 KB
ios-simulator/scripts/sim_health_check.shscript8.1 KB
ios-simulator/scripts/sim_list.pyscript8.9 KB
ios-simulator/scripts/simctl_boot.pyexecutablescript9.1 KB
ios-simulator/scripts/simctl_create.pyexecutablescript8.9 KB
ios-simulator/scripts/simctl_delete.pyexecutablescript10.3 KB
ios-simulator/scripts/simctl_erase.pyexecutablescript10.2 KB
ios-simulator/scripts/simctl_shutdown.pyexecutablescript8.4 KB
ios-simulator/scripts/simulator_selector.pyexecutablescript10.3 KB
ios-simulator/scripts/status_bar.pyscript6.6 KB
ios-simulator/scripts/test_recorder.pyexecutablescript10.6 KB
ios-simulator/scripts/visual_diff.pyexecutablescript7.6 KB
ios-simulator/scripts/xcode/__init__.pyscript378 B
ios-simulator/scripts/xcode/builder.pyscript13.2 KB
ios-simulator/scripts/xcode/cache.pyscript5.5 KB
ios-simulator/scripts/xcode/config.pyscript5.4 KB
ios-simulator/scripts/xcode/reporter.pyscript10.7 KB
ios-simulator/scripts/xcode/xcresult.pyscript16.5 KB
native-app-performance/attribution.txtmarkdown349 B
native-app-performance/guide.mdmarkdown2.1 KB
native-app-performance/scripts/extract_time_samples.pyscript1.1 KB
native-app-performance/scripts/record_time_profiler.shscript1.3 KB
native-app-performance/scripts/top_hotspots.pyscript4.0 KB
swift-concurrency-expert/attribution.txtmarkdown353 B
swift-concurrency-expert/guide.mdmarkdown1.9 KB
swift-concurrency-expert/references/swift-6-2-concurrency.mdmarkdown4.3 KB
swift-concurrency-expert/references/swiftui-concurrency-tour-wwdc.mdmarkdown1.6 KB
swift-ui/guide.mdmarkdown1.0 KB
swift-ui/references/index.mdmarkdown4.2 KB
swift-ui/references/liquid-glass/appkit.mdmarkdown3.3 KB
swift-ui/references/liquid-glass/overview.mdmarkdown1.6 KB
swift-ui/references/liquid-glass/patterns.mdmarkdown3.9 KB
swift-ui/references/liquid-glass/swiftui.mdmarkdown4.0 KB
swift-ui/references/logging-private-fix.mdmarkdown8.0 KB
swift-ui/references/modern-swift.mdmarkdown2.9 KB
swift-ui/references/swift-concurrency.mdmarkdown39.6 KB
swift-ui/references/swift-testing-playbook.mdmarkdown35.3 KB
swift-ui/references/swiftui.mdmarkdown1.8 MB
swift-ui/references/toolbar/swiftui-features.mdmarkdown4.7 KB
swiftui-liquid-glass/attribution.txtmarkdown345 B
swiftui-liquid-glass/guide.mdmarkdown4.1 KB
swiftui-liquid-glass/references/liquid-glass.mdmarkdown8.0 KB
swiftui-performance-audit/attribution.txtmarkdown355 B
swiftui-performance-audit/guide.mdmarkdown1.7 KB
swiftui-performance-audit/references/code-smells.mdmarkdown4.8 KB
swiftui-performance-audit/references/demystify-swiftui-performance-wwdc23.mdmarkdown1.8 KB
swiftui-performance-audit/references/optimizing-swiftui-performance-instruments.mdmarkdown1.8 KB
swiftui-performance-audit/references/profiling-intake.mdmarkdown2.4 KB
swiftui-performance-audit/references/report-template.mdmarkdown1.2 KB
swiftui-performance-audit/references/understanding-hangs-in-your-app.mdmarkdown1.2 KB
swiftui-performance-audit/references/understanding-improving-swiftui-performance.mdmarkdown2.2 KB
swiftui-ui-patterns/guide.mdmarkdown2.0 KB
swiftui-ui-patterns/references/app-wiring.mdmarkdown6.5 KB
swiftui-ui-patterns/references/async-state.mdmarkdown3.5 KB
swiftui-ui-patterns/references/components-index.mdmarkdown4.2 KB
swiftui-ui-patterns/references/controls.mdmarkdown1.6 KB
swiftui-ui-patterns/references/deeplinks.mdmarkdown1.7 KB
swiftui-ui-patterns/references/focus.mdmarkdown2.3 KB
swiftui-ui-patterns/references/form.mdmarkdown3.0 KB
swiftui-ui-patterns/references/grids.mdmarkdown1.8 KB
swiftui-ui-patterns/references/haptics.mdmarkdown2.0 KB
swiftui-ui-patterns/references/input-toolbar.mdmarkdown1.4 KB
swiftui-ui-patterns/references/lightweight-clients.mdmarkdown2.5 KB
swiftui-ui-patterns/references/list.mdmarkdown2.7 KB
swiftui-ui-patterns/references/loading-placeholders.mdmarkdown1.2 KB
swiftui-ui-patterns/references/macos-settings.mdmarkdown2.0 KB
swiftui-ui-patterns/references/matched-transitions.mdmarkdown1.6 KB
swiftui-ui-patterns/references/media.mdmarkdown2.0 KB
swiftui-ui-patterns/references/menu-bar.mdmarkdown2.2 KB
swiftui-ui-patterns/references/navigationstack.mdmarkdown4.2 KB
swiftui-ui-patterns/references/overlay.mdmarkdown1.2 KB
swiftui-ui-patterns/references/performance.mdmarkdown1.9 KB
swiftui-ui-patterns/references/previews.mdmarkdown1.6 KB
swiftui-ui-patterns/references/scroll-reveal.mdmarkdown5.2 KB
swiftui-ui-patterns/references/scrollview.mdmarkdown2.3 KB
swiftui-ui-patterns/references/searchable.mdmarkdown1.7 KB
swiftui-ui-patterns/references/sheets.mdmarkdown4.3 KB
swiftui-ui-patterns/references/split-views.mdmarkdown2.0 KB
swiftui-ui-patterns/references/tabview.mdmarkdown3.4 KB
swiftui-ui-patterns/references/theming.mdmarkdown1.7 KB
swiftui-ui-patterns/references/title-menus.mdmarkdown2.1 KB
swiftui-ui-patterns/references/top-bar.mdmarkdown1.3 KB
swiftui-view-refactor/guide.mdmarkdown1.6 KB
swiftui-view-refactor/references/mv-patterns.mdmarkdown2.3 KB

ios-simulator/scripts/hang_watcher.py

View on GitHub
#!/usr/bin/env python3
"""
iOS Simulator Hang Watcher — featuring HangBuster session mode.

Two surfaces live in this file:

1. **HangWatcher** (legacy, --watch / --since) — passive os_log hang stream.
   Backward-compatible with PR #75.
2. **HangBuster** (new, --start / --stop / --get-details / --list-sessions /
   --clear-sessions / --diff) — agent-native session recorder. Detaches a
   worker, normalises and thresholds events on the fly, clusters at stop time,
   emits a token-tight summary with progressive drill paths.

The shared filter pipeline lives in ``common/hang_pipeline.py``; session
storage in ``common/hang_sessions.py``.

Environment variables (all read by ``common.env_config.env_int``):

- ``IOS_SIM_HANG_PREDICATE``         Override the default log predicate
- ``IOS_SIM_HANG_MIN_MS``            Min event duration kept (default 250)
- ``IOS_SIM_HANG_SESSION_TTL_HOURS`` Session prune age (default 24)
- ``IOS_SIM_HANG_DEFAULT_TOP_N``     Default top-N for ``--stop`` L1 (default 3)
- ``IOS_SIM_HANG_BUDGET_TOKENS``     Optional default for ``--budget-tokens``
"""

import argparse
import contextlib
import json
import os
import re
import select
import signal
import subprocess
import sys
import time
from datetime import datetime, timedelta
from pathlib import Path

# Resolve imports whether run from repo root or scripts/ directory
_script_dir = str(Path(__file__).resolve().parent)
if _script_dir not in sys.path:
    sys.path.insert(0, _script_dir)

from common.cache_utils import ProgressiveCache  # noqa: E402
from common.device_utils import resolve_device_identifier  # noqa: E402
from common.env_config import env_int  # noqa: E402
from common.hang_pipeline import (  # noqa: E402
    build_normalised_event,
    compress_to_budget,
    diff_sessions,
    event_to_jsonl,
    format_cluster_detail,
    format_diff,
    format_l0,
    format_l1,
    format_l2,
    summary_to_json,
    symbolicate_stack,
)
from common.hang_pipeline import (  # noqa: E402
    extract_duration_ms as _pipeline_extract_duration_ms,
)
from common.hang_pipeline import (  # noqa: E402
    is_hang_message as _pipeline_is_hang_message,
)
from common.hang_pipeline import (  # noqa: E402
    parse_log_line as _pipeline_parse_log_line,
)
from common.hang_sessions import SessionStore  # noqa: E402

# === CONSTANTS ===

# Default predicate: catches RunningBoard kills + SwiftUI/UIKit micro-hangs.
# Override with env var IOS_SIM_HANG_PREDICATE for custom tuning.
DEFAULT_HANG_PREDICATE = (
    '(subsystem == "com.apple.runningboard") '
    'OR (eventMessage CONTAINS "Hang detected") '
    'OR ((eventMessage CONTAINS[c] "main thread") AND (eventMessage CONTAINS[c] "hang"))'
)

# How many times the worker re-spawns ``log stream`` after an EOF / subprocess
# death before giving up and marking the session crashed. Override via env var
# IOS_SIM_HANG_MAX_RESTARTS.
DEFAULT_MAX_STREAM_RESTARTS = 3
# Backoff between restart attempts. Short — log stream usually recovers fast.
RESTART_BACKOFF_SECONDS = 2.0


def _compute_start_timestamp(duration_str: str) -> str:
    """Parse duration string and return ISO-8601 start timestamp.

    Args:
        duration_str: Duration like '30s', '5m', '1h'.

    Raises:
        ValueError: If the format is unrecognised.
    """
    match = re.match(r"(\d+)([smh])", duration_str.lower())
    if not match:
        raise ValueError(
            f"Invalid duration format: {duration_str!r}. Use format like '30s', '5m', '1h'."
        )

    value, unit = match.groups()
    seconds = int(value) * {"s": 1, "m": 60, "h": 3600}[unit]
    start = datetime.now() - timedelta(seconds=seconds)
    return start.strftime("%Y-%m-%d %H:%M:%S")


# === HANG WATCHER ===


class HangWatcher:
    """Watch for iOS simulator hang events via os_log stream."""

    def __init__(self, udid: str | None = None):
        """Initialize hang watcher.

        Args:
            udid: Device UDID. Resolves to booted simulator if None.
        """
        self.udid = udid
        self.hang_events: list[dict] = []
        self.interrupted = False
        self._process: subprocess.Popen | None = None
        self._cache = ProgressiveCache()

    # === PUBLIC API ===

    def watch(
        self,
        duration_seconds: int | None = None,
        bundle_id: str | None = None,
        predicate: str | None = None,
        verbose: bool = False,
        json_mode: bool = False,
    ) -> bool:
        """Stream hang events live from the simulator.

        Runs `xcrun simctl spawn <udid> log stream --predicate <pred>` and
        parses each line into a structured hang event. Stops after
        duration_seconds or on Ctrl-C.

        Args:
            duration_seconds: Stop after N seconds. None = run until Ctrl-C.
            bundle_id: Filter events to a specific app bundle ID.
            predicate: Custom log predicate. Falls back to env var then default.
            verbose: Emit raw log lines alongside structured events.
            json_mode: Emit JSON objects per line instead of formatted text.

        Returns:
            True if stream ran without fatal errors.
        """
        resolved_udid = self._resolve_udid()
        effective_predicate = _resolve_predicate(predicate)
        cmd = self._build_stream_cmd(resolved_udid, effective_predicate)

        if verbose or not json_mode:
            print(
                f"Watching for hangs on {resolved_udid}",
                file=sys.stderr,
            )
            if bundle_id:
                print(f"Post-parse filter: {bundle_id}", file=sys.stderr)
            print(f"Predicate: {effective_predicate}", file=sys.stderr)

        self._register_signal_handler()

        try:
            self._process = subprocess.Popen(
                cmd,
                stdout=subprocess.PIPE,
                stderr=subprocess.PIPE,
                text=True,
                bufsize=1,
            )

            start_time = datetime.now()

            for raw_line in iter(self._process.stdout.readline, ""):
                if not raw_line:
                    break

                line = raw_line.rstrip()
                event = self._parse_line(line)

                if event:
                    if bundle_id and not self._matches_bundle(event, bundle_id):
                        continue

                    self.hang_events.append(event)

                    if json_mode:
                        print(json.dumps(event))
                        sys.stdout.flush()
                    else:
                        print(self._format_event(event))
                        if verbose:
                            print(f"  raw: {line}")

                elif verbose and line.strip():
                    print(f"  [skip] {line}", file=sys.stderr)

                if (
                    duration_seconds
                    and (datetime.now() - start_time).total_seconds() >= duration_seconds
                ):
                    break

                if self.interrupted:
                    break

            # Terminate before wait — log stream never self-exits on duration elapsed.
            if self._process and self._process.poll() is None:
                self._process.terminate()
                try:
                    self._process.wait(timeout=2)
                except subprocess.TimeoutExpired:
                    self._process.kill()
            return True

        except Exception as error:
            print(f"Error streaming hang events: {error}", file=sys.stderr)
            return False

        finally:
            if self._process and self._process.poll() is None:
                self._process.terminate()

    def show_since(
        self,
        since_duration: str,
        bundle_id: str | None = None,
        predicate: str | None = None,
        verbose: bool = False,
        json_mode: bool = False,
    ) -> bool:
        """Show historical hang events using `log show`.

        Args:
            since_duration: Duration string like "5m", "1h", "30s".
            bundle_id: Filter to a specific app bundle ID.
            predicate: Custom log predicate.
            verbose: Include raw log lines.
            json_mode: Emit JSON objects per line.

        Returns:
            True if command ran without fatal errors.
        """
        resolved_udid = self._resolve_udid()
        effective_predicate = _resolve_predicate(predicate)
        start_timestamp = self._compute_start_timestamp(since_duration)
        cmd = self._build_show_cmd(resolved_udid, effective_predicate, start_timestamp)

        if verbose or not json_mode:
            print(f"Showing hangs since {start_timestamp}", file=sys.stderr)

        try:
            result = subprocess.run(
                cmd,
                capture_output=True,
                text=True,
                timeout=60,
                check=False,
            )

            for raw_line in result.stdout.splitlines():
                line = raw_line.rstrip()
                event = self._parse_line(line)

                if event:
                    if bundle_id and not self._matches_bundle(event, bundle_id):
                        continue

                    self.hang_events.append(event)

                    if json_mode:
                        print(json.dumps(event))
                    else:
                        print(self._format_event(event))
                        if verbose:
                            print(f"  raw: {line}")

            return True

        except subprocess.TimeoutExpired:
            print("Error: log show timed out after 60s", file=sys.stderr)
            return False
        except Exception as error:
            print(f"Error fetching historical hangs: {error}", file=sys.stderr)
            return False

    def get_summary(self) -> str:
        """Return token-efficient summary of captured hang events."""
        total = len(self.hang_events)
        if total == 0:
            return "No hang events detected."

        processes = {}
        for event in self.hang_events:
            proc = event.get("process", "unknown")
            processes[proc] = processes.get(proc, 0) + 1

        top = sorted(processes.items(), key=lambda x: x[1], reverse=True)[:5]
        top_str = ", ".join(f"{p}({c})" for p, c in top)
        return f"Hangs detected: {total} | Processes: {top_str}"

    def get_json_output(self) -> dict:
        """Return full results as a JSON-serialisable dict."""
        return {
            "hang_events": self.hang_events,
            "summary": {
                "total_hangs": len(self.hang_events),
                "processes": list({e.get("process") for e in self.hang_events}),
            },
        }

    def save_to_cache(self) -> str:
        """Persist hang archive to progressive cache and return cache_id."""
        return self._cache.save(self.get_json_output(), "hang-watcher")

    # === PRIVATE HELPERS ===

    def _resolve_udid(self) -> str:
        """Resolve UDID from stored value or booted device."""
        identifier = self.udid or "booted"
        try:
            return resolve_device_identifier(identifier)
        except RuntimeError as error:
            print(f"Error: {error}", file=sys.stderr)
            sys.exit(1)

    def _build_stream_cmd(self, udid: str, predicate: str) -> list[str]:
        """Build xcrun simctl spawn log stream command."""
        return [
            "xcrun",
            "simctl",
            "spawn",
            udid,
            "log",
            "stream",
            "--predicate",
            predicate,
        ]

    def _build_show_cmd(self, udid: str, predicate: str, start: str) -> list[str]:
        """Build xcrun simctl spawn log show command for historical queries."""
        return [
            "xcrun",
            "simctl",
            "spawn",
            udid,
            "log",
            "show",
            "--predicate",
            predicate,
            "--start",
            start,
        ]

    def _parse_line(self, line: str) -> dict | None:
        """Parse a log line into a hang event dict. Delegates to ``hang_pipeline``.

        The legacy event dict carried ``duration_estimate_ms``; we map the
        pipeline's ``duration_ms`` field back onto that name for backward compat.
        """
        event = _pipeline_parse_log_line(line)
        if event is None:
            return None
        if "duration_ms" in event:
            event["duration_estimate_ms"] = event.pop("duration_ms")
        return event

    def _is_hang_message(self, message: str) -> bool:
        """Delegate to ``hang_pipeline.is_hang_message``."""
        return _pipeline_is_hang_message(message)

    def _extract_duration_ms(self, message: str) -> float | None:
        """Delegate to ``hang_pipeline.extract_duration_ms``."""
        return _pipeline_extract_duration_ms(message)

    def _matches_bundle(self, event: dict, bundle_id: str) -> bool:
        """Delegate to module-level ``matches_bundle`` (kept for legacy callers)."""
        return matches_bundle(event, bundle_id)

    def _format_event(self, event: dict) -> str:
        """Format a hang event for human-readable terminal output."""
        duration_str = ""
        if "duration_estimate_ms" in event:
            ms = event["duration_estimate_ms"]
            duration_str = f" [{ms / 1000:.1f}s]" if ms >= 1000 else f" [{ms:.0f}ms]"

        return (
            f"HANG {event['timestamp']} | {event['process']} (PID {event['pid']})"
            f"{duration_str} | {event['message'][:120]}"
        )

    def _compute_start_timestamp(self, duration_str: str) -> str:
        """Parse duration string and return ISO-8601 start timestamp."""
        return _compute_start_timestamp(duration_str)

    def _register_signal_handler(self):
        """Register SIGINT handler for graceful shutdown."""

        def handle_sigint(sig, frame):
            self.interrupted = True
            if self._process:
                self._process.terminate()

        signal.signal(signal.SIGINT, handle_sigint)


# === HANGBUSTER (session mode) ===


def _resolve_predicate(predicate: str | None) -> str:
    """Resolution chain: CLI override → env var → default.

    Bundle filtering is *not* applied here — see ``matches_bundle()``. The
    default hang predicate matches events from RunningBoard, SpringBoard, and
    the watchdog, none of which run inside the target app's process. ANDing a
    ``process == <app>`` clause silently drops the bulk of useful hang signal.
    """
    return predicate or os.getenv("IOS_SIM_HANG_PREDICATE") or DEFAULT_HANG_PREDICATE


def matches_bundle(event: dict, bundle_id: str) -> bool:
    """Check if a parsed log event's process name matches the bundle ID.

    Applied post-parse so hang events from system processes (RunningBoard,
    SpringBoard) still flow through the pipeline; ``--bundle-id`` narrows the
    final output rather than the os_log predicate.
    """
    app_name = bundle_id.rsplit(".", maxsplit=1)[-1].lower()
    return app_name in event.get("process", "").lower()


class HangBuster:
    """Session-mode façade.

    Methods route to ``SessionStore`` + filter pipeline. The worker subprocess
    re-enters this class via ``run_worker()``.
    """

    def __init__(self, store: SessionStore | None = None):
        self.store = store or SessionStore()

    # === PUBLIC API ===

    def start(self, args: dict, udid: str | None) -> str:
        """Create session, detach worker, return session_id once worker registers."""
        self.store.prune_expired()
        aggregate_cap_mb = env_int("IOS_SIM_HANG_TOTAL_CAP_MB", 100)
        if aggregate_cap_mb > 0:
            self.store.prune_to_aggregate_cap(aggregate_cap_mb * 1024 * 1024)
        resolved_udid = self._resolve_udid(udid)
        meta = self.store.create({**args, "udid": resolved_udid})
        cmd = [
            sys.executable,
            __file__,
            "--worker-session-id",
            meta.session_id,
        ]
        # The detached worker survives parent exit. ``start_new_session=True``
        # calls setsid() so the process group is independent of the controlling TTY.
        subprocess.Popen(
            cmd,
            stdout=subprocess.DEVNULL,
            stderr=subprocess.DEVNULL,
            stdin=subprocess.DEVNULL,
            start_new_session=True,
            close_fds=True,
        )
        try:
            self.store.wait_for_worker(meta.session_id, timeout_seconds=3.0)
        except TimeoutError:
            self.store.mark_crashed(meta.session_id)
            raise RuntimeError(f"Worker did not register within 3s for {meta.session_id}") from None
        return meta.session_id

    def stop(
        self,
        session_id: str,
        budget_tokens: int | None = None,
        top_n: int | None = None,
        terse: bool = False,
        json_mode: bool = False,
    ) -> str:
        """Signal worker, drain, build summary, return formatted output."""
        delivered = self.store.signal_worker(session_id, signal.SIGTERM)
        if delivered:
            # Give the worker up to 2s to flush + exit cleanly.
            self._wait_for_worker_exit(session_id, timeout_seconds=2.0)
        meta = self.store.load_meta(session_id)
        line_counters = meta.extras.get("line_counters", {})

        if meta.args.get("raw_capture"):
            # Raw-capture sessions skip the clustering pipeline entirely.
            return self._stop_raw_session(session_id, meta, line_counters, json_mode)

        summary = self.store.build_summary(
            session_id,
            matched_lines=line_counters.get("matched", 0),
            total_lines=line_counters.get("total", 0),
            dropped_below_threshold=line_counters.get("dropped", 0),
        )
        # Apply default top_n at summary-write time — keeps ranked clusters bounded.
        effective_top_n = top_n or env_int("IOS_SIM_HANG_DEFAULT_TOP_N", 3)
        summary.clusters = summary.clusters[:effective_top_n]
        self.store.stop(session_id, summary)
        if json_mode:
            return json.dumps(summary_to_json(summary), indent=2)
        if terse:
            return format_l0(summary)
        budget = budget_tokens or env_int("IOS_SIM_HANG_BUDGET_TOKENS", 0) or None
        return compress_to_budget(summary, max_tokens=budget, default_top_n=effective_top_n)

    def _stop_raw_session(self, session_id: str, meta, line_counters: dict, json_mode: bool) -> str:
        """Finalise a raw-capture session: gzip raw.ndjson, write status, report.

        No summary.json is written for raw sessions — clustering is not applied.
        ``--get-details`` redirects to the raw file.
        """
        import gzip
        import shutil

        raw_path = self.store.raw_path(session_id)
        gz_path = self.store.raw_path(session_id, gzipped=True)
        raw_bytes = raw_path.stat().st_size if raw_path.exists() else 0
        no_gzip = bool(meta.args.get("no_gzip"))
        final_path = raw_path
        if not no_gzip and raw_path.exists() and raw_bytes > 0:
            with open(raw_path, "rb") as src, gzip.open(gz_path, "wb") as dst:
                shutil.copyfileobj(src, dst)
            raw_path.unlink()
            final_path = gz_path
            meta.extras["raw_gzipped"] = True
            meta.extras["raw_bytes_compressed"] = gz_path.stat().st_size

        meta.extras["raw_bytes"] = raw_bytes
        # Mark stopped without going through build_summary (no summary.json for raw).
        meta.status = "stopped"
        from datetime import datetime as _dt

        now = _dt.now()
        meta.stopped_at = now.isoformat()
        meta.stopped_at_ms = int(now.timestamp() * 1000)
        self.store._write_meta(meta)
        truncated = bool(meta.extras.get("truncated"))
        if json_mode:
            return json.dumps(
                {
                    "session_id": session_id,
                    "mode": "raw",
                    "raw_path": str(final_path),
                    "raw_bytes": raw_bytes,
                    "raw_bytes_compressed": meta.extras.get("raw_bytes_compressed"),
                    "truncated": truncated,
                    "total_lines": line_counters.get("total", 0),
                    "stream_restarts": line_counters.get("stream_restarts", 0),
                },
                indent=2,
            )
        size_mb = raw_bytes / (1024 * 1024)
        gz_mb = (meta.extras.get("raw_bytes_compressed") or 0) / (1024 * 1024)
        trunc_str = " [TRUNCATED at size cap]" if truncated else ""
        gz_str = f" → {gz_mb:.2f} MB gzipped" if gz_path.exists() else ""
        explore_cmd = "zcat" if gz_path.exists() else "cat"
        return (
            f"Session {session_id}: raw mode, {line_counters.get('total', 0)} lines, "
            f"{size_mb:.2f} MB{gz_str}{trunc_str}\n"
            f"Explore: {explore_cmd} {final_path} | jq ..."
        )

    def get_details(
        self,
        session_id: str,
        cluster: int | None = None,
        raw: bool = False,
        resample: bool = False,
        json_mode: bool = False,
        symbolicate: bool = False,
        app_binary: str | None = None,
        dsym: str | None = None,
    ) -> str:
        """Drill into a stored session. ``cluster`` is 1-indexed for human use."""
        try:
            meta = self.store.load_meta(session_id)
        except FileNotFoundError:
            return f"Unknown session: {session_id}"
        if meta.args.get("raw_capture"):
            # Raw sessions have no clusters — point at the file.
            gz_path = self.store.raw_path(session_id, gzipped=True)
            ndjson_path = self.store.raw_path(session_id)
            target = gz_path if gz_path.exists() else ndjson_path
            cmd = "zcat" if gz_path.exists() else "cat"
            return f"Raw session — explore with: {cmd} {target} | jq ..."
        summary = self.store.load_summary(session_id)
        if summary is None:
            return f"No summary for {session_id}. Run --stop first."
        if raw:
            return self._dump_raw_events(session_id)
        if cluster is not None:
            index = cluster - 1
            if index < 0 or index >= len(summary.clusters):
                return f"Cluster {cluster} out of range (1..{len(summary.clusters)})"
            target = summary.clusters[index]
            events = [
                e for e in self.store.read_events(session_id) if e.fingerprint == target.fingerprint
            ]
            if resample:
                fresh = _attempt_auto_sample(
                    meta.args.get("udid", ""), events[0].pid if events else 0
                )
                target.auto_samples = [fresh]
            if symbolicate:
                _apply_symbolication(target, app_binary, dsym)
            if json_mode:
                from common.hang_pipeline import cluster_to_json

                return json.dumps(cluster_to_json(target), indent=2)
            return format_cluster_detail(target, events)
        if json_mode:
            return json.dumps(summary_to_json(summary), indent=2)
        return format_l2(summary)

    def list_sessions(self, json_mode: bool = False) -> str:
        metas = self.store.list_sessions()
        if json_mode:
            return json.dumps([m.to_json() for m in metas], indent=2)
        if not metas:
            return "No sessions stored."
        lines = [f"Sessions: {len(metas)}"]
        for meta in metas[:20]:
            stopped = meta.stopped_at or "-"
            counters = meta.extras.get("line_counters", {})
            restarts = counters.get("stream_restarts", 0)
            duration_s = (
                (meta.stopped_at_ms - meta.started_at_ms) / 1000.0 if meta.stopped_at_ms else None
            )
            duration_str = f"  capture={duration_s:.1f}s" if duration_s is not None else ""
            restart_str = f"  restarts={restarts}" if restarts else ""
            raw_str = ""
            if meta.args.get("raw_capture"):
                size = meta.extras.get("raw_bytes_compressed") or meta.extras.get("raw_bytes") or 0
                trunc = "T" if meta.extras.get("truncated") else "-"
                raw_str = f"  raw={size / 1024 / 1024:.2f}MB(trunc:{trunc})"
            lines.append(
                f"  {meta.session_id}  {meta.status:8s}  started={meta.started_at}  "
                f"stopped={stopped}{duration_str}{restart_str}{raw_str}"
            )
        if len(metas) > 20:
            lines.append(f"  ... {len(metas) - 20} more")
        return "\n".join(lines)

    def clear_sessions(self, older_than: str | None = None, json_mode: bool = False) -> str:
        deleted = self.store.clear(older_than=older_than)
        if json_mode:
            return json.dumps({"deleted": deleted, "older_than": older_than})
        suffix = f" older than {older_than}" if older_than else ""
        return f"Cleared {deleted} session(s){suffix}."

    def diff(self, session_a: str, session_b: str, json_mode: bool = False) -> str:
        summary_a = self.store.load_summary(session_a)
        summary_b = self.store.load_summary(session_b)
        if summary_a is None or summary_b is None:
            missing = [s for s, x in [(session_a, summary_a), (session_b, summary_b)] if x is None]
            return f"Missing summary.json for: {', '.join(missing)}"
        result = diff_sessions(summary_a, summary_b)
        if json_mode:
            return json.dumps(result, indent=2)
        return format_diff(result)

    # === WORKER ===

    def run_worker(self, session_id: str) -> int:
        """Long-running worker entrypoint. Returns exit code.

        Layout: claim meta → resolve predicate → open events.jsonl line-buffered
        → for each restart attempt, spawn ``xcrun simctl spawn ... log stream``
        and read lines until EOF or subprocess death. SIGTERM flushes and exits
        cleanly. EOF / subprocess death triggers a bounded restart loop
        (``IOS_SIM_HANG_MAX_RESTARTS``); on exhaustion the session is marked
        ``crashed`` rather than left in stale ``running`` state.

        In ``--raw-capture`` mode the worker spawns ``log stream --style ndjson``
        and dumps raw lines to ``raw.ndjson`` instead of parsing into the
        clustering pipeline. Same restart/crash semantics; additional size-cap
        bail when the raw file exceeds ``max_size_mb``.
        """
        meta = self.store.claim_worker(session_id, pid=os.getpid())
        args = meta.args
        min_hang_ms = int(args.get("min_hang_ms", env_int("IOS_SIM_HANG_MIN_MS", 250)))
        bundle_id = args.get("bundle_id")
        predicate_override = args.get("predicate")
        auto_sample = bool(args.get("auto_sample", False))
        auto_spindump = bool(args.get("auto_spindump", False))
        udid = args["udid"]
        predicate = _resolve_predicate(predicate_override)
        max_restarts = env_int("IOS_SIM_HANG_MAX_RESTARTS", DEFAULT_MAX_STREAM_RESTARTS)
        raw_capture = bool(args.get("raw_capture", False))
        max_size_bytes = int(args.get("max_size_mb", 10)) * 1024 * 1024 if raw_capture else 0

        events_path = self.store.events_path(session_id)
        counters = {"total": 0, "matched": 0, "dropped": 0, "stream_restarts": 0}
        sampled_fingerprints: set[str] = set()
        spindumped_fingerprints: set[str] = set()
        stop_flag = {"value": False}
        cap_state = {"hit": False}  # set by raw reader when size cap exceeded

        def _on_sigterm(_signum, _frame):
            stop_flag["value"] = True

        signal.signal(signal.SIGTERM, _on_sigterm)
        signal.signal(signal.SIGINT, _on_sigterm)

        cmd = ["xcrun", "simctl", "spawn", udid, "log", "stream", "--predicate", predicate]
        if raw_capture:
            cmd.extend(["--style", "ndjson"])

        def _spawn_log_stream() -> subprocess.Popen:
            return subprocess.Popen(
                cmd,
                stdout=subprocess.PIPE,
                stderr=subprocess.DEVNULL,
                stdin=subprocess.DEVNULL,
                text=True,
                bufsize=1,
            )

        proc: subprocess.Popen | None = None
        crashed = False
        try:
            with contextlib.ExitStack() as stack:
                out_handle = stack.enter_context(open(events_path, "a", buffering=1))
                raw_handle = (
                    stack.enter_context(open(self.store.raw_path(session_id), "a", buffering=1))
                    if raw_capture
                    else None
                )
                for attempt in range(max_restarts + 1):
                    if stop_flag["value"]:
                        break
                    if attempt > 0:
                        counters["stream_restarts"] = attempt
                        out_handle.write(
                            json.dumps(
                                {
                                    "event": "stream_restart",
                                    "attempt": attempt,
                                    "at_ms": int(time.time() * 1000),
                                }
                            )
                            + "\n"
                        )
                        out_handle.flush()
                        time.sleep(RESTART_BACKOFF_SECONDS)
                        if stop_flag["value"]:
                            break
                    try:
                        proc = _spawn_log_stream()
                    except FileNotFoundError:
                        crashed = True
                        break

                    if raw_capture:
                        exit_code = self._read_stream_into_raw(
                            proc=proc,
                            raw_handle=raw_handle,
                            stop_flag=stop_flag,
                            counters=counters,
                            max_size_bytes=max_size_bytes,
                            session_id=session_id,
                            cap_state=cap_state,
                        )
                    else:
                        exit_code = self._read_stream_into_events(
                            proc=proc,
                            out_handle=out_handle,
                            stop_flag=stop_flag,
                            counters=counters,
                            bundle_id=bundle_id,
                            min_hang_ms=min_hang_ms,
                            auto_sample=auto_sample,
                            auto_spindump=auto_spindump,
                            sampled_fingerprints=sampled_fingerprints,
                            spindumped_fingerprints=spindumped_fingerprints,
                            session_id=session_id,
                            session_start_ms=meta.started_at_ms,
                            udid=udid,
                        )

                    if cap_state["hit"]:
                        # Size-cap is a clean stop, not a crash. Record marker.
                        out_handle.write(
                            json.dumps(
                                {
                                    "event": "size_cap_hit",
                                    "bytes": self.store.raw_path(session_id).stat().st_size,
                                    "at_ms": int(time.time() * 1000),
                                }
                            )
                            + "\n"
                        )
                        out_handle.flush()
                        self._mark_truncated(session_id)
                        break

                    if stop_flag["value"]:
                        # Clean SIGTERM. Don't restart, don't mark crashed.
                        out_handle.write(
                            json.dumps({"event": "stream_ended", "at_ms": int(time.time() * 1000)})
                            + "\n"
                        )
                        out_handle.flush()
                        break

                    # Subprocess died without a stop request. Record it.
                    out_handle.write(
                        json.dumps(
                            {
                                "event": "stream_died",
                                "exit_code": exit_code,
                                "attempt": attempt,
                                "at_ms": int(time.time() * 1000),
                            }
                        )
                        + "\n"
                    )
                    out_handle.flush()
                else:
                    # for/else: ran every restart without a clean break — exhausted.
                    crashed = True

                with contextlib.suppress(OSError):
                    os.fsync(out_handle.fileno())
        finally:
            # raw_handle / out_handle are closed by ExitStack on with-block exit.
            if proc is not None and proc.poll() is None:
                proc.terminate()
                try:
                    proc.wait(timeout=2)
                except subprocess.TimeoutExpired:
                    proc.kill()

            if crashed and not stop_flag["value"]:
                self.store.mark_crashed(session_id)
            # SessionStore.persist_worker_counters preserves terminal status
            # (stopped from parent's stop(), or crashed above) and avoids
            # clobbering it back to running.
            self.store.persist_worker_counters(session_id, counters)

        return 2 if crashed else 0

    def _read_stream_into_raw(
        self,
        *,
        proc: subprocess.Popen,
        raw_handle,
        stop_flag: dict,
        counters: dict,
        max_size_bytes: int,
        session_id: str,
        cap_state: dict,
    ) -> int | None:
        """Raw NDJSON capture: dump lines verbatim to raw.ndjson, no parsing.

        Sets ``cap_state['hit'] = True`` and returns when the file exceeds
        ``max_size_bytes``. The caller treats that as a clean stop (no
        restart, no crash) and writes a ``size_cap_hit`` marker.
        """
        raw_path = self.store.raw_path(session_id)
        bytes_written = raw_path.stat().st_size if raw_path.exists() else 0
        last_fsync = time.time()
        while not stop_flag["value"]:
            if proc.stdout is None:
                return proc.poll()
            ready, _, _ = select.select([proc.stdout], [], [], 0.25)
            if not ready:
                if time.time() - last_fsync > 1.0:
                    raw_handle.flush()
                    with contextlib.suppress(OSError):
                        os.fsync(raw_handle.fileno())
                    last_fsync = time.time()
                exit_code = proc.poll()
                if exit_code is not None:
                    return exit_code
                continue
            line = proc.stdout.readline()
            if not line:
                with contextlib.suppress(subprocess.TimeoutExpired):
                    proc.wait(timeout=0.5)
                return proc.poll()
            counters["total"] += 1
            # Drop non-JSON banners like `log stream`'s "Filtering the log data..." and
            # any pwuid warnings. Raw consumers expect strict NDJSON.
            stripped = line.lstrip()
            if not stripped.startswith("{"):
                continue
            raw_handle.write(line if line.endswith("\n") else line + "\n")
            bytes_written += len(line) + (0 if line.endswith("\n") else 1)
            if max_size_bytes > 0 and bytes_written >= max_size_bytes:
                cap_state["hit"] = True
                raw_handle.flush()
                with contextlib.suppress(OSError):
                    os.fsync(raw_handle.fileno())
                return proc.poll()
        return proc.poll()

    def _mark_truncated(self, session_id: str) -> None:
        """Best-effort: set extras.truncated=True. Called when size cap hit."""
        try:
            meta = self.store.load_meta(session_id)
        except FileNotFoundError:
            return
        meta.extras["truncated"] = True
        # Write meta directly via the public store path; intentional: SessionStore
        # exposes no extras setter and we want one round-trip not two.
        self.store._write_meta(meta)

    def _read_stream_into_events(
        self,
        *,
        proc: subprocess.Popen,
        out_handle,
        stop_flag: dict,
        counters: dict,
        bundle_id: str | None,
        min_hang_ms: int,
        auto_sample: bool,
        auto_spindump: bool,
        sampled_fingerprints: set[str],
        spindumped_fingerprints: set[str],
        session_id: str,
        session_start_ms: int,
        udid: str,
    ) -> int | None:
        """Read lines until EOF / subprocess death / stop request.

        Returns the subprocess exit code (None if still alive when stop_flag
        was set, otherwise the recorded poll() value at exit time). Does not
        emit ``stream_died`` / ``stream_ended`` events itself — the caller
        decides which marker to write based on stop_flag.
        """
        last_fsync = time.time()
        while not stop_flag["value"]:
            if proc.stdout is None:
                return proc.poll()
            ready, _, _ = select.select([proc.stdout], [], [], 0.25)
            if not ready:
                if time.time() - last_fsync > 1.0:
                    out_handle.flush()
                    with contextlib.suppress(OSError):
                        os.fsync(out_handle.fileno())
                    last_fsync = time.time()
                # If the subprocess silently died, poll() returns its code now.
                # Otherwise keep waiting — quiet log streams are normal.
                exit_code = proc.poll()
                if exit_code is not None:
                    return exit_code
                continue
            line = proc.stdout.readline()
            if not line:
                # EOF — subprocess closed stdout. Wait briefly for poll() to
                # settle so we report a meaningful exit code.
                with contextlib.suppress(subprocess.TimeoutExpired):
                    proc.wait(timeout=0.5)
                return proc.poll()
            counters["total"] += 1
            raw_event = _pipeline_parse_log_line(line.rstrip())
            if raw_event is None:
                continue
            if bundle_id and not matches_bundle(raw_event, bundle_id):
                continue
            counters["matched"] += 1
            duration = raw_event.get("duration_ms")
            if duration is None or duration < min_hang_ms:
                counters["dropped"] += 1
                continue
            normalised = build_normalised_event(
                raw_event,
                session_start_ms=session_start_ms,
                current_ms=int(time.time() * 1000),
            )
            if normalised is None:
                continue
            if auto_sample and normalised.fingerprint not in sampled_fingerprints:
                sampled_fingerprints.add(normalised.fingerprint)
                self._stash_auto_sample(
                    session_id, normalised, _attempt_auto_sample(udid, normalised.pid)
                )
            if auto_spindump and normalised.fingerprint not in spindumped_fingerprints:
                spindumped_fingerprints.add(normalised.fingerprint)
                self._stash_auto_sample(
                    session_id, normalised, _attempt_auto_spindump(udid, normalised.pid)
                )
            out_handle.write(event_to_jsonl(normalised) + "\n")
        return proc.poll()

    # === PRIVATE ===

    def _wait_for_worker_exit(self, session_id: str, timeout_seconds: float) -> None:
        meta = self.store.load_meta(session_id)
        if not meta.pid:
            return
        deadline = time.time() + timeout_seconds
        while time.time() < deadline:
            try:
                os.kill(meta.pid, 0)
            except ProcessLookupError:
                return
            time.sleep(0.05)

    def _dump_raw_events(self, session_id: str) -> str:
        path = self.store.events_path(session_id)
        if not path.exists():
            return ""
        with open(path) as handle:
            return handle.read()

    def _resolve_udid(self, udid: str | None) -> str:
        identifier = udid or "booted"
        try:
            return resolve_device_identifier(identifier)
        except RuntimeError as error:
            raise RuntimeError(str(error)) from error

    def _stash_auto_sample(self, session_id: str, normalised, sample: dict) -> None:
        """Record an auto-sample side-channel for later cluster annotation.

        Delegates to SessionStore's append-only JSONL writer — concurrent stashes
        from a busy worker no longer race against each other.
        """
        self.store.stash_auto_sample(session_id, normalised.fingerprint, sample)


SAMPLE_DURATION_SECONDS = 1
SAMPLE_TIMEOUT_SECONDS = 5
SPINDUMP_DURATION_SECONDS = 1
SPINDUMP_TIMEOUT_SECONDS = 10
ATOS_TIMEOUT_SECONDS = 10


def _attempt_auto_sample(udid: str, pid: int) -> dict:
    """Capture a main-thread stack via ``xcrun simctl spawn <udid> sample``.

    Shells out to the in-simulator ``sample`` binary, which writes a textual
    main-thread profile to stdout. Short duration keeps the worker hot path
    responsive; fingerprint dedup at the caller means we sample at most once
    per unique hang pattern per session.
    """
    if not udid:
        return {
            "kind": "simctl-sample",
            "stack": None,
            "captured_at_ms": int(time.time() * 1000),
            "symbolicated": False,
            "reason": "no udid available",
        }
    if not pid:
        return {
            "kind": "simctl-sample",
            "stack": None,
            "captured_at_ms": int(time.time() * 1000),
            "symbolicated": False,
            "reason": "no pid available",
        }
    cmd = [
        "xcrun",
        "simctl",
        "spawn",
        udid,
        "sample",
        str(pid),
        str(SAMPLE_DURATION_SECONDS),
        "-mayDie",
        "-file",
        "-",
    ]
    captured_at_ms = int(time.time() * 1000)
    try:
        result = subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            timeout=SAMPLE_TIMEOUT_SECONDS,
            check=False,
        )
    except subprocess.TimeoutExpired:
        return {
            "kind": "simctl-sample",
            "stack": None,
            "captured_at_ms": captured_at_ms,
            "symbolicated": False,
            "reason": "timeout",
        }
    except FileNotFoundError:
        return {
            "kind": "simctl-sample",
            "stack": None,
            "captured_at_ms": captured_at_ms,
            "symbolicated": False,
            "reason": "xcrun not found",
        }
    if result.returncode != 0 or not result.stdout.strip():
        return {
            "kind": "simctl-sample",
            "stack": None,
            "captured_at_ms": captured_at_ms,
            "symbolicated": False,
            "reason": (result.stderr.strip() or f"sample exited {result.returncode}")[:200],
        }
    return {
        "kind": "simctl-sample",
        "stack": result.stdout,
        "captured_at_ms": captured_at_ms,
        "symbolicated": False,
        "reason": None,
    }


def _attempt_auto_spindump(udid: str, pid: int) -> dict:
    """Capture a hang report via ``xcrun simctl spawn <udid> spindump``.

    ``spindump`` is Apple's own hang-report tool — it produces a structured
    text report explicitly designed for the "what was main thread doing"
    question. Heavier than ``sample`` so we run a slightly longer timeout.
    """
    captured_at_ms = int(time.time() * 1000)
    if not udid:
        return {
            "kind": "spindump",
            "stack": None,
            "captured_at_ms": captured_at_ms,
            "symbolicated": False,
            "reason": "no udid available",
        }
    if not pid:
        return {
            "kind": "spindump",
            "stack": None,
            "captured_at_ms": captured_at_ms,
            "symbolicated": False,
            "reason": "no pid available",
        }
    cmd = [
        "xcrun",
        "simctl",
        "spawn",
        udid,
        "spindump",
        str(pid),
        str(SPINDUMP_DURATION_SECONDS),
        "-file",
        "-",
    ]
    try:
        result = subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            timeout=SPINDUMP_TIMEOUT_SECONDS,
            check=False,
        )
    except subprocess.TimeoutExpired:
        return {
            "kind": "spindump",
            "stack": None,
            "captured_at_ms": captured_at_ms,
            "symbolicated": False,
            "reason": "timeout",
        }
    except FileNotFoundError:
        return {
            "kind": "spindump",
            "stack": None,
            "captured_at_ms": captured_at_ms,
            "symbolicated": False,
            "reason": "xcrun not found",
        }
    if result.returncode != 0 or not result.stdout.strip():
        return {
            "kind": "spindump",
            "stack": None,
            "captured_at_ms": captured_at_ms,
            "symbolicated": False,
            "reason": (result.stderr.strip() or f"spindump exited {result.returncode}")[:200],
        }
    return {
        "kind": "spindump",
        "stack": result.stdout,
        "captured_at_ms": captured_at_ms,
        "symbolicated": False,
        "reason": None,
    }


def _apply_symbolication(cluster, app_binary: str | None, dsym: str | None) -> None:
    """In-place: rewrite each auto-sample's stack via atos using the chosen target.

    No-ops if no target path is resolvable or atos returns nothing — failures
    must never strip the existing (unsymbolicated) stack, only enhance it.
    """
    target = _resolve_symbolication_target(app_binary, dsym)
    if not target:
        return
    samples = cluster.auto_samples or ([cluster.auto_sample] if cluster.auto_sample else [])
    for sample in samples:
        if not sample or not sample.get("stack"):
            continue
        original = sample["stack"]
        rewritten = symbolicate_stack(original, lambda addrs: _run_atos(target, addrs))
        if rewritten != original:
            sample["stack"] = rewritten
            sample["symbolicated"] = True


def _run_atos(binary_path: str, addresses: list[str]) -> dict[str, str]:
    """Resolve a batch of runtime addresses via ``xcrun atos -o <path>``.

    Returns ``{addr: resolved_text}`` for every input address; addresses atos
    couldn't resolve come back as themselves (atos echoes the input). Failures
    return an empty dict so callers can fall through cleanly.
    """
    if not binary_path or not addresses:
        return {}
    cmd = ["xcrun", "atos", "-o", binary_path, *addresses]
    try:
        result = subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            timeout=ATOS_TIMEOUT_SECONDS,
            check=False,
        )
    except (subprocess.TimeoutExpired, FileNotFoundError):
        return {}
    if result.returncode != 0:
        return {}
    lines = [line for line in result.stdout.splitlines() if line.strip()]
    # atos prints one resolved line per input address, in input order.
    return dict(zip(addresses, lines, strict=False))


def _resolve_symbolication_target(app_binary: str | None, dsym: str | None) -> str | None:
    """Pick the path atos should resolve against. dSYM wins when both set."""
    explicit = dsym or app_binary
    if explicit:
        return explicit
    env_dsym = os.environ.get("IOS_SIM_HANG_DSYM", "").strip()
    if env_dsym:
        return env_dsym
    env_binary = os.environ.get("IOS_SIM_HANG_APP_BINARY", "").strip()
    return env_binary or None


# === CLI ===


def _add_legacy_args(parser: argparse.ArgumentParser) -> argparse._MutuallyExclusiveGroup:
    """Add the v1 --watch / --since flags plus the new HangBuster subcommands.

    All modes share the same parser so users can keep using v1 invocations
    unchanged. Subcommands are mutually exclusive (mode_group).
    """
    mode_group = parser.add_mutually_exclusive_group(required=True)
    mode_group.add_argument(
        "--watch", action="store_true", help="Legacy live stream (until --duration / Ctrl-C)"
    )
    mode_group.add_argument(
        "--since",
        metavar="DURATION",
        help="Legacy historical query (e.g. 5m, 1h, 30s)",
    )
    mode_group.add_argument(
        "--start",
        action="store_true",
        help="Start a HangBuster session (detached worker, returns session ID)",
    )
    mode_group.add_argument(
        "--stop", metavar="SESSION_ID", help="Stop a session and emit the summary"
    )
    mode_group.add_argument(
        "--get-details",
        metavar="SESSION_ID",
        help="Drill into a stored session (combine with --cluster N or --raw)",
    )
    mode_group.add_argument(
        "--list-sessions", action="store_true", help="List stored HangBuster sessions"
    )
    mode_group.add_argument("--clear-sessions", action="store_true", help="Delete stored sessions")
    mode_group.add_argument(
        "--diff", nargs=2, metavar=("SESSION_A", "SESSION_B"), help="Compare two sessions"
    )
    # Internal worker entry — hidden from --help. Detached child re-enters this script with it.
    mode_group.add_argument("--worker-session-id", metavar="ID", help=argparse.SUPPRESS)
    return mode_group


def main():
    """Main entry point — supports v1 + HangBuster modes from one parser."""
    parser = argparse.ArgumentParser(
        description=(
            "Watch for iOS simulator hang events via os_log. "
            "Use --watch/--since for the v1 stream, or --start/--stop for HangBuster session mode."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  # HangBuster session mode (agent-friendly):
  SID=$(python scripts/hang_watcher.py --start --min-hang-ms 200)
  # ... interact with the simulator ...
  python scripts/hang_watcher.py --stop $SID
  python scripts/hang_watcher.py --get-details $SID --cluster 1
  python scripts/hang_watcher.py --list-sessions
  python scripts/hang_watcher.py --diff $SID_A $SID_B
  python scripts/hang_watcher.py --clear-sessions --older-than 24h

  # Legacy:
  python scripts/hang_watcher.py --watch --duration 60
  python scripts/hang_watcher.py --since 5m --json

Environment variables:
  IOS_SIM_HANG_PREDICATE         Override the default log predicate
  IOS_SIM_HANG_MIN_MS            Min event duration kept (default 250)
  IOS_SIM_HANG_SESSION_TTL_HOURS Session prune age (default 24)
  IOS_SIM_HANG_DEFAULT_TOP_N     Default top-N for --stop (default 3)
  IOS_SIM_HANG_BUDGET_TOKENS     Default token budget for --stop
        """,
    )
    _add_legacy_args(parser)

    # Filters / target
    parser.add_argument(
        "--bundle-id",
        help=(
            "Post-parse filter: drop events whose process name does not contain the "
            "app suffix from this bundle ID. Hang capture itself stays simulator-global "
            "(RunningBoard/SpringBoard events are kept)."
        ),
    )
    parser.add_argument("--predicate", help="Override the default os_log predicate")
    parser.add_argument("--udid", help="Device UDID (uses booted simulator if omitted)")

    # Legacy-only
    parser.add_argument(
        "--duration", type=int, metavar="SECONDS", help="Stop after N seconds (--watch only)"
    )

    # HangBuster knobs
    parser.add_argument(
        "--min-hang-ms",
        type=int,
        help="Drop events below this duration (default 250 / env IOS_SIM_HANG_MIN_MS)",
    )
    parser.add_argument(
        "--auto-sample",
        action="store_true",
        help="On hang, capture a main-thread stack via `xcrun simctl spawn <udid> sample`",
    )
    parser.add_argument(
        "--auto-spindump",
        action="store_true",
        help="On hang, capture a spindump report via `xcrun simctl spawn <udid> spindump`",
    )
    parser.add_argument("--top", type=int, dest="top_n", help="Top-N clusters to retain in summary")
    parser.add_argument(
        "--all", action="store_true", dest="all_clusters", help="Keep all clusters (no top-N cap)"
    )
    parser.add_argument(
        "--budget-tokens", type=int, help="Max tokens for --stop output (picks L0/L1/L2)"
    )
    parser.add_argument(
        "--cluster", type=int, help="Cluster index (1-based) for --get-details drill"
    )
    parser.add_argument(
        "--resample", action="store_true", help="With --get-details: force a fresh auto-sample"
    )
    parser.add_argument("--raw", action="store_true", help="With --get-details: dump events.jsonl")
    parser.add_argument(
        "--symbolicate",
        action="store_true",
        help="With --get-details: resolve [0x...] frames via `xcrun atos`",
    )
    parser.add_argument(
        "--app-binary",
        help="Path to unstripped app binary for --symbolicate (env: IOS_SIM_HANG_APP_BINARY)",
    )
    parser.add_argument(
        "--dsym",
        help="Path to .dSYM for --symbolicate (preferred over --app-binary; env: IOS_SIM_HANG_DSYM)",
    )
    parser.add_argument(
        "--older-than", help="With --clear-sessions: delete sessions older than e.g. 24h"
    )
    parser.add_argument("--terse", action="store_true", help="--stop: force L0 one-line output")

    # Raw capture (HangBuster)
    parser.add_argument(
        "--raw-capture",
        action="store_true",
        help=(
            "With --start: capture raw os_log NDJSON to raw.ndjson instead of bucketed events. "
            "Explore afterwards with: zcat <session>/raw.ndjson.gz | jq ..."
        ),
    )
    parser.add_argument(
        "--max-size-mb",
        type=int,
        default=10,
        help="Raw-capture per-session size cap in MB (default 10). Worker stops at cap.",
    )
    parser.add_argument(
        "--no-gzip",
        action="store_true",
        help="Skip gzip of raw.ndjson on --stop (raw-capture mode only).",
    )

    # Output
    parser.add_argument("--json", action="store_true", help="Emit JSON output")
    parser.add_argument("--verbose", action="store_true", help="Include raw lines (legacy modes)")

    args = parser.parse_args()

    # === HangBuster worker entry ===
    if args.worker_session_id:
        buster = HangBuster()
        sys.exit(buster.run_worker(args.worker_session_id))

    # === HangBuster session subcommands ===
    if args.start:
        buster = HangBuster()
        start_args = {
            "min_hang_ms": (
                args.min_hang_ms
                if args.min_hang_ms is not None
                else env_int("IOS_SIM_HANG_MIN_MS", 250)
            ),
            "bundle_id": args.bundle_id,
            "predicate": args.predicate,
            "auto_sample": args.auto_sample,
            "auto_spindump": args.auto_spindump,
            "raw_capture": args.raw_capture,
            "max_size_mb": args.max_size_mb,
            "no_gzip": args.no_gzip,
        }
        try:
            session_id = buster.start(start_args, udid=args.udid)
        except RuntimeError as error:
            print(f"Error: {error}", file=sys.stderr)
            sys.exit(1)
        print(session_id)
        sys.exit(0)

    if args.stop:
        buster = HangBuster()
        top_n = None if args.all_clusters else args.top_n
        out = buster.stop(
            args.stop,
            budget_tokens=args.budget_tokens,
            top_n=top_n,
            terse=args.terse,
            json_mode=args.json,
        )
        print(out)
        sys.exit(0)

    if args.get_details:
        buster = HangBuster()
        out = buster.get_details(
            args.get_details,
            cluster=args.cluster,
            raw=args.raw,
            resample=args.resample,
            json_mode=args.json,
            symbolicate=args.symbolicate,
            app_binary=args.app_binary,
            dsym=args.dsym,
        )
        print(out)
        sys.exit(0)

    if args.list_sessions:
        buster = HangBuster()
        print(buster.list_sessions(json_mode=args.json))
        sys.exit(0)

    if args.clear_sessions:
        buster = HangBuster()
        print(buster.clear_sessions(older_than=args.older_than, json_mode=args.json))
        sys.exit(0)

    if args.diff:
        buster = HangBuster()
        print(buster.diff(args.diff[0], args.diff[1], json_mode=args.json))
        sys.exit(0)

    # === Legacy modes ===
    if args.since:
        try:
            _compute_start_timestamp(args.since)
        except ValueError as error:
            parser.error(str(error))

    watcher = HangWatcher(udid=args.udid)
    if args.watch:
        success = watcher.watch(
            duration_seconds=args.duration,
            bundle_id=args.bundle_id,
            predicate=args.predicate,
            verbose=args.verbose,
            json_mode=args.json,
        )
    else:
        success = watcher.show_since(
            since_duration=args.since,
            bundle_id=args.bundle_id,
            predicate=args.predicate,
            verbose=args.verbose,
            json_mode=args.json,
        )
    if not success:
        sys.exit(1)
    if not args.json and not args.watch:
        print(f"\n{watcher.get_summary()}")
    if watcher.hang_events:
        cache_id = watcher.save_to_cache()
        print(f"Archive saved: {cache_id}", file=sys.stderr)
    sys.exit(0)


if __name__ == "__main__":
    main()
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall