Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
docs(versioning): move the design to Confluence (CHOO-1865)
Louis Amaudruz2f3ff98006cd
diff --git a/docs/VERSIONING.md b/docs/VERSIONING.mddeleted file mode 100644index f171dd91a..000000000--- a/docs/VERSIONING.md+++ /dev/null@@ -1,822 +0,0 @@-# Versioning and cross-artifact compatibility--Status: **design, pending approval** · Ticket: [CHOO-1865](https://sandboxquantum.atlassian.net/browse/CHOO-1865)--Switch ships many independently-versioned artifacts. This document defines how-they declare compatibility with one another, and how they are updated safely-while sessions are running.--**Scope.** This document owns *which versions work together, and how transitions-between versions are handled safely*. How each artifact is packaged and-distributed is [CHOO-1864](https://sandboxquantum.atlassian.net/browse/CHOO-1864)-and deliberately not covered here.-------## 1. The problem--Six shippable artifacts, three disjoint release tags, and no declared-interdependency between any of them:--| Artifact | Version today | Released by |-| --- | --- | --- |-| switch-core (+ `gateway`, `setup` images, Helm chart, standalone compose) | `0.12.3` | tag `switch-v*` |-| switchdash desktop | `0.19.2` | tag `switchdash-v*` |-| `@sandbox-quantum/switch-agent-runtime` | `0.1.5` | tag `switch-agent-runtime-v*` |-| Claude Code connector plugin | `0.7.8` | none — served from the default branch |-| Codex connector plugin | `0.2.0` | none — served from the default branch |-| Remote sidecar | `1.7` | ships inside switchdash |--Nothing states which combinations are valid. Neither a user nor the software-itself can answer *"does this switchdash work against that switch-core?"* except-by trying it.--Four tickets are four edges of this one graph, each solved separately:-[CHOO-1321](https://sandboxquantum.atlassian.net/browse/CHOO-1321) (core ↔-switchdash), [CHOO-601](https://sandboxquantum.atlassian.net/browse/CHOO-601)-(plugin version reporting),-[CHOO-1736](https://sandboxquantum.atlassian.net/browse/CHOO-1736) (managed stack-not following the app's pin), and-[CHOO-1677](https://sandboxquantum.atlassian.net/browse/CHOO-1677) (switchdash-bundling a stale core). Solving them pairwise gives N² special cases and no-shared vocabulary.--### 1.1 What already exists--Two mechanisms in the tree already do this correctly for one edge each, and the-model below generalises them rather than replacing them:--- **`PROTOCOL_VERSION = 1`** (`core/switch_core/bridges/agent/protocol/connections.py`)- — an integer checked when an agent opens the event stream.-- **The sidecar's major** (`dash/apps/switchdash-desktop/src/sidecar/sidecar-version.ts`)- — `SIDECAR_VERSION` plus an explicit `MIN_SUPPORTED_SIDECAR_MAJOR` floor, with- compatibility judged on the major alone. This is the most developed- compatibility model in the repo and the direct ancestor of §3.--### 1.2 What is missing--**switch-core cannot state its own version.** `0.12.3` lives in-`core/pyproject.toml`, never enters the Python process, and is not stamped into-the image. The only introspection endpoint is `GET /health`-(`core/switch_core/main.py`), which returns `{"status": "ok"}`.--Consequently the only working version check in the repo-(`dash/apps/switchdash-desktop/src/main/core/managed-switch-server/deployed-version.ts`)-reverse-engineers the deployed version from the running container's image tag.-That works only for stacks switchdash itself manages. For a switch-core someone-else operates, switchdash has no visibility at all.--**No client version reaches the server.** There is no version header, no field-on agent registration, and no version column on any client-bearing table.--**Why the artifact version matters even though contracts decide compatibility.**-The compatibility gate (§3) reads contract versions only — an artifact version-never decides whether two components may talk. The artifact version is still-required for everything around that decision: reporting that a newer release-exists (§4), folding a release path to work out what a move costs (§5.3),-refusing a switch-core downgrade whose database has already migrated forward-(§8.1), naming the `untested` release combinations (§4.1), and answering "what-are you running?" in a bug report. Both travel on the same endpoint, so this is-one primitive rather than two.--### 1.3 "Unknown" currently renders as "fine" — in four places--The ticket's non-negotiable rule is that *incompatible*, *untested* and-*unknown* stay distinct, and that unknown never reads as fine. Today it does:--1. `protocol_version` on the events endpoint **defaults to the server's own- value**, so a client that declares nothing is treated as compatible. No- shipped client sends it, so the check has never fired in production.-2. `readVersionStatus()` returns `drift: null` — indistinguishable from "no- drift" — when the deployed version cannot be read.-3. The standalone compose interpolates `${SWITCH_VERSION:-latest}`, so a missing- env var silently floats the stack to `latest`.-4. `refuseDowngrade()` blocks only when the direction is *provably* a downgrade;- an uncomparable pair passes through.--These are the same defect four times, and fixing that pattern is a larger share-of the value here than any new machinery.-------## 2. Artifact versions--**Every artifact uses semantic versioning `MAJOR.MINOR.PATCH`, and an artifact-version describes only that artifact.** It says *where you are*. It carries no-compatibility meaning whatsoever.--| Field | Meaning |-| --- | --- |-| `MAJOR` | Breaking change to how the artifact is used, configured or installed |-| `MINOR` | New functionality |-| `PATCH` | Fixes |--A protocol break will usually ship alongside a major bump, but **nothing may-infer compatibility from an artifact version**. Versions inform people;-contracts (§3) inform machines.--Changes required:--- **Sidecar** moves from two components to three: `1.7` → `1.7.0`. Its major- **stays at 1** — see §11.1.-- **Gateway** (`gateway/package.json`) has no `version` field. It gets one, or- is explicitly documented as part of the switch-core release rather than a- separate artifact.-- **Helm chart** `Chart.yaml` says `0.2.1` and is silently overwritten at- package time with the tag version. The file stops lying.--**Every artifact gets a changelog.** Today only switch-core and switchdash have-one. Each release produces two outputs from one event: a **changelog entry** for-humans and a **release manifest** (§5) for machines, generated together so they-cannot drift.-------## 3. Compatibility lives on contracts, not artifacts--A **contract** is a named interface where two artifacts talk. Each contract-carries a single integer, incremented only when that interface changes in a way-the other side can observe.--Each participant declares two numbers per contract:--- **`speaks`** — the newest version it implements-- **`accepts`** — the oldest version it still handles--Two participants are compatible when their ranges overlap: each side's `speaks`-is at or above the other side's `accepts`. They then operate at the lower of the-two `speaks`.--### 3.1 The contracts--| Contract | Between | Today |-| --- | --- | --- |-| `agent-protocol` | switch-core ↔ agent runtime (and the sidecar, which embeds it) | exists as `PROTOCOL_VERSION = 1` |-| `gateway-api` | switch-core ↔ switchdash, gateway frontend | new |-| `stack-compose` | standalone compose ↔ switchdash's managed-stack pipeline | new |-| `sidecar-control` | remote sidecar ↔ switchdash | exists as the sidecar major |-| `db-schema` | switch-core ↔ Postgres | Alembic revision; one-way |--Five edges, not N² pairs. Adding an artifact means declaring which contracts it-participates in; it does not mean touching the others.--### 3.2 The connector plugins are on no contract--A plugin's payload is a skill, a hook and an MCP config. It declares which-runtime version to launch, and the runtime fetches its tool definitions from the-server at startup (`GET /agents/{id}/ops`), so a plugin's tool surface cannot go-stale.--**A plugin's compatibility is the runtime's, inherited.** This is why there is no-plugin contract. It also settles CHOO-601: the server should *know and report*-which plugin version an agent runs, and must never *gate* a connection on it —-the contract underneath decides that.--> **Gate on contracts. Report on releases.**--### 3.3 Where contract numbers live--Contract versions are **baked in at build**, because they describe what the code-does — a component cannot look this up, it *is* this.--One authored file at the repo root is the only thing a human edits. From it,-CI generates a Python module and a TypeScript module so the two languages cannot-disagree, and fails if the generated files do not match their source.--This is deliberate: `COMPATIBLE_SWITCH_VERSION` is currently hand-copied into-`app-identity.canary.ts` with a "keep in sync" comment and nothing enforcing it.--### 3.4 How the numbers are exchanged--**Both sides always publish two numbers per contract** — `speaks` and `accepts`.-A single number is never sufficient: it cannot express a compatibility window,-and the window is the whole mechanism.--*What* is exchanged is identical on every edge. *How* differs, because the-transports differ — one edge is HTTP, one is a local file, one is a data file-with no running peer at all. Each edge reuses a channel that already exists:--| Contract | Server side publishes via | Client side declares via |-| --- | --- | --- |-| `agent-protocol` | `GET /version`, and the `connection_state` frame already sent when the stream opens | query params on `GET /agents/{id}/events` — the endpoint already takes `?protocol=` |-| `gateway-api` | `GET /version` | nothing to send; switchdash compares the server's range against its own compiled-in one |-| `sidecar-control` | the sidecar's ready file (`sidecar.ready`), which already carries its version, hash, pid and port | switchdash's own range is compiled in; it reads the sidecar's from that file |-| `stack-compose` | a version field in the compose file itself, and an annotation on the published OCI artifact | switchdash reads it from the bundled copy and from the on-host file |-| `db-schema` | reported in `GET /version` | switch-core compares the revision in the database against the revisions its own build knows |--Two consequences worth stating:--- **`sidecar-control` needs no endpoint.** switchdash and the sidecar communicate- over a file on the host, so the range goes in the file the sidecar already- writes. Adding an HTTP handshake there would be inventing a transport we do- not need.-- **`stack-compose` has no running peer.** The compose file is data, so its- version is carried *in the artifact*, and there is only one direction to check.--**The default on `?protocol=` must be removed.** It currently defaults to the-server's own value, so a client that declares nothing is treated as compatible.-An absent declaration is *unknown*, not *current*.--`GET /version` is the one genuinely new primitive. It returns switch-core's-artifact version, its `speaks`/`accepts` for every contract it participates in,-and its schema revision — unauthenticated, alongside `/health` in the auth-allowlist:--```json-{- "version": "0.12.3",- "contracts": {- "agent-protocol": { "speaks": 1, "accepts": 1 },- "gateway-api": { "speaks": 1, "accepts": 1 },- "db-schema": { "speaks": 1, "accepts": 1 }- },- "schema_revision": "b3f36489c258"-}-```-------### 3.5 A managed stack crosses three edges, not one--When switchdash runs the stack itself, three contracts are in play and they are-easily conflated:--1. **`stack-compose`** — can this pipeline drive this compose file?-2. **`gateway-api`** — can switchdash talk to the server the file started?-3. **`agent-protocol`** — can the agent runtimes talk to that same server?--The compose file is only the first. It takes `SWITCH_VERSION` from the `.env`-switchdash writes and pulls that image tag, which means **switchdash chooses-which server version it will then have to talk to**.--So for a managed stack, compatibility on edge 2 is not discovered — it is-*arranged*. The app pins a core it already knows it can speak to, which is what-`COMPATIBLE_SWITCH_VERSION` does today. The contract check earns its keep only-where reality diverges from that choice: a stack already running the version an-*older* switchdash pinned, a server operated by someone else, or a host that was-reset or hand-edited.--**The pin is a choice; the check is for when the choice was somebody else's.**--This gives the pin something it lacks today. It is currently a hand-maintained-constant that nothing verifies — it stays true because a person remembers. Once-both sides declare ranges, CI can assert that the pinned switch-core's-`gateway-api` range overlaps switchdash's own. The pin stays an exact version,-for reproducible builds; it simply stops being taken on faith.--## 4. Two questions, not one--Every artifact answers two independent questions:--- **Compatible?** — the contract check. A hard gate. Changes rarely.-- **Current?** — is this the build it should be on. Soft. Changes constantly.--Compatibility is not currency. A plugin from three months ago may be perfectly-compatible and still worse: stale skill text, an unfixed hook bug. The contract-model cannot see that, and should not.--The plugin and the sidecar live almost entirely in the second question —-`sidecar-control` will sit at 1 for a long time, so for the sidecar the currency-question does nearly all the work. That is already why its code compares content-hashes first and uses the version only as a tie-break.--**For artifacts we own and that hold no user data, the default is to keep them-current, with the contract check as the brake rather than the engine.**--### 4.1 Compatibility states--| State | Meaning | Behaviour |-| --- | --- | --- |-| `compatible` | Ranges overlap | Silent |-| `outdated` | Compatible; a newer build exists | Informational |-| `deprecated` | Compatible today; the peer has announced it is dropping this version | Warned, while it still works |-| `unknown` | The peer declared nothing, or it could not be read | Shown as unknown — **never as fine** |-| `incompatible` | Ranges disjoint | Blocked at the boundary |--`untested` — ranges overlap but this exact release combination was never-exercised — is a **release-layer advisory generated by CI from what we actually-ran**. It never blocks. Keeping it on a separate layer from `incompatible` is-what stops the tested-combination set from becoming a hand-maintained matrix-that rots.--### 4.2 Never report a mismatch without the remedy--Because both sides declare a range, we know not only that they disagree but-**who must move and to what**. The output is never "incompatible"; it is-"requires switch-core 0.14 or newer, this one is 0.12".--Direction is not symmetric:--- **Client too old** — common. The client updates; for the runtime and sidecar- we simply replace them.-- **Server too old** — nothing the client does fixes it. For a managed stack,- offer to update it; for a server we do not manage, report clearly.-- **Either side could move** — prefer moving the **client**. It is cheap and- reversible. Moving the server means a schema migration, which is not.-------## 5. Release manifests--Each release publishes a small manifest alongside its changelog entry:--```yaml-version: 0.7.9-contracts:- agent-protocol: { speaks: 1, accepts: 1 }-disturbance: next-session-atomic: true-reversible: true-```--| Field | Meaning | Source |-| --- | --- | --- |-| `contracts` | This release's `speaks`/`accepts` per contract | Generated by CI from the contract file |-| `disturbance` | What applying it costs — §6 | Declared; often derivable |-| `atomic` | Can a failed apply leave things worse than before? | A property of the installer, constant per artifact |-| `reversible` | Can it be rolled back? | Constant per artifact (switch-core: no) |--Only `disturbance` is a genuine per-release judgement, and even that is often-derivable: an empty contract delta on an artifact read at session start is-`next-session` by construction.--### 5.1 Manifests and the contract file are one source, two outputs--`contracts.yaml` (§3.3) is the source. At release time it yields:--- **the compiled-in copy** — baked into the build, and the thing a handshake- reads. Answers *"can I talk to you right now?"*-- **the published manifest** — a record of what that release declared. Answers- *"could I talk to you **if I installed you**?"*--This is why the manifest repeats the contract numbers rather than carrying only-`disturbance` / `atomic` / `reversible`. **A build that is not installed cannot-be asked.** Determining that an update would be `BLOCKED` requires its ranges in-advance; the alternative is discovering it by installing and breaking.--The compiled copy describes the present. The manifest describes a hypothetical-future.--**There is no single global manifest file.** `contracts.yaml` is one shared file-covering every artifact, but it holds only *current* numbers; a history is-per-artifact and holds that artifact's past. In one line: **`contracts.yaml` is-"now, for everything"; a history is "over time, for one thing".**--1. **Repo** — `contracts.yaml` carries every artifact's current ranges, in one- place a human edits.-2. **Build** — each artifact compiles in **its own** ranges; that is what a- handshake reads.-3. **Release** — the artifact emits a manifest (its own ranges plus- `disturbance` / `atomic` / `reversible`), appends it to **its own** cumulative- history, and publishes it on **its own** channel.--A single published file was rejected: artifacts release on different days, so it-would be rewritten by whichever release ran last; a consumer only ever needs the-one artifact it is evaluating; the artifacts ship through different channels; and-it would have to be hosted somewhere, reintroducing a central dependency that-per-artifact history avoids by riding the channel already delivering the-artifact.--### 5.2 A manifest describes the post-install state, not just the artifact--An artifact that pins another and installs it as a unit declares the ranges that-result from installing **it**, not merely the ranges of its own code.--The connector plugin is the case that matters. It pins a runtime version in its-`.mcp.json`, and the runtime is what actually speaks `agent-protocol`. Its-manifest therefore does not say *"I pin runtime 0.2.0"*, leaving the consumer to-resolve that; it says *"installing me yields `agent-protocol` speaks 2, accepts-1"*. The pin is known at plugin build time, so CI resolves it against-`contracts.yaml` and writes the resulting ranges in — one fetch, and nothing-hand-typed to drift.--This is what §3.2's "a plugin's compatibility is the runtime's, inherited"-means concretely: **inherited means expressed in the plugin's own declaration.**-The plugin is the unit of distribution; the runtime is an implementation detail-of it.--The runtime is pinned in two places — the plugin's `.mcp.json` and switchdash's-own constant for sessions it launches directly — and a test already fails when-those version strings drift. Under this model both declare effective-`agent-protocol` ranges, so that test gains a sibling: **the declared ranges must-agree.** That is the stronger check, since it also permits two different runtime-versions that provably speak the same thing.--### 5.3 Manifests describe the *move*, not the version--`0.7.8 → 0.8.0` and `0.7.9 → 0.8.0` are different journeys and can have-different answers. Each release declares only what changed **since the release-before it**; a jump **folds** every release in between:--- `disturbance` → the worst on the path-- `reversible` → false if any step on the path was irreversible-- `contracts` → compare the endpoints; the ranges handle it-- `atomic` → unaffected by path length; one install is performed--N releases therefore require N declarations, not N² pairs. A client jumping-forward across three breaking releases is told so, rather than being judged only-against the latest.--### 5.4 How the history reaches whoever is deciding--A path cannot be folded if it cannot be seen, so manifests for all releases must-be reachable — not only the newest.--Walking backwards one release at a time would mean N requests and would break-once an old release is deleted. Instead: **each release publishes a cumulative-file containing every manifest up to and including itself.** Deciding whether to-move to 0.8.0 is then one fetch — find the current version in that file and fold-everything after it.--The unknown rule falls out of this for free: **if the current version is not in-the list**, the path cannot be folded, so the move is `unknown` — most cautious-class, and it prompts. That is the correct treatment of something ancient enough-to predate the record.--Size is not a concern; a few fields per release stays small over hundreds of-releases.--**Whatever switchdash bundles or pins has its history embedded at switchdash-build time.** This is a constraint on the build pipeline, not an implementation-detail:--| Artifact | Where the history comes from |-| --- | --- |-| Sidecar | **Embedded.** switchdash ships the bundle; CI embeds the history beside it |-| Bundled compose | **Embedded.** switchdash already carries a pinned copy |-| switch-core | **Embedded up to the pin.** Upgrading a managed stack is a move and needs the path; switchdash pins an exact version, so CI knows how far to go |-| Connector plugins | Fetched — installed from a marketplace out of band (§5.5) |-| switchdash itself | Fetched — its update feed already carries per-release metadata |--The sidecar has no release tag of its own; like the plugin it rides another-artifact, so its history is a committed file beside `sidecar-version.ts`,-appended when `SIDECAR_VERSION` bumps, under the same CI check.--**Why embedding is sufficient rather than merely convenient:** the mover always-ships the target. switchdash folds only *forward*, from something older on the-host up to what it carries — and it carries that history by construction. A host-running something *newer* is not a fold at all but a reattach (§11.3), which-needs only the peer's live declaration. A host older than the oldest entry known-is `unknown`, and therefore the most cautious class. All three cases terminate-without a network call.-------### 5.5 How switchdash discovers that a new version exists--switchdash is both a managed artifact and the manager of several others, and it-is the only component positioned to show the user one consolidated picture. To-do that it needs two facts per managed artifact: **what is installed** and **what-is available**.--It already has most of them. The addition is that each existing resolver also-fetches the manifest history and runs the evaluation:--| Artifact | How a new version is discovered |-| --- | --- |-| Connector plugin | Already refreshes the agent CLI's marketplace and reads installed vs latest. The history file sits in the same plugin directory |-| Runtime | No separate discovery — the plugin's `.mcp.json` pins it, so the runtime moves because the plugin moved |-| Sidecar | Nothing to discover. switchdash ships it; the deployed version comes from the host's ready file |-| switch-core | For a managed stack, pinned by switchdash, so a new core arrives with a new switchdash. For a server it does not manage, it reports rather than manages |-| switchdash | Its own update feed |--**Plugins have no release tag.** They are served from the default branch, so-merging is releasing and there is no tag to attach a manifest to. Their history-is therefore a committed file in the plugin directory, appended when the version-is bumped — enforced in CI: if `plugin.json`'s version changed and the history-gained no entry, fail.--**Scope boundary.** *What* is fetched is defined here. *Where each artifact-publishes it and how it is reached* belongs to CHOO-1864, so every case above-reuses a channel that already exists rather than proposing a new one.--## 6. Disturbance: what is lost, not what restarts--| Level | Meaning | Example |-| --- | --- | --- |-| `none` | Nothing running is affected | A plugin release that only edits its README |-| `next-session` | New sessions get it; running ones keep what they have | A skill-text edit; a new runtime pin |-| `restart-resumable` | The component restarts and everything reattaches | Sidecar upgrade; switch-core patch |-| `restart-visible` | Work resumes, but the user sees an interruption | switchdash app update |-| `restart-lossy` | Work is actually lost | Stack reset; a protocol bump that strands running sessions |--The boundary between `restart-resumable` and `restart-visible` is *does anyone-notice*. The boundary between `restart-visible` and `restart-lossy` is *is-anything lost*. Only the last is worth interrupting someone over.--**`restart-resumable` is not conditional on idleness.** A sidecar upgrade-reattaches by design: sessions live in tmux on the host, sidecar state is-persisted across restarts, and sessions are launched with the *path* to the-endpoint file rather than a port, precisely so a restarted sidecar with a fresh-port stays reachable from panes spawned against the previous process. The event-stream resumes from its cursor, and if it fell outside the buffer it emits a gap-frame rather than pretending to be caught up — so the worst case is *detected*,-not silent.--### 6.1 What happens to sessions on a `next-session` update--Nothing. No prompt, no injection, no restart — if running sessions had to be-restarted it would not be `next-session`.--What we do is **show** it: the directory is on plugin `0.7.9`, two sessions are-running `0.7.8`, displayed as *"2 sessions on the previous version — they pick-it up when they next start"*. They converge as sessions end.--This is the **installed vs running** distinction (§7) at its smallest scale. A-user-initiated "restart this session" affordance is reasonable — resuming a-Claude Code session preserves the conversation — but it is never automatic. The-one case worth actively nudging is when the running version is `deprecated`-rather than merely outdated.-------## 7. Scope: everything is shared at a different granularity--Per location, the chain is linear:--```-sidecar → agent CLI (Claude Code / Codex) → plugin → runtime → switch-core-```--Each link talks only to the next, so N hosts is N copies of one small pattern-rather than a graph. But each link is **shared at a different granularity**, and-that — not the component count — is the real source of complexity:--| Link | Scope |-| --- | --- |-| switch-core | global |-| plugin + runtime | per host + user |-| sidecar bundle (the version) | per directory |-| sidecar process (what runs) | per agent |--The sidecar bundle is one file per repo directory, while every agent in that-directory runs its own process with its own state. So agents in one directory-share a version involuntarily; agents in different directories drift freely.--**Verdicts are computed per agent and rolled up** through directory and host,-worst state winning. That yields blast radius for free — *"this affects 3 agents-in this directory"* — because scope is modelled rather than derived by hand.--**Track what is installed separately from what is running.** They diverge for-exactly as long as an old process outlives an update, which is §8 in miniature.--### 7.1 Two views, two owners--- **switchdash** is the only component that sees every location → *"are my hosts- consistent?"*-- **switch-core** is the only component that sees every connected client →- *"who is talking to me, and on what?"*--Neither can answer the other's question, and neither needs to.-------## 8. Updates while things are running--Immediately after any update the deployment is, by construction, running mixed-versions. The model must describe that state rather than assume it away.--### 8.1 In-flight sessions, per artifact--- **switch-core** — sessions keep running. This is what the `accepts` floor buys:- a new core must reach back far enough to cover anything plausibly still alive.- A session below the floor is refused at its **next reconnect**, with a message- naming both versions. It is never killed mid-work, and never left running- while silently dropping events.-- **switchdash** — restarts anyway; the interesting question is the stack it- manages.-- **Plugin / runtime** — a running session keeps the runtime it started with; new- sessions get the new one. Mixed by construction and correct.-- **Sidecar** — the existing verdict table (replace on incompatible major,- reattach when the host has newer, upgrade otherwise) is retained and folded- into this framework.-- **`db-schema`** — one-way. Forward at boot, no rollback.--### 8.2 The update verdict--The verdict is **computed from the folded manifest plus live state**, never-written by hand:--```-if a contract delta strands a currently-connected peer → BLOCKED-else if not atomic, or not reversible → MANUAL-else if disturbance <= restart-resumable → SILENT-else if restart-visible and nothing live → SILENT-else if restart-visible and something live → PROMPT-else → PROMPT-```--| Verdict | Surface |-| --- | --- |-| `SILENT` | Applied without asking, and recorded |-| `DEFER` | *"will apply when this host is idle"* — rare; only where waiting saves something |-| `PROMPT` | *"this will interrupt 3 sessions"*, with the real count |-| `BLOCKED` | *"needs switch-core 0.14 first"* — names what must move |-| `MANUAL` | Cannot be automated, and why |--Nobody labels a release "silent". Codex plugin updates come out `MANUAL` purely-because that installer has no update verb and does uninstall-then-reinstall — a-failure leaves the agent with **no connector at all**. Making that path atomic-turns it silent automatically, with no policy change.--### 8.3 Safety is computed; autonomy is chosen--`SILENT` is a **ceiling, not an instruction**. Whether we act on it is a separate-per-artifact policy decision. An artifact may be more conservative than its-verdict allows; never less.--> Manage silently the things the user does not know exist. Ask about the things-> they do.--| Artifact | Policy |-| --- | --- |-| Sidecar | Auto-apply. Its version should be invisible |-| Runtime | Auto-apply |-| Plugin | Auto-apply, **recorded** — skill text changes agent behaviour, so it should not need approval but must be findable afterwards |-| switchdash | **Never auto.** It is the supervisor — the component that applies everyone else's updates — and the UI the user is looking at. The verdict gates and annotates the offer instead |-| switch-core | **Never auto.** Data, and one-way migrations |--**Silent is not invisible.** Silent means no prompt, not no record.--This closes a live footgun: switchdash's updater currently applies a build whose-pinned core is *older* than the running stack, which then refuses to start and-tells the user to update switchdash. Under this rule that update is `BLOCKED`,-with a reason, before anything is clicked.--### 8.4 Safe update sequence--Update the depended-upon before the depender: **switch-core, then switchdash,-then the runtime and plugins**, with the sidecar riding switchdash. A server's-`accepts` floor is what covers old clients; an old server cannot know anything-about a new client.--Rollback is safe anywhere in that order **except across a schema migration**,-where the model must refuse rather than warn.-------## 9. Surfacing--None of this is worth building if it only reaches the logs.--- **switch-core records what each client declared** — artifact version and- contract versions, per connection. This is the substrate for everything else.-- **Gateway compatibility view** — every connected client, what it speaks, and- its state; plus the deployment summary: *"3 sessions on `agent-protocol` 1,- server speaks 2, floor 1."*-- **"What would raising this floor break?"** — answerable before doing it,- instead of afterwards.-- **switchdash** extends its existing drift notice to servers it does not manage- via `GET /version`, and stops rendering "could not read" as "no drift".-- **Update availability** is annotated with its verdict, so *"an update exists"*- and *"this update will interrupt your work"* are visibly different.-------## 10. Two defaults that carry most of the weight--1. **Unknown never renders as fine.** If a version cannot be read or was not- declared, say so. (§1.3 lists four places that currently violate this.)-2. **Undeclared never means safe.** A release with no manifest, or a missing- field, is treated as the most disruptive class and prompts. The failure to- avoid is someone forgetting to declare and receiving silent auto-updates as a- reward.-------## 11. Risks--### 11.1 Renumbering the sidecar--The sidecar is the only artifact whose version *currently is* its compatibility-signal. Moving that into `sidecar-control` is correct, but switchdash installs-already in the field still judge on the major.--**The major must stay at 1** (`1.7` → `1.7.0`). An old client parses major 1-either way. Going to `2.0.0` would make every existing switchdash read the new-sidecar as incompatible — reproducing CHOO-1937, where two installs sharing a-host replace each other indefinitely.--### 11.2 A forgotten counter--The model is only as good as our discipline in incrementing a contract when we-change it. A missed bump means the system reports "compatible" for something-that is not.--Mitigation: CI flags a change to an interface-defining file with no-corresponding counter change. This is a prompt, not a proof, and it is the-honest cost of keeping artifacts independently releasable.--### 11.3 Introducing real floors makes a latent sidecar bug reachable--`decideExisting()` in `remote-sidecar-launcher.ts` evaluates **incompatible-before newer-on-host**:--```ts-if (!this.isCompatible(ready)) { /* … */ return null; } // replace-if (ready.hash === localHash) return this.toEndpoint(ready);-if (compareSidecarVersions(ready.version, SIDECAR_VERSION) > 0) { /* … */ }-```--Returning `null` means *replace*. So a client that considers the running sidecar-incompatible replaces it **even when that sidecar is newer** — a downgrade. On a-host two switchdash installs share, the newer one puts its build back, and the-two replace each other indefinitely. The newer-on-host guard added for CHOO-1937-sits *after* the compatibility check and does not cover this path.--**This is not reachable today**, because `MIN_SUPPORTED_SIDECAR_MAJOR = 0` while-majors are 1, so `isCompatible` is always true. It is latent, and the current-mitigation is a policy written in a comment — `sidecar-version.ts` warns that-raising the floor "kills every older sidecar on sight — including one an older-switchdash on the same host will then kill right back, each replacing the other-forever."--**This model makes floors first-class and expects them to move**, which converts-that policy into something a mechanism must enforce:--> **Never downgrade a peer, even when it is incompatible.** Newer-on-host is-> evaluated first. A client that cannot speak to a newer peer refuses the host-> and says so — *"this host's sidecar is newer than this switchdash supports"* —-> rather than replacing it.--Refusing terminates. Replacing does not.--### 11.4 Deploy lock scope (to verify)--`sidecarDeployLockRelPath()` is keyed per **agent**, while the bundle it guards-is shared per **directory**. Two agents in one directory take different locks and-write the same file. Upload is temp-file-then-rename, so nothing tears — but two-switchdash installs with differing bundles could alternate overwriting each-other, which is the shape of CHOO-1937 one level down. Needs verification rather-than assumption.-------## 12. Rejected alternatives--- **A central matrix of version tuples.** Rots on contact: cannot express "any- 0.12.x", needs an edit per release per artifact, and goes stale silently —- the failure mode this work exists to end. Retained only as the non-blocking- `untested` layer, CI-generated, never hand-written.-- **Semver ranges between artifact versions** (switchdash declares- `switch-core >=0.12 <0.14`). What CHOO-1321 would have produced. Couples- release cadence to compatibility and misstates reality in both directions: it- forces a bump when no interface moved, and stays silent when a patch breaks- the wire.-- **A single lockstep release train.** Genuinely simpler — one version,- everything ships together, compatible means equal. Rejected because it ends- how these artifacts are actually shipped (the plugin releases by merging to- main; the runtime publishes from a branch so it can be tested without- merging), and forces version bumps on artifacts that did not change.-- **Exact-match protocol equality** — today's behaviour. No overlap window at- all, so every protocol change is a flag day. Not a trade-off; a defect.-- **The client asking the server "am I compatible?" as the only mechanism.**- Fails exactly when the two cannot talk, and cannot gate an update before it is- installed. Useful as a supplement, not as the base.-------## 13. Deferred--**The deprecation-window policy** — how long a contract version must be accepted-before its code path is deleted — is layered on top of this model and does not-change its core. It is deferred to a follow-up.--One part is **not** deferrable and is included here: the `accepts` floor must-exist in the declaration and be recorded server-side from the outset. It is the-mechanism the policy will later act on, and without it the question *"who would-raising this floor break?"* cannot be asked at all.--Sketch, for later: a floor rises only after the dropped version was marked-deprecated for at least one minor cycle and nothing observable is still below-it, with a published calendar backstop for deployments we cannot observe; the-end is a hard refusal, not an override; and deprecation is announced to the-specific affected client while it still works.-------## 14. Implementation plan--Four layers, in dependency order. Each is useful on its own.--**A — make versions legible.**-switch-core learns its own version; `GET /version`; the contract file plus-generated Python and TypeScript with a CI equality check; clients declare on-connect; the server records what they declared. Fix the four defects in §1.3.--**B — enforce ranges.**-Exact-match becomes range overlap; refusal messages name both sides and the-remedy; switchdash gains drift detection for servers it does not manage.--**C — make it visible.**-Gateway compatibility view; mixed-version summary; the "what would raising this-floor break" query.--**D — update safety.**-Release manifests and path folding; the verdict engine; per-artifact autonomy-policy; the switchdash updater gate; atomic Codex reinstall; CI-generated tested-combinations; the documented update sequence.--Splitting by layer is not the per-pair fragmentation CHOO-1865 forbids — it is-one model landing in reviewable pieces. Proposed split: **A + B** in one PR,-**C + D** in a second.