0
Fork 0
mirror of https://github.com/zeronsh/comet.git synced 2026-11-18 18:56:11 +00:00
comet/ARCHITECTURE.md
Wing a8d1dc6ecd
Updates that can't strand a device, on every platform, from any device (#1241)
* update: say how a device is installed and whether it can update from afar

UpdateStatus now carries `install`, `canApplyRemotely`, `cannotApplyReason`
and `manualCommand`, so a client no longer has to guess by platform. Older
engines omit them; a method this build doesn't know reads as Unknown rather
than losing the report. `update-ability-v1` advertises it.

ApplyUpdate refuses with the same reason the report gives. That includes a
managed install started by hand, which used to swap `current` and then fail
to restart a service it isn't running under.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

* providers: decide what to run at the last moment, and only claim what happened

An update judged its plan before the wait for idle and never looked again, so
a CLI reinstalled meanwhile got the old owner's updater. Under the lease and
owner gate it now re-reads the executable and what's installed and rebuilds the
plan, refusing and checking again if that isn't what the check offered.

With no target version (Hermes, Cursor), exit 0 used to report Updated. It now
takes a moved version, a rewritten executable, or Hermes's own check no longer
finding commits. Otherwise the row stays where it was, with the reason.

Homebrew:
- Only Homebrew's published version is offered. A release Homebrew doesn't have
  yet was an Update button that always failed, and would have failed Update all.
- A formula keeping an npm CLI in its keg is Homebrew's, not npm's. `npm install
  --prefix` was changing the keg behind brew's back. A Node keg's globals stay npm's.
- A Cellar or Caskroom path with no brew at that prefix can't apply, and the
  manual step names brew rather than a self-updater that writes a second copy.

Also: a Chocolatey Claude stays manual, and updaters get 30 minutes rather than
15, since stopping a silent download can leave a truncated CLI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

* update: Linux updates that can't strand a box

`app/current` now moves exactly once, when a new version has proved it's ready.
Until then every start of the service runs the old version, so if the new binary
exits, hangs, or the power goes, the next start lands on a binary that works and
knows how to put things back.

- Refuses before stopping anything if the release and a copy of the databases
  won't fit.
- Records the update durably before answering, with an id; `UpdateStatus.update`
  says how it went (inProgress, updated, rolledBack, failed), since reconnecting
  can't tell an update from a rollback.
- The old version copies the SQLite stores once nothing has them open, leaves a
  watchdog behind, and replaces itself with the new binary. It's the same process,
  so the service manager sees nothing change.
- The new version holds back work it can't take back (resuming chats, queued
  messages), proves it reads its data, serves its port and, when signed in, reaches
  Zeron's servers, then commits and only then resumes chats.
- A failed or timed-out trial goes back: the old version restores the databases
  before anything opens them. An interrupted restore finishes first.

`zeron update` on a box with a running service takes the same path and reports the
outcome. Automatic updates don't retry a release that went back; a person can.
ZERON_SERVICE_UNIT names another unit, so a test install can never restart a real
one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

* providers: an update someone asks for doesn't wait for running chats

It used to wait behind an exclusive lease with no bound, which with agents always
running can look stuck for ever. Where the installer keeps the old version's files,
it now goes ahead: running chats keep the version they started on, new ones get
the new one, and nothing is drained or held up. That's Claude's native install,
Codex standalone, Grok standalone, Cursor (chats use its SDK, not this CLI),
Antigravity and agents from the ACP registry.

Installers that replace or delete files keep waiting, because a chat's process
lives for its whole session and goes on loading files from where it started: npm
and the other package managers, Homebrew, Muse, OpenCode, Pi and Hermes. Their row
says why, in the new `waitReason`. Automatic updates still wait for a quiet moment.

The registry's cleanup used to delete any version older than the last, now that
updates don't wait for chats it keeps a version something is running from.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

* update: Mac and Windows devices can update from afar

The same rule as Linux, with the engine doing all of it, so the app doesn't have
to be open: the installed app changes only at the commit, and anything before that
lands back on the old version.

macOS: the new bundle is copied beside the installed one before anything stops, so
what can fail, fails with Zeron still running. The engine drains, backs up and
replaces itself in place, the same process, so it never starts a successor. Once
proved, one atomic swap makes the new bundle the app. An app still open carries on
from the retired bundle until it restarts.

Windows: the old process can't be replaced, so it starts the new exe from a folder
inside the installation and stays on as the watchdog. A running exe can be renamed,
so moving it into place is the commit.

A bundle something runs from is no longer deleted, for updates from the app too:
that's #1037. Retired bundles and old stages go once a process scan finds nothing
running from them.

A second start during a trial (the app's reconnect seeing the port go quiet) now
bows out rather than rolling back a trial that's still running, and zombies no
longer count as running on macOS. The failure tests give each fake install its own
copy of the binary: hard links made the process checks see through to other
installs, which was the cause of their intermittent failures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

* update: nothing but the trial opens the databases mid-update

An app that can't start its helper embeds the engine, which skips the update's
start-up step, and could have opened databases a trial had changed or a restore
was part way through. It now refuses until the update has settled. The app's own
install on quit also refuses during an update: going back from a trial needs the
installed app to stay as it was.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

* update: compile on Windows

The watchdog's environment variables are only read on Unix, the test's
version lookup no longer ends in a Unix-only expression, and the Grok CLI
fixture and the test that uses it are Unix-only like their callers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* update: check free disk space on Windows

Without it every Windows update refused with "couldn't check the free disk
space". The store-list test compares paths with forward slashes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* update: a brief reader can't fail the update record on Windows

Replacing a file fails with "Access is denied" while anything has it open
without delete sharing (antivirus, an indexer, a script). Seen once on a real
trial: the watchdog couldn't record the trial's pid. Retry the rename for up
to a second.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* update: give the second-start test a deadline a slow machine can't miss

It failed once in 80 runs on a loaded box, when the second start landed after a
3-second trial deadline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

* update: another device's status follows it through its restart

One device asking another's `UpdateStatus` got a subscription that ended the moment
the update restarted the engine, so whoever asked had to know to ask again. It now
carries on until the subscriber goes, asking again if nothing has come for a while,
which also covers a device that died without a word.

Asking a device that can't be reached now says that plainly, and that the update
didn't start, rather than `transport: peer …: readiness check failed`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

* update: a beta Mac stays on beta, and says what's on offer

Tested with a bundle shaped like a beta: a beta interface carrying stable's engine.

An update asked from another device already followed the app's recorded channel,
but with no record, as when the app hasn't run since it was installed, the default
was stable: it installed the stable app and left beta. An app with no recorded
choice now stays on the channel it was built for. A choice someone made at that Mac
still stands.

The engine's report compared releases with its own version, which on a beta is
stable's, so a newer beta read as nothing new and no update was offered. On a macOS
app install it now compares with the app's version, and says what that is in
`appVersion`. It looks again once a commit has changed the answer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>
2026-11-05 16:59:05 -07:00

339 lines
28 KiB