feat(ci): containerize macOS self-hosted runner

Add macOS container image for GitHub Actions self-hosted runner using
jianliang00/container (Apple Virtualization framework fork). The image
packages CLT, Homebrew, mise, Node.js 24, Deno 2.5, Task 3.49, Rust
nightly-2026-02-09, cargo-tauri, sccache, and the Actions runner binary.

Key changes:
- docker/macos/Dockerfile: macOS runner image (pre-built tarballs, no
  network during build)
- docker/macos/entrypoint.sh: ephemeral runner lifecycle with signal
  trapping
- scripts/runner.sh: unified CLI (prepare, build, start, stop, status,
  clean)
- Restructure docker/ by OS: linux/Dockerfile, macos/Dockerfile
- Update all references to old docker/Dockerfile.linux-amd64 path
- Add .hadolint.yaml with trusted registries and project ignores
- Add hadolint usage to AGENTS.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: pythoninthegrass

.github/workflows/release.yml

@@ -135,7 +135,7 @@ jobs:
         uses: useblacksmith/build-push-action@v2
         with:
           context: .
-          file: docker/Dockerfile.linux-amd64
+          file: docker/linux/Dockerfile
           target: artifacts
           push: false
           outputs: type=local,dest=dist

.github/workflows/test.yml

@@ -149,7 +149,7 @@ jobs:
         uses: useblacksmith/build-push-action@v2
         with:
           context: .
-          file: docker/Dockerfile.linux-amd64
+          file: docker/linux/Dockerfile
           target: check
           push: false
 

.gitignore

@@ -210,6 +210,11 @@ target
 # Contains mutation testing data
 **/mutants.out*/
 
+# macOS container build context (large tarballs from `runner.sh prepare`)
+docker/macos/*.tar
+docker/macos/*.tar.gz
+docker/macos/*.pkg
+
 # INCLUDE
 !**/.gitkeep
 !**/*.example

.hadolint.yaml

@@ -0,0 +1,10 @@
+failure-threshold: warning
+
+ignored:
+  - DL3008        # pin versions in apt-get
+  - DL3059        # multiple consecutive RUN (intentional in multi-stage)
+  - DL4006        # pipefail -- macOS container tool does not support SHELL
+
+trustedRegistries:
+  - docker.io
+  - ghcr.io

.tool-versions

@@ -7,3 +7,4 @@ nodejs         24.2.0
 prek           0.3.2
 ruff           0.12.11
 uv             0.9.24
+hadolint       2.12.0

AGENTS.md

@@ -145,6 +145,13 @@ cargo nextest run --workspace                     # Tests (falls back to cargo t
 cargo check --manifest-path src-tauri/Cargo.toml  # Fast type check (no binary)
 ```
 
+**Dockerfiles**:
+
+```bash
+hadolint docker/linux/Dockerfile                         # Lint Linux Dockerfile
+hadolint docker/macos/Dockerfile                         # Lint macOS Dockerfile
+```
+
 ### When to Run
 
 - **Before committing**: `task lint && task format`

backlog/tasks/task-312 - Containerize-macOS-self-hosted-GitHub-Actions-runner.md

@@ -0,0 +1,39 @@
+---
+id: TASK-312
+title: Containerize macOS self-hosted GitHub Actions runner
+status: In Progress
+assignee: []
+created_date: '2026-04-06 07:02'
+updated_date: '2026-04-06 07:02'
+labels:
+  - ci
+  - infrastructure
+  - macos
+dependencies: []
+references:
+  - 'https://github.com/jianliang00/container'
+  - 'https://github.com/jianliang00/container/releases/tag/0.0.1'
+  - docker/macos/Dockerfile
+  - docker/macos/entrypoint.sh
+  - scripts/runner.sh
+priority: medium
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Containerize the macOS ARM64 self-hosted runner using jianliang00/container (Apple Virtualization framework fork). Replaces bare-metal runner with a reproducible, isolated container image containing all CI dependencies.
+
+The container image packages pre-built tarballs from the host (no network during macOS container builds) including CLT, Homebrew, mise, Node.js, Deno, Task, Rust nightly, cargo tools, and the GitHub Actions runner binary.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Container image builds successfully with `scripts/runner.sh build`
+- [x] #2 All tools verified in smoke test (Rust, Node, Deno, Task, Brew, sccache, gh, CLT)
+- [ ] #3 Runner registers with GitHub and picks up jobs
+- [ ] #4 Existing workflow labels (macOS, ARM64) work without changes
+- [x] #5 Build context prepared from host tools via `scripts/runner.sh prepare`
+- [x] #6 Linux Dockerfile relocated to docker/linux/Dockerfile with all references updated
+- [x] #7 hadolint passes on both Dockerfiles
+<!-- AC:END -->

docker/Dockerfile.linux-amd64 docker/linux/Dockerfiledocker/Dockerfile.linux-amd64 renamed to docker/linux/Dockerfile

@@ -0,0 +1,79 @@
+# syntax=docker/dockerfile:1.17.1
+# check=skip=all
+
+FROM ghcr.io/jianliang00/macos-base:26.3
+
+# hadolint ignore=DL4006 -- container tool does not support SHELL directive
+# No network during build -- all dependencies are COPY'd as pre-built tarballs.
+# Run `scripts/runner.sh prepare` on the host to generate the build context.
+
+# Preserve the full default macOS PATH through all ENV directives
+ENV BASE_PATH="/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin"
+
+# Xcode Command Line Tools
+COPY CLTools.pkg /tmp/CLTools.tar
+RUN tar xf /tmp/CLTools.tar -C / \
+    && rm /tmp/CLTools.tar \
+    && xcode-select --switch /Library/Developer/CommandLineTools \
+    && echo "CLT installed at $(xcode-select -p)"
+
+# Homebrew + packages
+COPY homebrew.tar /tmp/homebrew.tar
+RUN /bin/mkdir -p /opt/homebrew \
+    && tar xf /tmp/homebrew.tar -C /opt/homebrew \
+    && rm /tmp/homebrew.tar
+
+# mise
+COPY mise.tar /tmp/mise.tar
+RUN /bin/mkdir -p /Users/Shared/.local/bin \
+    && tar xf /tmp/mise.tar -C /Users/Shared/.local/bin \
+    && rm /tmp/mise.tar
+
+# Node.js
+COPY node.tar /tmp/node.tar
+RUN /bin/mkdir -p /opt/node \
+    && tar xf /tmp/node.tar -C /opt/node \
+    && rm /tmp/node.tar
+
+# Deno
+COPY deno.tar /tmp/deno.tar
+RUN /bin/mkdir -p /opt/deno/bin \
+    && tar xf /tmp/deno.tar -C /opt/deno/bin \
+    && rm /tmp/deno.tar
+
+# Task
+COPY task.tar /tmp/task.tar
+RUN /bin/mkdir -p /opt/task/bin \
+    && tar xf /tmp/task.tar -C /opt/task/bin \
+    && rm /tmp/task.tar
+
+# Rust toolchain
+COPY rust.tar /tmp/rust.tar
+RUN /bin/mkdir -p /Users/Shared/.rustup /Users/Shared/.cargo \
+    && tar xf /tmp/rust.tar -C /Users/Shared \
+    && rm /tmp/rust.tar \
+    && cd /Users/Shared/.cargo/bin \
+    && for link in $(find . -type l); do \
+         target=$(readlink "$link"); \
+         case "$target" in */rustup) ln -sf /Users/Shared/.cargo/bin/rustup "$link" ;; esac; \
+       done
+
+# Cargo tools (tauri-cli, cargo-binstall)
+COPY cargo-tools.tar /tmp/cargo-tools.tar
+RUN tar xf /tmp/cargo-tools.tar -C /Users/Shared/.cargo/bin \
+    && rm /tmp/cargo-tools.tar
+
+# GitHub Actions runner
+COPY actions-runner.tar.gz /tmp/actions-runner.tar.gz
+WORKDIR /opt/actions-runner
+RUN tar xzf /tmp/actions-runner.tar.gz \
+    && rm /tmp/actions-runner.tar.gz
+
+# Set final PATH with all tools
+ENV PATH="/Users/Shared/.cargo/bin:/Users/Shared/.local/bin:/Users/Shared/.local/share/mise/shims:/opt/homebrew/bin:/opt/homebrew/sbin:/opt/node/bin:/opt/deno/bin:/opt/task/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin"
+ENV RUSTUP_HOME="/Users/Shared/.rustup" \
+    CARGO_HOME="/Users/Shared/.cargo"
+
+COPY entrypoint.sh /opt/actions-runner/entrypoint.sh
+RUN chmod +x /opt/actions-runner/entrypoint.sh
+ENTRYPOINT ["/opt/actions-runner/entrypoint.sh"]

docker/macos/Dockerfile

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+export HOME="${HOME:-/Users/Shared}"
+
+# PATH setup -- mirrors .github/actions/setup-tauri-build/action.yml
+export PATH="$HOME/.cargo/bin:$HOME/.local/share/mise/shims:/opt/homebrew/bin:/opt/homebrew/sbin:$PATH"
+
+# Enable sccache for Rust builds (CI taskfile disables it; override here)
+export RUSTC_WRAPPER=sccache
+
+# Required environment variables
+: "${GITHUB_REPO_URL:?GITHUB_REPO_URL is required}"
+: "${RUNNER_TOKEN:?RUNNER_TOKEN is required}"
+
+RUNNER_NAME="${RUNNER_NAME:-mt-macos-container}"
+RUNNER_LABELS="${RUNNER_LABELS:-macOS,ARM64}"
+RUNNER_WORKDIR="${RUNNER_WORKDIR:-_work}"
+
+cleanup() {
+    echo "Caught signal, removing runner..."
+    ./config.sh remove --token "${RUNNER_TOKEN}" 2>/dev/null || true
+    exit 0
+}
+trap cleanup SIGTERM SIGINT
+
+echo "Configuring runner '${RUNNER_NAME}' with labels '${RUNNER_LABELS}'..."
+./config.sh \
+    --url "${GITHUB_REPO_URL}" \
+    --token "${RUNNER_TOKEN}" \
+    --name "${RUNNER_NAME}" \
+    --labels "${RUNNER_LABELS}" \
+    --work "${RUNNER_WORKDIR}" \
+    --ephemeral \
+    --unattended \
+    --replace
+
+echo "Starting runner..."
+./run.sh &
+wait $!