Skip to content

Hand a Homebrew-managed bundle back to brew instead of installing over it - #4

Merged
tarnish233 merged 16 commits into
mainfrom
brew-owns-brew-installs
Aug 29, 2026
Merged

tarnish233 merged 16 commits into
mainfrom
brew-owns-brew-installs

Conversation

@tarnish233

Copy link
Copy Markdown
Owner

Ports Claude Code's update policy: when a Homebrew cask owns this bundle, the app hands over brew upgrade --cask gitpic instead of replacing the bundle itself. Nothing is spawned and nothing quits — the sheet says what to run and stays where it is.

Companion PR on the tap (comments only, no stanza change): tarnish233/homebrew-tap#2

Why this is not a revert of bb07783

0.20.9 deleted Route.homebrew and made the app install every update itself, cask included. That removal fixed two measured defects, and both came from executing brew upgrade after the app had already quit:

  • an .accessory app's menu-bar icon vanished for a tap refresh plus a full download, with no progress, nothing to cancel, and a 900 s watchdog as the only bound;
  • when the tap lagged the release, brew upgrade exited 0 saying "the latest version is already installed", which the script logged as success before reopening the same build.

This design executes nothing, so neither failure has anywhere to happen. It detects, then hands over a string.

The half that makes it safe

It asks what the cask offers, not what the release offers, before saying anything — which is the non-obvious half of Claude Code's behaviour, read out of its shipped binary rather than its docs. A release exists the moment it is published; the tap follows by dispatch with a six-hourly cron behind it. Comparing against the release would offer a command that prints "already installed" and exits 0.

Order is ownership → location → version → asset, and ownership going first is load-bearing: brew install --cask --appdir ~/Apps is .elsewhere, and asking location first sent an ordinary cask install to a dead-end refusal when the brew command was exactly right for it.

Accepted trade-off, chosen deliberately: during the tap's lag a brew user is told 已是 Homebrew 提供的最新版本 with no command and no in-app fallback. That makes AGENTS.md's dispatch-token check more load-bearing, not less.

Cost control

Ownership is a directory scan and a readlink — no subprocess. The implementation bb07783 deleted asked brew itself: a login-shell probe up to 8 s, then brew list --cask up to 20 s, per prefix, on the shared spawn gate, every time the sheet opened. The tap read is off that gate with a 10 s bound and its own queue, because 40 s of network in front of every upload would have been a worse regression than the 28 s that was removed.

The tap's local clone is consulted first and settles the common case for free.

Two defects this fixes that existed before it

  • UpdateSheet told every refused user to run a cask upgrade — unconditionally, including non-brew installs, for whom it fails with Cask 'gitpic' is not installed.
  • build-app.sh reused whatever target/release/gitpic existed, and its only staleness guard compared versions. Measured: a binary from the previous evening, still 0.20.9, was embedded into an 0.20.9 bundle without the update cask subcommand added since, and nothing failed. Releases were never exposed (CI builds the CLI in its own step first, from a clean checkout); local builds were, which is where check-self-update.sh builds the app it tests the real updater with.

Review pass

A full review of the diff found 15 issues, all fixed in the last four commits. The two that mattered most were bugs that silently disabled work in this PR:

  • the local tap short-circuit was dead on every Intel Mac. Taps hang off HOMEBREW_REPOSITORY, not the prefix: on Intel the Caskroom is /usr/local/Caskroom but the clone is at /usr/local/Homebrew/Library/Taps. Ownership still worked, so the only symptom was a request paid on every sheet open that the file on disk could have answered — and 「暂时读不到」 for an offline user whose answer was sitting in a file. The fixture wrote the Apple Silicon layout by construction, so it had encoded the bug.
  • a CRLF cask parsed as nothing at all. "\r\n" is a single Swift Character, so split(separator: "\n") returned the whole file as one piece — measured, 1 piece against Rust str::lines()'s 3 on identical bytes, against a doc claiming the two parsers followed the same rules.

Also fixed: status_error describing the release feed for a tap failure; a 10 s bound that was really 13 s and had no cancellation, so a wedged child outlived the sheet; a timeout arriving as a contentless decode failure; homebrewUpToDate rendering 「已是 Homebrew 提供的最新版本(X)」 from the bundle's version, which is false for anyone who self-updated ahead of the tap; the once-per-version banner being spent inside the tap-lag window and never firing again; UpdateAction::Cask missing from the global-flag table, repeating verbatim an omission that table's own comment records; and a check-self-update.sh guard that grepped an append-only machine-wide log and so could never fail.

Verification

  • Rust 255 unit + 28 integration; Swift 291 in 37 suites; clippy --all-targets and fmt clean; check_manifests.py and release_notes.py --self-test pass.
  • Verified on a machine that has the cask installed: the embedded CLI answers {"ok":true,"cask":"gitpic","version":"0.20.9"} from inside the bundle.
  • The canonicalize() premise measured directly: invoked through a symlink, current_exe() reports no .app ancestor and canonicalize() reports one.
  • Homebrew's greedy behaviour re-read from upgrade.rb:70 and cask.rb:433/435/443.

Not yet done, and deliberately last: removing auto_updates true from the tap. Its correctness depends on this app already refusing to self-install over a cask bundle; reversed, there is a window where brew's receipt comparison and the app's installer both write /Applications/GitPic.app.

Not observable on this machine yet: the installed GitPic is 0.20.9, the latest release, so update_available is false and the sheet never opens. The three Homebrew outcomes rest on unit tests until a newer release exists.

fl509132 added 16 commits August 29, 2026 10:01
…ly wants

`gitpic update` printed the cask's command and the formula's side by side and
left the reader to pick, on the grounds that this process could not tell them
apart. That was true of the code and not of the machine. It also had no answer at
all for the two installs that are neither: a `GitPic.app` someone installed from
the DMG by hand, and a `cargo install --git` build. Those readers were handed two
commands, both of which fail.

`install_source` tells them apart from the path, and the whole thing turns on one
step that is easy to leave out. The cask links `HOMEBREW_PREFIX/bin/gitpic` at the
copy inside the app bundle, so the commonest install of all is invoked *through a
symlink* — and on Apple platforms `current_exe()` is `_NSGetExecutablePath` with
no canonicalisation, which returns the link rather than its target. Measured on
this machine: `/opt/homebrew/bin/gitpic` has no `.app` ancestor, while its
realpath `/Applications/GitPic.app/Contents/Resources/gitpic` does. So the naive
version misreads the single most common case, and both answers it falls to are
wrong ones — `Unknown`, which prints the same unhelpful thing as before and buys
nothing, or `Formula`, which prints `brew upgrade gitpic_cli` and fails with "no
available formula", the exact mistake the two-command note existed to avoid.
`std::env::current_exe`'s own docs decline to promise either behaviour, so
`detect` canonicalises rather than depending on which one you get.

A bundle is then refined by asking whether any `Caskroom/gitpic/*/GitPic.app`
resolves to it. That is the reverse of the test Claude Code can use on itself —
its binary really lives in the Caskroom, so `execPath()` contains `/Caskroom/`,
whereas gitpic's cask uses an `app` stanza that *moves* the bundle out and leaves
a symlink pointing back. Evidence is therefore a link that resolves to us, which
also makes the check correct at any `--appdir`.

**`gitpic` is not on crates.io** — verified against the API, `crate 'gitpic' does
not exist` — so the cargo hint carries `--git`; a bare `cargo install gitpic`
would have been a command that cannot work. The URL comes from
`CARGO_PKG_REPOSITORY` so it cannot drift from Cargo.toml.

Also retracts a claim in `cli.rs` that was already false: "the app is a Homebrew
cask signed ad-hoc, so there is no signature chain to verify a self-downloaded
replacement against" was given as the reason `gitpic update` does not install.
`Updater`'s header retracts it — the installer verifies the SHA-256
`api.github.com` reports for the asset, which is the same trust root a cask's own
`sha256` rests on, so ad-hoc signing never separated the two. The reason that
holds is that for a cask or a formula the right actor is brew.

Not verified end to end: the composition `current_exe()` → `canonicalize()` →
`CaskApp` cannot be exercised without writing into the real
`/Applications/GitPic.app`, so it rests on the unit table over synthesized paths
plus the realpath measurement above.
"There is a new release" and "brew can install it" are different facts, and the
gap between them is why the Homebrew path was deleted in bb07783. The app learns
a release exists the moment it is published; the tap follows by dispatch with a
six-hourly cron behind it, and AGENTS.md records that the dispatch token has
expired before. In that window `brew upgrade --cask gitpic` prints "the latest
version is already installed" and exits 0.

Claude Code 2.1.251 solves this by asking the cask before it says anything —
read out of the shipped binary rather than the docs: it fetches what the cask
offers, then prints "Update available: 2.1.251 → R" *with* the command, or
"Claude is up to date!" with no command at all. The command is never handed over
speculatively. `gitpic update cask` is the half of that this project was missing.

It has to live here rather than in the app because `GitPicCore` never talks to
api.github.com — everything network-shaped goes through this binary — and because
of the rule this module already enforced for the release feed. That rule binds
harder here: the version this reads is shown in the update sheet *next to a
command the user is being told to type into a terminal*, so a settable origin
would be a way to put an attacker's argument for running something in front of
the user inside GitPic's own window. `TAP_REPO` and `TAP_CASK_PATH` are
constants, pinned by the same test as `RELEASES_REPO`.

`Attempt` and `fetch` became generic and the anonymous-retry dance moved into
`get_json`, shared by both lookups. Not for tidiness: the subtle part is the
third branch, where an anonymous retry has no credential left to reject, and
copying that reasoning into a second call site is how the copy ends up as
`unreachable!()` in a background check. All 23 existing release tests pass
unchanged, `a_rejected_credential_retries_anonymously` included.

`cask_version` is deliberately not a Ruby parser. It reads the first `version`
stanza that is a plain quoted literal parsing as three numbers and answers `None`
for everything else — an interpolation, `version :latest`, and in particular
Homebrew's comma-separated `version "1.2,345"` form (`Cask#version.csv`). `None`
reaches the app as "could not tell", which shows the command with a caveat. A
guess there could show 「已是最新」 over a real update, which is the one outcome
that hides a pending upgrade behind a reassuring sentence.

The stub test encodes its base64 **wrapped**, because that is what the Contents
API sends — it breaks at column 60 and the decoder rejects the newlines, so an
unwrapped fixture would have tested a reply this code never receives.

Verified against the real tap: `update cask` reports 0.20.9, which is what
`Casks/gitpic.rb` declares. 253 unit + 28 integration tests, clippy and fmt clean.

The cask and formula tokens moved to `release` so there is one spelling of each;
`install_source` imports them rather than repeating them. Also corrects
`main.rs`'s claim that the update path "reads no credential — the endpoint is
public", which stopped being true in 0.20.5.
No call sites yet — the route that will use this lands separately. This is the
detection on its own, with the tests that could not exist while the answer came
from a subprocess.

**Claude Code's one-liner does not port, and the reason is the cask stanza.** It
detects a package-managed install with `execPath().includes("/Caskroom/")`, which
works because its cask ships a `binary` artifact: the executable stays in the
Caskroom and `bin/claude` links to it. GitPic's cask uses `app "GitPic.app"`,
which *moves* the bundle out and leaves a link pointing back — measured on this
machine:

    /Applications/GitPic.app                          (a real directory)
    /opt/homebrew/Caskroom/gitpic/0.20.9/GitPic.app -> /Applications/GitPic.app

`Bundle.main.bundleURL` therefore never contains `/Caskroom/`, so the evidence has
to be read in the other direction: a Caskroom link that resolves *to us*. Verified
against the real install — the link resolves to `/Applications/GitPic.app` and
matches.

That direction is not merely a workaround, it is the more correct question.
`brew list --cask gitpic`, which is what bb07783 deleted, answers about the
*machine*: true whenever a cask is installed anywhere, including when the copy
asking is a different GitPic at a different path. Reading the link answers about
the bundle. Two consequences are pinned as tests: a Caskroom entry pointing at
some other bundle is not evidence about this one, and a cask installed at a custom
`--appdir` is still the cask's — that second one is the case that gets a dead-end
refusal today, since `location(of:)` calls anything outside the two Applications
directories `.elsewhere` when `brew upgrade --cask gitpic` is correct for it.

Cost, which is the other half of why the old version had to go: a directory scan
and a readlink. Nothing spawns. The deleted probe cost up to 8 s for a login shell
plus up to 20 s per `brew list --cask`, per prefix, on a serial queue, every time
the sheet opened. And because it is conclusive by construction — a directory holds
such a link or it does not — there is no third "could not tell" state, which is
what keeps `Route.unavailable`'s `retryable` flag dead.

A dangling Caskroom link is deliberately *not* ownership: `fileExists` follows the
link, so an entry left behind after someone deleted the bundle by hand is skipped
rather than resolved to a path that is not there.

`localTapVersion` reads the clone Homebrew already keeps
(`<prefix>/Library/Taps/tarnish233/homebrew-tap/Casks/gitpic.rb`, confirmed present
on this machine with one parseable `version` line at line 2). It is a **lower
bound** on what `brew upgrade` would find and never an upper one, because the clone
is only as fresh as the last `brew update` while `brew upgrade` auto-updates first.
That asymmetry is what makes it worth reading first: if it already names something
newer than the bundle, no request is needed at all; `nil` means "ask something
authoritative", not "up to date".

`declaredVersion` mirrors `release.rs`'s `cask_version` row for row, including the
refusal of Homebrew's csv `version "1.2,345"` form — the app reads the local clone
with one parser and the network copy with the other, and a string accepted by one
and refused by the other would make the answer depend on which path was taken.

The Homebrew-shaped fixture moved out of `SelfUpdateInstallTests` into a shared
`HomebrewShape`, so the shape measured off one real install is described once and
both suites build from it.

274 Swift tests in 37 suites pass, the refactored swap test included.
…bound

The app cannot ask GitHub itself — every network-shaped call goes through the CLI,
and `release.rs` requires the origin to be a compile-time constant because what
comes back is rendered in GitPic's own window. So this is a `gitpic update cask`
subprocess. What matters is where it runs.

**Not on `gate`.** The gate serialises every invocation and has no timeout, by its
own admission ("a wedged CLI holds the gate until it exits"). The CLI bounds one
attempt at 20 s request / 10 s connect and retries once anonymously when GitHub
refuses the credential, so the worst case is around forty seconds — and on `gate`
that is forty seconds in front of every upload, incurred on the sheet-open path.
Deleting twenty-eight seconds of exactly that shape is what bb07783 was for.
Putting forty back would be the same regression wearing a different hat.

`loginEvents` is the precedent and the justification is strictly weaker here: a
login is off the gate because it writes `auth.toml`, which no other command
writes. A read-only lookup writes nothing at all.

Coming off the gate is also why the bound belongs on this side. The gate was the
only thing incidentally keeping two spawns apart, so `run` and `runJSON` now take
`on:` and `timeout:` together — a caller overrides both or neither. Ten seconds,
shorter than the CLI's own ceiling on purpose, so this side is the binding one and
a wedged child cannot outlive the sheet that asked for it. A timeout is not a
failure to report: it means the tap could not be read, which the caller has an
answer for.

`TapCask` mirrors the Rust struct. `version: nil` means the cask was read and
declares nothing comparable; a thrown error means it was not read at all. Two
different facts with the same consequence, deliberately not merged here so the
caller decides once in one place.

Also corrects `updateCheck`'s doc, which still said it "needs neither config nor
credential — the releases endpoint is public". It reads the image-host token when
there is one to raise the rate limit; what survives is that every way that can
fail collapses to an anonymous request, so the claim that matters — it works on a
machine whose config is broken — still holds.

274 Swift tests still pass; `run`'s new parameters both default to today's
behaviour, so no existing caller changed.
…talling over it

The breaking half. `route` takes a fourth fact and answers three new ways, and the
four exhaustive switches that read it all had to be told about them — which is the
point of their having no `default:`.

**Ownership is asked before the location, and that order is load-bearing.**
`brew install --cask gitpic --appdir ~/Apps` is an ordinary thing to do and
produces a bundle `location(of:)` calls `.elsewhere`. Asking location first sends
that user to 「这份 GitPic 在 …」 — a dead end — when `brew upgrade --cask gitpic`
is exactly right for them. Claude Code is package-manager-first for the same
reason: whether *we* could install locally is irrelevant when somebody else owns
the install. `casksOutrankTheLocationRule` pins it, and it is the deleted
`caskInACustomAppdirIsSentToTheReleasePage` inverted.

**The Homebrew branch compares against the cask, never the release**, and must not
reuse the version gate below it. `latest` is the release's; for a brew user the
base is what the tap offers. Bundle 0.20.9 with release 0.20.10 and tap 0.20.9 is
`homebrewUpToDate`, which `mine < theirs` would have waved straight through into an
install. `latest` is not consulted on that branch at all, and neither is `asset` —
which is also why the branch sits above both, since `installableAsset()` derives a
filename from `latest` and would otherwise mint a refusal about a missing DMG for
someone who was never going to download one.

`homebrewUpToDate` offers no command, deliberately, and this is the cost of the
policy rather than an oversight: during the tap's lag `brew upgrade --cask gitpic`
prints "the latest version is already installed" and exits 0, so handing it over
would be handing over a command that does nothing. A brew user in that window is
told to wait. The app does not install over a cask-managed bundle to fill the gap.

`retryable` stays dead, but its stated premise needed splitting rather than
deleting: `route` is still pure — the cask fact is a caller-computed parameter —
and what is no longer pure is the orchestration, which lives in `CaskOwnership`.
A lookup that fails becomes `Offer.unknown`, one of the Homebrew cases, not a
refusal.

The orchestration is in `GitPicCore` and not in `Updater` on purpose:
`Updater.swift` records that `swift test` cannot import `GitPicApp`, so all three
outcomes would have been untested there. `askTap` is injected, so they are.

**Two live bugs fixed on the way.** `UpdateSheet` appended
「或在终端运行 `brew upgrade --cask gitpic`」 to *every* refusal, so a copy running
from `~/Downloads` on a machine with no cask was told to run a command answering
`Error: Cask 'gitpic' is not installed`; that sentence now exists only under the
Homebrew cases. And `resolveUpgradePath`'s cache allowlist correctly omits the new
cases — documented rather than left to be "fixed", because the *tap* can move
without the report moving, so a cached `homebrewUpToDate` would keep saying
「已是最新」 with no command for the life of the process.

`refusalsAreWrittenForTheWindow` was **not** weakened. Its ban on a command line in
any `reason` is unchanged and still passes: the one deliberate command string is the
Homebrew cases' own `command` value, which the sheet draws as a monospaced row, and
a new row pins that the prose half stays a Chinese sentence with no flag in it.

`check-self-update.sh` now asserts the log recorded "not cask". Its copy lives in
`~/Applications` with no Caskroom entry pointing at it, so it belongs on the
self-install branch — but that is a real question now, and without the assertion a
change that flipped it would surface as a 60 s "never settled" timeout rather than
as the reason.

285 Swift tests in 37 suites, up from 267.
The mirror image of 5433f9d, which retired four claims the *deleted* branch left
behind. Same method — grep the whole tree for the assertion, not just re-read the
files this branch touched — because the stale sentences are load-bearing here and a
reader who believes them will make a wrong change.

Rewritten rather than deleted, since in each case the argument still has a live
half: `Updater`'s header ("One path now, for every install"), `UpdateSheet`'s
("There is one action now") and its alert's retraction paragraph, `ToolDiscovery`'s
"nothing asks about brew any more", `GeneralPane`'s "who owns the bundle stopped
being a question the app asks" — which was corrected once already earlier in this
work and needed correcting again — plus both READMEs, which told every reader that
a Homebrew copy is self-updated.

**AGENTS.md's "Two cask stanzas" block is now about one stanza, and two of its
claims were wrong before this change rather than because of it.**

`auto_updates true` never governed `brew upgrade --cask gitpic`. A named cask takes
the `outdated?(greedy: true)` branch (`cask/upgrade.rb:70`), which skips the
`auto_updates` comparison entirely and falls through to plain receipt inequality
(`cask/cask.rb:442`) — so the stanza only ever affected a bare `brew upgrade` and
`brew outdated`. The old text's "`brew upgrade` still upgrades a bundle that is
genuinely behind and correctly does nothing once the app has updated itself" was
therefore false for the explicit form all along. And
`HOMEBREW_UPGRADE_AUTO_UPDATES_CASKS`, cited there as "defaults on", is marked
`odeprecated` with `replacement: "the default behaviour"` (`env_config.rb:745-755`).

The section now records the removal order — the stanza comes out *after* the app
that defers to brew ships, never before — and the one transitional hazard, which is
a CHANGELOG line rather than code: a 0.20.9 cask user who self-updated has a bundle
ahead of brew's receipt, so a bare `brew upgrade` can reinstall an older tap version
over it. Narrow, self-healing after one upgrade, and impossible for the app to cause
since `route` compares the tap against the installed bundle.

`uninstall quit:` is restated as load-bearing rather than a courtesy: it is what
makes the command the app now hands out safe, and for an `.accessory` app brew's
reopen is the only thing that restores the menu-bar icon.

Both READMEs now describe two cases instead of one, and say why the app asks the tap
before offering a command. CHANGELOG entries in both languages, including the
Homebrew section with the removal order and the transitional hazard.

Verified: `.github/scripts/check_manifests.py` passes, `release_notes.py
--self-test` passes, and extracting 0.20.9's notes still stops at its own
`release-notes-end` marker rather than bleeding into the new Unreleased section.
253 + 28 Rust tests and 285 Swift tests pass.
… target/

`build-app.sh` reused `$TARGET_DIR/release/gitpic` whenever the file existed, and
the version check below it was described as what made that safe: "the one runtime
check that the merged version is real rather than asserted", guarding against a
stale binary that "would otherwise ship silently inside an app stamped with a
version it does not contain".

It compares *versions*, so it catches a leftover from before a version bump and is
blind to a leftover from earlier the same day.

Measured, on this change: a `target/release/gitpic` built the previous evening —
still 0.20.9, matching Cargo.toml — was embedded into an 0.20.9 bundle whose
`Contents/Resources/gitpic update --help` had no `cask` subcommand, one that had
been added hours earlier. The build printed `cli 0.20.9 (embedded)` and exited 0.

The failure mode is quiet in the direction that hides it. A missing subcommand
surfaces to the app as `RunFailure.undecodable`, which `CaskOwnership.verdict` maps
to `Offer.unknown` — so every Homebrew user would get the upgrade command with a
「暂时读不到」 caveat instead of the real comparison, forever, with nothing failing.

`cargo build` is incremental, so building unconditionally is a no-op when the binary
is current; the reuse bought nothing worth this. The version check stays for the case
it can actually decide — an explicit `GITPIC_BIN` pointing at another build — and its
comment no longer claims to cover more than it does.

Scope: `release.yml` was never exposed, because it runs `cargo build --release
--locked` in its own step before calling this (`release.yml:202`, then `:207`), and
CI's checkout has no `target/` at all. The machine this bites on is a developer's —
which is also where `check-self-update.sh` builds the app it exercises the real
updater against, so a stale CLI there means testing the updater against a bundle
that is not the one under development.

Verified after the fix: the embedded CLI has `update cask` and answers
`{"ok":true,"cask":"gitpic","version":"0.20.9"}` from inside the bundle.
It was untracked in the working tree before this work started and has nothing to do
with the update path; a `git add -A` in the docs commit swept it in. Removed from
the index only — the file stays on disk, untracked, exactly as it was found.
…its own failures

Three defects from the review of this branch, all in code added by it.

`classify` asked whether `Cellar` or `.cargo` appeared *anywhere* in the canonicalised
path. That is true of `/Users/x/Cellar/gitpic`, of a tarball unpacked under a directory
somebody happened to name `Cellar`, of a restored `~/backup/.cargo/bin/gitpic`, and of a
second Homebrew's Cellar this machine cannot upgrade from. Each then printed a command
that fails — `brew upgrade gitpic_cli` answers "No available formula with the name", and
the cargo line would rebuild a different binary than the one running. That is exactly the
mistake the module header says the old two-command note existed to avoid, now printed with
confidence instead of offered as one of two. Both tests are anchored to a root: the
prefixes for `Cellar`, and `CARGO_HOME` (or `~/.cargo`) for cargo. `default_prefixes` also
honours `HOMEBREW_PREFIX`, which matters far more to the CLI than to the app — `brew
shellenv` exports it, so a terminal at a non-default prefix almost always has it.

`status_error` was written when this module had one endpoint and hardcoded the release
feed into three arms. Generalising the client for the tap lookup left them behind, so a
404 on `Casks/gitpic.rb` reported `tarnish233/gitpic has published no releases yet` —
wrong repository, wrong resource, wrong failure, from a command that never touched the
release feed — and every consumer keying `RemoteNotFound` or `AuthFailed` to the feed
began receiving them from the tap too. `what` and the 404 subject now travel together in
an `Endpoint`, so the one log line a maintainer reads distinguishes "the tap moved" from
"GitHub is down". The likeliest 404 is named: Homebrew shards third-party casks into
`Casks/g/gitpic.rb`.

`UpdateAction::Cask` arrived with no row in the global-flag table and no parse test —
repeating verbatim the omission that table's own doc comment records about `update check`.
`gitpic --json update cask` is the exact invocation `GitpicRunner.tapCask` makes, and when
it stops parsing the app shows every cask user the command with a 「暂时读不到」 caveat and
nothing fails, so a green suite would have been the only signal.

Also retires `commands/update.rs`'s "nothing here reads `config.toml` or the credential",
false via `best_effort_token`, and corrected in two other files by this same branch.
…ng when it cannot

Four defects, two of which silently disabled things this branch added.

**The local short-circuit was dead on every Intel Mac.** Taps hang off
`HOMEBREW_REPOSITORY`, which is not the prefix. Read out of Homebrew's own `bin/brew`: the
repository starts equal to the prefix, is re-derived from the `bin/brew` symlink target
when there is one, and an x86_64 install then forces the prefix back to `/usr/local`. So
on Apple Silicon `bin/brew` is a real file and everything is under `/opt/homebrew`, while
on Intel the Caskroom is `/usr/local/Caskroom` but the clone is at
`/usr/local/Homebrew/Library/Taps`. Reading only `<prefix>/Library/Taps` found nothing
there — and `detect` still worked, so the failure was invisible: the free short-circuit
simply never fired, every sheet paid for a request the file on disk could have answered,
and an offline Intel user was told 「暂时读不到」 while the answer sat in a file. Both
layouts are tried now. The fixture wrote the Apple Silicon layout by construction, so it
could not have caught this; it takes a `repositorySubpath` instead.

**A CRLF cask parsed as nothing at all.** `"\r\n"` is a single Swift `Character` and is not
equal to `"\n"`, so `split(separator: "\n")` returned the whole file as one piece —
measured, one piece against `str::lines()`'s three on the same bytes. The line never began
with `version `, the parser returned nil, and the claim to follow "the same rules as
`release.rs`'s `cask_version`" was false for any clone with `core.autocrlf` set.
`whereSeparator: \.isNewline` and `.whitespacesAndNewlines`, with a fixture axis for it.

**`verdict`'s catch discarded the error** while `Offer.unknown`'s own doc promised "The
real error is logged". Six distinct failures — no runner, a timeout, a rate limit, a 404 on
the cask path, undecodable output, a CLI too old to have the subcommand — produced
byte-identical output with nothing to diagnose from. The caption stays constant; the cause
goes on the record via `RunFailure.message`.

**A timeout arrived as a decode failure with no text.** `ChildProcess.run` does not throw
on timeout: it reports `timedOut` and `128 + SIGKILL`, so empty stdout failed to decode and
surfaced as `.undecodable(status: 137, raw: "")`, rendered as 「看不懂 gitpic 的回答(退出码
137,没有输出)。可能装的是旧版本。」 — naming the wrong cause entirely. `RunFailure.timedOut`
is its own case. And `run` had no cancellation handling, so the claim that a wedged child
cannot outlive the sheet was aspirational: cancelling the awaiting task neither ended the
await nor touched the child. The bounded path now terminates it, using the same
`LoginChild` holder `loginEvents` uses for the same spawn race. Scoped to bounded callers
on purpose — killing an upload mid-`PUT` would trade a slow commit for a half-finished one.

Smaller, from the same pass: `detect` compared `URL` (i.e. `absoluteString`, where a
directory hint alone can make the same path unequal) instead of `.path`, which the sibling
`location(of:)` already does; `defaultPrefixes` honours `HOMEBREW_PREFIX`; "Conclusive by
construction" is replaced by the truth, since a cask under an unlisted prefix is a false
negative — self-healing, being the same receipt-inequality shape AGENTS.md documents, but
not nothing. Two doc claims retired: a pinning test that did not exist (it does now) and a
`///` run into the line above it. New tests cover the wire shape, which nothing decoded.
…ion they already have

`homebrewUpToDate` carried only `installed`, which the sheet rendered as 「已是 Homebrew
提供的最新版本(X)」 — a statement about what *Homebrew* provides, built from the *bundle's*
number. The case is reached whenever the bundle is not older, so it covers two situations,
and in the second that sentence is false.

The second is the transition this branch's own changelog spends a paragraph on: a cask user
who self-installed 0.20.10 while the tap still declares 0.20.9. They were told Homebrew
provides 0.20.10 and to wait for a version they were already running. `offered` now travels
alongside, and the sheet has two sentences — one for the tap merely lagging, one for the
bundle being ahead. The existing `behindTap` row pinned the mislabel rather than catching
it, so it now pins both numbers and says why.

**The banner was also spent in exactly the window where the sheet offers nothing.** It is
posted when the check finds a release; which upgrade is on offer is only worked out later,
when the sheet opens. So a Homebrew user inside the tap's lag got their one notification
for a version the sheet then declined to install, and because `announcedVersion` is
persisted no further banner for that release could ever fire — including after the tap
landed and `brew upgrade` would have worked. Before this policy the single notification was
always actionable, because the app installed for everyone. `forgetAnnouncement(of:)` drops
the record for `homebrewUpToDate` only; `homebrewUnverified` hands over the command, so its
banner was actionable and stays spent. Worst case is one banner per daily check while the
tap lags, which is the right trade: the tap normally follows within minutes and always
within six hours, and when it lags for days — an expired dispatch token, three releases,
per AGENTS.md — a daily reminder is precisely the signal that was missing.

Two overclaims retired. The cache-allowlist comment said the fall-through prevents a stale
「已是 Homebrew 提供的最新版本」 "for the life of the process"; `resolveUpgradePath` has one
caller, `UpdateSheet`'s `.task(id:)`, so what it actually buys is a fresh answer per sheet
*opening* — a sheet left open across the tap catching up still shows the old sentence. That
limit is now stated rather than implied. And `theHandOverCarriesTheCommandOutsideTheProse`
asserted the no-flag/Chinese property against the reason string the test itself supplied, a
tautology that left the four captions `route` and `verdict` really mint covered by nothing;
both pairs are now exercised where they are written.

Also fixes an editing accident: inserting `homebrewExplanation` above `installProgress` had
reassigned that function's doc comment (about 取消 and Escape) to a view with no buttons,
left `installProgress` undocumented, and joined its signature to its body on one 142-column
line.
…et's claim true

The "not cask" assertion added by this branch grepped the whole of `GitPic-update.log`.
That log is append-only, machine-wide, and also written by the installed
`/Applications/GitPic.app` — so on any machine that had run the script once, or ever opened
the update sheet on a non-cask copy, the assertion could never fail again. A guard that
cannot fail is worse than none: the regression it exists for would sail past it, click
button 1 (now 复制升级命令), copy a string, and time out saying nothing was replaced —
exactly the uninformative failure it was added to replace. Scoped to this run's bytes with
`LOG_MARK`, which the script already computes for this purpose and uses correctly 150 lines
above.

The release-notes bullet claiming "you are never given a command that would do nothing" is
rendered inside the app's own update sheet, and `homebrewUnverified` contradicts it in every
case where the check did not happen — offline, rate-limited, no CLI located, an unparseable
version — all of which hand over the command anyway. Reworded to describe the case that is
actually true of, `homebrewUpToDate`. Both READMEs gain the missing half: when the tap
cannot be read the command is still offered, with a note that it went unchecked. The bullets
were also over AGENTS.md's own stated budget (~40 chars 中文, ~100 English) at 77/130; they
are inside it now.

Also: the pre-build in `check-self-update.sh` is still required but no longer for the reason
its comment gave. `build-app.sh` always builds now, so a stale binary is not what this
prevents; what it prevents is the version rewrite above leaving `Cargo.lock` describing the
old version, which `build-app.sh`'s `--locked` refuses to update. Verified by rewriting the
version and watching `cargo build --release --locked` fail with exactly that error. And
AGENTS.md's `src/` map gains `install_source.rs`, absent since it was added, with the
`release.rs` entry extended to mention the tap lookup it now also holds.
…rgo's root there

`a_caskroom_link_is_what_makes_a_bundle_the_casks` calls
`std::os::unix::fs::symlink`, which does not exist on Windows — so `src/install_source.rs`
did not compile there at all, from the commit that introduced it. `cargo clippy
--all-targets -- -D warnings` failed with two `E0433: cannot find `unix` in `os``. CI found
it; my local runs could not, because they were all macOS.

Gated to `#[cfg(unix)]` rather than ported to `std::os::windows::fs::symlink_dir`: the
subject is a Homebrew cask installing a macOS app bundle, so there is nothing for the
Windows build to learn from it. Everything else in the module is path arithmetic and stays
covered on every platform.

Verified by type-checking the module against `x86_64-pc-windows-msvc` — cross-compiling the
whole crate is not possible here (`ring` wants a Windows C toolchain), but `rustc
--target x86_64-pc-windows-msvc --test --emit=metadata` type-checks and passes clean, which
is the half that was failing.

While there: `cargo_root` read only `HOME`, which is usually unset on Windows, so a Windows
`cargo install` was classified `Unknown` and pointed at the release page. It falls back to
`USERPROFILE`. Not a crash either way, but `Cargo` is the one source of the five that means
anything on Windows — the other four are Homebrew and macOS bundles — so it is the one worth
getting right there.
…t's answer

Two findings from a second review pass, both verified before changing anything.

**The cancellation handler I added last commit was a regression, and it is reverted.**
`AppModel.resolveUpgradePath` loops on purpose: when a check lands while the tap probe is
running the generation moves, the in-flight call notices and asks again — its comment says
"the probe already running is the one that has to notice". But moving the generation is
exactly what makes `UpdateSheet`'s `.task(id:)` tear that task down, so the second ask is
made from a task that is already cancelled. The design depends on
`withCheckedThrowingContinuation` ignoring cancellation, which is the opposite of what a
Swift reader expects — and is the trap I walked into.

Measured both ways with a standalone reproduction of the shape: with the handler, the first
probe is killed mid-flight **and the re-query is killed before it starts**, because `onCancel`
fires immediately on an already-cancelled task; without it, both complete. Since
`CaskOwnership.verdict` turns every failure into `Offer.unknown`, the handler made a new
report resolve to 「暂时读不到 Homebrew 提供的版本」 with a caveat instead of a real version
comparison. It self-heals on reopen — `homebrewUnverified` is not in the cache allowlist — but
until then it is wrong information.

What the handler was meant to buy does not justify that. It came from a review finding whose
concrete complaint was that `resolvingUpgradePath` staying true makes a reopened sheet show a
buttonless spinner; the probe does still complete and write its answer, so that spinner is
honest, and an honest 「正在确认升级方式…」 for the length of a 10 s bound beats a wrong
sentence. The bound, on its own queue and blocking nothing, is what keeps a wedged child
harmless — the docs on `run` and `tapCask` say that now instead of claiming cancellation does.

`TapProbeCancellationTests` is the tripwire, in `QuitPathContractTests`' idiom and for its
reason: the interleaving needs `AppModel`, which `swift test` cannot import. It scans
`GitpicRunner.swift` for `withTaskCancellationHandler`, `checkCancellation` and
`Task.isCancelled`, exempts whole-line comments so the explanations stay legal, and asserts
the bound it relies on instead is still present and still off the gate. Verified to fail on a
compilable violation, naming the line — not just to pass today.

**Install-source detection was still a directory too wide.** Anchoring to the roots last
commit fixed `/Users/x/Cellar/gitpic`, but `<prefix>/Cellar` still matches any formula's keg,
and the whole of `CARGO_HOME` includes `registry/src` and `git/checkouts` — one buildable
source tree per dependency ever fetched, thousands of them on this machine. A
`target/release/gitpic` built in one was reported as a `cargo install`, and
`cargo install --force` would rewrite `CARGO_HOME/bin/gitpic`: a different file from the one
running. Now `<prefix>/Cellar/gitpic_cli/…` and a parent directory equal to
`<cargo_root>/bin`, which also means the executable name is not spelled here and Windows'
`gitpic.exe` needs no case of its own.
… arrives in

`detect` canonicalises `current_exe()` and then handed `classify` anchors built straight out of
the environment. Every comparison assumed the two spellings agree, and there are two ways they
do not.

**Windows, unconditionally.** `std::fs::canonicalize` returns an extended-length `\\?\C:\…`
path there, so `exe.parent()` can never equal a `C:\Users\x\.cargo\bin` built from
`CARGO_HOME` — every ordinary `cargo install` was classified `Unknown` and sent to the release
page instead of being given `cargo install --force --git …`. And `Cargo` is the one source of
the five that means anything on Windows, the other four being Homebrew and macOS bundles, so
that is the whole feature gone on that platform. Taken as documented behaviour, not measured:
there is no Windows here to measure on, and I am not going to imply otherwise.

**Any platform, when a root is reached through a symlink**, which *is* measurable here.
Canonicalising the executable resolves the link while the raw anchor still names it.
`anchors_are_compared_in_the_same_spelling_as_the_exe` builds a `CARGO_HOME` and a Homebrew
prefix behind symlinks and asserts both still classify; it was written before the fix and
failed with `Unknown` against `Cargo`, so it is pinning the behaviour rather than describing it.
That is also the coverage gap that let this through: every existing row calls `classify`
directly with both sides spelled the same way, so nothing crossed the `detect`/canonicalise
boundary the bug lives on.

`resolved` falls back to the path as given when it cannot be canonicalised, which is the right
answer rather than a compromise — an anchor that does not exist cannot have `exe` underneath
it, so the comparison should fail, and it does, on the raw spelling exactly as before. That is
what keeps the synthesized-path table working.

`cask_owns` needed nothing: it canonicalises the Caskroom link and compares against a bundle
derived from the already-canonical `exe`, so both sides were resolved. The Swift side needed
nothing either — `CaskOwnership.detect` and `SelfUpdate.location(of:)` both resolve both sides.
Checked rather than assumed.
…broke

The regression test for the last commit was `#[cfg(unix)]`, because it builds symlinks — so it
never ran on the Windows runner, which is the platform where the bug was unconditional and
where the whole `Cargo` case was broken. Fixing a Windows bug and testing only Unix is most of
the way to not having tested it.

This needs no symlink and no `cfg`, because `std::env::temp_dir()` is *already* spelled
non-canonically on two of the three platforms CI builds. Measured here: macOS returns
`/var/folders/…` and canonicalises to `/private/var/folders/…`. On Windows the environment
gives `C:\…` and canonicalise returns extended-length `\\?\C:\…`. On Linux `/tmp` is usually
already canonical, so there it asserts the ordinary case still holds. Handing `temp_dir()` over
*without* canonicalising it is the whole point — that is exactly how `cargo_root` and
`default_prefixes` pass their values in.

Verified to catch the bug rather than describe it: with `resolved` removed from both
comparisons, both anchor tests fail, and this one's message prints the divergence it found —
`/private/var/…/cargo/bin/gitpic` against an anchor of `/var/…/cargo`.

Paths are joined a component at a time rather than with embedded `/`, since this one runs on
Windows. Module and tests typechecked against `x86_64-pc-windows-msvc`; `cargo clippy
--all-targets -- -D warnings` run as CI runs it, which is what caught a `cloned_ref_to_slice_refs`
warning in the previous commit's test that a plain `cargo clippy` had let past.
@tarnish233
tarnish233 merged commit c2e8f67 into main Aug 29, 2026
6 checks passed
@tarnish233
tarnish233 deleted the brew-owns-brew-installs branch August 29, 2026 04:52
tarnish233 pushed a commit that referenced this pull request Aug 29, 2026
A Homebrew-managed bundle is handed back to brew instead of being installed over. The
release notes above carry the user-facing half; PR #4 (c2e8f67) carries the mechanism and
the argument for why this is not a revert of what bb07783 deleted — that route *ran* brew
after the app had quit, and both of its measured defects came from that. This one executes
nothing: it asks what the cask offers, then prints a command.

This is the release the tap's `auto_updates true` was waiting on. Removing it before this
shipped would have opened a window where brew's receipt comparison and the app's own
installer both write /Applications/GitPic.app; from here the stanza is a false assertion
about a bundle that no longer updates itself, and comes out next.

Dispatch health checked before cutting, since AGENTS.md records the token dying quietly for
three releases: 0.20.9 published 12:55:09Z and the tap moved at 12:55:18Z, 0.20.8 in ten
seconds. Path 1 is working, which matters more than it used to — a brew user inside the tap's
lag is now told to wait rather than offered an install, so the length of that window is
user-visible.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant