PR-E2 (ADR 0008 §6.5): self-hosted Mac M4 GitHub Actions integration workflow

[FluffyAIcode]

Why

Closes the loop on automated GA gating. After PR-N1..N4 retired all verifier-protocol test doubles from the Linux gate, the integration suite (tests/integration/) became the binding correctness gate for runtime modules — inference_engine.session.coordinator, inference_engine.session.generator, inference_engine.scheduler.scheduler, inference_engine.server.{app,engine,tokenizer,streaming}, kakeya.{client,session}. Until this PR, that suite ran manually via scripts/review_pr_*_on_mac.sh; PR-E2 wires it into CI on every PR labelled needs-mac-m4.

What ships

File	Lines	Purpose
.github/workflows/integration.yaml	+136	Self-hosted runner workflow: verify host + HF cache → pip install -e . → pytest -m integration → upload JUnit + inline failure summary
.github/workflows/auto-label-mac.yaml	+89	pull_request_target workflow that auto-applies needs-mac-m4 when a PR touches inference_engine/, sdks/, proto/, tests/integration/, or kv_cache_proposer/; auto-removes it if a subsequent push drops all verifier-dependent edits
docs/ops/mac-m4-runner-setup.md	+137	Operator runbook: hardware requirements, runner registration with kakeya-mac-m4 label, HF cache pre-warm command, Python toolchain setup, runtime expectations, cache hygiene cron, runner upgrade procedure, failure triage

Workflow details

integration.yaml

• Runs on: [self-hosted, macOS, ARM64, kakeya-mac-m4]
• Trigger: PR opened/synchronize/reopened/labeled + workflow_dispatch. Conditional on needs-mac-m4 label being present.
• Pre-flight: chip/memory check + HF_HUB_OFFLINE=1 enforcement (cache miss fails fast with a clear pre-warm command).
• Concurrency: cancel-in-progress per PR; new pushes supersede.
• Timeout: 90 min (operating point is 2-3 min on warm cache; the timeout is a safety margin).

auto-label-mac.yaml

• Runs on: ubuntu-latest (no self-hosted overhead).
• Triggers: every PR opened/synchronize/reopened.
• Logic: lists changed files via the GitHub API; matches against the trigger-path list; adds/removes the label as needed.

Two-tier gating model post PR-E2

Tier	Workflow	Coverage	Trigger
Linux gate	ci.yaml	Verifier-independent code, 100 %	Every PR; non-optional
Mac M4 gate	integration.yaml	Verifier-dependent code (runtime + SDK + proto + integration tests)	PRs labelled needs-mac-m4 (auto-applied)

Failure semantics differ:

• Linux gate failure blocks merge unconditionally.
• Mac M4 gate failure surfaces a structured report; the merge decision is human until v0.3.0 final ships, at which point we'll set required-status-check on this workflow too.

Operator runbook highlights

The docs/ops/mac-m4-runner-setup.md is the source of truth for the runner. Key one-time setup:

1. Register the runner with the kakeya-mac-m4 label (in addition to the default self-hosted, macOS, ARM64).
2. Pre-warm the HF cache:

   python3 -c "
   from transformers import AutoModelForCausalLM, AutoTokenizer
   AutoModelForCausalLM.from_pretrained('Qwen/Qwen3-0.6B')
   AutoTokenizer.from_pretrained('Qwen/Qwen3-0.6B')
   "

3. Verify Python 3.12+ and ARM64 architecture.
4. Run as launchd service so it survives reboots.

Stack

PR-E2 is branched off main, independent of the cleanup PRs. The workflow doesn't fail at launch even before PR-E1 lands; it just won't find any tests under tests/integration/ until that PR is merged. Recommended merge order:

1. Cleanup PRs (so the workflow has tests to run): PR-D1 (ADR 0008 Phase D): remove ADR 0007 server-side dead code #49 → PR-E1 (ADR 0008 §6.5): integration suite + INV-3 byte-exact GA gate #50 → PR-E1b (ADR 0008 §6.5): gRPC long-session bench + server CLI #51 → PR-E1c: fix kv_live_bytes reporting path #52 → PR-N1: remove verifier-protocol test doubles from Linux CI gate #53 → PR-N2: remove DeterministicEngine + DeterministicTokenizer from scheduler tests #54 → PR-N3: remove HTTP-shim, engine, tokenizer test doubles #55 → PR-N4: remove SDK conftest stub + finalize no-doubles cleanup #56.
2. PR-E2 (this PR) — wires up the workflow once the integration suite is on main.
3. After PR-E2 merges, the next PR you touch will auto-trigger the Mac M4 workflow.

Per ADR 0008 §9

This PR ships only workflow YAML + a runbook — no Python source changes. No Mac M4 evidence required for this PR; the workflow itself becomes the Mac M4 evidence machinery for ALL future PRs.

Reviewer checklist

• YAML files parse cleanly (verified locally with python3 -c "import yaml; yaml.safe_load(...)").
• auto-label-mac.yaml permission scope is pull-requests: write and trigger is pull_request_target (required for PRs from forks to gain the label).
• integration.yaml runs-on includes kakeya-mac-m4 (operator must add this label when registering the runner per the runbook).
• Runbook covers the cache pre-warm command + the HF_HUB_OFFLINE=1 constraint at test time.