c139 plan: Updates

Written: 2026-11-11, at kick-off, from Mark's prompt (initial-prompt.md), c130's platform research (§5 Auto-update), c137's delivery modes and inventory, c62's build-partner records and the /partner-digest skill. Reader: Mark at the review stop (review-1.md); Tyler for the dependencies; the session that pushes the screens into ../qnative after the rulings.

The defaults below are proposals. Nothing is ruled until Mark walks review-1.md.

Why

The native app (c131) is the one thing every build partner installs, and it will change weekly while the program moves. The low-level update already exists: qupdate in qcontrol reads a sidecar JSON that CI publishes beside each binary, downloads the tarball, checks its SHA-256 and replaces the binary in place, elevating only when the target is unwritable. What it lacks is everything a person sees: no states anyone can read, no preference, no channels, no release notes, no restart, and no word for "someone else manages this". Mark's prompt asks for that half: updates launched from Settings, invisible if the person wants it so, the current and new version with release notes, and an early era for build partners that looks different from the structured rollout that comes with maturity.

The shape

What is updated

Two binaries live on a partner's machine: the app (qnative, the window and the tray, per user) and qcontrol (the sensor, a service installed for every user). The person sees one product, Qpoint. The Updates page shows both versions and one Update action; the sensor's row says when it needs an administrator (qupdate's elevation rule). Whether one update carries both is Tyler's call (T2, T4); the page works either way, because each row has its own state.

The app's version is the one in the window's footer (v0.1.0 today). The sensor's version is the one the sensor reports (/api/sensor, served by the bridge until c131 D17's routes land). The mocks read both from there; only the new version, its date and its notes are a marked knob, because no world carries update state.

The feed

qupdate's sidecar, as it is: version (tag or 7-char SHA), git_sha, ref, committed_at, published_at, os, arch, artifact, sha256. This cycle asks for three fields more in the partner era and three later (T3), none of which changes what qupdate does with the rest:

The states

One machine for each binary. Every state says what is true in one sentence, and what happens next (R4).

installing is not a state the person waits on: the replace happens during staging, and the switch happens at restart, so there is no moment when quitting Qpoint breaks it (Zed's non-interruptible phase, moved to where it costs nothing). Failed after three automatic tries, or for three days, becomes visible beyond the page: one tray line (R3's exception, "visible when needed").

The preference

One control, three values, under "Install updates". Checks always run (hourly) unless updates are managed elsewhere; the preference decides what happens after a check finds something.

"Invisible if their preference so desires" is the first value. Invisible means nothing interrupts: no dialog, no OS notification, no toast, no restart while the window is open. It does not mean untraceable (D2).

The trace

After a quiet install, the app says what changed where the person already looks, and nowhere else:

• The footer. The window's footer already names the data source and the version (c131 R1). For seven days after an update the version reads v0.2.0 · updated; a click opens Settings → Updates. In Ask me first, it reads v0.1.0 · 0.2.0 ready until the restart.
• The Updates page leads with the installed version and its notes, then the history (version, date, how it came: automatically or by you).
• The tray menu has one line while an update is ready ("Restart to update to 0.2.0"); in Automatically that line is there for whoever opens the menu, with no dot on the icon. The version line at the menu's foot says updated for the same seven days.
• The history carries a state, so a failed attempt shows beside the installs (Firefox's update history; D16).

No inbox message: c137's inventory dropped app-update as a message type on the same grounds (row 24: "invisible when working: the updater and the Status page's version line handle it"). Reopening that row is the alternative in call 2.

Two eras

The page is one page. The era changes what it shows, not how it is built (R7), and the era comes from the feed, not from a flag in the app (D12).

Later, from the prior art (prior-art.md questions 12–16): the channel is a setting in the same install, never a second app; the rollout share is drawn on the machine and never sent, and a staged rollout tells the person nothing, since Check now gets the update anyway; a release may carry a priority set once, mapped onto c137's quiet and normal modes, never priority; the organisation's policy holds the channels allowed, a pin, a minimum, a wait of about 30 days, an update window shown in advance, and who goes first.

Out of scope

• The self-hosted control plane (c134). Updating it is an operator updating a server (a Docker image tag, migrations, a maintenance window), a different story from a person's laptop. Later, its own cycle.
• The organisation's side of the later era: the plane's update policy page, rollout health, the admin's pin. Named here so the native page leaves room for it; designed with c134 when the plane exists.
• First install and the installer. c131's packaging.
• Downgrade. Not offered; a pulled release is replaced by a newer one.

Rules

• R1. Never in the way. No modal, no restart while the window is open, no update during a tour or a developer stream. The app restarts when the person says so, when they quit, or when nobody is looking (D3).
• R2. The sensor keeps watching. Updating the app never stops qcontrol, and the page says so at the moment of restart. Updating qcontrol is the one moment the machine may go briefly unwatched, and the page says that before it happens (T4).
• R3. Silent leaves a trace, never a prompt. After a quiet install, the change is told where the person looks (footer, Updates page, tray menu), never pushed. The one exception: an update that keeps failing becomes one tray line.
• R4. One sentence per state, and what happens next. Versions as the feed names them; the source named (downloads.qpoint.io, Homebrew, HQ); no state without a next step (c131 R1, c108's honest states).
• R5. Nothing installs unverified. The checksum always (qupdate), the signature when Tyler's signing lands (T1). A failed check changes nothing and says so.
• R6. Holding a version back is an organisation's decision. The person can defer ("Not now"), not refuse. In a product that governs AI on a machine, a stale sensor is a gap; skipping belongs to policy, later (D8).
• R7. One page for both eras. The state machine is the protocol; notes, channel and policy are slots that fill when the feed carries them. Nothing built for the partner era is thrown away when the structured rollout arrives.

Decisions (proposed defaults, for review-1)

Phases

0. Prior art (done 2026-11-11)

prior-art.md: seven desktop apps' update settings (Zed, VS Code, Firefox, 1Password, Slack, the Claude desktop app, Raycast) and five ways of giving some people a build first (VS Code Insiders, Chrome's channels, TestFlight, staged percentages, B2B early access), each in the same rows; what we copy, what we refuse, sixteen questions with defaults. It backed D1, D2, D5–D8 and D10, found the model stricter than every precedent on five counts (no restart while the window is open, the sensor's sentence, a visible trace, no skip, one channel source) and thinner on seven; four of those became D13–D16, the rest are later-era notes above.

1. The model (done 2026-11-11)

This plan's §The shape, drawn as An update and its states with the c130 kit; ## The shape at the end of the CYCLE.md Why.

2. Mocks (done 2026-11-11)

In the native skin (c132 medium A), rows from useNativeWorld(name), the update state as a marked knob (app/data/c139-updates-mock.ts):

• /pages/native/settings-updates: Settings → Updates in every state, in both eras, with the preference live; the footer's trace; the managed variants (a package manager; the organisation, later era only).
• /pages/native/updates-tray: the tray menu in each state that reaches it, the footer's two marks, and what's new after a quiet install.
• scripts/shot-programs/c139-updates.json (scale: 2, clip: ".native-window"); the sketch in c130-sketches-design.json.

3. Story (done 2026-11-11)

app/data/stories/c139.ts, wired in app/data/cycle-stories-mock.ts.

Review stop 1: review-1.md.

4. Into the app (after the rulings)

The rulings applied to the mocks, then the states pushed into ../qnative through /gpui-story (a story per state, captured per world; c132's loop), with the footer's trace and the tray line. Waits for T2 (which updater) only for the real wiring; the stories can be drawn on a fake updater behind the same states.

5. The feed contract (with Tyler)

The sidecar's new fields and the notes file written up as a proposal for qupdate or the app's own updater; the notes draft wired to the release step.

6. The later era (when maturity calls)

Channels, staged rollout, public notes, the organisation's policy and its page on the plane (c134). Not now.

Tyler's dependencies

Clarifying questions

1. Is the partner era's notes audience everyone with the app (today: yes, every install is a partner's), or do we need a per-person "insider" flag before the later era? Default: everyone, until the feed says audience: public.
2. Should developer mode being allowed (c138 D8) change what the Updates page shows (the SHA, the commit trail, a "build from main" channel)? Default: no; the channel is the feed's, not the build's.
3. Does a mechanic-access grant (c136) block an automatic update of qcontrol while a fix is in progress? Default: no, but the grant's Status line shows the version, so the mechanic sees it.

Patterns to consider

• The era as data. The feed carries the channel and the notes' audience, so the structured rollout is the same page reading more fields: modularity as purpose plus protocol (the state machine is the protocol, the slots are free).
• The footer as the trace. The window already says where its data comes from and which version runs (c131 R1); the update's trace rides on that line instead of a new surface.
• Release notes as a by-product of the record. The partner era's notes are drafted from what the cycles already write (Key Changes, sharp edges, commits), the way /partner-digest drafts the weekly issue. Archaeology, not a new writing job.
• Copy version info. One button that puts both versions, the SHAs, the OS and the channel on the clipboard, for a partner's bug report (c62's direct line).
• The organisation's update window, later. "Not during business hours" is a policy, the same place a pinned version lives.