Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

fix: stop unknown reading as fine in three more places (CHOO-1865)

Louis Amaudruz0a8dc0268035
diff --git a/.env.example b/.env.example
index 482cbbe10..29d462b7e 100644
--- a/.env.example
+++ b/.env.example
@@ -12,8 +12,11 @@
# ── Standalone images (GHCR) ─────────────────────────────────────────────────
# Coordinates for the published switch-core / gateway / setup images that the
-# standalone stack pulls. Defaults resolve to the latest GHCR release; pin
-# SWITCH_VERSION to a released tag (e.g. 0.3.0) for a reproducible stack.
+# standalone stack pulls. Set SWITCH_VERSION to a released tag (e.g. 0.3.0) for
+# a reproducible stack. It is REQUIRED and has no default in the compose file:
+# it used to fall back to `latest`, so a missing or misspelt value silently
+# floated the whole stack to whatever had most recently been published, with
+# nothing to say so. Compose now refuses to start instead.
# Repo users building from source (`just standalone-up`) can ignore these.
SWITCH_REGISTRY=ghcr.io
SWITCH_IMAGE_NAMESPACE=sandbox-quantum
diff --git a/.github/workflows/pr-ci.yml b/.github/workflows/pr-ci.yml
index b300f6e18..13733a50b 100644
--- a/.github/workflows/pr-ci.yml
+++ b/.github/workflows/pr-ci.yml
@@ -67,6 +67,10 @@ jobs:
dash:
- *shared
- 'dash/**'
+ # switchdash bundles a generated copy of this file, and the job
+ # below verifies the copy is current — so a change here has to
+ # run the dash job even though it lives outside dash/.
+ - 'deploy/local/standalone-docker-compose.yml'
gateway:
- *shared
- 'gateway/**'
@@ -146,6 +150,13 @@ jobs:
- name: Install Playwright Chromium
run: pnpm exec playwright install --with-deps chromium
+ # The bundled compose is a generated copy of deploy/local's, and until now
+ # nothing verified the sync had run — the two could drift with only a
+ # comment asking nicely, which is how it silently stopped running once
+ # already (CHOO-1865).
+ - name: Bundled standalone compose is current
+ run: pnpm --filter switchdash-desktop run sync:compose:check
+
- name: Build workspace packages
run: pnpm -r --filter './packages/**' run build
diff --git a/dash/apps/switchdash-desktop/package.json b/dash/apps/switchdash-desktop/package.json
index cdffb553d..ce4bc706c 100644
--- a/dash/apps/switchdash-desktop/package.json
+++ b/dash/apps/switchdash-desktop/package.json
@@ -32,6 +32,7 @@
"build:main": "electron-vite build --filter main",
"build:sidecar": "node scripts/build-sidecar.mjs",
"sync:compose": "node scripts/sync-standalone-compose.mjs",
+ "sync:compose:check": "node scripts/sync-standalone-compose.mjs --check",
"build:renderer": "electron-vite build --filter renderer",
"package": "pnpm run build && electron-builder --config electron-builder.config.ts",
"package:mac": "pnpm run build && electron-builder --mac --config electron-builder.config.ts",
diff --git a/dash/apps/switchdash-desktop/scripts/sync-standalone-compose.mjs b/dash/apps/switchdash-desktop/scripts/sync-standalone-compose.mjs
index c6895dfe4..2b6b0ce06 100644
--- a/dash/apps/switchdash-desktop/scripts/sync-standalone-compose.mjs
+++ b/dash/apps/switchdash-desktop/scripts/sync-standalone-compose.mjs
@@ -2,7 +2,8 @@
/**
* Sync the bundled standalone compose from the repo's source of truth.
*
- * node scripts/sync-standalone-compose.mjs
+ * node scripts/sync-standalone-compose.mjs # write the bundled copy
+ * node scripts/sync-standalone-compose.mjs --check # fail if it is stale
*
* Copies deploy/local/standalone-docker-compose.yml (the file the switch-release
* workflow publishes to GHCR as `standalone-compose:<version>`) into
@@ -11,6 +12,11 @@
* stays in lockstep with the pinned switch-core release. It reads the repo file
* directly rather than pulling the OCI artifact so it works offline and before a
* release exists; the two are identical by construction.
+ *
+ * `--check` exists because nothing verified this had run (CHOO-1865). The two
+ * copies could drift with only a comment asking nicely — which is exactly how
+ * the rename below went unnoticed. It catches both directions: a source change
+ * that was never synced, and a hand-edit to the bundled copy.
*/
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
@@ -47,6 +53,21 @@ const header = `# BUNDLED COPY — do not hand-edit. This is the standalone comp
#
`;
-const body = readFileSync(source, 'utf8');
-writeFileSync(dest, header + body, 'utf8');
+const expected = header + readFileSync(source, 'utf8');
+
+if (process.argv.includes('--check')) {
+ const actual = existsSync(dest) ? readFileSync(dest, 'utf8') : null;
+ if (actual !== expected) {
+ console.error(
+ `sync-standalone-compose: ${dest}\n` +
+ 'is out of date. Either the source compose changed without re-syncing, or\n' +
+ 'the bundled copy was hand-edited. Run `pnpm run sync:compose` and commit.'
+ );
+ process.exit(1);
+ }
+ console.log('Bundled standalone compose is up to date.');
+ process.exit(0);
+}
+
+writeFileSync(dest, expected, 'utf8');
console.log(`Synced ${source}\n -> ${dest}`);
diff --git a/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/deployed-version.test.ts b/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/deployed-version.test.ts
index 70e6a788c..5488e2ee8 100644
--- a/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/deployed-version.test.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/deployed-version.test.ts
@@ -179,16 +179,26 @@ describe('readVersionStatus', () => {
});
});
- it('stays quiet but warns when the host cannot be read', async () => {
+ it('reports an unreadable host as unreadable, not as no drift', async () => {
+ // It used to return drift: null — the same answer a healthy, in-step stack
+ // gives — so a failed probe rendered as fine and the user was told nothing
+ // (CHOO-1865). Unknown must never look like fine.
const host = fakeHost({ imagesError: new Error('ssh: connection closed'), env: null });
expect(await readVersionStatus(host, '0.11.0')).toEqual({
deployedVersion: null,
- drift: null,
+ drift: {
+ deployed: null,
+ expected: '0.11.0',
+ direction: 'unreadable',
+ reason: expect.stringContaining('ssh: connection closed'),
+ },
});
expect(warn).toHaveBeenCalledOnce();
});
it('reports nothing for a host with no stack', async () => {
+ // `absent` is genuinely not a drift: nothing has been deployed here, which
+ // is a first start rather than a failed check.
const host = fakeHost({ images: new Map(), env: null });
expect(await readVersionStatus(host, '0.11.0')).toEqual({
deployedVersion: null,
diff --git a/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/deployed-version.ts b/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/deployed-version.ts
index 473f74103..132988811 100644
--- a/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/deployed-version.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/deployed-version.ts
@@ -92,10 +92,17 @@ export function classifyVersionDrift(
* `host`. Shared by the local and remote supervisors so both surface the same
* thing at boot.
*
- * A host we cannot read reports no drift: the caller is a status reconcile, and
- * inventing a drift banner out of a failed probe would be worse than staying
- * quiet. The start path guards separately (see `startStack`), so an unreadable
- * host here cannot let a downgrade through.
+ * A host we cannot read reports an `unreadable` drift rather than none
+ * (CHOO-1865). It previously returned null, which is what a stack in step
+ * returns — so a failed probe rendered exactly like a healthy server, and the
+ * user was told nothing at all. Saying "we could not check" is honest; saying
+ * nothing is not.
+ *
+ * `absent` still reports no drift, and that is not the same omission: nothing
+ * has been deployed here, which is a first start rather than a failure.
+ *
+ * The start path guards separately (see `startStack`), so an unreadable host
+ * here cannot let a downgrade through.
*/
export async function readVersionStatus(
host: ServerHost,
@@ -107,7 +114,15 @@ export async function readVersionStatus(
`managed-switch-server: could not read the deployed switch-core version on ${host.label}`,
{ reason: deployed.reason }
);
- return { deployedVersion: null, drift: null };
+ return {
+ deployedVersion: null,
+ drift: {
+ deployed: null,
+ expected,
+ direction: 'unreadable',
+ reason: deployed.reason,
+ },
+ };
}
if (deployed.kind === 'absent') return { deployedVersion: null, drift: null };
return {
diff --git a/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/pipeline.test.ts b/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/pipeline.test.ts
index 9774b172c..df43f6fd5 100644
--- a/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/pipeline.test.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/pipeline.test.ts
@@ -155,6 +155,36 @@ describe('startStack version guard', () => {
expect(await startStack(opts)).toEqual({ kind: 'started', serverId: 'srv-1' });
});
+ it('says so loudly when it cannot prove the start is not a downgrade', async () => {
+ // An uncomparable pair used to fall into the same "not a downgrade" branch
+ // as a clean match and pass in complete silence (CHOO-1865). It carries the
+ // same risk as a downgrade; we simply cannot prove it, and the log has to
+ // make that difference visible to whoever reads it afterwards.
+ readDeployedVersionMock.mockResolvedValue({
+ kind: 'deployed',
+ version: 'nightly',
+ source: 'container',
+ });
+ const { opts } = options();
+ await startStack(opts);
+
+ expect(logError).toHaveBeenCalledOnce();
+ expect(logError.mock.calls[0]?.[0]).toContain('not comparable');
+ });
+
+ it('stays silent when the versions match, so the log means something', async () => {
+ readDeployedVersionMock.mockResolvedValue({
+ kind: 'deployed',
+ version: '0.11.0',
+ source: 'container',
+ });
+ const { opts } = options();
+ await startStack(opts);
+
+ expect(logError).not.toHaveBeenCalled();
+ expect(logWarn).not.toHaveBeenCalled();
+ });
+
it('refuses before authenticating to the registry, so nothing off-host happens either', async () => {
readDeployedVersionMock.mockResolvedValue({
kind: 'deployed',
diff --git a/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/pipeline.ts b/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/pipeline.ts
index df352b9ff..13c61efeb 100644
--- a/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/pipeline.ts
+++ b/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/pipeline.ts
@@ -52,10 +52,18 @@ export type StartStackOptions = {
* was last started with, so a refused start leaves the host exactly as it was
* and re-installing the newer switchdash is enough to recover.
*
- * A host whose deployed version cannot be read is allowed through with a
- * warning rather than blocked — a transient daemon or SSH failure must not make
- * the app unstartable — so this is a guard against the known-bad case, not a
- * proof of safety.
+ * This blocks the PROVABLE downgrade only. Two cases pass through, and both are
+ * now said out loud rather than passing in silence (CHOO-1865):
+ *
+ * - The deployed version cannot be read. A transient daemon or SSH failure must
+ * not make the app unstartable.
+ * - The two versions are not comparable — a dev tag, a fork's tag, anything that
+ * is not semver. `classifyVersionDrift` reports `unknown`, which used to fall
+ * into the same "not a downgrade" branch as a clean match and vanish. It
+ * carries the same risk as a downgrade; we simply cannot prove it.
+ *
+ * So this is a guard against the known-bad case, not a proof of safety, and the
+ * log has to make that difference visible to whoever reads it afterwards.
*/
async function refuseDowngrade(
host: ServerHost
@@ -69,7 +77,15 @@ async function refuseDowngrade(
return null;
}
const drift = classifyVersionDrift(deployed.version, COMPATIBLE_SWITCH_VERSION);
- if (drift?.direction !== 'downgrade') return null;
+ if (drift?.direction === 'unknown') {
+ log.error(
+ `managed-switch-server: starting ${host.label} without proving it is not a downgrade — ` +
+ `deployed switch-core ${deployed.version} and pinned ${COMPATIBLE_SWITCH_VERSION} are not comparable. ` +
+ `If the deployed one is in fact newer, its database has already migrated and this start may strand it.`
+ );
+ return null;
+ }
+ if (drift?.direction !== 'downgrade' || drift.deployed === null) return null;
log.error(
`managed-switch-server: refusing to downgrade ${host.label} from switch-core ${drift.deployed} to ${drift.expected}`
);
diff --git a/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/resources/standalone-docker-compose.pinned.yml b/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/resources/standalone-docker-compose.pinned.yml
index 92171afbf..4068086f8 100644
--- a/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/resources/standalone-docker-compose.pinned.yml
+++ b/dash/apps/switchdash-desktop/src/main/core/managed-switch-server/resources/standalone-docker-compose.pinned.yml
@@ -26,7 +26,23 @@
# and pins versions without edits:
# SWITCH_REGISTRY (default ghcr.io)
# SWITCH_IMAGE_NAMESPACE (default sandbox-quantum)
-# SWITCH_VERSION (default latest)
+# SWITCH_VERSION (REQUIRED — no default, on purpose)
+#
+# SWITCH_VERSION has no fallback. It used to default to `latest`, so a missing
+# or misspelt env var silently floated the whole stack to whatever had most
+# recently been published — a different switch-core on every `up`, with nothing
+# to say so. Compose now refuses to start rather than pick a version nobody
+# asked for (CHOO-1865). `.env.example` sets it, and switchdash writes it.
+
+# What this compose artifact speaks on the `stack-compose` contract, which is
+# what switchdash's local-server mode pins against (CHOO-1865). The version this
+# file is published under says which release it is; this says what it speaks.
+# Compose ignores `x-` keys.
+x-switch-contract:
+ name: stack-compose
+ artifact: compose
+ speaks: 1
+ accepts: 1
services:
postgres:
@@ -129,7 +145,7 @@ services:
condition: service_completed_successfully
switch:
- image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/switch-core:${SWITCH_VERSION:-latest}
+ image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/switch-core:${SWITCH_VERSION:?required - set it in .env, there is no default}
ports:
- "${SWITCH_BIND_ADDR:-127.0.0.1}:${API_HOST_PORT:-8000}:8000"
environment:
@@ -156,7 +172,7 @@ services:
condition: service_started
gateway:
- image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/gateway:${SWITCH_VERSION:-latest}
+ image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/gateway:${SWITCH_VERSION:?required - set it in .env, there is no default}
profiles: ["gateway"]
ports:
- "${SWITCH_BIND_ADDR:-127.0.0.1}:${GATEWAY_HOST_PORT:-3000}:3000"
@@ -164,7 +180,7 @@ services:
- switch
setup:
- image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/setup:${SWITCH_VERSION:-latest}
+ image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/setup:${SWITCH_VERSION:?required - set it in .env, there is no default}
profiles: ["collab"]
restart: on-failure
environment:
diff --git a/dash/apps/switchdash-desktop/src/renderer/features/switch-servers/ServersSidebarSection.tsx b/dash/apps/switchdash-desktop/src/renderer/features/switch-servers/ServersSidebarSection.tsx
index 0ab0f0e91..f5435065c 100644
--- a/dash/apps/switchdash-desktop/src/renderer/features/switch-servers/ServersSidebarSection.tsx
+++ b/dash/apps/switchdash-desktop/src/renderer/features/switch-servers/ServersSidebarSection.tsx
@@ -157,7 +157,9 @@ function ServerDriftIndicator({ drift }: { drift: SwitchVersionDrift }) {
? `switch-core ${drift.expected} is available (running ${drift.deployed})`
: drift.direction === 'downgrade'
? `Runs switch-core ${drift.deployed} — newer than this app expects (${drift.expected})`
- : `Runs switch-core ${drift.deployed}; this app expects ${drift.expected}`;
+ : drift.direction === 'unreadable'
+ ? `Can't read which switch-core this runs; this app expects ${drift.expected}`
+ : `Runs switch-core ${drift.deployed}; this app expects ${drift.expected}`;
return (
<Tooltip>
diff --git a/dash/apps/switchdash-desktop/src/renderer/features/switch-servers/VersionDriftNotice.tsx b/dash/apps/switchdash-desktop/src/renderer/features/switch-servers/VersionDriftNotice.tsx
index 85b151f2f..4da32d548 100644
--- a/dash/apps/switchdash-desktop/src/renderer/features/switch-servers/VersionDriftNotice.tsx
+++ b/dash/apps/switchdash-desktop/src/renderer/features/switch-servers/VersionDriftNotice.tsx
@@ -31,6 +31,21 @@ export function VersionDriftNotice({
}) {
if (!drift) return null;
+ // We could not read what is deployed. No action offered: restarting on the
+ // strength of a failed probe could just as easily be a downgrade, and there
+ // is nothing here to prove otherwise (CHOO-1865).
+ if (drift.direction === 'unreadable') {
+ return (
+ <Alert variant="warning">
+ <TriangleAlert className="size-4" />
+ <AlertTitle>Can't tell which switch-core this is running</AlertTitle>
+ <AlertDescription>
+ {`This app expects ${drift.expected}, but the deployed version could not be read (${drift.reason}). Nothing is known about whether it matches.`}
+ </AlertDescription>
+ </Alert>
+ );
+ }
+
if (drift.direction === 'downgrade') {
return (
<Alert variant="destructive">
diff --git a/dash/apps/switchdash-desktop/src/shared/core/managed-switch-server/managed-switch-server.ts b/dash/apps/switchdash-desktop/src/shared/core/managed-switch-server/managed-switch-server.ts
index 65995e1a6..b7c76bce7 100644
--- a/dash/apps/switchdash-desktop/src/shared/core/managed-switch-server/managed-switch-server.ts
+++ b/dash/apps/switchdash-desktop/src/shared/core/managed-switch-server/managed-switch-server.ts
@@ -25,17 +25,36 @@ export type DockerAvailability =
* not be restarted against the older pin.
* - `unknown` — one of the two is not a comparable semver. Neither direction can
* be proven, so it is surfaced rather than assumed safe.
+ * - `unreadable` — the deployed version could not be read at all. Distinct from
+ * "matches" on purpose (CHOO-1865): a probe that failed and a stack that is
+ * in step used to be the same empty result, so a host we could not read
+ * rendered as healthy. Unknown must never look like fine.
*/
-export type SwitchVersionDriftDirection = 'upgrade' | 'downgrade' | 'unknown';
+export type SwitchVersionDriftDirection = 'upgrade' | 'downgrade' | 'unknown' | 'unreadable';
-/** A mismatch between the deployed switch-core version and this build's pin. */
-export type SwitchVersionDrift = {
- /** The version the stack is actually deployed at. */
- deployed: string;
- /** The version this build of switchdash pins. */
- expected: string;
- direction: SwitchVersionDriftDirection;
-};
+/**
+ * A mismatch between the deployed switch-core version and this build's pin.
+ *
+ * A union rather than one shape with nullable fields, so the invariant is the
+ * compiler's to keep: there is a deployed version in every case except the one
+ * where reading it is what failed.
+ */
+export type SwitchVersionDrift =
+ | {
+ /** The version the stack is actually deployed at. */
+ deployed: string;
+ /** The version this build of switchdash pins. */
+ expected: string;
+ direction: 'upgrade' | 'downgrade' | 'unknown';
+ }
+ | {
+ /** Null because the deployed version is exactly what could not be read. */
+ deployed: null;
+ expected: string;
+ direction: 'unreadable';
+ /** What failed, so the user is told more than "something did". */
+ reason: string;
+ };
/**
* Why a downgrade is refused, in one message — shared by the main process (as
diff --git a/deploy/local/standalone-docker-compose.yml b/deploy/local/standalone-docker-compose.yml
index 4914e9cda..040d23349 100644
--- a/deploy/local/standalone-docker-compose.yml
+++ b/deploy/local/standalone-docker-compose.yml
@@ -19,7 +19,23 @@
# and pins versions without edits:
# SWITCH_REGISTRY (default ghcr.io)
# SWITCH_IMAGE_NAMESPACE (default sandbox-quantum)
-# SWITCH_VERSION (default latest)
+# SWITCH_VERSION (REQUIRED — no default, on purpose)
+#
+# SWITCH_VERSION has no fallback. It used to default to `latest`, so a missing
+# or misspelt env var silently floated the whole stack to whatever had most
+# recently been published — a different switch-core on every `up`, with nothing
+# to say so. Compose now refuses to start rather than pick a version nobody
+# asked for (CHOO-1865). `.env.example` sets it, and switchdash writes it.
+
+# What this compose artifact speaks on the `stack-compose` contract, which is
+# what switchdash's local-server mode pins against (CHOO-1865). The version this
+# file is published under says which release it is; this says what it speaks.
+# Compose ignores `x-` keys.
+x-switch-contract:
+ name: stack-compose
+ artifact: compose
+ speaks: 1
+ accepts: 1
services:
postgres:
@@ -122,7 +138,7 @@ services:
condition: service_completed_successfully
switch:
- image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/switch-core:${SWITCH_VERSION:-latest}
+ image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/switch-core:${SWITCH_VERSION:?required - set it in .env, there is no default}
ports:
- "${SWITCH_BIND_ADDR:-127.0.0.1}:${API_HOST_PORT:-8000}:8000"
environment:
@@ -149,7 +165,7 @@ services:
condition: service_started
gateway:
- image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/gateway:${SWITCH_VERSION:-latest}
+ image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/gateway:${SWITCH_VERSION:?required - set it in .env, there is no default}
profiles: ["gateway"]
ports:
- "${SWITCH_BIND_ADDR:-127.0.0.1}:${GATEWAY_HOST_PORT:-3000}:3000"
@@ -157,7 +173,7 @@ services:
- switch
setup:
- image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/setup:${SWITCH_VERSION:-latest}
+ image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/setup:${SWITCH_VERSION:?required - set it in .env, there is no default}
profiles: ["collab"]
restart: on-failure
environment: