feat(release): ship the Homebrew formula from native release tarballs (#356)

## Requirement or Bug

Ship the Homebrew formula as the native binary, the way CodexBar's tap
does: per-platform release tarballs, bumped by the release run, verified
by a real install.

Stacked on #355 (shares `update-brew-formula.mjs`).

## Bug Reproduction Steps

N/A (feature).

## Root Cause

N/A (feature).

## Code Changes

- `update-brew-formula.mjs`: `renderFormula` writes the whole formula
from a template instead of patching one `url` line with a regex. The
template has `on_macos`/`on_linux` × `Hardware::CPU.arm?`, one native
`pythinker-code-<target>.tar.gz` url + sha256 per target, `bin.install
"pythinker"`, and a `test do` that asserts `pythinker --version`. The
sha256 comes from the downloaded bytes, not from the sidecars. All four
downloads share one 600 s poll that retries on 404. After the push, the
script reads `Formula/pythinker-code.rb` back from the tap's `main` and
fails if it differs. A rejected push gets up to 3 attempts with `pull
--rebase` between them.
- `release.yml`:
- `update-brew-tap` now also needs `publish-native-assets`. On 2.4.1 the
tarballs appeared about 13 min after `release` finished.
- New `verify-brew-install` job (macos-latest + ubuntu-latest) runs
`brew tap`, `brew install`, `brew test` and compares `--version` with
`package.json`.
- `Release lane summary` reads `BREW_RESULT` from `verify-brew-install`.
- `cli/update/source.ts`: a native binary under a Homebrew Cellar counts
as a `homebrew` install. `detectNativeInstall()` returns false there, so
the binary never stages or swaps itself inside the Cellar, and `brew
upgrade` is its update path. Every caller of `detectNativeInstall()`
(update download, startup swap, source detection) goes through this one
function.
- `.agents/skills/release/SKILL.md`: the brew section now describes this
flow.

How this differs from CodexBar: CodexBar dispatches a tap-side workflow
with a PAT. This PR keeps the existing GitHub App token, which pushes
the formula directly. That needs no new secret and no workflow in the
second repo. The substance is the same: a native per-platform formula, a
404 retry on assets, and a content check after the bump.

## Behavior Changes and Affected Users

| Behavior | Before | After | Who relies on the old behavior | Escape
hatch |
|---|---|---|---|---|
| What `brew install pymodel/tap/pythinker-code` installs | npm tarball
+ `depends_on "node"` | native binary, no Node.js | Homebrew users on
macOS and Linux | `npm i -g @pymodel/pythinker-code` |
| `node` formula after `brew upgrade` | a dependency | orphaned (`brew
autoremove` may delete it) | users who rely on brew-managed `node` only
through this formula | `brew install node` |
| opentui caveat in the formula | printed | removed (the native binary
bundles it) | nobody | n/a |
| Install source of a native binary in `/opt/homebrew/Cellar/…` or
`/home/linuxbrew/.linuxbrew/Cellar/…` | `native` (would stage and swap
itself) | `homebrew` (shows the `brew upgrade` hint) | nobody; only this
PR puts native binaries into the Cellar | n/a |
| Release lane brew result | the tap push job | the real install on
macOS + Ubuntu | release operators | `RELEASE_LANE_BREW=disabled`
(unchanged) |

Inventory of the old npm-formula path and where each item went:

| Old item | New place |
|---|---|
| `depends_on "node"` | dropped; the binary bundles Node |
| opentui caveat | dropped |
| npm tarball sha256 from the registry | sha256 of each release tarball
from the downloaded bytes |
| npm 404 poll (600 s) | the same poll, shared across the 4 release
tarballs |
| `--version` test | kept, now on the native binary |

Test coverage:
- `source.test.ts`: Cellar paths on macOS and Linux → `homebrew`, and
`detectNativeInstall` returns false. Both failed before the change.
- `update-brew-formula.test.mjs`: formula pairs in order, a missing
target throws, an invalid sha256 throws.
- `release-workflows.test.mjs`: the brew needs and `BREW_RESULT` wiring.
- Manual check with real Homebrew on the 2.4.1 tarballs, done with `brew
install` + `brew test`:
  - macOS arm64: the Developer ID signature stays intact.
  - Linux x64 (`homebrew/brew` container): `--version` prints 2.4.1.
- `pnpm test:release` 58/58; app update suites 329/329; `tsc`, lint,
actionlint clean.

## Checklist

- [x] I have read the
[CONTRIBUTING](https://github.com/PyModel/pythinker-code/blob/main/CONTRIBUTING.md)
document.
- [x] I have linked a related issue (external PRs: issue must have a
maintainer's `/approve`).
- [x] I have added tests that prove my feature works.
- [x] The behavior-change table above is complete, and every removed
behavior or flipped default is named in the changeset and either has an
escape hatch or was explicitly approved by a maintainer in this PR.
- [x] Ran `gen-changesets` skill, or this PR needs no changeset.
- [x] Ran `gen-docs` skill, or this PR needs no doc update.

Author: elkaix

.agents/skills/release/SKILL.md

@@ -43,7 +43,8 @@ workspace, set its `private` and changesets policy explicitly and update `flake.
 | `Native release artifact` | CLI was published | Six signed/tested zips, checksums, provenance |
 | `Publish native release assets` | native builds passed | All-or-nothing immutable upload with `manifest.json` |
 | `Redeploy CDN` + verify | native assets published | Webhook may retry; verification is the hard gate |
-| `Update Homebrew tap` | CLI was published | App token scoped to `homebrew-tap` contents |
+| `Update Homebrew tap` | native assets published | Renders `Formula/pythinker-code.rb` from the four native `.tar.gz` (macOS/Linux × arm64/x64), hashes downloaded bytes, pushes with an App token scoped to `homebrew-tap` contents, reads the formula back from the tap |
+| `Verify Homebrew install` | tap updated | `brew install` + `brew test` from `pymodel/tap` on macOS and Linux; `pythinker --version` must equal the release. This is the Homebrew lane result in the summary |
 | `Release lane summary` | always | One table with provenance state; fails when an expected enabled lane failed or skipped |
 
 Set `RELEASE_LANE_DESKTOP`, `RELEASE_LANE_VSCODE`, `RELEASE_LANE_CDN`, or
@@ -70,6 +71,17 @@ otherwise errors.
   `beta`/`dev` tags). A mismatch means the checkout in the job predates the release commit or npm
   propagation lag — check `npm view @pymodel/pythinker-code dist-tags` before touching anything.
   Dokploy deploy specifics: see memory `cdn-dokploy-deploy-pipeline`.
+- **Homebrew lane red.** `Update Homebrew tap` polls each native tarball for 10 minutes, so a
+  failure there means the release has no tarball for that target: check `Publish native release
+  assets` first. `Verify Homebrew install` red with the bump green means the formula installs but the
+  binary fails in a keg on that OS; reproduce with `HOMEBREW_NO_AUTOREMOVE=1 brew install
+  pymodel/tap/pythinker-code` (plain `brew uninstall` afterwards autoremoves orphaned dependencies).
+  A native binary under a Homebrew `Cellar/` reports install source `homebrew` and never
+  self-updates; `brew upgrade pythinker-code` is its only update path.
+- **Native update 404s.** `verify-release-consistency.mjs` HEADs every URL in the CDN `latest.json`
+  and every file the release `manifest.json` names. A red gate lists the missing assets; the
+  updater fetches exactly those URLs from the GitHub release (`pythinkerCodeReleaseAssetUrl`). The
+  CDN has no `/binaries/` route — it answers unknown paths with the site HTML and HTTP 200.
 - **`pnpm install` fails in CI or locally.** `engine-strict=true` + Node `>=24.15.0` — check
   `.nvmrc` before debugging anything else.
 - **Identity freeze / version rewind.** Copying another product's `CHANGELOG.md`, `package.json`

.changeset/brew-native-formula.md

@@ -0,0 +1,5 @@
+---
+'@pymodel/pythinker-code': minor
+---
+
+Homebrew now installs the native `pythinker` binary on macOS and Linux, without Node.js.

.github/workflows/release.yml

@@ -494,7 +494,11 @@ jobs:
     permissions:
       contents: read
     name: Update Homebrew tap
-    needs: release
+    # The formula installs the native tarballs, so it can only point at them
+    # once publish-native-assets has put them on the release.
+    needs:
+      - release
+      - publish-native-assets
     if: >-
       needs.release.outputs.pythinker_native_release == 'true'
       && vars.RELEASE_LANE_BREW != 'disabled'
@@ -526,6 +530,51 @@ jobs:
           TAP_GITHUB_TOKEN: ${{ steps.tap-token.outputs.token }}
         run: node scripts/release/update-brew-formula.mjs
 
+  # Installs the bumped formula from the public tap on a real Homebrew, the
+  # way users get it, and checks the binary reports the released version.
+  # Homebrew relocates and may re-sign what it installs, so this is the only
+  # proof the native binary survives a keg on each OS.
+  verify-brew-install:
+    timeout-minutes: 20
+    name: Verify Homebrew install (${{ matrix.os }})
+    needs:
+      - update-brew-tap
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # pinned from v6.0.2
+        with:
+          persist-credentials: false
+          sparse-checkout: apps/pythinker-code/package.json
+          sparse-checkout-cone-mode: false
+
+      - name: Install pythinker-code from PyModel/tap
+        shell: bash
+        env:
+          HOMEBREW_NO_AUTO_UPDATE: '1'
+          HOMEBREW_NO_INSTALL_CLEANUP: '1'
+        run: |
+          set -euo pipefail
+          if [ -x /home/linuxbrew/.linuxbrew/bin/brew ]; then
+            eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
+          fi
+          expected="$(jq -r .version apps/pythinker-code/package.json)"
+          brew tap pymodel/tap
+          brew install --formula pymodel/tap/pythinker-code
+          brew test pymodel/tap/pythinker-code
+          actual="$("$(brew --prefix)/bin/pythinker" --version)"
+          if [ "$actual" != "$expected" ]; then
+            echo "::error::Homebrew installed pythinker $actual, expected $expected."
+            exit 1
+          fi
+          echo "Homebrew installs pythinker $actual on ${{ matrix.os }}."
+
   deploy-docs:
     name: Deploy docs
     needs: release
@@ -663,6 +712,7 @@ jobs:
       - redeploy-cdn
       - verify-cdn-release
       - update-brew-tap
+      - verify-brew-install
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -687,7 +737,7 @@ jobs:
           CDN_DEPLOY_RESULT: ${{ needs.redeploy-cdn.result }}
           CDN_VERIFY_RESULT: ${{ needs.verify-cdn-release.result }}
           BREW_ENABLED: ${{ vars.RELEASE_LANE_BREW != 'disabled' }}
-          BREW_RESULT: ${{ needs.update-brew-tap.result }}
+          BREW_RESULT: ${{ needs.verify-brew-install.result }}
           DESKTOP_EXPECTED: ${{ needs.release.outputs.desktop_version_bumped }}
           DESKTOP_ENABLED: ${{ vars.RELEASE_LANE_DESKTOP != 'disabled' }}
           DESKTOP_RESULT: ${{ needs.cut-desktop-tag.result }}

apps/pythinker-code/src/cli/update/source.ts

@@ -26,8 +26,7 @@ function loadSeaModule(): NodeSeaModule | null {
   return cachedSea;
 }
 
-/** Runtime SEA detection — true when running as a packaged native binary. */
-export function detectNativeInstall(): boolean {
+function isSeaBinary(): boolean {
   const sea = loadSeaModule();
   if (sea === null) return false;
   try {
@@ -37,6 +36,19 @@ export function detectNativeInstall(): boolean {
   }
 }
 
+/**
+ * True for a self-updating native install: a packaged native binary that no
+ * package manager owns. A native binary Homebrew installed lives in its
+ * Cellar; staging or swapping it there would desync Homebrew's records, so
+ * `brew upgrade` stays its only update path.
+ */
+export function detectNativeInstall(
+  execPath: string = process.execPath,
+  isSea: () => boolean = isSeaBinary,
+): boolean {
+  return isSea() && classifyByPathHeuristic(execPath) !== 'homebrew';
+}
+
 // Path heuristic markers (compared in lowercase; both forward and backward slashes accepted).
 const PNPM_PATH_SEGMENT = 'pnpm/global/';
 const YARN_PATH_SEGMENTS = ['.config/yarn/global/', '/.yarn/global/'];
@@ -70,6 +82,7 @@ export interface DetectInstallSourceDeps {
   readonly getPackageRoot: () => string;
   readonly getGlobalPrefix: () => Promise<string>;
   readonly detectNative: () => boolean;
+  readonly execPath: string;
   readonly platform: NodeJS.Platform;
 }
 
@@ -153,11 +166,14 @@ export async function detectInstallSource(
     getGlobalPrefix:
       deps.getGlobalPrefix ??
       (() => npmGlobalPrefix(platform)),
-    detectNative: deps.detectNative ?? detectNativeInstall,
+    detectNative: deps.detectNative ?? isSeaBinary,
+    execPath: deps.execPath ?? process.execPath,
     platform,
   };
 
-  if (resolved.detectNative()) return 'native';
+  if (resolved.detectNative()) {
+    return classifyByPathHeuristic(resolved.execPath) === 'homebrew' ? 'homebrew' : 'native';
+  }
 
   const packageRoot = resolved.getPackageRoot();
   const heuristic = classifyByPathHeuristic(packageRoot);

apps/pythinker-code/test/cli/update/source.test.ts

@@ -4,6 +4,7 @@ import {
   classifyByPathHeuristic,
   classifyInstallSource,
   detectInstallSource,
+  detectNativeInstall,
 } from '#/cli/update/source';
 import { resolveCommandPath } from '#/utils/process/resolve-command';
 
@@ -158,6 +159,18 @@ describe('detectInstallSource', () => {
     ).resolves.toBe('native');
   });
 
+  it('returns homebrew for a native binary that Homebrew installed in its Cellar', async () => {
+    await expect(
+      detectInstallSource({
+        getPackageRoot: () => '/opt/homebrew/Cellar/pythinker-code/2.5.0/bin',
+        getGlobalPrefix: async () => '/opt/homebrew',
+        detectNative: () => true,
+        execPath: '/opt/homebrew/Cellar/pythinker-code/2.5.0/bin/pythinker',
+        platform: 'darwin',
+      }),
+    ).resolves.toBe('homebrew');
+  });
+
   it('returns unsupported when nothing matches', async () => {
     await expect(
       detectInstallSource({
@@ -197,3 +210,20 @@ describe('detectInstallSource', () => {
     expect(resolveCommandPath).toHaveBeenCalledWith('npm');
   });
 });
+
+describe('detectNativeInstall', () => {
+  it('is true for a native binary outside any package manager', () => {
+    expect(detectNativeInstall('/Users/someone/.local/bin/pythinker', () => true)).toBe(true);
+  });
+
+  it('is false for a native binary that Homebrew owns, so it never stages or swaps itself', () => {
+    expect(detectNativeInstall('/opt/homebrew/Cellar/pythinker-code/2.5.0/bin/pythinker', () => true)).toBe(false);
+    expect(
+      detectNativeInstall('/home/linuxbrew/.linuxbrew/Cellar/pythinker-code/2.5.0/bin/pythinker', () => true),
+    ).toBe(false);
+  });
+
+  it('is false when the process is not a native binary', () => {
+    expect(detectNativeInstall('/Users/someone/.local/bin/pythinker', () => false)).toBe(false);
+  });
+});

scripts/release/release-workflows.test.mjs

@@ -32,6 +32,10 @@ void test('release workflow uses full push-boundary lane signals and isolated jo
   assert.match(workflow, /APPLE_CERTIFICATE_P12: \$\{\{ secrets\.MAC_CSC_LINK \}\}/u);
   assert.match(workflow, /APPLE_NOTARIZATION_KEY_P8: \$\{\{ secrets\.APPLE_API_KEY_P8 \}\}/u);
   assert.match(workflow, /^  update-brew-tap:\n    timeout-minutes: 20$/mu);
+  const brewJob = workflow.slice(workflow.indexOf('  update-brew-tap:'), workflow.indexOf('  verify-brew-install:'));
+  assert.match(brewJob, /needs:\n      - release\n      - publish-native-assets\n/u);
+  assert.match(workflow, /^  verify-brew-install:/mu);
+  assert.match(workflow, /BREW_RESULT: \$\{\{ needs\.verify-brew-install\.result \}\}/u);
 });
 
 void test('VS Code release supports isolated recovery and attests verified VSIX files', () => {