release-headless

name	release-headless
description	Gotchas for the agents-cli headless release. The macOS home base signs, notarizes, and npm-publishes over SSH with no GUI and no Touch ID — three things must be primed or the release stalls. Triggers on: release stuck at sign/publish, errSecInternalComponent, "no npmjs.com bundle", "Missing embedded.provisionprofile", making the release autonomous.
user-invocable	true
version	1.0.0
author	muqsit

Headless release — home-base gotchas

apps/cli/scripts/release.sh orchestrates from any fleet box (Linux included) but routes the privileged phase — build + sign + notarize + npm publish — to the macOS home base over SSH. That phase runs with no GUI session and no Touch ID, so three things must be primed. When a release dies after "CI all-green, merged, tagged" but nothing lands on npm, it is almost always one of these.

Everything below is host-agnostic: resolve the home base from the release script, never hardcode a path.

1. Secrets bundles must be unlocked (locked ≠ empty)

The home base reads two file-backed secret bundles headlessly:

• npmjs.com → NPM_TOKEN (the publish token)
• apple.com → APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID, CSC_NAME (notarization)

They are decrypted with AGENTS_SECRETS_PASSPHRASE, which headless-sign-context.sh loads from an on-disk pass file. The failure mode: if a bundle was re-encrypted with a different passphrase (drift), or is simply locked, a headless agents secrets export <bundle> --plaintext returns empty — and the release reports no 'npmjs.com' secrets bundle on <home base>, which looks identical to the bundle being missing.

• Diagnose, don't assume. A 0 keys listing over SSH can mean locked, not empty. Check for the encrypted blob on disk (agents-cli.bundles.<name>.enc) — if it exists, the bundle is real and just unreadable headlessly. AGENTS_SECRETS_PASSPHRASE=<pass> agents secrets export <name> --plaintext tells you whether it is a passphrase mismatch (0) or a good decrypt (N keys).
• Fix: on the home base, agents secrets unlock npmjs.com apple.com. Interactive Touch ID works there; the unlock holds ~7 days and is global, so a subsequent headless SSH read (and the release) can then decrypt it. Do not try to unlock over SSH — no biometry prompt is available headlessly.
• Do not "fix" this by deleting + recreating the bundle blind: the token/creds are re-exportable from another box that already holds them (agents secrets export <name> --host <home base>), but the real problem is the lock state, not missing data.

2. The signing keychain ACL must grant codesign (errSecInternalComponent)

Codesign over pure SSH fails with errSecInternalComponent when the Developer ID private key's ACL requires interactive approval — there is no GUI session to answer it. The fix is not a GUI login; it is granting codesign non-interactive access:

• headless-sign-context.sh unlocks the signing keychain and runs security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k <pass> <keychain>. That partition-list grant is persistent in the keychain, so once primed it survives across releases.
• If codesign still fails on a fresh/reset box, the ACL prime did not take. It can only be authorized from a session that can reach the key. The durable, box-agnostic cure is the CI-standard recipe: store the Developer ID as a .p12 secret and have the context import it into a fresh keychain each run with security import … -T /usr/bin/codesign + set-key-partition-list — then no pre-existing keychain state has to survive a reboot. (The identity .p12 exports headlessly, so this needs no GUI step to set up.)
• Symptom-to-cause: errSecInternalComponent is a keychain/ACL problem, never a cert-chain or notarization problem. Do not chase the cert.

3. The build runs from a fresh worktree of the tag — gitignored inputs are absent

The home-base phase does git worktree add --detach <wt> v<version> and builds there. Anything the build needs that is gitignored is not in that worktree. The concrete case: the keychain helper needs apps/cli/bin/embedded.provisionprofile, but /apps/cli/bin/ is gitignored — so the profile lives only in the home base's main checkout, and the worktree build dies with Missing … embedded.provisionprofile. Generate at developer.apple.com and check it in.

• release.sh copies the profile from the home base's checkout into the worktree after creating it. If you add another gitignored build input, copy it in the same place — do not assume the worktree has it.
• General rule: the tag's tree is the source of truth for the build except for gitignored signing inputs, which must be injected from the home base's checkout.

4. The published tree is the CI-tested tree, not main's HEAD

On a busy default branch, unrelated PRs merge during a release PR's CI window, so the squash-merge lands on a newer base and its tree diverges from what CI tested. release.sh (via select-publish-commit.sh) detects this and tags + publishes the CI-tested release commit (the PR head the full matrix went green on), not the drifted merge — the intervening commits ride the next release. So a v<version> tag can legitimately point at a commit that is not on the default branch's first-parent line. This is by design; do not "fix" it by re-pointing the tag at main.

The mental model

merged → tagged → **home-base phase** is where autonomy lives or dies. The home base is the one box with npm-publish rights + the Developer ID cert, so the privileged phase always routes there regardless of the trigger box. Making that phase truly zero-touch means: bundles unlocked (1), keychain ACL primed (2), gitignored signing inputs injected into the build worktree (3). Get those three right and a Linux box can drive the whole release end to end.