macOS .pkg: add clean-host fresh-install lane to release acceptance

[Jesssullivan]

Context

This issue tracks the production macOS pkg clean-host acceptance lane for TCFS Finder/FileProvider. PZM Mac App Development testing-mode evidence is useful lab proof, but it does not replace production Developer ID clean-host Finder acceptance.

Current state as of 2026-05-09

The repo contains the named post-install harness and workflow:

• scripts/macos-postinstall-smoke.sh
• .github/workflows/macos-postinstall-smoke.yml
• workflow_dispatch default runner label: macos-15
• environment: tcfs-macos-smoke
• required smoke secrets: TCFS_SMOKE_S3_ENDPOINT, TCFS_SMOKE_S3_BUCKET, TCFS_SMOKE_S3_ACCESS_KEY_ID, TCFS_SMOKE_S3_SECRET_ACCESS_KEY, TCFS_SMOKE_MASTER_KEY_B64

Current PZM testing-mode evidence is green through enumerate, hydrate, evict, rehydrate, mutation upload/readback, and deterministic CLI conflict/status content preservation. The latest recorded PZM runs remain lab/testing-mode proof, not production Finder acceptance.

Remaining blockers

• Choose and run a production Developer ID clean-host executor: GitHub-hosted macOS with publicly reachable storage, private-network hosted runner, self-hosted VM, or manual Darwin lane.
• Complete one tagged run that proves published pkg install plus host-app launch, FileProvider domain presence, CloudStorage enumeration, and exact-content hydrate.
• Keep Finder badges/progress/notification behavior observational until reliable assertions exist.

Acceptance

• One tagged production Developer ID clean-host run completes with archived logs.
• The run proves package/install smoke and install-to-first-real-use through enumerate plus hydrate.
• Any executor-specific failure mode is recorded with an explicit fallback decision.

Refs: #280, docs/ops/macos-fileprovider-reality.md, docs/ops/packaged-install-first-use.md

[Jesssullivan]

Audit update as of April 17, 2026.

The clean-host gap is real, but this pass makes the missing scope boundary much sharper.

What the repo proves today:

• scripts/install-smoke.sh proves the installed binaries execute, tcfsd creates its socket, and tcfs status works when the CLI is present.
• It does not prove launchd, pluginkit, host-app registration, CloudStorage appearance, Finder enumeration, hydration, mutation, or conflict handling.
• docs/ops/macos-fileprovider-reality.md already defines the real desktop acceptance lane: install -> extension visible -> launch host app -> CloudStorage root appears -> enumerate -> open a placeholder-backed file -> hydration succeeds -> tcfsd stays healthy.

Important installer edge case surfaced by the current packaging path:

• the release workflow's postinstall only auto-registers the FileProvider extension when the app lands at /Applications/TCFSProvider.app
• the previously documented installer -target CurrentUserHomeDirectory path lands the app under ~/Applications/TCFSProvider.app, so that path is not a truthful substitute for clean-host / install proof

Missing fresh-install / power-user surfaces from this issue's current wording:

1. pristine macOS / target install with no inherited env, no existing launch agent, and no prior app copy
2. first-run host-app config/Keychain provisioning and FileProvider domain re-add
3. post-install desktop path: CloudStorage root, enumerate, hydrate one real remote-backed file
4. at least one user-ish edge case from the same machine: unsync/dehydrate + rehydrate, or mutate/conflict
5. launchd health check from the installed artifact, not just temp-home daemon smoke

Recommendation: keep #309 as the clean-host package/install tracker, but make the acceptance bar explicit: one fresh-install pass on a clean macOS machine should finish with both

• binary/package smoke, and
• a linked run of the named Finder/FileProvider desktop smoke from docs/ops/macos-fileprovider-reality.md

Otherwise we prove installer mechanics without proving the user-facing post-install path.

One more signal from the tinyland branch audit: test/fileprovider-functional is exactly the kind of automation target that would turn this from a recurring manual gap into a named acceptance lane.

[Jesssullivan]

Repo-gap read after the current PM/doc pass:

What is still missing for #309 is not only a clean macOS host. We also do not yet have a named repo-local smoke harness for the post-install FileProvider path.

Current state in the tree:

• scripts/install-smoke.sh only proves installed binary startup in an isolated temp home
• there is no macOS-specific scripts/* smoke for host-app launch, FileProvider domain re-add, pluginkit visibility, ~/Library/CloudStorage appearance, enumerate, or hydrate
• docs/ops/macos-fileprovider-reality.md defines the manual lane, but it is still prose/manual steps rather than an executable harness
• .github/workflows/release.yml packages the app and runs pluginkit -a during install, but it does not prove host-app launch or first desktop use

That suggests #309 is really two subproblems:

1. Harness gap
   • add a named macOS post-install smoke script/runbook that checks:
     • pluginkit registration
     • host-app launch
     • domain presence / re-add
     • ~/Library/CloudStorage root appearance
     • enumerate of at least one item
     • hydrate of at least one placeholder-backed file
2. Executor gap
   • decide where that harness runs from a known-clean state:
     • Tart / UTM VM
     • GitHub Actions macOS runner
     • or intentionally keep this as a manual per-tag maintainer lane

If we want a tight tonight-sized slice, the smallest durable move is probably to define or add the harness first, then choose the clean-host executor second.

[Jesssullivan]

Draft PR #319 is up with the repo-local harness half of this issue.

What the patch adds:

• scripts/macos-postinstall-smoke.sh as a named post-install FileProvider harness
• artifact/version checks for installed tcfs / tcfsd
• pluginkit registration verification
• host-app launch plus host-log confirmation that the domain re-add path ran
• wait for ~/Library/CloudStorage/TCFS*
• enumeration sample
• optional hydration of a known remote-backed file via --expected-file
• post-hydrate tcfs status check requiring storage [ok]

That narrows #309 to the remaining executor decision:

• where this harness runs from a known-clean state per tag (VM, macOS Actions runner, or explicit manual maintainer lane)

PR: #319

[Jesssullivan]

Merged in #320 as 5dee4f7 on main.

Current blocker is no longer executor design. The repo now has the manual GitHub-hosted macOS .pkg post-install lane plus the named harness. Remaining work is operational:

• set repository secrets: TCFS_S3_ENDPOINT, TCFS_S3_BUCKET, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, TCFS_NATS_URL
• dispatch .github/workflows/macos-postinstall-smoke.yml on a real tag
• if that run fails for hosted-runner reasons rather than product reasons, pivot this issue to the fallback executor explicitly

[Jesssullivan]

Follow-up in #321: the hosted macOS lane does not actually need NATS.

Repo evidence:

• docs/ops/fleet-deployment.md already states tcfs push/pull works without NATS and that NATS is tailnet-only
• tcfs status reports storage and NATS separately
• tcfsd treats NATS connection as non-blocking / best-effort

So the remaining blocker for the GitHub-hosted executor is narrower than the current issue body implied:

• reachable S3/storage from the hosted runner
• storage credentials
• one successful tagged run

If storage remains tailnet-only or otherwise unreachable from GitHub-hosted macOS, that should be treated as the real reason to pivot #309 to a VM or manual executor.

[Jesssullivan]

Deep-dive update:

• Draft PR [codex] fix macOS FileProvider shared keychain config #322 is up with a repo-side fix for the macOS shared-config path.
• Root cause addressed there: the macOS host app wrote configJSON without an explicit shared access group, while the extension assumed same-Developer-ID signing was enough to read it back.
• The patch switches the macOS path to an explicit app-group keychain item in the data-protection keychain, matching the stronger model already used on iOS.

What this does not settle:

• whether group.io.tinyland.tcfs is fully valid on a clean Developer ID install without additional provisioning-profile work
• whether the GitHub-hosted macOS runner can actually reach the chosen storage endpoint once secrets are added

So #309 now has three distinct layers:

1. workflow cannot run today without storage secrets
2. hosted runner may still fail on backend reachability even with secrets
3. after backend reachability is solved, app-group / FileProvider runtime behavior is the next clean-machine proof question

PR: #322

[Jesssullivan]

Tahoe / Darwin strategy note from Apr 18, 2026 research:

• I did not find a new Tahoe 26.x beta policy change that materially weakens the current FileProvider path for tcfs.
• Apple now has FSKit as a real user-space filesystem framework on macOS, and that is the only forward-looking Apple-aligned mount-style path worth taking seriously.
• Apple still positions NSFileProviderReplicatedExtension as the macOS cloud-sync model; that remains the safest supported product path for tcfs.
• macFUSE has moved toward FSKit and now advertises macOS 26 support for non-local volumes, but its FSKit backend still has meaningful limitations (mountpoints under /Volumes, missing notification semantics, lower I/O performance, etc.).
• Commercial NTFS drivers support Tahoe, but they still look like survivability of old driver models rather than evidence that Apple is becoming friendlier to third-party kernel-style filesystem stacks.

Implication for tcfs:

• keep FileProvider as the primary supported Darwin surface
• treat FSKit exploration as the only credible mount-style hedge
• do not let kext/FUSE-style mounts become the mainstream macOS support promise

This does not change the immediate #309 acceptance lane: the near-term blocker is still proving the packaged FileProvider path on a clean host with reachable storage.

Useful sources:

• Apple FSKit docs: https://developer.apple.com/documentation/FSKit
• Apple File Provider docs: https://developer.apple.com/documentation/FileProvider
• Apple macOS Tahoe 26.4 release notes: https://developer.apple.com/documentation/macos-release-notes/macos-26_4-release-notes
• macFUSE getting-started / FSKit notes: https://github.com/macfuse/macfuse/wiki/Getting-Started
• macFUSE backends: https://github.com/macfuse/macfuse/wiki/FUSE-Backends

[Jesssullivan]

Merged #322 to main as 892c7a2.

This closes one concrete repo-side failure class in the macOS clean-host lane: the Host app and File Provider extension now use an explicit shared app-group keychain item in the data-protection keychain rather than relying on implicit same-Developer-ID access.

What remains open on #309 is narrower:

• live storage reachability from the chosen executor
• repo secrets for the hosted workflow if we keep the GitHub-hosted lane
• clean-machine validation that the current app-group/container story is sufficient on a shipped Developer ID install

So #309 is no longer blocked on the shared-keychain config path; it is blocked on execution environment and remaining app-group/runtime proof.