feat(cli): a release cooldown for auto, a skip-this-version answer, and docs

auto now waits min_age_hours (default 24) before installing a release; notify
and prompt are unaffected because they tell a human who can decide. A release
published by mistake, pulled soon after, or published by someone who should
not have been able to is most dangerous in its first hours, and waiting means
this machine is not the one that finds out.

An UNKNOWN publish date counts as too fresh rather than old enough. The
abbreviated npm packument carries no dates, so the other choice would switch
the cooldown off for exactly the users on the cheapest source -- present in
the config, absent in effect. min_age_hours = 0 disables it deliberately.

The prompt gains a third answer. 'No' and 'never tell me about this one' are
different intentions, and with two answers someone who dislikes one release
has to switch the mode off, which then hides the release that fixes it.

The cache records its schema and a foreign value -- including an absent one --
is discarded rather than migrated. Keeping every field optional forever so
older shapes load buys one saved request for a CACHE in exchange for Option
fields that only describe versions nobody runs. Check sources lose their
aliases for the same reason.

Docs: a new cli/updates.md covering the default, every [update] key, the modes
and their refusals, the four sources, the cooldown, skipping, what a check
transmits and where state lives; commands.md rewritten around --mode;
installation.md gains the per-package-manager upgrade table.

Carries #7787, #7784 and #7785 as its base; those collapse out as they merge.

Author: jdalton

changelog.d/A2-update-prompt-auto-and-channels.md

@@ -0,0 +1,105 @@
+### Added
+
+**`prompt` and `auto` update modes now do something, and refuse to do the wrong
+thing.** The previous slice made the modes configurable; this wires them to the
+existing signed self-updater, behind three refusals.
+
+**A package-managed install is never replaced in place.** `perry update`
+overwrites the running executable, which is right for a tarball or `install.sh`
+install and wrong for every managed one: Homebrew, npm, apt and winget each keep
+their own record of what is installed and at what version, and overwriting the
+file underneath leaves that record lying. `prompt` and `auto` now detect the
+owner and name that owner's command instead:
+
+| owner | what Perry says to run |
+|---|---|
+| Homebrew | `brew upgrade perryts/perry/perry` |
+| npm | `npm install -g @perryts/perry@latest` |
+| apt | `sudo apt update && sudo apt install --only-upgrade perry` |
+| winget | `winget upgrade PerryTS.Perry` |
+
+npm gets an extra sentence, because it is the worst case: Perry ships as a
+wrapper package plus a per-platform binary package, so replacing the binary also
+desyncs it from the wrapper that launched it.
+
+**Nothing is offered after a command that failed.** The user is looking at an
+error; a question about upgrading is noise at the worst possible moment, and an
+unattended install would bury the error under progress output. Both active modes
+fall back to a plain notice.
+
+**An unwritable install directory is reported, not attempted.** `install.sh`
+targets `/usr/local/bin`, which is root-owned on a default macOS and most Linux
+boxes. That is now checked *before* anything is downloaded, so the outcome is
+one sentence naming `sudo perry update` rather than a half-finished install. Perry
+never escalates on its own.
+
+**`perry update --mode <off|notify|prompt|auto>`** saves the setting and exits,
+so the one thing people are most likely to change does not require hand-editing
+TOML. It is a read-modify-write through the shared loader, so the rest of the
+file comes back out the way it went in.
+
+**`perry doctor`** now reports the effective mode and, when there is one, the
+package manager that owns the binary — the two questions behind "why did it not
+update".
+
+<details>
+<summary><b>Why the channel detection fails open</b></summary>
+
+Every rule answers "is this definitely managed?", never "is this definitely
+unmanaged?", and an unrecognised layout resolves to self-managed.
+
+That asymmetry is deliberate. Guessing "managed" wrongly would refuse to
+self-update a plain tarball install — the majority case, and the one with no
+other upgrade path. Guessing "self-managed" wrongly costs an in-place update on
+a machine that had a package manager available, which is recoverable by running
+that manager.
+
+The paths are canonicalized before classification, because Homebrew's `perry` in
+`/usr/local/bin` is a symlink into the Cellar; classifying the link rather than
+its target would miss every Homebrew install there is.
+
+apt requires **both** a dpkg file list and a dpkg-owned path, because dpkg does
+not own `/usr/local` — that is `install.sh`'s directory. The path alone would
+misclassify a hand-placed binary; the dpkg list alone would claim a tarball
+install on a machine that also has the `.deb` installed somewhere else. The check
+is a file-existence test rather than a `dpkg -S` subprocess, since this runs on
+the update path of every command.
+</details>
+
+<details>
+<summary><b>Prompting needs stdin, not just stderr</b></summary>
+
+The mode gate already requires stderr to be a terminal. That is not enough to
+ask a question: stdin can be a pipe while stderr is a tty, and reading from it
+would either block the command or take whatever the pipe happened to contain as
+consent. `prompt` degrades to a plain notice when stdin is not a terminal.
+
+`auto` asks nothing, so it does not need stdin — but it does still require the
+command to have succeeded, an unmanaged install, and a writable directory.
+</details>
+
+<details>
+<summary><b>Tests</b></summary>
+
+24 new, all in the required per-pull-request job. The decision is a pure
+function of the mode plus four facts about the machine, so every refusal is
+asserted directly rather than left inside an `if` in the middle of a teardown
+path:
+
+- both active modes downgrade to a notice after a failed command;
+- both refuse on all four managed channels, and name a command for each;
+- both report elevation rather than attempting an unwritable install;
+- `prompt` degrades without stdin while `auto` does not need it.
+
+The channel table covers Homebrew under all three prefixes, npm for global, nvm
+and project-local layouts, apt with and without each half of its rule, both
+winget delivery shapes, and four unrecognised layouts that must fail open.
+Classification splits on both path separators rather than using
+`Path::components`, so the winget cases run on every host instead of only on
+Windows.
+
+Verified end to end: writing `mode` into a real config file that already had a
+`license_key` and an unknown `[update] future_key` left both intact.
+
+`cargo test -p perry`: 914 passed, 0 failed.
+</details>

changelog.d/A3-update-check-sources.md

@@ -0,0 +1,92 @@
+### Added
+
+**Where Perry asks "what is the latest version?" is now a choice.** It used to
+walk one fixed list — an override, the config, Perry Hub, then the GitHub
+releases API — and read a GitHub-releases-shaped document from whichever
+answered first. That is fine while everyone installs the same way, and wrong as
+soon as they do not: an npm user's "latest" is whatever the registry's `latest`
+dist-tag says, and asking GitHub instead can announce a version their package
+manager cannot install yet.
+
+```toml
+[update]
+source = "npm"              # gh-releases | npm | gh-registry | custom
+package = "@perryts/perry"  # npm-shaped sources; defaults to Perry's own
+registry = "..."            # npm-shaped sources; defaults to the public registry
+server = "..."              # the URL for `custom`, and the mirror override
+```
+
+Unset keeps the historical ladder, so nothing changes for anyone who does not
+set it — except on an **npm-managed install**, which now defaults to asking npm,
+because that is the version its own package manager can actually install.
+
+<details>
+<summary><b>The split that matters: checking is not downloading</b></summary>
+
+A check source answers one question and returns a version, a link, a publish
+time and a headline. It does **not** decide where the binary comes from.
+Artifacts and their signed manifest always resolve from the release
+infrastructure, whatever the check source is.
+
+That separation is load-bearing rather than tidy. The manifest — Ed25519 over
+the artifact's digest and version — is what makes a self-update trustworthy,
+and a check source is a URL a user can point anywhere. Letting it redirect the
+download would turn a configuration setting into a way to install an arbitrary
+binary. Whoever answers "what is new?" never gets to answer "what should I
+run?", and there is a test that fails if a source ever leaks into the artifact
+ladder.
+
+The old `get_update_servers` and its private config reader are **deleted**
+rather than left beside the new code, so the compiler enforces that both call
+sites moved. A new abstraction with the old ladder still wired up underneath is
+the shape where four sources exist, pass their own tests, and are never
+reached.
+</details>
+
+<details>
+<summary><b>Credentials go to exactly one of the four</b></summary>
+
+The npm shapes ask for the *abbreviated* packument
+(`Accept: application/vnd.npm.install-v1+json`) — smaller, cacheable, and the
+document npm itself requests for this question. It also avoids GitHub's
+unauthenticated API rate limit, which the old ladder shared with everything
+else on the machine.
+
+The public registry is asked **without credentials**, and a test asserts no
+`Authorization` header is sent: a token there would be a leak, not a
+convenience. GitHub Packages does need one, so that shape reads `GH_TOKEN` /
+`GITHUB_TOKEN` and fails with a sentence naming the fix when neither is set,
+rather than retrying anonymously and reporting the resulting 404 as "up to
+date".
+
+A configured source does not fall back to the ladder when it errors. Somebody
+who said "ask npm" and got a failure wants to hear that, not a version from
+somewhere they never named.
+</details>
+
+<details>
+<summary><b>Tests</b></summary>
+
+11 new, all parsing real response shapes from string fixtures so no network is
+involved:
+
+- a GitHub release document, including that the `v` prefix is stripped;
+- an abbreviated packument, which has no `time` map — so the publish date reads
+  "unknown" rather than being invented, which matters because the release
+  cooldown in the next slice depends on it;
+- a full packument, which does supply it;
+- a custom manifest with only a `version`, and one with every optional field;
+- that each shape **rejects the others' documents** rather than reading a field
+  that happens to be present — a registry answering a gh-releases request must
+  be an error, not a version of `""`;
+- that a scoped package's `/` is percent-encoded, or the registry reads the
+  scope as a path segment and answers 404;
+- that an unknown `source` name falls back instead of failing, so a config
+  written by a newer Perry does not break an older one;
+- that `custom` with no URL is treated as a missing key rather than a default;
+- that an npm install defaults to npm and every other channel keeps the ladder;
+- that no check source can reach the artifact ladder;
+- and both credential rules.
+
+`cargo test -p perry`: 925 passed, 0 failed.
+</details>

changelog.d/A4-update-cooldown-skip-docs.md

@@ -0,0 +1,53 @@
+### Added
+
+**`auto` waits a day before installing a brand-new release.** `min_age_hours`
+defaults to 24 for `auto` and 0 for every other mode, so a notice still mentions
+a release the moment it exists while an unattended install holds off.
+
+A release published by mistake, pulled shortly after, or published by someone
+who should not have been able to is most dangerous in its first hours. Waiting
+costs nothing and means your machine is not the one that finds out. `notify` and
+`prompt` are unaffected — they tell a human, who can decide.
+
+**An unknown publish date counts as too fresh, not as old enough.** The
+abbreviated npm document carries no dates, so treating unknown as "old enough"
+would switch the cooldown off for exactly the people using the cheapest source —
+a protection present in the config and absent in effect. `min_age_hours = 0`
+turns it off deliberately.
+
+**The prompt has three answers.** "No" and "never tell me about this one" are
+different intentions, and with only two answers a user who does not want one
+specific release has to switch the whole mode off — which then hides the release
+that fixes it. Answering the third writes `skip_version`, which suppresses
+exactly that version; the next release is mentioned normally.
+
+**The notice says what the release is,** not only that one exists. Sources that
+carry a title now pass it through, and it prints under the version line at no
+extra request.
+
+### Documentation
+
+New page `docs/src/cli/updates.md`, covering the default behaviour, everything
+in `[update]`, the four modes and their three refusals, the four check sources,
+the cooldown, skipping a version, exactly what a check transmits, and where the
+two files live. `perry update`'s section in `commands.md` is rewritten around
+`--mode`; `installation.md` gains the per-package-manager upgrade table; the
+environment tables in `flags.md` gain `NO_UPDATE_NOTIFIER` and
+`PERRY_UPDATE_MODE`.
+
+<details>
+<summary><b>Tests</b></summary>
+
+Four new, bringing the update surface to 22 in `update_policy`:
+
+- `auto` holds off inside the cooldown and installs past it, while `notify` and
+  `prompt` are never held back;
+- an unknown release age is treated as too fresh, and an explicit `0` still lets
+  it through so nobody is stuck;
+- the cooldown defaults to a day for `auto` only, and an explicit value wins for
+  every mode;
+- a skipped version suppresses itself and **not** the next one, which is what
+  separates it from switching notices off.
+
+`cargo test -p perry`: 929 passed, 0 failed.
+</details>

changelog.d/A5-no-cache-migrations.md

@@ -0,0 +1,33 @@
+### Changed
+
+**The update cache carries its shape, and a foreign shape is discarded rather
+than migrated.** `~/.perry/update-check.json` now records a `schema` number; a
+value this build does not recognize — including its absence, which reads as `0` —
+means the file is thrown away and the next check rewrites it.
+
+This replaces the alternative, which was to keep every field optional forever so
+that older shapes still load. That trade is a bad one for a cache: it buys one
+saved network request in exchange for a set of `Option` fields that only exist
+to describe versions nobody runs, and that nothing ever removes. Bumping
+`CACHE_SCHEMA` is now the whole migration story.
+
+**One spelling per check source.** `github`, `npm-registry` and
+`github-packages` are gone; the names are `gh-releases`, `npm`, `gh-registry`
+and `custom`. A set of accepted aliases is a surface to document and test
+forever in exchange for saving one look at the docs.
+
+An unknown `source` still falls back to the default rather than failing, but for
+a different reason than compatibility: an update check is the wrong place to
+turn a config typo into a hard error.
+
+<details>
+<summary><b>Tests</b></summary>
+
+The test that asserted a pre-throttle cache still loads is replaced by one
+asserting the opposite — that a foreign schema, and an absent one, are both
+recognized as not-ours. Verified at runtime as well: a planted cache with no
+schema, claiming version `99.0.0` and a `last_check` in 2099, was ignored, a
+real check ran, and the file came back stamped `"schema": 1`.
+
+`cargo test -p perry`: 930 passed, 0 failed.
+</details>

changelog.d/REVIEW-update-surface-followups.md

@@ -0,0 +1,55 @@
+### Fixed
+
+Five defects in the update surface, all found in review of
+[#7749](https://github.com/PerryTS/perry/pull/7749) after it had merged.
+
+**The config warning escaped the rules that were meant to silence it.** The
+"unrecognized `[update] mode`" line was printed inside `UpdatePolicy::resolve`,
+before the precedence rules it sits behind had been applied — so it reached
+stderr during `--format json`, in CI, with a piped stderr, and under `--quiet`.
+Those rules exist to keep exactly those runs silent, and the one line whose job
+was to report a config problem was the one line ignoring them. It is now held on
+the policy and emitted at the single point where the run is known to be speaking
+at all.
+
+**The notify interval throttled on time alone, so it swallowed the next
+release.** The documented contract is that the interval throttles repeats of
+*the same* update. Keyed only on a timestamp, it also suppressed a **different**
+version that arrived inside the window — so somebody setting a week-long
+interval to stop being nagged about one release would also have been denied the
+release that fixed it. The cache now records which version it announced, and a
+different version is announced regardless of the interval.
+
+**The interval comparison was signed.** `Duration::as_secs() as i64` goes
+negative for a large enough configured value, and a negative interval reads as
+already-elapsed — so an absurd value would have notified on *every* run instead
+of suppressing. The comparison is unsigned.
+
+**Two `perry` processes could corrupt the cache.** Every write used one shared
+`*.json.tmp`, so two writers each wrote it and each renamed it: the loser's
+rename landed a file the winner was still writing into. Each write now builds
+its own temporary name.
+
+**A refresh could erase a notice recorded while its request was in flight.**
+`fetch_latest_version` read the notice state *before* issuing its request and
+wrote it back afterwards, overwriting anything recorded in between — telling the
+user about the same release twice. The read-modify-write pairs are now
+serialized by a lock file, and the refresh re-reads inside that lock immediately
+before replacing.
+
+<details>
+<summary><b>Tests</b></summary>
+
+Two new contract tests, both sabotage-verified — reverting either fix turns its
+test red:
+
+- a different version is announced regardless of the interval, and never having
+  announced anything counts as "not this version";
+- an enormous interval still suppresses rather than wrapping into notifying.
+
+The existing interval tests are unchanged in intent: they now go through a
+helper that holds the announced version constant, so they still exercise only
+the interval arithmetic.
+
+`cargo test -p perry`: 904 passed, 0 failed.
+</details>

crates/perry/src/commands/doctor.rs

@@ -286,16 +286,34 @@ fn check_runtime_library() -> CheckResult {
 }
 
 fn check_update_available() -> CheckResult {
+    // Say which mode is in effect and who owns this binary. Both are things a
+    // user asks `doctor` about precisely when updates are not behaving as they
+    // expect — "why did it not install" is almost always one of the two.
+    let policy = crate::update_policy::UpdatePolicy::resolve();
+    let channel = crate::install_channel::detect();
+    let context = match channel.upgrade_command() {
+        Some(command) => format!(
+            " (mode: {}; installed by {} — upgrade with `{}`)",
+            policy.mode.label(),
+            channel.label(),
+            command
+        ),
+        None => format!(" (mode: {})", policy.mode.label()),
+    };
+
     match update_checker::check_cached_status() {
         update_checker::UpdateStatus::UpdateAvailable { latest, .. } => CheckResult {
             name: "update status".to_string(),
             status: CheckStatus::Warning,
-            details: Some(format!("v{} available — run `perry update`", latest)),
+            details: Some(format!(
+                "v{} available — run `perry update`{}",
+                latest, context
+            )),
         },
         update_checker::UpdateStatus::UpToDate => CheckResult {
             name: "update status".to_string(),
             status: CheckStatus::Ok,
-            details: Some("up to date".to_string()),
+            details: Some(format!("up to date{}", context)),
         },
         update_checker::UpdateStatus::CheckFailed => CheckResult {
             name: "update status".to_string(),