[stefanwb]

Summary

Phase 2b of #38, docs-only. Documents the smoke-test coverage and adds a macOS manual-fallback checklist. The originally-planned automated macOS CI job is dropped.

Why no automated macOS job

The spike (run on this PR) was conclusive: GitHub-hosted macos-latest can't reliably provision a Docker daemon for the job —

• Colima vz driver → VM won't boot (runner nested-virt limitation),
• Colima qemu driver → upstream Lima crash (panic: send on closed channel in qemu_driver.go).

Both fail at provisioning, before any assertion runs, and Colima's file-sharing may not match Docker Desktop's st_dev behaviour anyway — so a hosted job would add cost + flakiness for no reliable signal. The Linux smoke matrix (merged in #55) covers all the OS-independent behaviour; the one macOS-only behaviour (virtiofs collapsing st_dev across bind mounts, which changes the entrypoint's -xdev chown-prune over the :ro mounts under /root) is covered by a manual checklist instead.

What changed

• claude-docker/README.md: a "CI smoke tests" section (Linux CI coverage + how to run a cell locally) and a "Manual fallback checklist (macOS)" for verifying the virtiofs delta and credential flows on a real Mac before shipping entrypoint.sh/run.sh/Dockerfile changes.

No workflow/code changes — README only.

Closes #38.

🤖 Generated with Claude Code

[stefanwb]

Reviewed (draft, stacked on #55). Verified smoke/ scripts exist and CI/README correctly use the post-rename paths. Gating is safe — pull_request (not pull_request_target), contents: read, no secrets, so a labeled fork PR can't exfiltrate anything. The spike framing (stated assumption + pre-agreed drop path) is exemplary.

One substantive finding + minors:

1. Adding the smoke-macos label will NOT trigger a run — the documented spike procedure won't work as written.
on.pull_request has no types:, so it uses the defaults (opened, synchronize, reopened). labeled is not among them, so "add the label here and observe one run" silently does nothing — the labeled event isn't subscribed to, so no run starts to evaluate the if. Fixes (pick one):

• Add types: [opened, synchronize, reopened, labeled] to the pull_request trigger (enables the label flow), or
• Re-point the docs at workflow_dispatch (the "Run workflow" button), which already works as written via the github.event_name == 'workflow_dispatch' clause. Labeling only takes effect if you then push a commit (synchronize).
  Cheapest correct fix: trigger the spike via workflow_dispatch and drop/soften the label language — or add the labeled type if you want the label flow.

2. (minor) needs: [changes] on smoke-macos is unused — its if never references needs.changes.outputs.docker (unlike docker-build). changes always runs so it doesn't block, but it's a superfluous/ misleading dependency. Drop it, or actually gate on && needs.changes.outputs.docker == 'true'.

3. (cosmetic, not merged content) PR body still says test/smoke.sh (stale pre-#55 rename); the committed README/ci.yml correctly use smoke/.

Recommend fixing #1 before running the spike (otherwise you'll add the label, see nothing, and lose time), and dropping the needs in #2. Then run via workflow_dispatch regardless. Hold merge until #55 lands and this retargets to main, as noted.

[stefanwb]

Thanks — your review landed right as the spike resolved, and it's a clean sweep: after the spike I converted this PR to docs-only (dropped the smoke-macos job + Colima steps entirely, deleted the smoke-macos label), so all three findings are now moot:

1. labeled not a default pull_request type — spot on, and it's exactly the friction I hit running the spike: adding the label did nothing, and I had to close/reopen (a reopened event) to force a run. Good catch. It's now N/A — there's no macOS job or label to trigger. (For the record, the spike then failed at provisioning anyway: vz won't boot on the runner, qemu hits an upstream Lima panic — neither reached the cells, hence the drop.)
2. needs: [changes] unused on smoke-macos — N/A, the job is gone.
3. PR body said test/smoke.sh — rewritten; the body, README, and ci.yml now all use smoke/ and contain no smoke-macos/label references.

What's left is README-only: the Linux CI write-up + a macOS manual-fallback checklist (the realistic way to cover the virtiofs st_dev delta, since hosted runners can't). Retargeted to main, CI green. Closes #38.

[stefanwb]

Re-checked after the force-push to docs-only — confirmed: diff vs main is README-only (+36), the smoke-macos job + Colima steps are gone from ci.yml, and there are no leftover smoke-macos/label/workflow_dispatch references anywhere. All three findings are moot (no job/label to mis-trigger, no unused needs, paths consistent). Good call dropping Phase 2b's CI leg given the vz/qemu provisioning dead-end.

Reviewed the remaining README change:

• "CI smoke tests" accurately matches the Linux matrix (UID 1000/501/0, cold/warm, opt-ins, ephemeral, ro); the local-run command is executable (the stat -f + portable SCRIPT_DIR fixes from #55 make the macOS commands work).
• "Manual fallback checklist (macOS)" is honest and well-scoped — it pins the one macOS-unique behavior (virtiofs st_dev collapse → entrypoint.sh's -xdev chown-prune over :ro mounts under /root), which is exactly the gap Linux CI structurally can't cover. The "no spurious entrypoint: WARN" bullet targets it directly.

One trivial nit: entrypoint.sh:30-45 is a line-number ref that'll rot over time (same pattern as the #54 docstring) — consider referencing the chown block by description. Not blocking.

Clean docs-only PR. LGTM.