--- 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 --plaintext` returns **empty** — and the release reports `no 'npmjs.com' secrets bundle on `, 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..enc`) — if it exists, the bundle is real and just unreadable headlessly. `AGENTS_SECRETS_PASSPHRASE= agents secrets export --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 --host `), 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 `. 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 v` 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` 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.