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): one memory of where both screens are looking, and no silent drops

0xdiego257348a91187ea
diff --git a/cli/src/cable/cableHost.ts b/cli/src/cable/cableHost.ts
index e3dc07d50..995fcedc5 100644
--- a/cli/src/cable/cableHost.ts
+++ b/cli/src/cable/cableHost.ts
@@ -45,6 +45,8 @@ export interface CableHostWiring {
listModels?: (agentId: string) => Promise<Array<{ id: string }>>
/** The dial moved to another agent — the desktop window should show that agent on its own machine. */
focused?: (machineId: string, agentId: string, edge?: DeskEdge) => void
+ /** A notification was tapped: the window gives that agent a tile of its own. */
+ opened?: (machineId: string, agentId: string) => void
/** A finger on the dial's glass, in pieces, while it is down. */
scrolled?: (phase: 'down' | 'move' | 'up', dy: number, velocity: number) => void
log: (line: string) => void
@@ -395,6 +397,18 @@ export class DaemonCableHost implements CableHost {
return this.agentMachine.get(agentId) ?? ''
}
+ openAgent(agentId: string): void {
+ const machineId = this.machineOf(agentId)
+ if (!machineId) {
+ // Same rule as focus: an agent id without its machine is not routable, and guessing is how a
+ // remote move used to land on a local agent.
+ this.wiring.log(`cable: ignored open for unknown agent ${agentId}`)
+ return
+ }
+ this.wiring.log(`cable: open ${machineId}/${agentId} (notification)`)
+ this.wiring.opened?.(machineId, agentId)
+ }
+
/** Whether this daemon's last list held that agent — see CableHost.knows. */
knows(agentId: string): boolean {
return this.agentMachine.has(agentId)
diff --git a/cli/src/cable/cableSession.spec.ts b/cli/src/cable/cableSession.spec.ts
index 4917d2a3d..37948b74b 100644
--- a/cli/src/cable/cableSession.spec.ts
+++ b/cli/src/cable/cableSession.spec.ts
@@ -89,6 +89,7 @@ function makeHost(over: Partial<CableHost> = {}) {
scrolled: vi.fn(),
answer: vi.fn(),
focus: vi.fn(),
+ openAgent: vi.fn(),
updateAgent: vi.fn(),
listModels: async () => ['runtime-v1:s1:claude:opus@high', 'runtime-v1:s1:claude:sonnet@low'],
recentSummaries: async () => [],
@@ -317,6 +318,120 @@ describe('cable session', () => {
await session.stop()
})
+ it('says again where the window is looking after the list is re-sorted', async () => {
+ // The gap left by making re-anchors silent: the dial rebuilds when a re-sorted list lands, and if it
+ // lands on the wrong tile nobody notices. Measured — a swipe pulled `a2` into a pane, the window
+ // showed `a2`, the dial sat on the first agent. The daemon is the only side that knows both, so it
+ // repeats itself after every push.
+ let agents: CableAgent[] = [{ id: 'a1', name: 'one' }, { id: 'a2', name: 'two' }]
+ const { session, port } = await connect(makeHost({ listAgents: async () => agents }))
+ port.say({ t: 'hello', product: 'harness', mac: 'aa:bb' })
+ await settle()
+
+ await session.followApp('', 'a2') // the window is on a2
+ await settle()
+ port.sent.length = 0
+
+ agents = [{ id: 'a2', name: 'two' }, { id: 'a1', name: 'one' }] // the desk re-sorted the ring
+ port.say({ t: 'focus', agentId: 'a1' }) // and the dial drifted onto another tile
+ await settle()
+ await session.pushAgents()
+ await settle()
+
+ expect(port.sent.filter((m) => m.t === 'focus').map((m) => m.agentId)).toEqual(['a2'])
+ await session.stop()
+ })
+
+ it('a re-push after the window FOLLOWED the dial does not send it back', async () => {
+ // Reported from the desk as a tile going 3 → 4 → 3 → 4 on its own.
+ //
+ // There were two memories of the same fact: where the dial was, and what the window last said. When
+ // the window follows the DIAL, followApp returns early — the dial is already there — so the window's
+ // memory kept an OLDER agent, and the next list push re-asserted that stale one. The dial jumped back
+ // to it, the window's next report pulled it forward, and the two took turns.
+ let agents: CableAgent[] = [{ id: 'a3', name: 'three' }, { id: 'a4', name: 'four' }]
+ const { session, port } = await connect(makeHost({ listAgents: async () => agents }))
+ port.say({ t: 'hello', product: 'harness', mac: 'aa:bb' })
+ await settle()
+
+ await session.followApp('', 'a3') // the window led: both screens on a3
+ await settle()
+
+ port.say({ t: 'focus', agentId: 'a4' }) // a hand turns the dial to a4
+ await settle()
+ await session.followApp('', 'a4') // the window follows — early return, nothing commanded
+ await settle()
+ port.sent.length = 0
+
+ agents = [{ id: 'a4', name: 'four' }, { id: 'a3', name: 'three' }] // the desk re-sorts the ring
+ await session.pushAgents()
+ await settle()
+
+ // The re-assert says a4 — where both screens actually are — and never a3.
+ expect(port.sent.filter((m) => m.t === 'focus').map((m) => m.agentId)).toEqual(['a4'])
+ await session.stop()
+ })
+
+ it('a swipe made DURING a slow machine switch still reaches the window', async () => {
+ // Measured on the real desk: selecting a remote machine took ten seconds, and for all ten every dial
+ // report was discarded as "the window is mid-switch". The dial walked on, the window stayed put, and
+ // the two screens named different agents with nothing left to correct them.
+ //
+ // The repaint this guards against answers the command at once. A hand, seconds later, does not.
+ let finishSelection!: () => void
+ const gate = new Promise<void>((resolve) => { finishSelection = resolve })
+ const focus = vi.fn()
+ const host = makeHost({
+ focus,
+ selectMachine: vi.fn(async () => { await gate; return { ok: true as const } }),
+ })
+ const { session, port } = await connect(host)
+ port.say({ t: 'hello', product: 'harness', mac: 'aa:bb' })
+ await settle()
+
+ const following = session.followApp('remote-machine', 'r1')
+ await settle()
+ port.say({ t: 'focus', agentId: 'a1' }) // the switch's own repaint: discarded
+ await settle()
+ expect(focus).not.toHaveBeenCalled()
+
+ vi.setSystemTime(Date.now() + 5_000) // the switch is still going
+ port.say({ t: 'focus', agentId: 'a2' }) // …and a hand turns the dial
+ await settle()
+ expect(focus).toHaveBeenCalledWith('a2')
+
+ finishSelection()
+ await following
+ vi.useRealTimers()
+ await session.stop()
+ })
+
+ it('a swipe a second after the window clicked is a SWIPE, not an echo', async () => {
+ // This window was 4s for one afternoon, to catch a re-anchor the dial should never have reported in
+ // the first place. It caught real swipes instead: click something in the window, turn the dial within
+ // four seconds, and the move vanished — the two screens then sat on different agents with nothing to
+ // correct them, which is exactly the report that followed.
+ //
+ // The echo is stopped at its source now: a dial told where to look moves through code, and a move made
+ // by code is not reported at all. So a report arriving a second later is a hand.
+ const focus = vi.fn()
+ const { session, port } = await connect(makeHost({ focus }))
+ port.say({ t: 'hello', product: 'harness', mac: 'aa:bb' })
+ await settle()
+
+ await session.followApp('', 'a2')
+ await settle()
+ focus.mockClear()
+
+ vi.setSystemTime(Date.now() + 1_000)
+ port.say({ t: 'focus', agentId: 'a1' })
+ await settle()
+
+ expect(focus).toHaveBeenCalledWith('a1')
+ vi.useRealTimers()
+ await session.stop()
+ })
+
it('ignores stale dial focus while the app switches to a remote machine', async () => {
let selected = 'mac-local'
let finishSelection!: () => void
diff --git a/cli/src/cable/cableSession.ts b/cli/src/cable/cableSession.ts
index fcbc30daf..7e71870db 100644
--- a/cli/src/cable/cableSession.ts
+++ b/cli/src/cable/cableSession.ts
@@ -73,8 +73,32 @@ const MACHINES_POLL_MS = 15_000
* that write. Real hardware delivered that stale report 23 ms after the machine switch completed; keep
* a short transaction open until the commanded tile echoes, without making the dial feel unresponsive.
*/
+/**
+ * How long a focus COMMANDED by the window keeps the dial's own reports out.
+ *
+ * Deliberately SHORT, and it was briefly 4s — which broke the thing it was meant to protect. The echo it
+ * guards against is gone at the source now: a dial told where to look moves through code, and a move made
+ * by code is not reported at all (carousel_goto in ui_screens.c). What a long window does instead is
+ * swallow a REAL swipe made in the seconds after any click in the window — the two screens then sit on
+ * different agents with nothing to correct them, which is exactly the report that followed.
+ *
+ * So it stays only as long as a stale echo from an OLDER firmware could take, and every report it drops
+ * now says so in the log.
+ */
const APP_FOCUS_SETTLE_MS = 750
+/**
+ * How long after an app-driven switch begins its own repaint can still arrive.
+ *
+ * The switch itself is NOT the measure, and using it as one is what broke: selecting a remote machine
+ * takes seconds — ten, measured — and while `drivingAppFocus` was true every report was discarded, so a
+ * swipe made during it vanished and the two screens ended up on different agents.
+ *
+ * A repaint answers the command almost at once; a hand does not. So the guard lasts as long as the first,
+ * not as long as the whole errand.
+ */
+const APP_SWITCH_REPAINT_MS = 1_000
+
/** What a `voice.begin` without an `sr` is assumed to be — firmware old enough not to say. */
const DEFAULT_VOICE_RATE = 16_000
@@ -165,6 +189,15 @@ export interface CableHost {
*/
answer(agentId: string, requestId: string, answers: Record<string, string>): void
focus(agentId: string): void
+ /**
+ * "Put this one in front of me" — a NOTIFICATION was tapped.
+ *
+ * A different verb from [focus], and the difference is the whole point: focus
+ * says where the eye is and the window moves a tile to match, while this asks
+ * for a tile of its own. A turn that just finished is a new thing to look at,
+ * not a replacement for whatever the person was already watching.
+ */
+ openAgent(agentId: string): void
/**
* Does this daemon's own agent list hold that id?
*
@@ -250,14 +283,27 @@ export class CableSession {
/** Which images have already been written to which dial, and when. Survives the port, unlike `offered`. */
private readonly written = new Set<string>()
private readonly writeLog = new Map<string, number[]>()
- /** The agent the dial is on, as last observed or commanded. See followApp() for why this exists. */
- private dialFocus = ''
+ /**
+ * THE agent both screens are meant to be on. One memory, written by whichever side moved last.
+ *
+ * There were two — where the dial was, and what the window last said — and they drifted apart in the
+ * one case that matters most: when the WINDOW follows the DIAL, `followApp` returns early (the dial is
+ * already there), so the window's memory was never updated and kept an older agent. Anything that then
+ * re-asserted "where the window is" sent that stale agent, the dial jumped back to it, and the window's
+ * next report pulled it forward again. Measured on the real dial as a tile going 3 → 4 → 3 → 4.
+ *
+ * A single field cannot disagree with itself. Both sides write it on a real move, the last write wins,
+ * and it is the only thing the daemon ever re-asserts.
+ */
+ private desiredFocus = ''
/**
* App-driven machine/focus changes are one transaction. Without this queue, two quick desktop clicks
* can interleave their machine lists and let the older click focus last.
*/
private appFocusTail: Promise<void> = Promise.resolve()
private appFocusGeneration = 0
+ /** When the app-driven switch began — see APP_SWITCH_REPAINT_MS. */
+ private drivingSince = 0
/** While the app is rebuilding the dial's machine/list state, focus reports describe that rebuild. */
private drivingAppFocus = false
/** The dial may echo a focus command after its write promise resolves; consume that one echo. */
@@ -623,10 +669,14 @@ export class CableSession {
&& now <= this.expectedAppFocusEchoUntil
if (expectationActive) {
// Until the commanded tile echoes, every other focus is from the carousel/list repaint that
- // command caused. Do not even update dialFocus: the daemon already commanded the newer truth.
+ // command caused. Do not even update the record: the daemon already commanded the newer truth.
if (agentId === this.expectedAppFocusEcho) {
this.expectedAppFocusEcho = ''
this.expectedAppFocusEchoUntil = 0
+ } else {
+ // SAID OUT LOUD. A dropped report is a dial and a window on different agents, and dropping
+ // it silently is how that state became impossible to explain from the log.
+ this.host.log(`cable: dropped dial focus ${agentId} — waiting for ${this.expectedAppFocusEcho}`)
}
return
}
@@ -634,15 +684,28 @@ export class CableSession {
this.expectedAppFocusEcho = ''
this.expectedAppFocusEchoUntil = 0
}
- // A machine switch re-paints the carousel and may report its old tile while the new list is in
- // flight. That is not a hand choosing an agent, so it must not drive the desktop back.
- if (this.drivingAppFocus) return
+ // A machine switch re-paints the carousel and may report its OLD tile while the new list is in
+ // flight. That one report is not a hand and must not drive the window back.
+ //
+ // ONLY that one. This used to drop everything for as long as the switch took, and a remote
+ // machine's switch takes seconds — measured at ten. Every swipe made in that window vanished,
+ // so the dial walked on and the window stayed where it was, with the two screens naming
+ // different agents and nothing left to correct them. A dial that reports a move it did not make
+ // is fixed at the source now (carousel_goto in the firmware), which leaves only the stale repeat
+ // of the tile the dial was already on to guard against.
+ if (this.drivingAppFocus && now - this.drivingSince < APP_SWITCH_REPAINT_MS) {
+ this.host.log(`cable: dropped dial focus ${agentId} — repaint from the switch in flight`)
+ return
+ }
// Remember where the dial IS, not just that it said so: followApp() compares against this to
// avoid echoing the dial's own move back at it.
- this.dialFocus = agentId
+ this.desiredFocus = agentId
this.host.focus(agentId)
}
return
+ case 'agent.open':
+ if (str('agentId')) this.host.openAgent(str('agentId')!)
+ return
case 'scroll': {
// Forwarded verbatim, including the reports carrying no travel: the two ends of a stroke are the
// whole point of the message. A `down` with nothing in it stops a fling still running, and an `up`
@@ -908,6 +971,18 @@ export class CableSession {
// a count is enough, and a firmware that predates the field walks all of
// them exactly as it did before.
await this.send({ t: 'agents.end', ring: agents.filter((a) => !a.offRing).length })
+
+ // The list just changed shape under the dial, so say again which agent both screens are on.
+ //
+ // This is the ONLY thing the daemon re-asserts, and it is the current record rather than a second
+ // memory of it — see desiredFocus. A re-anchor after a push is silent by design (the dial reports
+ // nothing it did not do itself), so without this a dial that landed on the wrong tile would sit there
+ // with nobody to notice.
+ if (this.desiredFocus) {
+ this.expectedAppFocusEcho = this.desiredFocus
+ this.expectedAppFocusEchoUntil = Date.now() + APP_FOCUS_SETTLE_MS
+ await this.focusAgent(this.desiredFocus)
+ }
}
/**
@@ -1062,19 +1137,20 @@ export class CableSession {
}
async focusAgent(agentId: string): Promise<void> {
- this.dialFocus = agentId
+ this.desiredFocus = agentId
await this.send({ t: 'focus', agentId })
}
/**
* The desktop window moved to an agent — bring the dial with it.
*
- * ⚠️ THE `dialFocus` GUARD IS WHAT KEEPS THIS FROM OSCILLATING. The two screens drive each other: the
+ * ⚠️ THE `desiredFocus` GUARD IS WHAT KEEPS THIS FROM OSCILLATING. The two screens drive each other: the
* dial's own carousel reports `focus` up, the daemon hands that to the app, the app opens that agent's
* terminal, and the app opening a terminal is exactly what calls this. Answering it with another `focus`
- * closes the ring. It happens to settle today — the dial does not re-report a carousel that never moved
- * — but that is a property of the far end's UI, not of this protocol, and it is one jittery settle away
- * from a loop. So: say nothing when the dial is already there.
+ * closes the ring. So: say nothing when the record already names that agent.
+ *
+ * The record is one field written by both sides (see desiredFocus). It used to be two, and the ring
+ * closed through the gap between them.
*
* The machine comes first when it differs. Sending `focus` for an agent on a machine the dial is not on
* would name an id its list has never heard of, and the tile it would have to move to does not exist
@@ -1088,6 +1164,7 @@ export class CableSession {
const task = this.appFocusTail.then(async () => {
// A newer desktop selection made this queued one obsolete before it started.
if (generation !== this.appFocusGeneration) return
+ this.drivingSince = Date.now()
this.drivingAppFocus = true
try {
if (machineId && machineId !== this.host.selectedMachine()) {
@@ -1096,13 +1173,15 @@ export class CableSession {
}
// A newer selection can arrive while the remote machine RPC/list push is in flight. Never let
// this older transaction focus after it finishes.
- if (generation !== this.appFocusGeneration || agentId === this.dialFocus) return
+ // Already where the window is: nothing to command. The record is right either way — this is the
+ // window FOLLOWING the dial, and the dial's own report wrote it.
+ if (generation !== this.appFocusGeneration || agentId === this.desiredFocus) return
// Said before the frame goes out, not after: the frame itself succeeds either way.
const unknown = this.host.knows?.(agentId) === false
this.host.log(`cable: following the app to agent ${agentId}${unknown ? ' — NOT in this daemon\'s list, the dial has no tile for it' : ''}`)
this.expectedAppFocusEcho = agentId
this.expectedAppFocusEchoUntil = Date.now() + APP_FOCUS_SETTLE_MS
- await this.focusAgent(agentId)
+ await this.focusAgent(agentId) // writes the record
} finally {
this.drivingAppFocus = false
}
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 988ccd950..f6d7cc0b3 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -3780,6 +3780,8 @@ async function runForeground(session: AuthSession): Promise<void> {
// which end of the desk it belongs to — so the window replaces the first
// tile or the last one rather than guessing, and the dial never has to
// report which way the thumb moved.
+ // A notification tap, which asks for a tile of its OWN — see CableHost.openAgent.
+ opened: (machineId, agentId) => backend.sendLocal({ type: 'dial_open', payload: { machineId, agentId } }),
focused: (machineId, agentId, edge) =>
backend.sendLocal({ type: 'dial_focus', payload: { machineId, agentId, ...(edge ? { edge } : {}) } }),
scrolled: (phase, dy, velocity) => backend.sendLocal({ type: 'dial_scroll', payload: { phase, dy, velocity } }),