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/common/hang_sessions.py

View on GitHub
#!/usr/bin/env python3
"""HangBuster session storage — own dir layout, no ProgressiveCache reuse.

Each session is a directory under ``~/.ios-simulator-skill/sessions/<id>/``
containing ``meta.json`` (config + pid + status), ``events.jsonl``
(append-only normalised events), and ``summary.json`` (post-stop).

The parent creates the directory and writes initial meta. The detached
worker updates meta with its own pid (avoids pidfile race) and appends to
events.jsonl. ``--stop`` SIGTERMs the worker, drains events, builds a
``SessionSummary``, and writes ``summary.json``.
"""

from __future__ import annotations

import contextlib
import json
import os
import re
import secrets
import signal
import time
from dataclasses import dataclass, field
from datetime import datetime, timedelta
from pathlib import Path

from common.env_config import env_int
from common.hang_pipeline import (
    SessionSummary,
    SummaryBuilder,
    event_from_jsonl,
    summary_from_json,
    summary_to_json,
)

# === CONSTANTS ===

DEFAULT_SESSIONS_DIR = Path("~/.ios-simulator-skill/sessions").expanduser()
DEFAULT_TTL_HOURS = env_int("IOS_SIM_HANG_SESSION_TTL_HOURS", 24)

_STATUS_PENDING = "pending"
_STATUS_RUNNING = "running"
_STATUS_STOPPED = "stopped"
_STATUS_CRASHED = "crashed"

_DURATION_RE = re.compile(r"(\d+)([smhd])$")


# === TYPES ===


@dataclass
class SessionMeta:
    """Parent + worker writes to meta.json."""

    session_id: str
    started_at: str
    started_at_ms: int
    args: dict
    pid: int | None = None
    status: str = _STATUS_PENDING
    stopped_at: str | None = None
    stopped_at_ms: int | None = None
    extras: dict = field(default_factory=dict)

    def to_json(self) -> dict:
        return {
            "session_id": self.session_id,
            "started_at": self.started_at,
            "started_at_ms": self.started_at_ms,
            "args": self.args,
            "pid": self.pid,
            "status": self.status,
            "stopped_at": self.stopped_at,
            "stopped_at_ms": self.stopped_at_ms,
            "extras": self.extras,
        }

    @classmethod
    def from_json(cls, payload: dict) -> SessionMeta:
        return cls(
            session_id=payload["session_id"],
            started_at=payload["started_at"],
            started_at_ms=payload["started_at_ms"],
            args=payload.get("args", {}),
            pid=payload.get("pid"),
            status=payload.get("status", _STATUS_PENDING),
            stopped_at=payload.get("stopped_at"),
            stopped_at_ms=payload.get("stopped_at_ms"),
            extras=payload.get("extras", {}),
        )


# === SESSION STORE ===


class SessionStore:
    """Filesystem-backed session repository."""

    def __init__(self, base_dir: Path | None = None):
        self.base_dir = Path(base_dir).expanduser() if base_dir else DEFAULT_SESSIONS_DIR
        self.base_dir.mkdir(parents=True, exist_ok=True)

    # === PUBLIC API ===

    def create(self, args: dict) -> SessionMeta:
        """Generate id + dir + initial meta.json. Caller detaches the worker next."""
        session_id = _generate_session_id()
        session_dir = self.base_dir / session_id
        session_dir.mkdir(parents=True, exist_ok=False)
        # Empty events file so the worker can `open(..., 'a')` cleanly.
        (session_dir / "events.jsonl").touch()
        now = datetime.now()
        meta = SessionMeta(
            session_id=session_id,
            started_at=now.isoformat(),
            started_at_ms=int(now.timestamp() * 1000),
            args=args,
            status=_STATUS_PENDING,
        )
        self._write_meta(meta)
        return meta

    def wait_for_worker(self, session_id: str, timeout_seconds: float = 2.0) -> SessionMeta:
        """Poll meta.json until status=running or timeout. Raises on timeout."""
        deadline = time.time() + timeout_seconds
        while time.time() < deadline:
            meta = self.load_meta(session_id)
            if meta.status == _STATUS_RUNNING and meta.pid:
                return meta
            time.sleep(0.05)
        raise TimeoutError(f"Worker for {session_id} did not register within {timeout_seconds}s")

    def claim_worker(self, session_id: str, pid: int) -> SessionMeta:
        """Called by worker on startup. Writes pid + status=running into meta."""
        meta = self.load_meta(session_id)
        meta.pid = pid
        meta.status = _STATUS_RUNNING
        self._write_meta(meta)
        return meta

    def persist_worker_counters(self, session_id: str, counters: dict) -> None:
        """Worker calls this at shutdown to flush its line counters into meta.

        Re-reads meta from disk so a concurrent terminal status — ``stopped``
        from the parent's ``stop()`` or ``crashed`` from this worker's own
        ``mark_crashed`` — is not clobbered back to ``running``.
        """
        meta = self.load_meta(session_id)
        meta.extras["line_counters"] = counters
        if meta.status not in (_STATUS_STOPPED, _STATUS_CRASHED):
            meta.status = _STATUS_RUNNING
        self._write_meta(meta)

    def stop(self, session_id: str, summary: SessionSummary) -> SessionMeta:
        """Mark session stopped and persist the computed summary."""
        meta = self.load_meta(session_id)
        meta.status = _STATUS_STOPPED
        now = datetime.now()
        meta.stopped_at = now.isoformat()
        meta.stopped_at_ms = int(now.timestamp() * 1000)
        self._write_meta(meta)
        self._write_summary(session_id, summary)
        return meta

    def mark_crashed(self, session_id: str) -> None:
        """Best-effort: tag a session whose worker exited without a summary.

        Records ``stopped_at`` / ``stopped_at_ms`` so capture-duration math in
        ``build_summary`` and ``--list-sessions`` reflects when the worker
        actually died, not when the session was finally inspected.
        """
        try:
            meta = self.load_meta(session_id)
        except FileNotFoundError:
            return
        meta.status = _STATUS_CRASHED
        now = datetime.now()
        meta.stopped_at = now.isoformat()
        meta.stopped_at_ms = int(now.timestamp() * 1000)
        self._write_meta(meta)

    def signal_worker(self, session_id: str, sig: int = signal.SIGTERM) -> bool:
        """Send ``sig`` to the worker pid recorded in meta.json. Returns True if delivered."""
        meta = self.load_meta(session_id)
        if not meta.pid:
            return False
        try:
            os.kill(meta.pid, sig)
            return True
        except ProcessLookupError:
            return False
        except PermissionError:
            return False

    def load_meta(self, session_id: str) -> SessionMeta:
        path = self._meta_path(session_id)
        if not path.exists():
            raise FileNotFoundError(f"No meta.json for session {session_id}")
        with open(path) as handle:
            return SessionMeta.from_json(json.load(handle))

    def load_summary(self, session_id: str) -> SessionSummary | None:
        path = self._summary_path(session_id)
        if not path.exists():
            return None
        with open(path) as handle:
            return summary_from_json(json.load(handle))

    def stash_auto_sample(self, session_id: str, fingerprint: str, sample: dict) -> None:
        """Append an auto-sample record to ``<session>/auto_samples.jsonl``.

        Append-only JSONL avoids the read-modify-write race that an aggregate
        JSON dict would have under concurrent worker stashes. Readers reduce
        last-write-wins per fingerprint.
        """
        path = self._auto_samples_path(session_id)
        line = json.dumps({"fingerprint": fingerprint, "sample": sample}, separators=(",", ":"))
        with open(path, "a") as handle:
            handle.write(line + "\n")
            handle.flush()
            os.fsync(handle.fileno())

    def read_auto_samples(self, session_id: str) -> dict[str, list[dict]]:
        """Return ``{fingerprint: [sample, ...]}`` preserving write order.

        Multiple capture mechanisms (e.g. ``--auto-sample`` + ``--auto-spindump``)
        can stash distinct records under one fingerprint; callers disambiguate
        via the ``kind`` field on each sample payload.
        """
        path = self._auto_samples_path(session_id)
        if not path.exists():
            return {}
        samples: dict[str, list[dict]] = {}
        with open(path) as handle:
            for raw in handle:
                line = raw.strip()
                if not line:
                    continue
                try:
                    payload = json.loads(line)
                except json.JSONDecodeError:
                    continue
                fingerprint = payload.get("fingerprint")
                if fingerprint is None:
                    continue
                samples.setdefault(fingerprint, []).append(payload.get("sample"))
        return samples

    def read_events(self, session_id: str) -> list:
        """Read all events.jsonl lines, returning NormalisedEvent instances.

        Skips non-event sentinel lines (e.g. ``{"event": "stream_ended"}``).
        """
        path = self._events_path(session_id)
        if not path.exists():
            return []
        events = []
        with open(path) as handle:
            for raw in handle:
                line = raw.strip()
                if not line:
                    continue
                try:
                    payload = json.loads(line)
                except json.JSONDecodeError:
                    continue
                # Skip non-event sentinel lines (e.g. {"event": "stream_ended"}).
                if payload.get("event") == "stream_ended":
                    continue
                try:
                    events.append(event_from_jsonl(line))
                except (json.JSONDecodeError, KeyError):
                    continue
        return events

    def events_path(self, session_id: str) -> Path:
        """Worker writes here. Public so the worker can open it line-buffered."""
        return self._events_path(session_id)

    def raw_path(self, session_id: str, gzipped: bool = False) -> Path:
        """Raw-capture NDJSON path. ``gzipped=True`` returns the post-stop path."""
        name = "raw.ndjson.gz" if gzipped else "raw.ndjson"
        return self.base_dir / session_id / name

    def session_dir(self, session_id: str) -> Path:
        return self.base_dir / session_id

    def session_total_bytes(self, session_id: str) -> int:
        """Sum of all files under a session dir. Used by aggregate-cap pruning."""
        total = 0
        session_path = self.session_dir(session_id)
        if not session_path.exists():
            return 0
        for path in session_path.rglob("*"):
            if path.is_file():
                with contextlib.suppress(OSError):
                    total += path.stat().st_size
        return total

    def prune_to_aggregate_cap(self, max_bytes: int) -> int:
        """Drop oldest sessions until total bytes ≤ max_bytes. Returns deletions.

        Pairs with ``prune_expired``: TTL handles age, this handles disk usage
        when activity outpaces TTL. Both are called automatically on every
        ``create`` so the user never has to clean up manually.
        """
        if max_bytes <= 0:
            return 0
        # Oldest first — deletion order.
        entries: list[tuple[int, str, int]] = []  # (started_at_ms, session_id, bytes)
        total = 0
        for entry in self.base_dir.iterdir():
            if not entry.is_dir():
                continue
            try:
                meta = self.load_meta(entry.name)
            except (FileNotFoundError, json.JSONDecodeError):
                continue
            size = self.session_total_bytes(entry.name)
            total += size
            entries.append((meta.started_at_ms, entry.name, size))
        if total <= max_bytes:
            return 0
        entries.sort(key=lambda e: e[0])  # oldest first
        deleted = 0
        for _, session_id, size in entries:
            if total <= max_bytes:
                break
            _remove_tree(self.session_dir(session_id))
            total -= size
            deleted += 1
        return deleted

    def list_sessions(self) -> list[SessionMeta]:
        """All non-expired session metas, newest first."""
        metas: list[SessionMeta] = []
        for entry in self.base_dir.iterdir():
            if not entry.is_dir():
                continue
            try:
                metas.append(self.load_meta(entry.name))
            except (FileNotFoundError, json.JSONDecodeError):
                continue
        metas.sort(key=lambda m: m.started_at_ms, reverse=True)
        return metas

    def clear(self, older_than: str | None = None) -> int:
        """Delete session dirs. ``older_than`` is a duration string like ``24h``."""
        cutoff_ms = _resolve_cutoff_ms(older_than) if older_than else None
        deleted = 0
        for entry in self.base_dir.iterdir():
            if not entry.is_dir():
                continue
            try:
                meta = self.load_meta(entry.name)
            except (FileNotFoundError, json.JSONDecodeError):
                _remove_tree(entry)
                deleted += 1
                continue
            if cutoff_ms is None or meta.started_at_ms <= cutoff_ms:
                _remove_tree(entry)
                deleted += 1
        return deleted

    def prune_expired(self, ttl_hours: int | None = None) -> int:
        """Remove sessions older than ttl. Called on every ``create``."""
        ttl = ttl_hours if ttl_hours is not None else DEFAULT_TTL_HOURS
        cutoff = int((datetime.now() - timedelta(hours=ttl)).timestamp() * 1000)
        return self._clear_older_than_ms(cutoff)

    # === SUMMARY HELPERS ===

    def build_summary(
        self,
        session_id: str,
        matched_lines: int = 0,
        total_lines: int = 0,
        dropped_below_threshold: int = 0,
        extras: dict | None = None,
        top_n: int | None = None,
    ) -> SessionSummary:
        """Convenience: read events.jsonl and run the pipeline through SummaryBuilder.

        Duration prefers ``meta.stopped_at_ms`` (set on both ``stop()`` and
        ``mark_crashed()``) so summaries for crashed/stopped sessions reflect
        the actual capture window, not the time of inspection. Live sessions
        without ``stopped_at_ms`` fall back to ``now`` as before.
        """
        meta = self.load_meta(session_id)
        events = self.read_events(session_id)
        end_ms = meta.stopped_at_ms or int(datetime.now().timestamp() * 1000)
        duration_ms = end_ms - meta.started_at_ms
        builder = SummaryBuilder(
            session_id=session_id,
            started_at=meta.started_at,
            duration_ms=max(0, duration_ms),
            matched_lines=matched_lines,
            total_lines=total_lines,
            dropped_below_threshold=dropped_below_threshold,
            extras=extras or {},
        )
        return builder.build(
            events,
            top_n=top_n,
            auto_samples_by_fp=self.read_auto_samples(session_id),
        )

    # === PRIVATE ===

    def _meta_path(self, session_id: str) -> Path:
        return self.base_dir / session_id / "meta.json"

    def _events_path(self, session_id: str) -> Path:
        return self.base_dir / session_id / "events.jsonl"

    def _summary_path(self, session_id: str) -> Path:
        return self.base_dir / session_id / "summary.json"

    def _auto_samples_path(self, session_id: str) -> Path:
        return self.base_dir / session_id / "auto_samples.jsonl"

    def _write_meta(self, meta: SessionMeta) -> None:
        path = self._meta_path(meta.session_id)
        tmp = path.with_suffix(".json.tmp")
        # Atomic write — concurrent reads (e.g. the parent polling) never see a half-file.
        # fsync before replace makes the new contents durable, not just atomically renamed.
        with open(tmp, "w") as handle:
            json.dump(meta.to_json(), handle, indent=2)
            handle.flush()
            os.fsync(handle.fileno())
        tmp.replace(path)

    def _write_summary(self, session_id: str, summary: SessionSummary) -> None:
        path = self._summary_path(session_id)
        tmp = path.with_suffix(".json.tmp")
        with open(tmp, "w") as handle:
            json.dump(summary_to_json(summary), handle, indent=2)
            handle.flush()
            os.fsync(handle.fileno())
        tmp.replace(path)

    def _clear_older_than_ms(self, cutoff_ms: int) -> int:
        deleted = 0
        for entry in self.base_dir.iterdir():
            if not entry.is_dir():
                continue
            try:
                meta = self.load_meta(entry.name)
            except (FileNotFoundError, json.JSONDecodeError):
                _remove_tree(entry)
                deleted += 1
                continue
            if meta.started_at_ms <= cutoff_ms:
                _remove_tree(entry)
                deleted += 1
        return deleted


# === MODULE-LEVEL HELPERS ===


def _generate_session_id() -> str:
    """``hang-YYYYMMDD-HHmmss-XXXX`` — random hex suffix avoids same-second collisions."""
    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
    suffix = secrets.token_hex(2)
    return f"hang-{timestamp}-{suffix}"


def _resolve_cutoff_ms(duration_str: str) -> int:
    """Parse e.g. ``24h``, ``30m`` and return the epoch-ms threshold."""
    match = _DURATION_RE.match(duration_str.strip().lower())
    if not match:
        raise ValueError(f"Invalid duration: {duration_str!r}. Use 30s/5m/24h/7d.")
    value, unit = int(match.group(1)), match.group(2)
    seconds = value * {"s": 1, "m": 60, "h": 3600, "d": 86400}[unit]
    cutoff = datetime.now() - timedelta(seconds=seconds)
    return int(cutoff.timestamp() * 1000)


def _remove_tree(path: Path) -> None:
    """rm -rf path. Used for session-dir cleanup."""
    for child in path.iterdir():
        if child.is_dir():
            _remove_tree(child)
        else:
            with contextlib.suppress(FileNotFoundError):
                child.unlink()
    with contextlib.suppress(OSError):
        path.rmdir()
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