Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

fix(cable): never offer a dial image to a board that is not a dial

0xdiego251e794eb8ceef
diff --git a/cli/src/cable/cableHost.ts b/cli/src/cable/cableHost.ts
index 0af203014..ccaa791b9 100644
--- a/cli/src/cable/cableHost.ts
+++ b/cli/src/cable/cableHost.ts
@@ -12,11 +12,11 @@ import { join } from 'node:path'
import { AuthSessionManager, readAuthSession } from '../lib/authSession.js'
import { registry, projectDisplayName, type RegisteredSession } from '../lib/registry.js'
-import { fetchRelease, loadImage, shouldOffer } from './fwPush.js'
+import { fetchRelease, loadImage, otaKeyForBoard, shouldOffer } from './fwPush.js'
import { routeVoiceTask, type RouterAgent, type RouterContinuity } from '../lib/voiceRouter.js'
import { env } from '../config/env.js'
-import type { AppSwarms, CableAgent, CableHost, CableMachine, CableMachineSource, CableSwarm, DialStatus, OpenReason, RouteDecision } from './cableSession.js'
+import type { AppSwarms, CableAgent, CableHost, CableMachine, CableMachineSource, CableSwarm, CableTile, DialStatus, OpenReason, RouteDecision } from './cableSession.js'
import type { WindowRoute } from './windowRoute.js'
import { FleetError, type FleetMachine, type MachineFleet } from './machineFleet.js'
@@ -392,12 +392,13 @@ export class DaemonCableHost implements CableHost {
return this.unread
}
- listSwarms(): { selected: string; swarms: CableSwarm[] } {
+ listSwarms(): { selected: string; swarms: CableSwarm[]; tiles: CableTile[] } {
const app = this.swarms
- if (!app) return { selected: '', swarms: [] }
+ if (!app) return { selected: '', swarms: [], tiles: [] }
return {
selected: app.active,
swarms: app.swarms.map((s) => ({ id: s.id, name: s.name, agents: s.agentIds.length, panes: s.panes })),
+ tiles: app.tiles,
}
}
@@ -831,13 +832,24 @@ export class DaemonCableHost implements CableHost {
/**
* The image to offer, or null for "nothing to do".
*
- * Null covers three different situations on purpose, because the dial reacts to all of them the same
- * way — by carrying on: the dial is current, it is running a dev build that must not be touched, or the
- * manifest is unreachable. An update is an opportunity here, never a condition of working.
+ * Null covers four different situations on purpose, because the device reacts to all of them the same
+ * way — by carrying on: it is current, it is running a dev build that must not be touched, the manifest
+ * is unreachable, or WE DO NOT KNOW WHICH BOARD THIS IS. An update is an opportunity here, never a
+ * condition of working.
+ *
+ * That fourth case is the one with teeth. The manifest has always been per-board, but this call used to
+ * take the default key and so always resolved the round dial's entry — harmless while a dial was the
+ * only thing that could plug in, and a brick the moment a Pro could: its ESP32-P4 cannot run an
+ * ESP32-S3 image, and the cable that would let us put it right is the firmware that just stopped.
*/
- async firmwareFor(runningVersion: string): Promise<{ version: string; image: Buffer; sha256: string } | null> {
+ async firmwareFor(runningVersion: string, hw?: string): Promise<{ version: string; image: Buffer; sha256: string } | null> {
if (env.CABLE_FW_DISABLE) return null
- const release = await fetchRelease(env.CABLE_FW_MANIFEST_URL)
+ const key = otaKeyForBoard(hw)
+ if (!key) {
+ this.log(`cable: not offering firmware — unknown board "${hw}"`)
+ return null
+ }
+ const release = await fetchRelease(env.CABLE_FW_MANIFEST_URL, key)
if (!release || !shouldOffer(runningVersion, release.version)) return null
const image = await loadImage(release, join(env.ADAPTER_DATA_DIR, 'firmware'))
if (!image) return null
diff --git a/cli/src/cable/fwPush.spec.ts b/cli/src/cable/fwPush.spec.ts
index 571cd229f..a50d8ad47 100644
--- a/cli/src/cable/fwPush.spec.ts
+++ b/cli/src/cable/fwPush.spec.ts
@@ -7,7 +7,7 @@
// window does not slow this side down — the dial's ring overflows and the bytes are gone with no error.
import { describe, expect, it, vi } from 'vitest'
-import { FW_SLICE_BYTES, FW_WINDOW_BYTES, FirmwareTransfer, shouldOffer } from './fwPush.js'
+import { CIRCLE_OTA_KEY, FW_SLICE_BYTES, FW_WINDOW_BYTES, FirmwareTransfer, PRO_OTA_KEY, otaKeyForBoard, shouldOffer } from './fwPush.js'
describe('shouldOffer', () => {
it('offers a strictly newer release', () => {
@@ -133,3 +133,34 @@ describe('FirmwareTransfer', () => {
expect(log).toHaveBeenCalledTimes(1)
})
})
+
+// ONE IMAGE PER BOARD, AND NEVER A GUESS.
+//
+// Until Harness Pro existed there was one kind of device on the cable, so the offer took the manifest's
+// default entry. Two boards later that default is a brick: the Pro is an ESP32-P4 and the dial an
+// ESP32-S3, neither can run the other's image, and the cable that would let anyone put it right is the
+// firmware that just stopped booting. So the board decides the entry, and an unrecognised one is offered
+// nothing at all.
+describe('which firmware a board may be offered', () => {
+ it('sends each board to its own manifest entry', () => {
+ expect(otaKeyForBoard('cst9217+axp2101')).toBe(CIRCLE_OTA_KEY)
+ expect(otaKeyForBoard('cst816s')).toBe(CIRCLE_OTA_KEY)
+ expect(otaKeyForBoard('harness-pro')).toBe(PRO_OTA_KEY)
+ expect(CIRCLE_OTA_KEY).not.toBe(PRO_OTA_KEY)
+ })
+
+ it('offers nothing to a board it does not recognise', () => {
+ // A future board, or a device whose hello says something we have never seen. Refusing is the whole
+ // point: the alternative is picking one of the two images we do have, and both are wrong.
+ expect(otaKeyForBoard('harness-ultra')).toBeNull()
+ expect(otaKeyForBoard('')).not.toBeNull() // empty is "did not say", handled below — not unknown
+ })
+
+ it('treats a device that does not say as the dial', () => {
+ // The one place a guess is right. `hw` has been in the hello since before the Pro was designed, so a
+ // build that omits it predates the Pro and can only be a dial. Refusing those would stop updates
+ // reaching exactly the devices most in need of one.
+ expect(otaKeyForBoard(undefined)).toBe(CIRCLE_OTA_KEY)
+ expect(otaKeyForBoard(null)).toBe(CIRCLE_OTA_KEY)
+ })
+})
diff --git a/cli/src/cable/fwPush.ts b/cli/src/cable/fwPush.ts
index ff63d5888..33a46c9c4 100644
--- a/cli/src/cable/fwPush.ts
+++ b/cli/src/cable/fwPush.ts
@@ -21,9 +21,40 @@ export interface FirmwareRelease {
size: number
}
-/** The dial's key in the shared manifest. Other boards and the CLI itself live in the same file. */
+/** The round dial's key in the shared manifest. Other boards and the CLI itself live in the same file. */
export const CIRCLE_OTA_KEY = 'commander'
+/** Harness Pro's. A different SoC entirely — an image from either key bricks the other board. */
+export const PRO_OTA_KEY = 'harness-pro'
+
+/**
+ * Which manifest entry belongs to the board that just greeted us, or null for "do not offer anything".
+ *
+ * THIS IS A SAFETY GATE, NOT A LOOKUP. Until the Pro existed there was one board, so the caller could
+ * omit the key and take the default; now there are two, built for different silicon, and an ESP32-S3
+ * image written to an ESP32-P4 is a device that will not boot — and cannot be recovered over the cable,
+ * because the cable is the firmware that just stopped running. So an unrecognised board gets nothing.
+ *
+ * The `hw` string is what the device puts in its hello (`board()->name`, cable_client.c).
+ *
+ * ABSENT IS THE DIAL, deliberately, and it is the one case where guessing is right: the field has been
+ * in the protocol since before the Pro was designed, so a device that does not send it is a build old
+ * enough to predate it — which can only be a dial. Refusing those would stop updates reaching exactly
+ * the devices most in need of one.
+ */
+export function otaKeyForBoard(hw: string | undefined | null): string | null {
+ if (!hw) return CIRCLE_OTA_KEY
+ switch (hw) {
+ case 'cst9217+axp2101':
+ case 'cst816s':
+ return CIRCLE_OTA_KEY
+ case 'harness-pro':
+ return PRO_OTA_KEY
+ default:
+ return null
+ }
+}
+
/**
* Whether `published` should be offered to a dial running `running`.
*