media/04-macos-adapter

[SunkenInTime]

Stack: 04/05

What becomes usable

• The macOS provider supervises the vendored BSD-3-Clause ungive/mediaremote-adapter v0.7.6 route through Apple-signed /usr/bin/perl, isolated behind the existing PID-authenticated per-widget UDS.
• Metadata is incrementally newline-framed and mapped to media frame v2, including blank-title sessions, conservative playback status, source, artwork, timestamps, and validated playback-rate-aware 1 Hz position advancement.
• Artwork follows the shared decode, downsample, PNG re-encode, and atomic cache-publication contract. Malformed adapter artwork is adapter loss.
• Short-lived transport helpers use the frozen outcome taxonomy. Seek repeatedly reads back until success or the 2 s deadline, with rate-aware ?2000 ms tolerance.
• A silent helper is killed at the ADR-defined 10 s first-frame deadline; EOF/crash/loss emits one canonical empty frame, marks unavailable, and restarts with bounded backoff. Backoff resets only after 30 s stable streaming.
• Command work and bounded TERM-to-KILL teardown cannot stall the supervision loop; stopped workers take ownership and self-release.
• macOS below 15.4 never spawns the helper. ADR 0017 records the runtime gate and Developer-ID/notarization posture.

Deliberately missing / unverified

The route spike passed, but the remediated Weaver implementation remains UNVERIFIED (needs attended Mac) for:

• real metadata, playback-rate-aware non-1? advancement, and 300?300+ artwork;
• malformed-art loss/recovery;
• all five verbs, delayed seek convergence, non-1? seek tolerance, and no-session false;
• helper/framework/spawn/timeout/signal rejection;
• silent first-frame watchdog and fatal shared-channel restart with resumed frames/transport;
• residual EOF, crash, player quit/relaunch, backoff, and TERM-to-KILL behavior;
• Developer-ID signing, secure timestamp, notarization, quarantine, and Gatekeeper;
• exact runtime behavior on macOS 15.4.

Hosted CI proves compilation and synthetic lifecycle/test behavior, not real MediaRemote player behavior.

Verification

Final implementation head 9c31229:

• npm test ? PASS, 63/63
• npm run typecheck ? PASS
• runtime: zig build test -Dweb-layer=exclude -Dtrace=off ? PASS
• Windows host: zig build test ? PASS
• weaver check examples/now-playing ? PASS
• direct aarch64-macos no-emit provider/host compiles ? PASS
• GitHub Actions run 30193380839 ? PASS: gate, Intel headless, Apple-silicon headless, and hosted Apple-silicon session

Tests cover the 10 s first-frame boundary; residual framing; blank/unknown session mapping; malformed and normalized artwork; failure taxonomy; 30 s backoff stability; the 15.4 predicate; invalid and non-1? rates; delayed seek convergence, no session, callback timeout, and out-of-tolerance expiry; synchronous command-drain avoidance; and bounded nonjoining slot teardown.

Evidence / visual gate

The attended route spike passed all eight route gates with real Spotify and a visibly delivered pause: docs/media-evidence/pr04-mac-spike.md. It is route evidence only. This PR changes no widget pixels, so no Weaver pixel visual gate applies.

Performance

Performance claim explicitly declined: Weaver's implementation has not been measured against a real player on an attended Mac.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 169da456-e891-45ba-813d-ae73a221c107

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch media/04-macos-adapter

---

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

The PR adds the supervised macOS MediaRemote adapter and its asynchronous per-widget transport execution path.

• Adds incremental metadata, artwork normalization, playback advancement, and adapter-loss recovery.
• Moves media commands onto bounded per-widget workers so helper execution does not block supervision.
• Transfers in-flight worker ownership during slot teardown and fences provider shutdown on worker completion.
• Adds macOS lifecycle, recovery, transport, and CI coverage.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains in the asynchronous command-drain or nonjoining worker-teardown fixes.

Important Files Changed

Filename	Overview
host/src/macos_host.zig	Integrates asynchronous command-result draining, nonjoining slot teardown, media supervision, and bounded shutdown fencing.
host/src/providers_macos.zig	Implements the macOS adapter provider, per-widget command executors, metadata lifecycle, artwork handling, and focused teardown tests.
host/src/macos_media.m	Adds the native macOS runtime and process support used by the supervised adapter.
runtime/src/provider_macos.zig	Extends the macOS runtime provider path for media frames and transport acknowledgements.
host/build.zig	Packages and builds the vendored MediaRemote adapter resources.
.github/workflows/ci.yml	Adds adapter auditing and rebuilds both host and runtime with automation seams for macOS session testing.

Sequence Diagram

sequenceDiagram
    participant Widget
    participant Host as Host supervision loop
    participant Worker as Per-widget command worker
    participant Helper as MediaRemote helper
    Widget->>Host: Transport command over authenticated UDS
    Host->>Worker: Enqueue command
    Host-->>Host: Continue supervision and provider delivery
    Worker->>Helper: Launch bounded command helper
    Helper-->>Worker: Accepted, declined, or channel failure
    Worker-->>Host: Queue result
    Host-->>Widget: Write command acknowledgement
    Note over Host,Worker: Slot teardown detaches an in-flight worker
    Note over Worker: Worker self-releases after bounded completion

Loading

_{Reviews (8): Last reviewed commit: "fix: publish detached worker completion ..." | Re-trigger Greptile}

[SunkenInTime]

@greptile-apps The blocking issue in the review of 351e8e4 is addressed by d474281. Each transport-capable widget now owns a FIFO command worker; the host loop only authorizes/enqueues commands and drains results as the sole UDS writer. Tests cover FIFO command IDs and false acknowledgements on helper failure. Final-head Windows, Apple-silicon, Intel, and hosted-session CI are green. Please re-review the current head.

[SunkenInTime]

@greptileai

[SunkenInTime]

@greptileai

[SunkenInTime]

@greptileai

[SunkenInTime]

@greptileai