Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(ssh): push agent-state edges to the host immediately

review7f2e32136799
diff --git a/src/main/remote-ssh/remote-status-push.test.ts b/src/main/remote-ssh/remote-status-push.test.ts
index 0df208642..fc0a49547 100644
--- a/src/main/remote-ssh/remote-status-push.test.ts
+++ b/src/main/remote-ssh/remote-status-push.test.ts
@@ -1,6 +1,7 @@
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
import type { MirrorFile, MirrorSettings } from '../../core/agent-status-mirror'
-import { initRemoteStatusPush } from './remote-status-push'
+import { initRemoteStatusPush, STATUS_EDGE_MIN_GAP_MS } from './remote-status-push'
+import type { AgentState } from '../../shared/agents/normalize'
function doc(updatedAt: number, ids: string[]): MirrorFile {
const nodes: MirrorFile['nodes'] = {}
@@ -8,6 +9,12 @@ function doc(updatedAt: number, ids: string[]): MirrorFile {
return { v: 1, updatedAt, nodes }
}
+function stateDoc(updatedAt: number, states: Record<string, AgentState | undefined>): MirrorFile {
+ const nodes: MirrorFile['nodes'] = {}
+ for (const [id, state] of Object.entries(states)) nodes[id] = { state, updatedAt }
+ return { v: 1, updatedAt, nodes }
+}
+
describe('initRemoteStatusPush', () => {
let flushCb: ((d: MirrorFile) => void) | null
let pushes: Array<{ id: string; json: string }>
@@ -128,6 +135,101 @@ describe('initRemoteStatusPush', () => {
expect('settings' in JSON.parse(pushes[0].json)).toBe(false)
})
+ it('a state EDGE inside the throttle window pushes immediately (working → done)', () => {
+ disposer = initRemoteStatusPush(deps({ throttleMs: 2000 }))
+ flushCb!(stateDoc(1, { a1: 'working' }))
+ expect(pushes).toHaveLength(1)
+ vi.advanceTimersByTime(STATUS_EDGE_MIN_GAP_MS + 100)
+ flushCb!(stateDoc(2, { a1: 'done' }))
+ expect(pushes).toHaveLength(2)
+ expect(JSON.parse(pushes[1].json).nodes.a1.state).toBe('done')
+ })
+
+ it('an edge resets the window: churn after it is throttled from the edge, not the leading push', () => {
+ disposer = initRemoteStatusPush(deps({ throttleMs: 2000 }))
+ flushCb!(stateDoc(1, { a1: 'working' }))
+ vi.advanceTimersByTime(1500)
+ flushCb!(stateDoc(2, { a1: 'blocked' })) // edge at t=1500 → new window until 3500
+ expect(pushes).toHaveLength(2)
+ flushCb!(stateDoc(3, { a1: 'blocked' })) // same-state churn → dirty
+ vi.advanceTimersByTime(600) // t=2100: old window would have fired here
+ expect(pushes).toHaveLength(2)
+ vi.advanceTimersByTime(1400) // t=3500
+ expect(pushes).toHaveLength(3)
+ expect(JSON.parse(pushes[2].json).updatedAt).toBe(3)
+ })
+
+ it('same-state churn stays throttled exactly as before', () => {
+ disposer = initRemoteStatusPush(deps({ throttleMs: 2000 }))
+ flushCb!(stateDoc(1, { a1: 'working' }))
+ for (let i = 2; i < 7; i++) {
+ vi.advanceTimersByTime(300)
+ flushCb!(stateDoc(i, { a1: 'working' }))
+ }
+ expect(pushes).toHaveLength(1)
+ vi.advanceTimersByTime(500)
+ expect(pushes).toHaveLength(2)
+ expect(JSON.parse(pushes[1].json).updatedAt).toBe(6)
+ })
+
+ it('an edge in ANOTHER project does not un-throttle this one', () => {
+ let states: Record<string, AgentState> = { a1: 'working', b1: 'working' }
+ disposer = initRemoteStatusPush(
+ deps({
+ throttleMs: 2000,
+ sshProjectIds: () => ['p1', 'p2'],
+ nodeIdsFor: (id) => new Set(id === 'p1' ? ['a1'] : ['b1'])
+ })
+ )
+ flushCb!(stateDoc(1, states))
+ expect(pushes).toHaveLength(2)
+ vi.advanceTimersByTime(1000)
+ states = { a1: 'working', b1: 'done' }
+ flushCb!(stateDoc(2, states))
+ expect(pushes).toHaveLength(3)
+ expect(pushes[2].id).toBe('p2')
+ })
+
+ it('caps flapping edges: at most one immediate edge push per min gap, trailing ships the final state', () => {
+ disposer = initRemoteStatusPush(deps({ throttleMs: 2000 }))
+ flushCb!(stateDoc(1, { a1: 'working' }))
+ // Flap every 50 ms for 2 s → 40 edges.
+ const seq: AgentState[] = []
+ for (let i = 0; i < 40; i++) {
+ vi.advanceTimersByTime(50)
+ const s: AgentState = i % 2 === 0 ? 'blocked' : 'working'
+ seq.push(s)
+ flushCb!(stateDoc(i + 2, { a1: s }))
+ }
+ // 2000 ms of flapping may produce at most one edge push per gap (+ the leading push).
+ expect(pushes.length).toBeLessThanOrEqual(1 + Math.ceil(2000 / STATUS_EDGE_MIN_GAP_MS))
+ vi.advanceTimersByTime(2000)
+ const last = JSON.parse(pushes[pushes.length - 1].json)
+ expect(last.nodes.a1.state).toBe(seq[seq.length - 1])
+ expect(last.updatedAt).toBe(41)
+ })
+
+ it('an edge that lands inside the cap still ships via the trailing push', () => {
+ disposer = initRemoteStatusPush(deps({ throttleMs: 2000 }))
+ flushCb!(stateDoc(1, { a1: 'working' }))
+ vi.advanceTimersByTime(10)
+ flushCb!(stateDoc(2, { a1: 'done' })) // inside the cap → deferred
+ expect(pushes).toHaveLength(1)
+ vi.advanceTimersByTime(1990)
+ expect(pushes).toHaveLength(2)
+ expect(JSON.parse(pushes[1].json).nodes.a1.state).toBe('done')
+ })
+
+ it('a node appearing with a state counts as an edge', () => {
+ disposer = initRemoteStatusPush(
+ deps({ throttleMs: 2000, nodeIdsFor: () => new Set(['a1', 'a2']) })
+ )
+ flushCb!(stateDoc(1, { a1: 'working' }))
+ vi.advanceTimersByTime(STATUS_EDGE_MIN_GAP_MS)
+ flushCb!(stateDoc(2, { a1: 'working', a2: 'working' }))
+ expect(pushes).toHaveLength(2)
+ })
+
it('dispose unsubscribes and stops timers', () => {
const d = deps({ heartbeatMs: 60_000, throttleMs: 2000 })
disposer = initRemoteStatusPush(d)
diff --git a/src/main/remote-ssh/remote-status-push.ts b/src/main/remote-ssh/remote-status-push.ts
index dd1ffd25c..2db4ad4ff 100644
--- a/src/main/remote-ssh/remote-status-push.ts
+++ b/src/main/remote-ssh/remote-status-push.ts
@@ -14,6 +14,16 @@ import { filterMirrorForNodes } from '../../core/agent-status-mirror'
/** Floor between two pushes to one project — a busy turn flushes the mirror every ~300 ms. */
export const STATUS_PUSH_THROTTLE_MS = 2_000
+/**
+ * Minimum gap between two IMMEDIATE state-edge pushes to one project. A flush that changes a
+ * node's pushed `state` (what the phone's "Claude is working" row reads) bypasses the throttle so
+ * a short turn's `done` does not wait up to STATUS_PUSH_THROTTLE_MS behind its `working`. An edge
+ * arriving sooner than this after the previous push is deferred to the ordinary trailing push, so
+ * a working/blocked flap costs at most ~2 writes/s per project (one ssh exec each) instead of one
+ * per hook event. 500 ms: above the ~300 ms tool-event cadence (a flap alternating on every event
+ * is halved), and still 4× faster than the throttle for the edge the phone actually waits on.
+ */
+export const STATUS_EDGE_MIN_GAP_MS = 500
/**
* The mirror only flushes on agent events, so a pushed file's `updatedAt` goes stale the moment
* the desktop disconnects or quits — indistinguishable from an idle-but-connected desktop. The
@@ -45,10 +55,17 @@ export function initRemoteStatusPush(deps: Deps): { dispose: () => void } {
let latest: MirrorFile | null = null
const timers = new Map<string, NodeJS.Timeout>()
const dirty = new Set<string>()
+ /** Per project: state signature of the last slice actually pushed, and when it was pushed. */
+ const lastStates = new Map<string, string>()
+ const lastPushAt = new Map<string, number>()
+
+ const sliceFor = (id: string): MirrorFile => filterMirrorForNodes(latest!, deps.nodeIdsFor(id))
- const pushProject = (id: string): void => {
+ const pushProject = (id: string, precomputed?: MirrorFile): void => {
if (!latest) return
- const slice = filterMirrorForNodes(latest, deps.nodeIdsFor(id))
+ const slice = precomputed ?? sliceFor(id)
+ lastStates.set(id, stateSignature(slice))
+ lastPushAt.set(id, Date.now())
let s: MirrorSettings | undefined
try {
s = deps.settingsFor?.(id)
@@ -69,8 +86,21 @@ export function initRemoteStatusPush(deps: Deps): { dispose: () => void } {
const off = deps.onFlush((doc) => {
latest = doc
for (const id of deps.sshProjectIds()) {
- if (timers.has(id)) dirty.add(id)
- else pushProject(id)
+ const t = timers.get(id)
+ if (!t) {
+ pushProject(id)
+ continue
+ }
+ // Inside the window: a STATE edge ships now (and restarts the window), unless the previous
+ // push was under STATUS_EDGE_MIN_GAP_MS ago — then the trailing push carries it.
+ const slice = sliceFor(id)
+ const edge = stateSignature(slice) !== lastStates.get(id)
+ if (edge && Date.now() - (lastPushAt.get(id) ?? 0) >= STATUS_EDGE_MIN_GAP_MS) {
+ clearTimeout(t)
+ timers.delete(id)
+ dirty.delete(id)
+ pushProject(id, slice)
+ } else dirty.add(id)
}
})
@@ -85,6 +115,17 @@ export function initRemoteStatusPush(deps: Deps): { dispose: () => void } {
for (const t of timers.values()) clearTimeout(t)
timers.clear()
dirty.clear()
+ lastStates.clear()
+ lastPushAt.clear()
}
}
}
+
+/** Node id → pushed `state` of a slice, order-independent. Only `state` counts as an edge. */
+function stateSignature(slice: MirrorFile): string {
+ return JSON.stringify(
+ Object.keys(slice.nodes)
+ .sort()
+ .map((id) => [id, slice.nodes[id].state ?? null])
+ )
+}