The desktop app's shell checks the plane's signed version policy itself, against the key the daemon pinned, before it takes a version or where releases are from it; a connected daemon asks the plane's initialize again every thirty seconds and fetches the signed answers when its policy revision moves, so a change reaches the clients and, at their next turn, the running sessions; initialize's update_required is signed and acted on only as signed; a release is mirrored into the plane's object store only once its manifest checks against the release keys; and /downloads answers a bare 404 whatever the policy says¶
Decision 931 · accepted · 2026-10-23 · issue #657
The plane's word reaches the desktop updater signed, a policy change reaches connected clients, and releases are mirrored¶
It replaces two things of Decision 919: initialize standing unsigned, and /downloads
refusing a version no component is served; the rest of 919 stands.
The desktop app's shell checks the plane's signature itself¶
Decision 874 has the shell take no URL from the page: a URL the page verified is still the
page's. So the page now hands the shell the policy's signed envelope as the plane sent it
(UpdatePlane.signed), and the shell (src-tauri/src/plane_word.rs):
- asks the daemon for the pinned key itself, over the daemon's loopback socket with the
token in
daemon.json(daemon::identity,identity.get'splane_key), the same pin the terminal and the daemon hold every answer to; - checks the Ed25519 signature over the document's bytes against that key, works its
fingerprint out again rather than reading it, and checks the kind (
client_versions) and that it is not pastexpires_at; - only then reads the document: each component's policy, the
desktopcomponent's recommended version, andrelease.url.
With a signed answer the page's version and versions are not read at all. A policy the
pinned key did not sign, one changed after it was signed, of another kind or past its time,
one that came with no daemon to ask or no key pinned for that plane, is refused with a
sentence ending "nothing is installed", before anything is fetched from the URL it names.
Without a signed answer (a plane from before 0.22, or a page that has no key pinned) the
shell does as before: the page's policy can hold an update back, and releases come from
GitHub; no field of the page's is a URL in either case.
Where the plane names releases, the release is <url>/v<version>/, the version the signed
policy recommends; a mirror has no "latest", so with none recommended the shell says so and
offers nothing. TROUPE_RELEASE_URL is the person's own and still wins. Everything after is
Decision 874's: the manifest's release-key signature first, the update held to it, the
download from where the manifest was found. The verifier is the twin of
Troupe.Protocol.PlaneSignature and planeSignature.ts, held to their shared vector; it
uses ring, already in the lock through rustls, since minisign-verify checks only
minisign's own format.
Not chosen: the shell fetching me.client_versions itself. It would need the plane
token, which only the page holds, and would be a second plane client in Rust beside the
page's, outside the one gate every plane request goes through (Decision 926). The envelope
is self-checking: whoever carries it cannot change it without the pin refusing it.
A policy change reaches connected clients: a signed poll, not a push¶
Nothing dials a laptop's daemon; it dials the plane. The one connection that stays open is
the offered session's (Decision 921), which exists only while a session is offered, so a
push over it would reach some machines and not others. The daemon is the client that is
running and signed in whenever any client on the machine is, so it asks
(Troupe.Gateway.Policy):
- every thirty seconds while it holds a token, the plane's
initializeagain (Plane.handshake/0). That alone judges the daemon's own version against the policy as it stands now, which is #657's "connected clients are judged again"; - the handshake's answer carries
policy.revision, a SHA-256 of the canonical JSON of whatme.client_versionsandme.client_defaultswould say now. Where it moved, or there was none yet, the daemon fetches both, checked against the pin as at a link.
Thirty seconds so that a change lands "within a minute" with room for one missed poll. The
revision keeps the cost of a poll at one initialize and no OpenBao call: signing both
answers every half minute for every signed-in machine would be two transit calls each, for
nothing changed. The revision is not signed and is no word on anything: forged, it makes a
daemon ask or not ask, and what it acts on is still only what the pinned key signed. A
plane from before the revision names none, and is asked at its links, as before.
What changes, and what is said. A changed organisation's document is kept as at a link
(the copy, the signature, config.changed with scope org to every client), and every
session running on the machine is resolved again (Troupe.Session.Organisation), from the
same workspace and overrides it started with (Troupe.Session.reconfigure/2). Where a value
the organisation sets, or holds a layer to, came out different, the session's root agent
takes the new configuration as its next turn begins, never during one, and logs
config_note with key organisation: "Your organisation's settings changed: max_tokens
holds from this turn." The clients already show a config_note as a line. Its children are
started with its configuration and follow; the budget keeps its use so far and its limits
are held to what is now enforced, and a looser one is had by asking, as before. What the
session set up as it started, its approval mode, MCP servers and watchers, holds until it is
started again, and the line names those keys apart. troupe config --explain --session and
context.get read the resolved layers through Troupe.Session.resolved/1, which returns
the new ones, so what explains a session is what it runs with from its next turn (Decision
918). A changed version policy is told as config.changed with scope versions, and the
desktop app asks its two questions again then rather than at the next day's round.
Not chosen: re-reading the document at every turn. Every session would read and verify the copy at every turn; a change is rare, and the poll knows when one happened. Not chosen: a plane-side push to the daemon over a new standing connection: a second long-lived connection per laptop, for a change measured in minutes.
update_required is signed¶
The plane signs a refusal as it signs the policy: data.signed, kind update_required,
its body the refusal's fields, for an hour rather than a week (a refusal is the plane's
word on one handshake, asked again at the next). Every client that pinned the plane's key
acts on a refusal only as that key signed it, for its own component and version
(Troupe.PlaneKeys.held_refusal/5, and its twin in update.ts): the daemon's handshake, the
terminal's plane connection and the desktop app. One unsigned, signed by another key, past
its hour or for another version is logged or said and not acted on: the client goes on as
with a plane that could not be asked, told to update by nothing it cannot check. A plane
nothing is pinned for, which signs nothing, is taken at its word as before.
Releases mirrored into the plane¶
admin.releases.mirror {version} (a platform admin's, on the console's Integrations page),
rather than a Mix task: a plane runs as a release with no Mix, and an administrator mirrors
from the console. Troupe.Plane.Releases fetches the release's manifest.json and its
signature from GitHub's release downloads (or the deployment's :releases source), checks
them against the release keys the plane was built with, read from the same
release-keys.txt every client is built with and settable by nothing at run time, and
refuses a manifest they did not sign, or one naming another version, with a sentence and
nothing copied. Then, in the background, since a release is a few hundred megabytes, each
file the manifest names is fetched, held to its size and sha256, and put under
releases/v<version>/, the signature and the manifest last: a release is mirrored once
its manifest is there, and a copy that stopped half way names none. admin.releases.list
says which are mirrored and which are being copied on this replica. Audited as
release.mirror, and the copy's end as release.mirrored or release.mirror_failed.
To check the manifest the plane needs the release verifier, which lived in the core; the
plane may not call the core (mix troupe.boundaries). Troupe.Release.Minisign and
Troupe.Release.Manifest move to the protocol app, under the same names, as
PlaneSignature is there: the plane checking a release and the clients checking it must
agree. Troupe.Release.Keys stays in the core. The plane checking the release changes
nothing about who checks it: every client checks it again before it installs.
/downloads says nothing about the policy¶
It handed out a version some component was served and 404'd one every component refused,
so anybody without a sign-in could probe which versions were blocked. It now hands out a
file that is in the store and answers a bare 404, with no body, for anything else, whatever
the policy says: the list of refused versions comes only from the signed, signed-in
me.client_versions. A blocked version that is mirrored is handed out, as GitHub hands it
out; no client installs a version the policy it holds refuses.
Governs: clients/gui/apps/desktop/src-tauri/src/plane_word.rs, clients/gui/apps/desktop/src-tauri/src/update.rs, apps/troupe_plane/lib/troupe/plane/releases.ex, apps/troupe_core/lib/troupe/plane_keys.ex, apps/troupe_core/lib/troupe/session/organisation.ex, apps/troupe_gateway/lib/troupe/gateway/policy.ex